Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
Locked
kubel34
Burner Inserter
Burner Inserter
Posts: 6
Joined: Mon Aug 26, 2019 5:48 pm
Contact:

Re: Small documentation improvement requests

Post by kubel34 »

LuaEntity::is_crafting is missing a return value, which should be a boolean.

-> Thanks, fixed for the next release.

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

Re: Small documentation improvement requests

Post by curiosity »

Speaking of LuaEntity::is_crafting, the description is unclear. What is the difference between "progress being made" and "crafting action made progress"? Are you trying to say that it returns whether the machine is in the process of crafting something? Something else?

-> It's that a 'craft' has been started beforehand (like kubel said below). I tried to clarify the wording a bit for the next release.

kubel34
Burner Inserter
Burner Inserter
Posts: 6
Joined: Mon Aug 26, 2019 5:48 pm
Contact:

Re: Small documentation improvement requests

Post by kubel34 »

I suppose that when a crafting machine starts crafting (enough ingredients + has power), is_crafting is true and stays true until the operation is completed.
"progress is currently being made" when there is power, and if there is not then the machine is not making progress but is still crafting.
I think that it is simply equivalent to: [code]is_crafting = progress > 0[/code]

-> Yep that's it.

I spotted another mistake: LuaControl::is_flashlight_enabled() is also missing a return value.

-> Thanks, fixed for the next release.

ILLISIS
Inserter
Inserter
Posts: 22
Joined: Wed Feb 09, 2022 10:49 am
Contact:

Re: Small documentation improvement requests

Post by ILLISIS »

https://lua-api.factorio.com/latest/eve ... _destroyed

Note
Depending on when a given entity is destroyed, this event will be fired at the end of the current tick or


The sentence ends at or[/strike]

-> Fixed for the next release, thanks.

Pi-C
Smart Inserter
Smart Inserter
Posts: 1716
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

LuaEntity.last_user:
last_user :: LuaPlayer [Read/Write]

I've accidentally set player.last_user to a Boolean value and got this error:

Code: Select all

Expected LuaPlayer, index, or name.

So the description should actually read
last_user :: LuaPlayer or PlayerIdentification [Read/Write]

Notes
PlayerIdentification can be used when writing to this value, but reading it will always return LuaPlayer.

I suppose the same applies to other R/W properties that return LuaPlayer on reading, namely LuaEntity.associated_player and LuaEntity.render_player.


-> Thanks, I noted this on all three properties. Long-term, the better solution is to allow separate read and write types in the documentation for cases like this, but that's not a thing just yet.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Nexela
Smart Inserter
Smart Inserter
Posts: 1828
Joined: Wed May 25, 2016 11:09 am
Contact:

Re: Small documentation improvement requests

Post by Nexela »

Surface.create_entity{target =, source =}

MapPosition is missing as an optional for target and source both takes either LuaEntity(with health for target) or MapPosition


-> You're right, thanks, fixed for the next release.

curiosity
Filter Inserter
Filter Inserter
Posts: 433
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.is_connected_to_electric_network - the description is incomplete. Seems to mean if the entity is connected to a network capable of producing power, the exact opposite of the entity having a blinking electric plug icon over it. But always false for some entities, like power poles, regardless of the network.

->Thanks, I clarified this for the next release.

Saiph300
Burner Inserter
Burner Inserter
Posts: 6
Joined: Tue Aug 14, 2018 5:20 pm
Contact:

Re: Small documentation improvement requests

Post by Saiph300 »

Hi, I'd like to ask some info about the field 'track_type' in https://wiki.factorio.com/Prototype/AmbientSound
This lets the game know in what instances the audio file is played. Possible values:
"early-game"
"main-track"
"interlude"
"late-game"
"menu-track"
I think this description already makes a bit of sense, but can you detail:
1) what is the difference between "interlude" and "main-track"
2) when are "early-game" and "late-game" triggered?


-> 1) I added to the page. 2) is at the same time as main-track, they have no special meaning. Also added to the page. Thank you for pointing out that information was missing here.

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

Re: Small documentation improvement requests

Post by curiosity »

Prototype/Turret#attack_parameters - the description is wrong. The vanilla gun turret exists without ammo_type, so obviously it's not required. You may want to say that specific turret subtypes require some parent fields to be a certain way, though IDK how you would present that.
-> Thanks, fixed.

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

Re: Small documentation improvement requests

Post by Xorimuth »

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

