QBCore Frameworkqbcore.netCommunity docs
On this page

Updated 2026-10-09 · 8 min read

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. For the complete event registration tables, use the client event reference and server event reference.

QBCore player state updates and client events

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

SituationEventWhere to listen
Character is ready on the clientQBCore:Client:OnPlayerLoadedClient
Character leaves / logs outQBCore:Client:OnPlayerUnloadClient
Server has created/loaded a Player objectQBCore:Server:PlayerLoadedServer (local)
Server is unloading a playerQBCore:Server:OnPlayerUnloadServer (local)
PlayerData was replacedQBCore:Player:SetPlayerDataClient (local); also emitted server-side on full updates
Player's job changedQBCore:Client:OnJobUpdateClient (local)
Player's gang changedQBCore:Client:OnGangUpdateClient (local)
Bank/cash changedQBCore:Client:OnMoneyChangeClient
Server needs to observe money updatesQBCore:Server:OnMoneyChangeServer (local)
A shared core definition changedQBCore:Client:UpdateObjectClient (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, server/events.lua and 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.

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

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

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

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

ArgumentTypeMeaning
moneyTypestringe.g. cash or bank
amountnumberAmount passed to the money method; for set, the new balance
operationstringadd, remove or set
reasonstringCaller-supplied audit reason
-- 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 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.

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.

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 for the current notification shape.

QBCore:Command:Update

This older identifier is not part of the pinned core's registered client events. Use 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 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

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

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

    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.

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.

Sources

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.

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