Documentation Improvement Requests

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

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.

[Silari]

https://lua-api.factorio.com/latest/Lua ... item_stack and https://lua-api.factorio.com/latest/Lua ... mpty_stack have an incomplete 'Return' section.

-> Thanks, fixed for the next release.

[Xorimuth]

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

-> discrete_slider will be removed with 1.2

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

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

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

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

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

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

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

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.

[curiosity]

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]

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.

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

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

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

[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

Code: Select all

/c
local player = game.player
local surface = player.surface

local args = {
	bounding_box = player.character.prototype.collision_box,
	start = player.position,
	goal = {-48, -35},
	force = "player",
	pathfind_flags = {
		cache = false,
	}
}

local masks = {
	[{"water-tile", "object-layer"}] = false, --[[around water and walls]]
	[{}] = false, --[[straight line]]
	[player.character.prototype.collision_mask] = false, --[[straight line]]
	[{["water-tile"] = true, ["object-layer"] = true}] = false, --[[around water and walls]]
}
for mask, do_it in pairs(masks) do
	if do_it then
		args.collision_mask = mask
		surface.request_path(args)
	end
end


local function on_script_path_request_finished (event)
	log(serpent.block(event, {maxlevel = 1}))
end

script.on_event(defines.events.on_script_path_request_finished, on_script_path_request_finished)

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

[eradicator]

Wtf is "generate_sdf" .

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.

[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