Ajouter des ressources et des scripts

Un serveur FiveM vide ne fait presque rien : tout ce que vos joueurs verront — véhicules, métiers, interface, menu administrateur — arrive sous forme de ressources. Cette page explique comment en installer une proprement, comment la déclarer, et comment s’en sortir quand le serveur refuse de la charger. Elle s’adresse à quelqu’un qui a déjà un serveur FiveM qui démarre (sinon, commencez par Installer un serveur FiveM).

Tout se passe dans les fichiers de votre serveur, accessibles depuis panel.cloudfive.xyz avec le gestionnaire de fichiers ou en SFTP.

Comprendre le dossier resources

À la racine des fichiers de votre serveur, deux éléments comptent : le fichier server.cfg, qui décide de ce qui tourne, et le dossier resources, qui contient ce qui est disponible. Les deux sont indépendants : une ressource présente sur le disque mais absente de server.cfg ne sera jamais lancée.

Une ressource est un dossier qui contient un fichier fxmanifest.lua (ou, sur du code ancien, __resource.lua). C’est ce fichier qui dit à FiveM quels scripts charger, côté client et côté serveur.

• server.cfg
• Répertoireresources/

  • Répertoire[core]/

    • Répertoireoxmysql/

      • fxmanifest.lua
  • Répertoire[local]/ vos ressources à vous

    • Répertoiremon-script/

      • fxmanifest.lua
• Répertoirecache/

  • …

Les dossiers dont le nom est entre crochets, comme [local] ou [core], ne sont pas des ressources : ce sont de simples classeurs. FiveM descend dedans pour trouver les vraies ressources, mais vous ne les déclarez jamais dans server.cfg. C’est pratique pour séparer ce que vous avez ajouté de ce qui est venu avec l’installation.

Prenez l’habitude de ranger

Mettez toutes vos installations dans un dossier [local]. Le jour où vous réinstallez ou migrez, vous savez exactement ce qui est à vous.

Installer une ressource et la déclarer avec ensure

1. Téléchargez la ressource et ouvrez l’archive avant de l’envoyer. Repérez le dossier qui contient directement fxmanifest.lua : c’est celui-là qu’il faut envoyer, pas l’archive entière.

2. Envoyez ce dossier dans resources/[local]/. Pour une ressource légère, le gestionnaire de fichiers suffit ; pour un pack de véhicules ou de vêtements, passez par le SFTP, bien plus rapide sur un grand nombre de fichiers.

3. Vérifiez le nom du dossier final. Évitez les espaces, les majuscules et les accents, et supprimez les suffixes ajoutés par le téléchargement comme -main ou -master.

4. Ouvrez server.cfg et ajoutez une ligne ensure avec le nom exact du dossier :

   server.cfg

   ensure oxmysql
   ensure mon-script

5. Enregistrez le fichier, puis redémarrez le serveur depuis le panel — voir Démarrer, arrêter et redémarrer son serveur.

6. Lisez la console pendant le démarrage. Une ressource chargée correctement n’affiche rien d’alarmant ; une ressource introuvable le dit explicitement.

Le serveur tourne sous Linux : MonScript et monscript sont deux noms différents. C’est la première cause de « couldn’t find resource ».

ensure, start, stop, restart

ensure démarre la ressource, et la redémarre si elle tournait déjà. C’est le mot-clé à utiliser par défaut dans server.cfg. start ne fait que démarrer. Dans la console du serveur, restart mon-script et stop mon-script agissent sans redémarrer tout le serveur.

Ne remplacez pas un dossier existant à l’aveugle

Si vous écrasez une ressource déjà installée pour la mettre à jour, vous perdez les fichiers de configuration que vous aviez modifiés dedans (souvent config.lua). Téléchargez l’ancien dossier d’abord, ou prenez une sauvegarde avant l’opération.

Gérer les dépendances entre ressources

La plupart des scripts ne fonctionnent pas seuls. Trois dépendances reviennent sans arrêt :

• un accès à la base de données, presque toujours oxmysql — voir Connecter la base de données ;
• un framework (ESX, QBCore, et leurs dérivés), qui fournit les comptes joueurs, l’argent, les métiers ;
• une bibliothèque partagée, par exemple ox_lib, utilisée par de nombreux scripts récents pour les menus et les notifications.

Pour savoir ce qu’une ressource exige, ouvrez son fxmanifest.lua : les lignes dependency ou dependencies listent ce qui doit tourner avant elle. Lisez aussi le fichier d’installation fourni par l’auteur (README, INSTALL), qui mentionne souvent un fichier .sql à importer et des lignes à ajouter côté framework.

