FiveM Scripts konvertieren: ESX, QBCore und QBOX (Framework-Guide)

Das Konvertieren von FiveM-Scripts zwischen Frameworks ist eine der häufigsten Aufgaben für Server-Entwickler. Ob du von ESX auf QBCore migrierst, oder von QBCore auf QBOX wechselst — die Grundprinzipien sind dieselben, aber die API-Details unterscheiden sich erheblich.

Dieser Guide ist Teil unseres ESX-Legacy-Guides 2026, der ESX's aktuellen Stand und Migrationsoptionen abdeckt.

---

Grundprinzipien der Script-Konvertierung

Bevor wir in Code-Beispiele eintauchen, drei universelle Regeln:

1. Immer zuerst lesen, dann portieren — Verstehe was das Script tut, bevor du anfängst zu ändern.
2. Server-seitig zuerst — Konvertiere Server-Events und Callbacks zuerst, dann Client-Side.
3. Teste nach jeder Änderung — Nicht alles auf einmal ändern und dann debuggen.

---

ESX → QBCore Konvertierung

Player-Daten

ESX:

-- Server-side
local xPlayer = ESX.GetPlayerFromId(source)
local money = xPlayer.getMoney()
local job = xPlayer.job.name
local grade = xPlayer.job.grade

xPlayer.addMoney(500)
xPlayer.setJob('police', 3)

QBCore:

-- Server-side
local Player = QBCore.Functions.GetPlayer(source)
local money = Player.PlayerData.money['cash']
local job = Player.PlayerData.job.name
local grade = Player.PlayerData.job.grade.level

Player.Functions.AddMoney('cash', 500)
Player.Functions.SetJob('police', 3)

Wichtige Unterschiede:

• ESX: xPlayer.getMoney() / QBCore: Player.PlayerData.money['cash']
• ESX: xPlayer.job.grade (Zahl) / QBCore: Player.PlayerData.job.grade.level (Objekt)
• QBCore unterscheidet zwischen Geld-Typen: cash, bank, crypto

---

Inventar und Items

ESX:

-- Item hinzufügen
xPlayer.addInventoryItem('water', 1)

-- Item entfernen
xPlayer.removeInventoryItem('water', 1)

-- Item-Check
local hasItem = xPlayer.canCarryItem('water', 1)

QBCore:

-- Item hinzufügen
Player.Functions.AddItem('water', 1)
-- oder via exports wenn ox_inventory:
exports.ox_inventory:AddItem(source, 'water', 1)

-- Item entfernen
Player.Functions.RemoveItem('water', 1)

-- Item-Check
local hasItem = Player.Functions.GetItemByName('water')

Events

ESX:

-- Client-side Shared Object
ESX = nil
TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)

-- Player-Loaded Event
AddEventHandler('esx:playerLoaded', function(xPlayer)
    -- ...
end)

QBCore:

-- Client-side Core Object
local QBCore = exports['qb-core']:GetCoreObject()

-- Player-Loaded Event
AddEventHandler('QBCore:Client:OnPlayerLoaded', function()
    local PlayerData = QBCore.Functions.GetPlayerData()
    -- ...
end)

Notifications

ESX:

-- Client-side
ESX.ShowNotification('Nachricht hier')
ESX.ShowAdvancedNotification('Titel', 'Untertitel', 'Nachricht', 'CHAR_HUMANDEFAULT', 1)

QBCore:

-- Client-side
QBCore.Functions.Notify('Nachricht hier', 'success')
-- Typen: success, error, primary, warning

Mit ox_lib (empfohlen für beide):

lib.notify({
    title = 'Titel',
    description = 'Nachricht',
    type = 'success' -- success, error, inform, warning
})

---

QBCore → QBOX Konvertierung

QBOX ist ein QBCore-Fork, daher sind die Änderungen weniger drastisch als bei ESX→QBCore.

Core-Import

QBCore:

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

QBOX:

-- QBOX nutzt direkte Module-Imports
local player = require '@qbox-core.modules.player'
-- oder je nach Modul:
local money = require '@qbox-core.modules.money'

UI und Benachrichtigungen

QBCore (eigene UI):

