Installer Quasar Inventory sur un serveur FiveM : guide ESX et QBCore

Quasar Inventory (qs-inventory) est le système d'inventaire le plus complet disponible pour les serveurs FiveM. Il remplace les inventaires par défaut d'ESX Legacy et de QBCore par une interface drag-and-drop avec aperçu 3D du personnage, gestion par poids et par slots, système d'objets avec rareté et durabilité, coffres de stockage, coffres de véhicules, boîtes à gants, boutiques et ateliers de craft. La configuration se fait entièrement en jeu via deux panneaux d'administration, sans éditer de fichier manuellement sur le serveur.

Ce guide s'adresse aux administrateurs qui hébergent un serveur FiveM sur un VPS Linux ou un serveur dédié et souhaitent installer qs-inventory proprement. Chaque étape est détaillée : préparation de l'environnement serveur, dépendances obligatoires, transfert de fichiers par FTP ou SFTP, import SQL dans la base de données, ordre de démarrage dans server.cfg, configuration du framework ESX Legacy ou QBCore, paramétrage des items, et dépannage des erreurs courantes.

Prérequis

Avant de commencer l'installation, vérifiez que votre serveur remplit les conditions suivantes. Quasar Inventory est une resource riche en fonctionnalités mais légère en consommation : elle ajoute peu de charge au serveur, mais exige un environnement correctement configuré.

Si vous n'avez pas encore installé votre framework, consultez le guide installer ESX Legacy sur FiveM ou la comparaison ESX Legacy vs QBCore pour choisir. Pour lier votre base de données MySQL ou MariaDB au serveur, suivez le guide lier MySQL à un serveur FiveM.

Préparer l'environnement du serveur

Connectez-vous à votre VPS ou serveur dédié en SSH depuis un terminal. Sous Ubuntu ou Debian, vérifiez que MariaDB est installée et accessible, que le pare-feu autorise les connexions FiveM et que l'espace disque est suffisant pour les fichiers du serveur et les sauvegardes.

# Vérifier la version de MariaDB
mariadb --version

# Vérifier l'espace disque disponible
df -h /home

# Ouvrir le port FiveM dans le pare-feu (UFW)
sudo ufw allow 30120/tcp
sudo ufw allow 30120/udp

# Vérifier l'adresse IP publique du serveur
curl -4 ifconfig.me

Si MariaDB n'est pas encore installée, le package est disponible dans les dépôts officiels Ubuntu et Debian :

sudo apt update
sudo apt install -y mariadb-server
sudo mysql_secure_installation

Créez ensuite une base de données et un utilisateur dédié pour votre serveur FiveM. N'utilisez jamais le compte root en production :

sudo mariadb -u root -p
CREATE DATABASE fivem_db;
CREATE USER 'fivem'@'localhost' IDENTIFIED BY 'votre_mot_de_passe';
GRANT ALL PRIVILEGES ON fivem_db.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Ces commandes préparent l'environnement nécessaire à qs-inventory. La base de données doit être accessible via oxmysql avant le démarrage de l'inventaire.

Dépendances obligatoires

Quasar Inventory repose sur plusieurs resources tierces qui doivent être installées et démarrées avant lui. Si l'une d'elles manque, qs-inventory refusera de démarrer ou produira des erreurs dans la console du serveur.

Téléchargez les dernières versions d'oxmysql et d'ox_lib depuis leurs dépôts GitHub officiels (Overextended). Déposez les dossiers extraits dans le répertoire resources/ de votre serveur FiveM. MugShotBase64 et qs-inventory-objects sont fournis directement dans l'archive de Quasar Inventory.

Supprimer l'ancien système d'inventaire

Deux systèmes d'inventaire ne peuvent pas coexister sur un même serveur FiveM. Avant d'installer qs-inventory, supprimez ou désactivez toutes les resources d'inventaire existantes. Commentez ou retirez les lignes ensure correspondantes dans votre server.cfg :

