Developer Preview

State bags

Live data on the server, players, lots and Sims – replicated to everyone, step by step.

Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.

A state bag is a small table of live data attached to something: the whole server, a player, a lot or a Sim. The server writes a value once and Neighborly delivers it to every player – including the ones who join an hour later. If you have used state bags on FiveM, the API is the same.

The four kinds of bags

In LuaBag nameAttached toWho may write
GlobalStateglobalThe whole serverServer
Player(id).state
LocalPlayer.state
player:12One connected playerServer, and that player for their own bag
Lot(zoneId).statelot:4821A lotServer
Entity(id).stateentity:90031A Sim or an objectServer

Read a key like a table field (GlobalState.open), write with bag:set(key, value, replicated). On the server, plain assignment (GlobalState.open = true) is a replicated set.

What happens when the server writes

server.lua
  GlobalState:set('open', true, true)
        |
        v
Neighborly server
  1. server change handlers run   (bag still has the old value)
  2. 'open' is stored in bag 'global'
        |
        v   one message to every connected player
every client
  3. client change handlers run   (again before storing)
  4. GlobalState.open == true
  1. Your server script sets a keyWith replicated = true (or plain assignment on the server) the value is meant for everyone. With false it never leaves the server – useful for data only the server needs.
  2. Handlers run first, then the value is storedLike on FiveM, AddStateBagChangeHandler handlers run just before the new value is stored. Inside a handler, the bag still has the old value; the new one is the value argument.
  3. Every client receives itClients apply the change in the order it was made and run their own handlers, again just before storing.
  4. Everyone reads the same valueFrom now on GlobalState.open is true on the server and on every client.
server.luaLUA
GlobalState.cafeOpen = true
Player(source).state:set('job', 'barista', true)
Lot(zoneId).state:set('doorbell', 'chime', true)
Entity(GetPlayerCharacter(source)).state:set('apron', 'blue', true)
Player(source).state:set('shiftStarted', os.time(), false)

What happens when a client writes

A client may write exactly one bag: its own player bag. Everything else is refused.

client of player 12
  LocalPlayer.state:set('mood', 'happy', true)
        |
        v
server: is 'player:12' the sender's own bag, and strict mode off?
        |
        +-- yes --> run handlers, store it
        |              |
        |              v
        |           other clients: Player(12).state.mood == 'happy'
        |
        +-- no ---> refuse it, send player 12 the real value back
WhoCallResult
Serverbag:set(k, v, true)Stored and sent to every client.
Serverbag:set(k, v, false)Stored on the server only. Clients never see it.
ClientLocalPlayer.state:set(k, v, true)Sent to the server, which stores it and passes it on to everyone else.
ClientLocalPlayer.state:set(k, v)Stays on that PC only, until the server changes the key.
ClientAny other bag with trueRefused. The client gets the server's value back, so it can't drift.

The server can't veto a write to a player's own bag before it happens – exactly like on FiveM. Use client writes for harmless things like a mood or a note, and watch them with a change handler. For anything that matters – jobs, money, permissions – let the client send an event and have the server write the bag. To refuse every client write, set "stateBagStrictMode": true in server.json.

Players who join later

player joins
        |
        v
server sends one snapshot of every replicated key:
GlobalState, every player, every lot, every entity
        |
        v
client scripts start and can read any bag right away
(no change handlers fire for snapshot values)

The snapshot arrives before any client script runs, so the top of client.lua can already read GlobalState. Values that arrive in the snapshot don't fire change handlers – they aren't changes. That's why almost every client that shows state uses the same two steps: read the current value, then listen for changes.

client.luaLUA
local function render(open)
    if open then
        exports.neighborly:showTextUI('Bluejay Café is open', { icon = 'coffee' })
    else
        exports.neighborly:hideTextUI()
    end
end

render(GlobalState.cafeOpen)

AddStateBagChangeHandler('cafeOpen', 'global', function(bagName, key, value)
    render(value)
end)

Change handlers

int AddStateBagChangeHandler(string? key, string? bagFilter, function handler) Shared

The handler receives (bagName, key, value, reserved, replicated). Pass nil as the key to hear every key and nil as the filter to hear every bag; then turn the bag name back into an id with GetPlayerFromStateBagName, GetLotFromStateBagName or GetEntityFromStateBagName. Keep the returned cookie if you want to stop listening with RemoveStateBagChangeHandler.

server.luaLUA
AddStateBagChangeHandler('mood', nil, function(bagName, key, value)
    local player = GetPlayerFromStateBagName(bagName)
    if not player then
        return
    end
    if type(value) ~= 'string' or #value > 20 then
        SetTimeout(0, function()
            Player(player).state:set('mood', nil, true)
        end)
    end
end)

The server handler above cleans up bad client writes. It waits for SetTimeout(0, …) before correcting the value, because handlers run before the new value is stored – a correction made inside the handler would be overwritten right after.

Rules and limits

RuleDetails
ValuesStrings, numbers, booleans, vector3 and tables of those. nil deletes a key. Functions can't be stored.
Tables are copiesChanging a field of a table you read from a bag changes nothing. Change your own table and set the whole key again: GlobalState.queue = list.
SizeKeep a value below about 16 KB; the hard limit is 64 KB per key. Key names can be up to 128 characters.
Same valueSetting a key to the value it already has sends nothing and fires no handler.
OrderChanges and events from the server reach each player in the order you made them.
LifetimeA player's bag is deleted when they leave. Global, lot and entity bags live until the server restarts – save what must survive with KVP or the database and set it again in onResourceStart.
Who receivesEvery connected player receives every replicated key. Don't put secrets in replicated keys – use false for those.

Coming from FiveM

FiveMNeighborly
GlobalState, Player(src).state, LocalPlayer.state, Entity(ent).stateThe same, with the same :set(key, value, replicated).
AddStateBagChangeHandler(key, bagName, handler)The same arguments and the same timing.
Entities are networked game entitiesEntity(id) takes a Sim id or an object id (strings).
–Lot(zoneId).state for data attached to a lot.
Clients may write bags of entities they ownClients may only write their own player bag.
Routing buckets limit who receives entity bagsEvery player receives every replicated bag.

See them in real resources