LuaHorizontalFlow should be LuaHorizontalFlowStyle?

Also why can't this be used on a frame :(



-> It should be, thanks, fixed for the next release. As for your question, that's how it works unfortunately, you can make an interface request if you want a proper answer, otherwise I can recommend adding a flow to the frame that you then set this property on.
My mods
Content: Lunar Landings | Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

User avatar
JohnTheCF
Inserter
Inserter
Posts: 26
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by JohnTheCF »

A recent edit (https://wiki.factorio.com/index.php?tit ... did=188205) added a "Can't be negative" note to a field/protperty that has a type of unsigned integer. Because unsigned integers can't be negative, I think that this note is redundant here and just specifying the type is enough.
-> Honktown reverted the edit, thank you. Reverting the edit yourself is usually faster than waiting on me to get to it, so I would recommend doing that instead of posting here (like Honktown did, thank you again).

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

Re: Small documentation improvement requests

Post by Xorimuth »

https://lua-api.factorio.com/latest/Lua ... istic_slot
"spider-vehicules" is spelt wrong and the 's' looks weird.
Should the same caveat be on get_vehicle_logistic_slot?

https://lua-api.factorio.com/latest/Lua ... _activated
typo in description: actived -> activated


-> Yes to all, thank you, fixed for the next release.
My mods
Content: Lunar Landings | Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

User avatar
jimmyhunter
Burner Inserter
Burner Inserter
Posts: 5
Joined: Mon Feb 21, 2022 9:06 pm
Contact:

Re: Small documentation improvement requests

Post by jimmyhunter »

hey hello
i am creating a prototype unit and i am stumbling on this prototype:

https://wiki.factorio.com/Types/BaseAttackParameters

all good and well but now i have defined almost everything except for this:

https://wiki.factorio.com/Types/CyclicSound

what exactly does this refer to?
the begin and end sound might be understandable but i would give more context than it currently has.
i have no clue when the middle sound should be defined as or how i should interpreted it as a sound at all really

in short: explain begin_sound and end_sound and give additional clarification on middle_sound

thank you, sincerely
Jimmy.

-> I added extra descriptions to the sounds in BaseAttackParameters and also in CyclicSounds, I hope it helps :)

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

Re: Small documentation improvement requests

Post by curiosity »

LuaItemStack.set_stack should say why it can fail.

-> Improved, thanks.

User avatar
JohnTheCF
Inserter
Inserter
Posts: 26
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Types/Sound#variations
variations, max_speed property description says that max_speed is mandatory if max_speed is present. Probably min_speed was meant there.

-> Thank you for finding this, fixed.

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

Re: Small documentation improvement requests

Post by curiosity »

Types/StyleSpecification#effect need description, or at the very least a list of possible values.
-> The list of possible values is hardcoded to one value, severely limiting its usefulness. But it's documented now, thank you for pointing it out.

User avatar
JohnTheCF
Inserter
Inserter
Posts: 26
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Types/RadiusV ... cification
default value for distance is 0, but it also says that it shoukd be grater than 0

-> Should be greater or equal. Thanks for noticing it, I fixed the doc.

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

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/LuaItemPrototype.html#LuaItemPrototype.module_effects wrote: Effects of this module; nil if this is not a module.
Can only be used if this is ModuleItem
So can it or can it not be used on other items?

-> Thanks, I decided to remove the redundant description text.

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

Re: Small documentation improvement requests

Post by Xorimuth »

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

This returns nil when the prototype's item_slot_count is set to 0. This should either be specified (at least with a question mark) or changed to return an empty table.


-> Good spot, thanks, fixed for the next release.
My mods
Content: Lunar Landings | Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

Pi-C
Smart Inserter
Smart Inserter
Posts: 1716
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

About LocalisedString:
concept LocalisedString

Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number or boolean, which will be converted to their textual representation.

I've set [code]LuaGuiElement.tooltip = nil[/code] expecting to see no tooltip at all, but instead, "nil" was displayed. If that is the correct behavior, the explanation should include nil along with "number or boolean":

Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number, a boolean or nil, which will be converted to their textual representation.

Otherwise, there should be a note that this applies at least in some cases:
Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number or boolean, which will be converted to their textual representation.

Note: In some cases (e.g. for LuaGuiElement.tooltip), nil will also be converted to its textual representation.
-> The localised string parser explicitly converts a nil value to the string "nil", which I've noted in the docs for the next release.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Locked

Return to “Documentation Improvement Requests”