Documentation Improvement Requests

[DaveMcW]

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

The 4 optional WireConnectionDefinition fields are listed as uint, but they should be defines.circuit_connector_id or defines.wire_connection_id.

The wire_id fields should also refer to copper wire instead of circuits.

• wire :: defines.wire_type: Wire color, either defines.wire_type.red or defines.wire_type.green.
• target_entity :: LuaEntity: The entity to (dis)connect the source entity with.
• source_circuit_id :: defines.circuit_connector_id (optional): Mandatory if the source entity has more than one circuit connector and using circuit wire.
• target_circuit_id :: defines.circuit_connector_id (optional): Mandatory if the target entity has more than one circuit connector and using circuit wire.
• source_wire_id :: defines.wire_connection_id (optional): Mandatory if the source entity has more than one wire connection and using copper wire.
• target_wire_id :: defines.wire_connection_id (optional): Mandatory if the target entity has more than one wire connection and using copper wire.

Same for CircuitConnectionDefinition

• wire :: defines.wire_type: Wire color, either defines.wire_type.red or defines.wire_type.green.
• target_entity :: LuaEntity
• source_circuit_id :: defines.circuit_connector_id
• target_circuit_id :: defines.circuit_connector_id

-> Thanks a lot for the detailed notes, fixed for the next release.

[ickputzdirwech]

https://lua-api.factorio.com/latest/Lua ... ty_filters To my knowledge all strings in this array must be names of entity prototypes that:
1. don't have the flag "not-deconstructable" and
2. are either a cliff or are minable

-> Thanks, updated for the next release.

[curiosity]

The "crafting" recipe category is hardcoded to disallow fluids, but this isn't documented anywhere obvious (Recipe.category or RecipeCategory). If anything is hardcoded about any other categories, or something else about the "crafting" category, it would also be good to know.

-> Only "crafting" has special behaviour, this is now documented on both linked pages.

[-DeadlyKitten]

please fix surface.spill_item_stack

the documantion currently only tells what the first 2 fields do but i found this command with 5 inputs in a mod

player.surface.spill_item_stack(player.position, inventory, true, player.force, true)

-> Not sure which docs you are looking at, but Surface.spill_item_stack lists five arguments. If there is still an issue in your opinion, please add a new comment to this thread.

[eradicator]

(I accidentally deleted curi's original comment, but thankfully it is preserved in this reply. Whoopsie)

https://wiki.factorio.com/Tutorial:Localisation#Built-in_parameters says "We can also use this for items and entities etc.", but there is no list of acceptable keywords anywhere.

Yea, it should say item-names and entity-names. The "etc" is also suspicious. Are there actually any other prototypes supported other than __ITEM__ and __ENTITY__?

-> Added, thank you Honktown for starting the list.

[curiosity]

Yea, it should say item-names and entity-names. The "etc" is also suspicious. Are there actually any other prototypes supported other than __ITEM__ and __ENTITY__?

There is also __TILE__ and some other things. But regardless, there should be a proper list of keywords, not "items and entities". This is not a guessing game.
-> Added, thank you Honktown for starting the list.

[Honktown]

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

Code: Select all

path :: string (optional): Path to save the screenshot in.

Default to script output? with or without a leading ./?

Code: Select all

quality :: int (optional): The render quality if using jpg format (0-100 inclusive).

There's nothing to say how this works. No quality = png and 0-100 = jpg?

-> I improved both of the screenshotting functions in a number of ways for the next release, thanks for the hint!

[DaveMcW]

https://lua-api.factorio.com/latest/Lua ... cted_rails
https://lua-api.factorio.com/latest/Lua ... gnal_state

Can only be used if this is RailSignal

This is technically incorrect, they require RailSignalBase, which includes RailSignal and RailChainSignal. Since RailSignalBase is not documented anywhere, we should list both child prototypes.

Can only be used if this is RailSignal or RailChainSignal

-> Very astute, thanks a lot, fixed for the next release.

[Xorimuth]

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

Note: This can become invalid if during operation if the given player becomes invalid.

Typo: two 'if's.

What does it mean by 'operation'? Does it mean if you save the settings for that player to a variable, then cause the player to become invalid, then try to access the settings variable?

-> Thank you, I reworded that sentence to make it clearer for the next release. And yes, it does mean what you proposed.

[oof2win2]

https://lua-api.factorio.com/latest/Lua ... t.location
> or `nil` if not not set or not in
Probably should have only one not

-> Thanks, fixed for the next release.

[JohnTheCF]

On the Prototype Definitions page, GuiStyle is shown to inherit from PrototypeBase, but on GuiStyle page PrototypeBase is not listed as parent and GuiStyle does not inherit it's properties.
-> GuiStyle inherits from PrototypeBase, I must have missed updating that. Fixed now

[curiosity]

https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.drop_target
https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.pickup_target

if there are multiple entities at the pickup or drop position, you can write there to select which one should be used for pickup and for drop
there is however a small limitation: that entity has to collide with the tile box under the pickup or drop position

https://discord.com/channels/1396775903 ... 8990987284

-> Clarified for the next release, thanks

[curiosity]

https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.get_transport_line doesn't say if the transport lines are 0-indexed or 1-indexed (or, possibly, any other scheme).

-> They are 1-indexed, which I noted for the next release.

[JohnTheCF]

https://wiki.factorio.com/Prototype/Til ... ransitions
There is a little typo in property description, space is missing between "and" and "transition_group2"

-> Thank you for pointing this out, fixed.

[curiosity]

https://wiki.factorio.com/Prototype/Roboport#recharge_minimum - missing description.
-> Added.

[JohnTheCF]

https://wiki.factorio.com/Prototype/Tutorial
"trigger" property is listed in table of contents, but not in mandatory or optional properties section.
-> That was an old value from the cache, I cleared the page cache so it should be fixed.

[snouz]

Not 100% sure it belongs to that page, but I can confirm settings are accessible in data.raw (from the setting stage at least). But it's nowhere to be seen in https://wiki.factorio.com/Data.raw

example in settings-updates.lua:
data.raw["bool-setting"]["Schall-VS-XL-t2-enable"].order = "1"
correctly moves the setting to the beginning.

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

[JohnTheCF]

Some StyleSpecification extensions have type string in table on StyleSpecification page, but are marked <abstract> on individual pages. So far I've noticed:
https://wiki.factorio.com/Types/EmptyWidgetStyleSpecification
https://wiki.factorio.com/Types/ScrollB ... cification
https://wiki.factorio.com/Types/StyleWi ... cification

-> EmptyWidgetStyleSpecification indeed has a style name, fixed the individual page. However, the other styles have <abstract> on both pages, which looks correct when looking at the source code.

[curiosity]

Contradictory documentation: Prototype/MiningDrill#allowed_effects and Prototype/Lab#allowed_effects say that the default is all effects, but Types/EffectTypeLimitation says that the default is nothing. What I think would be better is specifying the defaults for Prototype/Beacon#allowed_effects and Prototype/CraftingMachine#allowed_effects and removing the mention of nil entirely from Types/EffectTypeLimitation.

-> That is not the usual approach, but it works well enough in this case. So, changed, thank you for the idea.

[Honktown]

Not 100% sure it belongs to that page, but I can confirm settings are accessible in data.raw (from the setting stage at least). But it's nowhere to be seen in https://wiki.factorio.com/Data.raw

example in settings-updates.lua:
data.raw["bool-setting"]["Schall-VS-XL-t2-enable"].order = "1"
correctly moves the setting to the beginning.

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.)

-> The info on altering existing settings has been adde.