• ox_inventory, qb-inventory, esx_inventoryhud (systèmes d'inventaire)
• qb-weapons, esx_weaponshop (boutiques d'armes, gérées par qs-inventory)
• qb-shops, esx_shops (boutiques, remplacées par le système de shops intégré)

Ne supprimez pas les fichiers immédiatement : renommez les dossiers (par exemple qb-inventory.bak) pour pouvoir revenir en arrière en cas de problème. Conservez cette sauvegarde jusqu'à ce que qs-inventory soit pleinement opérationnel sur votre serveur.

Transfert et structure des fichiers

Téléchargez l'archive de Quasar Inventory depuis votre compte sur le site de l'éditeur. Transférez-la sur votre VPS ou serveur dédié via un client FTP/SFTP (FileZilla, WinSCP) ou via le gestionnaire de fichiers de votre panel d'administration (txAdmin, Pterodactyl). Extrayez l'archive dans le répertoire resources/ de votre serveur FiveM.

La structure attendue dans votre dossier resources/ après extraction :

resources/
  [qs]/
    qs-inventory/
      config/config.lua
      shared/items.lua
      shared/weapons.lua
      locales/
      web/
    qs-inventory-objects/
  [sql]/
    esx.sql
    qb.sql
  oxmysql/
  ox_lib/
  MugShotBase64/
  es_extended/   (ou qb-core/ ou qbx_core/)

Le dossier doit rester nommé qs-inventory. Renommer la resource provoque une erreur explicite dans la console : "You have renamed the script!" et le serveur refusera de charger l'inventaire.

Ordre de démarrage dans server.cfg

L'ordre des lignes ensure dans server.cfg est critique. FiveM démarre les resources dans l'ordre déclaré : si une dépendance n'est pas encore chargée quand qs-inventory démarre, le script échoue silencieusement ou affiche des erreurs dans la console F8. Le framework et le connecteur de base de données doivent toujours démarrer en premier.

Voici l'ordre correct :

ensure oxmysql
ensure ox_lib
ensure es_extended          # ou : ensure qb-core / ensure qbx_core
ensure MugShotBase64
ensure qs-inventory-objects
ensure qs-inventory

Si vous utilisez des extensions optionnelles comme illenium-appearance, ox_target ou qs-interface, placez-les avant ensure qs-inventory. Le framework, le script d'apparence et le système de ciblage sont détectés une seule fois, au démarrage de l'inventaire.

Placez toute resource qui dépend de qs-inventory (plugins de boutique, scripts de coffre, addons DLC comme qs-armor ou qs-weapondraw) après la ligne ensure qs-inventory.

Import SQL dans la base de données

L'archive contient un dossier [sql] avec deux fichiers. Choisissez celui qui correspond à votre framework :

Les deux fichiers créent également les tables spécifiques à qs-inventory : inventory_stash, inventory_trunk, inventory_glovebox, inventory_clothes, inventory_metadata et inventory_quests. D'autres tables sont générées automatiquement au premier démarrage (qs_inventory_settings, qs_inventory_creator, qs_inventory_skills).

Avant l'import, sauvegardez votre base de données. Importez ensuite le fichier via phpMyAdmin, HeidiSQL, DBeaver ou en ligne de commande sur votre VPS :

sudo mariadb -u root -p fivem_db < /chemin/vers/qs-inventory/[sql]/esx.sql

Si vous utilisez MySQL 8 au lieu de MariaDB, les fichiers SQL provoqueront une erreur sur la syntaxe ADD COLUMN IF NOT EXISTS, qui est spécifique à MariaDB. Dans ce cas, exécutez manuellement les lignes ALTER TABLE sans la clause IF NOT EXISTS, ou migrez vers MariaDB (recommandé par l'éditeur). N'importez le fichier SQL qu'une seule fois sur une installation neuve.

Configuration spécifique au framework

ESX Legacy

Quasar fournit une version pré-éditée d'es_extended (1.16.3) dans l'archive. La modification clé est l'ajout de cette ligne dans es_extended/shared/config/main.lua :

Config.CustomInventory = 'qs'

Cette directive redirige les fonctions d'inventaire ESX (AddItem, RemoveItem, GetItemBySlot) vers qs-inventory. Sans elle, ESX continue d'utiliser son inventaire natif et qs-inventory ne fonctionne pas.

Si vous utilisez déjà une version modifiée d'es_extended, ajoutez uniquement cette ligne dans votre configuration existante plutôt que de remplacer tout le dossier.

QBCore

Quasar fournit une version pré-éditée de qb-core (1.3.0). L'inventaire remplace les méthodes de gestion d'items du framework au démarrage. Les items doivent être déclarés dans qb-core/shared/items.lua.

Si vous installez sur un serveur QBCore existant, copiez les items de vêtements fournis par Quasar (tshirt, torso, arms, etc.) dans votre fichier qb-core/shared/items.lua pour activer les 14 emplacements de vêtements de l'inventaire.

Qbox

Qbox fonctionne en mode QBCore. Déployez la version pré-éditée de qbx_core (1.24.0) fournie dans l'archive et qs-inventory utilisera ses propres listes d'items et d'armes.

Déclarer les items et les armes

L'emplacement des fichiers de déclaration dépend du framework installé sur votre serveur :

Chaque item est défini par un nom unique, un libellé, un poids, une rareté et des métadonnées optionnelles (durabilité, description, image). Le système d'armes gère 64 accessoires (attachments), les numéros de série uniques et la durabilité avec barre d'état visible dans l'inventaire.

Vous pouvez aussi créer des items directement en jeu via le panneau /inventorycreator sans redémarrer le serveur. Les items créés en jeu sont sauvegardés dans la base de données et chargés automatiquement au prochain démarrage.

Configurer les poids et les slots

Quasar Inventory utilise un système hybride poids/slots. Chaque joueur dispose d'un nombre de slots (emplacements) et d'un poids maximal. Un objet occupe un slot et un certain poids. Le joueur ne peut plus ramasser d'objets quand l'un des deux plafonds est atteint.

La configuration s'effectue en jeu via la commande /inventoryconfig, section "Capacity Settings". Les paramètres modifiables incluent :

• Le poids maximal du joueur (en grammes ou en unités personnalisées)
• Le nombre de slots de l'inventaire principal
• Les 5 slots rapides (touches 1 à 5) et le slot protégé (non volable lors d'un braquage)
• Le portefeuille intégré et l'empilement d'objets identiques (stacking)
• Les limites de poids et de slots par type de coffre de véhicule (configurable par modèle ou par classe)
• Les limites des coffres de stockage (stashes) par métier ou par gang

La plupart de ces réglages s'appliquent immédiatement sans redémarrer le serveur. Les paramètres sont sauvegardés dans la base de données et écrasent les valeurs par défaut du fichier config/config.lua.

Intégration : coffres, véhicules, boutiques et craft

Quasar Inventory intègre nativement quatre systèmes qui nécessitent habituellement des plugins séparés sur un serveur FiveM.

Coffres (stashes)

Les coffres sont des inventaires partagés ou individuels, rattachés à un emplacement, un métier ou un gang. Créez-les en jeu avec /inventorycreator : positionnez le marqueur, définissez la capacité (poids et slots), les droits d'accès (métier, grade minimum, gang) et validez. Aucun fichier à éditer, aucun redémarrage nécessaire. Les données du coffre sont stockées dans la table inventory_stash de la base de données.

Coffres de véhicules et boîtes à gants

Chaque véhicule dispose d'un coffre (trunk) et d'une boîte à gants (glovebox) dont la capacité varie selon le modèle ou la classe du véhicule. La configuration par défaut attribue des capacités réalistes (un SUV a plus de place qu'une sportive), modifiables via /inventoryconfig. Les inventaires des véhicules sont sauvegardés dans la table inventory_trunk.

Boutiques

Le système de boutiques intégré permet de créer des magasins avec stock limité, prix configurable, onglets de catégories et un système de points de rachat. Créez une boutique en jeu via /inventorycreator : choisissez l'emplacement, ajoutez les items vendus, définissez les prix et les quantités. Les joueurs peuvent aussi revendre des objets via le système de points.

Ateliers de craft

Quasar Inventory intègre un système de craft avec recettes, temps de fabrication configurable, taux de réussite et système de réputation. Créez un atelier de craft en jeu via /inventorycreator : définissez l'emplacement, ajoutez les recettes (ingrédients, résultat, durée, chance de succès) et attribuez des restrictions d'accès par métier si nécessaire.

Panneaux d'administration en jeu

Quasar Inventory fournit deux commandes d'administration accessibles en jeu. Pour les activer, ajoutez les permissions ACE dans votre server.cfg :

add_ace group.admin command.inventoryconfig allow
add_ace group.admin command.inventorycreator allow

/inventoryconfig donne accès à 17 sections de configuration : capacité, interactions, braquage, police, véhicules, armes, vêtements, distributeurs automatiques, anti-duplication, poubelles et plus. Les réglages sont sauvegardés dans la base de données et persistent entre les redémarrages du serveur.

/inventorycreator permet de créer des boutiques, des coffres, des ateliers de craft, des items, des armes, des compétences et des missions directement en jeu. Aucune modification de fichier ni redémarrage du serveur n'est nécessaire : les éléments créés sont immédiatement disponibles pour tous les joueurs connectés.

Les administrateurs ESX (flag admin/superadmin) et les joueurs avec le rôle admin QBCore/Qbox ont automatiquement accès à ces panneaux, même sans la permission ACE.

Migrer depuis un autre inventaire

Si vous remplacez un inventaire existant sur votre serveur FiveM, qs-inventory propose un importateur de données intégré compatible avec quatre systèmes :

• ox_inventory
• qb-inventory
• Inventaire ESX natif
• tgiann-inventory

L'importateur analyse la base de données avant de commencer, préserve les données existantes de qs-inventory, crée des copies de sauvegarde des inventaires des joueurs et ignore les joueurs connectés au moment de la migration. Désactivez l'ancien inventaire dans server.cfg avant de lancer l'import. Effectuez la migration hors heure de pointe pour éviter les conflits de données, et sauvegardez votre base de données au préalable.

Dépannage des erreurs courantes

Les erreurs les plus fréquentes lors de l'installation de Quasar Inventory proviennent d'un ordre de démarrage incorrect, d'une dépendance manquante ou d'une incompatibilité de base de données. Voici les cas les plus courants et leurs solutions.

En cas de problème persistant, consultez les logs complets du serveur dans la console txAdmin ou dans le terminal SSH. L'erreur la plus fréquente reste l'ordre de démarrage : vérifiez systématiquement que chaque dépendance est chargée avant qs-inventory. La commande testwebhooks dans la console du serveur permet de diagnostiquer les problèmes de logs Discord si vous utilisez les webhooks intégrés.

Impact sur les performances du serveur

Quasar Inventory est une resource FiveM optimisée qui consomme peu de ressources serveur. Son interface NUI (HTML/CSS/JS) tourne côté client dans le navigateur intégré de FiveM et ne charge pas le serveur dédié ou le VPS. Les requêtes SQL sont asynchrones via oxmysql, ce qui évite de bloquer les autres resources pendant les lectures et écritures en base de données.

Pour maintenir de bonnes performances sur votre serveur FiveM, consultez le guide optimiser les performances d'un serveur FiveM. Surveillez la consommation de chaque resource dans la console txAdmin : si une resource consomme plus de 5 ms côté serveur, elle mérite une investigation.

OneSync est recommandé (mais pas obligatoire) pour bénéficier de certaines fonctionnalités avancées : sacs au sol avec physique, contrôle d'accès aux véhicules par distance côté serveur et gestion des interactions entre joueurs proches. Si OneSync est activé, vérifiez le paramètre sv_entityLockdown dans votre server.cfg : le mode "strict" empêche les joueurs de donner des coups de pied dans les sacs au sol.

Conclusion

Quasar Inventory remplace l'inventaire par défaut de votre serveur FiveM par un système complet qui intègre coffres, véhicules, boutiques, craft, échange entre joueurs et progression par compétences. L'installation sur un VPS Linux ou un serveur dédié demande de la rigueur sur l'ordre de démarrage dans server.cfg et sur les dépendances (oxmysql, ox_lib, framework pré-édité), mais une fois en place, la configuration et la création de contenu se font entièrement en jeu via les panneaux d'administration.

Pour aller plus loin dans la personnalisation de votre serveur RP, explorez les autres scripts FiveM disponibles et pensez à sauvegarder régulièrement votre base de données avant chaque mise à jour de resource.