QBCore Frameworkqbcore.netCommunity docs
On this page

15 min read

QBCore client functions

The signatures below are pinned to client/functions.lua. Check the deployed commit before copying an example.

QBCore API and client/server execution boundaries

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.

FunctionSignatureReturn / behavior
CreateClientCallbackCreateClientCallback(name, cb)Registers callback; no return
TriggerCallbackTriggerCallback(name, ...)Callback mode or awaited callback result
GetPlayerDataGetPlayerData(cb)PlayerData when no callback; callback is invoked synchronously otherwise
GetCoordsGetCoords(entity)vector4
HasItemHasItem(items, amount)boolean
GetNameGetName()string
LookAtEntityLookAtEntity(entity, timeout, speed)no success return; string on argument failure
PlayAnimPlayAnim(animDict, animName, upperbodyOnly, duration)animation duration on success; see notes below
IsWearingGlovesIsWearingGloves()boolean
NotifyNotify(text, texttype, length, icon)no return
ProgressbarProgressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)no return
GetVehiclesGetVehicles()vehicle handles
GetObjectsGetObjects()object handles
GetPlayersGetPlayers()active client player indices
GetPlayersFromCoordsGetPlayersFromCoords(coords, distance)nearby player indices
GetClosestPlayerGetClosestPlayer(coords)currently nil, distance because of the source bug documented below
GetPedsGetPeds(ignoreList)ped handles
GetClosestPedGetClosestPed(coords, ignoreList)ped handle, distance
GetClosestVehicleGetClosestVehicle(coords)vehicle handle, distance
GetClosestObjectGetClosestObject(coords)object handle, distance
LoadModelLoadModel(model, timeout)loaded boolean, resolved hash
SpawnVehicleSpawnVehicle(model, cb, coords, isnetworked, teleportInto)no return; callback receives vehicle
DeleteVehicleDeleteVehicle(vehicle)no return
GetPlateGetPlate(vehicle)plate string or nil
GetVehicleLabelGetVehicleLabel(vehicle)localized label or nil
GetVehiclePropertiesGetVehicleProperties(vehicle)properties table when entity exists
SetVehiclePropertiesSetVehicleProperties(vehicle, props)applies supplied fields; no return
DrawTextDrawText(x, y, width, height, scale, r, g, b, a, text)no return; marked unused upstream
DrawText3DDrawText3D(x, y, z, text)no return; marked unused upstream
RequestAnimDictRequestAnimDict(animDict, timeout)loaded boolean, dictionary name
GetClosestBoneGetClosestBone(entity, list)bone entry, world coords, distance
GetBoneDistanceGetBoneDistance(entity, boneType, boneIndex)distance
AttachPropAttachProp(ped, model, boneId, x, y, z, xR, yR, zR, vertex)prop entity handle
SpawnClearSpawnClear(coords, radius)boolean
LoadAnimSetLoadAnimSet(animSet, timeout)loaded boolean, anim-set name
LoadParticleDictionaryLoadParticleDictionary(dictionary, timeout)loaded boolean, dictionary
StartParticleAtCoordStartParticleAtCoord(dict, ptName, looped, coords, rot, scale, alpha, color, duration)looped particle handle; nil for non-looped path
StartParticleOnEntityStartParticleOnEntity(dict, ptName, looped, entity, bone, offset, rot, scale, alpha, color, evolution, duration)looped particle handle; nil for non-looped path
GetStreetNametAtCoordsGetStreetNametAtCoords(coords){ main, cross }; upstream name contains the Namet typo
GetZoneAtCoordsGetZoneAtCoords(coords)localized zone label
GetCardinalDirectionGetCardinalDirection(entity)direction string
GetCurrentTimeGetCurrentTime()time table
GetGroundZCoordGetGroundZCoord(coords)ground-adjusted vector3, original coords, or nil
GetGroundHashGetGroundHash(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

FunctionCurrent signature
CreateClientCallbackCreateClientCallback(name, callback)
TriggerCallbackTriggerCallback(name, ...)
GetPlayerDataGetPlayerData(callback)
HasItemHasItem(items, amount) → boolean
GetNameGetName()
NotifyNotify(text, textType, length, icon)
ProgressbarProgressbar(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.

ArgumentTypeMeaning
namestringCallback name registered server side with CreateCallback
first varargfunction or anyA function is treated as the completion handler and removed from the argument list. Anything else is passed through to the server
remaining varargsanyForwarded 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

ParameterTypeDefaultMeaning
textstring or tablenoneA string becomes the message. A table uses its text and caption fields, each falling back to 'Placeholder'
texttypestring'primary'Notification style
lengthnumber5000Milliseconds
iconanyomittedOnly 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

FunctionCurrent signature
GetCoordsGetCoords(entity)
LookAtEntityLookAtEntity(entity, timeout, speed)
GetPlayersFromCoordsGetPlayersFromCoords(coords, distance)
GetClosestPlayerGetClosestPlayer(coords)
GetPedsGetPeds(ignoreList)
GetClosestPedGetClosestPed(coords, ignoreList)
GetClosestVehicleGetClosestVehicle(coords)
GetClosestObjectGetClosestObject(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.

FunctionReturnsNotes
GetCoords(entity)vector4Position plus heading in w
GetPlayers()tableA direct alias for GetActivePlayers(), so player indices, not server IDs
GetPlayersFromCoords(coords, distance)table of player indicesdistance defaults to 5
GetClosestPlayer(coords)see below
GetPeds(ignoreList)table of handles
GetClosestPed(coords, ignoreList)handle, distance
GetClosestVehicle(coords)handle, distanceScans GetGamePool('CVehicle'), no range limit
GetClosestObject(coords)handle, distanceScans 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, 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:

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 before using any of them as a security or gameplay check.

Vehicles and assets

FunctionCurrent signature
LoadModelLoadModel(model, timeout)
SpawnVehicleSpawnVehicle(model, callback, coords, isNetworked, teleportInto)
DeleteVehicleDeleteVehicle(vehicle)
GetPlateGetPlate(vehicle)
GetVehicleLabelGetVehicleLabel(vehicle)
GetVehiclePropertiesGetVehicleProperties(vehicle)
SetVehiclePropertiesSetVehicleProperties(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

ParameterTypeDefaultMeaning
modelstring or hashnoneConverted with joaat when a string. The call returns early if IsModelInCdimage is false
cbfunctionnoneInvoked with the entity handle after creation. Optional
coordsvector4ped coordinatesSee the note below
isnetworkedbooleantrueOnly false disables networking, nil is treated as true
teleportIntobooleanfalsyWarps 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

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

ParameterTypeMeaning
animDictstringMust exist, checked with DoesAnimDictExist
animNamestringMust exist in the dictionary
upperbodyOnlybooleanSets flag 16 when true, otherwise 0
durationnumberMilliseconds. -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.
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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website