Comment ajouter des voitures addon à votre serveur FiveM ?

GTA V propose d'origine des centaines de véhicules, mais un serveur roleplay ou racing ne se démarque vraiment qu'avec des voitures custom. Dans ce guide, vous installez un véhicule addon sur votre serveur FiveM : vous uploadez la ressource via SFTP, vous l'activez dans server.cfg, vous la testez en jeu, puis vous rendez la voiture achetable dans le vehicle shop d'ESX ou de QBCore.

Addon ou replace : quelle est la différence ?

Les véhicules custom existent sous deux formes. Un véhicule replace écrase un modèle GTA existant : ses fichiers portent le nom d'une voiture d'origine (par exemple adder.yft) et tous ceux qui font spawn ce modèle verront désormais la nouvelle voiture. Un véhicule addon est ajouté au jeu comme un modèle entièrement nouveau, avec son propre spawn name, sans rien écraser. L'addon est presque toujours le meilleur choix : vous conservez toutes les voitures d'origine, vous évitez les conflits entre ressources et vous pouvez donner au véhicule son propre prix et sa propre catégorie dans le shop. Ce guide se concentre donc sur les voitures addon.

La structure de dossiers d'une ressource véhicule

Une voiture addon est une ressource FiveM classique. Dans le dossier, vous trouverez généralement ceci :

• fxmanifest.lua — décrit la ressource et pointe vers les fichiers meta.
• stream/ — les fichiers du modèle : .yft (le modèle 3D, souvent accompagné d'une variante _hi.yft) et .ytd (les textures).
• data/ — les fichiers meta : vehicles.meta (nom du modèle et données de spawn), carvariations.meta (couleurs et variantes), carcols.meta (options de tuning et éclairages) et handling.meta (comportement de conduite). Certaines voitures incluent des fichiers supplémentaires comme vehiclelayouts.meta.

Le spawn name se trouve dans vehicles.meta, dans la balise <modelName> — ce guide utilise sultan3 comme exemple. Vous aurez besoin de ce nom tout à l'heure pour le spawn et pour le shop.

Étape 1 : uploadez la ressource via SFTP

1. Connectez-vous à votre serveur via SFTP, par exemple avec FileZilla ou WinSCP. Notre article sur le SFTP vous explique comment faire.
2. Ouvrez le dossier resources de votre serveur FiveM. Un sous-dossier entre crochets, comme resources/[cars], est pratique — FiveM parcourt automatiquement les dossiers entre crochets.
3. Uploadez le dossier complet du véhicule (par exemple sultanclassic) dans ce sous-dossier.
4. Vérifiez que fxmanifest.lua se trouve directement dans le dossier du véhicule et non dans un dossier imbriqué supplémentaire — l'erreur la plus fréquente avec les téléchargements décompressés.

Étape 2 : activez la ressource dans server.cfg

1. Dans le panel MC-Node, ouvrez l'onglet Files et ouvrez le fichier server.cfg.
2. Ajoutez une ligne tout en bas : ensure sultanclassic. Utilisez ici le nom du dossier de la ressource, pas le spawn name.
3. Enregistrez le fichier et redémarrez votre serveur via l'onglet Console.

Étape 3 : testez la voiture en jeu

1. Rejoignez votre serveur, ouvrez votre menu admin — vMenu ou le menu txAdmin, par exemple — et choisissez l'option pour faire apparaître un véhicule.
2. Saisissez le spawn name (sultan3). Sur un serveur ESX avec les commandes par défaut, /car sultan3 fonctionne aussi.
3. Si la voiture apparaît, la ressource tourne. Profitez-en pour vérifier le comportement de conduite et le chargement de toutes les textures.

Rendre la voiture achetable dans ESX

Le esx_vehicleshop par défaut lit son catalogue dans la table de base de données vehicles.

1. Dans le panel, ouvrez l'onglet Databases et connectez-vous au panneau de base de données (phpMyAdmin) avec les identifiants affichés.
2. Sélectionnez la base de données de votre serveur et ouvrez la fenêtre SQL.
3. Exécutez cette requête : INSERT INTO vehicles (name, model, price, category) VALUES ('Sultan RS Classic', 'sultan3', 125000, 'sports');
4. Attention : model doit correspondre exactement au spawn name et la category doit exister dans la table vehicle_categories.
5. Redémarrez la ressource du vehicle shop ou le serveur entier ; la voiture est maintenant disponible chez le concessionnaire.

Rendre la voiture achetable dans QBCore

QBCore n'utilise pas de table de base de données mais un fichier de configuration partagé.

1. Via l'onglet Files, ouvrez le fichier resources/[qb]/qb-core/shared/vehicles.lua.
2. Ajoutez une nouvelle entrée, par exemple : { model = 'sultan3', name = 'Sultan RS Classic', brand = 'Karin', price = 125000, category = 'sports', type = 'automobile', shop = 'pdm' },
3. La valeur shop = 'pdm' place la voiture dans le vehicle shop par défaut ; category détermine sous quel onglet elle apparaît dans le menu du shop.
4. Redémarrez complètement le serveur via l'onglet Console — les fichiers partagés ne sont chargés qu'au démarrage.

Problèmes fréquents

• Lag de streaming ou voitures invisibles — Des fichiers .ytd trop lourds (textures 4K de plusieurs dizaines de mégaoctets) saturent la mémoire de textures des joueurs : lag, pop-in ou véhicules invisibles à la clé. Réduisez les textures en 2K ou utilisez une version optimisée de la voiture.
• Spawn names en double — Deux ressources avec le même modelName entrent en conflit : la voiture ne spawn pas ou le mauvais modèle apparaît. Supprimez l'une des deux ressources, ou renommez le modèle, les noms de fichiers et toutes les références meta de manière cohérente.
• La voiture n'apparaît pas dans le shop — La catégorie du shop a généralement été oubliée ou est incorrecte. Dans ESX, la catégorie doit exister dans vehicle_categories ; dans QBCore, elle doit correspondre aux catégories de la config du shop. Vérifiez aussi que le spawn name dans le shop est exact.
• La ressource ne démarre pas — Consultez le message d'erreur dans l'onglet Console. Le nom du dossier dans la ligne ensure est-il correct, et fxmanifest.lua se trouve-t-il directement dans le dossier du véhicule ?
• Model not found au spawn — La ressource n'est pas lancée ou vous tapez un mauvais spawn name. Vérifiez le nom dans vehicles.meta et redémarrez le serveur après chaque modification.

Pour aller plus loin

Vous débutez avec les bases de données ? Lisez comment créer une base de données et comment vous connecter à votre base de données. Si votre serveur reste lent après l'ajout de voitures, consultez aussi notre guide sur le lag serveur. Toujours bloqué ? Ouvrez un ticket via notre page de support en indiquant le nom de la ressource et le message d'erreur de la console.