Le problème de la compatibilité de framework
La plupart des scripts FiveM sont livrés avec un framework codé en dur. Si tu tournes sous QBCore, tu utilises des scripts QBCore. Les utilisateurs d'ESX sont coincés avec des scripts ESX. Les utilisateurs standalone bricolent le plus souvent les choses eux-mêmes. Agency Scripts a été conçu avec la philosophie inverse: le framework est un adaptateur, pas une hypothèse.
Le pattern d'adaptateur
Chaque script Agency expose un petit jeu de fonctions de lookup: getPlayerData, getInventory, addMoney, removeItem, getJob. On livre des adaptateurs qui les mappent vers les implémentations QBCore et ESX, sorti du carton. Pour standalone, tu implémentes toi-même ces quatre ou cinq fonctions — en général le boulot d'une matinée — et chaque script Agency devient compatible.
Ce que ça donne en pratique
Quand tu bascules ton serveur de QBCore à ESX (ce qui arrive 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 échanges l'adaptateur, tout le reste continue de tourner. C'est incroyablement rare dans l'écosystème FiveM, et c'est la raison principale pour laquelle les propriétaires de serveurs standardisent leur outillage sur le nôtre sur la durée.
Ce que signifie chaque label framework sur nos fiches produit
Quand une fiche produit mentionne «QBCore, ESX», ça veut dire qu'on livre des adaptateurs prêts pour les deux. Quand elle dit «Standalone», on veut dire que le script est framework-agnostique — il n'a besoin d'aucun adaptateur et tourne sur n'importe quel serveur. En pratique, presque tous les scripts Agency sont utilisables sur des installations standalone avec un petit shim de compatibilité.
Quand demander avant d'acheter
Si tu tournes sur une config inhabituelle — framework custom, QBCore très modifié ou truc sur mesure — ouvre un ticket sur notre Discord avant d'acheter. On te dira honnêtement ce qui marchera, ce qui demande une légère adaptation et ce qui ne vaut pas le coup. Pas de pression commerciale; on préfère que tu achètes un script qui te convient plutôt que trois qui ne te conviennent pas.
Comment fonctionne le pattern d'adaptateur en pratique
Quand vous installez un script Agency, le dossier de ressource contient un sous-répertoire framework avec au moins trois fichiers : qb.lua, esx.lua et standalone.lua. Le script principal détecte automatiquement quel framework est présent. Le fichier adaptateur correspondant se charge ; les autres ne le font pas.
Installation sur QBCore
Pour les serveurs QBCore, l'installation comprend généralement trois étapes : télécharger la ressource, la copier dans le dossier de ressources, et l'ajouter à server.cfg. La détection du framework est automatique. Pour les configurations QBCore significativement modifiées, vous pouvez avoir besoin de remplacer des fonctions d'adaptateur spécifiques dans config.lua.
Installation sur ESX
L'installation ESX suit le même schéma. Pour les versions ESX plus anciennes (avant 1.7) : définissez le flag de compatibilité legacy Config.ESXLegacy = true qui bascule vers les anciens appels d'API ESX.
Installation en mode autonome
Pour chaque script, le fichier d'adaptateur autonome liste exactement quelles fonctions vous devez implémenter — généralement quatre à huit fonctions. Une implémentation typique autonome prend une à trois heures selon la complexité de votre système de données joueur personnalisé. Une fois que vous avez implémenté l'adaptateur pour un script Agency, les scripts suivants prennent beaucoup moins de temps.
Pourquoi c'est important pour l'exploitation à long terme
Les frameworks FiveM ne sont pas permanents. L'architecture d'adaptateur d'Agency Scripts signifie qu'une migration de framework n'affecte que la couche d'adaptateur. Vos données Agency-Phone, journaux Agency-Admin, historique de transactions Agency-Blackmarket, et progression des joueurs dans Agency-Minerjob survivent tous intacts. Vous échangez les fichiers d'adaptateur, mettez à jour config.lua, et les scripts continuent de fonctionner.
Foire aux questions
Tous les scripts Agency utilisent-ils le même pattern d'adaptateur ?
Oui. Chaque script Agency payant et la plupart des gratuits utilisent ce pattern. Les seules exceptions sont les ressources purement UI comme Agency-Loadingscreen et Agency-Notify, qui n'ont aucune interaction de framework.
Que se passe-t-il si un nouveau framework devient populaire et n'est pas encore supporté ?
Ouvrez un ticket de support sur Discord. Nous évaluons les nouvelles demandes de support de framework en fonction de l'adoption communautaire. Historiquement, nous avons ajouté le support dans les 2 à 4 semaines pour les frameworks avec des communautés significatives.
Résumé des prérequis par framework
- QBCore — toute version récente de QBCore. Auto-détecté, zéro configuration pour les configurations standard.
- ESX — ESX Legacy 1.7+ ou ESX mainline. Définissez le flag legacy pour les versions plus anciennes.
- Autonome — implémentez 4 à 8 fonctions par script dans config.lua.
Migrer entre frameworks avec Agency Scripts
L'un des moments les plus stressants pour un développeur FiveM est de décider de migrer d'ESX vers QBCore ou vice versa. Cette migration implique habituellement de réécrire des dizaines de ressources. Avec Agency Scripts, la douleur est considérablement réduite.
Parce que toutes les ressources Agency utilisent la même couche d'abstraction de framework, vous n'avez pas besoin de réécrire la logique de l'application — vous changez seulement la configuration de framework. Les données de base, la logique des emplois, les configurations d'articles, restent identiques. Seule la couche d'intégration change.
Configuration du détecteur de framework
Le détecteur automatique de framework fonctionne en vérifiant les ressources présentes au démarrage. Si qb-core est détecté, il utilise les fonctions QBCore. Si es_extended est détecté, il utilise les fonctions ESX. Sinon, il tombe en mode standalone. Cette détection se passe une fois au démarrage et n'a aucun coût de performance pendant l'exécution.
Mode standalone : plus flexible qu'il n'y paraît
Le mode standalone d'Agency Scripts n'est pas seulement pour les serveurs sans framework. Certains opérateurs de serveurs choisissent délibérément le mode standalone parce qu'il leur donne plus de contrôle. Ils construisent leur propre couche de données minimaliste et utilisent les ressources Agency comme blocs de construction. C'est une approche avancée mais puissante.
Tester la compatibilité
Avant de déployer Agency Scripts en production sur un nouveau framework, testez toujours dans un environnement de staging. La plupart des problèmes de compatibilité surviennent avec des versions non-standard ou fortement modifiées des frameworks. Agency Scripts est testé contre les versions officielles les plus récentes de QBCore et ESX — les forks peuvent nécessiter des ajustements mineurs.