Statebags - UgCore

Data that is read often replicates through statebags. Reading a statebag costs nothing: no export, no network round trip.

Prefer statebags over API calls for read-heavy data such as job, duty, loaded state and death state. Exports copy tables on every call.

Player statebags

Set by the server only, on Player(source).state:

Key	Value	Module
`ug-core:Loaded`	`true` once a character is loaded, or at join without characters	players
`ug-core:Player`	`{ name, characterId? }`	players
`ug-core:Metadata`	Metadata set with `replicate = true`	players
`ug-core:DeathState`	`'Alive'`, `'Downed'` or `'Dead'`	players
`ug-core:Injuries`	List of injuries	players
`ug-core:Job`	`{ name, label, grade, gradeName, gradeLabel, salary, boss, onDuty }`	jobs
`ug-core:Gang`	`{ name, label, grade, gradeName, gradeLabel, salary, boss }`	gangs
`ug-core:Session`	Session id, or nil in the shared world	sessions

Player statebags reach every client. Never put secrets in replicated metadata.

Read them

local job = Player(source).state['ug-core:Job']

if job and job.name == 'police' and job.onDuty then
    -- ...
end

local state = LocalPlayer.state['ug-core:DeathState']

-- Or through UgCore, which returns copies:
local downed = UgCore.LocalPlayer.IsDowned()
local job = UgCore.Jobs.Get()

React to changes

client.lua

AddStateBagChangeHandler('ug-core:Job', ('player:%d'):format(GetPlayerServerId(PlayerId())), function(_, _, job)
    print('New job: ' .. (job and job.label or 'none'))
end)

Global state

Key	Value
`GlobalState['ug-core:Config']`	Client and shared config values.
`GlobalState['ug-core:Modules']`	Enabled modules, their files and namespaces.

⌘I