Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
oof2win2
Long Handed Inserter
Long Handed Inserter
Posts: 55
Joined: Wed Nov 18, 2020 8:13 am
Contact:

Re: Small documentation improvement requests

Post by oof2win2 »

https://wiki.factorio.com/Types/MapGenPreset#basic_settings
Wiki says that "default_enable_all_autoplace_controls: If this is false, then all autoplace controls will be disabled.". This is however not true, as https://lua-api.factorio.com/latest/Concepts.html#MapGenSettings says "default_enable_all_autoplace_controls :: boolean: If autoplace_controls not defined should be default-enabled.". This is the correct description. When tested, this is also correct. I therefore believe that the wiki should be corrected.


-> Thanks for the hint, fixed.

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

Re: Small documentation improvement requests

Post by curiosity »

https://wiki.factorio.com/Prototype/RollingStock#max_speed should say that it is in tiles/tick.

Should also probably say somewhere (IDK where) that max speed of a train is the minimum max speed of its components.

edit: looking at the rolling stock page, it should explain what a "tie" means in-game in drive_over_tie_trigger and tie_distance (the latter should also say its units).


-> All now on https://wiki.factorio.com/Prototype/RollingStock.


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

Re: Small documentation improvement requests

Post by Xorimuth »

Slider discrete_slider vs discrete_values: viewtopic.php?f=25&t=89079

-> discrete_slider will be removed with 1.2
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 »

https://lua-api.factorio.com/latest/Lua ... lement.add specifies some defaults for sliders. But in select cases (max-min=1, I think?) sliders get their properties forcibly overridden, including after creation. This should be noted somewhere.

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 »

https://wiki.factorio.com/Prototype_definitions does not seem to document setting-stage prototypes at all. If creating new pages for that is too much at least a link would be nice? Tried Ctrl+F "setting" and was pretty confused it didn't find anything. I can only find the much more verbose Mod Settings Tutorial.

-> The data stage docs won't document settings stage things, however the page now links to the tutorial.
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
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

LuaSettings is a bit opaque. "settings.player" seems to be hardcoded to a single player? Not sure which player (i.e. if player one is deleted?), or why that is useful, or how it is different from settings.get_player_settings and LuaPlayer.mod_settings.

-> There actually was some documentation there, but it was formatted incorrectly and thus didn't show up on the website. Fixed that, and added more info as well for the next release. Thanks for bringing it up.
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
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

on_string_translated does not mention what "translated :: boolean" implies. It seems that it's actually translatABLE, i.e. that particular string can never be translated in that players locale even if the request is resent.

-> Thanks, clarified for the next release.
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
Stringweasel
Filter Inserter
Filter Inserter
Posts: 310
Joined: Thu Apr 27, 2017 8:22 pm
Contact:

Re: Small documentation improvement requests

Post by Stringweasel »

The docs for create_entity does not include all keys requried for when creating a artillery-flare. It requires the same keys as particle, but it does not seem to be a particle because you can't spawn it using create_particle.

-> Added for the next release. (they are indeed the same parameters)
Alt-F4 Author | Factorio Modder
Mods: Hall of Fame | Better Victory Screen | Fluidic Power | Biter Power | Space Spidertron | Spidertron Dock | Weasel's Demolition Derby

User avatar
Stringweasel
Filter Inserter
Filter Inserter
Posts: 310
Joined: Thu Apr 27, 2017 8:22 pm
Contact:

Re: Small documentation improvement requests

Post by Stringweasel »

The play_sound{ } function for both surface and player says that if no position is given then it's played "everywhere". This would mean that it's similar to a programmable speaker's global alert that can be heard everywhere. However, this is not true.

When a sound is played "everywhere" using play_sound{ } then the sound is simply played at each player's location at that point. If the player moves away from that location, and the sound is long enough, then the sound will become softer and eventually dissapear. See 98618 for reference.

The docs should therefore not mention "everywhere", but rather something like "if no position is given then the sound is played at the players immediate location".


-> Clarified for the next release, thanks for the hint.
Alt-F4 Author | Factorio Modder
Mods: Hall of Fame | Better Victory Screen | Fluidic Power | Biter Power | Space Spidertron | Spidertron Dock | Weasel's Demolition Derby

