10 min read
QBCore server functions
These signatures are pinned to
server/functions.lua.
Conceptual diagram; verify the behavior against your installed resource version.
Complete current signature index
| Function | Signature | Return / behavior |
|---|---|---|
GetCoords | GetCoords(entity) | vector4 |
GetIdentifier | GetIdentifier(source, idtype) | identifier string or nil |
GetSource | GetSource(identifier) | source, or 0 |
GetPlayer | GetPlayer(source) | online Player or nil |
GetPlayerByCitizenId | GetPlayerByCitizenId(citizenid) | online Player or nil |
GetOfflinePlayerByCitizenId | GetOfflinePlayerByCitizenId(citizenid) | offline Player interface or nil |
GetPlayerByLicense | GetPlayerByLicense(license) | online Player or nil |
GetPlayerByPhone | GetPlayerByPhone(number) | online Player or nil |
GetPlayerByAccount | GetPlayerByAccount(account) | online Player or nil |
GetPlayerByCharInfo | GetPlayerByCharInfo(property, value) | online Player or nil |
GetPlayers | GetPlayers() | array of online sources |
GetQBPlayers | GetQBPlayers() | core Player map |
GetPlayersByJob | GetPlayersByJob(job, checkOnDuty) | source array, count |
GetPlayersOnDuty | GetPlayersOnDuty(job) | source array, count |
GetDutyCount | GetDutyCount(job) | count |
GetClosestPlayer | GetClosestPlayer(source, coords) | closest source, distance |
GetClosestObject | GetClosestObject(source, coords) | object handle, distance |
GetClosestVehicle | GetClosestVehicle(source, coords) | vehicle handle, distance |
GetClosestPed | GetClosestPed(source, coords) | ped handle, distance |
GetBucketObjects | GetBucketObjects() | player-bucket table, entity-bucket table |
SetPlayerBucket | SetPlayerBucket(source, bucket) | boolean |
SetEntityBucket | SetEntityBucket(entity, bucket) | boolean |
GetPlayersInBucket | GetPlayersInBucket(bucket) | source array |
GetEntitiesInBucket | GetEntitiesInBucket(bucket) | entity array |
SpawnVehicle | SpawnVehicle(source, model, coords, warp) | entity handle |
CreateAutomobile | CreateAutomobile(source, model, coords, warp) | entity handle |
CreateVehicle | CreateVehicle(source, model, vehtype, coords, warp) | entity handle |
TriggerClientCallback | TriggerClientCallback(name, source, ...) | callback/awaited result depending on call form |
CreateCallback | CreateCallback(name, cb) | registers callback; no return |
CreateUseableItem | CreateUseableItem(item, data) | registers usable item; no return |
CanUseItem | CanUseItem(item) | registered handler/data or nil |
UseItem | UseItem(source, item) | invokes registered handler |
Kick | Kick(source, reason, setKickReason, deferrals) | disconnect flow; no useful return |
IsWhitelisted | IsWhitelisted(source) | boolean ACE result |
AddPermission | AddPermission(source, permission) | adds runtime player.<source> principal |
RemovePermission | RemovePermission(source, permission) | removes runtime principal(s) |
HasPermission | HasPermission(source, permission) | boolean |
GetPermission | GetPermission(source) | map of configured permissions currently allowed |
IsOptin | IsOptin(source) | boolean |
ToggleOptin | ToggleOptin(source) | toggles admin-message opt-in |
IsPlayerBanned | IsPlayerBanned(source) | banned boolean, optional reason |
GetDatabaseInfo | GetDatabaseInfo() | parsed database connection info or nil |
IsLicenseInUse | IsLicenseInUse(license) | boolean |
HasItem | HasItem(source, items, amount) | boolean; deprecated wrapper |
Notify | Notify(source, text, type, length) | sends notification; no return |
The source annotations are not always exact. Where annotation and implementation disagree, this page describes the implementation and calls out high-impact differences below.
Player lookup
| Function | Current signature |
|---|---|
GetIdentifier | GetIdentifier(source, idType) |
GetSource | GetSource(identifier) → source or 0 |
GetPlayer | GetPlayer(source) |
GetPlayerByCitizenId | GetPlayerByCitizenId(citizenId) |
GetOfflinePlayerByCitizenId | GetOfflinePlayerByCitizenId(citizenId) |
GetPlayerByLicense | GetPlayerByLicense(license) |
GetPlayerByPhone | GetPlayerByPhone(number) |
GetPlayersByJob | GetPlayersByJob(job, checkOnDuty) |
GetDutyCount | GetDutyCount(job) |
Callbacks, usable items, and permissions
| Function | Current signature |
|---|---|
CreateCallback | CreateCallback(name, callback) |
TriggerClientCallback | TriggerClientCallback(name, source, [callback], ...) |
CreateUseableItem | CreateUseableItem(item, callback) |
CanUseItem | CanUseItem(item) → registration or nil |
UseItem | UseItem(source, item) |
HasItem | HasItem(source, items, amount) → boolean; deprecated in favor of the inventory export |
AddPermission | AddPermission(source, permission) |
RemovePermission | RemovePermission(source, permission) |
HasPermission | HasPermission(source, permission) |
GetPermission | GetPermission(source) |
QBCore.Functions.CreateCallback('myresource:server:getJob', function(source, callback)
local Player = QBCore.Functions.GetPlayer(source)
callback(Player and Player.PlayerData.job or nil)
end)World, vehicles, and buckets
Current world helpers include GetClosestPlayer, GetClosestObject, GetClosestVehicle, and
GetClosestPed. Vehicle creation functions are:
SpawnVehicle(source, model, coords, warp)→ entity handleCreateAutomobile(source, model, coords, warp)→ entity handleCreateVehicle(source, model, vehicleType, coords, warp)→ entity handle
Vehicle creation
All three vehicle functions are server side but not equal. The upstream comment above
SpawnVehicle states that the CreateVehicle RPC still performs creation on a client, so a player
has to be nearby. CreateAutomobile and CreateVehicle map onto the server-side creation natives.
See OneSync, scope, and networked entities for when that distinction
matters.
Routing buckets
The core keeps two module-level registries alongside the native calls:
| Table | Key | Value |
|---|---|---|
QBCore.Player_Buckets | the player's license identifier | { id = source, bucket = bucket } |
QBCore.Entity_Buckets | the entity handle | { id = entity, bucket = bucket } |
Both are plain Lua tables in the core's server state. They are a convenience index over the natives, not the authority. The routing bucket itself is owned by the server runtime.
Signatures
| Function | Signature | Returns |
|---|---|---|
GetBucketObjects | GetBucketObjects() | Two tables: the player registry, then the entity registry |
SetPlayerBucket | SetPlayerBucket(source, bucket) | true on success, false when either argument is falsy |
SetEntityBucket | SetEntityBucket(entity, bucket) | true on success, false when either argument is falsy |
GetPlayersInBucket | GetPlayersInBucket(bucket) | Array of player sources |
GetEntitiesInBucket | GetEntitiesInBucket(bucket) | Array of entity handles |
The upstream annotations on the two getters say table|boolean. The implementations always return a
table, empty when nothing matches. Test with #result == 0, not with if not result.
SetPlayerBucket does two things
function QBCore.Functions.SetPlayerBucket(source, bucket)
if source and bucket then
local plicense = QBCore.Functions.GetIdentifier(source, 'license')
Player(source).state:set('instance', bucket, true)
SetPlayerRoutingBucket(source, bucket)
QBCore.Player_Buckets[plicense] = { id = source, bucket = bucket }
return true
else
return false
end
endBesides calling the native, it writes the bucket ID into the player's state bag under the key
instance with replication enabled. Client scripts can therefore read the current bucket without a
round trip:
-- client side
local instance = LocalPlayer.state.instanceThat also means any other resource writing to instance on the same state bag will disagree with
the actual routing bucket. Pick one owner for that key.
Note the guard is if source and bucket. Bucket 0, the default bucket, is truthy in Lua, so
returning a player to bucket 0 works. A nil bucket returns false without changing anything.
Cleanup differs between the two registries
QBCore.Player_Buckets is cleared for a player in the playerDropped handler in
server/events.lua, keyed by the license on their PlayerData.
QBCore.Entity_Buckets has no cleanup anywhere in the core at this commit. Entries persist after the
entity is deleted, so GetEntitiesInBucket can return stale handles. Validate before use:
local entities = QBCore.Functions.GetEntitiesInBucket(4)
for i = 1, #entities do
if DoesEntityExist(entities[i]) then
-- safe to act on this handle
end
endIf your resource creates and destroys many entities inside buckets, clear your own entries or track them yourself rather than relying on this table.
Reading a bucket back
GetPlayersInBucket scans the core's registry, so it only knows about players moved through
SetPlayerBucket. A player moved with the native SetPlayerRoutingBucket directly is invisible to
it. The natives GET_PLAYER_ROUTING_BUCKET and GET_ENTITY_ROUTING_BUCKET read the real value.
Using a bucket as an instance
What a bucket is for, which use cases the Cfx.re documentation names, why it says interiors are not among them, and the four lockdown modes are covered once in OneSync, scope, and networked entities. Read that before designing around buckets. What follows is only how the core wrappers are used.
-- server side, an isolated instance a player cannot spawn into
local BUCKET = 42
SetRoutingBucketEntityLockdownMode(BUCKET, 'strict')
SetRoutingBucketPopulationEnabled(BUCKET, false)
QBCore.Functions.SetPlayerBucket(source, BUCKET)
local vehicle = CreateVehicleServerSetter(joaat('blista'), 'automobile', 0.0, 0.0, 72.0, 0.0)
QBCore.Functions.SetEntityBucket(vehicle, BUCKET)Remember to move the player back, and to delete the entities and forget their registry entries, when the instance ends.
The core does not currently expose GetItems, GetVehiclesByName, GetJobs, GetGangs,
ExecuteSql, or player item mutation methods. Read shared definitions through
QBCore.Shared.Items, QBCore.Shared.Vehicles, QBCore.Shared.Jobs, and QBCore.Shared.Gangs;
use the deployed inventory resource for inventory mutation.
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.
Overview
Navigate QBCore client and server functions, commands, events and shared data. Find the right Lua reference and upstream repository before changing code.
Client Functions
Find QBCore client functions for player data, callbacks, notifications, vehicles, animations and progress bars, with signatures and practical usage references.
