QBCore Framework
Server/client API for qb-core: Player object, PlayerData, callbacks, jobs, gangs, money and metadata.
Activation Contract
Load this skill when the user creates or edits a qb-core resource, touches Player / QBCore.PlayerData, needs jobs, gangs, money, items or metadata through QBCore, or asks about QBCore callbacks, events or best practices.
This skill targets qb-core (qbcore-framework). If the user is on Qbox (qbx_core, exports.qbx_core), the APIs diverge: state it and do not apply this skill blindly.
Hard Rules
- Acquire the core once with
local QBCore = exports['qb-core']:GetCoreObject(); never call it inside every function. Playerexists on the SERVER only (QBCore.Functions.GetPlayer(source)).QBCore.PlayerDataexists on the CLIENT only, populated afterQBCore:Client:OnPlayerLoaded.- Always nil-check:
if not Player then return endbefore calling any method. - Money, jobs, gangs, items and metadata are mutated on the server through
Player.Functions.*, never from the client. - Pass a
reasontoAddMoney,RemoveMoney,SetMoney. - Use state bags OR events for a given piece of state, never both.
- Validate every client-supplied argument on the server; never trust amounts, prices or item names sent by the client.
- Prefer ox_lib for notifications, menus, dialogs and progress bars.
- Use dynamic
Wait()values in loops; avoidWait(0)unless per-frame work is required.
Decision Gates
| Need | Use |
|---|---|
| Client asks server for data | QBCore.Functions.CreateCallback + QBCore.Functions.TriggerCallback |
| Money | Player.Functions.AddMoney/RemoveMoney/SetMoney/GetMoney(moneyType, ...) |
| Job / duty / gang | Player.Functions.SetJob, SetJobDuty, SetGang |
| Persistent per-player flags | Player.Functions.SetMetaData / GetMetaData |
| Items (qb-inventory) | Player.Functions.AddItem/RemoveItem/GetItemByName/GetItemBySlot |
| Shared runtime state | state bags (see rules/core-concepts.md) |
Execution Steps
- Confirm
qb-corestarts before the resource; cacheQBCoreper side. - Decide the side: mutation and validation on server, display on client.
- Fetch
Player, nil-check, then validate every client-supplied argument. - Pick the call from Decision Gates; read the matching rules file for signatures.
- Return data via callbacks, not paired events.
Output Contract
Return runnable Lua with the client/server split explicit, Player nil-checked, and reasons on money operations. Use ox_lib for UI unless the user asks otherwise.
References
- rules/core-concepts.md — architecture, PlayerData, Player object, events, state bags.
- rules/player-methods.md — Player.Functions money, job, gang, metadata, items.
- rules/best-practices.md — naming, caching, waits, state management, security.
- rules/reference-links.md — official QBCore documentation links.
Upstream docs: https://docs.qbcore.org