QBox Framework Guide: Von QBCore migrieren und Performance steigern (2026)

QBox hat sich 2026 fest als natuerlicher Nachfolger von QBCore im FiveM-Roleplay-Oekosystem etabliert. Wenn du einen QBCore-Server betreibst und dich fragst, ob du den Wechsel machen solltest, oder wenn du frisch startest und zwischen Frameworks waehlst, deckt dieser Guide alles ab: echte Performance-Zahlen, einen Schritt-fuer-Schritt-Migrationsprozess, Code-Konvertierungsbeispiele und die Stolperfallen, die die meisten Serverbetreiber waehrend des Uebergangs erwischen.

Was ist QBox und warum gibt es das

QBox (manchmal als Qbox oder qbx geschrieben) ist ein FiveM-Roleplay-Framework, das von ehemaligen QBCore-Mitwirkenden gebaut wurde, die die Performance-, Sicherheits- und Codequalitaetsprobleme angehen wollten, die sich im Originalprojekt angesammelt hatten. Anstatt QBCore endlos zu patchen, forkten sie es und bauten die Architektur um das Overextended (ox)-Oekosystem herum neu auf.

Das Ergebnis ist ein modulares Framework, bei dem qbx_core als Fundament dient, aber die schwere Arbeit an zweckgebundene Bibliotheken delegiert wird: ox_lib fuer Utilities und UI, ox_inventory fuer Item-Management, oxmysql fuer Datenbankoperationen und ox_target fuer Interaktions-Targeting. Das ist kein monolithisches Framework. Jede Komponente kann unabhaengig aktualisiert werden, ohne den Rest deines Servers zu brechen.

QBox liefert mehrere Features direkt in qbx_core mit, die bei QBCore separate Ressourcen erforderten: Multicharakter-Auswahl, ein Server-Queue-System, Multijob- und Multigang-Unterstuetzung und Discord Rich Presence. All diese sind standardmaessig aktiviert und ueber einfache Lua-Config-Dateien konfigurierbar.

Performance-Benchmarks: QBox vs QBCore vs ESX

Performance-Behauptungen ohne Zahlen sind wertlos, also schauen wir uns tatsaechliche Benchmark-Daten aus der FiveM-Community von 2025-2026 an. Diese Zahlen stammen aus kontrollierten Tests mit identischen Serverkonfigurationen und 64 Spielern.

CPU-Verbrauchsvergleich

Framework	Core-Resource-CPU	Gesamter Framework-Overhead	Relative Performance
ESX Legacy	0,01-0,02ms	~0,30ms	Baseline (schnellstes)
QBox	0,00-0,01ms	~0,42ms	~25% mehr als ESX
QBCore	0,02-0,05ms	~0,73ms	~43% mehr als ESX

Speicherverbrauch

Framework	Core-Speicher	Mit Inventar	Gesamter Stack
ESX Legacy	~18 MiB	~25 MiB (qs-inventory)	~45 MiB
QBox	~22 MiB	~30 MiB (ox_inventory)	~55 MiB
QBCore	~28 MiB	~40 MiB (qb-inventory)	~75 MiB

Was diese Zahlen in der Praxis bedeuten

ESX Legacy bleibt der Roh-Performance-Champion. Das hat sich 2026 nicht geaendert. Allerdings schliesst QBox die Luecke im Vergleich zu QBCore deutlich und verbraucht je nach Serverlast und Skriptanzahl etwa 25-40% weniger CPU. Fuer die meisten Server ist der Unterschied zwischen ESX und QBox fuer Spieler nicht wahrnehmbar. Der Unterschied zwischen QBCore und QBox hingegen uebersetzt sich direkt in bessere Tick-Raten und fluessigeres Gameplay, besonders auf Servern mit 80+ Ressourcen.

QBox erreicht diese Verbesserungen durch mehrere architektonische Entscheidungen: Lazy Loading von Modulen, Eliminierung redundanter Polling-Schleifen, die in QBCore existierten, native Nutzung der optimierten Utility-Funktionen von ox_lib und ein saubereres Event-System, das unnoetige Netzwerktraffic reduziert.

Pre-Migrations-Checkliste

