Skip to main content

​
Welcome to Qbox Core

“And then there was Qbox” Qbox Core is a framework created on September 27, 2022, as a successor to qb-core and continues the development of a solid foundation for building easy-to-use, performant, and secure server resources.

​
What is Qbox Core?

Qbox Core is the foundation for your FiveM GTA V roleplay server. Built with performance and security in mind, it provides everything you need to create an immersive roleplay experience.

Installation

Get started with installing Qbox Core and its dependencies

Quick Start

Create your first character and learn the basics

API Reference

Explore the export-based API for reading and writing core data

Configuration

Configure your server settings and customize the framework

​
Key features

Qbox Core comes packed with features designed to make server development easier and more efficient:

​
Backwards compatibility

The bridge layer provides backwards compatibility with most QB resources with zero effort required. Simply drop in your existing resources and they’ll work seamlessly.

​
Built-in multicharacter system

Players can create and manage multiple characters on your server:
  • Configurable character slots per player (default: 3)
  • Custom character limits per license
  • Character data isolation with automatic cleanup
  • Integrated character selection UI
config/server.lua
characters = {
    playersNumberOfCharacters = {
        ['license2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] = 5,
    },
    defaultNumberOfCharacters = 3,
}

​
Multi-job and gang support

Flexible job and gang system with support for multiple simultaneous jobs:
  • Primary and secondary job assignments
  • Grade-based permissions and pay scales
  • On/off duty system
  • Society bank accounts integration
  • Boss permissions and bank authorization
['police'] = {
    label = 'LSPD',
    type = 'leo',
    defaultDuty = true,
    offDutyPay = false,
    grades = {
        [0] = {
            name = 'Recruit',
            payment = 50
        },
        [4] = {
            name = 'Chief',
            isboss = true,
            bankAuth = true,
            payment = 150
        },
    },
}

​
Queue system

Built-in queue system for managing server capacity:
  • Priority queue support
  • Configurable queue positions
  • Adaptive queue timing
  • Custom join messages

​
Persistent vehicles

Vehicles persist across server restarts:
  • Automatic vehicle spawning at last location
  • Configurable lock states
  • Vehicle ownership tracking
  • Integration with qbx_vehiclekeys
config/server.lua
persistence = {
    lockState = 'lock', -- 'lock' or 'unlock'
}

​
Export-based API

Clean, modern API using exports for all core functionality: 
-- Get a player
local player = exports.qbx_core:GetPlayer(source)

-- Add money
exports.qbx_core:AddMoney(source, 'cash', 500)

-- Set job
exports.qbx_core:SetJob(source, 'police', 0)

-- Update metadata
exports.qbx_core:SetMetadata(source, 'hunger', 100)

​
Developer modules

The core makes several optional modules available for developers to import into their resources:

Hooks

Ox-style hooks to extend functionality of your resources
local hooks = require 'modules.hooks'

Logger

Log to Discord or Ox’s logger through one unified interface
local logger = require 'modules.logger'

Lib

Common functions for tables, strings, math, native audio, vehicles, and drawing text
local qbx = require 'modules.lib'

​
Hooks module

Provide extensibility points in your resources:
modules/hooks.lua
local triggerEventHooks = require 'modules.hooks'

-- In your resource
if not triggerEventHooks('eventName', payload) then
    -- Hook returned false, cancel the action
    return
end

-- Other resources can register hooks
exports.qbx_core:registerHook('eventName', function(payload)
    -- Your logic here
    return true -- or false to cancel
end)

​
Logger module

Unified logging for Discord webhooks and Ox’s logger (Datadog, Grafana Loki, Fivemanage):
Example Usage
local logger = require 'modules.logger'

logger.log({
    source = 'MyResource',
    event = 'PlayerAction',
    message = 'Player completed a mission',
    webhook = 'https://discord.com/api/webhooks/...',
    color = 'green',
    tags = {'<@&123456789>'},
})

​
Lib module

Utility functions for common operations: 
local qbx = require 'modules.lib'

-- String utilities
local randomId = qbx.string.random('A.......')

-- Math utilities  
local rounded = qbx.math.round(3.7)

-- Table utilities
local grouped = qbx.table.mapBySubfield(data, 'category')

​
Money system

Flexible money system with configurable money types:
config/server.lua
money = {
    moneyTypes = { 
        cash = 500,    -- Starting cash
        bank = 5000,   -- Starting bank balance
        crypto = 0     -- Starting crypto
    },
    dontAllowMinus = { 'cash', 'crypto' },
    paycheckTimeout = 10,
    paycheckSociety = false
}
Once a money type is added, it will not be removed from the database even if you remove it from the config!

​
Player identifiers

Automatic generation of unique player identifiers:
  • citizenid: Unique character identifier (A + 7 random chars)
  • AccountNumber: Bank account number
  • PhoneNumber: 10-digit phone number
  • FingerId: 15-character fingerprint ID
  • WalletId: QB-style wallet ID
  • SerialNumber: 8-digit serial number

​
Database structure

Qbox Core uses a modern database structure with proper foreign key constraints:
qbx_core.sql
CREATE TABLE IF NOT EXISTS `players` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `citizenid` varchar(50) NOT NULL,
  `license` varchar(255) NOT NULL,
  `name` varchar(255) NOT NULL,
  `money` text NOT NULL,
  `charinfo` text DEFAULT NULL,
  `job` text NOT NULL,
  `gang` text DEFAULT NULL,
  `position` text NOT NULL,
  `metadata` text NOT NULL,
  PRIMARY KEY (`citizenid`)
);

​
Need help?

Join our Discord

Get support, share ideas, and connect with the Qbox community
We advise not modifying the core outside of the config files. If you feel something is missing or want to suggest additional functionality, bring it up on the official Qbox Discord!

​
Next steps

1

Install dependencies

Install oxmysql, ox_lib, and ox_inventory
2

Configure your server

Edit the config files to match your server setup
3

Import the database

Run the qbx_core.sql file to create the required tables
4

Start building

Use the export-based API to create your custom resources

Build docs developers (and LLMs) love

Get started for freeTalk to us