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.
trx.config.signals.changed (trx.signal.Signal). Says when any setting changes. It holds a count that goes up with each change, whichever settings moved. A widget that follows several settings at once listens to this rather than to each of them. (read-only)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 or trx.config.Value, optional. What the setting accepts, for the enum kinds. A declared dynamic_enum needs them, and they have to list the default. A value given as text takes the label settings/<key>/values/<value>.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.One value that an enum setting takes, as the settings menu shows it.
Properties:
enabled: boolean. Whether the value can be picked now. A dynamic enum can switch values off, such as a language whose files are missing.label: string. What the menu shows for it, in the player's language.value: string. The value, as trx.config.set takes it.One value that a declared dynamic_enum setting takes, with the label of
its own that the settings menu shows for it.
Properties:
label: string, optional. The game string of what the settings menu shows for it. The value itself by default.value: string. The value, as trx.config.set takes it.A setting a script declared with a row in the settings menu.
Properties:
key: string. The setting.row: trx.config.Row. The row, as the declaration gave it.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.signals
What the settings tell a script about themselves.
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 and a color as a
trx.math.Color. 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:
key (string). Dotted path.value (any). A boolean, a number, or a string, matching the option's type. A color is a trx.math.Color or the hex text one is written as. An enum value is taken in either spelling: underscores or the dashes the console shows.force (boolean, optional). Write through a setting the game flow enforces.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.is_default(key)
Whether a setting holds the value it falls back to.
Parameters:
Returns: boolean. True where the value equals the default.
trx.config.is_hidden(key)
Whether the game flow keeps a setting out of the settings menu, as it does
for one that a game does not use.
Parameters:
key (string). Dotted path.Returns: boolean. True where the setting is hidden.
trx.config.labels(key)
The values that an enum setting takes, in the order the game defines them,
with what the settings menu shows for each. Any other setting has none.
Parameters:
Returns: a list of trx.config.Label. The values, empty for a setting that is not an enum.
Example:
for _, entry in ipairs(trx.config.labels("visuals.shadow_type")) do
trx.log.info(entry.value .. " = " .. entry.label)
end
trx.config.to_string(key, [options])
A setting's value as text: as the settings file stores it, or as the
settings menu shows it.
Parameters:
options (table, optional). How to write it, and which value.
Keys:
human (boolean, optional). Whether to write the text as the settings menu shows it, with labels in the player's language, rather than as the settings file stores it. false by default.value (any, optional). A value to write in place of the setting's own. It is read as trx.config.set reads it.Returns: string or nil. The text, or nil where value is one the setting does not accept.
Example:
local shown = trx.config.to_string("visuals.shadow_type", { human = true })
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.declared_rows()
The rows that scripts asked for in the settings menu, in the order the
settings were declared. The settings menu reads them to place each row.
Returns: a list of trx.config.DeclaredRow. The rows.
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.
A level script runs before the level is read, where a handler can reach nothing the level carries. The call for the value in force therefore waits until the level has its objects. Every other watcher is called as it is attached.
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