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 Lua | Bag name | Attached to | Who may write |
|---|---|---|---|
GlobalState | global | The whole server | Server |
Player(id).stateLocalPlayer.state | player:12 | One connected player | Server, and that player for their own bag |
Lot(zoneId).state | lot:4821 | A lot | Server |
Entity(id).state | entity:90031 | A Sim or an object | Server |
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- Your server script sets a keyWith
replicated = true(or plain assignment on the server) the value is meant for everyone. Withfalseit never leaves the server – useful for data only the server needs. - Handlers run first, then the value is storedLike on FiveM,
AddStateBagChangeHandlerhandlers run just before the new value is stored. Inside a handler, the bag still has the old value; the new one is thevalueargument. - Every client receives itClients apply the change in the order it was made and run their own handlers, again just before storing.
- Everyone reads the same valueFrom now on
GlobalState.openistrueon the server and on every client.
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| Who | Call | Result |
|---|---|---|
| Server | bag:set(k, v, true) | Stored and sent to every client. |
| Server | bag:set(k, v, false) | Stored on the server only. Clients never see it. |
| Client | LocalPlayer.state:set(k, v, true) | Sent to the server, which stores it and passes it on to everyone else. |
| Client | LocalPlayer.state:set(k, v) | Stays on that PC only, until the server changes the key. |
| Client | Any other bag with true | Refused. 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.
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
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.
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
| Rule | Details |
|---|---|
| Values | Strings, numbers, booleans, vector3 and tables of those. nil deletes a key. Functions can't be stored. |
| Tables are copies | Changing 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. |
| Size | Keep a value below about 16 KB; the hard limit is 64 KB per key. Key names can be up to 128 characters. |
| Same value | Setting a key to the value it already has sends nothing and fires no handler. |
| Order | Changes and events from the server reach each player in the order you made them. |
| Lifetime | A 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 receives | Every connected player receives every replicated key. Don't put secrets in replicated keys – use false for those. |
Coming from FiveM
| FiveM | Neighborly |
|---|---|
GlobalState, Player(src).state, LocalPlayer.state, Entity(ent).state | The same, with the same :set(key, value, replicated). |
AddStateBagChangeHandler(key, bagName, handler) | The same arguments and the same timing. |
| Entities are networked game entities | Entity(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 own | Clients may only write their own player bag. |
| Routing buckets limit who receives entity bags | Every player receives every replicated bag. |
nb_lotcounter
nb_status
nb_scoreboard