# QBCore client functions

The signatures below are pinned to
[`client/functions.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/functions.lua).
Check the deployed commit before copying an example.

![QBCore API and client/server execution boundaries](/diagrams/core-object.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

## Complete current signature index

All functions in `QBCore.Functions` are also registered as client exports at the bottom of the
current file. The table records the implementation's actual return shape, including known
inconsistencies.

| Function | Signature | Return / behavior |
| --- | --- | --- |
| `CreateClientCallback` | `CreateClientCallback(name, cb)` | Registers callback; no return |
| `TriggerCallback` | `TriggerCallback(name, ...)` | Callback mode or awaited callback result |
| `GetPlayerData` | `GetPlayerData(cb)` | PlayerData when no callback; callback is invoked synchronously otherwise |
| `GetCoords` | `GetCoords(entity)` | `vector4` |
| `HasItem` | `HasItem(items, amount)` | boolean |
| `GetName` | `GetName()` | string |
| `LookAtEntity` | `LookAtEntity(entity, timeout, speed)` | no success return; string on argument failure |
| `PlayAnim` | `PlayAnim(animDict, animName, upperbodyOnly, duration)` | animation duration on success; see notes below |
| `IsWearingGloves` | `IsWearingGloves()` | boolean |
| `Notify` | `Notify(text, texttype, length, icon)` | no return |
| `Progressbar` | `Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)` | no return |
| `GetVehicles` | `GetVehicles()` | vehicle handles |
| `GetObjects` | `GetObjects()` | object handles |
| `GetPlayers` | `GetPlayers()` | active client player indices |
| `GetPlayersFromCoords` | `GetPlayersFromCoords(coords, distance)` | nearby player indices |
| `GetClosestPlayer` | `GetClosestPlayer(coords)` | **currently `nil, distance` because of the source bug documented below** |
| `GetPeds` | `GetPeds(ignoreList)` | ped handles |
| `GetClosestPed` | `GetClosestPed(coords, ignoreList)` | ped handle, distance |
| `GetClosestVehicle` | `GetClosestVehicle(coords)` | vehicle handle, distance |
| `GetClosestObject` | `GetClosestObject(coords)` | object handle, distance |
| `LoadModel` | `LoadModel(model, timeout)` | loaded boolean, resolved hash |
| `SpawnVehicle` | `SpawnVehicle(model, cb, coords, isnetworked, teleportInto)` | no return; callback receives vehicle |
| `DeleteVehicle` | `DeleteVehicle(vehicle)` | no return |
| `GetPlate` | `GetPlate(vehicle)` | plate string or `nil` |
| `GetVehicleLabel` | `GetVehicleLabel(vehicle)` | localized label or `nil` |
| `GetVehicleProperties` | `GetVehicleProperties(vehicle)` | properties table when entity exists |
| `SetVehicleProperties` | `SetVehicleProperties(vehicle, props)` | applies supplied fields; no return |
| `DrawText` | `DrawText(x, y, width, height, scale, r, g, b, a, text)` | no return; marked unused upstream |
| `DrawText3D` | `DrawText3D(x, y, z, text)` | no return; marked unused upstream |
| `RequestAnimDict` | `RequestAnimDict(animDict, timeout)` | loaded boolean, dictionary name |
| `GetClosestBone` | `GetClosestBone(entity, list)` | bone entry, world coords, distance |
| `GetBoneDistance` | `GetBoneDistance(entity, boneType, boneIndex)` | distance |
| `AttachProp` | `AttachProp(ped, model, boneId, x, y, z, xR, yR, zR, vertex)` | prop entity handle |
| `SpawnClear` | `SpawnClear(coords, radius)` | boolean |
| `LoadAnimSet` | `LoadAnimSet(animSet, timeout)` | loaded boolean, anim-set name |
| `LoadParticleDictionary` | `LoadParticleDictionary(dictionary, timeout)` | loaded boolean, dictionary |
| `StartParticleAtCoord` | `StartParticleAtCoord(dict, ptName, looped, coords, rot, scale, alpha, color, duration)` | looped particle handle; `nil` for non-looped path |
| `StartParticleOnEntity` | `StartParticleOnEntity(dict, ptName, looped, entity, bone, offset, rot, scale, alpha, color, evolution, duration)` | looped particle handle; `nil` for non-looped path |
| `GetStreetNametAtCoords` | `GetStreetNametAtCoords(coords)` | `{ main, cross }`; upstream name contains the `Namet` typo |
| `GetZoneAtCoords` | `GetZoneAtCoords(coords)` | localized zone label |
| `GetCardinalDirection` | `GetCardinalDirection(entity)` | direction string |
| `GetCurrentTime` | `GetCurrentTime()` | time table |
| `GetGroundZCoord` | `GetGroundZCoord(coords)` | ground-adjusted `vector3`, original coords, or `nil` |
| `GetGroundHash` | `GetGroundHash(entity)` | material hash, hit entity, normal, end coords, success, retval |

`QBCore.Debug` is also defined in this file but is a top-level debug helper rather than a
`QBCore.Functions` member.

## Player, callbacks, and UI

| Function | Current signature |
| --- | --- |
| `CreateClientCallback` | `CreateClientCallback(name, callback)` |
| `TriggerCallback` | `TriggerCallback(name, ...)` |
| `GetPlayerData` | `GetPlayerData(callback)` |
| `HasItem` | `HasItem(items, amount)` → boolean |
| `GetName` | `GetName()` |
| `Notify` | `Notify(text, textType, length, icon)` |
| `Progressbar` | `Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)` |

### TriggerCallback

`TriggerCallback(name, ...)` works in two modes, decided by the type of the first variadic argument.

| Argument | Type | Meaning |
| --- | --- | --- |
| `name` | string | Callback name registered server side with `CreateCallback` |
| first vararg | function or any | A function is treated as the completion handler and removed from the argument list. Anything else is passed through to the server |
| remaining varargs | any | Forwarded to the server callback |

With a handler function it returns immediately and the handler runs later. Without one it blocks the
calling coroutine on `Citizen.Await` and returns the server's value directly:

```lua
-- callback style
QBCore.Functions.TriggerCallback('myresource:server:getState', function(state)
    if not state then return end
    QBCore.Functions.Notify(state.label, 'primary')
end)

