Documentation Improvement Requests

[ILLISIS]

I has been some time since I last played with it but could more information be added to
https://lua-api.factorio.com/latest/Lua ... estination

As setting this to nil also clears https://lua-api.factorio.com/latest/Lua ... stinations

-> I added the info about writing nil to it. If there's any more information you feel is missing, please provide some more detail on that (in a new comment, otherwise I won't see it). Changed for 1.1.79.

[Honktown]

A small bit with settings (global variable) and writing settings, it upsets github's Lua Lint or something, as it's listed as read only? I don't know how to better describe it:

e.g. https://github.com/ILLISIS/Constructron ... 6429423111

Related, under the description of ModSetting:
https://lua-api.factorio.com/1.1.74/Con ... ModSetting

Code: Select all

Runtime settings can be changed through console commands and by the mod that owns the settings by writing a new table to the ModSetting.

"writing a new table to the ModSetting" is not right, in my opinion, as it sounds like writing a new table to itself, which is nonsensical, right? "writing a new table to the [containing table/parent settings type/setting name]" makes more sense.

-> So, two things: First, your remark about the wording being a bit off is a good point, I touched up the wording in a few places and added examples. Second, the linting issue is a bit weird, because these settings attributes aren't really writeable in the way most others are, where you can overwrite the whole property. You can only overwrite members of the LuaCustomTable, which is subtly different, and I don't think there's a good way to represent that in the current type system we have unfortunately. Changes will release with 1.1.79.

[Honktown]

https://lua-api.factorio.com/1.1.74/Lua ... quest_path

Code: Select all

path_resolution_modifier 	:: int?

Defines how coarse the pathfinder's grid is. Smaller values mean a coarser grid (negative numbers allowed). Allowed values are from -8 to 8. Defaults to 0.

A meaning to apply to this number would be useful. Working out a pathfinding problems with someone, a reasoned guess appears to be a "default path size" is one tile, and therefore, if negative is coarser, then 1 / (2^n) is the minimum tile size, or frequency of tile checks from start to finish? e.g. -2 means "use pieces 4x4 in size" or "only check 1/4 of tiles" or something else?

-> Thanks, I looked into this and added it for 1.1.79. Here's the new text so you don't need to wait for the release:

Code: Select all

Defines how coarse the pathfinder's grid is, where smaller values mean a coarser grid. Defaults to `0`, which equals a resolution of `1x1` tiles, centered on tile centers. Values range from `-8` to `8` inclusive, where each integer increment doubles/halves the resolution. So, a resolution of `-8` equals a grid of `256x256` tiles, and a resolution of `8` equals `1/256` of a tile.

[Honktown]

game.force_crc()

[code]Tells all peers to calculate their current map CRC;[/code]
Just the map, or, map and global?

-> Updated for 1.1.79.

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... .set_stack and similar don't say that they can raise on_player_cursor_stack_changed (and presumably on_player_main_inventory_changed, on_player_gun_inventory_changed, maybe more). From testing it appears that they aren't raised immediately though.

-> This is true, but I decided against listing these here since they are kind of secondary in a way, at least for the inventory ones. I don't think listing all of these everywhere is helpful. The raises information can never be complete anyways, since most actions can cause pretty much any event due to the reacting event being able to cause its own events and so on.

[Seth0x113]

Hey there, I am currently playing around with a mod idea/improving a mod that varies wind_speed for LuaSurface.

The runtime documentation for LuaSurface does state that it indicates the wind speed but it's unclear what/how it's represented. The current default value seems to be 0.02. That could be 2%, m/s or some other unit. I guess the current value is chosen for aesthetics and it's not hard to vary it but some more information about what's expected would be nice.

-> Should be tiles/tick, added for 1.1.79.

[BurninSun]

[1.1.76]
https://lua-api.factorio.com/latest/Data-Lifecycle.html
Some (but not all) of the highlighted `global` references link back to the API docs for global. No other highlighted references are linked and not all `global`s are linked.

eg.

The following sections about the individual steps presuppose an understanding of global.

Is linked.

The global table can be accessed and is safe to read from, but not write to, as doing so will lead to an error.

Is not linked.

All highlights should be linked where applicable.

-> Traditional style rules would dictate that links to the same destination are not repeated, and instead only done on the first occurrence of them. In this case however, the page is often read in small parts, and not in whole, so making all relevant places links is sensible. Thanks for bringing it up! Changed for 1.1.79.

[Honktown]

The documentation is wrong for connect_neighbour -> WireConnectionDefinition


