Convertissez une ressource FiveM en mappant son framework, son inventaire et ses dépendances de base de données, puis en testant un flux de jeu à la fois. Renommer les événements ESX en événements QBCore n'est pas une conversion complète. Une migration de personnage à l'échelle du serveur est un projet distinct.
Avant de modifier le code
Travaillez sur un serveur de développement isolé avec une copie de la ressource et une base de données jetable. Enregistrez les versions exactes du framework source et cible, l'inventaire, la bibliothèque de ciblage, la bibliothèque d'interface utilisateur et la licence de la ressource. Les fichiers protégés nécessitent une version prise en charge par l'auteur ; une configuration modifiable seule peut ne pas suffire.
1. Inventoriez les points d'intégration
Recherchez dans les fichiers de ressources ESX, QBCore, qbx_core, exports, RegisterNetEvent, MySQL et les noms de tables SQL. Classez chaque correspondance comme serveur, client ou partagée. Listez les entrées attendues, les valeurs de retour et le comportement en cas d'échec avant de les remplacer.
Par exemple, un flux de boutique inclut l'ouverture de son interface utilisateur, la vérification de l'accès, la lecture des prix, le paiement, l'ajout à l'inventaire et la sauvegarde du résultat. Ne convertir que sa notification laisse le comportement important inchangé.
2. Mappez explicitement le comportement
Résolvez le joueur du framework cible sur le serveur au moment de l'action. Les identifiants ESX et les ID de personnage QBCore/Qbox ont des significations différentes ; ne générez pas d'ID de personnage à partir de hachages tronqués et n’écrasez pas les identifiants de compte. Conservez un mappage révisé lorsque les données existantes doivent être déplacées.
Choisissez délibérément l'intégration de l'inventaire. Les noms d'articles, les unités de poids, la gestion des emplacements, les métadonnées et les vérifications de capacité diffèrent. Ne revenez pas silencieusement entre les systèmes d'inventaire. Décidez comment l'argent liquide, les soldes bancaires et tout mécanisme de monnaie illicite sont mappés sans traiter les comptes non liés comme équivalents.
3. Implémentez un petit adaptateur
Conservez les appels spécifiques au framework pour le joueur, le métier, l'argent et l'inventaire dans un module réservé au serveur. Les notifications client et les rappels d'interface utilisateur appartiennent à un module client distinct. Déclarez les dépendances réelles dans fxmanifest.lua et démarrez-les avant la ressource.
Pour Qbox, consultez les exports du serveur et ses directives de compatibilité. Un pont de compatibilité peut aider les ressources QB existantes, mais il ne garantit pas la compatibilité avec chaque inventaire, requête de base de données ou cœur modifié.
4. Préservez la limite de confiance
Le serveur doit déterminer les objets autorisés, les prix, les soldes, les permissions de métier et l'achèvement des tâches récompensées. Traitez chaque argument d'événement client comme non fiable. Un nom de métier seul ne prouve pas qu'une livraison a eu lieu ; un événement répété ne doit pas payer de manière répétée. Vérifiez les résultats du débit et de la livraison des objets, et définissez une compensation si la deuxième action échoue.
5. Convertissez le stockage appartenant à la ressource
Comparez le schéma source et cible installé avant d'écrire une migration. Utilisez un script séparé et versionné pour ce schéma exact. Conservez les identifiants, les plaques, les métadonnées d'origine et un tableau de correspondance durable. Signalez les lignes dupliquées ou non mappées au lieu de les ignorer. Ne modifiez pas les soldes appartenant au framework via SQL pendant que le framework les a chargés en mémoire.
6. Vérifiez et publiez
- Testez un nouveau personnage et un personnage existant : connexion, action convertie, reconnexion et redémarrage du serveur. Vérifiez la persistance après chaque étape.
- Testez les permissions refusées, les fonds insuffisants, l'inventaire plein, les entrées invalides, les requêtes répétées et les déconnexions pendant l'opération. Confirmez qu'aucun argent ou objet non intentionnel n'est créé.
- Comparez les lignes de la base de données et les soldes avant et après les actions de test connues. Enquêtez sur chaque différence inattendue.
- Déployez les fichiers révisés et toute migration requise pendant une fenêtre de maintenance. Conservez les sauvegardes de fichiers/bases de données correspondantes et une procédure de restauration qui tient compte des écritures effectuées après la publication.
Si la conversion échoue
Un export absent indique généralement une ressource/version ou un ordre de démarrage incorrect. Un rappel qui ne renvoie jamais de valeur nécessite une inspection de l'enregistrement et de l'invocation, y compris les arguments et le côté exécution. Les éléments manquants peuvent refléter les métadonnées d'inventaire ou les règles de capacité. Diagnostiquez la limite défaillante plutôt que d'ajouter de larges shims de compatibilité.
Documentation de référence
Cfx.re — manifeste de ressource · Cfx.re — sécurité du serveur
Utilisation simultanée d'ESX et de QBCore : pourquoi ce n'est pas faisable