Ajouter des véhicules addon sur un serveur FiveM : streaming et configuration

Un véhicule addon est un modèle 3D personnalisé ajouté à un serveur FiveM en complément des véhicules de base de GTA V. Contrairement à un véhicule de remplacement (replace), un addon ne supprime aucun véhicule existant : il est enregistré sous un nouveau nom de spawn et cohabite avec tout le parc d'origine. C'est la méthode privilégiée par les administrateurs de serveurs roleplay pour proposer des voitures, motos, camions et véhicules d'urgence uniques à leurs joueurs.

Ce guide s'adresse aux administrateurs qui hébergent un serveur FiveM sur un VPS Linux, un serveur dédié ou une offre mutualisée FiveM. Il couvre chaque étape : les prérequis matériels et logiciels, la récupération des fichiers du véhicule, la création de la resource avec le bon fxmanifest.lua, la configuration des fichiers meta (vehicles.meta, handling.meta, carcols.meta, carvariations.meta), le transfert par SFTP vers le serveur, le spawn via vMenu, ESX ou QBCore, et l'optimisation des textures pour limiter l'impact sur les performances du serveur et des clients.

Prérequis pour ajouter un véhicule addon

Avant de commencer, vérifiez que votre environnement serveur remplit les conditions suivantes :

Si votre serveur FiveM tourne sur un VPS (serveur privé virtuel), vérifiez que votre hébergeur autorise le trafic sortant sur le port 30120 (port par défaut de FiveM) et que le pare-feu (firewall) du serveur ne bloque pas le streaming des assets vers les clients. Sur un serveur FiveM mutualisé ElypseCloud, ces réglages sont déjà configurés.

Où télécharger un véhicule addon FiveM

Les véhicules addon FiveM sont distribués sous forme d'archives compressées contenant les fichiers de modèle 3D, de textures et de métadonnées. Les sources les plus utilisées par les administrateurs de serveurs sont :

• GTA5-Mods.com : le plus grand dépôt de mods pour GTA V, avec des milliers de véhicules addon convertis pour FiveM. Chaque fiche indique si le véhicule est au format addon ou replace.
• Forum cfx.re (Releases) : la communauté officielle FiveM. Les véhicules publiés ici sont généralement testés sur FXServer et livrés avec un fxmanifest.lua fonctionnel.
• Boutiques spécialisées : certains créateurs de modèles 3D vendent des véhicules haute qualité avec des textures optimisées, des LOD complets et un handling personnalisé.

Avant d'installer un véhicule téléchargé, vérifiez que l'archive contient au minimum les fichiers .yft (modèle 3D), .ytd (textures) et vehicles.meta. Un addon livré sans fichier meta n'est pas utilisable en l'état. Pour évaluer la fiabilité d'une source, consultez notre guide scripts et resources FiveM : où les trouver, lesquels éviter.

Structure d'une resource véhicule addon

Chaque véhicule addon est une resource FiveM autonome. La convention consiste à placer toutes les resources véhicules dans un sous-dossier dédié du répertoire resources, par exemple resources/[vehicles]/. Cette organisation facilite la gestion des fichiers par SFTP ou via le gestionnaire de fichiers du panel. La structure minimale d'une resource véhicule est la suivante :

resources/[vehicles]/mon-vehicule/
    fxmanifest.lua
    stream/
        mon-vehicule.yft          (modèle 3D, résolution standard)
        mon-vehicule_hi.yft       (modèle haute définition, vue rapprochée)
        mon-vehicule.ytd          (dictionnaire de textures)
    data/
        vehicles.meta
        handling.meta
        carcols.meta
        carvariations.meta

Le dossier stream/ contient les fichiers de modèle 3D (.yft) et de textures (.ytd). FiveM détecte automatiquement les fichiers placés dans ce dossier et les envoie (streaming) aux clients qui rejoignent le serveur, sans avoir à les déclarer dans le manifest. Le dossier data/ contient les fichiers de métadonnées XML qui définissent le comportement du véhicule en jeu : physique, couleurs, variations et catalogue.

