Small documentation improvement requests

[Honktown]

I'd like some rephrasing:
https://lua-api.factorio.com/1.1.59/Lua ... nnections

"The fluidbox connections for the given fluidbox index."
This, I expected to be similar to pipe_connections of the fluidbox prototype:
https://lua-api.factorio.com/latest/Lua ... onnections
"The pipe connection points."

However, get_connections has nothing about pipe connections returned, which makes the description confusing. I think for get_connections(index), a much better phrasing is: "The fluidbox(es) to which the fluidbox at this index is connected."

-> Thanks for the detailed report, fixed for the next release.

[Xorimuth]

I've been informed that most commands that raise events now state that (e.g. https://lua-api.factorio.com/latest/Lua ... ted_entity).

Here's a few that are missing this information:

on_player_driving_changed_state:
https://lua-api.factorio.com/latest/Lua ... ol.driving
https://lua-api.factorio.com/latest/Lua ... set_driver

on_player_cursor_stack_changed
I'd have thought this would be raised from any API commands that change the cursor e.g.
https://lua-api.factorio.com/latest/Lua ... ear_cursor
Maybe it doesn't raise immediately - I've not tested if it interrupts execution.

-> Thanks for the details, those three do indeed raise events, which is noted for the next release. The driving one fire immediately, the cursor one at the end of the tick, fyi.

[xfret]

