Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
Locked
Bilka
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

Documentation Improvement Requests

Post by Bilka »

Therenas wrote:
Wed Aug 16, 2023 3:34 pm
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.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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
I have mods! I guess!
Link

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

Today I was told that force_visibility can also affect the selectibilty of a SEWO. -> Added at SimpleEntityWithOwner#force_visibility
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

User avatar
DedlySpyder
Filter Inserter
Filter Inserter
Posts: 253
Joined: Fri Jun 20, 2014 11:42 am
Contact:

Re: Small documentation improvement requests

Post by DedlySpyder »

Took a look through my bug reports, which were normally because something was unclear to me:
-> All of these have been dealt with, changes to the API docs will appear with the next release.

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

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

Klonan wrote:
Mon Apr 19, 2021 11:15 am
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

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by 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.)
Last edited by eradicator on Wed Jun 16, 2021 10:47 am, edited 4 times in total.
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

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

Re: Small documentation improvement requests

Post by 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).
My mods
Content: Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Remote Configuration | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

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

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

https://wiki.factorio.com/Types/ItemProductPrototype wrote: 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
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

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

Re: Small documentation improvement requests

Post by 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
My mods
Content: Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Remote Configuration | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

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

Re: Small documentation improvement requests

Post by 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!)
My mods
Content: Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Remote Configuration | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

User avatar
ickputzdirwech
Filter Inserter
Filter Inserter
Posts: 768
Joined: Sun May 07, 2017 10:16 am
Contact:

Re: Small documentation improvement requests

Post by 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.
Mods: Shortcuts for 1.1, ick's Sea Block, ick's vanilla tweaks
Tools: Atom language pack
Text quickly seems cold and unfriendly. Be careful how you write and interpret what others have written.
- A reminder for me and all who read what I write

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

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

User avatar
Impatient
Filter Inserter
Filter Inserter
Posts: 880
Joined: Sun Mar 20, 2016 2:51 am
Contact:

Boundaries for values in surface.map_gen_settings

Post by 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
Long Handed Inserter
Long Handed Inserter
Posts: 68
Joined: Tue Apr 17, 2018 11:45 pm
Contact:

Re: Small documentation improvement requests

Post by coderpatsy »

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

-> Thanks for the context!

DoubleThought
Inserter
Inserter
Posts: 37
Joined: Fri Mar 01, 2019 1:14 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

DoubleThought wrote:
Wed May 12, 2021 6:59 am
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.
I have mods! I guess!
Link

User avatar
ickputzdirwech
Filter Inserter
Filter Inserter
Posts: 768
Joined: Sun May 07, 2017 10:16 am
Contact:

Re: Small documentation improvement requests

Post by 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.
Mods: Shortcuts for 1.1, ick's Sea Block, ick's vanilla tweaks
Tools: Atom language pack
Text quickly seems cold and unfriendly. Be careful how you write and interpret what others have written.
- A reminder for me and all who read what I write

Locked

Return to “Documentation Improvement Requests”