Migrer d'ESX ou de QBCore vers QBox

01Pourquoi migrer vers QBox

QBox est le successeur de QBCore, lancé en 2022 pour en reprendre le développement. Il garde une passerelle de compatibilité avec la plupart des ressources écrites pour QBCore, et s'appuie sur des bibliothèques ouvertes devenues la norme : ox_lib pour les menus et les rappels serveur, ox_inventory pour l'inventaire, oxmysql pour la base de données.

Il intègre aussi ce qui demandait des scripts à part sur les anciennes bases : le choix entre plusieurs personnages, plusieurs métiers ou gangs par joueur si vous l'autorisez, une file d'attente quand le serveur est plein, et des véhicules qui restent où on les a laissés. Pour comparer les trois frameworks point par point, lisez ESX, QBCore ou QBox : lequel choisir.

02Ce qui se reprend, ce qui se réécrit, ce qui se refait

Avant de toucher un fichier, classez chaque élément de votre serveur actuel. Le tableau résume ce que devient chacun en passant sur Nova ; les étapes qui suivent détaillent chaque ligne.

03Étape 1 : faire l'inventaire de votre serveur

Une migration ratée commence presque toujours par un dossier resources copié en bloc. Prenez le temps de lister ce qui tourne vraiment, et de garder de quoi revenir en arrière.

1. Exportez la base de données actuelle en .sql et gardez-en une copie hors du serveur : c'est votre point de retour.
2. Listez chaque ressource que démarre votre server.cfg, et notez son framework : elle dépend de qb-core, d’es_extended, ou d’aucun des deux.
3. Rangez-les en quatre familles : le framework et ses ressources de base, les scripts de jeu, les cartes et véhicules ajoutés, les scripts écrits pour vous.
4. Notez vos réglages de ville : métiers, grades et salaires, prix, objets, portes, gangs. Ils ne se copient pas, ils se recréent, et une liste écrite fait gagner des heures.
5. Pour chaque script acheté sous licence, demandez à son auteur s'il existe une version pour QBox ou QBCore avant de réécrire quoi que ce soit.

04Étape 2 : écarter les doublons

Le framework entier et ses ressources de base ne se migrent pas : la nouvelle base les fournit déjà. Sur Nova, c'est le cas de l'inventaire, du téléphone, du ciblage, de la banque, de l'apparence, du chat, du choix du point d'apparition, des clés de véhicule et des serrures. Deux versions de la même ressource se marchent dessus, et l'erreur se voit rarement au premier démarrage.

05Étape 3 : passer vos scripts QBCore à QBox

Pour migrer de QBCore vers QBox, la passerelle répond à la plupart des appels d'un script : l'objet obtenu par exports['qb-core']:GetCoreObject(), les fonctions du joueur comme Player.Functions.AddMoney ou SetJob, et les rappels créés par QBCore.Functions.CreateCallback. Sur Nova, elle est active par défaut et se règle dans l'écran Configuration de votre serveur (Bridge QB). Restent quatre points à vérifier, script par script :

• Le ciblage : un script qui appelle qb-target est à repasser sur ox_target, que Nova fournit (l’ancien qtarget est aussi reconnu).
• Les objets ajoutés à chaud par QBCore.Functions.AddItem : ox_inventory ne les connaît pas. Sur Nova, un objet se déclare dans le catalogue, en jeu.
• Les appels directs à qb-inventory : à remplacer par les exports d’ox_inventory (AddItem, RemoveItem, Search).
• Une ligne @ox_lib/init.lua dans le fxmanifest : sur Nova, ox_lib est fourni par nova_lib, et aucun dossier ox_lib n'existe sur le disque. Remplacez la ligne par @nova_lib/shared/lib_init.lua, sinon la console affiche « Failed to load script ».

Déposez ensuite vos scripts dans le dossier resources/[client] depuis l'écran Fichiers, un par un ou en archive. Une ressource nouvelle arrive éteinte : activez-la dans la carte Ressources, redémarrez le serveur, puis lisez la console. Le pas à pas est dans la documentation sur vos scripts.

06Étape 4 : porter vos scripts ESX

