Small documentation improvement requests

Place to ask discuss and request the modding support of Factorio. Don't request mods here.
curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/Global.html - doesn't say that LuaObjects can't be stored as keys.

-> Noted for the next release, thanks. Actually, this is not quite right. LuaObjects can be used as keys, it just doesn't really make sense since you won't be able to index them after save/load with the 'same' LuaObject, since it'll be a new table. This is the same principle as using regular tables as keys, so it's not appropriate to note this behavior here.

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_tiles_filtered - area.right_bottom is treated as exclusive by this function (area.left_top is properly inclusive), which is not what you'd expect from something called "bounding box".

Fixed for 1.1.54 - right bottom corner will be included (boskid)

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://wiki.factorio.com/Prototype/Tile#transitions - says that to_tiles is a string when in fact it's a table (or maybe an array) of strings. And the (lack of) formatting of the additional properties is pretty awful, if I'm honest. All of them in a single line like that looks like a mess.

-> Fixed.

Pi-C
Smart Inserter
Smart Inserter
Posts: 1276
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

Description of LuaForce.character_running_speed_modifier:
character_running_speed_modifier :: double [Read/Write]

Modifies the running speed of all characters in this force by the given value as a percentage. Setting the running modifier to 0.5 makes the character run 50% faster. The minimum value of -1 reduces the movement speed by 100%, resulting in a speed of 0.
Two questions:
  • According to the description, this modifies the property for all characters on the force. I assume the same is true for the different character_*_bonus properties. Shouldn't their descriptions also show "Modifies X of all characters in this force"?
  • What exactly does "all characters in this force" mean? Is it really all characters, including those that are not connected to a player?
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
Wiwiweb
Inserter
Inserter
Posts: 26
Joined: Sat May 08, 2021 2:36 am
Contact:

Re: Small documentation improvement requests

Post by Wiwiweb »

For EntityPrototypeFilter:

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

It says `type` expects a string but it can actually be a table of strings too.
Screenshot 2022-02-02 080659.png
Screenshot 2022-02-02 080659.png (34.75 KiB) Viewed 1123 times

Probably the same for all the `*PrototypeFilter` classes.


-> Thanks, fixed for the next release.

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.player needs clarification for what counts as "typing at the console". E.g. it exists in command handlers, but not in the on_console_chat or on_console_command handler. Is there anything else that may be considered "typing at the console" and does it exist during that?

