Module for reading, changing and declaring engine settings.
These are the player's settings, not the level's. trx.config.set writes to them and keeps the
change: it is remembered across saves and relaunches, exactly as if the player had made it
themselves. A level that wants to tint the water or pull the fog in wants trx.config.override
instead, which lasts as long as the script keeps it and leaves the player's own value untouched
underneath.
A game can also add settings of its own with trx.config.declare: they are saved and loaded with
the player's own, and shown in the settings menu where the declaration asks for. A setting a
game's scripts/_game.lua declares belongs to that game and goes when it does.
Everything about a setting but the value it holds now.
trx.config.describe hands one back and trx.config.declare takes one, so what a script reads
of a setting is what a script writes to make one. The row a declaration asks for is the part
trx.config.describe does not report: see trx.config.Row.
Properties:
default: any. What the setting holds until the player changes it, and what trx.config.reset puts back.key: string. Dotted path the setting answers to. The last segment is what the settings file keys it on, so it has to differ from every other setting's.kind: string. One of boolean, integer, number, color, enum, dynamic_enum or string. A declaration writes boolean, integer or dynamic_enum; the rest name storage the engine owns.max: integer, optional. Highest value a number takes. Absent, it takes as high a number as it can hold.min: integer, optional. Lowest value a number takes. Absent, it takes as low a number as it can hold.percent: boolean, optional. Marks a number stored 0-1 but entered and shown as a 0-100 percentage.ui: trx.config.Row, optional. The row a declared setting takes in the settings menu. Without one the setting has no row, and is the script's to read and write.values: a list of string, optional. What the setting accepts, for the enum kinds. A declared dynamic_enum needs them, and they have to list the default.The settings row a declared setting is shown on: where it sits, and what it does that the setting itself cannot say.
Every callback below is optional, and one that raises is logged and answered as though it were
absent. They are read as the setting is declared and are not reported back by
trx.config.describe.
Properties:
after: string, optional. Setting the row sits below. The row lands at the end of the tab where neither anchor is given.before: string, optional. Setting the row sits above. Steadier than a position: the row stays put when the tab is reordered.can_change_value: function, optional. Called with the value and the direction, -1 or 1. Return false to refuse that press.delta_fast: integer, optional. How far one press moves a number. One step where it is absent.delta_slow: integer, optional. How far one press moves a number while fine adjustment is held.format_value: function, optional. Called with the value, returning what the row prints in place of it.is_available: function, optional. Called with the value. Return false to grey the row out: it stays visible, and the player cannot move it.is_visible: function, optional. Called with the value. Return false to leave the row out of the tab.request_change_value: function, optional. Called with the value and the direction. Return true to take the press over; the row is left alone, and moving the setting is the script's to do.tab: string. Settings tab the row sits on: gameplay_general, gameplay_controls, gameplay_mods, gameplay_fixes, graphic_visuals, graphic_ui, graphic_ui_stats, graphic_ui_bars, graphic_rendering, sound_volume or sound_misc.A setting being watched. trx.config.on_change hands one back, and holding it
is what lets the watcher be dropped later. A watcher is spent once detached, and the end of a level
spends every one a level script attached.
Methods:
trx.config.get(key)
Reads a setting. The value comes back as the type the option is declared with, so a boolean option reads as a boolean. Colors and enums read as strings.
Parameters:
Returns: any. Raises if no option has that key.
Example:
if trx.config.get("audio.enable_music") then
trx.music.play(trx.catalog.music.SECRET)
end
trx.config.describe(key)
Everything about a setting but the value it holds now: what it is, what it accepts, and what it falls back to. This is the shape trx.config.declare takes, so a script can read one setting and declare another like it.
Parameters:
Returns: trx.config.Shape. What the setting is and how it is entered.
Example:
for _, value in ipairs(trx.config.describe("visuals.shadow_type").values) do
trx.log.info(value)
end
trx.config.format_value(key)
The current value as the console prints it: 1 or 0 for a boolean, two decimals for a plain number, a 0-100 percentage where the option is one, and enum values with dashes for underscores.
Parameters:
Returns: string. The text, ready to print.
Example:
trx.console.log(trx.config.format_value("visuals.fov"))
trx.config.accepted_values(key)
What a setting accepts, as text for an error message: on, off for a boolean, a marker like [integer] for the number kinds, or the value names for the enum kinds, with dashes for underscores.
Parameters:
Returns: string or nil. nil for the kinds with nothing to list, such as a color.
trx.config.set(key, value, [force])
Changes the player's setting, and keeps the change. Raises if the key is unknown or the value will not parse.
The old value is not kept anywhere: the new one becomes the active setting as if the player had chosen it, and is remembered across saves and relaunches. Prefer trx.config.override for anything a level wants only while it is running.
Parameters:
trx.config.reset(key, [force])
Puts a setting back to its default, and keeps the change, as trx.config.set does.
Parameters:
key (string). Dotted path.force (boolean, optional). As for trx.config.set.Returns: boolean. false when a script or the game flow is holding the setting (see trx.config.is_overridden).
trx.config.override(key, value)
Changes a setting for as long as the script keeps the override, without touching the player's own value.
The player's value sits underneath and comes back on trx.config.restore. Nothing is written to disk. Overrides stack, so one can be pushed over another; each trx.config.restore lifts one off. A setting the game flow enforces cannot be overridden.
Parameters:
key (string). Dotted path.value (any). As for trx.config.set.Example:
trx.config.override("visuals.water_color", "0080ff")
-- ... and when the level is done with it:
trx.config.restore("visuals.water_color")
trx.config.restore(key)
Lifts one override off a setting, putting back the value underneath it.
Parameters:
Returns: boolean. false if the setting was not overridden.
trx.config.is_overridden(key)
Whether a script or the game flow is currently holding this setting away from the player's own value.
Parameters:
Returns: boolean. True while an override stands, and false once the last is lifted.
trx.config.declare(spec)
Adds a setting of the game's own.
The declaration carries no text. The engine derives settings/<key>/title,
settings/<key>/description and, for an enum, settings/<key>/values/<value>, and looks each up
in the game strings, so a declared setting is translated as every other one is.
The setting comes up holding the player's saved value for it, whether the declaration runs before the settings file is read or after.
Raises where the key is taken, or where the declaration describes a setting that could hold nothing it allows: an enum defaulting to a value it does not list, or an integer defaulting outside its own bounds.
Parameters:
spec (trx.config.Shape). The setting's declaration.Example:
trx.config.declare({
key = "mod.water_color_mode",
kind = "dynamic_enum",
values = { "tombati", "dos", "custom" },
default = "custom",
ui = {
tab = "graphic_visuals",
before = "visuals.water_color",
},
})
trx.config.on_change(key, fn)
Calls fn(value) whenever the setting changes, and once as the watcher is
attached with the value it holds now - so a script applies the player's saved value rather than
waiting for them to touch it again.
A watcher that changes a setting itself is heard by that setting's watchers too. One that raises is logged and the rest still run; it is called again on the next change.
A watcher a level script attaches goes when the level ends, as a trx.events listener does. One a
game script attaches stays for as long as the game.
Parameters:
Returns: trx.config.Watcher. The watcher, for dropping it later.
Example:
local watcher = trx.config.on_change("mod.scanlines", function(value)
trx.log.info("scanlines are now " .. tostring(value))
end)
-- ... and when the script is done with it:
watcher:detach()
trx.config.list()
Every setting and its current value.
Returns: table. Maps each option's key to its value.
Example:
for key, value in pairs(trx.config.list()) do
trx.log.info(key .. " = " .. tostring(value))
end