State bags are FiveM's built-in system for synchronizing data between client and server without using events. They attach key-value pairs to entities, players, or the global scope, and automatically replicate changes.
Why Use State Bags?
Traditional FiveM development uses TriggerClientEvent and TriggerServerEvent to pass data. State bags are better when:
- Data needs to persist on an entity (vehicles, peds, objects)
- Multiple clients need to read the same value
- You want automatic replication without manual event handling
- You need data to survive entity ownership changes
Types of State Bags
Entity State
Attached to a networked entity (vehicle, ped, object):
-- Server or client
Entity(entity).state.locked = true
Entity(entity).state.fuel = 75.0
Player State
Attached to a player:
-- Server
Player(source).state.job = 'police'
Player(source).state.onDuty = true
Global State
Shared across all clients and server:
-- Server
GlobalState.weatherType = 'rain'
GlobalState.serverTime = 14
Reading State Bags
-- Client or server
local isLocked = Entity(vehicle).state.locked
local job = Player(playerId).state.job
local weather = GlobalState.weatherType
Listening for Changes
AddStateBagChangeHandler('locked', nil, function(bagName, key, value, reserved, replicated)
print('Lock state changed to: ' .. tostring(value))
end)
State Bags vs Events
| Feature | State Bags | Events |
|---|---|---|
| Persistent on entity | Yes | No |
| Auto-replication | Yes | Manual |
| Read anytime | Yes | Only when received |
| Multiple readers | Automatic | Must broadcast |
| Best for | Entity properties | One-time actions |
Performance Notes
- State bags have some network overhead per change
- Avoid setting state bags every frame
- Use events for one-off actions (animations, sounds)
- Use state bags for persistent properties (locked, fuel, job status)
FAQ
What are state bags in FiveM? A data synchronization system that attaches key-value pairs to entities, players, or global scope with automatic replication.
When should I use state bags instead of events? When data needs to persist on an entity or be readable by any client at any time.
Do state bags affect performance? Minimal impact for normal usage. Avoid rapid updates (every tick).
Related: fxmanifest.lua guide, ox_lib tutorial, FiveM resmon guide