Documentation Improvement Requests

[Enderdraak]

In https://lua-api.factorio.com/latest/Lua ... rge_forces it states that all entities get transfered. This does not exclude all other things. Like techs, bonuses or script info. And where the latter can be easily figured out that it will not happen within the merge itself and instead requires the on_forces_merging event. For techs and bonuses it might not be clear. Maybe change it to 'all the entities and nothing else'.

-> Good points, thanks. Added for 1.1.71.

[Pi-C]

According to the desccription of LuaGuiElement.tags, tags can be read and written. But it seems that the tag can't be changed after it has been created:

Code: Select all

      -- Camera
      if not vehicle_list[col_names.camera..v_id] then
        element = vehicle_list.add({
          type = 'sprite-button',
          name = col_names.camera..v_id,
          sprite = 'autodrive-camera',
          style = 'autodrive_button_off',
          tooltip = {tooltips.."camera"},
          tags = {state = show_on_camera and 'on' or 'off'},
        })
      end

When creating the GUI, "show_on_camera" is nil, so element.tags.state will be "off". In my handler for defines.events.on_gui_click, I have this:

Code: Select all

  -- Button for camera has been toggled
  elseif AD.prefixed(element.name, col_names.camera) then
    if element.tags.state == 'on' then
AD.writeDebug("Turning element state off.")
      element.tags.state = 'off'
    else
AD.writeDebug("Turning element state on.")
      element.tags.state = 'on'
      element.tags.test = 'true'
    end
AD.show("element.tags", element.tags)
  end

My log shows that the button has been clicked to turn on the camera, but element.tags didn't change:

Code: Select all

25452.311 Script @__autodrive__/libs/debugging.lua:173: Turning element state on.
25452.311 Script @__autodrive__/libs/debugging.lua:173: element.tags: {
  state = "off"
}

-> As pointed out to you below (comments now deleted to keep the thread cleaned up), tags are returned as a plain table, and you'll need to write a table back to modify them. I noted this on the Tags concept for 1.1.75.

[curiosity]

There seems to be missing from the docs a very important notion: the game-mod boundary. And what happens with table values that cross it.

-> Good point, thanks. There will be more of these 'auxiliary' topic pages in the future, and I wrote this one down for that. Will take a while to materialize though, FYI.

[Enderdraak]

So for some reason I was lookin in the recipe documentation. Ans specifically to what values of ingredients and results you need to have.
So what I found:
No sub page for https://wiki.factorio.com/Prototype/Recipe#normal or https://wiki.factorio.com/Prototype/Recipe#expensive exists.
While https://wiki.factorio.com/Prototype/Recipe#ingredients does not contain an 'optional' indicator, it does not explain that this or normal and(/or) expensive is needed.
Then we have for https://wiki.factorio.com/Prototype/Recipe#result and https://wiki.factorio.com/Prototype/Recipe#results that it does not explain that you can leave both away and that the game will then default to 1 item of the recipe name.

Edit: I skipped reading the https://wiki.factorio.com/Prototype/Recipe#Recipe_data part of the wiki

[aaron311]

Hello,

I really found the "Data Lifecycle" documentation page very helpful when I was reading it the other day struggling to remember how the various initialization-related events worked. It's great, but there were a few outstanding questions in my mind after reading it.


#1. I had a question about on_configuration_changed() which I asked here and got a very helpful (but verbose) answer from a dev:
viewtopic.php?f=25&t=103808

To that end, I have consolidated a few updates to [5] on_configuration_changed() that you might wish to consider:

[5] on_configuration_changed()

This step runs for all mods if the save's mod configuration has changed. The configuration is considered to be different when the major game version or any mod version changed, when any mod was added or removed, when a startup setting has changed, or when any prototypes have been added or removed.

During it, their LuaBootstrap::on_configuration_changed handler is called, allowing them to make changes or adjustments to their internal data structures. To that end, global can be accessed and modified at will. Mods also have full access to the game object, enabling any change to the game state that they deem appropriate.

Examples of when this event would fire when loading of a save file:
1. Game version has changed.
2. Save file format is different than current version.
3. List of active mods (name+version+crc) sorted by dependencies order is different.
4. Mod startup settings are different.
5. It is forced by a user (holding Control key while pressing the "Load" button in the Load game gui).
6. There were migrations applied to a save file since they were not yet applied to it.

Examples of when this event does NOT fire when loading a save file:
1. Client is joining a multiplayer server (client and server must already be in sync in all respects to join), and server has already run on_configuration_changed if necessary when loading the map when starting up.
2. Game is playing a replay.
3. Game has determined map was saved with an 'identical' configuration to the current game.

