Un petit script, un effet démesuré
Les barres de progression apparaissent partout dans FiveM — crochetage, réparation, blanchiment d'argent, minage, soins médicaux. Les implémentations par défaut sont fonctionnelles mais plates. Agency-ProgressBar, c'est notre vision de ce à quoi cet utilitaire devrait ressembler quand quelqu'un se soucie des détails.
L'anatomie d'une bonne barre de progression
Une bonne barre de progression communique quatre choses en même temps : quelle action est en cours, à quel point tu es avancé, combien de temps il reste et si tu peux annuler. La plupart des implémentations ne gèrent que les deux premières. Agency-ProgressBar affiche les quatre, avec des animations subtiles qui rendent la progression fluide au lieu de saccadée.
Une annulation qui fonctionne
Une annulation déclenchée par le joueur lance une brève animation de fondu qui ramène l'opacité de la barre à zéro en 300ms. Pas de disparition brutale. Les développeurs peuvent enregistrer un callback d'annulation pour que les scripts se nettoient proprement quand les joueurs s'éloignent d'une action en cours.
Positionnement contextuel
La barre apparaît près de l'élément pertinent à l'écran — au-dessus de ta tête pour les actions sur toi-même, au-dessus du PNJ ciblé pour les actions interactives. Plus besoin de lire le statut de l'action en bas de l'écran alors que quelque chose se passe en haut. Ce positionnement contextuel est une amélioration UX subtile que les joueurs ressentent sans savoir la nommer.
Le pattern d'exports
Comme tous nos scripts utilitaires, Agency-ProgressBar expose une API exports simple : exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Intégré dans n'importe quel script en quelques minutes. Il se combine avec Agency-Notify, Agency-Hud et le reste de notre écosystème sans aucune configuration spéciale.
Installation et configuration
Agency-ProgressBar est un utilitaire sans dépendance de base de données. Téléchargez depuis Tebex, copiez dans le répertoire de ressources, ajoutez ensure agency-progressbar à server.cfg. La ressource démarre immédiatement et n'importe quel script peut appeler l'API exports au prochain redémarrage.
Options de configuration
- Position par défaut — au-dessus de la tête du joueur (défaut) ou au bas de l'écran au centre.
- Schéma de couleurs — le dégradé de remplissage. Supporte une seule couleur, un dégradé à deux arrêts, ou mappé par sévérité.
- Touche d'annulation — quelle touche annule une barre de progression annulable. Défaut : retour arrière.
- Affichage du temps — afficher les secondes restantes (défaut), le pourcentage, ou rien.
Compatibilité avec les frameworks
Agency-ProgressBar est entièrement autonome sans dépendances de framework. Il fonctionne identiquement sur QBCore, ESX et les configurations serveur personnalisées.
Pourquoi c'est important pour le roleplay
Les barres de progression apparaissent dans des dizaines de moments de gameplay — crochetage, menottes, artisanat, soins, collecte de preuves, piratage. Quand ces barres semblent dépareillées ou se comportent de manière incohérente entre différents scripts, cela crée un bruit visuel subtil qui sape la cohérence du serveur. Quand chaque barre de progression sur votre serveur utilise Agency-ProgressBar, le langage visuel est unifié.
Exemples pratiques d'intégration
Crochetage : Appelez Play({label = 'Crochetage...', duration = 8000, canCancel = true}) au début d'une tentative. Si le mini-jeu échoue, appelez Dismiss() avec l'ID retourné.
Traitement médical : Utilisez target = {type = 'entity', id = patientNetId} pour ancrer la barre au-dessus du patient plutôt que du médecin.
Collecte de preuves : Définissez canCancel = false pour la collecte de preuves scénarisée qui ne devrait pas être interruptible.
Foire aux questions
Puis-je exécuter plusieurs barres de progression simultanément ?
Oui. Chaque appel Play() retourne un ID et gère son propre état. Plusieurs barres s'empilent verticalement au-dessus du joueur avec un espacement raisonnable.
Prérequis
- Serveur FiveM (tout framework ou autonome)
- Compte cfx.re avec licence Agency-ProgressBar valide
- Aucune dépendance de base de données
Utilisation dans des scripts personnalisés
Agency-Progressbar brille vraiment quand vous l'intégrez dans vos propres ressources. L'appel d'API côté client est simple et direct. Voici comment vous pourriez l'utiliser pour une action de piratage :
Importez l'export, déclenchez la barre de progression avec une durée et un label personnalisé, puis attendez le callback pour savoir si l'action a réussi ou été interrompue. Si le joueur appuie sur la touche de déplacement pendant l'animation, la barre s'annule automatiquement — parfait pour les actions qui nécessitent de rester immobile.
Barres de progression en chaîne
Pour les actions complexes en plusieurs étapes, vous pouvez chaîner plusieurs barres de progression. La première barre "prépare les outils", la seconde "effectue l'action". Chaque étape peut avoir son propre label, sa propre durée et ses propres conditions d'annulation. Cela donne aux actions simples une sensation de profondeur sans code complexe.
Personnalisation visuelle
Au-delà du comportement fonctionnel, vous pouvez personnaliser l'apparence :
- Couleur de la barre — rouge pour les actions dangereuses, vert pour les actions positives, jaune pour les actions neutres
- Position — en bas de l'écran, au centre, ou au-dessus de la tête du personnage
- Icône — ajoutez une icône Font Awesome pertinente pour indiquer le type d'action
- Indicateurs de progression — afficher le pourcentage, les secondes restantes ou juste la barre
Prévention des exploits
Les barres de progression côté client sont jolies, mais sans validation côté serveur, elles peuvent être contournées. Agency-Progressbar s'intègre avec des systèmes de validation serveur — le serveur peut vérifier que l'action était valide quand le callback est reçu. Cela empêche les joueurs de modifier le script pour ignorer le délai et compléter instantanément les actions.
Exemples concrets d'utilisation
Voici des cas d'utilisation réels d'Agency-Progressbar dans des serveurs FiveM :
- Revive d'un joueur tombé — 10 secondes, annulable si le joueur se déplace
- Fouille d'un véhicule — 5 secondes, requiert d'être à côté du véhicule
- Plantation d'une bombe — 30 secondes, longue pour créer de la tension dramatique
- Cueillette de ressources — 3 secondes par ressource récoltée
- Déverrouillage d'une serrure de porte — 8 secondes avec outil de crochetage
À propos d'Agency Scripts
Agency Scripts est une collection de ressources FiveM premium conçues pour les serveurs de roleplay qui prennent l'immersion au sérieux. Chaque ressource est construite avec les mêmes principes : compatibilité multi-framework, performances optimisées, et configuration flexible pour s'adapter à n'importe quel concept de serveur.
Toutes les ressources Agency sont disponibles via le système de licences cfx.re Keymaster. Une fois achetée, vous pouvez déployer la ressource sur n'importe quel serveur que vous possédez, avec un support actif disponible via le Discord Agency Scripts.
Support et communauté
La communauté Agency Scripts comprend des milliers de serveurs FiveM qui utilisent ces ressources. Le Discord officiel est l'endroit où les développeurs partagent leurs configurations, posent des questions, et suggèrent de nouvelles fonctionnalités. Les mises à jour sont régulières et incluent à la fois des corrections de bugs et de nouvelles fonctionnalités basées sur les retours de la communauté.
Pour les questions d'installation, les problèmes de compatibilité ou les demandes de fonctionnalités, le Discord reste le meilleur canal. La documentation est maintenue à jour et couvre tous les paramètres de configuration avec des exemples pratiques.