Documentation Improvement Requests

[snouz]

Settings aren't really documented at all, which may be more of the "confusion". The only page is: https://wiki.factorio.com/Tutorial:Mod_settings . With regards to data and data:extend, extend is a function you can see in core/lualib/dataloader.lua (it is nothing magical, just puts stuff in data,raw). settings also has a settings-update, and settings-final-fixes phase, for other mods to alter existing settings (hiding,restricting, changing, etc). See https://lua-api.factorio.com/latest/Data-Lifecycle.html . The data.raw on the wiki only is from the data stage (and a separate one for settings stage would be an empty data.raw table... because there are no mod settings by default.)

I've made a minor addition to https://wiki.factorio.com/Tutorial:Mod_ ... o_settings, do you think it's an acceptable edit?

-> Thank you for adding this to https://wiki.factorio.com/Tutorial:Mod_settings, I also added some more info.

[Honktown]

Settings aren't really documented at all, which may be more of the "confusion". The only page is: https://wiki.factorio.com/Tutorial:Mod_settings . With regards to data and data:extend, extend is a function you can see in core/lualib/dataloader.lua (it is nothing magical, just puts stuff in data,raw). settings also has a settings-update, and settings-final-fixes phase, for other mods to alter existing settings (hiding,restricting, changing, etc). See https://lua-api.factorio.com/latest/Data-Lifecycle.html . The data.raw on the wiki only is from the data stage (and a separate one for settings stage would be an empty data.raw table... because there are no mod settings by default.)

I've made a minor addition to https://wiki.factorio.com/Tutorial:Mod_ ... o_settings, do you think it's an acceptable edit?

I wouldn't phrase it that way. After a call to data:extend the setting is in data.raw, not at the end of the setting stage. Also, changing an allowed value to only one is what can force a setting. Changing the default won't do anything if a mod was loaded once, before changing the default. A new section is warranted I think: Modifying Existing Settings, with a mention for "mod-packs" and compatibility. You don't need to write it all yourself, but that should cover most of it.

