Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
Locked
curiosity
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.get_output_inventory wrote:Gets the entities output inventory if it has one.
entity's

-> Thanks, fixed.

hackamod
Long Handed Inserter
Long Handed Inserter
Posts: 62
Joined: Mon Apr 25, 2022 2:39 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Inserter
Inserter
Posts: 40
Joined: Sat Dec 14, 2019 3:26 am
Contact:

Re: Small documentation improvement requests

Post by -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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

curiosity
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

Honktown wrote:
Mon May 09, 2022 9:54 am
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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

Xorimuth
Filter Inserter
Filter Inserter
Posts: 623
Joined: Sat Mar 02, 2019 9:39 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
My mods
Content: Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Remote Configuration | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

xfret
Burner Inserter
Burner Inserter
Posts: 12
Joined: Sun Apr 11, 2021 10:40 am
Contact:

Re: Small documentation improvement requests

Post by 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 (Image).

For the prototype definition for the Entity grenade, action seems to indeed be an array of tables of type TriggerItem (Image), 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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
Attachments
no_items_to_place_this.jpg
no_items_to_place_this.jpg (92.12 KiB) Viewed 3851 times
I have mods! I guess!
Link

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

User avatar
Silari
Filter Inserter
Filter Inserter
Posts: 488
Joined: Sat Jan 27, 2018 10:04 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

Silari wrote:
Sun Jun 05, 2022 9:15 pm
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 :)
I have mods! I guess!
Link

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

lyvgbfh
Fast Inserter
Fast Inserter
Posts: 165
Joined: Fri Jul 10, 2020 6:48 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
Last edited by curiosity on Sun Jun 12, 2022 3:02 pm, edited 1 time in total.

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

lyvgbfh wrote:
Tue Jun 07, 2022 10:17 am
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 (☞゚ヮ゚)☞
I have mods! I guess!
Link

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

User avatar
Stringweasel
Filter Inserter
Filter Inserter
Posts: 310
Joined: Thu Apr 27, 2017 8:22 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
Alt-F4 Author | Factorio Modder
Mods: Hall of Fame | Better Victory Screen | Fluidic Power | Biter Power | Space Spidertron | Spidertron Dock | Weasel's Demolition Derby

Locked

Return to “Documentation Improvement Requests”