Documentation Improvement Requests

[paybara]

LuaEntity.circuit_connected_entities did not appear to be populated when inspecting entities attached to circuit networks.

Could be a bug, but given that LuaEntity.circuit_connection_definitions did have data, maybe it was deprecated and just needs to be marked as deprecated, or removed from docs?

[curiosity]

[quote=paybara post_id=584599 time=1682745816 user_id=165945]
LuaEntity.circuit_connected_entities did not appear to be populated when inspecting entities attached to circuit networks.
[/quote]
Hovering over the connected entity and performing [code]/c game.print(serpent.line(game.player.selected.circuit_connected_entities))[/code], can't reproduce.

[paybara]

[quote]Hovering over the connected entity and performing

[code]/c game.print(serpent.line(game.player.selected.circuit_connected_entities))
, can't reproduce.[/code]
[/quote]

...weird, that is working for me now.

I swear I was getting nothing but nils when I tried to use it in my mod, I guess I had some other bug.

Thanks for checking, and for the easy repro command!

[undermark5]

It would be good to add a note to "on_player_placed_equipment" indicating that it is triggered multiple times when ctrl-clicking in a stack of equipment. While it makes sense as to why this would be the case (you are adding multiple items and they each get a specific position in the grid), it does present some inconsistency with "on_player_removed_equipment" that only fires once with a count of items that were removed (and to be honest, I first wondered if I found a bug, because I didn't care about the particulars of the equipment that was added). So, it should be made clear in documentation that "on_player_placed_equipment" can be called multiple times when ctrl-clicking as changing the behavior of "on_player_removed_equipment" to fire for every item may result in breaking changes to existing mods.

Combine the above with the fact that the grid passed in the event already has all of the added pieces of equipment present makes me question if this is in fact a bug or not (previously, ctrl-clicking didn't trigger the event at all). Like it still makes some sense to have multiple times, but couldn't it get changed to give the index/key of any new equipment in the grid's equipment table?

[Rseding91]

... but couldn't it get changed to give the index/key of any new equipment in the grid's equipment table?

The event already has that? "equipment" https://lua-api.factorio.com/latest/eve ... _equipment

[undermark5]

... but couldn't it get changed to give the index/key of any new equipment in the grid's equipment table?

The event already has that? "equipment" https://lua-api.factorio.com/latest/eve ... _equipment

I'm aware, I'm saying that rather than firing the event multiple times for every piece of equipment, it could instead fire once and include a list/table of every piece of equipment that was added (it's all already present in the grid provided by the event, but you don't know which ones are new unless you've tracked this yourself or wait for each individual event).

My whole point is that there is inconsistency that isn't inherently apparent between 2 similar events. Not trying to say that this inconsistency can't exist, just that if it does, it should be documented better. As I stated, it does make some sense to get multiple events but it's not immediately apparent from the documents that ctrl-clicking into the grid fires multiple events while ctrl-clicking out of the grid fires a single event. Either changing the behavior or providing more details around when the events fire in the documentation solves the problem (documentation likely being the simpler of the two because it doesn't create potentially breaking charges and doesn't require writing code).

[BurninSun]

[1.1.81]
https://lua-api.factorio.com/latest/Lua ... ate_chunks
Lists `radius` as a required 2nd parameter, but the function is happy to run with a single `position` parameter and nothing for `radius`. Not sure if that actually does anything or not but the function should either be changed to require the 2nd parameter or the documentation should be updated for what it means to not pass the `radius` parameter.
-> Added to the docs with 1.1.102. It defaults to 0, which requests only the given chunk.

[curiosity]

LuaGameScript.get_entity_by_tag - what does it do?
-> Added to the docs in 1.1.102, thanks Honktown for the description/pointer to discord.

[Honktown]

LuaGameScript.get_entity_by_tag - what does it do?

That's for getting a tag set by clicking an entity and entering a tag while in `/editor` or Map Editor. Related, from Discord discussions:
[code]boskid — 06/24/2022 2:14 AM
value from "entity tag" inside of AdditionalEntityInfoGui will be accessible in the expansion (1.2.0) through LuaEntity::name_tag[/code]
and
[code]
boskid — 05/14/2023 1:47 AM
Great I made entity name tags writable from lua in 1.2.0[/code]

Edit: I see, the doc literally shows nothing lol.

-> Added to the docs in 1.1.102, thanks Honktown for the description/pointer to discord.

[Honktown]

https://lua-api.factorio.com/1.81/Conce ... Parameters
LogisticParameters is missing the nil interpretations. min is 0 by default, and max is infinite

-> Thanks, added to the docs with 1.1.102.

[Pi-C]

The description for LuaEntityPrototype.allow_passengers is misleading:

Code: Select all

allow_passengers :: boolean? Read 
Whether this vehicle allows passengers.

Can only be used if this is Vehicle

Vehicles may have a driver and/or a passenger. I therefore expected that I could use vehicle.set_driver() -- but not vehicle.set_passenger() -- if vehicle was based on a prototype where allow_passengers has been set to "false". Unfortunately, this doesn't work -- if allow_passengers is false, the vehicle may have neither driver nor player. I therefore suggest using the same explanation as for Prototype/Vehicle.allow_passengers:

Code: Select all

Determines whether this vehicle accepts passengers. This includes both drivers and gunners, if applicable.

[Honktown]

https://lua-api.factorio.com/1.1.83/Lua ... ning_speed

[code]
running_speed :: double? Read

The current movement speed of this character, including effects from exoskeletons, tiles, stickers and shooting.
Can only be used if this is Character
[/code]
This is a prototype. Surely the running_speed is the running_speed of the Prototype/Character?

-> Thanks for the note, description fixed for 1.1.110, see 114510.

[curiosity]

LuaGuiElement API has multiple string properties, which can only assume a value from a specific set. In the JSON docs these properties should have a union type of all allowed values instead of just string. Same goes for passing these properties to LuaGuiElement.add.

-> Changed it for the type of LuaGuiElement, if you have any specific things you want changed please let us know.

[_CodeGreen]

The "filled" parameter in Rendering.draw_rectangle is marked as required, but it is in fact optional and defaults to false.

-> Fixed. See 109201.

[curiosity]

https://lua-api.factorio.com/latest/Con ... #Alignment says that a single-word alignment implies middle vertical alignment when in reality the vertical alignment is top.

[Xorimuth]

https://lua-api.factorio.com/latest/Con ... enSettings I'd love an explanation of autoplace_settings, and how it differs to autoplace_controls. autoplace_settings seems empty most of the time

[Therenas]

Locking this thread because any future doc requests should get their own thread in this new subforum.

Any requests already posted in this thread will be looked at, so no need to repost those issues.