Documentation Improvement Requests

[Honktown]

https://wiki.factorio.com/Prototype/MiningDrill#storage_slots

Does this still do anything?

[code]data.raw.resource["iron-ore"].minable.results = {
{type = "item", name = "iron-ore", amount = 10},
{type = "item", name = "copper-ore", amount = 10},
}
data.raw["mining-drill"]["electric-mining-drill"].storage_slots = 1[/code]

https://wiki.factorio.com/Version_history/0.11.0#0.11.21

Storage slots of mining drill is moddable now. This affects the internal inventory size, so when resource with more different results is mined, no items are lost (as long as the size is big enough). Default value is 1.

storage 1

ores.jpg (246.67 KiB) Viewed 6421 times

It does appear to have some weird effect when not 1? I didn't understand it. Maybe it's what the original description is referring to, that an item result outputs each first, one item per slot... but newer behavior still outputs the rest?

storage 200

inventories.jpg (298.76 KiB) Viewed 6421 times

Edit: in the second image, the burner drill was not changed and the electric drill was changed to 200 slots .

-> Doesn't do that much anymore. With 1.1.37, the storage_slots property will be removed from the prototype and the inventory size of the mining drill will be calculated automatically by the game. More info + discussion in 99379

[Silari]

on_force_created should have a note that it is not fired for the default forces, same as the note on_surface_created has about not being fired for the default surface.

Related: viewtopic.php?p=549998

-> Good idea, thanks, added for the next release.

[JohnTheCF]

I've been reading Types/SpriteFlags documentation and noticed that "terrain-effect-map" description says that it also sets "group=terrain-effect-map", but this flag is not documented on this page.
-> The flag is internal only, this is now documented.

[Honktown]

It may be worth mentioning dictionary and array on https://lua-api.factorio.com/latest/Builtin-Types.html

e.g.:
1) They are implied types, whose behavior is defined by Factorio functions and Lua behavior.
2) An array is a table only with keys from 1-N. A dictionary is indexed by any key.
3) an array[type] = values of type which are indexed from 1-N if present

They're used in the API, but Idk if there's any page with what they're supposed mean/how they should be read (like the other Builtin Types)

Edit: I see https://lua-api.factorio.com/latest/Concepts.html has a lot of the tables... though not a meaning of array/dictionary

-> After some pondering, I've expanded the builtin types description at the top to explain what is meant by array and dictionary, and also bring up why types like uint64 are in that list at all. I didn't make array and dictionary into full builtin types though, since they are not actually like the others, in that they are not really a type that can be used on its own, it only specifies the format of other types, if you will. Thanks for the suggestion, improved for the next release.
(Also, thanks for the comments everyone else, I removed them to keep the thread as uncluttered as possible, but they are definitely appreciated)

[Deadlock989]

Re: https://wiki.factorio.com/Prototype/Turret

1. What are the units of attacking_speed, folding_speed etc.? They advance the animation state of the turret, that much is clear, but what's the relationship between animation frame and the float value?

2. What is folded_speed? It's the speed at which the folded animation advances if there are multiple frames per direction. Still don't know the units, my first guess was frames/tick but that doesn't add up.

-> Basically, x_animation_duration = 1 / x_speed. Documented as such.

[eradicator]

EntityPrototypeFilter types are largely undescribed. What is the difference between "buildable" and "building" and "blueprintable"? What internal checks do they actually do?

-> It seems the technical backend doesn't allow for these to have any descriptions attached to them, so I can't really add explanations for these. I added this to the backlog though to be fixed in the future.

[eradicator]

LuaEntityPrototype.logistic_mode would benefit from a list of possible values. I.e. to know if it's "request" or "requester" etc, and especially the "none" value for non-logistic infinity containers.

-> Sure. Added for the next release.

[Hornwitser]

A lot of events are described as "called when x happens", but it's really unclear what this means in isolation. For example the on_player_removed event is described as:

"Called when a player is removed (deleted) from the game. [...]"

Does this mean it's before the player is removed from the game state, some indeterminate game state during the player removal, or after the player is removed from the game state? I think it would help clarify a lot of events if they where more specific with when they are invoked in relation to the game state that the Lua code can observe. For example the on_pre_player_removed event says it's "Called before a player is removed" which makes it clear that game.get_player(event.player_index) is valid during the event handler.