-> Thanks, I clarified this for the next release. The only places it is not nil are command handlers and /c-type console commands.

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://wiki.factorio.com/Prototype/Beam - what is the difference between start/ending and head/tail?

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_entities_filtered leads one to believe (or, at least, doesn't contradict) that the radius option searches center to center. Should explicitly say what kind of check it does.

-> I noted that it searches for the center of entities for the next release.

User avatar
Therax
Filter Inserter
Filter Inserter
Posts: 470
Joined: Sun May 21, 2017 6:28 pm
Contact:

Re: Small documentation improvement requests

Post by Therax »

References to https://lua-api.factorio.com/latest/Con ... l#Position should be removed and replaced with references to MapPosition, TilePosition (which is entirely redundant with Position's current definition), or ChunkPosition as appropriate.

Several APIs and other Concepts that reference Position (such as BoundingBox) are actually MapPosition-based and accept fractional coordinates, which the documented definition of Position disallows.


-> Indeed, this was the solution that we went for. The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition.
Miniloader — UPS-friendly 1x1 loaders
Bulk Rail Loaders — Rapid train loading and unloading
Beltlayer & Pipelayer — Route items and fluids freely underground

User avatar
Silari
Filter Inserter
Filter Inserter
Posts: 388
Joined: Sat Jan 27, 2018 10:04 pm
Contact:

Re: Small documentation improvement requests

Post by Silari »

Therax wrote:
Tue Feb 15, 2022 6:18 pm
Several APIs and other Concepts that reference Position (such as BoundingBox) are actually MapPosition-based and accept fractional coordinates, which the documented definition of Position disallows.
See Klonan's post on that - viewtopic.php?p=558683#p558683 . Writing rounds values, so even things that only take Position will accept non-integer values to make it easier to pass things directly without needing to try and fix them yourself.

Also see Therenas' post - viewtopic.php?p=560440#p560440 that says he's hoping to fix all the position stuff up but the docs simply aren't setup that way right now.


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

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

Silari wrote:
Tue Feb 15, 2022 6:49 pm
See Klonan's post on that - viewtopic.php?p=558683#p558683 . Writing rounds values, so even things that only take Position will accept non-integer values to make it easier to pass things directly without needing to try and fix them yourself.

Also see Therenas' post - viewtopic.php?p=560440#p560440 that says he's hoping to fix all the position stuff up but the docs simply aren't setup that way right now.
Klonan is ultimately missing the point in that post. And beside that, rounding was never an issue either for usability or documentation. It seems like it is supposed to say that TilePosition converts fractional values to integers, which IMO makes it quite clear that you can pass a MapPosition to whatever takes TilePosition. There is absolutely no issue with this, you just have to specify the conversion rules.

Therax is right that there is redundancy right now and, as the most vaguely named, it makes sense for Position to go.


-> Indeed, this is the solution that we went for. The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition.

Bilka
Factorio Staff
Factorio Staff
Posts: 2853
Joined: Sat Aug 13, 2016 9:20 am
Contact:

Re: Small documentation improvement requests

Post by Bilka »

Regarding the whole Position confusion, as suggested a few times here, we decided to get rid of Position and have everything use the more specialized types like MapPosition, TilePosition, ChunkPosition and Vector. I went through the docs and adjusted everything to refer to the correct specialized type, so everything should be documented as the correct type now. This also introduces the new concept EquipmentPosition, which is used by equipment.

This should make it a lot more clear what each position type is used for. The confusion regarding rounding should also be solved with this change. The change will be part of the next release.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

kubel34
Burner Inserter
Burner Inserter
Posts: 5
Joined: Mon Aug 26, 2019 5:48 pm
Contact:

Re: Small documentation improvement requests

Post by kubel34 »

LuaEntity::is_crafting is missing a return value, which should be a boolean.

-> Thanks, fixed for the next release.

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

Speaking of LuaEntity::is_crafting, the description is unclear. What is the difference between "progress being made" and "crafting action made progress"? Are you trying to say that it returns whether the machine is in the process of crafting something? Something else?

-> It's that a 'craft' has been started beforehand (like kubel said below). I tried to clarify the wording a bit for the next release.

kubel34
Burner Inserter
Burner Inserter
Posts: 5
Joined: Mon Aug 26, 2019 5:48 pm
Contact:

Re: Small documentation improvement requests

Post by kubel34 »

I suppose that when a crafting machine starts crafting (enough ingredients + has power), is_crafting is true and stays true until the operation is completed.
"progress is currently being made" when there is power, and if there is not then the machine is not making progress but is still crafting.
I think that it is simply equivalent to: [code]is_crafting = progress > 0[/code]

-> Yep that's it.

I spotted another mistake: LuaControl::is_flashlight_enabled() is also missing a return value.

-> Thanks, fixed for the next release.

ILLISIS
Burner Inserter
Burner Inserter
Posts: 6
Joined: Wed Feb 09, 2022 10:49 am
Contact:

Re: Small documentation improvement requests

Post by ILLISIS »

https://lua-api.factorio.com/latest/eve ... _destroyed

Note
Depending on when a given entity is destroyed, this event will be fired at the end of the current tick or


The sentence ends at or[/strike]

-> Fixed for the next release, thanks.

Pi-C
Smart Inserter
Smart Inserter
Posts: 1276
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

LuaEntity.last_user:
last_user :: LuaPlayer [Read/Write]

I've accidentally set player.last_user to a Boolean value and got this error:

Code: Select all

Expected LuaPlayer, index, or name.

So the description should actually read
last_user :: LuaPlayer or PlayerIdentification [Read/Write]

Notes
PlayerIdentification can be used when writing to this value, but reading it will always return LuaPlayer.

I suppose the same applies to other R/W properties that return LuaPlayer on reading, namely LuaEntity.associated_player and LuaEntity.render_player.


-> Thanks, I noted this on all three properties. Long-term, the better solution is to allow separate read and write types in the documentation for cases like this, but that's not a thing just yet.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Nexela
Smart Inserter
Smart Inserter
Posts: 1828
Joined: Wed May 25, 2016 11:09 am
Contact:

Re: Small documentation improvement requests

Post by Nexela »

Surface.create_entity{target =, source =}

MapPosition is missing as an optional for target and source both takes either LuaEntity(with health for target) or MapPosition


-> You're right, thanks, fixed for the next release.

curiosity
Fast Inserter
Fast Inserter
Posts: 176
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.is_connected_to_electric_network - the description is incomplete. Seems to mean if the entity is connected to a network capable of producing power, the exact opposite of the entity having a blinking electric plug icon over it. But always false for some entities, like power poles, regardless of the network.

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

Saiph300
Burner Inserter
Burner Inserter
Posts: 6
Joined: Tue Aug 14, 2018 5:20 pm
Contact:

Re: Small documentation improvement requests

Post by Saiph300 »

Hi, I'd like to ask some info about the field 'track_type' in https://wiki.factorio.com/Prototype/AmbientSound
This lets the game know in what instances the audio file is played. Possible values:
"early-game"
"main-track"
"interlude"
"late-game"
"menu-track"
I think this description already makes a bit of sense, but can you detail:
1) what is the difference between "interlude" and "main-track"
2) when are "early-game" and "late-game" triggered?


-> 1) I added to the page. 2) is at the same time as main-track, they have no special meaning. Also added to the page. Thank you for pointing out that information was missing here.

Post Reply

Return to “Modding interface requests”