# QBCore server functions

These signatures are pinned to
[`server/functions.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua).

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

*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)` |

```lua
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](/docs/advanced/onesync) 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

```lua
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:

```lua
-- 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:

```lua
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](/docs/advanced/onesync#entity-lockdown-and-routing-buckets).
Read that before designing around buckets. What follows is only how the core wrappers are used.

```lua
-- 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.
