# QBCore Functions: client, server and player methods

QBCore exposes different functions on the **client**, **server**, and individual **Player**
objects. Calling the right name on the wrong side, or copying an old inventory method, is a common
reason for `attempt to call a nil value` errors.

This practical map is checked against
[qb-core commit 9b3cddc](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf).
For exhaustive signatures, use the dedicated [server functions](/docs/api/server-functions)
and [client functions](/docs/api/client-functions) references. Your deployed revision may differ.

![QBCore core access and execution-side function boundaries](/diagrams/core-object.svg)

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

## Quick reference: which function do I need?

| Task | Use | Runs on |
| --- | --- | --- |
| Read an online player's job or money | `QBCore.Functions.GetPlayer(source)` | Server |
| Find a connected player by character ID | `QBCore.Functions.GetPlayerByCitizenId(citizenid)` | Server |
| Look up a saved, offline character | `QBCore.Functions.GetOfflinePlayerByCitizenId(citizenid)` | Server |
| Read the local character's job or metadata | `QBCore.Functions.GetPlayerData()` | Client |
| Change a validated player's job | `Player.Functions.SetJob(job, grade)` | Server |
| Read, charge or credit a player account | `Player.Functions.GetMoney` / `RemoveMoney` / `AddMoney` | Server |
| Send a notification | `QBCore.Functions.Notify` | Client or server (different signatures) |
| Request server-owned information from UI | `CreateCallback` / `TriggerCallback` | Server / client |
| Add or remove inventory items | `qb-inventory` exports | Server |

## Getting QBCore Object

Import `qb-core` into the resource context that will use it. Filters reduce the surface returned
from `GetCoreObject`; they do not grant access to server-only functions on a client.

```lua
-- client.lua or server.lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })
```

For jobs, items and shared configuration, request `Shared` too, or use the
[GetShared export](/docs/core/shared-exports). Ensure `qb-core` starts before the calling
resource and declare the dependency in your `fxmanifest.lua`:

```lua
dependency 'qb-core'
```

See [core object](/docs/core/core-object) and
[resource load order](/docs/troubleshooting/resource-load-order).

## Player Functions

The following lookup helpers exist in
[`server/functions.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua).
They are **server-side**; a player source is the current connection ID, not the persistent
`citizenid`.

### QBCore.Functions.GetPlayer(source)

Use this inside a server callback or trusted server event. It returns a Player object, or `nil`
if that connection does not have a loaded character.

```lua
-- server.lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

local function getPlayerJob(src)
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return nil end
    return Player.PlayerData.job.name
end
```

For network events, obtain `src` from the server's event `source`, not a client-supplied player ID.
A Player object does **not** establish permission to perform a requested operation.

### QBCore.Functions.GetPlayerByCitizenId(citizenid)

Looks up a **currently online** character by its persistent citizen ID. It can return `nil`
when the character is offline. To read a character that is not connected, use the next function.

### QBCore.Functions.GetOfflinePlayer(citizenid)

This heading is retained for links to older examples. The current function name is
**`QBCore.Functions.GetOfflinePlayerByCitizenId(citizenid)`**; there is no
`QBCore.Functions.GetOfflinePlayer` in the pinned upstream server API. It reads a saved
character using the core's offline player interface. Do not assume an offline object can perform
in-game or network actions.

### QBCore.Functions.GetPlayerByPhone(phone)

Searches **online** QBCore players by their saved phone value. It may return `nil`. Inspect the
actual `charinfo.phone` format in your installed resources before comparing values.

### QBCore.Functions.GetQBPlayers()

Returns the core's online Player map, keyed by player source. For a list of source IDs, use
`QBCore.Functions.GetPlayers()` instead.

```lua
-- server.lua: read-only example
local players = QBCore.Functions.GetQBPlayers()
for src, Player in pairs(players) do
    if Player.PlayerData.job.name == 'police' then
        print(('Online police source: %s'):format(src))
    end
end
```

For a filtered count, the current server API also exposes
`QBCore.Functions.GetPlayersByJob(job, checkOnDuty)` and
`QBCore.Functions.GetDutyCount(job)`. See [server functions](/docs/api/server-functions).

### QBCore.Functions.CreateUseableItem(item, cb)

Registers an item-use callback on the **server**. The current spelling is `CreateUseableItem`
(not `CreateUsableItem`). The upstream wrapper accepts a function or supported function reference.

Do not hand out items simply because the client says one was used. Inventory ownership,
consumption and the associated effect must follow the installed
[qb-inventory API](/docs/resources/qb-inventory) and
[usable-item workflow](/docs/guides/item-use-effect).

## Player Object Functions

Get a Player on the server first. Its `Player.Functions` wrapper provides player state and
persistence methods from
[`server/player.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua).

