Standartisation in Base

[llms1]

Whenever there are multiple options to encode the same prototype there should be exactly one option that is the "standard" option. And the base mod should always use the standard option to make it easier for new mod developers to work with.

Lets take base/prototypes/recipe.lua as an example. There one can find the recipe for stone-brick:

Code: Select all

{
    type = "recipe",
    name = "stone-brick",
    category = "smelting",
    energy_required = 3.2,
    enabled = true,
    ingredients = {{"stone", 2}},
    result = "stone-brick"
 }

After seeing the

Code: Select all

enabled = true

line a new modder might think: "That is how all recipes, that are enabled from the start, look like".
And now when wanting to check whether a recipe is enabled from the start of a game it seems natural to use the following code:

Code: Select all

if recipe.enabled then
    -- paint the icon green
end

Upon loading the game and looking at the stone brick recipe he would see, that it is indeed green now, so everything seems to be working as intended.
But at a later time when looking at the iron-plate recipe it is noticed, that the recipe is not green, despite iron plates beeing available from the start of the game. This is because (as the documentation of prototypes points out) the enabled attribute of recipes defaults to true. And for the iron-plate recipe it is just left out:

Code: Select all

{
    type = "recipe",
    name = "iron-plate",
    category = "smelting",
    energy_required = 3.2,
    ingredients = {{"iron-ore", 1}},
    result = "iron-plate"
  }

So the correct code to check if a recipe is enabled or not would be:

Code: Select all

if recipe.enabled or recipe.enabled == nil then
    -- paint the icon green
end

This could have been figured out from the start by looking at the documentation, but the documentation can be overwhelming when just starting out.
This whole cycle happened to me in a lot of places when working with stuff from the base mod. And everytime it costs quite some time to figure out the underlying cause and then fix it. This makes it much harder than it needs to be to start modding factorio.
Other examples of this are:
- recipe ingredients can be written as: {type="item", name="steel-plate", amount=8} vs {"iron-plate", 12} which are accessed completely differently.
- some recipes use the results list some use the combination of result and result_count

Code: Select all

{
    type = "recipe",
    name = "firearm-magazine",
    energy_required = 1,
    ingredients = {{"iron-plate", 4}},
    result = "firearm-magazine",
    result_count = 1
  },
  {
    type = "recipe",
    name = "light-armor",
    enabled = true,
    energy_required = 3,
    ingredients = {{"iron-plate", 40}},
    result = "light-armor"
  }

see how even though both recipes produce one of their result, firearm-magazine has the result count specified and light armor does not.
And I am sure there are many more instances of style inconsistencies that I have not discovered yet.

I see the value of keeping the choice between not setting enabled to default to true and explicitly setting it to true. But at least for the base mod there should be a standartised way in which all recipes are described unless there is good reason to diverge from it.
That way a new modders mod might still break when interacting with other mods (which is always a possibility anyway and I would consider that an advanced topic) but at least for the base game, if something works for one prototype it will work for others, unless they are meaningfully different.