QBCore Basics: A Beginner's Guide to the qb-core Framework

QBCore is the most popular modern roleplay framework for FiveM. Built around the qb-core resource, it manages player data, an item-based inventory, jobs and gangs, an economy with cash, bank, and crypto accounts, and a clean event system for client-server communication. If you are building a custom roleplay server in 2026 and not specifically committed to ESX, QBCore (or its successor-style cousin QBox) is the framework most tutorials and paid scripts assume.

This page teaches the QBCore building blocks a beginner actually uses: getting the core object, retrieving a Player on the server, the money and job functions, player metadata, and the events that fire when a character loads. We finish with a tiny script you can drop into a resource and run. PlayDeck teaches this with AI: you describe the feature in plain English, the AI writes QBCore-correct Lua, and you steer and verify it, learning the framework's conventions as you build.

The QBCore object and how to get it

Every QBCore script begins by getting the core object, which exposes the framework's shared functions, config, and player table. The standard line, used in both client and server files, is: local QBCore = exports['qb-core']:GetCoreObject(). From that object you reach functions like QBCore.Functions.GetPlayer on the server and shared data like QBCore.Shared.Items, the master list of every item your server knows about.

Make sure qb-core is listed before your resource starts, and that your fxmanifest.lua declares a dependency on it. If GetCoreObject returns nil, your resource almost certainly started before qb-core did adding a dependency line fixes the start order. This is the QBCore equivalent of the ESX getSharedObject gotcha.

The Player object: money, job, and metadata

On the server you retrieve a character with local Player = QBCore.Functions.GetPlayer(source), where source is the player's server ID. The returned Player object holds everything about that character under Player.PlayerData including Player.PlayerData.citizenid (the permanent unique ID for that character), their job, their money, and a flexible metadata table.

QBCore namespaces its mutating functions under Player.Functions. To change money you call Player.Functions.AddMoney('cash', 1000) or Player.Functions.RemoveMoney('bank', 500, 'paid-rent'). Jobs use Player.Functions.SetJob('police', 2). Arbitrary per-character data, like a hunger value or a license, lives in metadata: Player.Functions.SetMetaData('hunger', 80) and Player.PlayerData.metadata.hunger to read it back. Metadata is one of QBCore's most useful features for roleplay systems.

• Player.PlayerData.citizenid: permanent character ID
• Player.Functions.AddMoney('cash', 1000): add cash
• Player.Functions.RemoveMoney('bank', 500, 'reason'): take from bank with a reason string
• Player.Functions.SetJob('mechanic', 0): set job and grade
• Player.Functions.SetMetaData('hunger', 80): store custom character data

A minimal QBCore command

Here is a complete server-side feature. RegisterCommand('paycheck', function(source) local Player = QBCore.Functions.GetPlayer(source) if not Player then return end Player.Functions.AddMoney('bank', 500, 'paycheck') end) gives the calling player 500 in their bank account, logged with the reason 'paycheck', whenever they type /paycheck.

The early return on a nil Player matters: GetPlayer returns nil if the source is not a fully loaded character, and indexing nil crashes the resource. Guarding every GetPlayer call is a habit that will save you hours of debugging. QBCore, like all FiveM frameworks, expects you to validate on the server and never trust client-sent amounts see the server-side vs client-side guide for why.

Events you will use constantly

QBCore fires named events at key lifecycle moments. On the client, QBCore:Client:OnPlayerLoaded fires when a character finishes loading the right time to build a HUD or request data from the server. QBCore:Client:OnJobUpdate fires whenever the player's job changes, so job-locked menus and blips can react immediately.

On the server, you will often register your own net events with RegisterNetEvent and handle them, using GetPlayer(source) inside to act on the calling character. Because server net events can be triggered by any client, you must validate everything inside them: confirm the player exists, confirm they can afford or are allowed the action, and never assume the client sent honest data.

How QBCore differs from ESX in practice

If you already know ESX, the mental model is similar but the syntax differs. ESX's xPlayer becomes QBCore's Player; xPlayer.addMoney(1000) becomes Player.Functions.AddMoney('cash', 1000); ESX's job name from xPlayer.getJob().name becomes Player.PlayerData.job.name. QBCore tends to be more consistent and namespaced, which makes scripts easier to read once the pattern clicks.

The biggest conceptual addition is metadata and the citizenid-centric design, which make persistent per-character systems (licenses, status bars, reputation) cleaner than in classic ESX. If you are converting scripts between frameworks, our ESX-to-QBox conversion guide maps the equivalent calls side by side.