QBCore zu QBOX Migration: Vollständige Schritt-für-Schritt-Anleitung

QBOX ist die nächste Evolution von QBCore — bessere Performance, saubererer Code und native OX-Ökosystem-Integration. Wenn du einen QBCore-Server betreibst und das Upgrade in Betracht ziehst, führt dich dieser Guide durch alles: Was sich ändert, was gleich bleibt und wie du mit minimaler Ausfallzeit migrierst.

Warum von QBCore zu QBOX migrieren?

QBOX ist nicht nur ein Fork von QBCore — es ist eine Modernisierung von Grund auf. Die wichtigsten Verbesserungen:

• Performance: QBOX benchmarkt konsistent schneller als QBCore, besonders bei höheren Spielerzahlen (64+). Die Server-Tick-Rate bleibt stabil, wo QBCore zu sinken beginnt.
• Native OX-Integration: ox_lib, ox_inventory und ox_target funktionieren nativ ohne Bridge-Layer. Keine Kompatibilitäts-Shims, kein Übersetzungs-Overhead.
• Sauberere Codebasis: Bessere Typsicherheit, verbesserte Funktions-Signaturen, reduzierte technische Schulden. Einfacher zu debuggen und zu erweitern.
• Zukunftssicherheit: Aktive Entwicklung mit wachsender Community. Neue Scripts zielen zunehmend nativ auf QBOX ab.

Für einen vollständigen technischen Vergleich sieh ESX vs QBCore vs QBOX.

Was sich zwischen QBCore und QBOX ändert

Kern-Unterschiede

| Aspekt | QBCore | QBOX | |---|---|---| | Core-Ressource | qb-core | qbx_core | | Inventar | qb-inventory (Standard) | ox_inventory (nativ) | | Target-System | qb-target | ox_target (nativ) | | UI-Bibliothek | qb-menu / qb-input | ox_lib (nativ) | | Türschlösser | qb-doorlock | ox_doorlock | | Spieler-Daten | QBCore.Functions.GetPlayerData() | exports.qbx_core:GetPlayerData() | | Bridge-Support | Nein | QBCore API-Kompatibilitäts-Layer inklusive |

Was gleich bleibt

QBOX enthält einen QBCore-Bridge-Layer, was bedeutet:

• Die meisten QBCore-Exports funktionieren weiterhin (QBCore.Functions.*, Events usw.)
• Scripts, die Standard-QBCore-APIs verwenden, laufen in den meisten Fällen ohne Änderung
• Datenbankstruktur ist weitgehend kompatibel
• Job-System-Konzepte sind gleich (Ränge, Berechtigungen, im Dienst)
• Gang-System funktioniert ähnlich

Migrations-Strategie

Phase 1: Vorbereitung (1–2 Tage)

1. Vollständiges Backup: Datenbank, alle Ressourcen, server.cfg, alles. Keine Ausnahmen.
2. Scripts auditieren: Liste jede Ressource auf und prüfe QBOX-Kompatibilität. Kategorisiere als: native QBOX-Version verfügbar, funktioniert via Bridge, oder braucht Ersatz.
3. Test-Server einrichten: Niemals direkt auf Produktion migrieren. Klone deinen Server und teste die Migration zuerst dort.
4. QBOX-Dokumentation lesen: Verstehe die Kernänderungen bevor du anfängst.

Phase 2: Core-Migration (1 Tag)

1. qbx_core installieren: Ersetze qb-core durch qbx_core. Der Bridge-Layer aktiviert sich automatisch.
2. OX-Ökosystem installieren: ox_lib, ox_inventory, ox_target, ox_doorlock hinzufügen, falls nicht bereits vorhanden.
3. server.cfg aktualisieren: Ressourcen-Ensure-Reihenfolge ändern. qbx_core und OX-Ressourcen müssen zuerst laden.
4. Datenbank-Migration: QBOXs Migrations-Scripts ausführen, um das Spielerdaten-Format zu konvertieren.
5. Ersetzte Ressourcen entfernen: qb-target, qb-menu, qb-input, qb-doorlock entfernen (jetzt von OX-Äquivalenten übernommen).

Phase 3: Script-Kompatibilität (2–5 Tage)

Hier passiert die meiste Arbeit. Teste jede Ressource:

Scripts, die über Bridge meist sofort funktionieren:

• Scripts mit Standard-QBCore-Spieler-Funktionen
• Scripts mit qb-target-Exports (bridged zu ox_target)
• Scripts mit qb-menu (bridged zu ox_lib)
• Die meisten NUI-basierten Scripts
• Job-Scripts die QBCore.Functions.GetPlayerData() verwenden

Scripts, die möglicherweise Änderungen brauchen:

