ESX.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 (xLib.game, xLib.entity) and es_extended maps them onto ESX.Game for compatibility.

OverviewCopy Anchor Link

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 deletingCopy Anchor Link

ESX.Game.SpawnVehicleCopy Anchor Link

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.

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

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.SpawnLocalVehicleCopy Anchor Link

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.SpawnObjectCopy Anchor Link

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

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

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

ESX.Game.SpawnLocalObjectCopy Anchor Link

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

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

ESX.Game.DeleteVehicleCopy Anchor Link

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.DeleteObjectCopy Anchor Link

ESX.Game.DeleteObject(object)

Marks the object as mission entity and deletes it.

ESX.Game.TeleportCopy Anchor Link

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

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

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.GetPedMugshotCopy Anchor Link

ESX.Game.GetPedMugshot(ped, transparent)

Registers a ped headshot and waits until it is ready.

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

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

Entity poolsCopy Anchor Link

ESX.Game.GetObjectsCopy Anchor Link

ESX.Game.GetObjects()

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

ESX.Game.GetPedsCopy Anchor Link

ESX.Game.GetPeds(onlyOtherPeds)

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

ESX.Game.GetVehiclesCopy Anchor Link

ESX.Game.GetVehicles()

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

ESX.Game.GetPlayersCopy Anchor Link

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

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

Closest entityCopy Anchor Link

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

ESX.Game.GetClosestEntityCopy Anchor Link

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

Returns: entity, distance

ESX.Game.GetClosestObjectCopy Anchor Link

ESX.Game.GetClosestObject(coords, modelFilter)

Returns: object handle and distance.

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.GetClosestPedCopy Anchor Link

ESX.Game.GetClosestPed(coords, modelFilter)

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

ESX.Game.GetClosestPlayerCopy Anchor Link

ESX.Game.GetClosestPlayer(coords)

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

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.GetClosestVehicleCopy Anchor Link

ESX.Game.GetClosestVehicle(coords, modelFilter)

Returns: vehicle handle and distance.

ESX.Game.GetPlayersInAreaCopy Anchor Link

ESX.Game.GetPlayersInArea(coords, maxDistance)

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

ESX.Game.GetVehiclesInAreaCopy Anchor Link

ESX.Game.GetVehiclesInArea(coords, maxDistance)

Returns: array of vehicle handles within maxDistance.

ESX.Game.IsSpawnPointClearCopy Anchor Link

ESX.Game.IsSpawnPointClear(coords, maxDistance)

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

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.GetVehicleInDirectionCopy Anchor Link

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.IsVehicleEmptyCopy Anchor Link

ESX.Game.IsVehicleEmpty(vehicle)

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

EnumerateEntitiesWithinDistanceCopy Anchor Link

EnumerateEntitiesWithinDistance(entities, isPlayerEntities, coords, maxDistance)

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

Vehicle propertiesCopy Anchor Link

ESX.Game.GetVehiclePropertiesCopy Anchor Link

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

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

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.SetVehiclePropertiesCopy Anchor Link

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.

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.

UtilitiesCopy Anchor Link

ESX.Game.Utils.DrawText3DCopy Anchor Link

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

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

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)

RelatedCopy Anchor Link

• Streaming
• OneSync server functions
• Client functions
• esx_lib

Frequently asked questions