So migrierst du ESX → QBCore richtig

Du möchtest einen sauberen Wechsel von ESX zu QBCore ohne Datenverlust oder den Ausfall von Kernsystemen. Folge diesem Plan. Du wirst am Ende stabile Identifikatoren, oxmysql-Abfragen und ox_lib-basierten Code haben.

Dieser Guide ist Teil unseres vollständigen FiveM-Frameworks-Guides, in dem wir ESX, QBCore und QBOX ausführlich vergleichen und dir helfen, das richtige zu wählen.

Ziel: Deinen Server mit minimalen Ausfallzeiten von ESX zu QBCore zu migrieren.

---

Überblick

• Voraussetzungen
• Schritt 1. Einen Plan und einen Rollback-Punkt erstellen
• Schritt 2. Eine saubere QBCore-Basis aufbauen
• Schritt 3. mysql-async durch oxmysql ersetzen
  • Häufige Konvertierungen
  • Schritt 4. ESX-Datenstrukturen auf QBCore mappen
  • Schritt 5. Identifikatoren stabilisieren
    • SQL-Bootstrap
    • citizenid generieren und Spieler in Lua einfügen
    • Fahrzeuge übertragen
    • Schritt 6. ESX-Code mit ox_lib auf QBCore portieren
      • Spielerobjekt
      • Jobs
      • Callbacks und UI
      • Befehle
      • Schritt 7. Inventar und Items
      • Schritt 8. Testen und Ausrollen
      • Fehlerbehebung
      • Cutover-Checkliste
      • Anhang A. Beispiel-fxmanifest für Migrationshelfer
      • Anhang B. Sichere JSON-Helfer
      • Was du erreicht hast
      • Nützliche Links auf deiner Seite
      • Externe Referenzen

---

Voraussetzungen

1. Tools
   1. GIT und ein separater Branch für die Migration.
   2. MariaDB oder MySQL 8 mit aktivierten vollständigen Backups.
   3. Ein Staging-Server, der die Produktion spiegelt.
   4. Server-Artifacts
      1. FXServer auf denselben Build wie Produktion aktualisiert.
      2. QBCore Basis-Framework und Standard-Ressourcen.
      3. Bibliotheken, die du verwenden wirst

         1. oxmysql für die Datenbank.

         2. ox_lib für Callbacks, UI-Helfer und Utility-Wrapper.

            ---

            Schritt 1. Einen Plan und einen Rollback-Punkt erstellen

            1. Produktionsänderungen einfrieren. Stoppt neue Skript-Installationen und DB-Schreibvorgänge, die nicht zum Testen erforderlich sind.
            2. Deine gesamte Datenbank als benannten Snapshot sichern.
            3. Dein Server-Repository branchen und einen dedizierten migrate-esx-to-qbcore-Branch erstellen.
            4. Ein Runbook schreiben. Enthält Befehle zum Starten und Stoppen des Staging-Servers, zur DB-Wiederherstellung und zur Ausführung von Health-Checks.

            ---

            Schritt 2. Eine saubere QBCore-Basis aufbauen

            1. Eine frische QBCore-Basis auf Staging deployen.
            2. Nur das Wesentliche aktiviert lassen. Jobs, Inventare und benutzerdefinierte Skripte deaktivieren, bis nach der DB-Migration.
            3. Diese Ressourcen zuerst installieren und starten

               1. qb-core

               2. qb-vehicles oder deine bevorzugten Ersetzungen

               3. oxmysql

               4. ox_lib

                  ---

                  Schritt 3. mysql-async durch oxmysql ersetzen

                  Wenn verbleibende ESX-Skripte noch MySQL.Async verwenden, konvertiere die Aufrufe zu oxmysql. Verwende einfaches Suchen und Ersetzen mit Überprüfung.

                  Häufige Konvertierungen

                        -- ESX mysql-async
                        MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @id', {['@id'] = identifier}, function(rows)
                          -- ...
                        end)

                        -- QBCore oxmysql
                        local rows = MySQL.query.await('SELECT * FROM players WHERE citizenid = ?', { citizenid })
                        -- rows ist eine Lua-Tabelle; nil und Längenprüfungen direkt behandeln

                        -- ESX scalar Beispiel
                        MySQL.Async.fetchScalar('SELECT COUNT(1) FROM owned_vehicles', {}, function(count)
                          -- ...
                        end)

                        -- oxmysql scalar
                        local count = MySQL.scalar.await('SELECT COUNT(1) FROM player_vehicles')

                        -- ESX insert
                        MySQL.Async.execute('INSERT INTO addon_account VALUES (@owner, @name, @money)', {
                          ['@owner'] = identifier, ['@name'] = name, ['@money'] = money
                        })

                        -- oxmysql insert
                        MySQL.prepare.await('INSERT INTO player_accounts (citizenid, name, amount) VALUES (?, ?, ?)', { citizenid, name, amount })

