Updated 2026-10-09 · 8 min read
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. For exhaustive signatures, use the dedicated server functions and client functions references. Your deployed revision may differ.
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.
-- 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. Ensure qb-core starts before the calling
resource and declare the dependency in your fxmanifest.lua:
dependency 'qb-core'See core object and resource load order.
Player Functions
The following lookup helpers exist in
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.
-- 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
endFor 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.
-- 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
endFor a filtered count, the current server API also exposes
QBCore.Functions.GetPlayersByJob(job, checkOnDuty) and
QBCore.Functions.GetDutyCount(job). See 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 and usable-item workflow.
Player Object Functions
Get a Player on the server first. Its Player.Functions wrapper provides player state and
persistence methods from
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(...) 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:
-- 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
endThis 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.
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 and
set a 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.
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.
Server Utility Functions
Common server lookup helpers are defined in the pinned
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.
-- 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
endQBCore.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.
-- 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:
-- 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.
-- 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.
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 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 and
admin permission guidance.
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.
When a function is nil
If you have the resource files locally, try the 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.
- Confirm the file runs on the correct side (client versus server) and that
qb-corestarts before the resource. - Compare the exact function name, capitalization, parameters, and returned values with the pinned upstream source.
- Check whether the function is owned by qb-inventory, qb-target or another resource
rather than
qb-core. - Test in a separate server, collect the first error and the installed commits, and follow resource debugging.
Sources
- qb-core server/functions.lua
- qb-core client/functions.lua
- qb-core server/player.lua
- qb-core server/commands.lua
- GetCoreObject source
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.
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.
Player data
Explore QBCore PlayerData fields for characters, jobs, money, metadata and inventory. See how to read and update player state safely in FiveM Lua scripts.
Events
Use QBCore client and server events for player loading, jobs, money, notifications and callbacks. See Lua handlers, event origins and security guidance.
