Documentation Improvement Requests

[curiosity]

https://lua-api.factorio.com/latest/Con ... apSettings - "aeging" - is this a typo in the docs or in the field name itself?

-> Typo indeed, thanks, fixed for 1.1.70.

[Honktown]

get active entities count is missing a single n on given:

Code: Select all

surface
:: SurfaceIdentification?

    If give, only the entities active on this surface are counted.

-> Indeed, thanks, fixed for 1.1.70.

[Honktown]

I had confusion over on_pre_player_mined_item vs on_player_mined_entity:
1.1.68:
[code]Called when the player finishes mining an entity, before the entity is removed from map.[/code]
vs
[code]Called after the results of an entity being mined are collected just before the entity is destroyed. After this event any items in the buffer will be transferred into the player as if they came from mining the entity.[/code]

An example someone gave was on_pre_player_mined_item raises even when the player can't hold the contents of the entity and the entity, which results in the entity continuing to exist (a chest or an assembler are the most obvious).

A possible change to on_pre_player_mined_item would be to describe it with:
[code]Called when a mining action is completed, even when a player does not have the inventory to empty and mine the entity.[/code]
It may not cover every case of "before the entity is removed from map" but I believe it conveys at least one example of "completed mining action, whether or not the entity was mined, too".

-> This one is kinda tricky to explain, I gave it a go for 1.1.70.

[Honktown]

math.random() could use a tiny bit more description.

A uniqueness of Factorio's math.random seems to be that Factorio will handle math.random(double, double) when either double has a decimal component, by flooring (flooring to the next representable double integer, I guess?).

Contrast with the 5.2 documentation, which does not describe using numbers containing decimals.

Two compilers for comparison, Lua 5.4.4 compiler and Lua 5.3.4 online compiler error on print(math.random(1.5, 5)) . The error is "number has no integer representation" with the only significant difference in the manual for 5.3: "(The value n-m cannot be negative and must fit in a Lua integer.)" 5.4.4 has more changes, but similarly does not describe decimal values.

-> This is a quirk that Factorio has in general. In many places that are looking for ints, the game also accepts doubles and just floors them. This is due to Lua 5.2 not having native integers and the game needing to deal with doubles anyways, in a way. I added a note to the docs for 1.1.70 though.

[Pi-C]

LuaEntity.selected_gun_index:

Code: Select all

selected_gun_index :: uint? [Read/Write] 
Index of the currently selected weapon slot of this character, car, or spidertron. nil if this entity doesn't have guns.

Can only be used if this is Character or Car

The last sentence should be changed to

Code: Select all

Can only be used if this is Character, Car, or Spidertron.

By the way, it just occurred to me that "spidertron" shouldn't be used at all in the descriptions: While "character" and "car" are names of specific prototypes, they also are the names for complete classes of prototypes (data.raw.car and data.raw.character). In contrast, "spidertron" is just a specific prototype from data.raw["spider-vehicle"].

-> I think in informal use (if something like that exists in technical documentation), calling it a spidertron instead of a spider-vehicle is fine. The sentence you propose to be changed is part of a system that is very inconsistent and crappy currently, so it won't be good until I get to a complete redo of it. Still, I went over a few properties on LuaEntity to make it more consistent for 1.1.70.

[BattleFluffy]

It would be nice if there was some better explanation about what the additional properties of an "artillery flare" are.

https://lua-api.factorio.com/latest/Lua ... ate_entity

For example here I create a flare:

Code: Select all

game.surfaces[1].create_entity{
	name = "artillery-flare",
	position = some.position,
	force = "enemy",
	movement = {0,0},
	height = 0,
	vertical_speed = 0,
	frame_speed = 1
}

It's a bit unclear what these last 4 things do. What's the "height" of the artillery flare for example? I took a guess at these values and it seems to work..

[Pi-C]

LuaControl.riding_state currently has this description:

[code]
riding_state :: RidingState [Read/Write]
Current riding state of this car or the vehicle this player is riding in.
[/code]

According to the Prototype definitions, spider-vehicles are vehicles. However, a function containing the line
[code]
local rs = vehicle.riding_state
[/code]
errored with
[code]
Target is not character, player or car.
[/code]
when it was called for a "spider-vehicle" prototype.

-> Good spot, RidingState does indeed only apply to Car prototypes, not SpiderVehicle or other vehicles. I amended the description to reflect this for 1.1.70.

[curiosity]

https://lua-api.factorio.com/latest/Con ... apSettings is said to be a table, when in fact it's a LuaObject. Possibly true for some other concepts as well, such as MapSettings.

-> This has been addressed for a future version.

[Honktown]

Could the "style" of LuaGuiElement.add{} have a little more explanation?
[code]
style
:: string?

Style of the child element.
[/code]
vs e.g.
[code]
style
:: string?

Name of a style prototype to apply to the new element.
[/code]

-> Sure thing, added for 1.1.70.

[raiguard]