[SpaceCat-Chan]

the wiki says that icon tint defaults to {r: 0, g: 0, b: 0, a: 1} here

but after some testing this seems to be false, the actual default seems to be {r: 1, g: 1, b: 1, a: 1}

example:
the bottom layer of barrels have no tint, so the stated default would just make it completely black, but the bottom layer of barrels are not black

-> Wiki was edited by Honktown

[Honktown]

the wiki says that icon tint defaults to {r: 0, g: 0, b: 0, a: 1} here

but after some testing this seems to be false, the actual default seems to be {r: 1, g: 1, b: 1, a: 1}

example:
the bottom layer of barrels have no tint, so the stated default would just make it completely black, but the bottom layer of barrels are not black

I made some edits which are a) more accurate and b) hopefully clearer:
https://wiki.factorio.com/Types/IconData#tint
https://wiki.factorio.com/Types/Color

1) Default values when color/tint is nil is different than default values when table is present and 2) the alpha channel at 1 indicates full opacity, not full transparency

[curiosity]

https://lua-api.factorio.com/latest/Con ... TileResult - it's unclear what kind if table we may expect in condition. Also no info about condition_size.

-> Addressed for the next release

[Honktown]

Speaking of small requests:
LuaFluidPrototype fuel_value

It's always >= 0, and is in Joules. There's nothing surprising about the values and their meaning if one reads the wiki (the wiki lists 0J as the default, for example, though it results in no tooltip value and fluid isn't burnable...). Since there's no description, one might expect a nil value for the default, with nil meaning the fluid isn't burnable, which is not the case.

There are some other values in LuaFluidPrototype that could use any description.

-> Thanks for the hint, I gave that whole page a bit of an overhaul for the next release.

[PFQNiet]

Belt speed wording is a little awkward, but notably it implies that any number will work. This is not the case.

Belts internally have 256 positions, and items on a belt must move an integer number of positions per tick, the speed value must be a multiple of 1/256. Well, it can be other things, but it will be rounded down. It would be nice to have that clarified.

-> Thank you for pointing this out, documented.

[eradicator]

Prototype/Entity#additional_pastable_entities does not specify if it takes an array of prototype.name or prototype.type (by trial an error it is - counterintuitively - name).

-> Thanks, fixed and example added.

[curiosity]

Someone was confused the other day about what nil means in https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.render_to_forces. Is it render to all or render to none?

-> Thanks to you (and Eradicator), I have clarified this for the next release. If it's nil (and in the case of forces, an empty array too), it'll render for everyone.

[JohnTheCF]

OffshorePump prototype documentation (https://wiki.factorio.com/Prototype/OffshorePump) mentions remove_on_tile_collision twice in Optional properties section.
-> Thanks, fixed.

[curiosity]

https://lua-api.factorio.com/latest/Concepts.html#SoundType is sorely missing any details about what is special or different about all these types. No info on the wiki either (https://wiki.factorio.com/Prototype/Sound#category).

-> Info added on the wiki (and in the runtime docs for the next release)

[curiosity]

https://lua-api.factorio.com/latest/Concepts.html#TrainScheduleRecord doesn't say that wait_conditions can be nil.

-> Thanks, fixed for the next release.

[eradicator]

https://lua-api.factorio.com/latest/Data-Lifecycle.html
https://lua-api.factorio.com/latest/Libraries.html

It would be nice if these two pages (are there more?) had internal links (#) to each of the headlines/sections to make them directly linkable in discussions, tutorials and documentations. It's clunky to have to write instructions like:

Data-Lifecycle and then scroll down to section 4.

-> This is/will be part of the new API website. There's currently no way to get the actual links from the page, but they do work, ie. https://lua-api.factorio.com/next/Data- ... ialization. Anchors on the page itself will be added in the future. Good suggestion, thanks for bringing it up!

[Zetabite]

For https://lua-api.factorio.com/latest/Con ... enSettings or similar, add specification on limits for map size. Maybe even an entry on https://lua-api.factorio.com/latest/Bui ... .html#uint describing the exception if there is one.

-> The actual limitation is a million tiles in each direction (as noted on the wiki), which I added to the MapGenSettings concept for the next release.