OneSync Functions

ESX.OneSync groups server-side helpers that need OneSync: area searches that the server could otherwise not do without asking a client, and functions that spawn networked entities owned by the server. Use them when the server must decide where entities are, for example for anti-cheat checks, job vehicles or NPCs that should survive their creator leaving.

OverviewCopy Anchor Link

PlayersCopy Anchor Link

GetPlayersInAreaCopy Anchor Link

ESX.OneSync.GetPlayersInArea(source, maxDistance, ignore, routingBucket)

Returns: array of { id, ped, coords, dist }. ped is the network ID of the player's ped. Empty table if nobody is in range.

local nearby = ESX.OneSync.GetPlayersInArea(source, 15.0, { [source] = true })

for i = 1, #nearby do
    TriggerClientEvent("myscript:client:hearShot", nearby[i].id, nearby[i].dist)
end

GetClosestPlayerCopy Anchor Link

ESX.OneSync.GetClosestPlayer(source, maxDistance, ignore, routingBucket)

Same parameters as GetPlayersInArea. When source is a player ID, that player is skipped.

Returns: a single { id, ped, coords, dist } table, or an empty table if no player is in range.

local closest = ESX.OneSync.GetClosestPlayer(source, 3.0)

if closest.id then
    local xTarget = ESX.GetPlayerFromId(closest.id)
    -- e.g. search or cuff xTarget
end

Entities in an areaCopy Anchor Link

The model filter is an allow-list: when you pass { [joaat("model")] = true }, only entities with those models are returned.

GetPedsInAreaCopy Anchor Link

ESX.OneSync.GetPedsInArea(coords, maxDistance, modelFilter)

Player peds are excluded.

Returns: number[], network IDs.

local peds = ESX.OneSync.GetPedsInArea(vector3(-47.0, -1757.0, 29.4), 30.0)
print(("%d NPCs near the store"):format(#peds))

GetObjectsInAreaCopy Anchor Link

ESX.OneSync.GetObjectsInArea(coords, maxDistance, modelFilter)

Same parameters and return value as GetPedsInArea, for objects.

local atms = ESX.OneSync.GetObjectsInArea(source, 5.0, { [`prop_atm_01`] = true })

GetVehiclesInAreaCopy Anchor Link

ESX.OneSync.GetVehiclesInArea(coords, maxDistance, modelFilter)

Same parameters and return value as GetPedsInArea, for vehicles. The built-in /dv command uses it.

for _, netId in ipairs(ESX.OneSync.GetVehiclesInArea(coords, 10.0)) do
    local vehicle = NetworkGetEntityFromNetworkId(netId)
    if DoesEntityExist(vehicle) then DeleteEntity(vehicle) end
end

Closest entityCopy Anchor Link

These search within a fixed radius of 100 units.

GetClosestPedCopy Anchor Link

ESX.OneSync.GetClosestPed(coords, modelFilter)

Returns: netId, distance, coords. Player peds are skipped. If nothing is within 100 units, the distance stays 100 and the network ID does not point to a real entity, so check it with DoesEntityExist(NetworkGetEntityFromNetworkId(netId)).

GetClosestObjectCopy Anchor Link

ESX.OneSync.GetClosestObject(coords, modelFilter)

Same as GetClosestPed, for objects.

GetClosestVehicleCopy Anchor Link

ESX.OneSync.GetClosestVehicle(coords, modelFilter)

Same as GetClosestPed, for vehicles.

local netId, distance = ESX.OneSync.GetClosestVehicle(source)

if distance < 5.0 then
    local vehicle = NetworkGetEntityFromNetworkId(netId)
    print("Closest plate: " .. GetVehicleNumberPlateText(vehicle))
end

Spawning entitiesCopy Anchor Link

All spawn functions work in two modes. With a callback, they return immediately and call cb(netId) later (cb(false) on failure). Without a callback, they yield the current thread and return the network ID; a failure then raises an error, so wrap the call in pcall if you need to handle it.

SpawnVehicleCopy Anchor Link

ESX.OneSync.SpawnVehicle(model, coords, heading, properties, cb, vehicleType)

Uses CreateVehicleServerSetter and sets the orphan mode so the vehicle is not deleted when its owner leaves.

Returns: network ID when called without a callback.

local netId = ESX.OneSync.SpawnVehicle("police", vector3(452.0, -1019.0, 28.4), 90.0, { plate = "LSPD 01" }, "automobile")
local vehicle = NetworkGetEntityFromNetworkId(netId)
TaskWarpPedIntoVehicle(GetPlayerPed(source), vehicle, -1)

SpawnObjectCopy Anchor Link

ESX.OneSync.SpawnObject(model, coords, heading, cb)

Returns: network ID when called without a callback.

ESX.OneSync.SpawnObject("prop_roadcone02a", coords, 0.0, function(netId)
    if not netId then return end
    FreezeEntityPosition(NetworkGetEntityFromNetworkId(netId), true)
end)

SpawnPedCopy Anchor Link

ESX.OneSync.SpawnPed(model, coords, heading, cb)

Same parameters as SpawnObject, creates a networked ped.

local netId = ESX.OneSync.SpawnPed("s_m_y_cop_01", vector3(441.0, -978.0, 30.7), 180.0)

SpawnPedInVehicleCopy Anchor Link

ESX.OneSync.SpawnPedInVehicle(model, vehicle, seat, cb)

Returns: network ID of the ped when called without a callback.

local vehNet = ESX.OneSync.SpawnVehicle("taxi", coords, heading, {}, "automobile")
local vehicle = NetworkGetEntityFromNetworkId(vehNet)
ESX.OneSync.SpawnPedInVehicle("a_m_y_stlat_01", vehicle, -1)

Common issuesCopy Anchor Link

• Working with the wrong handle: every function returns network IDs. Use NetworkGetEntityFromNetworkId before calling entity natives.
• Entities in other dimensions: only the player functions filter by routing bucket. Area and closest-entity searches cover all buckets.
• Spawned ped or object disappears: only SpawnVehicle calls SetEntityOrphanMode(entity, 2). Call it yourself on peds and objects that must persist when no player is near.

RelatedCopy Anchor Link

• Server functions
• xPlayer
• esx_lib
• Client game module

Frequently asked questions