Installer Qbox pas à pas

Qbox (qbx_core) est un fork moderne de QBCore, bâti sur l'écosystème ox : ox_lib, oxmysql, ox_inventory, ox_target. Sans txAdmin, il n'y a pas de « recette » qui installe tout à ta place. Ce chapitre refait la recette officielle à la main, avec les outils que tu as sur TeamKit : le panel AMP, le SFTP et l'interface web de ta base.

Avant de commencer, tu dois avoir fini le chapitre 01 : ton serveur démarre avec les ressources de base, ta clé Cfx.re est renseignée, tu sais te connecter en SFTP. Garde aussi le chapitre 06 sous la main pour tout ce qui touche à la base de données.

Ce que tu vas installer #

La recette officielle (qbox.yaml dans https://github.com/Qbox-project/txAdminRecipe) télécharge une soixantaine de ressources. Tu n'as pas besoin de tout. Voici le socle minimal pour une ville jouable, rangé par dossier :

Deux fichiers viennent en plus du dépôt txAdminRecipe : items.lua (la liste des objets pour ox_inventory) et qbox.sql (les tables partagées par plusieurs ressources). Les images d'objets viennent du dépôt qbx_invimages.

Les autres qbx_* (braquages, drogues, courses…) s'ajoutent plus tard, un par un, quand le socle tourne.

✅ À retenir : Qbox = qbx_core + les quatre ressources ox. Sans ox_inventory, qbx_core ne démarre pas : c'est une dépendance déclarée, pas une option.

Vérifier trois réglages avant tout #

1. Ouvre Configuration → FiveM → OneSync Mode et mets On. Le manifeste de qbx_core déclare /onesync en dépendance : sans OneSync, la ressource refuse de démarrer.
2. Ouvre Configuration → FiveM → Enforce Game Build et choisis 3258 (le build utilisé par la recette officielle). Ne répète pas sv_enforceGameBuild dans Starting Resources : ce réglage AMP s'en charge.
3. Ouvre ton tableau de bord teamkit.fr et regarde le moteur de ta base. Qbox exige MariaDB (minimum 10.9, source : https://docs.qbox.re/installation). Si ton tableau de bord indique MySQL 8.4, demande au staff une base MariaDB avant d'importer quoi que ce soit. Le chapitre 06 explique pourquoi.

Télécharger les ressources #

Tout vient de GitHub, avec deux cas. Les ressources ox ont une page « Releases » avec une archive prête à l'emploi : prends celle nommée comme la ressource (ox_lib.zip, oxmysql.zip…), jamais « Source code », qui n'a pas l'interface compilée. **Les ressources qbx_*** se prennent par Code → Download ZIP ; le dossier extrait s'appelle qbx_core-main et devra être renommé.

1. Télécharge, depuis https://github.com/overextended : ox_lib.zip, oxmysql.zip, ox_inventory.zip, ox_target.zip (onglet Releases de chaque dépôt).
2. Télécharge, depuis https://github.com/Qbox-project : le ZIP de chaque qbx_* du tableau ci-dessus, plus qbx_invimages.
3. Télécharge le ZIP de https://github.com/Qbox-project/txAdminRecipe : tu y prendras items.lua et qbox.sql ; server.cfg, ox.cfg et permissions.cfg te serviront de modèles.
4. Télécharge pma-voice (https://github.com/AvarianKnight/pma-voice, ZIP du dépôt) et illenium-appearance (page Releases du projet, à vérifier sur sa page).
5. Extrais tout dans un dossier de travail sur ton PC, et retire le suffixe -main ou -master de chaque dossier.

Vérifie que chaque dossier contient un fxmanifest.lua à sa racine. Si tu vois qbx_core/qbx_core-main/fxmanifest.lua, tu as un niveau de trop : remonte le contenu.

✅ À retenir : archive « Releases » pour ox, « Download ZIP » pour qbx. Un dossier = un fxmanifest.lua à la racine, et un nom sans -main.

Déposer les fichiers par SFTP #

Le SFTP est décrit au chapitre 01 : hôte, port de ton instance, identifiants = ton compte AMP.

1. Ouvre server-data/resources/ dans FileZilla ou WinSCP. Tu y vois déjà [system], [managers], [gameplay], [gamemodes], [local], [test] : n'y touche pas.
2. Crée les dossiers [ox], [qbx], [voice], [standalone]. Les crochets font partie du nom : FXServer traite un dossier entre crochets comme une catégorie et regarde dedans.
3. Dépose oxmysql, ox_lib, ox_inventory, ox_target dans [ox].
4. Dépose tous les qbx_* dans [qbx].
5. Dépose pma-voice dans [voice] et illenium-appearance dans [standalone].
6. Remplace [ox]/ox_inventory/data/items.lua par le items.lua du dépôt txAdminRecipe.
7. Copie le contenu du dossier images de qbx_invimages dans [ox]/ox_inventory/web/images/.

Ton arborescence doit ressembler à ceci :

server-data/resources/
├── [system]/ [managers]/ [gameplay]/ …   (déjà là, ne pas toucher)
├── [ox]/
│   ├── oxmysql/
│   ├── ox_lib/
│   ├── ox_inventory/
│   └── ox_target/
├── [qbx]/
│   ├── qbx_core/
│   ├── qbx_vehicles/
│   ├── qbx_spawn/
│   └── … (les autres qbx_*)
├── [voice]/pma-voice/
└── [standalone]/illenium-appearance/

Règle absolue : aucun fichier .bak ou .old dans un dossier de ressource. Beaucoup de manifestes chargent server/** et client/** : la copie serait exécutée comme un script. Tes sauvegardes vont ailleurs (chapitre 09).

✅ À retenir : un dossier par famille, les crochets dans le nom, et rien d'autre que la ressource dans son dossier.

Importer les tables SQL #

Plusieurs ressources livrent un fichier .sql que tu importes par l'interface web de ta base (lien sur le tableau de bord). Le chapitre 06 détaille l'import ; ici, l'ordre.

1. Importe [qbx]/qbx_core/qbx_core.sql (tables players, bans, player_groups).
2. Importe [qbx]/qbx_vehicles/vehicles.sql (table player_vehicles, liée à players).
3. Importe qbox.sql du dépôt txAdminRecipe (tables de illenium-appearance, courrier, comptes bancaires…).
4. Importe [qbx]/qbx_vehicleshop/vehshop.sql si tu installes la concession.
5. Note les autres qbx_* qui contiennent un .sql (par exemple qbx_vehiclesales, qbx_weed, qbx_lapraces, qbx_drugs) : importe-les le jour où tu ajoutes la ressource.

L'ordre compte : player_vehicles pointe vers players par une clé étrangère. Si tu importes vehicles.sql avant qbx_core.sql, l'import échoue.

✅ À retenir : qbx_core.sql d'abord, puis vehicles.sql, puis qbox.sql. Un .sql par ressource, importé quand tu installes la ressource.

Renseigner la chaîne oxmysql #

1. Ouvre ton tableau de bord teamkit.fr, bloc base de données : hôte local, port, utilisateur, nom de base. Le mot de passe est celui de ton compte AMP.
2. Ouvre Configuration → FiveM → Additional Server Settings dans AMP.
3. Ajoute cette ligne, avec tes valeurs :

set mysql_connection_string "mysql://UTILISATEUR:MOT_DE_PASSE@HOTE:PORT/BASE?charset=utf8mb4"

Le port n'est pas 3306 : c'est celui affiché par le tableau de bord. Si ton mot de passe contient un des caractères ; , / ? : @ & = + $ #, oxmysql ne saura pas le lire dans cette forme (source : https://overextended.dev/oxmysql). Utilise alors la forme à points-virgules, décrite au chapitre 06.

Écrire le bloc Starting Resources #

C'est l'étape qui fait tout marcher ou tout casser. Ouvre Configuration → FiveM → Starting Resources. Trois règles :

• Les ConVars (set, setr) en tête, avant le premier ensure. AMP écrit « Additional Server Settings » après les ressources, trop tard pour ox_inventory, ox_lib et illenium-appearance, qui lisent leur convar au démarrage.
• L'ordre des ensure compte : oxmysql, ox_lib, qbx_core, ox_target, ox_inventory, puis le reste. C'est l'ordre imposé par la doc d'ox_inventory.
• Retire ensure basic-gamemode si la liste actuelle le contient : c'est le spawn de démonstration de FiveM, en conflit avec qbx_spawn. La recette officielle l'arrête.

Remplace le contenu de Starting Resources par ce bloc, puis adapte les valeurs :

# ---------- ConVars : TOUJOURS en tête ----------
# qbx_core (liste complète : https://docs.qbox.re/resources/qbx_core/convars)
set qbx:acknowledge true
setr qbx:enableBridge "true"
set qbx:enableQueue "true"
set qbx:discordLink "discord.gg/TON-INVITATION"
set qbx:max_jobs_per_player 1
set qbx:max_gangs_per_player 1
setr qbx:enableVehiclePersistence "false"
set resources_useSystemChat true

# ox_lib (https://overextended.dev/ox_lib)
setr ox:locale fr
setr ox:primaryColor blue
setr ox:primaryShade 8
setr ox:userLocales 0

# ox_inventory (https://overextended.dev/ox_inventory)
setr inventory:framework "qbx"
setr inventory:slots 50
setr inventory:weight 30000
setr inventory:target true
setr inventory:police ["police"]
setr inventory:keys ["TAB", "K", "F1"]
set inventory:versioncheck true
set inventory:clearstashes "6 MONTH"

# ox_target (https://overextended.dev/ox_target)
setr ox_target:defaultHotkey LMENU
setr ox_target:drawSprite 1
setr ox_target:defaults 1

# Traductions des ressources qui lisent une convar de langue
setr qb_locale "fr"
setr illenium-appearance:locale "fr"

# pma-voice : reprendre les lignes de voice.cfg du dépôt txAdminRecipe

# ---------- Ressources de base FiveM (déjà présentes) ----------
ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure hardcap
ensure baseevents

# ---------- Écosystème ox et cœur (ordre imposé) ----------
ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_target
ensure ox_inventory

# ---------- Voix ----------
ensure pma-voice

# ---------- Socle qbx ----------
ensure qbx_vehicles
ensure qbx_spawn
ensure qbx_smallresources
ensure qbx_hud
ensure qbx_radialmenu
ensure qbx_adminmenu
ensure qbx_scoreboard
ensure qbx_vehiclekeys
ensure qbx_management
ensure qbx_idcard

# ---------- Personnage ----------
ensure illenium-appearance

# ---------- Métiers et véhicules ----------
ensure qbx_police
ensure qbx_ambulancejob
ensure qbx_medical
ensure qbx_garages
ensure qbx_vehicleshop
ensure qbx_customs

Les valeurs qui comptent :

• set qbx:acknowledge true : coupe le message « Welcome to Qbox! » affiché à chaque démarrage. Rien de plus.
• setr qbx:enableBridge "true" : active le pont de compatibilité avec les scripts qb-* (voir plus bas).
• setr ox:locale fr : langue des ressources qui utilisent le module locale d'ox_lib, si elles livrent un locales/fr.json. Sinon, anglais.
• setr inventory:framework "qbx" : sans cette ligne, ox_inventory ne sait pas à quel framework parler.
• setr inventory:weight 30000 : capacité en grammes. La recette officielle met 85000 ; à toi de choisir.
• setr inventory:police ["police"] : les métiers qui voient l'équipement de police. Garde ceux qui existent dans qbx_core/shared/jobs.lua.

✅ À retenir : convars en tête, oxmysql → ox_lib → qbx_core → ox_target → ox_inventory, et jamais basic-gamemode avec Qbox.

Créer le premier admin #

Les permissions Qbox reposent sur les ACE de FiveM. Tu les écris dans Configuration → FiveM → Access Control Commands.

1. Reprends les lignes de permissions.cfg du dépôt txAdminRecipe :

add_ace group.admin command allow
add_ace resource.qbx_core command allow
add_ace resource.ox_lib command.add_ace allow
add_ace resource.ox_lib command.remove_ace allow
add_ace resource.ox_lib command.add_principal allow
add_ace resource.ox_lib command.remove_principal allow
add_ace group.admin admin allow
add_ace group.mod mod allow
add_ace group.support support allow
add_principal group.admin group.mod
add_principal group.mod group.support

2. Récupère ta licence Cfx.re : connecte-toi une première fois au serveur et lis la console AMP, la ligne de connexion affiche license: suivi d'une longue chaîne hexadécimale.
3. Ajoute une ligne avec ta licence :

add_principal identifier.license:REMPLACE_PAR_TA_LICENCE group.admin

4. Redémarre l'instance (bouton Restart sur Status) : Access Control Commands est écrit dans server.cfg au démarrage, un refresh ne suffit pas.

Les commandes d'administration de qbx_core (/tp, /car, /setjob, /givemoney…) demandent group.admin (source : https://docs.qbox.re/resources/qbx_core/commands).

✅ À retenir : un admin = une ligne add_principal identifier.license:… group.admin, puis redémarrage.

Redémarrer et lire la console #

1. Clique sur Restart dans Status.
2. Ouvre Console et attends la fin du chargement (une à deux minutes la première fois).
3. Cherche ces lignes, dans cet ordre :

[oxmysql] Database server connection established!
[ox_inventory] Inventory has loaded 500 items

Le nombre d'objets dépend de ton items.lua. Ces deux lignes signifient que la base répond et que l'inventaire a lu ses données.

4. Cherche ensuite les lignes en rouge. Les plus fréquentes :

5. Lance ton jeu, F8, puis connect IP:30120. Tu dois arriver sur l'écran de création de personnage de qbx_core, puis dans illenium-appearance.
6. Teste /car adder en jeu : si la voiture apparaît, ton compte admin fonctionne.

✅ À retenir : deux lignes vertes à trouver (connexion base, inventaire chargé), puis les rouges à lire une par une, de haut en bas.

Les qbx_* essentiels, et ce qu'ils demandent #

Les véhicules sont listés dans qbx_core/shared/vehicles.lua. Un modèle listé mais absent du jeu déclenche l'avertissement Could not find gameName value : retire la ligne ou ajoute le véhicule en addon.

Compatibilité avec les scripts qb-* #

Qbox garde une compatibilité large avec les scripts écrits pour QBCore, grâce à un pont (bridge/qb dans qbx_core). Concrètement :

• Le manifeste de qbx_core déclare provide 'qb-core'. Un script qui demande qb-core en dépendance est satisfait par qbx_core.
• exports['qb-core']:GetCoreObject() fonctionne à travers le pont (source : https://docs.qbox.re/faq).
• Le pont s'active avec setr qbx:enableBridge "true" (valeur par défaut).
• set qbx:acknowledge true ne touche pas au pont : il coupe seulement le message de bienvenue en console. Ne compte pas dessus pour « activer » quoi que ce soit.

Ce qui ne passe pas le pont : les scripts qui lisent directement la base en SQL brut, ou qui utilisent des fonctions non documentées de QBCore. Autre différence : les grades de métier sont des nombres (2), plus des chaînes ('2') ; un script qui compare des chaînes peut produire « attempt to compare string with number ».

Piège classique : un script qb-* qui appelle exports['qb-inventory'] ne trouvera rien, car ton inventaire s'appelle ox_inventory. L'erreur « No such export X in resource Y » vient de là : l'export est appelé par le vrai nom de la ressource, pas par son provide. Cherche une version compatible ox_inventory.

✅ À retenir : le pont couvre la majorité des scripts qb-*. Ce qui casse, c'est l'accès SQL direct, les exports d'inventaire, et les grades en chaîne.

✅ Checklist du chapitre #

• OneSync Mode = On, Enforce Game Build = 3258, base en MariaDB.
• oxmysql, ox_lib, ox_inventory, ox_target pris sur la page Releases, pas « Source code ».
• Chaque dossier renommé sans -main, avec fxmanifest.lua à la racine.
• items.lua et les images copiés dans ox_inventory.
• qbx_core.sql, vehicles.sql, qbox.sql importés dans cet ordre.
• Chaîne mysql_connection_string dans Additional Server Settings, avec le port de ton instance.
• ConVars en tête de Starting Resources, basic-gamemode retiré.
• add_principal identifier.license:… group.admin dans Access Control Commands.
• Console : « Database server connection established! » et « Inventory has loaded N items ».
• Connexion en jeu, création de personnage, /car fonctionne.

❓ Si ça ne marche pas #

« Couldn't find resource qbx_core » : le dossier s'appelle encore qbx_core-main, ou il est hors de server-data/resources/. Renomme, puis tape refresh et ensure qbx_core dans la console.

qbx_core démarre puis s'arrête avec « Startup errors detected » : lis les lignes juste au-dessus. Le plus souvent : OneSync à Off, ou une table manquante parce qu'un .sql n'a pas été importé.

L'inventaire s'ouvre vide, ou pas du tout : setr inventory:framework "qbx" est absent ou placé après les ensure. Remonte les convars en tête de Starting Resources et redémarre l'instance.

Tout est en anglais : setr ox:locale fr est placé trop bas, ou la ressource n'a pas de locales/fr.json.

« Unable to establish a connection to the database » : chapitre 06, section « Les erreurs et leur cause exacte ».

Tu spawnes dans le mode de démonstration FiveM : basic-gamemode est encore dans Starting Resources. Retire-le et redémarre.

Pour tout le reste, chapitre 08 : Dépannage.