# ESX.Game (/docs/es_extended/client/modules/game)

`ESX.Game` is the client toolbox for entities: spawning and deleting vehicles and objects, finding the closest ped, player or vehicle, teleporting, and reading or applying vehicle tuning. In ESX Legacy 1.16 these functions live in [esx_lib](/docs/core/esx_lib) (`xLib.game`, `xLib.entity`) and `es_extended` maps them onto `ESX.Game` for compatibility.

## Overview [#overview]

| | |
|---|---|
| Resource | `es_extended` (implemented in `esx_lib`) |
| Side | Client |
| Mapping | `es_extended/client/compat.lua` |
| Implementation | `esx_lib/imports/game/client.lua`, `esx_lib/imports/entity/client.lua` |

`coords` parameters accept a `vector3` or a table with `x`, `y`, `z`. `modelFilter` parameters are sets keyed by model hash, for example ``{ [`prop_atm_01`] = true }``.

## Spawning and deleting [#spawning-and-deleting]

### ESX.Game.SpawnVehicle [#esxgamespawnvehicle]

```lua
ESX.Game.SpawnVehicle(vehicleModel, coords, heading, cb, networked)
```

Loads the model, creates the vehicle, waits for collision and then returns it. The vehicle is unlocked for the player, does not need hotwiring and the radio is off.

| Name | Type | Description |
|---|---|---|
| `vehicleModel` | `string \| number` | Model name or hash. |
| `coords` | `vector3 \| table` | Spawn position. Must be within 424 units of the player. |
| `heading` | `number` | Heading in degrees. |
| `cb` | `function?` | `function(vehicle)`. Without it the function waits and returns the vehicle. |
| `networked` | `boolean?` | Default `true`. Pass `true` explicitly to also make the network id migratable and the vehicle a mission entity. |

**Returns:** `number?` vehicle handle when no `cb` is given.

```lua
local coords = GetOffsetFromEntityInWorldCoords(ESX.PlayerData.ped, 0.0, 5.0, 0.0)
local vehicle = ESX.Game.SpawnVehicle('sultan', coords, GetEntityHeading(ESX.PlayerData.ped))
TaskWarpPedIntoVehicle(ESX.PlayerData.ped, vehicle, -1)
```

Invalid models raise an error (or reject the internal promise when you use the return value).

### ESX.Game.SpawnLocalVehicle [#esxgamespawnlocalvehicle]

```lua
ESX.Game.SpawnLocalVehicle(vehicleModel, coords, heading, cb)
```

Same as `SpawnVehicle` with `networked = false`. Only the local player sees the vehicle, which is useful for showroom previews. **Returns:** nothing, use `cb`.

### ESX.Game.SpawnObject [#esxgamespawnobject]

```lua
ESX.Game.SpawnObject(object, coords, cb, networked)
```

| Name | Type | Description |
|---|---|---|
| `object` | `string \| number` | Model name or hash. |
| `coords` | `vector3 \| table` | Position. |
| `cb` | `function?` | `function(object)`. |
| `networked` | `boolean?` | Default `true`. |

**Returns:** the object handle, or the return value of `cb` when you pass one.

```lua
local coords = GetEntityCoords(ESX.PlayerData.ped)
local cone = ESX.Game.SpawnObject('prop_roadcone02a', coords)
PlaceObjectOnGroundProperly(cone)
```

### ESX.Game.SpawnLocalObject [#esxgamespawnlocalobject]

```lua
ESX.Game.SpawnLocalObject(object, coords, cb)
```

Spawns a non-networked object. **Returns:** nothing, use `cb`.

### ESX.Game.DeleteVehicle [#esxgamedeletevehicle]

```lua
ESX.Game.DeleteVehicle(vehicle)
```

Marks the vehicle as mission entity and deletes it. The client must own the entity for the delete to replicate.

### ESX.Game.DeleteObject [#esxgamedeleteobject]

```lua
ESX.Game.DeleteObject(object)
```

Marks the object as mission entity and deletes it.

### ESX.Game.Teleport [#esxgameteleport]

```lua
ESX.Game.Teleport(entity, coords, cb)
```

Requests collision at the target, waits until it is loaded, then moves the entity and sets its heading.

| Name | Type | Description |
|---|---|---|
| `entity` | `number` | Entity handle, usually the player ped. |
| `coords` | `vector3 \| vector4 \| table` | Target. Heading is read from `w` or `heading`, default `0.0`. |
| `cb` | `function?` | Called when done. |

```lua
ESX.Game.Teleport(ESX.PlayerData.ped, vector4(-1037.7, -2737.9, 20.2, 330.0), function()
    ESX.ShowNotification('Welcome to Los Santos')
end)
```

### ESX.Game.GetPedMugshot [#esxgamegetpedmugshot]

```lua
ESX.Game.GetPedMugshot(ped, transparent)
```

Registers a ped headshot and waits until it is ready.

| Name | Type | Description |
|---|---|---|
| `ped` | `number` | Ped handle. |
| `transparent` | `boolean?` | Use a transparent background. |