Changes in BOLD. Basically I struck "major" because it is misleading. And the examples were those given by the dev in the post and - personally - I feel they are illuminating for people struggling to understand the concept.



#2. I really struggled to understand whether it was 'safe' to do a sort of 'conditional event registration' in control.lua. Namely, I initially wrote some code that did:

Code: Select all

local function my_evil_func(event)
    script.on_event(defines.events.on_tick, nil)
    ...
end

...
script.on_event(defines.events.on_tick, my_evil_func)

This is of course horribly evil and will cause a desync because it will cause the my_evil_func to execute on the client on the first tick of joining the game, but of course that event will NOT fire for the server and existing clients. When I initially wrote this code, I was assuming that perhaps control.lua didn't actually fully run the same upon someone joining a multiplayer game; I figured maybe the current event registration table state for each mod was somehow transferred by the server to the client.

Fortunately, I searched the forums and found a few topics where it was discussed how this is horrible and not going to work.

As such, I'd suggest explicitly warning in the documentation. Maybe something like:

[1] control.lua

During this step, each mod's control.lua file is loaded and executed in their own Lua state that will be owned by them for the remainder of the play session. It allows a mod to register for events using the script object, register remote interfaces with the remote object, or register custom commands with the commands object.

Access to the game and rendering objects is not available as the game state can not be manipulated at this point. While each mod has their own global table, it is not restored until the end of this step (if loading a save file). This means that global is still empty at this point and anything a mod adds to it during this step will be overwritten.

Since this step is run every time a save file is created or loaded, it is not necessary to restart the game for changes to the control.lua file to take effect. Restarting or reloading a save will re-run this stage and pick up any modifications to the code.

Cautionary Note:
In multiplayer games, execution of control.lua cannot happen at the same time for all users; it is run for each user upon joining the game. Despite this, registering event handlers in control.lua is *usually* safe from desyncs because most mods register event handlers consistently regardless of mod/game state. However, if a mod makes *conditional* event handler registrations, registering event handlers in control.lua will surely cause a desync (the newly-joined client's events will fire differently than the previous clients in the game).

In the case of conditional event registration, the mod should instead store the current event registration state in the global table at all times. Then, control.lua should register an on_load event handler, which will then inspect the current event state in the global table and set up the conditional event handlers as appropriate for the current game state.

Obviously, feel free to edit/discard to your desire. No offense will be taken if these suggestions are ignored

-> Hello, appreciate the effort to put this together! Let's go through the points in order:
1. Not sure why 'major' was in there, I think it was before and I didn't really reconsider it. It should definitely be cut.
2. The changes suggested to on_configuration_changed are a bit verbose to me, and repeat a lot of what's said above. I know the data lifecycle page is very dense, but it's also meant to be concise and precise. It'll take a few reads before grasping it, but repeating the same information in a different way is detrimental in my eyes. Still, I modified and expanded the explanation a bit, especially with regards to multiplayer.
3. Conditional event handlers are already touched upon in a few places, and I don't want to go into it too much since it's very niche (and dangerous like you found out), but I sprinkled in a warning of sorts.
Changes will be released with 1.1.75.

[Honktown]

1.1.70/events.html#on_pre_build

The English for these two description is strange:

Code: Select all

flip_horizontal
:: boolean

    If building this blueprint was flipped horizontally.
flip_vertical
:: boolean

    If building this blueprint was flipped vertically.

Perhaps:

Code: Select all

flip_horizontal
:: boolean

    If a blueprint was used and whether it was flipped, horizontally. Nil if not built by blueprint.
flip_vertical
:: boolean

    If a blueprint was used and whether it was flipped, vertically. Nil if not built by blueprint.
    

-> Oof, yep. Fixed for 1.1.75, thanks.

[Honktown]

https://lua-api.factorio.com/1.1.70/Migrations.html

A question someone brought up and discovered, prototype migrations do not allow changing one prototype to another if the original still exists, right?

The context was they wanted to switch modular armor to their 'armor-with-grid-1' prototype, and were trying to reduce the odds of breaking things (the modular armor recipe was already hidden and disabled, item hidden, etc etc)

-> I can't reproduce this, I was able to rename a belt 1 to a belt 2 without removing the original prototype. Must have been another issue?

[Muppet9010]

The Factorio wiki description on an EnergySource for the Electric Energy Source is a bit misleading. When flagged in a discord chat Bilka requested it was raised here as a reminder for future clarification.

https://wiki.factorio.com/Types/EnergyS ... r_capacity

Area of concen: Shouldn't drain be that it's a constant drain from the buffer_capacity. And the buffer_capacity say it obtains energy from the electric network. Along similar lines the input_flow_limit and output_flow_limit relate to how fast the buffer_capacity can be filled/used.

-> Thank you Honktown for improving this on the wiki.

[Muppet9010]

The properaty_names argument that LuaSurface.calculate_tile_properties() takes is a little sparse on what property names it actually takes. The example is height, but doing a search in the API docs of height didn't return an obvious list of the property strings I could provide it.

https://lua-api.factorio.com/latest/Lua ... properties

From looking at a forum post I believe it takes the default and any modded noise-expression names. Like those defined in:

\data\core\prototypes\noise-programs.lua
\data\base\prototypes\entity\enemy-autoplace-utils.lua

Although I don't see height, instead elevation. So I wonder if the API docs example for this function is wrong ?
viewtopic.php?t=103226

[GlassBricks]

2 things:

LuaSurface::entity_prototype_collides and decorative_prototype_collides return a boolean; not nothing. They also have no description, so I'm guessing what they do from the name.

In my testing LuaItemStack::default_icons is of type of type BlueprintSignalIcon[], not BlueprintItemIcon[]. This is also the only place BlueprintItemIcon[] is used, so if this is changed then BlueprintItemIcon concept could be obsolete?

-> Funnily enough, the collides methods did have descriptions, they were just formatted incorrectly and thus not picked up on. Fixed this for 1.1.75, along with the return type.
-> Fixed the default_icons type for 1.1.79, thanks.

[Honktown]

LuaRecipe.ingredients
1) The example ingredients being here, in my opinion, doesn't match it not being in the description of LuaRecipePrototype.ingredients

