Documentation Improvement Requests

[Bilka]

Locking this thread because any future doc requests should get their own thread in this new subforum.

Any requests already posted in this thread will be looked at, so no need to repost those issues.

Did you just run into a prototype property that was called pizza_type but didn't seem to do anything with pizzas at all and didn't have a description to tell you what it really does? Did you try to use a complicated method in the control stage but couldn't figure out how the format the doc describes should look like and there wasn't any example? We want to fix that :D

We are looking for properties/methods that are missing descriptions or could use examples in both the prototype docs and the runtime docs. We would like to prioritize our documentation efforts by what mod authors specifically run into or have problems with due to missing explanations/examples. Please post your requests in this thread.

Examples of the kind of requests we're looking for: 88004 89845

Examples of a recent improvement that we would like to repeat for other properties/methods: Added examples for LuaCommandProcessor.add_command and Types/LineTriggerItem

Please do not just say "most things in the prototype docs", we know and we'd like to prioritize working what you run into, instead of going alphabetically.

[Honktown]

A small request, the list of Attack Parameters is not complete nor exhaustive: https://lua-api.factorio.com/latest/Con ... Parameters

Something like "examples of values" would've been sufficient to prevent confusion I encountered (when looking for a value). In other words, the table contains a lot more attack-related stuff, not only those things.

-> Updated for the next release

[eradicator]

Today I was told that force_visibility can also affect the selectibilty of a SEWO. -> Added at SimpleEntityWithOwner#force_visibility

[DedlySpyder]

Took a look through my bug reports, which were normally because something was unclear to me:

• [*]LuaEntity.destroy() Returns True on Invalid Entity - Rseding told me this only returns false if it failed to destroy a valid entity.
  [*]LuaSurface.find_non_colliding_position() Infinite Loop 0 Radius - This occurs when the chunks weren't generated. A hint to generate the chunks first would have been helpful.
  [*]That weird multiplayer save, but single player thing that happens. I'm still not entirely sure of how, but when you take a multiplayer game and just play it locally it's still kind of a multiplayer game. Specifically it will still fire on_player_joined_game but not on_player_left_game.
  [*]Ghost Lost in Migration When Changing Entity Type - It's just not supported, but I don't believe it's noted anywhere
  [*]Entity placeable_by Hidden Dependency on Item's Order - Placeable_by just adds the item to the items_to_place_this array, which is then sorted by order, so the lowest sort is always the winner here for blueprints. Whereas primary-place-result on the item places it at the beginning of the array.

-> All of these have been dealt with, changes to the API docs will appear with the next release.

[curiosity]

Explain what exactly "stretch_and_expand" means for horizontally/vertically stretchable/squashable (especially squashable) in Types/StyleSpecification. -> Added at https://wiki.factorio.com/Types/StretchRule

[curiosity]

The hidden tile is only updated if the tile put on top is minable, such as concrete, stone path, etc.

This should be added to LuaTile.hidden_tile (which is also missing description), LuaSurface.set_tiles and Prototype/Tile#minable.

Alternative phrasing: "The old tile becomes hidden if it is not minable and the new tile is."

-> Improved for the next release

[eradicator]

Regarding LuaForce.set/get_friend (and probably LuaForce.set/get_cease_fire) they have no effect on the neutral force. Which would've saved me a bunch of time had I known :D.

[quote=Klonan post_id=544124 time=1618868332 user_id=5544]
Neutral force is hardcoded to always return true for 'is_friend' checks, this isn't a bug
[/quote]

(Note from Therenas: The correction of this is waiting on the related bug being fixed)

