Documentation Improvement Requests

[curiosity]

Gets the entities output inventory if it has one.

entity's

-> Thanks, fixed.

[hackamod]

https://wiki.factorio.com/Tutorial:Loca ... ile_format

There was no mention of comments in the file here.
-- does not work, and I assumed it did, then I waited for a reply in a bug report.
# or ; seems to be the answer for a comment here and might save the next person some time.

-> Thanks for pointing this out, I added the comment characters to the example.

[-DeadlyKitten]

request to add information to https://wiki.factorio.com/Tutorial:Localisation about how to make a multi line description (\n turns into a newline character)
and how to create/change it programmatically (i dont know this but know it is posible)

-> Added the note on \n, programmatic creation (as in, creation with parameters) should already be covered by the page.

[Honktown]

If an empty players table passed to LuaRendering draw functions means "everyone" not "nobody". It'd be convenient if that were noted somewhere.

-> I noted this on all draw methods for both the players and forces parameters.

[curiosity]

If an empty players table passed to LuaRendering draw functions means "everyone" not "nobody". It'd be convenient if that were noted somewhere.

It is, though maybe not where you'd expect: LuaRendering.set_players.

[Honktown]

Clarity on LuaEntity secondary_selection_box is desired:
1) when does this apply?
2) there's no prototype definition for secondary selection box in a Prototype/Entity
3) it's not in the LuaEntityPrototype
4) is it entity-biased like LuaEntity.selection_box, or is it in un-adjusted dimensions?

-> This one only applies to curved rails. Since it's determined automatically, it's not a property of the prototype. I noted this for the next release, thanks.

[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."

-> Thanks, fixed for 1.1.70.

[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?

-> After looking into it, it's indeed pollution/Joule. Multiplying it with power consumption in Watt gives you the pollution/second. Thanks, added this for 1.1.70.

[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.

-> Appreciate the hint, I added defaults to that method and closely related ones. It defaults to ghost_revive, and default directions are (almost?) always North indeed. Also, I fixed the mistake that the default force was noted as enemy, when it really is the neutral force. Fixed for 1.1.70.

[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.

-> Sure thing weasel, appreciate the hint! Changed for 1.1.70.