-- awaiting style, only valid inside a coroutine such as CreateThread
CreateThread(function()
    local state = QBCore.Functions.TriggerCallback('myresource:server:getState')
    if state then print(state.label) end
end)
```

The pending-callback registry is `QBCore.ServerCallbacks[name]`, keyed by name alone. A second call
to the same callback name before the first resolves overwrites the first entry, so the first caller
never receives its result. Give each concurrent call its own callback name, or serialize them.

### GetPlayerData

`GetPlayerData(cb)` returns `QBCore.PlayerData` directly when `cb` is omitted, and otherwise invokes
`cb(QBCore.PlayerData)` synchronously. Both forms read the same local table, so neither waits for the
player to finish loading. Guard against an empty table early in the session.

### HasItem

`HasItem(items, amount)` is a thin wrapper over `exports['qb-inventory']:HasItem(items, amount)` at
this commit. It requires `qb-inventory` to be started, and its exact accepted shapes for `items` are
defined by that resource rather than by the core.

### Notify

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `text` | string or table | none | A string becomes the message. A table uses its `text` and `caption` fields, each falling back to `'Placeholder'` |
| `texttype` | string | `'primary'` | Notification style |
| `length` | number | `5000` | Milliseconds |
| `icon` | any | omitted | Only added to the NUI message when truthy |

```lua
QBCore.Functions.Notify('Delivery accepted', 'success', 3000)
QBCore.Functions.Notify({ text = 'Dispatch', caption = 'New call in Vespucci' }, 'primary')
```

### Progressbar

`Progressbar` is a wrapper over `exports['progressbar']:Progress`. It calls `error()` when the
`progressbar` resource is not started, so it is a hard dependency rather than an optional one. The
`name` argument is lowercased before being passed on. `onFinish` runs when the bar completes and
`onCancel` when it is cancelled.

```lua
QBCore.Functions.Progressbar('repair_vehicle', 'Repairing', 5000, false, true, {
    disableMovement = true,
    disableCarMovement = true,
    disableMouse = false,
    disableCombat = true,
}, {
    animDict = 'mini@repair',
    anim = 'fixing_a_ped',
    flags = 16,
}, {}, {}, function()
    TriggerServerEvent('myresource:server:repairFinished')
end, function()
    QBCore.Functions.Notify('Cancelled', 'error')
end)
```

## Entities and nearby-world queries

| Function | Current signature |
| --- | --- |
| `GetCoords` | `GetCoords(entity)` |
| `LookAtEntity` | `LookAtEntity(entity, timeout, speed)` |
| `GetPlayersFromCoords` | `GetPlayersFromCoords(coords, distance)` |
| `GetClosestPlayer` | `GetClosestPlayer(coords)` |
| `GetPeds` | `GetPeds(ignoreList)` |
| `GetClosestPed` | `GetClosestPed(coords, ignoreList)` |
| `GetClosestVehicle` | `GetClosestVehicle(coords)` |
| `GetClosestObject` | `GetClosestObject(coords)` |

Every one of these accepts `coords` as a vector3, as a table with `x`, `y`, `z`, or omitted. When
omitted, the local player's ped coordinates are used. A table is converted with `vec3(...)`, which
discards any heading.

| Function | Returns | Notes |
| --- | --- | --- |
| `GetCoords(entity)` | `vector4` | Position plus heading in `w` |
| `GetPlayers()` | table | A direct alias for `GetActivePlayers()`, so player indices, not server IDs |
| `GetPlayersFromCoords(coords, distance)` | table of player indices | `distance` defaults to `5` |
| `GetClosestPlayer(coords)` | see below | |
| `GetPeds(ignoreList)` | table of handles | |
| `GetClosestPed(coords, ignoreList)` | handle, distance | |
| `GetClosestVehicle(coords)` | handle, distance | Scans `GetGamePool('CVehicle')`, no range limit |
| `GetClosestObject(coords)` | handle, distance | Scans `GetGamePool('CObject')`, no range limit |

The closest-object and closest-vehicle functions have no model filter and no maximum range. They
return `-1` and `-1` when the pool is empty. Filter the returned entity yourself when a model
matters.

### GetClosestPlayer returns nil at this commit

Read the implementation before using this one. The function builds its result into a local named
`closestPlayer`, then returns a different identifier:

```lua
-- client/functions.lua, end of GetClosestPlayer
    return closestPed, closestDistance
