State bags: concepts and basic usage

A state bag is a shared sticky note the network keeps in sync for you. Half the time you reach for TriggerClientEvent (an event that pushes data to clients), what you really want is one of these. It is a key/value blob stuck to an entity, a player, or the whole server. Set the value once on the server and every client sees it. Hook a handler and you get told the moment it changes.

You'll build: A qu_state_bags resource that sets a player's mood from a command, reads it back with a change handler and directly via LocalPlayer.state, and mirrors the same pattern onto a vehicle entity.
You'll learn: Entity state, Player state, and GlobalState; who can write each; how to react to changes with AddStateBagChangeHandler or read LocalPlayer.state directly; and when to reach for a database instead
Time: ~25 minutes
Prereqs: Events and trust and authority
Outcome: You can replace ad-hoc broadcast events with state bags, pick the right scope (entity vs player vs global), and know when state belongs in a database instead

BEFORE YOU START

Build it

Make the resource folder

The server has one folder for this lesson.

Inside your server's resources folder, create this folder:

code

resources/qu_state_bags

Create the files

Every file named in the manifest exists.

Create this exact file layout:

code

resources/qu_state_bags/
fxmanifest.lua
server.lua
client.lua

Write fxmanifest.lua

FiveM knows which files to load.

Open fxmanifest.lua and paste this:

code

fx_version 'cerulean'
game 'gta5'

server_script 'server.lua'
client_script 'client.lua'

Older tutorials add a lua54 'yes' line here. As of June 2025 that setting is deprecated and ignored: Lua 5.4 is now the only Lua runtime, so you leave it out.

Write the lesson code

The topic is now represented by runnable code.

Open server.lua and paste this:

code

RegisterCommand('setmood', function(src, args)
local mood = args[1] or 'calm'
Player(src).state:set('mood', mood, true)
print('[qu_state_bags] set mood ' .. mood .. ' on player ' .. src)
end, false)

Open client.lua and paste this:

code

local myBagName = ('player:%s'):format(GetPlayerServerId(PlayerId()))

AddStateBagChangeHandler('mood', myBagName, function(bagName, key, value)
print('[qu_state_bags] my mood is now ' .. tostring(value))
end)

Start and test it

The expected proof appears in the correct console.

Open server.cfg and add this line:

code

ensure qu_state_bags

Save. Then, in the txAdmin Live Console (or the FXServer console window), run:

code

ensure qu_state_bags

ensure starts the resource if it is not running yet and restarts it if it is, so it is the safe command for a resource you just added.

Join the server so you are a real player, then run this in the in-game chat box:

code

/setmood focused

Your server slot may be a different number than 1. The point is the same line appears on both sides: the server set it, the client received it.

Read the bag directly with LocalPlayer.state

You can read your own mood on demand, without waiting for a change handler.

Sometimes you do not want to react to a change, you just want the current value right now, for example inside a command or a HUD draw loop. LocalPlayer.state is a shortcut for "my own player state bag" that you can read like a plain table, no handler needed. Add this to client.lua:

code

RegisterCommand('mymood', function()
print('[qu_state_bags] my mood right now is ' .. tostring(LocalPlayer.state.mood))
end, false)

Run ensure qu_state_bags again to pick up the change, then in chat run /setmood happy followed by /mymood. The change handler from Step 5 still fires the moment /setmood runs; /mymood is a separate way to check the same value on demand, whenever you need it, without waiting for anything to change.

SERVER

job = police

CLIENT 1

job = police

CLIENT 2

job = police

CLIENT 3

job = police

A state bag replicates a value from its owner to everyone who can see it; readers never set it.

Keep reading the full lesson

Still ahead in this lesson

How it works
If something went wrong
What you can do now
Try it yourself