### Player.Functions.AddItem(item, amount, slot, info)

**Not a core player method in the pinned revision.** Item mutation is provided by
`qb-inventory` or the inventory implementation installed on your server. Use the documented
[`exports['qb-inventory']:AddItem(...)`](/docs/resources/qb-inventory) API if you run the
upstream inventory, after checking item validity, capacity, entitlement and transaction rules
on the server.

### Player.Functions.RemoveItem(item, amount, slot)

Likewise, use the supported inventory resource export for item removal. Do not assume a tutorial
for a different inventory or older fork exposes the same Player method or parameters.

## Money Functions

These are server-side **Player methods**, not functions for untrusted client input. The current
implementation returns `true` for a successful mutation and `false` for several rejected cases;
invalid input may also cause an early return. Always handle a failed charge.

### Player.Functions.AddMoney(moneytype, amount, reason)

Credits an existing money type (for example `cash` or `bank`) after your own server-side
eligibility check. Include a reason for auditing. The caller must independently verify the reward
or staff permission; **never** expose an event that accepts an arbitrary client-supplied amount.

### Player.Functions.RemoveMoney(moneytype, amount, reason)

Charges a player subject to configured negative-balance restrictions. Use a server-owned
price, not a price received from the browser/UI:

```lua
-- server.lua: read-only, server-priced charge helper
local COST = 250

local function chargeForVerifiedPurchase(src)
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return false end

    -- The caller must independently validate the selected product,
    -- distance, stock and purchase eligibility before calling this.
    return Player.Functions.RemoveMoney('bank', COST, 'myresource:purchase') == true
end
```

This is **only the payment step**. A complete purchase must define what happens on item-delivery
failure (refund/rollback) and reject repeated submissions. See
[safe server events](/docs/security/safe-server-events).

### Player.Functions.SetMoney(moneytype, amount, reason)

Replaces the balance. Reserve this for authorized server workflows (such as audited
administration or data repair), not normal purchases.

### Player.Functions.GetMoney(moneytype)

Returns the current balance for the selected money type or `false` when no money type is passed.
Read this on the server when the result controls a transaction; a client's displayed balance is not
a payment authorization.

## Job Functions

### Player.Functions.SetJob(job, grade)

Assigns a job from `QBCore.Shared.Jobs`. It returns `false` for an unknown job and `true`
after updating the Player object. Job grades must exist in the configured job definitions; validate
them before changing a live player. See [create a job](/docs/guides/create-job) and
[set a job](/docs/guides/set-job).

### Player.Functions.SetGang(gang, grade)

Assigns a gang from the shared definitions. Apply the same server-side permission and grade checks
as for jobs.

### Player.Functions.SetJobDuty(onDuty)

