QBCore, ESX ou standalone : comment les scripts Agency fonctionnent avec ton framework

Le problème de compatibilité des frameworks

La plupart des scripts FiveM sont livrés avec un framework codé en dur. Si tu utilises QBCore, tu utilises des scripts QBCore. Les utilisateurs d’ESX sont limités aux scripts ESX. Ceux qui utilisent standalone doivent souvent bricoler leur solution. Agency Scripts a été conçu selon la philosophie inverse : le framework est un adaptateur, pas une hypothèse de départ.

Le modèle d’adaptateur

Chaque script Agency expose quelques fonctions de récupération de données : getPlayerData, getInventory, addMoney, removeItem, getJobNous fournissons des adaptateurs qui les relient directement aux implémentations QBCore et ESX. Pour standalone, tu implémentes toi-même les quatre ou cinq fonctions, généralement en une matinée, et tous les scripts Agency deviennent compatibles.

Ce que ça signifie concrètement

Quand tu passes ton serveur de QBCore à ESX, ce qui arrive effectivement tous les quelques années à mesure que les frameworks évoluent, les scripts Agency n’ont pas besoin d’être réinstallés ni reconfigurés. Tu remplaces l’adaptateur et tout le reste continue de fonctionner. C’est extrêmement rare dans l’écosystème FiveM et c’est la principale raison pour laquelle les propriétaires de serveurs choisissent nos outils sur le long terme.

Que signifie le libellé de framework sur nos pages produit ?

Quand une page produit indique « QBCore, ESX », cela signifie que nous fournissons des adaptateurs prêts à l’emploi pour les deux frameworks. Quand elle indique « Standalone », cela signifie que le script ne dépend d’aucun framework, qu’il n’a pas besoin d’adaptateur et qu’il fonctionne sur n’importe quel serveur. En pratique, presque tous les scripts Agency peuvent être utilisés sur des configurations standalone avec une petite couche de compatibilité.

Quand nous contacter avant d’acheter

Si tu utilises une configuration inhabituelle, un framework personnalisé, un QBCore fortement modifié ou une solution sur mesure, ouvre un ticket sur notre Discord avant d’acheter. Nous te dirons honnêtement ce qui fonctionnera, ce qui nécessitera une légère adaptation et ce qui ne vaut pas la peine. Aucune pression commerciale, nous préférons que tu achètes un script adapté plutôt que trois qui ne le sont pas.

Comment fonctionne concrètement le modèle d’adaptateur

Quand tu installes un script Agency, le dossier de la ressource contient un framework sous-dossier avec au moins trois fichiers : qb.lua, esx.lua, et standalone.lua. Le script principal détecte automatiquement le framework présent en vérifiant l’export QBCore ou ESX. Le fichier d’adaptateur correspondant est chargé, les autres ne le sont pas. Cette détection automatique a lieu avant l’exécution de toute logique de jeu, elle n’entraîne aucune surcharge à l’exécution.

Chaque adaptateur implémente la même interface interne. Si un script doit donner de l’argent à un joueur, il appelle Framework.AddMoney(src, amount) en interne. Cette fonction, dans qb.lua appelle l’export monétaire de QBCore ; dans esx.lua elle appelle le système de comptes ESX ; dans standalone.lua elle appelle la fonction que tu as définie dans config.lua. Un appel, trois implémentations, aucune modification du script d’un framework à l’autre.

Installation sur QBCore

Sur les serveurs QBCore, l’installation se fait généralement en trois étapes : télécharger la ressource, la placer dans le dossier resources et l’ajouter à server.cfg. Le framework est détecté automatiquement. Si tu utilises un QBCore fortement modifié (système monétaire personnalisé, inventaire personnalisé, métiers personnalisés), tu devras peut-être remplacer certaines fonctions de l’adaptateur dans config.lua plutôt que de modifier qb.lua directement. L’approche par surcharge de configuration t’évite de perdre tes modifications lors des mises à jour de la ressource.

Installation sur ESX

L’installation sur ESX suit le même modèle. Une étape supplémentaire est parfois nécessaire : si ta version d’ESX est beaucoup plus ancienne (antérieure à 1.7), certaines fonctions de l’adaptateur utilisent des noms d’export ESX plus récents. La ressource inclut un indicateur de compatibilité avec les anciennes versions Config.ESXLegacy = true qui bascule vers les anciens appels d’API ESX dans tous les scripts Agency qui en ont besoin.