2) The amounts in the advanced oil processing are incorrect (off by 10x) :

Code: Select all

{{type="fluid", name="crude-oil", amount=10}, {type="fluid", name="water", amount=5}}

How long has that been there??

-> Probably for quite a while! About 7 years from what I can see. Thanks, fixed for 1.1.79.

[Stringweasel]

LuaBurner::currently_burning

Writing `nil` will void the current burning fuel without producing a burnt_result.

-> Noted for 1.1.79, thanks.

[Honktown]

Maybe should be documented somewhere around map_gen_settings: "if there are no tiles defined to autoplace, the result for generation is always the first prototype tile, likely grass-1"

-> This is very specific and not 100% correct, we decided not to write this down.

[Deadlock989]

LuaSurface::create_entity - parameter "source". Context reads "Source entity. Used for beams and highlight-boxes" but this parameter is also valid for projectiles, is passed on to on_script_trigger_effect events for projectiles etc.

-> Noted for 1.1.79, thanks.

[Muppet9010]

The LuaEntity.set_driver() and LuaEntity.set_passenger() both list the parameter as mandatory in its type, but in description it lists the valid use of nil.

Noticed as Sumneko flags the discrepency.

https://lua-api.factorio.com/latest/Lua ... set_driver

-> Good catch, thanks. Fixed for 1.1.79.

[BurninSun]

[1.1.72]
https://lua-api.factorio.com/latest/Lua ... n_settings

...These can be modified to after surface generation,...

need to remove "to", or is it supposed to be "to alter"?

-> Thanks, fixed for 1.1.79.

[guardog]

https://lua-api.factorio.com/latest/Lua ... set_recipe

Description and actual behaviour shows that both recipe or nil can be accepted as parameters, but the documentation showed that the parameters are not optional.

-> Thanks, fixed for 1.1.79.

[LuziferSenpai]

Hey,

A feature that would be awesome, that is saves which of the category you have currently open/closed. So that is doesnt reopen the categories all the time, when you search something or switch between pages.

Greetz,

Luzifer

-> Good point actually, put it on the roadmap.

[Honktown]

https://lua-api.factorio.com/1.1.74/Lua ... nt_formula

The count formula used for this infinite research. nil if this research isn't infinite.

Technology with multiple levels also have a research count formula, and it comes up. Since a technology has a minimum of 1 level / max level, this presumably even can show up with a research count formula but only one level of technology to which it applies.

A more accurate description is probably:

The count formula, if this research was defined with one. Otherwise nil.

-> Thank you, fixed for 1.1.79.

[curiosity]

LuaEquipmentGrid.inhibit_movement_bonus: "True if this movement bonus equipment is turned off, otherwise false."
Sounds like it's a property of an equipment, not of a grid. IMO, this would be better: "True if this grid's movement bonus equipment is turned off, otherwise false."

-> Yup that's weird, thanks a lot. Fixed for 1.1.79.