Hinweise

1. Bevorzuge query.await, scalar.await und prepare.await für sauberen Ablauf.
2. Verwende prepared statements für Schreibvorgänge.

---

Schritt 4. ESX-Datenstrukturen auf QBCore mappen

Du wirst Spieleridentitäten und Entities migrieren. Verwende diese Referenz zum Mappen von Tabellen.

                        ESX-Tabelle

Schlüsselspalte

                        QBCore-Tabelle

Schlüsselspalte

Hinweise

users

identifier

players

citizenid

Identifikatoren konvertieren und citizenid für jede Zeile erstellen

owned_vehicles

owner

player_vehicles

citizenid

Kennzeichenformatierung und JSON-Payloads konvertieren

datastore_data

owner

player_metadata

citizenid

Wenn du JSON speicherst, sorgfältig zusammenführen

addon_account_data

owner

player_accounts

citizenid

Kontonamen auf QBCore-Banking oder Cash mappen

addon_inventory_items

owner

player_inventories

citizenid

Wenn du zu ox_inventory wechselst, separat migrieren

Du kannst benutzerdefinierte Tabellen behalten. Passe nur Fremdschlüssel an, die ESX-Identifikatoren referenzieren.

---

Schritt 5. Identifikatoren stabilisieren

                        ESX speichert oft einen CFX-Identifikator wie `license:xxxx` oder historisch `steam:xxxx`. QBCore verwendet `citizenid` als stabilen Spielerschlüssel und behält die Laufzeit-Identifikatoren nur zur Authentifizierung.

Du wirst

1. Eine citizenid für jeden Spieler erstellen.
2. Legacy-Identifikatoren mit dem neuen Datensatz verknüpfen.
3. Eine Lookup-Tabelle für Support und Audits führen.

SQL-Bootstrap

Führe dies auf einer Kopie deiner ESX-Datenbank aus, um QBCore-Tabellen vorzubereiten.

                        -- 1) players-Tabelle erstellen, falls fehlend. An dein QBCore-Schema anpassen.
                        CREATE TABLE IF NOT EXISTS players (
                          citizenid VARCHAR(11) PRIMARY KEY,
                          license VARCHAR(64) UNIQUE,

identifiers JSON NOT NULL,

                          name VARCHAR(64),

charinfo JSON NOT NULL, metadata JSON NOT NULL, money JSON NOT NULL, job JSON NOT NULL,

                          position VARCHAR(128) DEFAULT NULL,

created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

                        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

                        -- 2) Eine Hilfsfunktion in SQL mit einem deterministischen Generator wäre komplex.
                        -- Stattdessen das Mapping in einer separaten Tabelle vorbereiten und citizenid in Lua generieren.
                        CREATE TABLE IF NOT EXISTS legacy_identifier_map (
                          license VARCHAR(64) PRIMARY KEY,
                          steam VARCHAR(64) NULL,
                          fivem VARCHAR(64) NULL,
                          discord VARCHAR(64) NULL,
                          xbl VARCHAR(64) NULL,
                          liveid VARCHAR(64) NULL,
                          citizenid VARCHAR(11) UNIQUE
                        );

                        -- 3) Das Mapping aus ESX-Users befüllen
                        INSERT INTO legacy_identifier_map (license)
                        SELECT DISTINCT REPLACE(identifier, 'identifier:', '')

FROM users

                        WHERE identifier LIKE 'license:%' OR identifier LIKE 'steam:%';

citizenid generieren und Spieler in Lua einfügen

