Documentation Improvement Requests

[Honktown]

Compared to the documentation, it appears the behavior of on_gui_closed may have changed without notice https://lua-api.factorio.com/1.1.50/eve ... gui_closed Emphasis: "This is only called if the player explicitly closed the GUI." and this does not seem to be the case. I'm playing 1.1.49, but it's also present in those docs...

Attached is a command to cause events (open a thing to trigger it). The first command was to "reset" the code someone else was testing at the time, who brought up the issue.

[curiosity]

Speaking of MapPosition, it says "table" next to it whereas other position concepts are "table_or_array". And according to the description, MapPosition can also be an array.
-> Nice catch, fixed for the next version.

Besides, the introduction of MapPosition is absolutely redundant. There's already TilePosition, which has integer coordinates. So it just had to be properly noted which of the Position values are actually TilePosition and fix Position to correctly specify fractional coordinates. And now TilePosition's description doesn't even make sense! "This uses the same format as Position except it rounds any x/y down to whole numbers." Rounds down what? The fractional part of an integer?
-> The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition (with fractional coordinates) and TilePosition. So these descriptions should no longer be confusing.

[curiosity]

https://lua-api.factorio.com/next/Conce ... rintEntity: "The representation of an entity inside of a blueprint. It has at least these fields, but can contain additional ones depending on the kind of entity."
What are the additional fields?

-> There's dozens, it's on the TODO list to write them down at some point, just FYI.

[FuryoftheStars]

And now TilePosition's description doesn't even make sense! "This uses the same format as Position except it rounds any x/y down to whole numbers." Rounds down what? The fractional part of an integer?

That’s what “rounds […] down to whole numbers” means, yes.

[robot256]

The page for LuaBootstrap::raise_event() should note that invocations are ignored without producing an error when the "data" table contains any invalid LuaEntity references. I (re)learned this recently (viewtopic.php?f=23&t=101002).

Thanks!

-> Thanks, noted for the next release.

[curiosity]

That’s what “rounds […] down to whole numbers” means, yes.

Seems to me like you are missing the point. There is nothing to round down, the coordinates are already integer.

[Klonan]

That’s what “rounds […] down to whole numbers” means, yes.

Seems to me like you are missing the point. There is nothing to round down, the coordinates are already integer.

The documentation goes both ways, so its describing read behavior and write behavior

When reading a TilePosition, naturally it is only integers

But when writing it to the game engine, you can give it any number, and that will be rounded internally,

For instance with this 'Get hidden tile': https://lua-api.factorio.com/latest/Lua ... idden_tile
You don't have to give it integers, but whatever position you give it, it will be rounded down

So for instance, you can read an entity MapPosition, which has a precision of 1/256 tiles,
and then use that same table to call a method asking for a TilePosition, without any worry

[curiosity]

But when writing it to the game engine, you can give it any number, and that will be rounded internally,
...
So for instance, you can read an entity MapPosition, which has a precision of 1/256 tiles,
and then use that same table to call a method asking for a TilePosition, without any worry

Are you saying it's not the case for Position? Which also has integer coordinates according to the docs.
-> 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]

LuaEntity.neighbours's first line of description is a list item, so it displays weird in the property list. It should probably have a generalized summary of all the cases before the list.

-> Good spot, thanks, fixed for the next release.

[curiosity]

https://wiki.factorio.com/Prototype/ElectricPole#active_picture - what is this for?
-> Description added on the page.

[Xorimuth]

https://wiki.factorio.com/Types/SpiderV ... _positions what does light_positions do? I'm trying to improve the create_spidertron function in base so that it correctly scales the lights as well.

Seems to be the locations that the eye_light is placed.
-> Thank you for adding this yourself!

[curiosity]

https://wiki.factorio.com/Types/LightDefinition#type - the dependent property listing is inconsistent with other pages, where they are listed on the same level as the independent ones.

-> Fixed in the new prototype docs.

[Pi-C]

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

Fields

filter
:: string

The condition to filter on. One of "type"

This looks incomplete -- perhaps somebody removed the rest of the sentence accidentally?

-> This is actually just a bit of unfortunate formatting. That filter only supports "type", and is the only one to do so. I added a period at the end of those sentences for the next release though, to make it clearer that there's nothing missing. Thanks for bringing it up!

[curiosity]

The wiki doesn't say the maximum number of prototypes for most prototypes so far as I can see.
-> It's listed on all prototypes where it matters (maximum number is 255 or less).

[repne-scasb]

Bug: The new API docs lack enum value lists: viewtopic.php?f=7&t=101185
-> This was fixed.

[curiosity]

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.darkness doesn't say what the possible values interval is.

-> Thanks, added for the next release. It's [0, 1].

[jan1i3]

The description for `scroll_mode` for LuaGuiElement::scroll_to_item mentions "scroll-pane", contrary to the function's (correct) description saying "listbox".

The description for `scroll_mode` for `scroll_to_element` seems to be identical, it is correct in that case, just make sure to not break that one if they are shared.

-> Thanks Jan. If I were pedantic, it could be interpreted as 'in the scroll-pane of the list-box', but you're right that it's confusing, so I changed it for the next release. No worries about them being shared, documentation like this is almost always just copy-pasted, not actually shared. Which is probably where the mistake came from in the first place!

[curiosity]

Oh, all the "can only be used if" remarks are missing. This is a big degradation compared to the old docs.
Speaking of which:

The description for `scroll_mode` for LuaGuiElement::scroll_to_item mentions "scroll-pane", contrary to the function's (correct) description saying "listbox".

This says (or, rather, would have said) "Can only be used if this is scroll-pane". So which is it, scroll pane in general or specifically listbox?

-> Not sure if it didn't show when you made this comment, but the 'Can only be used if this is X' lines are present in the most recent version of the docs website. In that specific case, it only work for listboxes. 'scroll_to_element' can be used for scroll-panes.

[Pi-C]

Class LuaEquipment

Code: Select all

An item in a LuaEquipmentGrid, for example one's power armor.

The role of the power armor is not really clear in this example: Is the armor the item that can be placed in the equipment grid, or is the armor the grid where other things can be placed in? I'd put it this way:

Code: Select all

An item in a LuaEquipmentGrid, for example a fusion reactor placed in one's power armor.

-> Good spot, that is indeed confusing. Appreciate the alternate wording, fixed for the next release.

[Honktown]

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

Fields

filter
:: string

The condition to filter on. One of "type"

This looks incomplete -- perhaps somebody removed the rest of the sentence accidentally?

That's the automation of the docs. If you look at the other filters, they have more than one type of filter, so 'one of "a" or "b"' makes sense. Logically the plural-ness could be split into two or three cases... one (first), two (first and last), and "many" (first, last, middles). -> one = "filter of type a", two = "filter of type a[,] or b", many = "filter of type a, [b, c, ...], or last

-> This is true, see response in the next comment.