[Meta] Unify naming between data and control stage.

[eradicator]

I realize this is a heap of work. So it's more of a wishful thought / querry for implementability.

What?
A number of properties of objects have different names between data and control stage. I.e. what is referenced as Recipe.result or Recipe.results (singular or plural) in data stage is always referenced as Recipe.products (always plural) in control stage. It's be nice if this could be unified to use a single identical term in both stages, i.e. always "products".

Why?
It would greatly help (new) modders to not have to worry about the same thing being named differently depending on when you look at it. It would also add that final touch of polishing to the already very good modding API ;).

Addendum
I'd greatly apprecite if one of the devs could state how realistic this is to ever happen at all. If judged as doable i'm sure the community (including me) can come up with a full list of parameter names.

[Bilka]

I.e. what is referenced as Recipe.result or Recipe.results (singular or plural) in data stage is always referenced as Recipe.products (always plural) in control stage. It's be nice if this could be unified to use a single identical term in both stages, i.e. always "products".

This example doesn't make much sense. Result has an entirely different format compared with results and products. Making it possible to use both formats with just one property is more confusing, not less.

I like the idea in general, but issues might also pop up if things are formatted differently between stages. This will confuse users that will assume that they can use the same formate between stages, because it has the same name, right? One example of that are properties using BoundingBox. In the control phase, you can get left_top and right_bottom specifically. Writing to those specifically is NOT possible in the data phase, the first position in the table is assumed to be left_top, regardsless of whether you wrote right_bottom = in front of it.

Outside of these two concerns, I wouldn't mind having some consistency between phases. Do you prefer using the name of the thing in the data stage instead of the name from the control phase, the other way around, or does it depend on the property?

[eradicator]

@Bilka:
I feel that the question of the actual data format belongs into a different thread so i'm putting my answer in a spoiler. My main concern here is with the names of the properties, not their content. And before that with the question if this sort of major change is feasible at all. Once those two are done further details can be discussed =).

Wall of Text

I use "simple" and "explicit" a lot here, so to clarify:

Code: Select all

local simple_box = {{-2, -3}, {5, 8}}
local explicit_box = {left_top = {-2, -3}, right_bottom = {5, 8}}

