QBCore Architecture

Understanding QBCore’s architecture is essential for any developer working with the framework. This tutorial will give you a comprehensive overview of how QBCore is structured and how its components work together.

Learning Objectives

By the end of this tutorial, you will understand:

The overall structure of QBCore framework
Key components and their responsibilities
How different parts of the system interact
The resource system and dependencies

⏱️ Estimated Time: 15 minutes
🎯 Skill Level: Beginner
📋 Prerequisites: Basic programming knowledge

QBCore Framework Overview

QBCore is a comprehensive framework built for FiveM that provides:

Player Management: Character creation, data persistence, and session handling
Job System: Employment, salary, and role-based functionality
Economy: Money management, banking, and transactions
Inventory: Item management and interactions
Vehicle System: Ownership, keys, and modifications
Housing: Property ownership and management

Core Philosophy

QBCore follows these key principles:

Modular Design: Each feature is separate and can be modified independently
Event-Driven: Communication happens through events for loose coupling
Database-Centric: Player data persists in MySQL database
Extensible: Easy to add new features and modifications

Framework Structure

qbcore-framework/
├── qb-core/                 # Core framework
├── qb-multicharacter/       # Character selection
├── qb-spawn/               # Player spawning
├── qb-inventory/           # Inventory management
├── qb-houses/              # Housing system
├── qb-jobs/                # Job resources
│   ├── qb-ambulancejob/
│   ├── qb-policejob/
│   └── qb-mechanicjob/
└── qb-vehicles/            # Vehicle-related resources

Core Components

1. QB-Core (qb-core)

The heart of the framework that provides:

-- Core player object
QB.Player = {
    PlayerData = {},      -- All player information
    Functions = {},       -- Player-specific functions
    Events = {}          -- Player event handlers
}
 
-- Core functions
QB.Functions = {
    GetPlayer = function(source) end,
    GetPlayers = function() end,
    CreateCallback = function() end,
    TriggerCallback = function() end
}

Key Point: The QB-Core resource must always be running first as all other resources depend on it.

2. Player Data Structure

Every player in QBCore has a structured data object:

PlayerData = {
    source = 1,              -- Server ID
    citizenid = "ABC12345",  -- Unique character ID
    cid = 1,                 -- Character database ID
    money = {                -- Money accounts
        cash = 500,
        bank = 2000,
        crypto = 0
    },
    job = {                  -- Current job
        name = "unemployed",
        label = "Unemployed",
        payment = 10,
        onduty = false,
        grade = {}
    },
    gang = {},               -- Gang information
    position = {},           -- Last known position
    metadata = {},           -- Custom data storage
    items = {},             -- Inventory items
    charinfo = {}           -- Character details
}

3. Event System

QBCore uses FiveM’s event system for communication:

-- Server to Client
TriggerClientEvent('eventName', source, data)
 
-- Client to Server  
TriggerServerEvent('eventName', data)
 
-- Resource to Resource
TriggerEvent('eventName', data)

4. Database Integration

QBCore integrates with MySQL through oxmysql:

-- Database queries in QBCore
local result = MySQL.Sync.fetchAll('SELECT * FROM players WHERE citizenid = ?', {citizenid})
MySQL.Async.execute('UPDATE players SET money = ? WHERE citizenid = ?', {money, citizenid})

Resource Dependencies

Understanding how QBCore resources depend on each other:

Dependency Chain

qb-core (Always first)
├── qb-multicharacter
├── qb-spawn  
├── qb-inventory
└── All other resources

Resource Manifest Structure

Every QBCore resource has a fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'
 
description 'QB-ResourceName'
version '1.0.0'
 
shared_scripts {
    '@qb-core/shared/locale.lua',
    'locales/*.lua',
    'config.lua'
}
 
client_scripts {
    'client/main.lua'
}
 
server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/main.lua'
}
 
dependency 'qb-core'  -- Always depends on qb-core

File Organization

Standard QBCore Resource Structure

resource-name/
├── fxmanifest.lua      # Resource manifest
├── config.lua          # Configuration settings
├── client/             # Client-side code
│   └── main.lua
├── server/             # Server-side code
│   └── main.lua
├── shared/             # Shared between client/server
│   └── main.lua
└── locales/            # Translation files
    ├── en.lua
    └── es.lua

Data Flow

Understanding how data flows through QBCore:

Player Connection: MultiCharacter → Character Selection → Spawn
Data Loading: Database → PlayerData Object → Client Sync
Event Handling: User Action → Client Event → Server Processing → Database Update
Resource Communication: Resource A → QB-Core → Resource B

⚠️

Important: Always validate data on the server side. Never trust client-side data completely.

Common Patterns

1. Getting Player Data

-- Server-side
local Player = QB.Functions.GetPlayer(source)
if Player then
    local money = Player.PlayerData.money.cash
    local job = Player.PlayerData.job.name
end

2. Using Callbacks

-- Server-side callback creation
QB.Functions.CreateCallback('resource:getData', function(source, cb)
    local data = GetSomeData()
    cb(data)
end)
 
-- Client-side callback usage  
QB.Functions.TriggerCallback('resource:getData', function(data)
    -- Use the data
end)

3. Event Handling

-- Register event handler
RegisterNetEvent('resource:eventName', function(data)
    -- Handle the event
end)
 
-- Trigger the event
TriggerEvent('resource:eventName', data)

Best Practices

Code Organization

Keep client and server code separate
Use shared files for common data/functions
Follow QBCore naming conventions
Comment your code thoroughly

Performance

Cache player data when possible
Use callbacks for data requests
Avoid excessive database queries
Clean up unused variables and events

Security

Always validate server-side
Use source validation for player actions
Sanitize user inputs
Check player permissions before actions

What’s Next?

Now that you understand QBCore’s architecture:

Setting Up Your First Server - Get hands-on experience
Basic Commands & Admin Setup - Learn essential tools
Study Existing Resources - Look at qb-core and other default resources

Summary

QBCore is a modular, event-driven framework that provides:

Structured player data management
Event-based communication system
Database integration for persistence
Extensible resource system

Understanding this architecture is crucial for effective QBCore development!

Next Tutorial: Setting Up Your First Server

Overview Overview