QBCore Frameworkqbcore.netCommunity docs
On this page

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.

QBCore core access and execution-side function boundaries

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

Quick reference: which function do I need?

TaskUseRuns on
Read an online player's job or moneyQBCore.Functions.GetPlayer(source)Server
Find a connected player by character IDQBCore.Functions.GetPlayerByCitizenId(citizenid)Server
Look up a saved, offline characterQBCore.Functions.GetOfflinePlayerByCitizenId(citizenid)Server
Read the local character's job or metadataQBCore.Functions.GetPlayerData()Client
Change a validated player's jobPlayer.Functions.SetJob(job, grade)Server
Read, charge or credit a player accountPlayer.Functions.GetMoney / RemoveMoney / AddMoneyServer
Send a notificationQBCore.Functions.NotifyClient or server (different signatures)
Request server-owned information from UICreateCallback / TriggerCallbackServer / client
Add or remove inventory itemsqb-inventory exportsServer

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
end

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

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

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

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

  1. Confirm the file runs on the correct side (client versus server) and that qb-core starts before the resource.
  2. Compare the exact function name, capitalization, parameters, and returned values with the pinned upstream source.
  3. Check whether the function is owned by qb-inventory, qb-target or another resource rather than qb-core.
  4. Test in a separate server, collect the first error and the installed commits, and follow resource debugging.

Sources

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.

On this page

QBCore Functions: client, server and player methodsQuick reference: which function do I need?Getting QBCore ObjectPlayer FunctionsQBCore.Functions.GetPlayer(source)QBCore.Functions.GetPlayerByCitizenId(citizenid)QBCore.Functions.GetOfflinePlayer(citizenid)QBCore.Functions.GetPlayerByPhone(phone)QBCore.Functions.GetQBPlayers()QBCore.Functions.CreateUseableItem(item, cb)Player Object FunctionsPlayer.Functions.AddItem(item, amount, slot, info)Player.Functions.RemoveItem(item, amount, slot)Money FunctionsPlayer.Functions.AddMoney(moneytype, amount, reason)Player.Functions.RemoveMoney(moneytype, amount, reason)Player.Functions.SetMoney(moneytype, amount, reason)Player.Functions.GetMoney(moneytype)Job FunctionsPlayer.Functions.SetJob(job, grade)Player.Functions.SetGang(gang, grade)Player.Functions.SetJobDuty(onDuty)Metadata FunctionsPlayer.Functions.SetMetaData(meta, val)Player.Functions.GetMetaData(meta)Character FunctionsPlayer.Functions.UpdatePlayerData()Player.Functions.SetPlayerData(key, val)Server Utility FunctionsQBCore.Functions.GetCoords(entity)QBCore.Functions.GetIdentifier(source, idtype)QBCore.Functions.GetSource(identifier)QBCore.Functions.GetPlayers()QBCore.Functions.CreateCallback(name, cb)Client Utility FunctionsQBCore.Functions.GetPlayerData()QBCore.Functions.TriggerCallback(name, cb, ...)QBCore.Functions.SpawnVehicle(model, coords, warpPed)QBCore.Functions.GetVehicleLabel(model)Math and Utility FunctionsCommand FunctionsQBCore.Commands.Add(name, help, arguments, argsrequired, callback, permission)QBCore.Commands.Refresh(source)Debug and Development FunctionsQBCore.Debug(resource)When a function is nilSources
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