QBCore Frameworkqbcore.netCommunity docs
On this page

10 min read

QBCore server functions

These signatures are pinned to server/functions.lua.

QBCore API and server-only function boundaries

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

Complete current signature index

FunctionSignatureReturn / behavior
GetCoordsGetCoords(entity)vector4
GetIdentifierGetIdentifier(source, idtype)identifier string or nil
GetSourceGetSource(identifier)source, or 0
GetPlayerGetPlayer(source)online Player or nil
GetPlayerByCitizenIdGetPlayerByCitizenId(citizenid)online Player or nil
GetOfflinePlayerByCitizenIdGetOfflinePlayerByCitizenId(citizenid)offline Player interface or nil
GetPlayerByLicenseGetPlayerByLicense(license)online Player or nil
GetPlayerByPhoneGetPlayerByPhone(number)online Player or nil
GetPlayerByAccountGetPlayerByAccount(account)online Player or nil
GetPlayerByCharInfoGetPlayerByCharInfo(property, value)online Player or nil
GetPlayersGetPlayers()array of online sources
GetQBPlayersGetQBPlayers()core Player map
GetPlayersByJobGetPlayersByJob(job, checkOnDuty)source array, count
GetPlayersOnDutyGetPlayersOnDuty(job)source array, count
GetDutyCountGetDutyCount(job)count
GetClosestPlayerGetClosestPlayer(source, coords)closest source, distance
GetClosestObjectGetClosestObject(source, coords)object handle, distance
GetClosestVehicleGetClosestVehicle(source, coords)vehicle handle, distance
GetClosestPedGetClosestPed(source, coords)ped handle, distance
GetBucketObjectsGetBucketObjects()player-bucket table, entity-bucket table
SetPlayerBucketSetPlayerBucket(source, bucket)boolean
SetEntityBucketSetEntityBucket(entity, bucket)boolean
GetPlayersInBucketGetPlayersInBucket(bucket)source array
GetEntitiesInBucketGetEntitiesInBucket(bucket)entity array
SpawnVehicleSpawnVehicle(source, model, coords, warp)entity handle
CreateAutomobileCreateAutomobile(source, model, coords, warp)entity handle
CreateVehicleCreateVehicle(source, model, vehtype, coords, warp)entity handle
TriggerClientCallbackTriggerClientCallback(name, source, ...)callback/awaited result depending on call form
CreateCallbackCreateCallback(name, cb)registers callback; no return
CreateUseableItemCreateUseableItem(item, data)registers usable item; no return
CanUseItemCanUseItem(item)registered handler/data or nil
UseItemUseItem(source, item)invokes registered handler
KickKick(source, reason, setKickReason, deferrals)disconnect flow; no useful return
IsWhitelistedIsWhitelisted(source)boolean ACE result
AddPermissionAddPermission(source, permission)adds runtime player.<source> principal
RemovePermissionRemovePermission(source, permission)removes runtime principal(s)
HasPermissionHasPermission(source, permission)boolean
GetPermissionGetPermission(source)map of configured permissions currently allowed
IsOptinIsOptin(source)boolean
ToggleOptinToggleOptin(source)toggles admin-message opt-in
IsPlayerBannedIsPlayerBanned(source)banned boolean, optional reason
GetDatabaseInfoGetDatabaseInfo()parsed database connection info or nil
IsLicenseInUseIsLicenseInUse(license)boolean
HasItemHasItem(source, items, amount)boolean; deprecated wrapper
NotifyNotify(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

FunctionCurrent signature
GetIdentifierGetIdentifier(source, idType)
GetSourceGetSource(identifier) → source or 0
GetPlayerGetPlayer(source)
GetPlayerByCitizenIdGetPlayerByCitizenId(citizenId)
GetOfflinePlayerByCitizenIdGetOfflinePlayerByCitizenId(citizenId)
GetPlayerByLicenseGetPlayerByLicense(license)
GetPlayerByPhoneGetPlayerByPhone(number)
GetPlayersByJobGetPlayersByJob(job, checkOnDuty)
GetDutyCountGetDutyCount(job)

Callbacks, usable items, and permissions

FunctionCurrent signature
CreateCallbackCreateCallback(name, callback)
TriggerClientCallbackTriggerClientCallback(name, source, [callback], ...)
CreateUseableItemCreateUseableItem(item, callback)
CanUseItemCanUseItem(item) → registration or nil
UseItemUseItem(source, item)
HasItemHasItem(source, items, amount) → boolean; deprecated in favor of the inventory export
AddPermissionAddPermission(source, permission)
RemovePermissionRemovePermission(source, permission)
HasPermissionHasPermission(source, permission)
GetPermissionGetPermission(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 handle
  • CreateAutomobile(source, model, coords, warp) → entity handle
  • CreateVehicle(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:

TableKeyValue
QBCore.Player_Bucketsthe player's license identifier{ id = source, bucket = bucket }
QBCore.Entity_Bucketsthe 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

FunctionSignatureReturns
GetBucketObjectsGetBucketObjects()Two tables: the player registry, then the entity registry
SetPlayerBucketSetPlayerBucket(source, bucket)true on success, false when either argument is falsy
SetEntityBucketSetEntityBucket(entity, bucket)true on success, false when either argument is falsy
GetPlayersInBucketGetPlayersInBucket(bucket)Array of player sources
GetEntitiesInBucketGetEntitiesInBucket(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
end

Besides 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.instance

That 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
end

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

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