LuaEntity::set_filter()'s second argument can be set to nil to clear the filter, but this is not explained in the documentation at all, and the type is just string.

LuaEntity::set_infinity_pipe_filter()'s argument can also be nil to clear it. This is stated in the documentation, but the intellisense type is just string.

-> Thanks, great hints. There are likely quite a few of these spread all over, since the ability to define a type as potentially nil is very new (as you likely know ). Fixed these and a couple other ones for 1.1.70.

[Pi-C]

It is not obvious how LuaEntity.stop_spider() is supposed to work.

Expected behavior: If a spider-vehicle is in motion, it will immediately stop once it has received the stop_spider() command.

Real behavior: The spider-vehicle won't stop as long as LuaEntity.autopilot_destination and LuaEntity.autopilot_destinations are set. When the position stored in autopilot_destination has been reached, the first position stored in autopilot_destinations will be removed, and the next position (if there is any) will be copied to LuaEntity.autopilot_destination. According to Klonan, LuaEntity.stop_spider() will stop all extra momentum/movement when a spider-vehicle has reached a waypoint, but it won't clear LuaEntity.autopilot_destinations.

-> Thanks, noted for 1.1.70.

[Pi-C]

Regarding the LuaVirtualSignalPrototype, what exactly constitues a special signal?

-> Great question. Everything, anything, each and unknown are considered special, which is noted for 1.1.70.
(Appreciate the comments explaining this, I removed them to keep this thread lean)

[Stringweasel]

[h]JSON Migration[/h]

When only the name of the entity is changed then the migrated entity will still have the original unit_number. However, when an entity's type is changed then the migrated entity will have a new unit number. Regardless of name or type change, any LuaEntity references stored in global will be invalid.

Proof - thanks to calciumwizard
Original

Changed only name. Unit number remains the same

Changed type. Unit number changes


-> Thanks for the details, noted for 1.1.70.

[BurninSun]

[1.1.69]
The following are documented as `optional = false` when they are in fact optional and can cause errors when accessed by some objects.
`LuaEquipmentPrototype.logistic_parameters` (only applies to RoboportEquipment)
`LuaEquipmentPrototype.movement_bonus` (only applies to MovementBonusEquipment)
`LuaGroup.order_in_recipe` (only applies to groups, not subgroups)
`LuaGroup.subgroups` (only applies to groups, not subgroups)

-> Thanks, addressed for 1.1.70.

[curiosity]

Please note that for control stage lifecycle a mod counts as present in the save only if it had control.lua. Details in Discord.

-> Interesting, noted for 1.1.71, thanks.

[Honktown]

set_infinity_inventory_filter Could probably use a little tweaking:

Code: Select all

 Can only be used if this is InfinityContainer 

Looks like the description was copy/pasted from set_infinity_container_filter on LuaEntity

Also, the InfinityInventoryFilter probably should have that the index is not required for writing a filter (the index is the first arg of the write function).

-> Thanks, both addressed for 1.1.71.

[Honktown]

LuaLogisticContainerControlBehavior.circuit_mode_of_operation doesn't mention it can only be used on chests with the logistic_mode = "requester", and results in an error even if one writes the value that can be read (0 in the case of unmodded Infinity Chests)

-> Thanks, noted for 1.1.71.

[BurninSun]

[1.1.69]
LuaPlayer.can_place_entity
[quote]Checks if this player can build the give entity at the given location on the surface the player is on.[/quote]
"give" should be "given"

-> Appreciated, fixed for 1.1.71.

[Honktown]

https://lua-api.factorio.com/1.1.69/Lua ... brightness

Code: Select all

min_brightness :: double [Read/Write]

The minimal brightness during the night. Default is 0.15. The value has an effect on the game simalution only, it doesn't have any effect on rendering.

Besides the typo simalution, this does seem to have an effect on rendering? Changing it from 0 to 1 around "midnight", daytime = .5 changes some brightness.

This also changes darkness, which implies enemy spawners might get affected (wiki prototype info):

Code: Select all

max_darkness_to_spawn	::	float (optional)
min_darkness_to_spawn	::	float (optional)

Edit:
Looks like the visual weights must be changed, too. Thanks Therenas for noticing.

Example:

Code: Select all

/c
local player = game.player
local surface = player.surface
surface.daytime = .5
surface.min_brightness = 0
surface.brightness_visual_weights = {.8, .8, .8}

-> Thanks, fixed for 1.1.75.

[Muppet9010]

LuaEntity.damage() says that the type and dealer are optional. However, if you actually provide nil to either of these you get an error. They are optional in the sense that you don't have to provide those arguments.

This means to provide a dealer argument value you have to provide a type argument value as well, you can't provide nil to leave it as game default.

https://lua-api.factorio.com/latest/Lua ... ity.damage

-> This is a tricky one, as there's no real other way to represent this in the docs. If you can actually write nil, the type will be 'TypeX or nil' (at least it should be). This should really be a method that takes a table instead, but that's not what it is. I'll add a text note to it though, for 1.1.71.