**Returns:** `mugshot` handle and `txd` string, or nothing if the ped does not exist. Free it with `UnregisterPedheadshot(mugshot)` when you are done.

```lua
local mugshot, txd = ESX.Game.GetPedMugshot(ESX.PlayerData.ped)
ESX.ShowAdvancedNotification('LSPD', 'ID check', 'Identity verified', txd, 1, false, true)
UnregisterPedheadshot(mugshot)
```

## Entity pools [#entity-pools]

### ESX.Game.GetObjects [#esxgamegetobjects]

```lua
ESX.Game.GetObjects()
```

**Returns:** `number[]` from `GetGamePool('CObject')`.

### ESX.Game.GetPeds [#esxgamegetpeds]

```lua
ESX.Game.GetPeds(onlyOtherPeds)
```

**Returns:** `number[]` from `GetGamePool('CPed')`, without the local player ped when `onlyOtherPeds` is `true`.

### ESX.Game.GetVehicles [#esxgamegetvehicles]

```lua
ESX.Game.GetVehicles()
```

**Returns:** `number[]` from `GetGamePool('CVehicle')`.

### ESX.Game.GetPlayers [#esxgamegetplayers]

```lua
ESX.Game.GetPlayers(onlyOtherPlayers, returnKeyValue, returnPeds)
```

| Name | Type | Description |
|---|---|---|
| `onlyOtherPlayers` | `boolean?` | Exclude the local player. |
| `returnKeyValue` | `boolean?` | Return `{ [playerIndex] = ped }`. |
| `returnPeds` | `boolean?` | Return peds instead of player indexes (array mode only). |

**Returns:** `table`. Only players whose ped exists (in scope) are included.

## Closest entity [#closest-entity]

All "closest" functions use the player position when `coords` is `nil` and return `-1, -1` when nothing is found.

### ESX.Game.GetClosestEntity [#esxgamegetclosestentity]

```lua
ESX.Game.GetClosestEntity(entities, isPlayerEntities, coords, modelFilter)
```

| Name | Type | Description |
|---|---|---|
| `entities` | `table` | Entity list. For players a `{ [playerIndex] = ped }` table. |
| `isPlayerEntities` | `boolean` | Return the table key (player index) instead of the entity. |
| `coords` | `vector3? \| table?` | Search origin. |
| `modelFilter` | `table?` | Model hash set. |

**Returns:** `entity`, `distance`

### ESX.Game.GetClosestObject [#esxgamegetclosestobject]

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

**Returns:** object handle and distance.

```lua
local atm, distance = ESX.Game.GetClosestObject(nil, {
    [`prop_atm_01`] = true,
    [`prop_atm_02`] = true,
    [`prop_fleeca_atm`] = true,
})

if atm ~= -1 and distance < 1.5 then
    OpenBankMenu()
end
```

### ESX.Game.GetClosestPed [#esxgamegetclosestped]

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

**Returns:** ped handle and distance. The local player ped is excluded.

### ESX.Game.GetClosestPlayer [#esxgamegetclosestplayer]

```lua
ESX.Game.GetClosestPlayer(coords)
```

**Returns:** client player index and distance. The local player is excluded. There is no model filter.

```lua
local player, distance = ESX.Game.GetClosestPlayer()

if player ~= -1 and distance <= 3.0 then
    TriggerServerEvent('police:handcuff', GetPlayerServerId(player))
else
    ESX.ShowNotification('Nobody nearby', 'error')
end
```

### ESX.Game.GetClosestVehicle [#esxgamegetclosestvehicle]

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

**Returns:** vehicle handle and distance.

### ESX.Game.GetPlayersInArea [#esxgamegetplayersinarea]

```lua
ESX.Game.GetPlayersInArea(coords, maxDistance)
```

**Returns:** array of client player indexes within `maxDistance` (local player excluded).

### ESX.Game.GetVehiclesInArea [#esxgamegetvehiclesinarea]

```lua
ESX.Game.GetVehiclesInArea(coords, maxDistance)
```

**Returns:** array of vehicle handles within `maxDistance`.

### ESX.Game.IsSpawnPointClear [#esxgameisspawnpointclear]

```lua
ESX.Game.IsSpawnPointClear(coords, maxDistance)
```

**Returns:** `true` when no vehicle is within `maxDistance` of `coords`.

```lua
local spot = vector3(229.7, -800.1, 30.6)

if ESX.Game.IsSpawnPointClear(spot, 3.0) then
    ESX.Game.SpawnVehicle('blista', spot, 160.0)
else
    ESX.ShowNotification('The parking spot is blocked', 'error')
end
```

### ESX.Game.GetVehicleInDirection [#esxgamegetvehicleindirection]

```lua
ESX.Game.GetVehicleInDirection()
```

Casts a short ray from the camera.

**Returns:** `vehicle`, `coords` of the hit when the ray hits a vehicle, otherwise nothing.

### ESX.Game.IsVehicleEmpty [#esxgameisvehicleempty]

```lua
ESX.Game.IsVehicleEmpty(vehicle)
```

**Returns:** `true` when the vehicle has no passengers and the driver seat is free.