PFQNiet
Filter Inserter
Filter Inserter
Posts: 289
Joined: Sat Sep 05, 2020 7:48 pm
Contact:

Re: Small documentation improvement requests

Post by PFQNiet »

RealOrientation
The smooth orientation. It is a float in the range [0, 1), where a value of 0 indicates "north" and a value of 0.5 indicates "south".
So... is 0.25 East or West?

-> Heh, good point, clarified 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 »

on_runtime_mod_setting_changed

Called when a runtime mod setting is changed by a player.

Contains
player_index :: uint (optional): The player who changed the setting or nil if changed by script.
setting :: string: The setting name that changed.
setting_type :: string: The setting type: "runtime-per-user", or "runtime-global".
It is not obvious whether player_index is always optional, or whether it will always exist if setting_type == "runtime-per-user" but may be nil for "runtime-global".

-> Fixed for the next release, thanks.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

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

Re: Small documentation improvement requests

Post by curiosity »

Pi-C wrote:
Tue Jun 01, 2021 7:39 pm
on_runtime_mod_setting_changed

Called when a runtime mod setting is changed by a player.

Contains
player_index :: uint (optional): The player who changed the setting or nil if changed by script.
setting :: string: The setting name that changed.
setting_type :: string: The setting type: "runtime-per-user", or "runtime-global".
It is not obvious whether player_index is always optional, or whether it will always exist if setting_type == "runtime-per-user" but may be nil for "runtime-global".
That description is completely wrong. player_index is always the player whose setting was changed (or nil if it's a global setting) regardless of how it was changed.

-> Thanks for the hint!

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://lua-api.factorio.com/latest/Lua ... get_recipe

Works on a ghost of a crafting machine. Not sure if it is intentional or not (there is no other obvious way to check the recipe on a ghost), but it works. get_recipe() and previous_recipe don't do anything on a blueprint of a furnace, which makes sense.

(discussion moved to here)


-> Improved 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 »

Prototype/TipsAndTricksItem.starting_status

I don't get what the difference between "optional" and "unlocked" is supposed to be. When I reset my player-data.json and start a new game with the prototype set to either of these it instantly switches to {"status": "suggested"} in the json file.

-> The type now has its own page with docs for what each possible option does.
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.

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

Re: Small documentation improvement requests

Post by curiosity »

https://wiki.factorio.com/Types/IconData#shift - what units?

edit: more relevant info that needs to be documented: viewtopic.php?f=48&t=69221


-> Documented, thank you to snouz, Honktown and posila.

User avatar
lovely_santa
Filter Inserter
Filter Inserter
Posts: 502
Joined: Sat Feb 18, 2017 9:41 pm
Contact:

Re: Small documentation improvement requests

Post by lovely_santa »

https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.timeout

It would be nice to have some small definition of what this 'timeout' actually stands for... (the time between the mine is placed and when it is armed)


-> Thanks, fixed for the next release.
You can find all my mods on the mod portal. Also helping on Arch666Angel's mods.
Image

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

Re: Small documentation improvement requests

Post by Honktown »

The collision_mask argument for surface.request_path is a bit confusing, in my opinion:

Code: Select all

collision_mask :: CollisionMask or array[string]
The collision mask is not the collision mask of the prototype for expected results (they are opposite collision masks!), and "array[string]" is an unusual term. I found viewtopic.php?t=34548 which describes a previous issue someone took with it (that it should be dictionary string → boolean). In addition, an array of string is accepted.
Command example
^only turn one mask on at a time for the in-game debug to show the paths, I guess. It won't show all of them at once (bug...?).

-> Answered by Klonan here.
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 »

Wtf is "generate_sdf" :lol:.

Saw it on the character-bonus technology-icon definitions and noticed it's supported by several sprite related prototypes but it's explained nowhere.


-> Explained on https://wiki.factorio.com/Types/Sprite, it's unused in the rest of the sprite types.
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
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

UnlockRecipeModifierPrototype looks like someone copied the wrong template.
It says "item" and "count" instead of "recipe" :D.


-> The doc for this ended up on https://wiki.factorio.com/Types/TurretA ... rPrototype somehow. Thanks for noticing, fixed :D
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.

Locked

Return to “Documentation Improvement Requests”