Guide du framework Qbox : Installation, pont QBCore et migration

Qbox est un framework de jeu de rôle pour FiveM qui a commencé comme une bifurcation QBCore et fournit désormais ses propres API et ressources principales. Il maintient un pont de compatibilité pour de nombreuses ressources QBCore correctement écrites, mais l'accès direct à la base de données, l'accès aux fichiers internes et les comportements non pris en charge sont des exceptions documentées. Utilisez la recette officielle Qbox txAdmin pour une nouvelle installation et auditez chaque ressource avant une migration.

Points clés

• Qbox est un framework, pas simplement un ensemble d'utilitaires Ox ou un dossier QBCore renommé.
• La procédure d’installation officielle actuelle utilise la recette populaire QBox dans txAdmin.
• Le pont QB peut aider avec les ressources compatibles, mais il n'est pas une garantie pour chaque script QBCore.
• La migration inclut la configuration, les grades, l'inventaire et la conversion de la base de données, ainsi que des tests ressource par ressource.
• Il n'y a pas de classement universel de performance basé sur la source entre Qbox, QBCore et ESX.

Ce qu'est Qbox

L'introduction officielle de Qbox relate la création du projet le 27 septembre 2022 et décrit son origine dans QBCore. Le projet a depuis développé son propre cœur et ses ressources associées. Sa couche de compatibilité existe pour faciliter l'utilisation de nombreuses ressources QB pendant que les équipes adoptent les API Qbox actuelles, mais Qbox doit être évalué comme son propre framework et sa propre recette.

Le manuel actuel qbx_core manifest déclare directement ox_lib et oxmysql les dépendances. La recette officielle rassemble Qbox et les ressources tierces sélectionnées en une pile de départ complète. Parce que le contenu de la recette peut changer, liez-vous à la recette actuelle plutôt que de figer une longue liste de dépendances dans un tutoriel d'installation evergreen.

Installez Qbox via la recette officielle

1. Préparez un environnement FXServer pris en charge et ouvrez sa configuration txAdmin fournie.
2. Répondez aux exigences de la base de données listées dans la documentation d'installation actuelle de Qbox.
3. Sélectionnez la recette officielle QBox populaire plutôt que d'assembler un cœur partiel manuellement.
4. Complétez les variables de la recette, la configuration de la base de données et la configuration du serveur en utilisant la documentation actuelle.
5. Passez en revue la liste des ressources générées et l'ordre de démarrage avant le premier démarrage public.
6. Vérifiez le chargement des joueurs, la création de personnages, les autorisations, la persistance et les journaux sur un serveur de test.

Ne remplacez pas les manifestes des fournisseurs par des exemples raccourcis copiés à partir d'un guide. Installez les versions officielles ou les versions de la recette et traitez leurs manifestes comme faisant partie du contrat de dépendance. Lorsqu’une mise à jour modifie une exigence de cœur ou de bibliothèque, comparez la documentation de la version aux exigences de chaque ressource dépendante avant le déploiement.

Qbox et le pont QBCore

Le guide de conversion officiel de Qbox explique comment le pont QB soutient la compatibilité tandis que les API sont remplacées progressivement. La FAQ de Qbox indique que la plupart des scripts QBCore correctement écrits peuvent fonctionner à travers ce pont, puis identifie les exceptions importantes : les ressources qui accèdent directement aux tables de base de données, lisent ou modifient les fichiers principaux internes, ou s'appuient sur des comportements non pris en charge peuvent nécessiter des modifications.

Comportement des ressources	Attente de migration
Utilise les API QB documentées couvertes par le pont	Candidat pour les tests de pont ; la compatibilité doit encore être vérifiée.
Lit directement les tables du framework	Auditez les requêtes et les hypothèses de schéma avant de toucher aux données en direct.
Charge les fichiers internes du cœur	Adaptez le code aux exports ou modules pris en charge lorsque la documentation le prévoit.
Suppose que les grades de métier ou de gang sont du texte	Examinez les exigences de conversion des grades numériques de Qbox.
Gère les données d’inventaire ou de personnage	Utilisez le chemin de conversion documenté et validez chaque relation.

Un produit marqué compatible QBCore doit donc être testé contre Qbox en tant que cible séparée. Demandez s'il utilise uniquement les API couvertes par le pont documenté, quels systèmes d'inventaire et cibles il attend, et si son SQL suppose un schéma QB que Qbox n'expose pas de la même manière.

Checklist de migration pour un serveur QBCore existant

1. Gelez les modifications et faites l’inventaire : recensez le cœur, la base de données, l’inventaire, les métiers, les gangs, les véhicules, les logements, les téléphones, les permissions et les ressources personnalisées.
2. Sauvegardez : créez des instantanés restaurables de la base de données et des ressources avant la conversion.
3. Examinez la configuration : Qbox documente les modifications des fichiers de configuration et de l’accès aux API ; ne recopiez pas aveuglément les anciens éléments internes du cœur.
4. Convertissez les grades et les données : suivez la procédure officielle actuelle pour convertir les grades numériques des métiers et des gangs, l’inventaire et la base de données.
5. Auditez les ressources : classez chaque intégration comme couverte par le pont, adaptable ou incompatible.
6. Testez par étapes : validez les personnages, l'argent, les métiers, les gangs, l'inventaire, les véhicules, les permissions et le comportement de reconnexion.
7. Inspectez les preuves : examinez les journaux du serveur, du client et de la base de données et comparez le nombre d’enregistrements essentiels avant le basculement.
8. Gardez la possibilité de revenir en arrière : ne modifiez pas la seule base de données de production avec un extrait de conversion générique.

Choisissez Qbox pour des raisons explicites

Qbox convient à un nouveau serveur qui souhaite délibérément la recette et les API Qbox actuelles. Il peut également convenir à une équipe QBCore préparée à auditer la compatibilité du pont et à compléter le travail de conversion documenté. C'est une mauvaise cible de migration lorsque des ressources critiques dépendent d’éléments internes non documentés du cœur et que l'équipe ne peut pas les remplacer ou les adapter en toute sécurité.

Ne choisissez pas Qbox parce qu'une page promet qu'un inventaire, une bibliothèque de bases de données ou un framework est automatiquement plus rapide. Les performances dépendent de l'ensemble complet des ressources, de la charge de travail de la base de données, du comportement des joueurs, des artefacts et de la configuration du serveur. Si les performances sont un facteur de décision, effectuez des benchmarks d'actions représentatives sur des environnements équivalents et conservez les journaux.

Validation de production

Testez les actions réussies et refusées, pas seulement le scénario nominal. Confirmez que les changements d'argent se produisent une seule fois, que les permissions des métiers et des gangs rejettent les joueurs non autorisés, que l'inventaire reste cohérent entre les reconnexions, que les véhicules possédés persistent, et que les actions administratives sont enregistrées. Les requêtes des clients doivent être validées sur le serveur ; un événement déclenché par le client n'est pas sûr simplement parce que l'interface utilisateur le cache des joueurs normaux.

Consultez le comparatif des frameworks pour choisir entre ESX, QBCore et Qbox. Pour une sélection dans le catalogue des scripts FiveM payants, commencez par Scripts QBOX et vérifiez les exigences actuelles du framework, du pont, de l'inventaire et des dépendances sur la page du produit avant l'achat.

Placez Qbox dans la décision du framework

Comparez la recette Qbox actuelle avec la guide d'architecture QBCore et le guide de décision complet ESX, QBCore et Qbox avant de convertir les données de production.

Documentation de référence

Source : docs.qbox.re · Source : docs.qbox.re · Source : docs.qbox.re