In the documentation for the prototype Projectile (https://wiki.factorio.com/Prototype/Projectile), it states that the member "action" is of type Trigger. In the documentation for the type Trigger (https://wiki.factorio.com/Types/Trigger), it states that this type is an array of tables of type TriggerItem. In the prototype definition for "artillery-projectile", though, it appears to be a straight up TriggerItem itself ().

For the prototype definition for the Entity grenade, action seems to indeed be an array of tables of type TriggerItem (), so it appears it can be either. Should the doc be modified to reflect this or have I incorrectly inferred something?

-> Thank you for noticing this, Types/Trigger itself can either be one TriggerItem or an array of them. Noted!

[Honktown]

https://lua-api.factorio.com/1.1.59/Lua ... place_this
a tile prototype's item_to_place_this can be nil, vs an empty table. I'd appreciate that being mentioned.

Code: Select all

/c
for k,v in pairs(game.tile_prototypes) do
	local items_to_place_this = v.items_to_place_this
	if not items_to_place_this then
		game.print(k.." has no items_to_place_this")
		break
	end
end

-> Sure, added for the next release.

[Honktown]

https://lua-api.factorio.com/1.1.59/Lua ... properties
Two underscores are missing in a tile prototypes mineable_properties:

Code: Select all

miningtime :: double
miningparticle :: string?

The LuaEntityPrototype -> mineable_properties do have them

-> These have been broken for a looong time, thanks! Fixed for the next release.

[Honktown]

https://lua-api.factorio.com/1.1.59/Lua ... ate_entity
highlight-box has an inaccurate bit for bounding_box

The bounding box defining the highlight box using absolute map coordinates. If specified, the position parameter is ignored, but needs to be present anyways. If not specified, the game falls back to the source parameter first, then the target parameter second. One of these three parameters need to be specified.

"If specified, the position parameter is ignored, but needs to be present anyways." I read (present tense) this as: "position is not necessary if bounding_box is not provided"

Code: Select all

/c
local player = game.player
local surface = player.surface
surface.create_entity{
	name = "highlight-box",
	target = player.character,
	time_to_live = 600,
}

Cannot execute command. Error: position not specified.

Code: Select all

/c
local player = game.player
local surface = player.surface
surface.create_entity{
	name = "highlight-box",
	position = {0,0},
	target = player.character,
	time_to_live = 600,
}

Success.

It seems position is always needed?

-> I'm not quite sure how you misunderstood the wording, I find it to be quite clear. The position parameter is ignored, yes, so it's not 'necessary', but it still needs to be present, ie not nil else the function will error. It's bad API design I guess, but the wording says what's happening. Either way, I rephrased it a bit for the next release.

[Silari]

Documentation for the Technology prototype's unit property's count_formula needs a word removed. https://wiki.factorio.com/Prototype/Technology#unit

[quote]"Formula that specifies how many units are needed per level of the infinite technology."[/quote]

That implies it only works on infinite techs, but count formula works perfectly fine on any technology, including infinite, finitely leveled, or non-leveled (upgrade=false, ie the default). Non-leveled techs just use 1 for the level.

-> Thank you Honktown for changing the wiki.

[Honktown]

Documentation for the Technology prototype's unit property's count_formula needs a word removed. https://wiki.factorio.com/Prototype/Technology#unit

"Formula that specifies how many units are needed per level of the infinite technology."

That implies it only works on infinite techs, but count formula works perfectly fine on any technology, including infinite, finitely leveled, or non-leveled (upgrade=false, ie the default). Non-leveled techs just use 1 for the level.

Added information to the wiki. It will likely be reviewed and edited a little.

-> Thank you. No edits necessary

[Honktown]

https://lua-api.factorio.com/1.1.60/Lua ... ing_target

Writing nil is not supported. "Error: entity: table expected, got nil" I would get the impression it is (although the turret would probably immediately re-target that entity or another)

[RW]
Current description: "The shooting target for this turret or nil."

[lyvgbfh]

Prototype/ArtilleryWagon has a proper description for `.gun` but Prototype/ArtilleryTurret claims gun is an "item".

https://wiki.factorio.com/Prototype/ArtilleryWagon
https://wiki.factorio.com/Prototype/ArtilleryTurret

-> Thank you Honktown for changing the wiki.

[curiosity]

It should be noted in what units the various "emissions" runtime properties are. Pollution per second? Pollution per Joule? Something else entirely?

[Honktown]

Prototype/ArtilleryWagon has a proper description for `.gun` but Prototype/ArtilleryTurret claims gun is an "item".

https://wiki.factorio.com/Prototype/ArtilleryWagon
https://wiki.factorio.com/Prototype/ArtilleryTurret

Done ┐(´ー｀)┌

-> Thanks (☞ﾟヮﾟ)☞

[Honktown]

What's the default build_check_type of surface.can_place_entity? default direction should be filled in too, presumably defines.direction.north.

[Stringweasel]

IMO a note should be added to on_player_driving_changed_state.

This event is not raised when the vehicle is destroyed and the player consequently ejected.

It might be good to be explicit, because this is an undocumented recent change in the past few versions. See 102511 for reference.

[moon69]

LuaSurface.create_entity documentation doesn't have advice for "stream" type entities.

It appears to be the same requirements as type "beam", but it would be nice to be sure.

[moon69]

RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?

-> Thank you Honktown for adding this to the wiki.

[moon69]

Prototype/Animation.layers documentation was copy/pasta from Types/Animation.layers and doesn't really make sense here.

layers
Type: table of Animation
If this property is present, all Animation definitions have to be placed as entries in the array, and they will all be loaded from there. Each item (Animation definition) in the array may also have the layers property.
If this property is present, all other properties are ignored and the mandatory properties do not have to be defined.

Layers may not be an empty table.

Since the only mandatory properties for Prototype/Animation.layers are 'name' & 'type', this gives...

Code: Select all

data:extend({
  {
    layers =
    {
      {
        name = "test-animation",
        type = "animation",
        animation_speed = 0.5,
        ...

The mandatory properties 'name' & 'type' I assume must be at the same level as 'layers' and are not ignored?
I think it should be like this?

Code: Select all

data:extend({
  {
    name = "test-animation",
    type = "animation",
    layers =
    {
      {
        animation_speed = 0.5,
        ...

[Honktown]

RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?

Spawned children particles, to be clear? If you sign up for the wiki, you can make the edits yourself btw.

-> Thank you Honktown for adding this to the wiki.

[Honktown]

LuaForce.get_train_stops
The name parameter is the name of the stations, not the prototype. Please note.

[Pi-C]

I've been wondering why my selection tool would find car prototypes although selection_mode was set to {"entity-with-owner"}. Turns out there is a bug in the prototype descriptions.

According to Prototype/Vehicle, vehicle prototypes are Prototype/EntityWithOwner:
Prototype definitions » PrototypeBase » Prototype/Entity » Prototype/EntityWithHealth » Prototype/EntityWithOwner » Prototype/Vehicle

However, Prototype/EntityWithOwner is missing from the descriptions of Prototype/Car and Prototype/SpiderVehicle.


Also, according to Prototype/RollingStock, rolling stock is Prototype/EntityWithOwner as well. But Prototype/EntityWithOwner is missing from the description of Prototype/ArtilleryWagon, Prototype/CargoWagon, and Prototype/FluidWagon (the description is correct for Prototype/Locomotive).