Updated 2026-09-26 · 4 min read
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.
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.
-- 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
-- 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
-- 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
-- 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
-- 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
-- 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
endUse pairs for GetQBPlayers(). Do not use # to count its potentially sparse server-ID keys.
QBCore.Functions.GetPlayersOnDuty
-- 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)
endThe elements are numbers: id.PlayerData is invalid. The broader lookup at this revision also
accepts a job type; check 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, not the server lookup contracts, on the client.
QBCore.Functions.Notify
-- 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.
Shared Functions
Read definitions through QBCore.Shared or the supported shared exports. Refer to
Shared data and Shared mutation 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.
QBCore.Functions.SpawnVehicle
The client helper receives a callback, while the server helpers have different signatures. Copy the matching example from client functions or server functions. Do not insert a heading into a networking-flag argument or treat an asynchronous callback result as a synchronous return.
Related Resources
Sources
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.
qb-core
Source-backed qb-core guide for QBCore: installation role, GetCoreObject, player data, shared definitions, functions, events, commands and direct exports.
qb-adminmenu
Set up the QBCore admin menu, distinguish txAdmin from framework access, isolate MenuV and permission failures, and verify staff-only actions on staging.