[quote="Bilka"]This example doesn't make much sense. Result has an entirely different format compared with results and products. Making it possible to use both formats with just one property is more confusing, not less.[/quote]
".result" has an additional formating option available. Doesn't .results also support "simple" format? Other than that results is just a table of result('s), so a singular result would simply need additional nesting: {result} instead of result. (Also i'm really bad at examples in general :P)

Also that sort of simple/explicit dual formatting exists for a number of things and i see it as more of a general concept that is just required to be learned. (Yes, it does make cross-mod changes in data stage pretty annoying if you don't know if you're looking for .x or [1] (i.e. coordinates), so i wouldn't be against unifying those away (==enforce explicit format), but that is imho a different topic. Thinking along that line i personally would also like if normal= was the default ingredient node for recipes. I see at least one or two people a week that ask why their recipe changes don't work that stem from the fact that there's three possible positions (direct, normal, expensive) for ingredients, and even i don't know what would happen if someone specified both direct and normal.

[quote="Bilka"]I like the idea in general, but issues might also pop up if things are formatted differently between stages.[/quote] The general behavior of the (control stage) API is that for writing operations you can use simple or explicit format, while reading always results in explicit format (positions, bounding boxes etc) so i don't think that any additional confusion would come from this.

[quote="Bilka"]This will confuse users that will assume that they can use the same formate between stages, because it has the same name, right? One example of that are properties using BoundingBox. In the control phase, you can get left_top and right_bottom specifically.[/quote]
Bounding_box is already named equally between both stages with it's current behavior. So i don't see how unifying other things would cause additional confusion. It's the same simple/explicit write/read situation as above.

[quote="Bilka"]Writing to those specifically is NOT possible in the data phase, the first position in the table is assumed to be left_top, regardsless of whether you wrote right_bottom = in front of it.[/quote] Not quite following you there. An explicitly defined bounding box (i.e. {left_top = {-2, -3}, right_bottom = {5, 8}}) does not have a "first position". Thinking about this while typing... the main problem here is that reading in data stage does not return the explicit definition. Though fixing this would be pretty ugly i presume. You'd have to check every write a mod makes to the data table and convert it to explicit if it was simple (though it would save lots of work on the modders end if it would be fixed).

[quote="Bilka"]Do you prefer using the name of the thing in the data stage instead of the name from the control phase, the other way around, or does it depend on the property?[/quote]Personally? I prefer the better fitting name, and if unclear the one that is easier to use or is cheaper to migrate to, though that choice should not be based on my opinion :P. I.e. A recipe is a way to produce and item from ingredients. Thus "product" fits better, but "result/s" is shorter and more widely used so it causes less migration cost (=code writing and re-learning). Either way i don't think it matters as long as their both the same.

Also here's a hopefully less controverse example of the names used for mod settings scopes.

Code: Select all

  --scope (data/control)
  startup = {'startup'         , 'startup'} ,
  map     = {'runtime-global'  , 'global' } ,
  player  = {'runtime-per-user', 'player' } ,

[Rseding91]

We aren't likely to change any of the names at this point in development as it would break too many mods compared to the benefit it gave.

[eradicator]

We aren't likely to change any of the names at this point in development as it would break too many mods compared to the benefit it gave.

My thought was that new major versions already break most mods anyway, so some small, hopefully search+replaceable changes wouldn't hurt too much.

Thanks for the answer though =).

[bobingabout]

We aren't likely to change any of the names at this point in development as it would break too many mods compared to the benefit it gave.

you change names of variables between major mod versions all the time, why would this be different from 0.16 to 0.17?

Another one is inserters...
pickup_position = {0, -1},
insert_position = {0, 1.2},
in data vs
pickup_position
drop_position
in control.

[Rseding91]

We aren't likely to change any of the names at this point in development as it would break too many mods compared to the benefit it gave.

you change names of variables between major mod versions all the time, why would this be different from 0.16 to 0.17?

No we don't.

[keyboardhack]

We aren't likely to change any of the names at this point in development as it would break too many mods compared to the benefit it gave.

you change names of variables between major mod versions all the time, why would this be different from 0.16 to 0.17?

No we don't.

Yes you do.

Changed "on_preplayer_mined_item" to "on_pre_player_mined_item".
Changed LuaEntity::recipe to LuaEntity::get_recipe() and LuaEntity::set_recipe().
Changed the root custom gui containers (top, left, center, goal) to have the corresponding name.
Changed LuaFluidBox fluid from {type="...", amount=...} to {name="...", amount=...}
Changed name of colspan parameter of table to column_count.
Changed LuaItemPrototype::group_filters and sub_gorup_filters to item_group_filters and item_subgroup_filters to match the prototype values.

Changed less_then to less_than in lua GUI progress bar style specification. (33196)
Changed LuaEntityPrototype::underground_belt_distance to LuaEntityPrototype::max_underground_distance and changed it to work on both underground pipes and underground belts.

Changed LuaEntity::get_filter/set_filter parameters around to match the inventory versions. They also now only work on inserter filters.
Changed LuaEntity::color to work for locomotives, cargo wagons, and characters - it will return nil if used on other entities.
Renamed some defines (groupstate->group_state, circuitconnector->circuit_connector, circuitconditionindex->circuit_condition_index, trainstate->train_state)
Renamed LuaForce::logistic_robot_storage_modifier -> logistic_robot_storage_bonus to better match what it does
game.local_player has been renamed to game.player and now works through remote calls.

[Rseding91]

No we don't.

Yes you do.

...

No, we don't. Near every one of those aside from the group filters one is a bug fix and not "we felt like changing it". From things simply spelled wrong "less_then" -> 'less_than", to features added by changing how the API works to allow multiple parameters "recipe" to "set_recipe", "get_recipe" they weren't changes for change sake.

Also compared to everything else done between major versions those things changed from bug fixes or adding features account for a minuscule percent of the changes because we don't want to break mods just for the sake of "this name might be better" meaning they're not done "all the time".

We did one huge rename change in the past (changed the entire API to use underscores between everything) and are still feeling the ramifications of doing so.

[bobingabout]

Still, it's Beta, you're allowed to change things.

It's far more forgiving to do this now, than to decide after the 1.0 that you want to change variables.

and, we're not saying "Change it to this, because it's better!" we're saying "You call it this here, but the same variable has a different name there, pick one and use the same name in both places"

I can understand why you might want a difference between Product and Result if they're showing similar information in entirely different structures, but what about my inserter example? insert_position in data, but drop_position in control? they do exactly the same thing, defined exactly the same way, there is no reason why the words should be different, especially when the counterpart pickup_position uses the same name in both.

And yes, this change will actively break at least two of my own mods, I don't mind having to fix this between 0.16 and 0.17 (though I'll probably be swearing out loud while doing it) in the name of consistency, it's worth doing.

I mean... lets look at this change:

Changed LuaEntityPrototype::underground_belt_distance to LuaEntityPrototype::max_underground_distance and changed it to work on both underground pipes and underground belts.

Isn't that pretty much the exact same reasoning we're using here?

[DaveMcW]

How about you make a list of the top 10 names that should be unified, and lobby for those.

If most get fixed you can go for more.

[bobingabout]

Personally, I don't go looking for them, but I shout loudly when I notice them.
The only two I can remember right now is the one on inserters, and result/products on recipes.
I KNOW there are more, but the only one bugging me right now is the one on inserters.

[Trippelbob]

Hello again

Even though it isn't an inconsistency between the data and control phase, this should fit well into the list:

Minium und maximum values of loot items and mining results are named differently. (The latter use the same product table type as recipe results.)

API images

[bobingabout]

Yes, now that you mention it, that was another one that bugged me.

[darkfrei]

It would be nice if you can to define prototypes with the same way that in the control:

Code: Select all

data.entity["assembling-machine-2"].type = "assembling-machine"

Code: Select all

data.item["piercing-rounds-magazine"].type = "ammo"