Une ressource dont la dépendance manque démarre généralement sans erreur, puis ne fait rien du tout en jeu. C’est déroutant : ne cherchez pas le bug dans le script, cherchez la dépendance.

Ordre de chargement et conflits

server.cfg est lu de haut en bas, et cet ordre est l’ordre de chargement. Il n’a pas d’importance pour la plupart des scripts, mais il en a pour les briques de base. Dans l’ordre :

1. oxmysql ou l’accès base de données ;
2. les bibliothèques partagées (ox_lib…) ;
3. le framework ;
4. tout le reste.

server.cfg — la trame

ensure oxmysql
ensure ox_lib
ensure es_extended
ensure mon-script

Les conflits, eux, ne sont pas une question d’ordre. Ils apparaissent quand deux ressources enregistrent la même commande, le même événement ou la même touche. Symptôme typique : une fonctionnalité marche une fois sur deux, ou la console répète la même erreur. Deux pistes :

• la ressource est installée en double, sous deux noms de dossier différents. Cherchez le même nom de script à deux endroits dans resources ;
• deux scripts font le même métier (deux inventaires, deux systèmes de téléphone). Il faut choisir, et retirer la ligne ensure du perdant.

Installez une ressource à la fois

Ajoutez une ressource, redémarrez, vérifiez en jeu, puis passez à la suivante. Quand six nouveautés arrivent ensemble et que le serveur ne démarre plus, il n’y a aucun moyen rapide de savoir laquelle est fautive.

Dans la console du serveur, refresh relit la liste des ressources présentes sur le disque. Enchaînez refresh puis ensure mon-script pour prendre en compte une ressource que vous venez d’envoyer, sans redémarrer tout le serveur. Attention : refresh ne recharge pas le contenu d’une ressource déjà lancée, et une modification de server.cfg demande un vrai redémarrage.

Cas des ressources protégées (escrow)

Les ressources payantes achetées sur la boutique Cfx.re arrivent souvent chiffrées : c’est le système d’escrow. Le code est illisible et non modifiable, à l’exception des fichiers que l’auteur a volontairement laissés ouverts (en général la configuration et les traductions).

Deux conséquences pratiques :

• une ressource escrow est liée à votre clé Cfx.re. Si vous changez de clé, ou si vous installez la ressource sur un serveur qui utilise une autre clé, elle refusera de démarrer avec une erreur d’autorisation. Voir Obtenir et configurer sa clé Cfx.re ;
• n’essayez pas de modifier les fichiers chiffrés : vous casserez la signature et la ressource ne se lancera plus. Pour une adaptation profonde, il faut passer par l’auteur.

L’association entre la ressource et votre serveur se gère depuis votre compte Cfx.re, au même endroit que la clé. Si vous déplacez votre serveur, mettez-la à jour avant de chercher ailleurs.

Les ressources piratées coûtent plus cher qu’elles ne rapportent

Les versions « leak » de scripts payants sont la source la plus fréquente de portes dérobées sur les serveurs FiveM : vol de base de données, comptes administrateurs créés en silence, serveur utilisé pour attaquer d’autres machines. Elles sont par ailleurs interdites par nos conditions générales. Si vous suspectez une ressource, retirez-la et signalez-la à abuse@cloudfive.xyz.

Si ça ne marche pas

« couldn’t find resource mon-script ». Le nom dans server.cfg ne correspond pas au nom du dossier. Vérifiez les majuscules, les tirets, et surtout l’absence de dossier en trop : resources/[local]/mon-script-main/mon-script/fxmanifest.lua ne sera jamais trouvé. Le fxmanifest.lua doit être directement dans le dossier que vous déclarez.

La ressource démarre mais rien ne se passe en jeu. Il manque une dépendance, ou l’étape d’installation côté framework et côté base de données n’a pas été faite. Relisez la console du démarrage depuis le début : l’erreur utile est presque toujours la première, pas la dernière.

Le serveur ne démarre plus depuis l’ajout. Commentez la ligne en la préfixant d’un #, redémarrez pour confirmer que c’est bien elle, puis réintroduisez la ressource une fois sa dépendance en place.

Une erreur d’escrow ou d’autorisation. La clé Cfx.re du serveur n’est pas celle à laquelle la ressource est rattachée : vérifiez la clé avant toute autre manipulation.

Tout fonctionne, mais le serveur est devenu lent. C’est normal après une série d’ajouts, et ça se mesure : voyez Optimiser les performances de son serveur FiveM. Si la limite est matérielle plutôt que logicielle, comparez avec Combien de RAM pour un serveur FiveM ?.

Si vous êtes bloqué après ces vérifications, ouvrez un ticket de support en indiquant le nom de la ressource et en copiant les lignes de console concernées.