# OneSync Functions (/docs/es_extended/server/onesync)

`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.

## Overview [#overview]

| Fact | Value |
| --- | --- |
| Side | Server |
| Requires | OneSync (`set onesync on` in `server.cfg`) |
| Area functions | Implemented in [esx_lib](/docs/core/esx_lib) (`xLib.onesync`), exposed on `ESX.OneSync` |
| Spawn functions | `es_extended/server/modules/onesync.lua` |
| Return values | Network IDs, not entity handles |

## Players [#players]

### GetPlayersInArea [#getplayersinarea]

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

| Name | Type | Description |
| --- | --- | --- |
| `source` | `number` or `vector3` | A player ID (uses their ped position) or coordinates. |
| `maxDistance` | `number?` | Radius. Default `100`. |
| `ignore` | `table?` | `{ [playerId] = true }` for players to skip. |
| `routingBucket` | `number?` | Only include players in this routing bucket. |

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

```lua
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
```

### GetClosestPlayer [#getclosestplayer]

```lua
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.

```lua
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 area [#entities-in-an-area]

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

### GetPedsInArea [#getpedsinarea]

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

| Name | Type | Description |
| --- | --- | --- |
| `coords` | `vector3`, `table` or `number` | Center, or a player ID to use their position. |
| `maxDistance` | `number?` | Radius. Without it, every matching ped on the server is returned. |
| `modelFilter` | `table?` | `{ [modelHash] = true }`. Only these models are returned. |

Player peds are excluded.

**Returns:** `number[]`, network IDs.

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

### GetObjectsInArea [#getobjectsinarea]

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

Same parameters and return value as `GetPedsInArea`, for objects.

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

### GetVehiclesInArea [#getvehiclesinarea]

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

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

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

## Closest entity [#closest-entity]

These search within a fixed radius of 100 units.

### GetClosestPed [#getclosestped]

```lua
ESX.OneSync.GetClosestPed(coords, modelFilter)
```

| Name | Type | Description |
| --- | --- | --- |
| `coords` | `vector3`, `table` or `number` | Center, or a player ID. |
| `modelFilter` | `table?` | `{ [modelHash] = true }` allow-list. |

**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))`.

### GetClosestObject [#getclosestobject]

```lua
ESX.OneSync.GetClosestObject(coords, modelFilter)
```

Same as `GetClosestPed`, for objects.

### GetClosestVehicle [#getclosestvehicle]

```lua
ESX.OneSync.GetClosestVehicle(coords, modelFilter)
```

Same as `GetClosestPed`, for vehicles.

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

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

## Spawning entities [#spawning-entities]

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.

### SpawnVehicle [#spawnvehicle]

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

| Name | Type | Description |
| --- | --- | --- |
| `model` | `string` or `number` | Model name or hash. |
| `coords` | `vector3` or `table` | Spawn position. |
| `heading` | `number` | Heading. |
| `properties` | `table` | Vehicle properties. Stored in the `VehicleProperties` entity state bag, which the client applies. Use `{}` for none. |
| `cb` | `function?` | `function(netId)`. You can also pass the vehicle type string here and skip the callback. |
| `vehicleType` | `string?` | `"automobile"`, `"bike"`, `"boat"`, `"heli"`, `"plane"`, `"submarine"`, `"trailer"` or `"train"`. Resolved with [`ESX.GetVehicleType`](/docs/es_extended/server/functions#getvehicletype) when omitted. |

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.

```lua
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)
```

<Callout type="warn">
Without `vehicleType`, ESX must ask a client for unknown models. If no player is online, the spawn fails. Pass the type for vehicles spawned at server start.
</Callout>

### SpawnObject [#spawnobject]

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

| Name | Type | Description |
| --- | --- | --- |
| `model` | `string` or `number` | Model name or hash. |
| `coords` | `vector3` or `table` | Position. |
| `heading` | `number` | Heading. |
| `cb` | `function?` | `function(netId)`. |

**Returns:** network ID when called without a callback.

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

### SpawnPed [#spawnped]

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

Same parameters as `SpawnObject`, creates a networked ped.

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

### SpawnPedInVehicle [#spawnpedinvehicle]

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

| Name | Type | Description |
| --- | --- | --- |
| `model` | `string` or `number` | Ped model. |
| `vehicle` | `number` | Vehicle **entity handle** (not a network ID). |
| `seat` | `number` | Seat index, `-1` is the driver. |
| `cb` | `function?` | `function(netId)`. |

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

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

## Common issues [#common-issues]

- **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.

## Related [#related]

- [Server functions](/docs/es_extended/server/functions)
- [xPlayer](/docs/es_extended/server/xplayer)
- [esx_lib](/docs/core/esx_lib)
- [Client game module](/docs/es_extended/client/modules/game)