Bevor du eine einzige Datei auf deinem Produktionsserver anfasst, arbeite diese Checkliste durch. Das Ueberspringen eines dieser Schritte ist der Hauptgrund, warum Migrationen scheitern.

• Vollstaendiges Datenbank-Backup -- dumpe deine gesamte MySQL/MariaDB-Datenbank. Nicht nur die Players-Tabelle, alles. Verwende mysqldump --all-databases > backup_$(date +%Y%m%d).sql
• Vollstaendiges Serverdatei-Backup -- kopiere deinen gesamten Resources-Ordner, server.cfg und alle benutzerdefinierten Konfigurationsdateien an einen externen Speicherort
• Entwicklungsserver einrichten -- migriere nie zuerst auf der Produktion. Klone deinen Server in eine Testumgebung
• Aktuelle Ressourcenliste dokumentieren -- fuehre refresh in der txAdmin-Konsole aus und exportiere deine Ressourcenliste. Notiere, welche Skripte QBCore-nativ und welche von Drittanbietern sind
• Skript-Kompatibilitaet pruefen -- gleiche deine Skripte mit der Kompatibilitaetstabelle unten ab
• Auf die neueste QBCore-Version updaten -- wenn du eine alte QBCore-Version verwendest, update auf die neueste Version vor der Migration. Das eliminiert zusammengesetzte Probleme
• Datenbank-Collation pruefen -- die player.citizenid-Spalte muss die utf8mb4_unicode_ci-Collation verwenden. Pruefe und aendere sie bei Bedarf
• Dein Entwicklungsteam informieren -- Mitarbeiter, die mit QBCore-Events und Exports vertraut sind, brauchen Zeit, um Qbox- und ox_lib-Idiome zu lernen

Schritt-fuer-Schritt-Migration von QBCore zu QBox

Schritt 1: QBox ueber das txAdmin-Rezept installieren

Der sauberste Migrationspfad verwendet das offizielle txAdmin-Rezept. Dieses laedt alle erforderlichen Dateien automatisch herunter und konfiguriert sie: server.cfg, ox.cfg, permissions.cfg und voice.cfg.

Wenn du das Rezept nicht verwenden kannst (zum Beispiel bei einem benutzerdefinierten Hosting-Setup), lade qbx_core manuell vom QBox-GitHub-Repository herunter und folge den Konfigurationsdateien im txAdminRecipe-Repository.

Schritt 2: Den Overextended-Stack installieren

Installiere die ox-Abhaengigkeiten in genau dieser Reihenfolge und validiere, dass jede ohne Fehler startet, bevor du zur naechsten uebergehst:

1. oxmysql -- Datenbanktreiber (ersetzt mysql-async oder ghmattimysql)
2. ox_lib -- Utility-Bibliothek (UI-Elemente, Callbacks, Shared Functions)
3. ox_inventory -- Inventarsystem (ersetzt qb-inventory)
4. ox_target -- Interaktions-Targeting (ersetzt qb-target)

Deine server.cfg-Ressource-Start-Reihenfolge sollte diese Abhaengigkeitskette widerspiegeln:

ensure oxmysql
ensure ox_lib
ensure ox_inventory
ensure qbx_core
ensure ox_target
# ... deine anderen Ressourcen darunter

Schritt 3: ox_inventory fuer QBox konfigurieren

Fuege diesen Convar in deine server.cfg vor den Resource-Ensures hinzu:

setr inventory:framework "qbx"

Fuehre dann das ox_inventory-Datenbank-Konvertierungsskript aus. Dieses migriert deine bestehenden Item-Daten vom qb-inventory-Format in das ox_inventory-Format. Sichere deine Datenbank vor diesem Schritt. Die Konvertierung ist in der ox_inventory-Dokumentation dokumentiert.

Schritt 4: Job- und Gang-Grade-Formate konvertieren

Das ist die haeufigste Fehlerquelle bei der Migration. In QBCore werden Job-Grades als Strings gespeichert. In QBox sind es Numbers.

QBCore-Format (jobs.lua):