QBCore.Functions.Notify('Nachricht', 'success')
exports['qb-menu']:openMenu({ ... })

QBOX (ox_lib required):

-- ox_lib ist Pflicht in QBOX
lib.notify({ title = 'Titel', description = 'Nachricht', type = 'success' })
lib.showContext({ ... }) -- Context-Menüs
lib.progressBar({ ... }) -- Progress Bars

Inventar

QBCore:

-- qb-inventory
Player.Functions.AddItem('water', 1)
Player.Functions.RemoveItem('water', 1)

QBOX:

-- ox_inventory (Standard in QBOX)
exports.ox_inventory:AddItem(source, 'water', 1)
exports.ox_inventory:RemoveItem(source, 'water', 1)

---

Framework-Detection (Dual-Support)

Wenn du ein Script für beide Frameworks anbieten willst:

-- Framework-Detection
local QBCore, ESX

if GetResourceState('qb-core') == 'started' then
    QBCore = exports['qb-core']:GetCoreObject()
elseif GetResourceState('es_extended') == 'started' then
    TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)
end

-- Wrapper-Funktionen
local function GetPlayer(source)
    if QBCore then
        return QBCore.Functions.GetPlayer(source)
    elseif ESX then
        return ESX.GetPlayerFromId(source)
    end
end

local function AddMoney(source, amount)
    if QBCore then
        local Player = QBCore.Functions.GetPlayer(source)
        if Player then Player.Functions.AddMoney('cash', amount) end
    elseif ESX then
        local xPlayer = ESX.GetPlayerFromId(source)
        if xPlayer then xPlayer.addMoney(amount) end
    end
end

---

Häufige Fallstricke

1. Identifier vs. CitizenID

ESX verwendet den Rockstar-/Steam-Identifier als primären Schlüssel:

local identifier = xPlayer.identifier -- "steam:110000112345678"

QBCore/QBOX verwendet CitizenID:

local citizenid = Player.PlayerData.citizenid -- "ABC12345"

Beim Datenbankschema beachten: Wenn du von ESX migrierst, müssen alle Datenbank-Abfragen angepasst werden.

2. Job-Struktur

ESX:

xPlayer.job = { name = 'police', grade = 3 }

QBCore:

Player.PlayerData.job = {
    name = 'police',
    label = 'Polizei',
    grade = { name = 'officer', level = 3 }
}

3. Callback-Systeme

ESX:

ESX.RegisterServerCallback('myScript:getData', function(source, cb)
    cb({ data = 'wert' })
end)

-- Client
ESX.TriggerServerCallback('myScript:getData', function(result) end)

QBCore:

QBCore.Functions.CreateCallback('myScript:getData', function(source, cb)
    cb({ data = 'wert' })
end)

-- Client
QBCore.Functions.TriggerCallback('myScript:getData', function(result) end)

ox_lib (empfohlen für alle):

-- Server
lib.callback.register('myScript:getData', function(source)
    return { data = 'wert' }
end)

-- Client
local result = lib.callback.await('myScript:getData', false)

---

Konvertierungs-Checkliste

Wenn du ein Script konvertierst, gehe diese Liste durch:

• [ ] Shared Object / Core-Import angepasst
• [ ] Player-Daten-Zugriff (getMoney → PlayerData.money etc.)
• [ ] Inventar-Funktionen (addInventoryItem → AddItem / ox_inventory)
• [ ] Job-Daten-Zugriff
• [ ] Notifications/UI-Calls
• [ ] Callbacks (ESXCallback → QBCallback → lib.callback)
• [ ] Identifier/CitizenID in DB-Abfragen
• [ ] Events (esx:playerLoaded → QBCore:Client:OnPlayerLoaded)
• [ ] fxmanifest.lua Dependencies aktualisiert

---

Fazit

Script-Konvertierungen zwischen ESX, QBCore und QBOX folgen immer denselben Mustern: Player-Daten, Inventar, Events und Callbacks. Wer die Unterschiede in den Core-APIs kennt, kann die meisten Scripts in wenigen Stunden portieren.

Für detaillierte Framework-Vergleiche lies unseren technischen Framework-Vergleich 2026.