What Are State Bags?
State bags are a built-in FiveM feature for synchronizing data between the server and clients without writing custom event handlers. They provide a key-value store attached to entities, players, or the global state that automatically replicates changes across the network. When the server sets a value on a player state bag, all clients that need that information receive it automatically. This replaces the common pattern of manually triggering events to sync data and reduces boilerplate code significantly.
Player State Bags
Each connected player has a state bag accessible through Player(source).state on the server and LocalPlayer.state on the client. You can set any key-value pair on the player state, and it will synchronize to relevant clients automatically. This is perfect for data like duty status, job title, gang affiliation, or custom status indicators that other players or resources need to read. Set values on the server for security, and read them on the client for rendering UI elements or adjusting behavior based on player state.
Entity State Bags
Beyond players, every networked entity in FiveM can have state bag data attached to it. Access entity state with Entity(entityHandle).state on both client and server. This is useful for storing metadata on vehicles like fuel level, lock status, or ownership without maintaining separate tracking tables. When a player approaches a vehicle, the client can read its state bag to display fuel level on a HUD without requesting data from the server. Entity state bags persist as long as the entity exists and automatically clean up when the entity is removed.
Global State
GlobalState is a state bag shared across the entire server and all clients. Use it for server-wide settings like weather, time of day, event flags, or economy modifiers. When the server sets GlobalState.weather = 'rain', every connected client receives this update and can react accordingly. This is more efficient than broadcasting events to all players because state bags handle new player connections automatically. A player who joins mid-session immediately receives the current global state without requiring a separate sync event.
State Bag Handlers
You can react to state bag changes by registering handlers with AddStateBagChangeHandler. This function takes a key filter, a bag filter, and a callback that fires whenever the specified state changes. The handler receives the bag name, key, value, and other metadata. Use handlers to trigger visual effects when a player goes on duty, update UI when inventory data changes, or log state modifications for debugging. Handlers work on both client and server, giving you flexibility in where you process state updates.
Best Practices and Limitations
State bags are not designed for high-frequency updates. Setting state bag values triggers network synchronization, so avoid updating them every frame. Use them for data that changes occasionally like status flags, configuration values, and metadata rather than constantly changing values like position or velocity. Keep stored values small and serializable since they travel over the network. When you need complex objects, flatten them into simple key-value pairs or use JSON strings. Always set state from the server when the data needs to be authoritative to prevent client-side manipulation.