Small documentation improvement requests

[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".

[JohnTheCF]

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

-> Thank you for pointing this out, fixed.

[curiosity]

https://wiki.factorio.com/Prototype/Roboport#recharge_minimum - missing description.
-> Added.

[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.

[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.

[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]

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.

-> That is not the usual approach, but it works well enough in this case. So, changed, thank you for the idea.

[Honktown]

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.)

[snouz]

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?

[Honktown]

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.)

[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]

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]

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.

[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]?

[Silari]

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.

[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.

[JohnTheCF]

https://wiki.factorio.com/Prototype/UtilityConstants
pollution_color property is missing.
-> Was added in 1.1.41, fixed.

[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]

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]

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.