# qb-core Events & Functions Reference

This page describes the pinned source below, not every resource named `qb-core`. Compare your
checkout before copying an example. Source review is not an in-game test.

![QBCore events and authoritative state changes](/diagrams/player-lifecycle.svg)

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

## Server Events

Use `AddEventHandler` for local server hooks. Do not make a local lifecycle hook network-callable
with `RegisterNetEvent`. A client request is not proof that a character loaded or a payment happened.

| Hook at the pinned revision | Arguments | Meaning |
| --- | --- | --- |
| `QBCore:Server:PlayerLoaded` | Player object | Core constructs an online Player and registers it |
| `QBCore:Server:OnPlayerUnload` | server ID | Character logout or connected-player cleanup |
| `QBCore:Server:OnPlayerUpdated` | server ID, key, value | Player state update; `all` means a full snapshot |
| `QBCore:Server:OnMoneyChange` | server ID, account, amount, action, reason | Core money method emitted an update |

### QBCore:Server:OnPlayerLoaded

This older heading is kept for incoming links. **The construction hook in the pinned source is
`QBCore:Server:PlayerLoaded`, without `On`, and its argument is a Player object, not a source ID.**
It is not the same as the client-side `QBCore:Client:OnPlayerLoaded` gameplay hook.

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

AddEventHandler('QBCore:Server:PlayerLoaded', function(Player)
    if not Player or not Player.PlayerData then return end
    print(('Character available: %s'):format(Player.PlayerData.citizenid))
end)
```

Registration alone does not replay earlier logins when your resource restarts. Bootstrap existing
players from `QBCore.Functions.GetQBPlayers()` when your feature requires it. Make setup idempotent;
never grant first-character rewards on every load or resource restart.

### QBCore:Server:OnMoneyChange

```lua
-- server.lua: observation only; authorization belongs in the operation that changes money.
AddEventHandler('QBCore:Server:OnMoneyChange', function(src, account, amount, action, reason)
    print(('Money change: source=%s account=%s amount=%s action=%s reason=%s')
        :format(src, account, amount, action, reason))
end)
```

For a `set` operation, the amount is the new balance, not an added amount. Do not sum every event as
income. This observer is not an anti-cheat or a durable accounting ledger.

### QBCore:Server:OnPlayerUnload

```lua
-- server.lua: state owned by this resource only.
local sessions = {}
AddEventHandler('QBCore:Server:OnPlayerUnload', function(src)
    sessions[src] = nil
end)
AddEventHandler('playerDropped', function()
    sessions[source] = nil
end)
```

Cleanup should tolerate repeated calls. Source IDs belong to connections and can later be reused;
use `citizenid` for persistent character data.

## Client Events

| Event | Arguments | Use |
| --- | --- | --- |
| `QBCore:Client:OnPlayerLoaded` | none | Initialize character-facing UI |
| `QBCore:Client:OnPlayerUnload` | none | Clear character-facing state |
| `QBCore:Client:OnPlayerUpdated` | key, value | Field update or full `all` snapshot |
| `QBCore:Client:OnJobUpdate` | job table | React to the job update forwarded by core |
| `QBCore:Client:OnGangUpdate` | gang table | React to the gang update forwarded by core |
| `QBCore:Notify` | text, type, length, optional icon | Display a notification |

### QBCore:Client:OnPlayerLoaded

```lua
-- client.lua
local QBCore = exports['qb-core']:GetCoreObject()
RegisterNetEvent('QBCore:Client:OnPlayerLoaded', function()
    local data = QBCore.Functions.GetPlayerData()
    if not data or not data.citizenid then return end
    print(('Character loaded: %s'):format(data.citizenid))
end)
```

Do not set `LocalPlayer.state.isLoggedIn` yourself to force initialization. Wait for the real
lifecycle and handle already-loaded players when your own resource starts.

### QBCore:Client:OnJobUpdate

```lua
-- client.lua: display only, not an authorization check.
RegisterNetEvent('QBCore:Client:OnJobUpdate', function(job)
    if type(job) ~= 'table' then return end
    print(('Job: %s; duty: %s'):format(job.label, tostring(job.onduty)))
end)
```

At this revision, the core forwards job/gang notifications from `OnPlayerUpdated`. The legacy
`QBCore:Player:SetPlayerData` client event is forwarded for full snapshots, not every field update.

## Server Functions

| Function | Actual return at the pinned revision |
| --- | --- |
| `GetPlayer(source)` | Player object or `nil` |
| `GetPlayerByCitizenId(citizenid)` | Online Player object or `nil` |
| `GetPlayers()` | Array of server IDs, not Player objects |
| `GetQBPlayers()` | Table of Player objects keyed by server ID; not a dense array |
| `GetPlayersOnDuty(job)` | Array of server IDs, then a numeric count |
| `GetPlayersByJob(job, checkOnDuty)` | Array of server IDs, then a numeric count |
| `GetDutyCount(job)` | Number of on-duty players |

### QBCore.Functions.GetPlayer

```lua
-- server.lua
local QBCore = exports['qb-core']:GetCoreObject()
for _, id in ipairs(QBCore.Functions.GetPlayers()) do
    local Player = QBCore.Functions.GetPlayer(id)
    if Player then
        print(Player.PlayerData.citizenid)
    end
end
```

Use `pairs` for `GetQBPlayers()`. Do not use `#` to count its potentially sparse server-ID keys.

### QBCore.Functions.GetPlayersOnDuty

```lua
-- server.lua
local QBCore = exports['qb-core']:GetCoreObject()
local ids, count = QBCore.Functions.GetPlayersOnDuty('police')
print(('%d police officers on duty'):format(count))
for _, id in ipairs(ids) do
    TriggerClientEvent('QBCore:Notify', id, 'Briefing at the station', 'primary', 5000)
end
```

The elements are numbers: `id.PlayerData` is invalid. The broader lookup at this revision also
accepts a job type; check [server functions](/docs/api/server-functions) for the full API.

## Client Functions

Client and server helpers with the same name can have different signatures and visibility.
Use [client functions](/docs/api/client-functions), not the server lookup contracts, on the client.

### QBCore.Functions.Notify

```lua
-- client.lua
local QBCore = exports['qb-core']:GetCoreObject()
QBCore.Functions.Notify('Action completed', 'success', 5000)
```

### QBCore.Functions.HasItem

Inventory implementations differ. Use the side-specific API of your deployed inventory and validate
required items again on the server. See [inventory updates](/docs/troubleshooting/inventory-updates).

## Shared Functions

Read definitions through `QBCore.Shared` or the supported shared exports. Refer to
[Shared data](/docs/core/shared) and [Shared mutation exports](/docs/core/shared-exports), rather
than assuming an undocumented helper exists on every fork.

## Vehicle Utilities

### QBCore.Functions.GetPlate

Use the client helper in a client example. A license plate supplied by a client does not establish
ownership on the server. See [vehicle integration](/docs/guides/add-custom-vehicles).

### QBCore.Functions.SpawnVehicle

The client helper receives a callback, while the server helpers have different signatures.
Copy the matching example from [client functions](/docs/api/client-functions) or
[server functions](/docs/api/server-functions). Do not insert a heading into a networking-flag
argument or treat an asynchronous callback result as a synchronous return.

## Related Resources

- [PlayerData and player methods](/docs/core/player-data)
- [Server events](/docs/api/server-events)
- [Client events](/docs/api/client-events)
- [Safe server events](/docs/security/safe-server-events)

## Sources

- [Player construction, methods and notifications](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua)
- [Player lookup implementations](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua)
- [Client event forwarding](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/events.lua)
- [Disconnect and callback handlers](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/events.lua)