(Note from eradicator: Klonan has decided that he doesn't want to fix it for unclear reasons. So I'd want at least documentation of every hidden hardcoded effect on both set/get_cease_fire and set/get_friend for all directions. I.e. is PlayerForce.get_friend(NeutralForce) always true too? Or is it just NeutralForce.get_friend(PlayerForce) that's always treated as true even though the API lies about it?)

(Note 2 from eradicator: So Klonan said he's going to think about it some more.)

[Xorimuth]

Entity#remove_decoratives what does "automatic" mean? Presumably it depends on the subentity? I'm particularly interested in type "car". -> Correct, documented. Cars aren't considered buildings (= no removal).

[curiosity]

It is worth noting in https://lua-api.factorio.com/latest/LuaGuiElement.html that a list box has a built-in scroll pane and a scroll pane has a built-in vertical flow. -> Improved for the next release

[Pi-C]

amount_min and amount_max

Type: Types/uint16

Mandatory if amount is not specified and named keys are being used.

When using named keys, either amount or (amount_min and amount_max) must be set. But what happens if all are used? -> amount taking precedence noted on FluidProductPrototype and ItemProductPrototype

Moderator note: Discussion of this post was split into a separate topic: 98070

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... Entity.die it seems that 'force' should be 'optional'.

-> Fixed and added example for the next release

[Xorimuth]

I'd appreciate some explanation of HighlightBoxEntity please.
https://wiki.factorio.com/Prototype/HighlightBoxEntity

Overall, when would you use this? The following are the questions that I had as I read through it and tried it out, but from experimenting it seems that it is only used to display the highlight box permanently. Given that, is the description "Used to attach graphics to entities during runtime." really true? It seems that it is a lot more specific (and less useful) than that.

Does setting `bounding_box` in the data do anything? -> Added on https://wiki.factorio.com/Prototype/HighlightBoxEntity

In https://lua-api.factorio.com/latest/Lua ... ate_entity, according to the game, it must have either `target`, `source`, or `bounding_box` set, but it says that `source` is only used for 'beams'...? (It might be useful to expand on when you'd want to use `target` as well).

In the `highlight-box` specific arguments for `surface.create_entity`:
It would be useful if it stated that `bounding_box` is absolute coordinates, not relative coordinates like they are in entity data definitions.
It seems that `position` is ignored when using `bounding_box` but it has to be set anyway.
What are the meanings of `box_type` (https://lua-api.factorio.com/latest/Con ... RenderType). When would you use each? Are there any examples of usage of those already in the game? EDIT it seems that they just set different colours.
Less important it could state that time_to_live and blink_interval are in ticks (presumably... I've not tested yet).

-> Fixed for the next release (finally!)

[ickputzdirwech]

I am assuming that the items in https://lua-api.factorio.com/latest/events.html#on_player_cancelled_crafting are basically the same as in https://lua-api.factorio.com/latest/events.html#on_pre_player_crafted_item. Could still use some clarification imo.

-> Improved for the next release.

[curiosity]

The docs claim that LuaFlowStatistics.input_counts and output_counts are dictionaries of string to array of numbers, whereas in reality they are string to a single number.

-> Fixed for the next release.

[Honktown]

https://wiki.factorio.com/Prototype/Fluid
remove pressure_to_speed_ratio from the example -> Fixed.

It does not exist among the prototype keys/links. It is mentioned in the example, but in the log:

Code: Select all

  39.413 Warning PrototypeLoader.cpp:202: Value ROOT.fluid.<some-fluid-name>.pressure_to_speed_ratio was not used.

[Impatient]

Some time ago I ran into some undocumented behavior of surface.map_gen_settings.

It seems that a value of lower than 1/6th (0.166667) for the frequency of ore patches ( used in surface.map_gen_settings.autoplace_controls ) has no effect in game. The docs though do not state any limits as there is only a reference to MapGenSize for the type to be used.

Here is a post about what I tested and found: 84632
And here is Rseding91's assessment of the situation: 91396

It appears to be an obscure thing. Making it work for lower values would be my preferred solution, but if that is not possible, it would be nice, if the docs state the boundaries.

-> Thanks for the detailed explanation. This has been noted on the MapGenSize concept. Basically, anything that's outside the range of values the vanilla map generator offers are not guaranteed to work as expected

[coderpatsy]

Klonan tried fixing it but because it affects older saves it was shelved: viewtopic.php?p=540284#p540284

-> Thanks for the context!

[DoubleThought]

Types/IconData (https://wiki.factorio.com/Types/IconData) does not specify what units shift works in. I am uncertain if it's in grid coordinates, where an icon ranges from [-1, 1], or where an icon ranges from [0, 1], or where an icon ranges from [0, icon_size].
-> Documented, thank you to snouz, Honktown and posila.

[Honktown]

Types/IconData (https://wiki.factorio.com/Types/IconData) does not specify what units shift works in. I am uncertain if it's in grid coordinates, where an icon ranges from [-1, 1], or where an icon ranges from [0, 1], or where an icon ranges from [0, icon_size].

Worse than all those, it's in pixels (from an origin at the center, so negative shifts are left and up, respectively). Pixels after scaling iirc.
-> Documented, thank you to snouz, Honktown and posila.

[ickputzdirwech]

Apparently you can use entity_create{orientation=...} for rolling stock. See 98373. But it's not documented in https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.create_entity.

PS: I wonder what else is available and not mentioned there...

-> Fixed for the next release. We're also having a look at what else is missing.