['police'] = {
    label = 'Law Enforcement',
    grades = {
        ['0'] = { name = 'Recruit', payment = 500 },
        ['1'] = { name = 'Officer', payment = 750 },
        ['2'] = { name = 'Sergeant', payment = 1000 },
        ['3'] = { name = 'Lieutenant', payment = 1250 },
        ['4'] = { name = 'Chief', payment = 1500, isboss = true },
    },
},

QBox-Format (jobs.lua):

['police'] = {
    label = 'Law Enforcement',
    grades = {
        [0] = { name = 'Recruit', payment = 500 },
        [1] = { name = 'Officer', payment = 750 },
        [2] = { name = 'Sergeant', payment = 1000 },
        [3] = { name = 'Lieutenant', payment = 1250 },
        [4] = { name = 'Chief', payment = 1500, isboss = true },
    },
},

Die Aenderung ist subtil, aber kritisch: ['0'] wird zu [0], ['1'] wird zu [1], und so weiter. Wende das sowohl auf qbx_core/shared/jobs.lua als auch auf qbx_core/shared/gangs.lua an.

Schritt 5: QBox-SQL-Migration ausfuehren

Fuehre die qbx_core.sql-Datei aus, die mit qbx_core geliefert wird. Diese erstellt die zusaetzlichen Datenbanktabellen, die QBox benoetigt, einschliesslich Tabellen fuer die Multijob- und Multigang-Systeme. Wenn deine player.citizenid-Spalte nicht die utf8mb4_unicode_ci-Collation hat, behebe das zuerst, sonst schlaegt das SQL fehl.

Schritt 6: Built-in Features konfigurieren

QBox buendelt Features, die bei QBCore separate Ressourcen waren. Entscheide, welche du willst:

-- qbx_core/config/client.lua
Config = {
    useExternalCharacters = false,  -- auf true setzen, wenn du eine separate Multichar-Ressource verwendest
    -- Discord Rich Presence Einstellungen am Ende der Datei
}

-- server.cfg
setr qbx:enablequeue true          # eingebautes Queue-System
setr qbx:max_jobs_per_player 1     # Multijob-Limit (kann nicht deaktiviert werden)
setr qbx:max_gangs_per_player 1    # Multigang-Limit (kann nicht deaktiviert werden)

Schritt 7: Testen und validieren

Starte deinen Entwicklungsserver und teste systematisch jede Ressource. Konzentriere dich auf:

• Spieler-Spawning und Charakter-Auswahl
• Inventar-Operationen (geben, nehmen, Items verwenden)
• Job-Aktionen und Grade-basierte Berechtigungen
• Fahrzeug-Spawning und Garagen-Systeme
• Banking und Geldtransaktionen
• Telefonfunktionalitaet

Skripte konvertieren: Code-Beispiele

Obwohl QBox eine circa 99%-ige Rueckwaertskompatibilitaet mit QBCore-Skripten aufrechterhaelt, verbessert die Konvertierung deiner Ressourcen auf native QBox-APIs die Performance und macht deinen Code zukunftssicher. Das Core-Objekt (QBCore = exports['qb-core']:GetCoreObject()) existiert in QBox nicht mehr. Stattdessen verwendest du Exports und importierte Module.

fxmanifest.lua aktualisieren

Fuege zuerst die QBox-Modul-Imports zum Manifest deines Skripts hinzu:

fx_version 'cerulean'
game 'gta5'

lua54 'yes'

shared_scripts {
    '@ox_lib/init.lua',
    '@qbx_core/modules/lib.lua',
}

client_scripts {
    '@qbx_core/modules/playerdata.lua',
    'client/main.lua',
}

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/main.lua',
}

Gaengige Funktionsersetzungen

Hier ist ein praktisches Vorher-Nachher fuer ein typisches Client-Skript:

Vorher (QBCore):

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('myresource:client:doSomething', function()
    local PlayerData = QBCore.Functions.GetPlayerData()
    local job = PlayerData.job.name
    local plate = QBCore.Functions.GetPlate(GetVehiclePedIsIn(PlayerPedId(), false))

    if job == 'police' then
        exports['qb-core']:DrawText('You are on duty', 'left')
        Wait(3000)
        exports['qb-core']:HideText()
    end
end)