• Scripts mit hardcodierten qb-inventory-Aufrufen (ox_inventory-Äquivalente nötig)
• Scripts, die direkt auf QBCore-interne Tabellen oder Methoden zugreifen
• Scripts mit veralteten QBCore-APIs
• Sehr alte Scripts (vor 2024) mit veralteten Mustern

Scripts, die Ersatz brauchen:

• qb-inventory → ox_inventory (Datenmigration nötig)
• qb-target → ox_target (API-Unterschiede)
• qb-menu / qb-input → ox_lib (anderes UI-System)
• qb-doorlock → ox_doorlock

Phase 4: Testing (2–3 Tage)

1. Jeden Job testen (Polizei, Rettungsdienst, Mechaniker usw.)
2. Alle Inventar-Interaktionen testen (Shops, Lager, Kofferräume)
3. Housing testen (Betreten, Verlassen, Lager, Schlüssel)
4. Fahrzeug-Operationen testen (Garage, Shop, Kraftstoff)
5. Kriminelle Aktivitäten testen (Drogen, Überfälle)
6. Telefon und Kommunikation testen
7. Admin-Befehle und -Tools testen
8. Lasttest mit mehreren Spielern zur Performance-Verifizierung

Phase 5: Go Live

1. Wartungsfenster planen (2–4 Stunden)
2. Spieler mit spezifischem Ausfallzeit-Fenster ankündigen
3. Finales Backup von Produktion
4. Migrierte Konfiguration deployen
5. Datenbank-Migrationen auf Produktion ausführen
6. Kernsysteme verifizieren
7. Server mit Staff-Monitoring öffnen
8. Altes Backup 2 Wochen verfügbar halten für Rollback

Häufige Migrations-Probleme

Inventar-Datenformat

qb-inventory und ox_inventory speichern Items unterschiedlich. QBOX bietet Migrations-Scripts, aber verifiziere, dass alle Spieler-Inventare korrekt übertragen wurden. Stichprobenartig 10–20 Spieler-Inventare nach der Migration prüfen.

Event-Namen-Konflikte

Manche Scripts registrieren Events mit Namen, die zwischen QBCore und QBOX kollidieren. Bei "Event already registered"-Fehlern auf doppelte Event-Handler prüfen.

Berechtigungs-/ACE-Probleme

QBOX behandelt Berechtigungen für manche Features möglicherweise anders. Admin-, Polizei- und Job-Berechtigungen nach der Migration verifizieren.

Phone-Scripts

Phone-Scripts (lb-phone, qs-smartphone) brauchen oft spezifische QBOX-Kompatibilitäts-Patches. Beim Phone-Script-Entwickler nach QBOX-spezifischen Anweisungen fragen.

Nach der Migration: Was optimieren

Sobald QBOX stabil läuft:

1. Gebridgte Scripts ersetzen: Schrittweise QBCore-Scripts über Bridge durch native QBOX-Versionen ersetzen.
2. ox_lib-UI überall nutzen: ox_libs Kontext-Menüs, Notifications und Dialoge für konsistente UX standardisieren.
3. QBOX-spezifische Features aktivieren: Verbesserte Charaktererstellung, bessere Multicharacter-Unterstützung, verbesserte Spielerdaten-Verwaltung.
4. Performance überwachen: Resmon nutzen, um Ressourcennutzung vor und nach der Migration zu vergleichen.

FAQ

Wie lange dauert die Migration?

Für einen typischen Server mit 50–100 Ressourcen: 1–2 Wochen inklusive Testing. Einfache Server mit hauptsächlich Standard-Scripts können schneller migrieren.

Kann ich QBOX neben QBCore vorübergehend betreiben?

Nein. Sie sind gegenseitig ausschließende Frameworks. Der Bridge-Layer in QBOX übernimmt die Rückwärtskompatibilität.

Werden meine Spieler ihre Daten verlieren?

Nicht bei korrekter Migration. Spielerdaten (Geld, Jobs, Inventar, Fahrzeuge, Housing) sollten alle übertragen werden. Der Schlüssel ist ordnungsgemäße Datenbank-Migration und gründliches Testing vor dem Go-Live.

Lohnt sich der Aufwand?

Für die meisten Server ja. Die Performance-Verbesserungen allein rechtfertigen den Migrationsaufwand, und das wachsende QBOX-Ökosystem bedeutet bessere Script-Unterstützung in Zukunft.

Kann ich jemanden für die Migration beauftragen?

Ja. FiveM-Entwicklungs-Communities haben erfahrene Entwickler, die sich auf Framework-Migrationen spezialisiert haben.

Sobald migriert, lies unseren ox_lib vollständigen Guide und unseren Guide zu den besten QBOX Scripts für was nach der Migration zu installieren ist.