Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
Locked
User avatar
snouz
Inserter
Inserter
Posts: 27
Joined: Sun Jan 03, 2021 6:01 pm
Contact:

Re: Small documentation improvement requests

Post by snouz »

Honktown wrote:
Sat Oct 16, 2021 9:16 am
Settings aren't really documented at all, which may be more of the "confusion". The only page is: https://wiki.factorio.com/Tutorial:Mod_settings . With regards to data and data:extend, extend is a function you can see in core/lualib/dataloader.lua (it is nothing magical, just puts stuff in data,raw). settings also has a settings-update, and settings-final-fixes phase, for other mods to alter existing settings (hiding,restricting, changing, etc). See https://lua-api.factorio.com/latest/Data-Lifecycle.html . The data.raw on the wiki only is from the data stage (and a separate one for settings stage would be an empty data.raw table... because there are no mod settings by default.)

I've made a minor addition to https://wiki.factorio.com/Tutorial:Mod_ ... o_settings, do you think it's an acceptable edit?


-> Thank you for adding this to https://wiki.factorio.com/Tutorial:Mod_settings, I also added some more info.
Graphically contributed to : Bio Industries (soon) | Warehousing | MFerrari's mods | Brevven's mods | Bob Artisanal Reskins | Mining Drones | Teleporters | Emoji signals

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

Re: Small documentation improvement requests

Post by Honktown »

snouz wrote:
Sat Oct 16, 2021 2:33 pm
Honktown wrote:
Sat Oct 16, 2021 9:16 am
Settings aren't really documented at all, which may be more of the "confusion". The only page is: https://wiki.factorio.com/Tutorial:Mod_settings . With regards to data and data:extend, extend is a function you can see in core/lualib/dataloader.lua (it is nothing magical, just puts stuff in data,raw). settings also has a settings-update, and settings-final-fixes phase, for other mods to alter existing settings (hiding,restricting, changing, etc). See https://lua-api.factorio.com/latest/Data-Lifecycle.html . The data.raw on the wiki only is from the data stage (and a separate one for settings stage would be an empty data.raw table... because there are no mod settings by default.)

I've made a minor addition to https://wiki.factorio.com/Tutorial:Mod_ ... o_settings, do you think it's an acceptable edit?
I wouldn't phrase it that way. After a call to data:extend the setting is in data.raw, not at the end of the setting stage. Also, changing an allowed value to only one is what can force a setting. Changing the default won't do anything if a mod was loaded once, before changing the default. A new section is warranted I think: Modifying Existing Settings, with a mention for "mod-packs" and compatibility. You don't need to write it all yourself, but that should cover most of it.

