ss.params | Split/Second Modding

The params namespace exposes the game's tweak tree as nested properties. Every key a params file can set, and every game_setup/* value, lives in this tree. A read returns the live value, an assignment writes it, a directory is a proxy that can be walked further, and a missing name is nil. A name containing spaces, or a whole path, goes in brackets.

Static members#

These elements are static to the class itself and can be accessed like so:

local players = ss.params.game_setup.num_players

Static functions#

The bracket forms as functions, and the functions for looking around the tree.

Function	Return Values	Description
`ss.params.get(string path)`	any value	Returns the value at the given path. Returns nil for a missing name.
`ss.params.set( string path, any value )`	nil	Sets the value at the given path. A missing path, a type the node cannot hold or a value it refuses results in an error.
`ss.params.type(string path)`	string type	Returns the type of the node at the given path: `dir`, `float`, `int`, `uint`, `bool`, `enum`, `string`, `conststring`, `floatlist` or `unknown`. Returns nil for a missing name.
`ss.params.exists(string path)`	boolean exists	Returns whether the given path names a directory or a value.
`ss.params.info(string path)`	table info	Returns a table describing the node at the given path: `type`, `class` (the game's own node class), `node` and `address` (the variable the game reads), `min` and `max` for numbers, `names`, `index` and `mask` for enums, and `capacity` for strings.
`ss.params.list(string path)`	table listing	Returns the contents of the directory at the given path, as `{ dirs = { names }, leaves = { { name, type, value } } }`.
`ss.params.dump(string path)`	nil	Writes the contents of the directory at the given path to the log, one line per entry.

Types#

The types follow the game's node classes.

Type	Field	Description
table	`dir`	A directory. Reads as a proxy that can be walked further; its path can be given to `list` and `dump`.
number	`float`	A floating point value, with the `min` and `max` the game registered it with. The limits are reported by `info` and are not enforced on a write.
integer	`int, uint`	A signed or unsigned integer, with `min` and `max` reported by `info` and not enforced on a write.
boolean	`bool`	A boolean. A write takes `true`, `false` or a number.
string	`enum`	An enumeration. Reads as the name of the current entry. A write takes a name, case-insensitively, or a 0-based index; `info` lists the `names`.
string	`string`	A string. A write goes into the game's own fixed buffer, so a value longer than the node's `capacity` is refused.
string	`conststring`	A read-only string.
nil	`floatlist`	A float list. Reads as nil and refuses writes, with the class name in the error. Data curves and the other rarer classes behave the same way.
nil	`unknown`	A node class the hook does not know. Reads as nil and refuses writes, with the class name in the error.

Resolution and cost#

A path is resolved on every access; there is no handle to hold. The walk of the tree by name takes a fraction of a millisecond on the development VM, which is suitable for a script that reads a few values when something happens and not for a hundred reads every tick. A value that is read often is best kept in a local.

ss.params.RaceSetup can be accessed at any time, but its contents come and go with the race: the RaceSetup/... directories are built by the race setup and read nil in the front end. The Game Mode's Type index is derived at race setup from the node's mask, which is what the front end's choice sets, so the mode is set with the boot's mode file rather than by writing Type.

A write lands in the variable the game reads, and what follows is whatever the game does with it. A value the game copies out at race setup, such as num_players, has to be set before that setup; a value it reads every frame, such as MGF/EnvironmentFriction, changes at once.

Example#

ss.params.game_setup.num_players                     -- 8
ss.params.RaceSetup["Game Mode"].Type                -- "Race" (an enum reads as its entry's name)
ss.params["RaceSetup/Logic/Laps/Number of Laps"] = 5 -- a write; a bad one is an error
ss.params.MGF.EnvironmentFriction = 0.2
ss.params.dump("RaceSetup/Logic/Laps")               -- the directory's entries, with types and values, to the log