abstract StateBag(String)

package fivem.shared.core

A handle to one FiveM state bag, addressed by its bag name.

State bags are the engine's own replicated key/value store. Setting a value on the server with replicated = true pushes it to every client automatically — no events, no manual sync, and it survives a client reconnecting into range. That makes them the right tool for entity metadata (vehicle fuel, a door's locked flag, a player's job) and the wrong tool for high-frequency data, since every replicated write is a network message.

var bag = StateBag.entity(vehicle.netId);
bag.set("fuel", 84.5);
var fuel:Float = bag.get("fuel");

bag.onChange("fuel", (value, _) -> updateFuelGauge(value));

Clients may only write non-replicated (local) values; a client attempting a replicated write is ignored by the server.

Static variables

staticread onlyname:String

The raw bag name, e.g. "entity:1234".

Static methods

staticinlineentity(netId:Int):StateBag

The bag for a networked entity, addressed by its network ID.

staticinlineentityFromName(bagName:String):Int

Resolves a bag name back to the entity it belongs to, or 0.

staticinlineget<T>(this:String, key:String):Null<T>

Reads a value, or null if the key was never set.

Values arrive deserialised. Tables come back as raw Lua tables, so run anything array-shaped through LuaTables.toArray.

staticinlineglobal():StateBag

The server-wide bag, replicated to every client.

staticinlinehas(this:String, key:String):Bool

staticinlinekeys(this:String):Array<String>

Every key currently set on this bag.

staticinlinelocalEntity(handle:Int):StateBag

The bag for a client-side entity that has no network ID. Values here never replicate — the entity doesn't exist anywhere else.

staticinlineonAnyChange<T>(keyFilter:Null<String>, bagFilter:Null<String>, handler:(bagName:String, key:String, value:T, replicated:Bool) ‑> Void):Int

Runs handler for state bag changes matching the filters. Passing null for a filter matches everything — a null keyFilter with a null bagFilter fires for every change on the server, which is rarely what you want.

The handler receives (bagName, key, value, replicated).

staticinlineonChange<T>(this:String, key:String, handler:(value:T, replicated:Bool) ‑> Void):Int

Runs handler whenever key changes on this bag, receiving the new value and whether the change was replicated.

Returns a cookie for StateBag.removeChangeHandler.

staticinlineplayer(serverId:Int):StateBag

The bag for a player, addressed by their server ID.

staticinlineplayerFromName(bagName:String):Int

Resolves a bag name back to the player server ID it belongs to, or 0.

@:value({ replicated : true })staticinlineremove(this:String, key:String, replicated:Bool = true):Void

Clears a key by setting it to nil.

staticinlineremoveChangeHandler(cookie:Int):Void

Detaches a handler by the cookie onChange / onAnyChange returned.

@:value({ replicated : true })staticinlineset(this:String, key:String, value:Dynamic, replicated:Bool = true):Void

Writes a value.

Parameters:

replicated

Whether to push the change to clients. Server-side only — a client's replicated writes are discarded by the server.