Documentation Improvement Requests

[kubel34]

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

-> Thanks, fixed for the next release.

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

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]

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]

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.

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

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]

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]

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]

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.

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

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.

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

LuaItemStack.set_stack should say why it can fail.

-> Improved, thanks.

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

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.

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

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]

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.

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