Small documentation improvement requests

[snouz]

I found some errors in: https://wiki.factorio.com/Types/IconData

According to my tests, the default scale seems to be 0.5 for recipe icons. When you force a scale of 1, they'll appear twice as big on the alt mode. I haven't checked 32px icons, since all vanillas are 64. I can make a test if needed.

Also, it could be made clearer that the shift of subsequent icons in "icons" is (I believe) based on (scale * size) of the first icon in "icons". For default icons, that is (0.5 * 64) so 32 (but if your first icon is scale 1 size 64, shift of every icon is based on 64)

Also, I believe the default tint isn't {r=0, g=0, b=0, a=1}, as this is completely opaque black (as confirmed by my tests). It's apparently the opposite, {r=1, g=1, b=1, a=0}.

It could also be made clear that the shadow behind the icons is drawn based on the shape of the FIRST icon in icons (as tested by my script which originally used a transparent image as a first layer, and thus there would be no shadow at all in the menu or on entities)

ctrl maj f on an icon I created, with no defined scale or tint:


EDIT: got a wiki account, ran some tests and made the IconData page more precise.

[curiosity]

IDK where, but this should be documented:

orders are optional
A nil turns into "" somewhere?

you are right, they are optional
which means if you provide a nil, on the c++ side they will be loaded with some default
which for orderString is an empty string (with some exceptions for TipsAndTricksItem and TutorialDefinition where the name is used as a default instead)

Source: https://discord.com/channels/1396775903 ... 2785441842

-> Documented at https://wiki.factorio.com/PrototypeBase#order. Differing defaults given by boskid aren't documented since the game falls back to names for comparison anyway. However, there is another differing default at https://wiki.factorio.com/Prototype/Nam ... Expression (documented)

[Honktown]

Its the deviation of the angle, in orientation units (0 - 1)

so setting it to 1 or above means basically 360 degree random spread (+/- 0.5 orientation aka +/- 180 degrees)

For instance the shotgun has a deviation of 0.3, so +-/0.15 orientation either direction from the origin orientation

It's +/- radians / 2, actually. Edit: I added information to the wiki.

Embedded images:

Examples

This is what 2 looks like, aka +/- ~57 degrees:

deviation_2.jpg (354.83 KiB) Viewed 2581 times

3.14, +/- 90 degrees:

deviation_3.14.jpg (387.79 KiB) Viewed 2581 times

and 6.28, aka weeeeeeee:

deviation_6.28.jpg (472.94 KiB) Viewed 2581 times

[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 2568 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 2568 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)