Nachher (QBox):

RegisterNetEvent('myresource:client:doSomething', function()
    local job = QBX.PlayerData.job.name
    local plate = qbx.getVehiclePlate(GetVehiclePedIsIn(PlayerPedId(), false))

    if job == 'police' then
        lib.showTextUI('You are on duty', { position = 'left-center' })
        Wait(3000)
        lib.hideTextUI()
    end
end)

Beachte: keine Core-Objekt-Initialisierung, kein Exports-Aufruf um den Core zu holen. QBX.PlayerData ist direkt ueber das importierte playerdata-Modul verfuegbar, und qbx.getVehiclePlate() kommt vom lib-Modul.

Callback-Migration

Hier brechen die meisten Skript-Konvertierungen. QBCore-Callbacks feuern nicht auf QBox, wenn du das alte Registrierungsmuster verwendest:

Vorher (QBCore):

-- Server
QBCore.Functions.CreateCallback('myresource:server:getData', function(source, cb)
    local result = MySQL.query.await('SELECT * FROM my_table')
    cb(result)
end)

-- Client
QBCore.Functions.TriggerCallback('myresource:server:getData', function(result)
    print(json.encode(result))
end)

Nachher (QBox / ox_lib):

-- Server
lib.callback.register('myresource:server:getData', function(source)
    return MySQL.query.await('SELECT * FROM my_table')
end)

-- Client
local result = lib.callback.await('myresource:server:getData')
print(json.encode(result))

Das ox_lib-Callback-System ist sauberer und eliminiert das Callback-Pyramiden-Muster. Es verwendet await statt verschachtelter Callbacks, was deinen Code deutlich lesbarer macht.

Vollstaendige Ersetzungsreferenz

QBCore	QBox-Aequivalent
QBCore.Functions.GetPlayerData()	QBX.PlayerData
QBCore.Functions.GetPlate(vehicle)	qbx.getVehiclePlate(vehicle)
QBCore.Shared.Jobs	exports.qbx_core:GetJobs()
QBCore.Shared.Gangs	exports.qbx_core:GetGangs()
QBCore.Shared.Vehicles	exports.qbx_core:GetVehiclesByName()
QBCore.Shared.Weapons	exports.qbx_core:GetWeapons()
QBCore.Shared.Items	exports.ox_inventory:Items()
exports['qb-core']:DrawText()	lib.showTextUI()
exports['qb-core']:HideText()	lib.hideTextUI()
QBCore.Functions.CreateCallback	lib.callback.register
QBCore.Functions.TriggerCallback	lib.callback.await

Skript-Kompatibilitaetstabelle

Hier ist der aktuelle Kompatibilitaetsstatus beliebter Skripte mit QBox, Stand Maerz 2026:

Skript-Kategorie	Beliebte Skripte	QBox-Status	Hinweise
Inventar	ox_inventory	Nativ	Standard mit QBox
Telefon	qb-phone / lb-phone	Kompatibel	Funktioniert via Bridge-Layer
Housing	qb-houses / bcs-housing	Kompatibel	Kleine Config-Aenderungen
Fahrzeuge	qb-vehicleshop	Kompatibel	Funktioniert ohne Aenderungen
Garagen	qb-garages / jg-advancedgarages	Kompatibel	Funktioniert ohne Aenderungen
Banking	qb-banking / Renewed-Banking	Update noetig	Muss an ox_inventory Money angepasst werden
Polizei	qb-policejob	Kompatibel	QBox hat nativen Ersatz (qbx_policejob)
Rettungsdienst	qb-ambulancejob	Kompatibel	QBox hat nativen Ersatz (qbx_ambulancejob)
Mechaniker	qb-mechanicjob	Kompatibel	Funktioniert via Bridge-Layer
Crafting	qb-crafting	Update noetig	Muss ox_inventory Crafting API verwenden
Target	ox_target	Nativ	Ersetzt qb-target
UI/TextUI	ox_lib	Nativ	Ersetzt qb-core DrawText
Multicharacter	In qbx_core integriert	Nativ	Keine separate Ressource noetig
Loading Screen	Custom	Kompatibel	Framework-unabhaengig
HUD	qb-hud / ps-hud	Kompatibel	Funktioniert ohne Aenderungen
Doorlock	ox_doorlock	Nativ	Ersetzt qb-doorlock

