State Bags vs Events in FiveM: Syncing Vehicle and Player State the Simple Way

When crafting a FiveM script that requires all players to agree on a certain condition, such as a car being locked or a player being on duty, two primary methods exist: network events and state bags. While both methods serve the purpose, they cater to distinct requirements. Misusing one over the other can lead to inconsistencies where one player sees a car locked while another perceives it as unlocked. This article delves into the differences between these methods with concise Lua examples.

The primary distinction lies in their functionality: events send notifications about occurrences, with the server announcing what has just taken place, and each connected client reacts accordingly. If a client was not online during the event or the affected entity is not loaded on their server, they won't receive the information.

On the other hand, state bags store values that are tied to an entity, player, or the entire server. These values remain consistent for clients that join later since they read from the stored value rather than waiting for a message. A helpful guideline is: if you're detailing an event that has occurred, utilize an event. Conversely, if you're describing the current state of something, employ a state bag.

There are three types of state bags:

1. Entity(entity).state: linked to networked entities like vehicles, NPCs, or objects.

2. Entity state bags utilize OneSync, which is commonly employed on roleplay servers.

3. Player(source).state on the server, LocalPlayer.state on the client: associated with players.

4. GlobalState: server-wide values accessible by every client. It's advisable to store simple data types such as strings, numbers, booleans, and small tables. Functions, however, cannot be stored, and large tables that frequently change are not advisable.

For instance, when toggling vehicle locks with an event, the code looks like this on the server:

RegisterNetEvent("locks:toggle")

function toggleLocked(netId) TriggerClientEvent("locks:apply", -1, netId, true) end

And the client-side code:

RegisterNetEvent("locks:apply")

function applyLocked(netId, locked) local veh = NetToVeh(netId)

if veh ~= 0 then SetVehicleDoorsLocked(veh, locked and 2 or 1) end end

However, this method falls short if a player enters the area after the event or joins later. They won't receive the message, resulting in open doors for them. To rectify this, callbacks can be used to manually manage the state bags.

Contrastingly, implementing locks with state bags on the server involves:

RegisterNetEvent("locks:toggle")

function toggleLocked(netId)

local src = source

local veh = NetworkGetEntityFromNetworkId(netId)

if veh == 0 or not DoesEntityExist(veh) then return end

local locked = not Entity(veh).state.locked

Entity(veh).state:set("locked", locked, true)

end

On the client-side, listening for changes happens as follows:

AddStateBagChangeHandler("locked", nil, function(bagName, key, value)

local veh = GetEntityFromStateBagName(bagName)

if veh == 0 then return end

SetVehicleDoorsLocked(veh, value and 2 or 1)

end)

Key considerations for this method include using the value argument instead of Entity(veh).state.locked and acknowledging that GetEntityFromStateBagName returns 0 if the entity hasn't been loaded on the client yet. When the entity streams in, the state bag will already have the updated value, allowing the script to read Entity(veh).state.locked when the player attempts to enter.

Similar applications of state bags include tracking player duty status on the server:

setDuty(src, onDuty) Player(src).state:set("onDuty", onDuty, true)

Players can verify their duty status on their client with LocalPlayer.state.onDuty, enabling job menus to show or hide as needed. For server-wide values like weather, time, or the state of a bank vault, GlobalState is suitable:

GlobalState:set("vaultOpen", false, true)

The client can then read GlobalState.vaultOpen to display or hide vault interactions. While events remain effective for one-time actions, client requests, or effects that shouldn't repeat when a player streams in, combining both methods often yields the best results. Security is paramount when relying on state values set by the server; always validate client input as you would any other input.

Employ resource prefixes for keys to avoid collisions, refrain from writing to state bags every frame, and keep values simple, preferably as booleans or numbers. This approach ensures a seamless experience, as evidenced by resources like xFiveM Shop, which openly share their scripts for review.