FiveM-Skripte zwischen ESX, QBCore und Qbox konvertieren

Konvertiere eine FiveM-Ressource, indem du ihre Framework-, Inventar- und Datenbankabhängigkeiten zuordnest und dann einen Gameplay-Flow nach dem anderen testest. Das Umbenennen von ESX-Ereignissen in QBCore-Ereignisse ist keine vollständige Konvertierung. Eine serverweite Charaktermigration ist ein separates Projekt.

Bevor du Code änderst

Arbeite auf einem isolierten Entwicklungsserver mit einer Kopie der Ressource und einer temporären Datenbank. Notiere die genauen Quell- und Ziel-Framework-Versionen, das Inventar, die Targeting-Bibliothek, die UI-Bibliothek und die Ressourcenlizenz. Geschützte Dateien erfordern eine unterstützte Version vom Autor; eine alleinige editierbare Konfiguration ist möglicherweise nicht ausreichend.

1. Bestandsaufnahme der Integrationspunkte

Durchsuche die Ressourcendateien nach ESX, QBCore, qbx_core, exports, RegisterNetEvent, MySQL und SQL-Tabellennamen. Klassifiziere jede Übereinstimmung als Server, Client oder geteilt. Liste die erwarteten Eingaben, Rückgabewerte und Fehlerverhalten auf, bevor du sie ersetzt.

Zum Beispiel umfasst ein Shop-Flow das Öffnen der Benutzeroberfläche, das Überprüfen des Zugriffs, das Lesen von Preisen, das Bezahlen, das Hinzufügen zum Inventar und das Speichern des Ergebnisses. Die Konvertierung nur der Benachrichtigung lässt das wichtige Verhalten unverändert.

2. Verhalten explizit abbilden

Ermittle zum Zeitpunkt der Aktion serverseitig das Spielerobjekt des Ziel-Frameworks. ESX-Kennungen und QBCore-/Qbox-Charakter-IDs haben unterschiedliche Bedeutungen; erzeuge keine Charakter-IDs aus gekürzten Hashes und überschreibe keine Kontokennungen. Bewahre eine geprüfte Zuordnung auf, wenn bestehende Daten migriert werden müssen.

Wähle die Inventarintegration bewusst. Artikelnamen, Gewichtseinheiten, Slot-Handhabung, Metadaten und Kapazitätsprüfungen unterscheiden sich. Greife nicht stillschweigend zwischen Inventarsystemen zurück. Entscheide, wie Bargeld, Bankguthaben und jede Mechanik für illegale Währungen abgebildet werden, ohne nicht verwandte Konten als gleichwertig zu behandeln.

3. Implementiere einen kleinen Adapter

Halte die frameworkspezifischen Spieler-, Job-, Geld- und Inventaraufrufe in einem reinen Servermodul. Client-Benachrichtigungen und UI-Callbacks gehören in ein separates Client-Modul. Deklariere tatsächliche Abhängigkeiten in fxmanifest.lua und starte sie vor der Ressource.

Für Qbox konsultiere die Server-Exporte und seine Kompatibilitätsanleitung. Eine Kompatibilitätsbrücke kann bestehenden QB-Ressourcen helfen, garantiert aber keine Kompatibilität mit jedem Inventar, jeder Datenbankabfrage oder jedem modifizierten Kern.

4. Bewahre die Vertrauensgrenze

Der Server muss zulässige Gegenstände, Preise, Guthaben, Jobberechtigungen und den Abschluss belohnter Aufgaben bestimmen. Behandle jedes Client-Ereignisargument als nicht vertrauenswürdig. Ein Jobname allein beweist nicht, dass eine Lieferung stattgefunden hat; ein wiederholtes Ereignis darf nicht wiederholt bezahlen. Überprüfe sowohl die Abbuchungs- als auch die Artikel-Lieferergebnisse und definiere eine Entschädigung, wenn die zweite Aktion fehlschlägt.

5. Konvertiere ressourceneigenen Speicher

Vergleiche das installierte Quell- und Zielschema, bevor du eine Migration schreibst. Verwende ein separates, versioniertes Skript für genau dieses Schema. Erhalte ursprüngliche Kennungen, Kennzeichen, Metadaten und eine dauerhaft gespeicherte Zuordnung. Melde doppelte oder nicht zugeordnete Zeilen, statt sie zu ignorieren. Ändere keine vom Framework verwalteten Guthaben per SQL, während das Framework sie im Arbeitsspeicher hält.

6. Überprüfen und freigeben

1. Teste einen neuen und einen bestehenden Charakter: Login, die konvertierte Aktion, erneute Verbindung und Serverneustart. Überprüfe die Persistenz nach jedem Schritt.
2. Teste verweigerte Berechtigungen, unzureichende Mittel, volles Inventar, ungültige Eingaben, wiederholte Anfragen und Verbindungsabbrüche während des Vorgangs. Bestätige, dass keine unbeabsichtigten Gelder oder Gegenstände erstellt werden.
3. Vergleiche Datenbankzeilen und Salden vor und nach bekannten Testaktionen. Untersuche jede unerwartete Differenz.
4. Stelle die überprüften Dateien und alle erforderlichen Migrationen während eines Wartungsfensters bereit. Halte passende Datei-/Datenbank-Backups und ein Rollback-Verfahren bereit, das Schreibvorgänge nach der Veröffentlichung berücksichtigt.

Wenn die Konvertierung fehlschlägt

Ein fehlender Export deutet normalerweise auf die falsche Ressource/Version oder Startreihenfolge hin. Ein Callback, der nie zurückkehrt, erfordert eine Überprüfung sowohl der Registrierung als auch des Aufrufs, einschließlich Argumenten und Ausführungsseite. Fehlende Elemente können Inventarmetadaten oder Kapazitätsregeln widerspiegeln. Diagnostiziere die fehlerhafte Grenze, anstatt breite Kompatibilitätsschichten hinzuzufügen.

Referenzdokumentation

Cfx.re — Ressourcenmanifest · Cfx.re — Serversicherheit

Gleichzeitige Nutzung von ESX und QBCore: Warum das nicht machbar ist