# QBCore Events: client and server reference

QBCore events let resources react when a character loads, their job changes, their money changes
or a framework update is published. **Client events, server network events and local server
events are not interchangeable.** Registering a handler is not permission to change player state.

This guide maps common integration tasks to
[qb-core commit 9b3cddc](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf).
For the complete event registration tables, use the
[client event reference](/docs/api/client-events) and
[server event reference](/docs/api/server-events).

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

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

## Quick reference: which QBCore event should I listen for?

For a custom resource, the [Compatibility Analyzer](/tools/compatibility-analyzer)
can identify literal references to registered events and flag handlers absent from the
selected files. An absent handler in the selection is not proof an event is missing
from your running server.

| Situation | Event | Where to listen |
| --- | --- | --- |
| Character is ready on the client | `QBCore:Client:OnPlayerLoaded` | Client |
| Character leaves / logs out | `QBCore:Client:OnPlayerUnload` | Client |
| Server has created/loaded a Player object | `QBCore:Server:PlayerLoaded` | Server (local) |
| Server is unloading a player | `QBCore:Server:OnPlayerUnload` | Server (local) |
| PlayerData was replaced | `QBCore:Player:SetPlayerData` | Client (local); also emitted server-side on full updates |
| Player's job changed | `QBCore:Client:OnJobUpdate` | Client (local) |
| Player's gang changed | `QBCore:Client:OnGangUpdate` | Client (local) |
| Bank/cash changed | `QBCore:Client:OnMoneyChange` | Client |
| Server needs to observe money updates | `QBCore:Server:OnMoneyChange` | Server (local) |
| A shared core definition changed | `QBCore:Client:UpdateObject` | Client (local) |