Installation en standalone

C’est avec le standalone que la plupart des propriétaires de serveurs ont rencontré des difficultés avec d’autres scripts. La prise en charge standalone d’Agency Scripts est explicite et bien documentée. Pour chaque script, le fichier d’adaptateur standalone répertorie exactement les fonctions que tu dois implémenter. La plupart des scripts nécessitent entre quatre et huit fonctions. Chaque fonction comporte un commentaire expliquant ce qu’elle doit renvoyer. Une implémentation standalone typique prend une à trois heures, selon la complexité de ton système personnalisé de données des joueurs.

Une fois l’adaptateur implémenté pour un script Agency, les scripts suivants demandent beaucoup moins de temps, car les mêmes fonctions personnalisées s’appliquent souvent à plusieurs ressources.

Pourquoi c’est important pour l’exploitation à long terme de ton serveur

Les frameworks FiveM ne sont pas permanents. Les serveurs actifs depuis trois ans ou plus ont probablement déjà dû faire au moins un choix majeur concernant leur framework, par exemple migrer d’un fork communautaire d’ESX vers la version principale d’ESX, ou d’une ancienne version de QBCore vers la version actuelle. Les serveurs qui s’appuient sur des scripts étroitement liés à un framework paient un lourd coût de migration : chaque script doit être mis à jour ou remplacé lorsque le framework change de manière importante.

Grâce à l’architecture par adaptateurs d’Agency Scripts, une migration de framework ne touche que la couche d’adaptation. Tes données Agency-Phone, les journaux Agency-Admin, l’historique des transactions Agency-Blackmarket et la progression des joueurs dans Agency-Minerjob restent intacts. Tu remplaces les fichiers d’adaptateur, tu mets à jour config.lua et les scripts continuent de fonctionner. C’est là que réside la véritable valeur à long terme de cette approche de compatibilité : elle ne sert pas seulement à prendre en charge plusieurs frameworks, elle protège aussi ton serveur de l’évolution des frameworks.

Questions fréquentes

Tous les scripts Agency utilisent-ils le même modèle d’adaptateur ?

Oui. Tous les scripts Agency payants et la plupart des scripts gratuits utilisent ce modèle. Les seules exceptions sont les ressources purement liées à l’interface, comme Agency-Loadingscreen et Agency-Notify, qui n’interagissent avec aucun framework et fonctionnent partout de la même manière.

Puis-je mélanger les adaptateurs de framework ? Par exemple, utiliser l’économie QBCore avec un inventaire standalone ?

Oui, via des remplacements dans la configuration. Définis la détection de ton framework sur QBCore, puis remplace des fonctions spécifiques de l’adaptateur dans config.lua pour appeler ton système d’inventaire personnalisé au lieu de celui de QBCore. Le système de remplacement est justement prévu pour les serveurs avec des configurations hybrides.

Que se passe-t-il si un nouveau framework devient populaire et n’est pas encore pris en charge ?

Ouvre un ticket d’assistance sur Discord. Nous évaluons les demandes de prise en charge de nouveaux frameworks en fonction de leur adoption par la communauté. Pour les frameworks qui ont des communautés importantes, nous avons historiquement ajouté la prise en charge sous 2-4 semaines. En attendant, l’adaptateur standalone fonctionne avec n’importe quel framework comme solution temporaire.

Les adaptateurs de framework sont-ils mis à jour lorsque le framework lui-même évolue ?

Oui. Lorsque QBCore ou ESX publie une mise à jour qui introduit des changements incompatibles, nous mettons à jour les adaptateurs dans les jours qui suivent la sortie du framework. Les abonnés actifs reçoivent des notifications de mise à jour via Tebex. C’est l’une des raisons d’être du modèle d’abonnement : la maintenance des adaptateurs est un travail continu, pas un coût ponctuel.

Résumé des exigences par framework

• QBCore, toute version récente de QBCore. Détection automatique, aucune configuration nécessaire pour les installations standard.
• ESX, ESX Legacy 1.7+ ou ESX mainline. Active l’indicateur legacy pour les anciennes versions.
• Standalone, implémente 4-8 fonctions par script dans config.lua. Configuration unique, réutilisable pour les scripts Agency.
• Toutes les configurations, compte cfx.re avec une licence valide, serveur FiveM avec Artifacts 5181 ou supérieur recommandé.