Migrer d'ESX vers QBox demande plus de travail, puisque rien ne traduit les appels d'ESX. Chaque script de jeu se réécrit, ou se remplace par un équivalent écrit pour QBox ou QBCore. Pour un script court, la réécriture tient souvent en une poignée de remplacements :

La logique du script reste la vôtre : seules changent la façon d'obtenir le joueur, ses comptes et son inventaire. Les rappels et les menus passent par ox_lib, déjà présent. Gardez une règle en tête pendant la réécriture : toute action sensible, argent, objets ou métier, se décide côté serveur, jamais sur la foi de ce qu'envoie le client.

07Étape 5 : reprendre vos données

Les personnages, leurs inventaires et leurs véhicules ne sont pas convertis automatiquement : la base de Nova n'a pas la même forme que celle d'ESX ou de QBCore. L'import de l'espace client refuse d'ailleurs toute instruction qui nomme une table du framework, comme players, users, player_vehicles ou ox_inventory.

Prévoyez donc un nouveau départ côté personnages. Annoncez-le tôt à votre communauté, et faites-en un moment : une réouverture où tout le monde repart à égalité se vit mieux qu'une perte découverte au premier jour.

Les données de vos propres scripts, elles, se reprennent. Exportez leurs tables en .sql, puis importez le fichier depuis l'écran Bases de données : il est relu en entier avant de s'exécuter, et une seule instruction refusée suffit pour que rien ne parte. La documentation sur les bases de données dit combien de bases votre offre permet.

08Étape 6 : recréer la ville en jeu

Sur un QBox classique, métiers, objets et véhicules se déclarent dans des fichiers Lua. Sur Nova, ils se recréent dans le jeu en tapant /admin, à partir de la liste faite à l'étape 1. Reliez d'abord le serveur au bot Discord : tant qu'il ne l'est pas, le panneau n'ouvre que l'écran de liaison.

• Métiers et gangs : grades, salaires et accès patron se créent depuis le panneau.
• Objets : un objet se déclare dans le catalogue et arrive dans les inventaires ; son image s'envoie depuis l'écran Médias de l'espace client.
• Véhicules : le catalogue de la concession se remplit en jeu, et peut importer d’un coup les véhicules connus de QBox.
• Portes, propriétés, boutiques et prix : chacun a son écran, sans fichier à ouvrir.
• Staff : les rangs viennent des rôles de votre serveur Discord. Ils ne s’écrivent plus en add_principal dans server.cfg.

Un script déposé qui lit des permissions ACE au démarrage, pour une commande réservée par exemple, les reçoit depuis l'écran Configuration, sous Permissions des scripts. Vous n'avez pas accès au server.cfg, et vous n'en avez pas besoin.

09Étape 7 : tester, puis ouvrir

1. Faites une sauvegarde depuis l'écran Sauvegardes avant chaque lot de scripts : la restauration remet fichiers et bases dans l'état d'avant.
2. Activez vos scripts par petits lots, redémarrez, et lisez la console après chaque lot : une dépendance absente ou un fxmanifest manquant y est nommé.
3. Jouez une boucle complète à deux ou trois : créer un personnage, prendre un métier, être payé, acheter, se faire arrêter, se faire soigner.
4. Ouvrez la ville quand la console reste propre après un redémarrage.
5. Si un point bloque, ouvrez une demande depuis la page du serveur : elle joint son état, et le support saura que vous migrez.

10Migrer vers Nova : ce que ça coûte

Nova est un abonnement par serveur, hébergement, mises à jour et support compris : NOVA à 99 € par mois pour 64 joueurs, NOVA+ à 149 € pour 128 joueurs, NOVA INFINITY à 229 € pour 256 joueurs. L'annuel se paie dix mois pour douze, et le serveur s'installe à la souscription, sans frais d'installation.

Pour vos propres scripts, les trois offres réservent 2 Go, 8 Go ou 20 Go, et une, deux ou trois bases de données. Comme pour tout serveur FiveM, il vous faut votre propre clé Cfx, créée sur le portail Cfx.re. La page des tarifs dit quelles offres sont ouvertes aujourd'hui, et le guide combien coûte un serveur FiveM fait le compte sur douze mois.

Questions fréquentes