Haeufige Migrationsfallen und wie man sie vermeidet

1. Job-Grades als Strings statt Numbers

Das ist der haeufigste Migrationsfehler. Wenn deine Skripte oder Datenbank Job-Grades immer noch als Strings referenzieren ('0', '1'), werden Dinge leise kaputtgehen. Grade-basierte Berechtigungspruefungen schlagen fehl, Boss-Menues laden nicht, und Job-Aktionen werden ohne klare Fehlermeldungen abgelehnt.

Loesung: Durchsuche deinen gesamten Resources-Ordner nach Grade-Vergleichen und stelle sicher, dass sie Numbers verwenden. Pruefe auch deine Datenbankeintraege.

2. Callbacks die nie zurueckkehren

Wenn du zu QBox migrierst, aber Skripte behaeltst, die QBCore.Functions.CreateCallback verwenden, haengen diese Callbacks auf der Client-Seite unbegrenzt. Der QBCore-Bridge repliziert das alte Callback-System nicht vollstaendig.

Loesung: Konvertiere alle Callbacks zu lib.callback.register und lib.callback.await von ox_lib.

3. Inventar-Item-Name-Konflikte

ox_inventory verwendet ein anderes Item-Registrierungssystem als qb-inventory. Items, die in qb-core/shared/items.lua definiert sind, muessen stattdessen in der ox_inventory-Items-Konfiguration registriert werden.

Loesung: Fuehre das ox_inventory-Konvertierungstool aus und verifiziere, dass alle Item-Namen ueber deine Skripte hinweg uebereinstimmen.

4. Datenbanktreiber-Konflikte

mysql-async neben oxmysql auszufuehren verursacht Connection-Pool-Konflikte und Race Conditions.

Loesung: Entferne mysql-async vollstaendig. Ersetze alle mysql-async-Aufrufe durch oxmysqls Await-API-Muster.

5. Ressourcen in falscher Reihenfolge starten

ox_lib muss vor qbx_core starten. ox_inventory muss vor den meisten Gameplay-Ressourcen starten. Das falsch zu machen verursacht kaskadenartige Nil-Reference-Errors.

Loesung: Folge genau der Ressource-Start-Reihenfolge aus Schritt 2 des Migrationsabschnitts oben.

Solltest du 2026 migrieren?

Die ehrliche Antwort haengt von deiner Situation ab:

Jetzt migrieren, wenn:

• Du einen neuen Server von Grund auf startest
• Du ohnehin eine grosse Server-Ueberarbeitung planst
• Du Performance-Probleme auf QBCore mit 60+ Spielern erlebst
• Dein Entwicklungsteam modernere Tools und sauberere APIs moechte

Warten oder ueberspringen, wenn:

• Dein Server stabil ist, die Spieler zufrieden sind und du keine Performance-Beschwerden hast
• Du stark auf Skripte angewiesen bist, die tief in QBCore-Internals eingreifen
• Dein Team nicht die Kapazitaet fuer Tests und Validierung hat

Fuer neue Server 2026 ist QBox die klare Empfehlung. Es bietet bessere Performance als QBCore, eine moderne Entwicklererfahrung durch das ox-Oekosystem und aktive Wartung durch ein dediziertes Team. Der Rueckwaertskompatibilitaets-Layer bedeutet, dass du nicht vom riesigen QBCore-Skript-Oekosystem ausgesperrt bist, und der Migrationspfad ist gut dokumentiert.

Wenn du den Framework-Vergleich vertiefen moechtest, schau dir unseren QBox vs QBCore-Vergleich an oder tauche in den kompletten QBox- und Ox-Stack-Guide ein, um das volle Bild zu bekommen, wie das Overextended-Oekosystem zusammenpasst.

Fuer Server, die sich mit kompatiblen Skripten eindecken moechten, durchstoebere unsere FiveM-Skript-Sammlung -- wir testen alle Skripte auf QBox-Kompatibilitaet und kennzeichnen sie entsprechend.