OneSync and Entity System

OneSync is FiveM's networking technology that allows servers to support more than 32 players (up to 1024 players) using server-side entity management.

What is OneSync?

In normal mode, GTA V syncs entities via peer-to-peer OneSync, switching to a centralized server:

Normal: Player A <--> Player B (peer-to-peer)
OneSync: Player A --> Server --> Player B

Turn on OneSync

# server.cfg
set onesync on
# or
set onesync legacy # for compatibility mode

Entity Ownership

In OneSync, every entity (vehicle, ped, object) has an owner — client that controls that entity.

-- Check if we are the owner of the entity.
local function IsEntityOwner(entity)
    return NetworkGetEntityOwner(entity) == PlayerId()
end

-- Wait for ownership to transfer before doing anything.
local function WaitForOwnership(entity, timeout)
    local start = GetGameTimer()
    while NetworkGetEntityOwner(entity) ~= PlayerId() do
        if GetGameTimer() - start > (timeout or 5000) then
            return false
        end
        Citizen.Wait(100)
    end
    return true
end

State Bags — Share Data between Clients

State Bags is a feature that gives an entity/player a shared state that everyone can see.

-- Set state to entity
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
Entity(vehicle).state.fuel = 80.0
Entity(vehicle).state.locked = false
Entity(vehicle).state.ownerName = 'M2Dev'

-- Read state
local fuel = Entity(vehicle).state.fuel
local isLocked = Entity(vehicle).state.locked

-- State of player
LocalPlayer.state.isOnDuty = true
LocalPlayer.state.job = 'police'

-- Read the state of other players
local targetState = Player(targetPlayerId).state
print(targetState.job)

State Bag Change Handler

-- Detect when state changes
AddStateBagChangeHandler('fuel', nil, function(bagName, key, value, reserved, replicated)
    -- bagName = 'entity:N' or 'player:N'
    print(bagName .. ' fuel changed to: ' .. tostring(value))
end)

-- only entity
AddStateBagChangeHandler('locked', 'entity:' .. NetworkGetNetworkIdFromEntity(myVehicle),
    function(bagName, key, value)
        if value then
            LockVehicle()
        else
            UnlockVehicle()
        end
    end
)

Server-Side Entity Creation

In OneSync, we recommend creating server-side entities:

-- server.lua
local function CreateServerVehicle(model, coords, heading)
    local vehicle = CreateVehicle(
        GetHashKey(model),
        coords.x, coords.y, coords.z,
        heading,
        true, -- network
        false -- thisScriptCheck
    )
    
    -- Set state
    Entity(vehicle).state.fuel = 100.0
    Entity(vehicle).state.serverCreated = true
    
    return vehicle
end

Network Events with OneSync

-- Send event to everyone in radius.
local function TriggerEventInRadius(eventName, coords, radius, ...)
    for _, playerId in ipairs(GetPlayers()) do
        local src = tonumber(playerId)
        local ped = GetPlayerPed(tostring(src))
        local playerCoords = GetEntityCoords(ped)
        
        if GetDistanceBetweenCoords(coords, playerCoords, true) <= radius then
            TriggerClientEvent(eventName, src, ...)
        end
    end
end

Summary

OneSync allows the server to support a large number of players. But you need to understand entity ownership and state bags in order to write scripts that work correctly.