Ein kleines Script mit übergroßer Wirkung
Progress-Bars tauchen in FiveM überall auf — Lockpicking, Reparieren, Geldwäsche, Mining, medizinische Hilfe. Standardimplementierungen sind funktional, aber flach. Agency-ProgressBar ist unsere Sicht darauf, wie sich dieses Hilfsmittel anfühlen sollte, wenn jemand Wert auf die Details legt.
Die Anatomie einer guten Progress-Bar
Eine gute Progress-Bar kommuniziert gleichzeitig vier Dinge: welche Aktion passiert, wie weit du schon bist, wie viel Zeit noch bleibt und ob du abbrechen kannst. Die meisten Implementierungen decken nur die ersten beiden ab. Agency-ProgressBar zeigt alle vier, mit subtilen Animationen, die Fortschritt flüssig wirken lassen statt ruckelig.
Abbruch, der funktioniert
Ein vom Spieler ausgelöster Abbruch startet eine kurze Fade-Out-Animation, die die Deckkraft des Balkens in 300ms auf null zurückführt. Kein abruptes Verschwinden. Entwickler können einen Cancel-Callback registrieren, damit Scripts sauber aufräumen, wenn Spieler mittendrin von einer Aktion weggehen.
Kontextbezogene Positionierung
Der Balken erscheint in der Nähe des relevanten Bildschirmelements — über deinem Kopf bei Aktionen, die dich selbst betreffen, über dem Ziel-NPC bei interaktiven Aktionen. Kein Ablesen mehr vom unteren Bildschirmrand, während oben etwas passiert. Diese kontextbezogene Positionierung ist ein subtiles UX-Upgrade, das Spieler spüren, ohne es benennen zu können.
Das Export-Pattern
Wie alle unsere Utility-Scripts stellt Agency-ProgressBar eine einfache Exports-API bereit: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). In Minuten in jedes Script integriert. Es arbeitet mit Agency-Notify, Agency-Hud und dem Rest unseres Ökosystems ohne jede Spezialkonfiguration zusammen.
Installation & Einrichtung
Agency-ProgressBar ist ein Drop-in-Hilfsmittel ohne Datenbankabhängigkeit. Herunterladen aus Tebex, Ordner in das Ressourcenverzeichnis legen, ensure agency-progressbar zur server.cfg hinzufügen. Fertig. Die Ressource startet sofort und jedes Script kann die Exports-API beim nächsten Neustart aufrufen.
Konfigurationsoptionen
- Standardposition — Über dem Spielerkopf (Standard) oder feste Unterseite-Mitte.
- Farbschema — Die Füll-Farbverlaufsfarbe. Unterstützt Einzelfarbe, Zwei-Stopp-Verlauf oder Schweregrad-Zuordnung.
- Abbruch-Taste — Welche Taste einen abbrechbaren Fortschrittsbalken abbricht. Standard: Backspace.
- Zeitanzeige — Verbleibende Sekunden (Standard), Prozent oder keines von beidem.
Framework-Kompatibilität
Agency-ProgressBar ist vollständig eigenständig ohne Framework-Abhängigkeiten. Es funktioniert identisch auf QBCore, ESX und benutzerdefinierten Server-Setups.
Warum das für das Roleplay wichtig ist
Fortschrittsbalken erscheinen in Dutzenden von Gameplay-Momenten — Schloss-Knacken, Fesseln, Crafting, Heilen, Beweissicherung, Hacking. Wenn diese Balken über verschiedene Scripts hinweg nicht übereinstimmen oder inkonsistent funktionieren, erzeugt das subtiles visuelles Rauschen, das die Server-Kohärenz untergräbt.
Häufig gestellte Fragen
Kann ich mehrere Fortschrittsbalken gleichzeitig ausführen?
Ja. Jeder Play()-Aufruf gibt eine ID zurück und verwaltet seinen eigenen Zustand. Mehrere Balken stapeln sich vertikal über dem Spieler mit angemessenem Abstand.
Wie befestige ich einen Fortschrittsbalken an einem Stützpunkt oder NPC?
Übergib ein target = {type = 'entity', id = entityNetId}-Feld in der Optionstabelle. Der Balken schwebt dann über der angegebenen Entität.
Voraussetzungen
- FiveM-Server (beliebiges Framework oder eigenständig)
- cfx.re-Konto mit gültiger Agency-ProgressBar-Lizenz
- Keine Datenbankabhängigkeit
Praktische Integrationsbeispiele
Hier sind gängige Muster für die Integration von Agency-ProgressBar in bestehende Scripts:
Schloss-Knacken: Rufe Play({label = 'Schloss knacken...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) zu Beginn eines Schlossknack-Versuchs auf. Kombiniere dies mit dem gleichzeitig laufenden Schlossknack-Mini-Spiel. Wenn das Mini-Spiel fehlschlägt, rufe Dismiss() mit der zurückgegebenen ID auf.
Medizinische Behandlung: Verwende target = {type = 'entity', id = patientNetId}, um den Balken über dem Patienten zu verankern, nicht über dem Sanitäter. Spieler, die die Szene beobachten, sehen den Fortschritt am Behandlungspunkt.
Beweissicherung: Setze canCancel = false für geskriptete Beweissicherung, die nicht unterbrechbar sein sollte. Der nicht-abbrechbare Balken teilt dem Spieler mit, dass diese Aktion obligatorisch ist.
Serverseitige Aktionen: Starte einen Fortschrittsbalken auf dem Client, während eine serverseitige Aktion asynchron läuft. Wenn der Server-Callback zurückkommt, lass den Balken entweder abschließen oder dismissiere ihn frühzeitig basierend auf dem serverseitigen Ergebnis.
Konsistenz über alle Scripts hinweg
Der stärkste Vorteil von Agency-ProgressBar wird sichtbar, wenn der gesamte Server ihn verwendet. Wenn jede Fortschrittsanzeige auf deinem Server dieselbe visuelle Sprache spricht — dieselben Farben, dieselbe Animation, dasselbe Abbruchverhalten — entwickeln Spieler Intuition für das System. Das ist der Unterschied zwischen einem Server, der sich zusammengestückelt anfühlt, und einem, der sich wie ein kohärentes Produkt anfühlt.
Konsistenz als Server-Qualitätsmerkmal
Der stärkste Vorteil von Agency-ProgressBar wird sichtbar, wenn der gesamte Server ihn verwendet. Wenn jede Fortschrittsanzeige auf deinem Server dieselbe visuelle Sprache spricht — dieselben Farben, dieselbe Animation, dasselbe Abbruchverhalten — entwickeln Spieler Intuition für das System. Ein Spieler, der seit zwei Wochen auf deinem Server spielt, weiß reflexartig, was der Fortschrittsbalken bedeutet und wie er sich verhalten wird.
Das ist der Unterschied zwischen einem Server, der sich zusammengestückelt anfühlt, und einem, der sich wie ein kohärentes Produkt anfühlt. Visuelle Konsistenz in UI-Primitiven ist eine der unbekanntesten aber effektivsten Polieraktionen, die ein Serverbesitzer vornehmen kann — und da Agency-ProgressBar alle Anwendungsfälle über einen einzigen Export abdeckt, ist die Erreichung dieser Konsistenz fast mühelos.
Migration von bestehenden Systemen
Beim Ersetzen von ox_lib-Progressbars: Der Hauptunterschied in der API ist, dass Agency-ProgressBar eine ID zurückgibt und explizite Update/Dismiss-Calls für programmatische Kontrolle verwendet, während ox_lib dies nicht tut. Für einfache Anwendungsfälle (Start → Abschluss ohne Programmsteuerung) sind die APIs im Wesentlichen gleichwertig. Für komplexere Anwendungsfälle (Progress aktualisieren, vorzeitig beenden) musst du diese Logik hinzufügen, wo du zuvor darauf verzichtet hast.
Performance-Eigenschaften
Agency-ProgressBar läuft vollständig im NUI-Kontext, was bedeutet, dass alle visuellen Berechnungen vom Browser-Engine des Clients übernommen werden, nicht von FiveMs Lua-Laufzeit. Das Ergebnis ist 0,00ms Idle-Ressourcenverbrauch, wenn kein Fortschrittsbalken aktiv ist, und sehr geringe Active-Kosten (unter 0,02ms) wenn einer angezeigt wird. Für Server mit 100+ gleichzeitigen Spielern ist diese Performance-Charakteristik relevant — die aggregierte Wirkung über die Spielerbevölkerung bleibt flat.
Die Client-Server-Kommunikation ist minimiert: Der Server initiiert einen Fortschrittsbalken auf dem Client, der Client verwaltet den Zeitablauf und die Annulier-Logik lokal, und der Server wird nur benachrichtigt, wenn der Balken abgeschlossen oder annulliert wird. Es gibt keine Polling-Logik, keine regelmäßigen Server-Events während ein Balken aktiv ist — die Kommunikation ist ereignisgesteuert, nicht zeitgesteuert.
Zusammenfassung
Agency Scripts baut seine gesamte Produktlinie nach denselben Grundprinzipien: Framework-agnostische Architektur, schlanke Performance-Eigenschaften, klar dokumentierte Konfiguration und eine API, die echte Composability zwischen den Scripts ermöglicht. Kein Script ist eine Insel — jedes ist so gebaut, dass es gut allein und noch besser als Teil des Ökosystems funktioniert.
Für Fragen zur Installation, Konfiguration oder Kompatibilität ist der Agency Scripts Discord der schnellste Weg zur Hilfe. Die Community dort ist aktiv und hilfsbereit, und das Core-Team ist regelmäßig präsent. Für kritische Probleme steht auch ein direktes Support-Ticket-System auf der Tebex-Produktseite zur Verfügung.
Updates für alle Agency-Scripts werden über Tebex-Benachrichtigungen kommuniziert. Active-Business-Abonnenten erhalten neue Scripts automatisch ohne zusätzlichen Kauf. Changelog-Details erscheinen im #changelog-Kanal des Discords, damit du Updates bewerten kannst, bevor du sie auf einem Produktionsserver installierst.