(I didn't notice the wiki mentioned settings-etc files already.)

-> I have added some additional info, such as how to force a setting to be of a certain value. The section is titled different but contains all the buzzwords mentioned here, so it should hopefully still show up in searches.

[Stringweasel]

https://wiki.factorio.com/Prototype/Gen ... emperature

The maximum temperature to which the efficiency will increase. After this temperature the generator will run at 100% efficiency. Note: higher temperatures can still be consumed.
-> It's a bit more complicated than that, I've expanded the page on maximum_temperature and related properties.

[GlassBricks]

For defines.events.on_game_created_from_scenario we could add the additional note that "This event is not fired when the scenario is loaded via the map editor", a fact I discovered only after digging around a bit. This would be useful to note that this event could be used to detect whether or not a scenario was loaded via the Map editor, for mods that want some interaction with the map editor specifically.

-> Added for the next release.

[Honktown]

A note on get_fluid_count() and get_fluid_contents() where defined, that they do not capture temperature details, and fluidboxes should be used directly [in the cases where temperature is relevant].

Related to: viewtopic.php?f=221&t=100323

-> Appreciate the context, added for the next release.

[justarandomgeek]

https://lua-api.factorio.com/latest/Con ... Connection

describes the type of positions as array[Vector], but hten has a comment that they have x/y, shouldn't this be array[Position]?

[Silari]

https://lua-api.factorio.com/latest/Con ... Connection

describes the type of positions as array[Vector], but hten has a comment that they have x/y, shouldn't this be array[Position]?

https://lua-api.factorio.com/latest/Con ... tml#Vector Vectors also have an x/y, sometimes as an array, sometimes as a table with explicit x and y members. Far as I can tell the only difference is Position MUST be int for x/y, Vector isn't specified but the example has decimals.

The description for Position implies that it's only used when actually specifying a map position, which may be why Vector is considered a different thing.

[Therenas]

Silari is right in this case, I actually put that x/y line there myself pretty recently. The whole situation isn't great, it's on my list to come up with a better solution to it, but the underlying issue is that it's just inconsistently implemented in the APIs, sometimes it's one way, sometimes the other. The real fix would be to fix what the API returns, but that's not feasible in 1.1. We'll see, maybe I can think of something.

[JohnTheCF]

https://wiki.factorio.com/Prototype/UtilityConstants
pollution_color property is missing.
-> Was added in 1.1.41, fixed.

[InappropriatePenguin]

I think there's a mistake in the description of this function: https://lua-api.factorio.com/next/LuaCo ... _blueprint.

It refers to a `get_cursor_blueprint_entities` function which I couldn't find in the API—I was guessing it meant to refer to `get_blueprint_entities`, which is described right below it.

-> Thanks for the hint, corrected and updated for the next release.

[InappropriatePenguin]

LuaControl.set_personal_logistic_slot (https://lua-api.factorio.com/latest/Lua ... istic_slot)

The function returns a boolean value reflecting whether it was successful or not. The note for that function however states that it will silently fail if personal logistic aren't researched. I wasn't sure if that meant that the returned boolean value could not be relied on in that instance.

In testing, the function does appropriately return false when personal logistics are not researched, so perhaps a better wording would be: "This function will return false if personal logistics aren't researched, but will not raise any error." or something along those lines.

This is on contrast to LuaControl.clear_personal_logistic_slot (https://lua-api.factorio.com/latest/Lua ... istic_slot), which does truly appear to "silently" fail when personal logistics aren't researched since it has no return value.

-> Thank you for the detailed report, this has been addressed for the next release.

[GlassBricks]

It seems LocalisedString also allows boolean values (and even nil in many cases); this could be documented.

-> Thanks, this is clarified for the next release.

[InappropriatePenguin]

LuaGameScript.delete_surface() (https://lua-api.factorio.com/latest/Lua ... te_surface)

This function appears to be similar to LuaSurface.delete_chunk() and LuaSurface.clear() in that it does not run immediately when called but rather appears to run either at the end of the current tick or some time in the next game tick. That is at least when it seems to raise its associated events.

I would suggest adding a note to its description to make that clear.

-> This is a good point. A proper system for documenting when an event fires is in the works, and should be ready soon, so I will not add a note for this single thing for now.

[fredthedeadhead]

I think I've found some mis-typed fields:

[list=1]
[*] https://lua-api.factorio.com/latest/Con ... l#Position

Position x and y are documented as being ints, but when I get the player's position, it returns floating point numbers with decimal places.

Code: Select all

/c local p = game.player p.print(p.position.x.." "..p.position.y)  
-0.05078125, 46.48828125

[*] https://lua-api.factorio.com/latest/Lua ... ce.daytime

LuaSurface.daytime is documented as a float, but is actually a double.
[/list]

-> Thanks for the hints, both of these are fixed for the next release.

[InappropriatePenguin]

LuaEntity.damage(damage, force, type, dealer)
[https://lua-api.factorio.com/latest/Lua ... ity.damage]

It appears that the `dealer` entity must be located on the same surface as the entity being damaged, or it will raise an error. Perhaps this can be mentioned, either in the parameter description or as a note next to "Can only be used if this is EntityWithHealth"?

-> Noted for the next release, thanks.

[JohnTheCF]

https://wiki.factorio.com/Types/MapGenP ... c_settings

`autoplace_settings` just has type of table and there is no explanation what its structure is supposed to be.

-> Thank you for pointing this out. The explanation for this from the runtime docs has now also been added to the wiki.

[Pi-C]

destructible :: boolean [Read/Write]

When the entity is not destructible it can't be damaged.

I've neglected this flag so far because its effect seemed to be the same as giving an entity full resistance against all damage types. However, a posting by posila let me realize that setting this flag set to false will prevent enemy units and turrets from attacking this unit (if the flag is set to true, they may attack it although they can't damage it). I'd suggest changing the description to

Code: Select all

 destructible :: boolean [Read/Write]

When the entity is not destructible it can't be damaged and won't be automatically attacked.

-> Thanks, clarified for the next release.

[-DeadlyKitten]

the page https://wiki.factorio.com/Types/SpawnPoint
lists this

Types/SpawnPoint ... evolution_factor or 1 ... spawn_weight or 2

in testing however i found that it is called weight not spawn_weight

-> It's called spawn_weight in the data stage (which is what the wiki page is about) and weight during runtime (https://lua-api.factorio.com/latest/Con ... Definition).

[fredthedeadhead]

-> Thanks for the hints, both of these are fixed for the next release.

Hi, I see that LuaSurface is updated, thanks! But Position x/y is not, they still show ints.

Concepts.html#Position

-> The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition. So this is now fixed by it no longer being confusing what Position is for.

[Silari]

-> Thanks for the hints, both of these are fixed for the next release.

Hi, I see that LuaSurface is updated, thanks! But Position x/y is not, they still show ints.

https://lua-api.factorio.com/latest/Con ... l#Position

LUAControl.position, which LUAPlayer inherits from, returns a MapPosition, not a Position. Pretty sure that was the correction made.