```

`closestPed` is not declared anywhere in that function, so the first return value is always `nil`
while the second is the correct distance. Use `GetPlayersFromCoords` and pick the nearest yourself,
or call `GetClosestPed` when a ped handle is what you actually need:

```lua
local nearby = QBCore.Functions.GetPlayersFromCoords(nil, 5.0)
local closest, closestDistance = -1, -1
local myCoords = GetEntityCoords(PlayerPedId())
for i = 1, #nearby do
    if nearby[i] ~= PlayerId() then
        local distance = #(GetEntityCoords(GetPlayerPed(nearby[i])) - myCoords)
        if closestDistance == -1 or distance < closestDistance then
            closest, closestDistance = nearby[i], distance
        end
    end
end
```

`GetClosestPlayer` also ignores any range you might expect it to honour. It calls
`GetPlayersFromCoords(coords)` with no distance argument, so it only ever considers players within
the default 5 units.

Under OneSync Infinity, every function here iterates entities that exist on **this** client. Players
and entities outside the local focus zone are simply absent. See
[OneSync, scope, and networked entities](/docs/advanced/onesync) before using any of them as a
security or gameplay check.

## Vehicles and assets

| Function | Current signature |
| --- | --- |
| `LoadModel` | `LoadModel(model, timeout)` |
| `SpawnVehicle` | `SpawnVehicle(model, callback, coords, isNetworked, teleportInto)` |
| `DeleteVehicle` | `DeleteVehicle(vehicle)` |
| `GetPlate` | `GetPlate(vehicle)` |
| `GetVehicleLabel` | `GetVehicleLabel(vehicle)` |
| `GetVehicleProperties` | `GetVehicleProperties(vehicle)` |
| `SetVehicleProperties` | `SetVehicleProperties(vehicle, properties)` |

### LoadModel

`LoadModel(model, timeout)` accepts a model name or a hash, and `timeout` defaults to `5000`
milliseconds. It returns two values: whether the model is loaded, and the resolved hash.

It returns early with `true` if the model was already loaded, and returns `false` plus a console
warning when the model is neither valid nor in the game's image. It does not release the model, so
call `SetModelAsNoLongerNeeded` yourself when you are done.

```lua
local loaded, hash = QBCore.Functions.LoadModel('sultan', 10000)
if not loaded then return end
-- use hash, then release it
SetModelAsNoLongerNeeded(hash)
```

### SpawnVehicle

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `model` | string or hash | none | Converted with `joaat` when a string. The call returns early if `IsModelInCdimage` is false |
| `cb` | function | none | Invoked with the entity handle after creation. Optional |
| `coords` | vector4 | ped coordinates | See the note below |
| `isnetworked` | boolean | `true` | Only `false` disables networking, `nil` is treated as `true` |
| `teleportInto` | boolean | falsy | Warps the local ped into the driver seat |

Pass a **vector4**. The heading is read from `coords.w`, and a plain table argument is converted with
`vec3(...)`, which has no `w` component. The convenience of passing a table therefore costs you the
heading.

After creation the function sets the vehicle as player owned, allows network ID migration, clears the
hotwire requirement, turns the radio off, and sets fuel to 100.0. It returns nothing, so the callback
is the only way to get the handle.

```lua
QBCore.Functions.SpawnVehicle('sultan', function(vehicle)
    QBCore.Functions.SetVehicleProperties(vehicle, { fuelLevel = 100.0 })
end, GetEntityCoords(PlayerPedId()), true, true)
```

This creates the vehicle **on the client**. Under an entity lockdown bucket the creation is blocked.
For a vehicle the server owns, use the server-side creation functions instead, see
[Server functions](/docs/api/server-functions) and
[OneSync, scope, and networked entities](/docs/advanced/onesync).

### Other vehicle helpers

| Function | Behaviour |
| --- | --- |
| `DeleteVehicle(vehicle)` | Marks the entity as a mission entity first, then deletes it |
| `GetPlate(vehicle)` | Returns `nil` for handle `0`, otherwise the trimmed plate text |
| `GetVehicleLabel(vehicle)` | Returns `nil` for `nil` or `0`, otherwise the localized display name |

## Animations and props

### PlayAnim

The upstream signature and the upstream annotation above it disagree at this commit. The annotation
lists `duration` before `upperbodyOnly`. The function does not:

```lua
function QBCore.Functions.PlayAnim(animDict, animName, upperbodyOnly, duration)
```

Use the order in the `function` line. The third argument is the boolean.

| Parameter | Type | Meaning |
| --- | --- | --- |
| `animDict` | string | Must exist, checked with `DoesAnimDictExist` |
| `animName` | string | Must exist in the dictionary |
| `upperbodyOnly` | boolean | Sets flag `16` when true, otherwise `0` |
| `duration` | number | Milliseconds. `-1` or omitted plays indefinitely and forces flag `49` |

Behaviour worth knowing before you call it:

- It **blocks**. The function waits out the animation before returning, so call it from its own
  thread if anything else needs to run.
- It returns the animation duration in seconds on success. On failure it returns the rejected
  promise's value, which is `nil` rather than the error string.
- It calls `RemoveAnimDict` when finished, which affects any other script relying on that dictionary
  staying resident.

```lua
CreateThread(function()
    QBCore.Functions.PlayAnim('mp_common', 'givetake1_a', true, 2000)
end)
```

### LookAtEntity

`LookAtEntity(entity, timeout, speed)` turns the local ped toward an entity. Both numeric arguments
are clamped: `speed` above `5.0` becomes `5.0`, and `timeout` above `5000` becomes `5000`.

The annotation claims a number return. In practice the function returns nothing on success, and on a
failed argument check it returns a **string** built from `GetInvokingResource()` and a message.
Compare against `nil` rather than treating the result as a number.

It also blocks while turning, and `timeout` is a millisecond ceiling on that loop.

### IsWearingGloves

`IsWearingGloves()` returns a boolean by comparing the local ped's drawable variation at component 3
against `QBCore.Shared.MaleNoGloves` or `QBCore.Shared.FemaleNoGloves`. It branches on the exact
model `mp_m_freemode_01`, so any ped that is not one of the two freemode models falls into the
female table.

[qb-bankrobbery](/docs/resources/qb-bankrobbery) uses this to decide whether fingerprint evidence is
dropped.

## Everything else

Other current helpers cover props, particles, bones, ground coordinates, cardinal direction, time,
street names, and zones. One upstream identifier is misspelled as `GetStreetNametAtCoords(coords)`.
Use the exact exported name until the deployed source changes.