Einmal auf Staging ausführen. Zuerst sichern.

                        -- server/migrate_identifiers.lua
                        local QBCore = exports['qb-core']:GetCoreObject()

                        local function generateCitizenId()
                          local charset = {}
                          for c = 65, 90 do table.insert(charset, string.char(c)) end
                          for n = 48, 57 do table.insert(charset, string.char(n)) end
                          math.randomseed(GetGameTimer())
                          local id = {}
                          for i = 1, 11 do id[i] = charset[math.random(1, #charset)] end
                          return table.concat(id)
                        end

                        local rows = MySQL.query.await('SELECT license FROM legacy_identifier_map WHERE citizenid IS NULL')
                        for _, r in ipairs(rows) do
                          local citizenid = generateCitizenId()
                          MySQL.prepare.await('UPDATE legacy_identifier_map SET citizenid = ? WHERE license = ?', { citizenid, r.license })
                        end

                        -- Spieler aus ESX-Users aufbauen
                        local users = MySQL.query.await([[SELECT u.identifier, u.firstname, u.lastname, u.dateofbirth, u.sex, u.height
                                                          FROM users u]])
                        for _, u in ipairs(users) do
                          local license = u.identifier
                          local map = MySQL.single.await('SELECT citizenid FROM legacy_identifier_map WHERE license = ?', { license })
                          if map and map.citizenid then
                            local name = string.format('%s %s', u.firstname or 'John', u.lastname or 'Doe')
                            local charinfo = json.encode({ firstname = u.firstname, lastname = u.lastname, birthdate = u.dateofbirth, gender = u.sex, height = u.height })
                            local metadata = json.encode({ hunger = 100, thirst = 100 })
                            local money = json.encode({ cash = 0, bank = 0, crypto = 0 })
                            local job = json.encode({ name = 'unemployed', label = 'Unemployed', grade = { name = '0', level = 0 }})

                            MySQL.prepare.await('INSERT IGNORE INTO players (citizenid, license, identifiers, name, charinfo, metadata, money, job) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', {

map.citizenid, license,

                              json.encode({ license = license }),

name, charinfo, metadata, money, job

                            })
                          end
                        end
                        print('Identifikator-Migration abgeschlossen')

Fahrzeuge übertragen

                        INSERT IGNORE INTO player_vehicles (citizenid, plate, vehicle, garage, state)
                        SELECT m.citizenid,
                               UPPER(JSON_UNQUOTE(JSON_EXTRACT(v.vehicle, '$.plate'))),

v.vehicle,

                               'legion',

1 FROM owned_vehicles v

                        JOIN legacy_identifier_map m ON m.license = v.owner;

Zufällige Stichproben im Spiel validieren. Kennzeichenformate und Garagen überprüfen.

---

Schritt 6. ESX-Code mit ox_lib auf QBCore portieren

Ersetze die ESX-Runtime-API durch QBCore-Äquivalente. Verwende ox_lib für Callbacks und Benachrichtigungen.

Spielerobjekt

                        -- ESX
                        local xPlayer = ESX.GetPlayerFromId(src)
                        xPlayer.addMoney(100)

                        -- QBCore
                        local Player = QBCore.Functions.GetPlayer(src)
                        Player.Functions.AddMoney('cash', 100)

Jobs

                        -- ESX Job-Prüfung
                        if xPlayer.getJob().name == 'police' then
                          -- ...
                        end

                        -- QBCore Job-Prüfung
                        local job = Player.PlayerData.job
                        if job and job.name == 'police' then
                          -- ...
                        end

Callbacks und UI

                        -- ESX Server-Callback
                        ESX.RegisterServerCallback('resource:getData', function(source, cb)
                          cb({ ok = true })
                        end)

                        -- ox_lib Callback
                        lib.callback.register('resource:getData', function(source)
                          return { ok = true }
                        end)

                        -- Benachrichtigung
                        lib.notify(source, { title = 'Job', description = 'Beförderung gewährt', type = 'success' })

Befehle

                        -- ESX
                        RegisterCommand('pay', function(src, args)
                          local amount = tonumber(args[1]) or 0
                          xPlayer.removeMoney(amount)
                        end)

                        -- QBCore mit Berechtigungen
                        QBCore.Commands.Add('pay', 'Bargeld bezahlen', {{name = 'amount', help = 'Betrag'}}, false, function(src, args)
                          local amount = tonumber(args[1]) or 0
                          local Player = QBCore.Functions.GetPlayer(src)
                          Player.Functions.RemoveMoney('cash', amount)
                        end)

---

Schritt 7. Inventar und Items

Wenn du von es_extended-Inventaren zu qb-inventory oder ox_inventory wechselst, behandle dies als separate Teil-Migration.

1. Item-Hinzufügungen einfrieren.
2. Die Item-Masterliste exportieren.
3. Item-Namen eins zu eins mappen.
4. Spieler-Inventare in Batches migrieren. Stack-Größen und Gewichte validieren.

Beispiel Item-Mapping CSV

esx_name,qb_name,notes bread,bread, water,water, lockpick,lockpick,

---

Schritt 8. Testen und Ausrollen

1. Unit-Tests
   1. Identifikator-Lookups für eine zufällige Auswahl von Spielern testen.
   2. Geldtransfers, Job-Änderungen und Fahrzeugbesitz testen.
   3. Gameplay-Tests
      1. Spieler mit alten ESX-Identifikatoren spawnen und automatisches Mapping bestätigen.
      2. Einen Polizeidienst-Flow, einen Ladenraub und einen Fahrzeugkauf durchführen.
      3. Performance-Tests
         1. resmon verwenden, um CPU und Speicher zu beobachten.
         2. Bestätigen, dass die DB-Abfrageanzahl nach der oxmysql-Konvertierung gesunken ist.
         3. Rollout-Plan

            1. Staging-DB während eines Wartungsfensters in die Produktion verschieben.

            2. 60-minütige Ausfallzeit ankündigen.

            3. Logs auf fehlende Identifikatoren und Fremdschlüsselfehler überwachen.

               ---

               Fehlerbehebung

               1. Duplizierte Citizens
                  1. Ursache: Migration wurde zweimal ausgeführt.
                  2. Fix: Eindeutige Schlüssel auf citizenid erzwingen und INSERT IGNORE beim Seeding verwenden.
                  3. Fehlende Fahrzeuge
                     1. Ursache: Owner-Schlüssel-Mismatch zwischen owned_vehicles.owner und legacy_identifier_map.license.
                     2. Fix: Owner-Werte normalisieren und den Fahrzeug-Insert für die betroffenen Kennzeichen erneut ausführen.
                     3. Spieler spawnen ohne Inventar
                        1. Ursache: Inventar-Migration übersprungen.
                        2. Fix: Inventar-Mapping neu aufbauen und reimportieren.
                        3. Skripte schlagen mit MySQL.Async nicht gefunden fehl

                           1. Ursache: Skript hängt noch von mysql-async ab.

                           2. Fix: Aufrufe durch oxmysql ersetzen und mysql-async vom Server entfernen.

                              ---

                              Cutover-Checkliste

                              1. Produktionsdatenbank mit einem Zeitstempel sichern.
                              2. Server stoppen und Spieler-Joins sperren.
                              3. Den finalen Staging-Dump in die Produktion zurückspielen.
                              4. QBCore-Build mit qb-core, oxmysql, ox_lib zuerst in der Ensure-Reihenfolge deployen.
                              5. Das Identifikator-Seeding-Skript einmal ausführen.
                              6. Konvertierte Skripte nur aktivieren, wenn ihre Abfragen auf oxmysql sind.
                              7. Server wieder öffnen und Logs 30 Minuten lang beobachten.
                              8. Rollback-Plan posten, wenn kritische Fehler auftreten.

                              ---

                              Anhang A. Beispiel-fxmanifest für Migrationshelfer

                              fx_version 'cerulean'

                                                                game 'gta5'

                                                                lua54 'yes'

                                                                server_scripts {
                                                                  '@oxmysql/lib/MySQL.lua',
                                                                  '@ox_lib/init.lua',
                                                                  'server/migrate_identifiers.lua'
                                                                }

---

Anhang B. Sichere JSON-Helfer

                                                                local function safeDecode(jsonStr, fallback)
                                                                  if type(jsonStr) ~= 'string' or jsonStr == '' then return fallback end
                                                                  local ok, result = pcall(json.decode, jsonStr)
                                                                  if not ok then return fallback end
                                                                  return result
                                                                end

---

Was du erreicht hast

1. Stabile Spielerdatensätze, die durch citizenid gekennzeichnet sind.
2. Eine saubere oxmysql-Schicht mit prepared statements und awaits.
3. ESX-Code auf QBCore portiert mit ox_lib-Callbacks und Utilities.
4. Einen versionierten Plan, den du für zukünftige Server wiederholen kannst.

---

Nützliche Links auf deiner Seite

1. Framework-Konvertierungs-Hub. https://vertexmods.com/blog/converting-fivem-scripts
2. MySQL Async zu oxmysql Guide. https://vertexmods.com/blog/mysql-async-to-oxmysql
3. SQL-Identifikatoren-Migration. https://vertexmods.com/blog/sql-identifiers-migration
4. Adapter-Patterns für Skript-Ports. https://vertexmods.com/blog/adapter-patterns
5. QBCore-Install-Schnellstart. https://vertexmods.com/blog/how-to-install-qbcore
6. Skript-Konvertierungs-Checkliste. https://vertexmods.com/blog/converting-fivem-scripts
7. QBOX mit ox-Stack-Übersicht. https://vertexmods.com/blog/qbox-ox-stack
8. Resmon und Performance. https://vertexmods.com/blog/how-to-use-resmon-in-fivem-optimize-resources

Externe Referenzen

1. QBCore Framework
2. oxmysql-Dokumentation.
3. ox_lib-Dokumentation.
4. CFX.re-Identifikatoren-Referenz.