Certains véhicules addon incluent des fichiers supplémentaires : vehiclelayouts.meta (positionnement des passagers), un sous-dossier audio/ (sons moteur personnalisés) ou des fichiers .ydr (accessoires détachables). Ces extensions suivent la même logique : les assets visuels et sonores vont dans stream/, les fichiers de configuration dans data/.

Créer le fxmanifest.lua

Le fichier fxmanifest.lua est le point d'entrée de toute resource FiveM. Il déclare la version du manifest, le jeu cible et les fichiers de données à charger. Pour un véhicule addon, le manifest minimal contient :

fx_version 'cerulean'
game 'gta5'

files {
    'data/vehicles.meta',
    'data/handling.meta',
    'data/carcols.meta',
    'data/carvariations.meta',
}

data_file 'HANDLING_FILE'           'data/handling.meta'
data_file 'VEHICLE_METADATA_FILE'   'data/vehicles.meta'
data_file 'CARCOLS_FILE'            'data/carcols.meta'
data_file 'VEHICLE_VARIATION_FILE'  'data/carvariations.meta'

La version cerulean est la version courante et recommandée du manifest FiveM (FXv2, depuis mai 2020). La directive files déclare les fichiers de métadonnées à envoyer au client. Les directives data_file indiquent à FXServer comment interpréter chaque fichier : HANDLING_FILE pour la physique, VEHICLE_METADATA_FILE pour le catalogue, etc. Les fichiers du dossier stream/ sont montés automatiquement par le moteur de streaming et n'ont pas besoin d'être déclarés.

Si votre véhicule inclut des fichiers supplémentaires (sons, layouts), ajoutez-les dans la section files et déclarez le type data_file correspondant. Par exemple, pour un fichier de positionnement des passagers :

files { 'data/vehiclelayouts.meta' }
data_file 'VEHICLE_LAYOUTS_FILE' 'data/vehiclelayouts.meta'

Configurer vehicles.meta

Le fichier vehicles.meta enregistre le véhicule dans le catalogue interne de GTA V. Sans ce fichier, le véhicule n'existe tout simplement pas pour le moteur du jeu. Chaque véhicule téléchargeable en addon est normalement fourni avec son vehicles.meta pré-rempli. Les champs essentiels à vérifier sont les suivants :

Le champ handlingId doit correspondre exactement (majuscules comprises) au champ handlingName dans handling.meta. Une différence de casse empêche l'association : le véhicule utilise alors le handling par défaut (ADDER), ce qui se traduit par une conduite complètement désynchronisée avec le modèle, une vitesse maximale incorrecte et un freinage inadapté.

Si vous devez modifier le gameName (par exemple pour éviter un conflit avec un autre addon), pensez à mettre à jour aussi la requête SQL d'insertion dans la base de données ESX ou le fichier shared/vehicles.lua de QBCore.

Configurer handling.meta

Le fichier handling.meta définit le comportement physique du véhicule : masse, vitesse maximale, adhérence, freinage, suspension et traction. Les véhicules addon sont généralement livrés avec un handling pré-configuré par le créateur du modèle. Si vous souhaitez ajuster le comportement, les paramètres les plus courants sont :

Testez systématiquement le handling en jeu après modification. Les valeurs interagissent entre elles : augmenter la vitesse maximale sans ajuster le freinage et l'adhérence rend le véhicule inconduisible. Utilisez la console txAdmin ou la commande /car pour faire apparaître le véhicule rapidement pendant vos tests.

Carcols et carvariations

