docs/api/state

@usbx/state

Values shared between scripts

local state = require("@usbx/state")

state.create

function#

Creates or gets the global State with the key. A key that exists with another default, scope or schema is an error.

state.create<T>(key: string, default: T?, schema: Schema<T>) -> State<T>

example

local score = state.create("score", 0, schema.number())

Use it forkeeping one value that every script shares for the whole game, like the round phase.

keyThe State key. Every script that creates it shares it.

defaultoptionalThe value before anything sets it.

schemaWhat values it accepts.

function#

Creates or gets the per-player State with the key. options can show it as a Leaderstat.

state.create_per_player<T>(key: string, default: T?, schema: Schema<T>, options: LeaderboardOptions?) -> PlayerState<T>

example

local coins = state.create_per_player("coins", 0, schema.number(), { leaderboard = { label = "Coins" } })

Use it fortracking each player's own tokens or wins, which can also show on the leaderboard.

keyThe State key.

defaultoptionalEach player's value before anything sets it.

schemaWhat values it accepts.

optionsoptionalShows the value on the player list and the scoreboard.

Build a create_per_player callleaderboard

keydefaultschema

leaderboard
Shows the value as a Leaderstat column, with a label for its title and an optional order.
Inside it: label, order

function#

Creates or gets the per-instance State with the key. A key that exists with another default, scope or schema is an error.

state.create_per_instance<T>(key: string, default: T?, schema: Schema<T>) -> InstanceState<T>

example

local health = state.create_per_instance("health", 100, schema.number())

Use it forgiving every breakable crate or door its own health, all kept under one key.

keyThe State key.

defaultoptionalEach instance's value before anything sets it.

schemaWhat values it accepts.