(I didn't notice the wiki mentioned settings-etc files already.)


-> I have added some additional info, such as how to force a setting to be of a certain value. The section is titled different but contains all the buzzwords mentioned here, so it should hopefully still show up in searches.
I have mods! I guess!
Link

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 »

https://wiki.factorio.com/Prototype/Gen ... emperature

The maximum temperature to which the efficiency will increase. After this temperature the generator will run at 100% efficiency. Note: higher temperatures can still be consumed.

-> It's a bit more complicated than that, I've expanded the page on maximum_temperature and related properties.
Alt-F4 Author | Factorio Modder
Mods: Hall of Fame | Better Victory Screen | Fluidic Power | Biter Power | Space Spidertron | Spidertron Dock | Weasel's Demolition Derby

GlassBricks
Inserter
Inserter
Posts: 25
Joined: Fri Jun 11, 2021 5:20 pm
Contact:

Re: Small documentation improvement requests

Post by GlassBricks »

For defines.events.on_game_created_from_scenario we could add the additional note that "This event is not fired when the scenario is loaded via the map editor", a fact I discovered only after digging around a bit. This would be useful to note that this event could be used to detect whether or not a scenario was loaded via the Map editor, for mods that want some interaction with the map editor specifically.

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

A note on get_fluid_count() and get_fluid_contents() where defined, that they do not capture temperature details, and fluidboxes should be used directly [in the cases where temperature is relevant].

Related to: viewtopic.php?f=221&t=100323


-> Appreciate the context, added for the next release.
I have mods! I guess!
Link

justarandomgeek
Filter Inserter
Filter Inserter
Posts: 300
Joined: Fri Mar 18, 2016 4:34 pm
Contact:

Re: Small documentation improvement requests

Post by justarandomgeek »

https://lua-api.factorio.com/latest/Con ... Connection

describes the type of positions as array[Vector], but hten has a comment that they have x/y, shouldn't this be array[Position]?

User avatar
Silari
Filter Inserter
Filter Inserter
Posts: 488
Joined: Sat Jan 27, 2018 10:04 pm
Contact:

Re: Small documentation improvement requests

Post by Silari »

justarandomgeek wrote:
Fri Oct 22, 2021 1:41 am
https://lua-api.factorio.com/latest/Con ... Connection

describes the type of positions as array[Vector], but hten has a comment that they have x/y, shouldn't this be array[Position]?
https://lua-api.factorio.com/latest/Con ... tml#Vector Vectors also have an x/y, sometimes as an array, sometimes as a table with explicit x and y members. Far as I can tell the only difference is Position MUST be int for x/y, Vector isn't specified but the example has decimals.

The description for Position implies that it's only used when actually specifying a map position, which may be why Vector is considered a different thing.

User avatar
Therenas
Factorio Staff
Factorio Staff
Posts: 232
Joined: Tue Dec 11, 2018 2:10 pm
Contact:

Re: Small documentation improvement requests

Post by Therenas »

Silari is right in this case, I actually put that x/y line there myself pretty recently. The whole situation isn't great, it's on my list to come up with a better solution to it, but the underlying issue is that it's just inconsistently implemented in the APIs, sometimes it's one way, sometimes the other. The real fix would be to fix what the API returns, but that's not feasible in 1.1. We'll see, maybe I can think of something.


InappropriatePenguin
Inserter
Inserter
Posts: 29
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by InappropriatePenguin »

I think there's a mistake in the description of this function: https://lua-api.factorio.com/next/LuaCo ... _blueprint.

It refers to a `get_cursor_blueprint_entities` function which I couldn't find in the API—I was guessing it meant to refer to `get_blueprint_entities`, which is described right below it.


-> Thanks for the hint, corrected and updated for the next release.

InappropriatePenguin
Inserter
Inserter
Posts: 29
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by InappropriatePenguin »

LuaControl.set_personal_logistic_slot (https://lua-api.factorio.com/latest/Lua ... istic_slot)

The function returns a boolean value reflecting whether it was successful or not. The note for that function however states that it will silently fail if personal logistic aren't researched. I wasn't sure if that meant that the returned boolean value could not be relied on in that instance.

In testing, the function does appropriately return false when personal logistics are not researched, so perhaps a better wording would be: "This function will return false if personal logistics aren't researched, but will not raise any error." or something along those lines.

This is on contrast to LuaControl.clear_personal_logistic_slot (https://lua-api.factorio.com/latest/Lua ... istic_slot), which does truly appear to "silently" fail when personal logistics aren't researched since it has no return value.


-> Thank you for the detailed report, this has been addressed for the next release.

GlassBricks
Inserter
Inserter
Posts: 25
Joined: Fri Jun 11, 2021 5:20 pm
Contact:

Re: Small documentation improvement requests

Post by GlassBricks »

It seems LocalisedString also allows boolean values (and even nil in many cases); this could be documented.

-> Thanks, this is clarified for the next release.

InappropriatePenguin
Inserter
Inserter
Posts: 29
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by InappropriatePenguin »

LuaGameScript.delete_surface() (https://lua-api.factorio.com/latest/Lua ... te_surface)

This function appears to be similar to LuaSurface.delete_chunk() and LuaSurface.clear() in that it does not run immediately when called but rather appears to run either at the end of the current tick or some time in the next game tick. That is at least when it seems to raise its associated events.

I would suggest adding a note to its description to make that clear.


-> This is a good point. A proper system for documenting when an event fires is in the works, and should be ready soon, so I will not add a note for this single thing for now.

fredthedeadhead
Inserter
Inserter
Posts: 28
Joined: Mon Oct 18, 2021 6:13 pm
Contact:

Re: Small documentation improvement requests

Post by fredthedeadhead »

I think I've found some mis-typed fields:

[list=1]
[*] https://lua-api.factorio.com/latest/Con ... l#Position

Position x and y are documented as being ints, but when I get the player's position, it returns floating point numbers with decimal places.

Code: Select all

/c local p = game.player p.print(p.position.x.." "..p.position.y)  
-0.05078125, 46.48828125

[*] https://lua-api.factorio.com/latest/Lua ... ce.daytime

LuaSurface.daytime is documented as a float, but is actually a double.
[/list]


-> Thanks for the hints, both of these are fixed for the next release.

InappropriatePenguin
Inserter
Inserter
Posts: 29
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by InappropriatePenguin »

LuaEntity.damage(damage, force, type, dealer)
[https://lua-api.factorio.com/latest/Lua ... ity.damage]

It appears that the `dealer` entity must be located on the same surface as the entity being damaged, or it will raise an error. Perhaps this can be mentioned, either in the parameter description or as a note next to "Can only be used if this is EntityWithHealth"?


-> Noted for the next release, thanks.

User avatar
JohnTheCF
Inserter
Inserter
Posts: 21
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Types/MapGenP ... c_settings

`autoplace_settings` just has type of table and there is no explanation what its structure is supposed to be.


-> Thank you for pointing this out. The explanation for this from the runtime docs has now also been added to the wiki.

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://lua-api.factorio.com/1.1.49/LuaEntity.html#LuaEntity.destructible wrote: destructible :: boolean [Read/Write]

When the entity is not destructible it can't be damaged.
I've neglected this flag so far because its effect seemed to be the same as giving an entity full resistance against all damage types. However, a posting by posila let me realize that setting this flag set to false will prevent enemy units and turrets from attacking this unit (if the flag is set to true, they may attack it although they can't damage it). I'd suggest changing the description to

Code: Select all

 destructible :: boolean [Read/Write]

When the entity is not destructible it can't be damaged and won't be automatically attacked.
-> Thanks, clarified for the next release.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

-DeadlyKitten
Inserter
Inserter
Posts: 40
Joined: Sat Dec 14, 2019 3:26 am
Contact:

Re: Small documentation improvement requests

Post by -DeadlyKitten »

the page https://wiki.factorio.com/Types/SpawnPoint
lists this
Types/SpawnPoint ... evolution_factor or 1 ... spawn_weight or 2
in testing however i found that it is called weight not spawn_weight

-> It's called spawn_weight in the data stage (which is what the wiki page is about) and weight during runtime (https://lua-api.factorio.com/latest/Con ... Definition).

fredthedeadhead
Inserter
Inserter
Posts: 28
Joined: Mon Oct 18, 2021 6:13 pm
Contact:

Re: Small documentation improvement requests

Post by fredthedeadhead »

fredthedeadhead wrote:
Sun Nov 28, 2021 9:50 am
-> Thanks for the hints, both of these are fixed for the next release.
Hi, I see that LuaSurface is updated, thanks! But Position x/y is not, they still show ints.

Concepts.html#Position

-> The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition. So this is now fixed by it no longer being confusing what Position is for.

User avatar
Silari
Filter Inserter
Filter Inserter
Posts: 488
Joined: Sat Jan 27, 2018 10:04 pm
Contact:

Re: Small documentation improvement requests

Post by Silari »

fredthedeadhead wrote:
Wed Dec 22, 2021 10:11 pm
fredthedeadhead wrote:
Sun Nov 28, 2021 9:50 am
-> Thanks for the hints, both of these are fixed for the next release.
Hi, I see that LuaSurface is updated, thanks! But Position x/y is not, they still show ints.

https://lua-api.factorio.com/latest/Con ... l#Position
LUAControl.position, which LUAPlayer inherits from, returns a MapPosition, not a Position. Pretty sure that was the correction made.

Locked

Return to “Documentation Improvement Requests”