Skip to main content

QBCore API

This page covers the core QBCore API -- the functions and tables you'll use most when building on the framework. QBCore is Lua-based, so all examples here are in Lua.

QBCore.Functions (Server)​

These are the primary server-side functions for managing players and data.

GetPlayer​

Retrieve a player object by their server source ID:

local Player = QBCore.Functions.GetPlayer(source)

GetPlayerByCitizenId​

Look up a player by their unique citizen ID (useful for offline lookups):

local Player = QBCore.Functions.GetPlayerByCitizenId("HLX28491")

GetPlayers​

Get all currently connected players:

local players = QBCore.Functions.GetPlayers()
for _, src in ipairs(players) do
    local Player = QBCore.Functions.GetPlayer(src)
    print(Player.PlayerData.charinfo.firstname)
end

CreateCallback​

Register a server callback that clients can invoke:

QBCore.Functions.CreateCallback('mypackage:server:getData', function(source, cb, args)
    local Player = QBCore.Functions.GetPlayer(source)
    local result = { name = Player.PlayerData.charinfo.firstname }
    cb(result)
end)

CreateUseableItem​

Register an item that triggers a function when used:

QBCore.Functions.CreateUseableItem("water_bottle", function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    Player.Functions.SetMetaData("thirst", math.min(Player.PlayerData.metadata.thirst + 30, 100))
    Player.Functions.RemoveItem("water_bottle", 1)
end)

QBCore.Functions (Client)​

Client-side functions for interacting with the server and local player.

GetPlayerData​

Get the local player's cached data (no server round-trip):

local PlayerData = QBCore.Functions.GetPlayerData()
local job = PlayerData.job.name
local cash = PlayerData.money.cash

TriggerCallback​

Invoke a server callback and receive the result:

QBCore.Functions.TriggerCallback('mypackage:server:getData', function(result)
    print("Name: " .. result.name)
end, optionalArgs)

Notify​

Show a notification to the local player:

QBCore.Functions.Notify("You picked up a health kit!", "success", 5000)
-- Types: "success", "error", "info", "warning"
-- Duration in milliseconds

QBCore.Players​

Server-side table that holds all active player objects, keyed by source:

-- Loop through all online players
for src, Player in pairs(QBCore.Players) do
    print(src, Player.PlayerData.charinfo.firstname)
end

Shared Data​

QBCore uses shared Lua tables to define items, jobs, vehicles, and gangs. These are accessible on both client and server.

QBCore.Shared.Items​

All registered items in the framework:

QBCore.Shared.Items = {
    water_bottle = {
        name = "water_bottle",
        label = "Water Bottle",
        weight = 200,       -- grams
        type = "item",
        image = "water_bottle.png",
        unique = false,
        useable = true,
        shouldClose = true,
        description = "A refreshing bottle of water"
    },
}

QBCore.Shared.Jobs​

All registered jobs (see the Player Guide for the full structure).

QBCore.Shared.Vehicles​

Vehicle definitions used by dealerships, garages, and spawning:

QBCore.Shared.Vehicles = {
    sedan_sport = {
        name = "sedan_sport",
        label = "Sport Sedan",
        brand = "Benefactor",
        type = "automobile",
        price = 45000,
        category = "sedans",
    },
}

QBCore.Shared.Gangs​

Gang definitions with grades, similar to jobs:

QBCore.Shared.Gangs = {
    ballas = {
        label = "Ballas",
        grades = {
            [0] = { name = "recruit" },
            [1] = { name = "enforcer" },
            [2] = { name = "shotcaller" },
            [3] = { name = "boss" },
        },
    },
}

Events​

QBCore fires several events you can listen to for hooking into the framework lifecycle:

-- Player loaded (server)
RegisterServerEvent('QBCore:Server:PlayerLoaded', function(controller, Player)
    print(Player.PlayerData.charinfo.firstname .. " has loaded in")
end)

-- Player job updated (client)
RegisterClientEvent('QBCore:Client:OnJobUpdate', function(JobInfo)
    print("New job: " .. JobInfo.name)
end)

-- Player money updated (client)
RegisterClientEvent('QBCore:Client:OnMoneyChange', function(moneyType, amount, operation)
    print(moneyType .. ": " .. operation .. " $" .. amount)
end)