Use `AddEventHandler` for a local event emitted by the current runtime. Use `RegisterNetEvent`
only when the event genuinely needs to cross the network boundary. The core's own handlers are
defined in [`client/events.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/events.lua),
[`server/events.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/events.lua)
and [`server/player.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua).

## Player Events

### Client-Side Player Events

#### QBCore:Client:OnPlayerLoaded

Use this when the local character has finished its framework load sequence. The upstream client
handler sets `LocalPlayer.state.isLoggedIn` and applies the configured PVP state.

```lua
-- client.lua; register a listener, not a second core event implementation
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

AddEventHandler('QBCore:Client:OnPlayerLoaded', function()
    local data = QBCore.Functions.GetPlayerData()
    if not data or not data.job then return end

    print(('My current job: %s'):format(data.job.name))
end)
```

Use [GetPlayerData](/docs/core/functions#qbcorefunctionsgetplayerdata) after the load event;
do not read `charinfo` or `job` before they are initialized.

#### QBCore:Client:OnPlayerUnload

Clear **your resource's local state** when a player logs out or switches characters. The core
updates `LocalPlayer.state.isLoggedIn` in its own handler. Do not call this event as a shortcut
for server logout.

```lua
-- client.lua
local cachedJob = nil

AddEventHandler('QBCore:Client:OnPlayerUnload', function()
    cachedJob = nil
end)
```

#### QBCore:Player:SetPlayerData

This local event is emitted after a **full** player-data update. The pinned client receives
`QBCore:Client:OnPlayerUpdated` with the key `all`, replaces its data and then emits
`QBCore:Player:SetPlayerData`. Smaller updates may instead arrive as one keyed field, so
do not assume this full-data event fires for every metadata or money change.

### Server-Side Player Events

#### QBCore:Server:OnPlayerLoaded

This is a **network handler** in the core. It checks that a Player is present for the calling
source before emitting the client-side loaded event. It is **not** the same as the local
`QBCore:Server:PlayerLoaded` integration event that the server-side Player loader emits.

To react to a loaded Player object on the server, listen for the latter:

```lua
-- server.lua
AddEventHandler('QBCore:Server:PlayerLoaded', function(Player)
    if not Player or not Player.PlayerData then return end

    -- Read-only example; do not trigger login again.
    print(('QBCore character loaded from source %s'):format(Player.PlayerData.source))
end)
```

#### QBCore:Server:PlayerLoggedOut

This **old event name is not emitted by the pinned core**. Use
`QBCore:Server:OnPlayerUnload` with the player source, or
`QBCore:Server:PlayerDropped` for a network disconnect. Both are local server events.
See [multicharacter loading](/docs/troubleshooting/multicharacter-loading) for login-flow
problems.

## Job Events

### Job Update Events

#### QBCore:Client:OnJobUpdate

The pinned client's player-data update handler emits this locally when the job changes.
The handler receives the **job table**, not a player source or arbitrary job name.

```lua
-- client.lua
AddEventHandler('QBCore:Client:OnJobUpdate', function(job)
    if not job then return end
    local canAccessPoliceUI = job.name == 'police' and job.onduty == true
    -- Keep this variable local to your UI; the server must authorize real actions.
end)
```

#### QBCore:Client:SetDuty

The pinned `QBCore:ToggleDuty` server handler emits this client event with a Boolean duty state.
A direct call to `Player.Functions.SetJobDuty` updates PlayerData and can emit a job update
instead; do not assume every code path sends the same duty event.

### Server-Side Job Events

#### QBCore:Server:OnJobUpdate

The core's `QBCore:Server:OnPlayerUpdated` dispatcher emits this local server event with
`source, job` when the job field changes, including full-data refreshes. Observe it, but
re-read the authoritative Player and check permissions before performing protected work.

## Gang Events

### Gang Update Events

#### QBCore:Client:OnGangUpdate

Receives the current gang table. The matching local server integration event is
`QBCore:Server:OnGangUpdate` (`source, gang`). See
[gang/player data](/docs/core/player-data) for the actual data shape.

## Money Events

### Money Update Events

#### hud:client:UpdateMoney

This is **not** a qb-core event in the pinned revision. The upstream Player methods notify the
HUD through `hud:client:OnMoneyChange`, with a different payload. HUD installations can replace
these events entirely. Use the core integration event below for framework-level listeners.

#### QBCore:Client:OnMoneyChange

Sent by `Player:AddMoney`, `Player:RemoveMoney` and `Player:SetMoney`:

| Argument | Type | Meaning |
| --- | --- | --- |
| `moneyType` | string | e.g. `cash` or `bank` |
| `amount` | number | Amount passed to the money method; for `set`, the new balance |
| `operation` | string | `add`, `remove` or `set` |
| `reason` | string | Caller-supplied audit reason |

```lua
-- client.lua: update a display only, never authorize a purchase
AddEventHandler('QBCore:Client:OnMoneyChange', function(moneyType, amount, operation)
    if moneyType == 'bank' then
        print(('Bank changed via %s'):format(operation))
    end
end)
```

The analogous local server event is
`QBCore:Server:OnMoneyChange(source, moneyType, amount, operation, reason)`.
Use [Player.Functions money APIs](/docs/core/functions#money-functions) for actual changes,
not a client-triggered notification.

## Vehicle Events

### Vehicle Interaction Events

#### QBCore:Client:VehicleInfo

An **internal** core vehicle/baseevents bridge. Its payload is an `info` table containing the
vehicle and transition data. This is not an authoritative request to spawn or grant a vehicle.

#### QBCore:Client:EnteredVehicle

Older resources may emit this name, but it is **not registered/emitted by the verified core
client/server event files**. Do not depend on it without inspecting the resource that supplies
it; use Cfx `baseevents` or the appropriate gameplay resource when vehicle entry is your task.

#### QBCore:Client:LeftVehicle

The same caveat applies to this legacy name. Compare the installed event source before
adding a listener.

## Inventory Events

### Item Events

#### QBCore:Client:OnUseItem

**Not emitted by the pinned qb-core event files.** Usable-item callbacks are registered on
the server with `QBCore.Functions.CreateUseableItem`; the inventory resource handles the
interaction. Follow the [usable item guide](/docs/guides/item-use-effect).

#### QBCore:Client:ItemBox

Also **not a current core event**. The inventory UI owns its item box notifications.

### Inventory Management Events

#### inventory:client:ItemBox

An event belonging to **qb-inventory**, not a universal QBCore event. The exact parameters
depend on the inventory revision; see
[qb-inventory functions and events](/docs/resources/qb-inventory/events).

## Status Events

### Needs Events (Hunger, Thirst, Stress)

#### hud:client:UpdateNeeds

The pinned server's `QBCore:UpdatePlayer` handler updates hunger/thirst metadata and emits
`hud:client:UpdateNeeds` with `hunger, thirst`. This is an integration with a HUD, not a
general contract for every replacement status system.

#### hud:client:UpdateStress

Stress changes are usually owned by a HUD or gameplay resource. Do not treat this as a
core-supported event without checking your installed `qb-hud` and stress implementation.

## Notification Events

### Standard Notifications

#### QBCore:Notify

The client-side core registers `QBCore:Notify(text, type, length, icon)` and forwards it to
`QBCore.Functions.Notify`. To notify a specific player from the server, prefer
`QBCore.Functions.Notify(source, text, type, length)`; to notify locally, use the client
`QBCore.Functions.Notify(text, type, length, icon)`.

See [client functions](/docs/api/client-functions#notify) for the current notification shape.

#### QBCore:Command:Update

This older identifier is **not part of the pinned core's registered client events**.
Use [commands](/docs/api/commands) to register and refresh the supported command interface.

## System Events

### Framework Events

#### QBCore:Client:UpdateObject

A local client event emitted after the core applies shared data updates. If your resource keeps a
cached core object, re-acquire the export after receiving it.

#### QBCore:Server:UpdateObject

A **local server** event fired by the shared mutation API after jobs/items/gangs or methods
are updated. It carries no payload at the pinned revision. Read
[shared mutation exports](/docs/core/shared-exports) before using runtime mutations.

Internal transports such as `QBCore:Server:TriggerCallback`,
`QBCore:Client:TriggerCallback`, and `QBCore:Client:OnPlayerUpdated` are framework
implementation paths. Do not dispatch these to simulate money, player or authorization changes.

## Custom Event Examples

### Creating Custom Events

A custom network event is a request across a trust boundary. For a **read-only** status lookup,
get the caller from server `source` and confirm a loaded character exists:

#### Server-Side Custom Event

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

RegisterNetEvent('myresource:server:requestJobName', function()
    local src = source
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    TriggerClientEvent('myresource:client:receiveJobName', src, Player.PlayerData.job.name)
end)
```

#### Client-Side Custom Event

```lua
-- client.lua
RegisterNetEvent('myresource:client:receiveJobName', function(jobName)
    if type(jobName) ~= 'string' then return end
    print(('Current job: %s'):format(jobName))
end)

TriggerServerEvent('myresource:server:requestJobName')
```

This example does not change data. For anything involving items, money, vehicles, permissions
or jobs, verify the caller's entitlement, server-owned state, distance, allowed values, replay
limits and transaction behavior **on the server**. Prefer existing supported exports over a
new privileged event.

## Event Best Practices

### Verify a listener in a test server

1. **Register a read-only client listener** in your own resource's `client.lua`, after
   `qb-core` has started:

   ```lua
   AddEventHandler('QBCore:Client:OnJobUpdate', function(job)
       if not job or not job.name then return end
       print(('Job updated: %s'):format(job.name))
   end)
   ```

2. **Start the resource after `qb-core`.** Log in to a test character and use a
   server-authorized job change to trigger the event. Check the F8 console.
3. **Test logout and reconnect.** Make sure your own cached state is cleared and
   no stale UI access survives a character change. Client-side output is not
   proof of server authorization.

### Performance Tips

- Register handlers once at resource startup; do not register a new listener on every UI open.
- Prefer state/job-change signals to polling every frame.
- Remove your own cached per-player state when the player drops or unloads.
- Profile first if the event path is expensive; see
  [performance investigation](/docs/development/performance).

### Security Considerations

- Treat **every client-sent event and callback argument as untrusted**, including a player ID,
  amount, item name, job grade or location.
- Use the server's `source` for the caller and check its current Player; a displayed role or
  client-side job event grants no privileges.
- When access is restricted, use appropriate ACE checks such as `IsPlayerAceAllowed` and
  enforce permissions for the exact operation.
- Never copy examples that grant money because the client's job name equals `admin`.
- Exercise malformed requests, replay, disconnects and insufficient funds in a test server
  using the [server authority checklist](/docs/security/server-authority-checklist).

## Sources

- [qb-core client/events.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/events.lua)
- [qb-core server/events.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/events.lua)
- [qb-core server/player.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua)
- [qb-core shared mutation exports](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/exports.lua)

Source reviewed on 2026-10-09. Handler snippets are examples based on the pinned source,
**not** proof that they were run on a live FiveM staging server. Verify your deployed core and
resource-specific event names before shipping integrations.