[quote]wire :: defines.wire_type
Wire color, either defines.wire_type.red or defines.wire_type.green.
[/quote]
This is incorrect if the source entity is a power switch, and the target is to be connected by copper wire.


Run with a switch selected, then run with a nearby power pole selected, then run a third time:
[spoiler=console command]
[code]/c
if false then
a = nil
b = nil
do return end
end

if not (a and a.valid) then
a = game.player.selected
do return end
end

if not (b and b.valid) then
b = game.player.selected
do return end
end

game.print(a.connect_neighbour({
wire = defines.wire_type.copper,
target_entity = b,
source_wire_id = defines.wire_connection_id.power_switch_right
}))




[/code]
[/spoiler]

I was reading the latter part of the table, and it wouldn't make sense if only red or green were allowed definitions:
[quote]source_wire_id :: defines.wire_connection_id?

Mandatory if the source entity has more than one wire connection using copper wire.
target_wire_id :: defines.wire_connection_id?

Mandatory if the target entity has more than one wire connection using copper wire.
[/quote]

The copper type define also allows power pole to power pole (verifying that only a copper wire type and target work). If a source_wire_id of power_switch_right is used when the source is a pole, the connect_neighbour fails, as opposed to being an error. Not sure if it should be an error or not, but it does fail.

-> Good find, appreciate the very detailed report! Fixed for 1.1.79.

[Honktown]

https://lua-api.factorio.com/1.1.76/eve ... ck_changed

I believe there's some minor typo/grammar issues:

Called after a players cursorstack changed in some way.

vs

Called after a player's cursor stack changed in some way.

-> Yup, fixed for 1.1.79.

[curiosity]

https://wiki.factorio.com/Prototype/RocketSilo#idle_energy_usage - does this do anything at all?

-> It does not. Documented in the new prototype docs.

[Xorimuth]

https://lua-api.factorio.com/latest/Con ... ventFilter makes no sense. Presumably it allows me to filter the name of the radar that did the scan, but most of the wording and listed things seem completely irrelevant.

-> Yup you're right. Unfortunately, the internal system to document filters is quite inflexible, and I can't really fix this at the moment. It's on the list to improve this situation though.

[Pi-C]

The description of LuaBootstrap::raise_event is still missing the new (as of version 1.1.77) script_raised_teleported event in the list of events that can be raised.

-> Thanks, fixed for 1.1.79.

[curiosity]

Assigning to LuaEntity.entity_label does nothing if (presumably) it's not a spidertron. Alternatively, consider that it doesn't error a bug.

-> I feel like it was already pretty clear that it doesn't do anything for non-spider-entities, but I clarified a bit for 1.1.79.

[Pi-C]

Assigning to LuaEntity.entity_label does nothing if (presumably) it's not a spidertron. Alternatively, consider that it doesn't error a bug.

There's also a typo in that description:

Code: Select all

The label on this entity, if any. nil if this is not a spider-vehicule.

It should be "spider-vehicle", not "spider-vehicule"!

-> This has been fixed, thanks. I blame the mistake on too much exposure to French.

[BurninSun]

[1.1.77]
https://lua-api.factorio.com/latest/Lua ... et_all_ids
https://lua-api.factorio.com/latest/Lua ... ring.clear
Both need clarification that passing "" as a parameter to mean "level" as per
viewtopic.php?f=65&t=87608

This is how these functions access rendering objects created in the console.

-> Thanks for the details, added for 1.1.79.

[Honktown]

tile-ghost is missing from LuaSurface.create_entity [1.1.78]

[Sharparam]

The documentation for LuaConstantCombinatorControlBehavior.set_signal says that the second parameter (signal) cannot be nil, but passing nil is valid (seemingly, it works in-game, version 1.1.76) to clear the signal.

-> Thanks, noted for 1.1.79.

[curiosity]

LuaEntityPrototype.items_to_place_this/LuaTilePrototype.items_to_place_this says it's an array of SimpleItemStack. Is it supposed to be ItemStackDefinition or can the stacks be strings and when?

-> It's indeed ItemStackDefinition, thanks. Fixed for 1.1.79.

[_CodeGreen]

LuaBootstrap.on_event() is missing array[string] from the event parameter.

-> Thanks, fixed for 1.1.90.

[lyvgbfh]

LocalisedString docs could use a section covering the usage of "?" - starting point for the body of that could be here

-> The runtime docs already explain this since a recent release.

<- Thanks, I was checking the wiki (https://wiki.factorio.com/Types/LocalisedString) since I was working in data stage.

-> Ah, I guess that can be updated as well, thanks.

-> Wiki and prototype docs have been updated.