Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
User avatar
DaveMcW
Smart Inserter
Smart Inserter
Posts: 3713
Joined: Tue May 13, 2014 11:06 am
Contact:

Re: Small documentation improvement requests

Post by 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
-> Thanks a lot for the detailed notes, fixed for the next release.

User avatar
ickputzdirwech
Filter Inserter
Filter Inserter
Posts: 787
Joined: Sun May 07, 2017 10:16 am
Contact:

Re: Small documentation improvement requests

Post by 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.
Mods: Shortcuts for 1.1, ick's Sea Block, ick's vanilla tweaks
Tools: Atom language pack
Text quickly seems cold and unfriendly. Be careful how you write and interpret what others have written.
- A reminder for me and all who read what I write

curiosity
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Inserter
Inserter
Posts: 42
Joined: Sat Dec 14, 2019 3:26 am
Contact:

Re: Small documentation improvement requests

Post by -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.

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

(I accidentally deleted curi's original comment, but thankfully it is preserved in this reply. Whoopsie)
curiosity wrote:
Mon Sep 13, 2021 6:28 pm
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.
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

curiosity
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

eradicator wrote:
Mon Sep 13, 2021 9:15 pm
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
Smart Inserter
Smart Inserter
Posts: 1037
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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!
I have mods! I guess!
Link

User avatar
DaveMcW
Smart Inserter
Smart Inserter
Posts: 3713
Joined: Tue May 13, 2014 11:06 am
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 679
Joined: Sat Mar 02, 2019 9:39 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
My mods
Content: Lunar Landings | Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

oof2win2
Long Handed Inserter
Long Handed Inserter
Posts: 56
Joined: Wed Nov 18, 2020 8:13 am
Contact:

Re: Small documentation improvement requests

Post by 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.

User avatar
JohnTheCF
Inserter
Inserter
Posts: 27
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.drop_target
https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.pickup_target
boskid@discord wrote: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
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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.

User avatar
JohnTheCF
Inserter
Inserter
Posts: 27
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »


User avatar
JohnTheCF
Inserter
Inserter
Posts: 27
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by 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.

User avatar
snouz
Inserter
Inserter
Posts: 27
Joined: Sun Jan 03, 2021 6:01 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
Graphically contributed to : Bio Industries (soon) | Warehousing | MFerrari's mods | Brevven's mods | Bob Artisanal Reskins | Mining Drones | Teleporters | Emoji signals

User avatar
JohnTheCF
Inserter
Inserter
Posts: 27
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 441
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1037
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

snouz wrote:
Fri Oct 15, 2021 10:41 am
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.
I have mods! I guess!
Link

Locked

Return to “Documentation Improvement Requests”