### EnumerateEntitiesWithinDistance [#enumerateentitieswithindistance]

```lua
EnumerateEntitiesWithinDistance(entities, isPlayerEntities, coords, maxDistance)
```

Global helper (no `ESX.` prefix) that returns every entity (or player key) within `maxDistance`.

## Vehicle properties [#vehicle-properties]

### ESX.Game.GetVehicleProperties [#esxgamegetvehicleproperties]

```lua
ESX.Game.GetVehicleProperties(vehicle)
```

Reads the full state of a vehicle into a table you can store in `owned_vehicles.vehicle`.

**Returns:** `table|nil` (`nil` if the vehicle does not exist).

| Group | Keys |
|---|---|
| Identity | `model`, `plate` (trimmed), `plateIndex` |
| Condition | `bodyHealth`, `engineHealth`, `tankHealth`, `fuelLevel`, `oilLevel`, `dirtLevel`, `paintFade` |
| Damage | `doorsBroken`, `doorsAngleRatio`, `windowsBroken`, `tyreBurst`, `tyreBurstComplete`, `wheelHealth`, `wheelsBroken`, `tyresCanBurst`, `driftTyres` |
| Paint | `color1`, `color2` (number or RGB table), `paintType1`, `paintType2`, `pearlescentColor`, `wheelColor`, `dashboardColor`, `interiorColor` |
| Wheels and lights | `wheels`, `wheelSize`, `wheelWidth`, `windowTint`, `xenonColor`, `customXenonColor`, `customXenonColorEnabled`, `neonEnabled`, `neonColor`, `tyreSmokeColor` |
| Other | `roofState`, `extras` |
| Mods | `modSpoilers` ... `modLightbar` (one key per mod slot, for example `modEngine`, `modBrakes`, `modTransmission`, `modSuspension`, `modArmor`), toggles `modNitrous`, `modTurbo`, `modSubwoofer`, `modSmokeEnabled`, `modHydraulics`, `modXenon`, plus `modCustomFrontWheels`, `modCustomBackWheels`, `modRoofLivery`, `modDoorR`, `modLivery`, `modLiveryIndex`, `livery` |

Damage tables are keyed by index as string (`'0'`, `'1'`, ...), so they survive JSON encoding.

```lua
local vehicle = GetVehiclePedIsIn(ESX.PlayerData.ped, false)
local props = ESX.Game.GetVehicleProperties(vehicle)

if props then
    TriggerServerEvent('garage:store', props.plate, props)
end
```

### ESX.Game.SetVehicleProperties [#esxgamesetvehicleproperties]

```lua
ESX.Game.SetVehicleProperties(vehicle, props)
```

Applies a properties table. Only keys present in `props` are changed. Sets the mod kit and waits up to 5 seconds for mods to load. Must run in a thread.

| Name | Type | Description |
|---|---|---|
| `vehicle` | `number` | Vehicle handle. |
| `props` | `table` | Properties as returned by `GetVehicleProperties`. |

```lua
local function spawnOwnedPreview(props)
    local spawn = vector4(215.8, -810.1, 30.7, 157.0)

    ESX.Game.SpawnVehicle(props.model, spawn.xyz, spawn.w, function(vehicle)
        ESX.Game.SetVehicleProperties(vehicle, props)
    end)
end
```

For vehicles spawned on the server, setting the `VehicleProperties` state bag on the entity makes the owning client apply the properties automatically.

## Utilities [#utilities]

### ESX.Game.Utils.DrawText3D [#esxgameutilsdrawtext3d]

```lua
ESX.Game.Utils.DrawText3D(coords, text, size, font)
```

Draws text at a world position, scaled by camera distance and FOV. Call it every frame.

| Name | Type | Description |
|---|---|---|
| `coords` | `vector3 \| table` | World position. |
| `text` | `string` | Text. |
| `size` | `number?` | Scale factor, default `1`. |
| `font` | `number?` | Font id, default `0`. |

```lua
CreateThread(function()
    local npc = vector3(-265.0, -963.6, 31.2)
    while true do
        local sleep = 500
        if #(GetEntityCoords(ESX.PlayerData.ped) - npc) < 10.0 then
            sleep = 0
            ESX.Game.Utils.DrawText3D(npc + vector3(0.0, 0.0, 1.0), 'Job center')
        end
        Wait(sleep)
    end
end)
```

<Callout type="warn" title="Removed raycast helpers">
`ESX.Game.GetShapeTestResultSync`, `ESX.Game.RaycastScreen` and `ESX.Game.StartRaycasting` no longer exist in 1.16. `ESX.Game.StopRaycasting`, `ESX.Game.IsRaycastActive` and `ESX.Game.GetRaycastResult` remain only as compatibility stubs. Use the raycast module of [esx_lib](/docs/core/esx_lib) or the native `StartShapeTestLosProbe` instead.
</Callout>

## Related [#related]

- [Streaming](/docs/es_extended/client/modules/streaming)
- [OneSync server functions](/docs/es_extended/server/onesync)
- [Client functions](/docs/es_extended/client/functions)
- [esx_lib](/docs/core/esx_lib)