Updates the player's duty flag and synchronizes its job data. It is a Player method, distinct from
the network event `QBCore:ToggleDuty` and its duty notifications. See
[QBCore events](/docs/core/events#job-events).

## Metadata Functions

### Player.Functions.SetMetaData(meta, val)

Sets a player metadata key and synchronizes it to the client. The upstream player code clamps
`hunger` and `thirst` to a 0–100 range; it does **not** apply the same validation to arbitrary
custom metadata. Validate values yourself.

### Player.Functions.GetMetaData(meta)

Reads a server-side metadata value. The formerly documented `Player.Functions.AddMetaData`
does **not** exist in the pinned Player interface; use the documented setter to update a validated
numeric value.

## Character Functions

### Player.Functions.UpdatePlayerData()

This compatibility alias maps to `Player.Functions.UpdateClient()` in the pinned player object.
For normal field changes, prefer the specific setter (`SetJob`, `SetMetaData` or
`SetPlayerData`) instead of mutating internal tables directly.

### Player.Functions.SetPlayerData(key, val)

Sets a top-level field and synchronizes it. Because this can overwrite broad player state,
validate the caller and data shape and prefer a narrower method where one exists. See
[player data](/docs/core/player-data).

## Server Utility Functions

Common server lookup helpers are defined in the pinned
[`server/functions.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua).
These headings also retain existing deep links from search results.

### QBCore.Functions.GetCoords(entity)

Returns a `vector4` containing the entity's X, Y, Z and heading. Verify that the entity exists
and that your code runs on the correct client/server side before using the result.

### QBCore.Functions.GetIdentifier(source, idtype)

Reads the caller's identifier for a specified type (default `license`). Use the server-provided
`source` from a network handler rather than trusting an identifier sent by a client.

### QBCore.Functions.GetSource(identifier)

Looks up a connected player's source from an identifier string. **Returns `0` when no match
is found**, not `nil`. Validate that the result is nonzero before accessing that player.

### QBCore.Functions.GetPlayers()

Returns a list of online server source IDs. This is different from
`QBCore.Functions.GetQBPlayers()`, which returns the map of Player objects.

```lua
-- server.lua: only read connected player IDs
for _, src in ipairs(QBCore.Functions.GetPlayers()) do
    local Player = QBCore.Functions.GetPlayer(src)
    if Player then
        -- Work with the loaded Player only.
    end
end
```

### QBCore.Functions.CreateCallback(name, cb)

Server callbacks handle client requests and run with the calling player's `source` as their first
argument. Callback registration is **not** authorization.

```lua
-- server.lua
QBCore.Functions.CreateCallback('myresource:server:getDutyCount', function(src, cb)
    if not QBCore.Functions.GetPlayer(src) then
        cb(0)
        return
    end

    cb(QBCore.Functions.GetDutyCount('police'))
end)
```

This example returns a non-sensitive count. If your callback returns money, inventory, private
data or privileged state, authorize the request and validate all arguments first.

## Client Utility Functions

### QBCore.Functions.GetPlayerData()

Reads the local player's synchronized data. Do not assume it is populated before the player-load
event:

```lua
-- client.lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

RegisterNetEvent('QBCore:Client:OnPlayerLoaded', function()
    local data = QBCore.Functions.GetPlayerData()
    if data and data.job then
        print(('Current job: %s'):format(data.job.name))
    end
end)
```

### QBCore.Functions.TriggerCallback(name, cb, ...)

Requests a value from a named server callback. In the pinned revision it supports callback style
and an awaited return style.

```lua
-- client.lua; paired with the server callback above
QBCore.Functions.TriggerCallback('myresource:server:getDutyCount', function(count)
    print(('Police on duty: %d'):format(count or 0))
end)
```

Never use a client callback result as proof that a purchase or job change has been authorized.

### QBCore.Functions.SpawnVehicle(model, coords, warpPed)

The older three-argument heading is retained for incoming links. The **current** client signature
is `SpawnVehicle(model, cb, coords, isnetworked, teleportInto)`: the second argument is a
callback receiving the created vehicle, **not** the coordinates. This creates a client-side
vehicle; use a server-side creation path when the server must own it. See
[client vehicle functions](/docs/api/client-functions#spawnvehicle).

### QBCore.Functions.GetVehicleLabel(model)

The current function accepts a **vehicle entity handle**, not a model hash. It returns `nil`
for a missing/zero handle.

## Math and Utility Functions

Older examples call `QBCore.Shared.Round`, `QBCore.Shared.Trim`,
`QBCore.Functions.GetStreetLabel` or `QBCore.Functions.GetZoneLabel`. Do **not** assume
these helpers exist in the pinned core. The client currently exposes
`GetStreetNametAtCoords(coords)` (spelled exactly that way upstream),
`GetZoneAtCoords(coords)` and `GetCardinalDirection(entity)`. Check the
[client signature index](/docs/api/client-functions) before porting an older script.

## Command Functions

### QBCore.Commands.Add(name, help, arguments, argsrequired, callback, permission)

Registers a server command. The current command implementation uses
FiveM's `RegisterCommand` restrictions and ACE-backed permission checks.
Never implement your own money/item grant command with a user-controlled role name.
Use [commands API](/docs/api/commands) and
[admin permission guidance](/docs/guides/how-to-become-admin).

### QBCore.Commands.Refresh(source)

Refreshes registered command suggestions/permissions for a connected player.

## Debug and Development Functions

### QBCore.Debug(resource)

The historical heading is retained for compatibility. The current debug signature is
`QBCore.Debug(resource, obj, depth)`. It is a debugging aid, not a replacement for the
[F8/server log and profiler workflow](/docs/development/debugging).

## When a function is nil

If you have the resource files locally, try the
[Compatibility Analyzer](/tools/compatibility-analyzer) for file/line references to
legacy API calls, unresolved exports and declared dependencies. These are static clues;
they do not validate the exact runtime or the installed resource revision.

1. Confirm the file runs on the **correct side** (client versus server) and that `qb-core`
   starts before the resource.
2. Compare the exact function name, capitalization, parameters, and returned values with the
   [pinned upstream source](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf).
3. Check whether the function is owned by **qb-inventory, qb-target or another resource**
   rather than `qb-core`.
4. Test in a separate server, collect the **first** error and the installed commits, and follow
   [resource debugging](/docs/development/debugging).

## Sources

- [qb-core server/functions.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua)
- [qb-core client/functions.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/functions.lua)
- [qb-core server/player.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua)
- [qb-core server/commands.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/commands.lua)
- [GetCoreObject source](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/shared/main.lua)

Source reviewed on 2026-10-09. These examples were **not** run against an actual FiveM server;
pin your installed resource revisions and test the intended workflows before deployment.
