QBCore for FiveM: what it is, common mistakes and the AI skill

Updated September 10, 2026

Don’t want to manage skills yourself? Get the full app.

QBCore is a FiveM roleplay framework built around the Player object, jobs, gangs, inventory and callbacks. This guide covers its core API, the mistakes that break QBCore scripts and the AI skill that writes code against the real API.

QBCore is a FiveM roleplay framework that handles players, jobs, gangs, money and inventory through the qb-core resource and a set of qb- modules. If you script for a QBCore server, you work with the QBCore object, the Player object on the server and PlayerData on the client. This page covers what the QBCore skill for FiveAI documents, the mistakes that break QBCore scripts most often, and how to install the skill in your AI assistant.

What the QBCore skill gives you

The skill is a SKILL.md file with one rule file per area of the framework:

core-concepts: how qb-core initializes, the shape of PlayerData and what the Player object holds on the server.
client-functions and server-functions: notifications, player state on the client, QBCore.Functions.GetPlayer(source) on the server, callbacks and usable items.
player-methods: the Player.Functions methods for money, items, jobs, gangs, metadata and accounts.
jobs-gangs: the job and gang systems, payments and duty status.
inventory-items: item handling and the usable item flow.
events-callbacks: QBCore events, server callbacks, client callbacks and event handling.
best-practices: nil checks, cached player objects, dynamic Wait times, camelCase naming, locals over globals, and ox_lib for menus, dialogs, notifications and progress bars.

Reach for it when you create a QBCore resource, add a job or gang, touch money or items, or read player data anywhere.

Common mistakes with QBCore

Using Player without a nil check. Symptom: "attempt to index a nil value" in the server console when the source has already left or is invalid. Fix: local Player = QBCore.Functions.GetPlayer(source) followed by if not Player then return end.
Mixing xPlayer (ESX) and Player (QBCore). Symptom: an xPlayer.addMoney call in a QBCore resource and a nil error at runtime. The script was adapted from an ESX example. Fix: use QBCore.Functions.GetPlayer and the Player.Functions methods only.
Reading PlayerData on the client before the player is loaded. Symptom: empty job or citizen id right after spawn. Fix: wait for the player loaded state before touching PlayerData, as the client functions rule describes.
Trusting amounts sent from the client. Symptom: a modified client triggers your server event with a custom price and the server accepts it. Fix: compute prices and rewards on the server, validate the source and secure your events.
Wait(0) loops that never sleep. Symptom: a client thread that runs every frame even when the player is far from the zone it watches, and a resource that shows high resmon time. Fix: use dynamic Wait times, short near the point of interest and long everywhere else.

Why AI assistants get QBCore wrong

A generic assistant mixes QBCore versions and frameworks. It often obtains the core object with the older event-based QBCore:GetObject pattern instead of the exports['qb-core']:GetCoreObject() export, invents Player.Functions methods that do not exist, or writes gang logic with job functions because the two look similar. It also puts server-only calls such as GetPlayer in a client file, which fails at runtime.

The skill gives the assistant a compact, current reference. The core-concepts and player-methods rule files list the real object shape and methods, jobs-gangs separates the two systems, and the principles (check nil, wait for player load, never trust the client, cache player objects, dynamic Wait times, ox_lib for UI) load every time you ask for QBCore code. The result is a script that uses the API your server runs instead of a blend of three tutorials.

Install the QBCore skill in 30 seconds

Click "Download SKILL.md" at the top of this page.
Unzip it into your AI tool's skills or rules folder. The install section below shows the exact path for Claude Code, Cursor and VS Code.
Ask the assistant for something concrete, such as a usable item that checks the player's job before it pays, and confirm that it uses QBCore.Functions.GetPlayer with a nil check.

How to install this skill

Download the zip, unzip it, and place the folder where your tool loads skills or rules. The exact path depends on the tool:

Claude Code

Unzip into .claude/skills/qbcore-framework/ inside the project (the folder must contain SKILL.md). For every project, use ~/.claude/skills/qbcore-framework/ instead.

Claude Code skills docs

Cursor

Cursor loads project rules from .cursor/rules/. Add a rule file there that points to the unzipped skill, or paste the contents of SKILL.md and the rule files into a rule. The format is .mdc with frontmatter and changes between versions, so check the docs for your version.

Cursor rules docs

VS Code / Copilot

Copilot reads instruction files from .github/instructions/*.instructions.md. Copy SKILL.md there with an applyTo glob for your Lua files, and keep the rule files next to it.

VS Code custom instructions docs

The SKILL.md file

This is the file your AI assistant reads. It links to the rule files bundled in the download.

Skill contents (includes SKILL.md and any other files)

QBCore Framework Development

Complete guide for developing with QBCore Framework — a comprehensive FiveM roleplay framework providing core functionalities and modules.

When to use

Creating or editing QBCore resources/scripts
Working with player data (Player object, PlayerData)
Implementing jobs, gangs, economy, or inventory systems
Using QBCore client/server functions, callbacks, or events
Questions about QBCore best practices and optimization

How to use

Read individual rule files for detailed explanations and examples:

rules/core-concepts.md — QBCore architecture, PlayerData structure, Player object, framework initialization
rules/client-functions.md — Client-side QBCore functions, notifications, player state management
rules/server-functions.md — Server-side functions, player retrieval, callbacks, usable items
rules/player-methods.md — Player object methods: money, items, jobs, gangs, metadata, accounts
rules/jobs-gangs.md — Job system, gang system, payments, duty status
rules/inventory-items.md — Inventory management, item handling, usable items
rules/events-callbacks.md — QBCore events, server callbacks, client callbacks, event handling
rules/best-practices.md — QBCore coding standards, optimization, security, naming conventions
rules/reference-links.md — Official QBCore documentation links

Key principles

Always check for nil — if Player then ... end before using Player object
Use QBCore.Functions.GetPlayer — Standard player retrieval: local Player = QBCore.Functions.GetPlayer(source)
Wait for player load — Check player loaded state on client before accessing PlayerData
Never trust client — Validate all data server-side, secure your events
Follow QBCore patterns — Use QBCore functions instead of reinventing (callbacks, notifications, etc.)
Optimize loops — Cache player objects, use dynamic Wait times, avoid unnecessary calls
Use camelCase — Follow Lua naming: myVariable, local over global
Minimal globals — Keep variables local unless they need global scope
Use ox_lib for UI — Prefer ox_lib for menus, dialogs, notifications, progress bars

Frequently asked questions

Is Qbox the same as QBCore?

No. Qbox is a fork of QBCore with its own changes. This skill targets QBCore. A lot of the Player object and job logic overlaps, but check the exports and function names before running QBCore code on a Qbox server.

Does the skill cover qb-inventory or ox_inventory?

It covers the QBCore item and inventory functions on the Player object and the usable item flow. Inventory resources such as qb-inventory and ox_inventory have their own exports, and you should read their docs for those.

Can I use this skill with ChatGPT?

Yes. SKILL.md is plain markdown. Paste it into a custom instruction or attach it to a ChatGPT project. Claude Code, Cursor and VS Code read it from their skills or rules folder.

Longer reads from the FiveAI blog on the same topic.