Le fichier carcols.meta définit les couleurs disponibles, les types de phares, les gyrophares (pour les véhicules d'urgence) et les kits de modification visuels (spoiler, jupes, capot, pare-chocs). Le fichier carvariations.meta déclare les combinaisons de couleurs, jantes et extras activées par défaut à l'apparition du véhicule.

Ces deux fichiers sont moins souvent modifiés que handling.meta, car ils sont générés par le créateur du modèle. Vérifiez néanmoins que les noms de modèle dans ces fichiers correspondent exactement au modelName de vehicles.meta. Une incohérence de nommage entre les fichiers meta empêche l'application des couleurs, des jantes et des modifications visuelles sans aucun message d'erreur dans la console.

Transférer et installer la resource sur le serveur

Une fois les fichiers organisés dans le bon répertoire local, l'installation sur le serveur se déroule en trois étapes :

1. Transfert des fichiers : envoyez le dossier complet de la resource dans resources/[vehicles]/ sur votre serveur. Sur un VPS ou un serveur dédié, utilisez un client SFTP (FileZilla, WinSCP) connecté en SSH à l'adresse IP du serveur. Sur un hébergement FiveM mutualisé, utilisez le gestionnaire de fichiers intégré au panel (txAdmin, Pterodactyl). L'accès FTP non chiffré est déconseillé : préférez toujours SFTP ou SCP.
2. Déclaration dans server.cfg : ajoutez la ligne ensure mon-vehicule dans votre fichier server.cfg. Cette directive indique à FXServer de charger la resource au démarrage. L'ordre des ensure n'a pas d'impact pour les véhicules addon (contrairement aux scripts qui ont des dépendances).
3. Chargement : redémarrez le serveur, ou utilisez la commande ensure mon-vehicule dans la console txAdmin pour charger la resource à chaud, sans redémarrage complet. Vérifiez dans les logs de la console que la resource se charge sans erreur.

Si vous avez plusieurs véhicules addon, ajoutez chaque resource individuellement dans server.cfg. Certains administrateurs créent un fichier de configuration séparé (vehicles.cfg) inclus via exec vehicles.cfg dans server.cfg, pour gérer plus facilement un large catalogue de véhicules. Pensez à sauvegarder votre serveur avant d'ajouter de nouvelles resources.

Rendre le véhicule accessible en jeu

Une fois la resource chargée par FXServer, le véhicule est disponible en jeu. Le nom à utiliser pour le faire apparaître est la valeur du champ gameName dans vehicles.meta, pas le nom du dossier de la resource.

Avec vMenu

vMenu inclut un menu de spawn de véhicules accessible par raccourci clavier. Si votre véhicule addon est correctement enregistré dans vehicles.meta, il apparaît dans la catégorie correspondante du menu (sport, SUV, urgence, etc.). Pour les serveurs qui n'utilisent pas de framework économique, vMenu reste la méthode la plus directe pour mettre un véhicule addon à disposition des joueurs.

Avec ESX Legacy ou QBCore

Sur un serveur utilisant un framework RP comme ESX Legacy ou QBCore, les véhicules addon doivent être enregistrés dans la base de données ou dans un fichier de configuration pour apparaître dans les garages et concessionnaires en jeu.

Pour ESX, le véhicule apparaît dans le script de concessionnaire configuré sur votre serveur dès que la ligne est insérée dans la base de données MySQL. Pour QBCore, vérifiez que le script de garage utilisé reconnaît la catégorie déclarée dans shared/vehicles.lua. Après modification, un redémarrage de la resource concessionnaire ou garage suffit : pas besoin de redémarrer tout le serveur FiveM.

Avec la console txAdmin

La console txAdmin permet de faire apparaître n'importe quel véhicule en tapant directement le nom de spawn. Cette méthode est utile pour les tests, mais ne rend pas le véhicule disponible dans les systèmes de jeu (garages, concessionnaires). Pour l'administration quotidienne de votre serveur, txAdmin reste l'outil central de gestion.

Streaming FiveM : comment les fichiers sont distribués aux joueurs

Comprendre le mécanisme de streaming est indispensable pour gérer un parc de véhicules addon sans dégrader les performances. Lorsqu'un joueur se connecte à un serveur FiveM, le client télécharge automatiquement tous les fichiers placés dans les dossiers stream/ des resources actives. Ce téléchargement s'effectue depuis le serveur FXServer lui-même (pas depuis un CDN externe) et transite par la bande passante réseau du serveur.

Le streaming fonctionne en deux phases :

1. Téléchargement initial : à la première connexion, le client récupère tous les fichiers de streaming. Les fichiers sont mis en cache localement sur le disque dur ou le SSD du joueur. Les connexions suivantes ne retéléchargent que les fichiers modifiés.
2. Chargement en mémoire : le moteur RAGE de GTA V charge les modèles 3D et les textures en mémoire vive (RAM) et en mémoire vidéo (VRAM) du GPU à mesure que les véhicules apparaissent dans le champ de vision du joueur.

Seuil de 16 Mo par fichier

FiveM affiche un avertissement dans la console lorsqu'un fichier individuel (.yft ou .ytd) dépasse 16 Mo (16 777 216 octets) de mémoire physique après chargement. Ce seuil n'est pas une limite stricte : le fichier est quand même transmis au client. Mais au-delà de 16 Mo, les risques de problèmes visuels augmentent :

Budget de streaming global

Au-delà de la taille individuelle de chaque fichier, le client dispose d'un budget total de streaming : la quantité de mémoire VRAM et de RAM allouée à l'ensemble des assets personnalisés chargés simultanément. Même si aucun fichier individuel ne dépasse 16 Mo, un serveur avec 500 véhicules addon dont les textures totalisent plusieurs gigaoctets de données saturera le budget de streaming. Résultat : des textures disparaissent, des modèles 3D ne se chargent pas, et les joueurs constatent des pop-in et des véhicules gris dans les zones denses.

Avec OneSync activé (la norme sur les serveurs FiveM modernes), le serveur gère la synchronisation des entités de façon centralisée. OneSync applique un culling par distance : les véhicules hors du champ de vision des joueurs connectés sont retirés de la simulation, ce qui libère des ressources. Ce mécanisme atténue l'impact d'un grand nombre de véhicules addon, mais ne dispense pas d'optimiser les textures.

Optimiser les textures et les performances

Les véhicules addon sont la première cause de ralentissement sur les serveurs FiveM riches en contenu personnalisé. Chaque véhicule ajoute des fichiers que le client doit télécharger via le réseau du serveur et charger en mémoire. Un serveur FiveM peut fonctionner correctement avec 200 à 400 véhicules addon, à condition que chaque resource soit optimisée en termes de poids et de résolution de textures.

Résolutions de textures recommandées

Les textures d'un véhicule addon sont stockées dans un fichier .ytd (dictionnaire de textures). Le choix de la résolution a un impact direct sur la taille du fichier et sur la consommation de mémoire VRAM du GPU côté client :

Évitez les textures en 4096 px : elles quadruplent la consommation mémoire par rapport au 2048 px pour un gain visuel négligeable sur un véhicule en mouvement. Vérifiez aussi que les textures sont compressées en DXT/BC et non en format brut (A8R8G8B8) : une texture non compressée peut peser 4 à 8 fois plus lourd que sa version DXT.

Modèles LOD (Level of Detail)

Un véhicule addon bien conçu inclut plusieurs niveaux de détail (LOD). Le fichier vehicule.yft contient le modèle affiché à distance normale. Le fichier vehicule_hi.yft contient le modèle le plus détaillé, visible en vue très rapprochée. Sans LOD, le moteur graphique affiche le modèle haute résolution quelle que soit la distance, ce qui consomme des ressources GPU et de la mémoire VRAM inutilement.

Les véhicules convertis depuis GTA V single-player ou depuis d'autres jeux manquent parfois de niveaux de détail intermédiaires. Vérifiez la présence des fichiers LOD avant d'installer un addon sur votre serveur de production, surtout si vous hébergez plus d'une centaine de véhicules.

Impact sur le processeur, la mémoire et le réseau

L'ajout massif de véhicules addon affecte principalement les clients (temps de téléchargement à la connexion, consommation de RAM et de VRAM) plutôt que le processeur du serveur lui-même. Les facteurs qui pèsent le plus, par ordre d'impact :

1. Taille des textures (.ytd) : les fichiers de textures représentent la majeure partie du poids de téléchargement. Ils consomment de la bande passante réseau du serveur et de l'espace de stockage sur le disque SSD.
2. LOD manquants : sans niveaux de détail, chaque véhicule visible à l'écran consomme autant de ressources GPU qu'un véhicule au premier plan.
3. Nombre de polygones : un modèle très détaillé (plus de 50 000 polygones) ralentit le rendu lorsque plusieurs véhicules sont visibles simultanément dans le champ de vision du joueur.
4. Nombre total de resources : chaque resource véhicule ajoute des entrées au registre de streaming. Le processeur du serveur doit gérer la distribution de ces fichiers à chaque client qui se connecte.

Pour aller plus loin sur l'optimisation globale de votre serveur, consultez notre guide optimiser les performances d'un serveur FiveM.

Choisir le bon hébergement pour un serveur riche en véhicules addon

Le choix de l'hébergement a un impact direct sur l'expérience des joueurs lorsque le serveur héberge un grand nombre de véhicules addon. Les trois ressources matérielles les plus sollicitées sont la RAM, le stockage et la bande passante réseau.

Le disque SSD (ou NVMe) est préférable au disque dur mécanique (HDD) pour le streaming de véhicules addon : les temps de lecture aléatoire sont beaucoup plus courts, ce qui accélère la distribution des fichiers .ytd et .yft aux clients. La RAM du serveur est consommée par le processus FXServer qui charge les métadonnées de toutes les resources actives.

Sur un VPS Linux (Ubuntu ou Debian), vous disposez d'un accès root complet pour configurer le serveur FiveM, ajuster les paramètres réseau et gérer les resources par SSH. Sur un serveur dédié, vous avez en plus la garantie que le processeur, la RAM et la bande passante ne sont partagés avec aucun autre client. Pour un serveur avec un large parc de véhicules addon et une base de données MySQL volumineuse (ESX ou QBCore avec des centaines de joueurs), le serveur dédié reste le choix le plus fiable.

Erreurs courantes et dépannage

En cas d'erreur persistante, consultez notre guide solutions aux erreurs courantes sur FiveM. Les sources de scripts et de resources fiables fournissent des véhicules mieux documentés et testés que les fichiers trouvés sur des forums non officiels.

Addon ou replace : quel type de véhicule choisir

Pour un serveur roleplay avec un parc de véhicules personnalisé, l'addon est le choix standard : il offre plus de flexibilité et ne supprime rien du jeu de base. Le replace reste utile pour remplacer un véhicule de police ou d'urgence par défaut par une version personnalisée, sans ajouter d'entrée supplémentaire au catalogue ni augmenter le volume de streaming.

Bonnes pratiques pour gérer un parc de véhicules addon

• Organisez vos resources dans un dossier dédié ([vehicles] ou [cars]) à l'intérieur du répertoire resources/ pour les identifier facilement dans le gestionnaire de fichiers ou par SFTP.
• Nommez chaque dossier de resource de façon descriptive : 2024-mustang-gt plutôt que car1. Ce nommage facilite la gestion quand le serveur héberge des dizaines de véhicules addon.
• Testez chaque véhicule individuellement avant de le déployer en production. Un seul fichier .yft corrompu peut provoquer des erreurs sur toutes les resources chargées après lui dans l'ordre de server.cfg.
• Surveillez le temps de connexion de vos joueurs : si le téléchargement initial dépasse deux minutes, réduisez la taille des fichiers .ytd, supprimez les textures en 4096 px ou retirez les véhicules les moins utilisés du serveur.
• Conservez une sauvegarde de chaque resource fonctionnelle sur un espace de stockage externe. Modifier un handling.meta ou un vehicles.meta peut casser le véhicule sans message d'erreur explicite dans les logs du serveur.
• Si vous utilisez un mapping personnalisé sur votre serveur, vérifiez les collisions entre les noms de modèle des véhicules et ceux des objets de mapping FiveM.
• Mettez à jour la version de vos artifacts FXServer et du gamebuild pour bénéficier des corrections liées au streaming et à la gestion mémoire.
• Sur un serveur avec un framework RP, documentez chaque véhicule addon ajouté à la base de données (nom, gameName, catégorie, prix) pour faciliter la maintenance à long terme.

Conclusion

L'ajout de véhicules addon sur un serveur FiveM suit une procédure répétable : créer un dossier de resource avec un fxmanifest.lua, y placer les fichiers .yft et .ytd dans stream/, configurer les fichiers meta dans data/, transférer la resource par SFTP sur le serveur et la charger dans server.cfg. Sur un serveur ESX ou QBCore, l'enregistrement du véhicule dans la base de données MySQL complète l'installation. L'essentiel de la difficulté réside dans l'optimisation des textures et le choix d'un hébergement adapté : un VPS ou un serveur dédié avec suffisamment de RAM, un stockage SSD rapide et une bande passante réseau généreuse garantissent un temps de connexion court pour vos joueurs, même avec un large catalogue de véhicules personnalisés.