Small documentation improvement requests

Place to ask discuss and request the modding support of Factorio. Don't request mods here.
User avatar
JohnTheCF
Burner Inserter
Burner Inserter
Posts: 13
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Types/TileTransitions
Mandatory properties are not always mandatory and their optionality is actually determined by bool property. They are mandatory by default though. Other optional properties have no description at all (with rare exceptions) and it's not clear what _effect_map and _weights do, as well as can you set "<property>" and "<property>_mask".

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

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Prototype/Til ... ransitions
There is a little typo in property description, space is missing between "and" and "transition_group2"

curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 90
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »


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

Re: Small documentation improvement requests

Post by JohnTheCF »

https://wiki.factorio.com/Prototype/Tutorial
"trigger" property is listed in table of contents, but not in mandatory or optional properties section.

-> That was an old value from the cache, I cleared the page cache so it should be fixed.

User avatar
snouz
Inserter
Inserter
Posts: 23
Joined: Sun Jan 03, 2021 6:01 pm
Contact:

Re: Small documentation improvement requests

Post by snouz »

Not 100% sure it belongs to that page, but I can confirm settings are accessible in data.raw (from the setting stage at least). But it's nowhere to be seen in https://wiki.factorio.com/Data.raw

example in settings-updates.lua:
data.raw["bool-setting"]["Schall-VS-XL-t2-enable"].order = "1"
correctly moves the setting to the beginning.
Graphically contributed to : Bio Industries (soon) | Warehousing | MFerrari's mods | Brevven's mods | Bob Artisanal Reskins | Mining Drones | Teleporters | Emoji signals

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

Re: Small documentation improvement requests

Post by JohnTheCF »

Some StyleSpecification extensions have type string in table on StyleSpecification page, but are marked <abstract> on individual pages. So far I've noticed:
https://wiki.factorio.com/Types/EmptyWidgetStyleSpecification
https://wiki.factorio.com/Types/ScrollB ... cification
https://wiki.factorio.com/Types/StyleWi ... cification

-> EmptyWidgetStyleSpecification indeed has a style name, fixed the individual page. However, the other styles have <abstract> on both pages, which looks correct when looking at the source code.

curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 90
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

Contradictory documentation: Prototype/MiningDrill#allowed_effects and Prototype/Lab#allowed_effects say that the default is all effects, but Types/EffectTypeLimitation says that the default is nothing. What I think would be better is specifying the defaults for Prototype/Beacon#allowed_effects and Prototype/CraftingMachine#allowed_effects and removing the mention of nil entirely from Types/EffectTypeLimitation.

Honktown
Filter Inserter
Filter Inserter
Posts: 839
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

snouz wrote:
Fri Oct 15, 2021 10:41 am
Not 100% sure it belongs to that page, but I can confirm settings are accessible in data.raw (from the setting stage at least). But it's nowhere to be seen in https://wiki.factorio.com/Data.raw

example in settings-updates.lua:
data.raw["bool-setting"]["Schall-VS-XL-t2-enable"].order = "1"
correctly moves the setting to the beginning.
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 have mods! I guess!
Link

User avatar
snouz
Inserter
Inserter
Posts: 23
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?
Graphically contributed to : Bio Industries (soon) | Warehousing | MFerrari's mods | Brevven's mods | Bob Artisanal Reskins | Mining Drones | Teleporters | Emoji signals

Honktown
Filter Inserter
Filter Inserter
Posts: 839
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 mods! I guess!
Link

User avatar
Stringweasel
Long Handed Inserter
Long Handed Inserter
Posts: 56
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.

GlassBricks
Burner Inserter
Burner Inserter
Posts: 8
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
Filter Inserter
Filter Inserter
Posts: 839
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: 293
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: 294
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: 210
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
Burner Inserter
Burner Inserter
Posts: 7
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.

evildogbot100
Fast Inserter
Fast Inserter
Posts: 152
Joined: Sun Dec 18, 2016 3:02 pm
Contact:

Re: Small documentation improvement requests

Post by evildogbot100 »

Hello, It seems that the documentation on prototype/beam can be elaborated a little bit. A simple explanation on how beams with head and tail segments actually behaves would be nice. From my tests it seems that every around 64 unit length, a single segment has to be drawn, and if the source image is longer than 64 pixel, it will be squished to fit the 64 pixel. Nowhere is this behavior explained in the wiki. Also, explanation on start/end of the beam would be nice as well.

InappropriatePenguin
Burner Inserter
Burner Inserter
Posts: 7
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.

Post Reply

Return to “Modding interface requests”