15 min read
QBCore client functions
The signatures below are pinned to
client/functions.lua.
Check the deployed commit before copying an example.
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:
-- 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 |
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.
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:
-- client/functions.lua, end of GetClosestPlayer
return closestPed, closestDistanceclosestPed 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:
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
endGetClosestPlayer 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 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.
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.
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 and OneSync, scope, and networked entities.
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:
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
nilrather than the error string. - It calls
RemoveAnimDictwhen finished, which affects any other script relying on that dictionary staying resident.
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 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.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
