Agency-ProgressBar: Das UI-Detail, das jedes Skript unauffällig aufwertet

Ein winziges Script, eine enorme Wirkung

Fortschrittsbalken tauchen überall in FiveM auf: beim Knacken von Schlössern, Reparieren, Geldwaschen, Bergbau und bei medizinischer Versorgung. Die Standardimplementierungen funktionieren, sind aber schlicht. Agency-ProgressBar zeigt, wie sich dieses Hilfsprogramm anfühlen sollte, wenn auf die Details geachtet wird.

Der Aufbau eines guten Fortschrittsbalkens

Ein guter Fortschrittsbalken vermittelt gleichzeitig vier Dinge: welche Aktion ausgeführt wird, wie weit sie fortgeschritten ist, wie viel Zeit noch verbleibt und ob du sie abbrechen kannst. Die meisten Implementierungen decken nur die ersten beiden ab. Agency-ProgressBar zeigt alle vier Informationen und sorgt mit dezenten Animationen für einen flüssigen statt ruckeligen Fortschritt.

Abbrechen, das funktioniert

Wenn ein Spieler eine Aktion abbricht, wird der Balken kurz ausgeblendet und seine Deckkraft innerhalb von 300ms auf null gesetzt. Er verschwindet nicht abrupt. Entwickler können einen Abbruch-Callback registrieren, damit Scripts ordnungsgemäß aufräumen, wenn Spieler eine Aktion mittendrin abbrechen.

Kontextbezogene Positionierung

Der Balken erscheint in der Nähe des relevanten Elements auf dem Bildschirm: bei Aktionen an dir selbst über deinem Kopf, bei interaktiven Aktionen über dem Ziel-NPC. Du musst den Aktionsstatus nicht mehr unten auf dem Bildschirm ablesen, während oben etwas passiert. Diese kontextbezogene Positionierung ist eine dezente UX-Verbesserung, die Spieler bemerken, ohne sie benennen zu können.

Das Export-Muster

Wie alle unsere Hilfs-Scripts bietet Agency-ProgressBar eine einfache Exports-API: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}) . Integriere es in wenigen Minuten in jedes Script. Es lässt sich ohne spezielle Konfiguration mit Agency-Notify, Agency-Hud und dem Rest unseres Ökosystems kombinieren.

Installation & Einrichtung

Agency-ProgressBar ist ein sofort einsatzbereites Hilfsprogramm ohne Datenbankabhängigkeit. Lade es von Tebex herunter, lege den Ordner in dein resources-Verzeichnis und füge ensure agency-progressbar in server.cfghinzu. Das ist alles. Die Resource funktioniert sofort und jedes Script kann die Exports-API nach dem nächsten Neustart aufrufen.

Wenn du einen bestehenden Fortschrittsbalken ersetzt (ox_libs progressBar, qb-progressbar usw.), reicht für die meisten Migrationen eine Änderung des Export-Aufrufs per Suchen und Ersetzen. Die Parameterstruktur orientiert sich bewusst an gängigen Community-Mustern.

Konfigurationsoptionen

Öffne config.lua zum Anpassen der Standardwerte:

• Standardposition, über dem Kopf des Spielers (Standard) oder fest unten in der Mitte.
• Farbschema , Farbverlauf der Füllung. Unterstützt eine einzelne Farbe, einen Verlauf aus zwei Farben oder eine Zuordnung nach Schweregrad (Grün für normal, Orange für langsam, Rot für kritisch).
• Abbruchtaste, welche Taste einen abbrechbaren Fortschrittsbalken abbricht. Standard: Backspace.
• Abbruchanimation fade-out (Standard), slide-out oder sofortiges Verschwinden.
• Zeitanzeige, verbleibende Sekunden anzeigen (Standard), Prozentwert oder keine Anzeige.
• Mindestdauer, Aktionen, die kürzer als dieser Schwellenwert sind, überspringen den Balken vollständig. Standard: 500ms.

Framework-Kompatibilität

Agency-ProgressBar ist vollständig standalone und hat keine Framework-Abhängigkeiten. Es funktioniert identisch mit QBCore, ESX und benutzerdefinierten Server-Setups. Die Exports-API ist die einzige Integrationsschnittstelle, es gibt keine gemeinsamen globalen Variablen, Framework-Events oder Berechtigungsprüfungen. Installiere es und rufe es von jedem Script aus auf, unabhängig von dessen Herkunft.

Warum das für Roleplay wichtig ist

Fortschrittsbalken sind ein grundlegendes UX-Element, das in zahlreichen Spielsituationen zum Einsatz kommt: beim Schlösserknacken, beim Anlegen von Handschellen, beim Crafting, beim Heilen, beim Sammeln von Beweisen und beim Hacken. Wenn diese Balken in verschiedenen Scripts uneinheitlich aussehen oder sich unterschiedlich verhalten, entsteht eine subtile visuelle Unruhe, die den stimmigen Gesamteindruck des Servers beeinträchtigt.

Wenn jeder Fortschrittsbalken auf deinem Server Agency-ProgressBar verwendet, ist die visuelle Sprache einheitlich. Spieler entwickeln ein intuitives Verständnis dafür, was der Balken bedeutet und wie er sich verhält. Das Abbrechen funktioniert immer gleich. Die Typografie passt zum Rest deiner UI. Kleinigkeiten, die sich zu einem spürbar ausgereifteren Spielerlebnis summieren.

Die kontextbezogene Positionierung ist wichtiger, als es zunächst klingt. Ein während des Schlösserknackens über dem Kopf deines Charakters verankerter Fortschrittsbalken hält deinen Fokus auf der Aktion und nicht auf einer Bildschirmecke. In angespannten Momenten, zum Beispiel wenn du verfolgt wirst und gleichzeitig ein Schloss knackst, bleiben Spieler so auch bei eingeblendetem Balken räumlich orientiert.

Häufig gestellte Fragen

Kann ich mehrere Fortschrittsbalken gleichzeitig ausführen?

Ja. Jeder Play() Aufruf gibt eine ID zurück und verwaltet seinen eigenen Status. Mehrere Balken werden mit angemessenem Abstand vertikal über dem Spieler gestapelt. Das ist bei mehrstufigen Aktionen nützlich, bei denen der Fortschritt paralleler Aufgaben gleichzeitig sichtbar sein muss, auch wenn in den meisten RP-Szenarien nur ein Balken gleichzeitig verwendet wird.

Wie befestige ich einen Fortschrittsbalken an einem Objekt oder NPC statt am Spieler?

Übergib ein target = {type = 'entity', id = entityNetId} Feld in der Options-Tabelle. Der Balken schwebt über der angegebenen Entity statt über dem Spieler. Verwende das für Reparaturen, medizinische Aktionen an bewusstlosen Spielern oder andere Fälle, in denen sich die Aktion auf etwas außerhalb des Spielers bezieht.

Kann der Balken serverseitig so eingestellt werden, dass er nicht abgebrochen werden kann?

Ja. Setze canCancel = false beim Aufruf von Play(). Die Abbruchtaste hat keine Wirkung und es wird keine Abbruchanimation abgespielt. Das eignet sich für serverseitig erzwungene Aktionen wie Festnahmeanimationen oder geskriptete Zwischensequenzen, bei denen eine Unterbrechung durch den Spieler den Ablauf stören würde.

Funktioniert das mit ox_lib-Animationen?

Ja. Agency-ProgressBar ist animationsunabhängig. Du steuerst die Animationen in deinem eigenen Script parallel zum Aufruf des Fortschrittsbalkens. Der Balken ist ausschließlich ein UI-Element. Du kannst ihn unabhängig davon mit jeder Animationsbibliothek oder mit direkten FiveM-Animationsaufrufen kombinieren.

Voraussetzungen

• FiveM-Server (beliebiges Framework oder standalone)
• cfx.re-Konto mit einer gültigen Agency-ProgressBar-Lizenz
• Keine Datenbankabhängigkeit
• Keine Abhängigkeiten von externen Resources

Praktische Integrationsbeispiele

Hier sind gängige Muster zur Integration von Agency-ProgressBar in bestehende Scripts:

Schlösserknacken: Rufe Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) zu Beginn eines Knackversuchs auf. Führe parallel dazu das Schlossknack-Minispiel aus. Wenn das Minispiel fehlschlägt, rufe Dismiss() mit der zurückgegebenen ID auf. Bei Erfolg lässt du den Balken normal zu Ende laufen.

Medizinische Behandlung: Verwende target = {type = 'entity', id = patientNetId} um den Balken über dem Patienten statt über dem Sanitäter zu verankern. Spieler, die die Szene beobachten, sehen den Fortschritt direkt am Behandlungsort und nicht über dem Kopf des Sanitäters.

Beweissicherung: Lege fest canCancel = false für geskriptete Beweissicherung, die nicht unterbrochen werden soll, damit Spieler nicht abbrechen können, um keine Fingerabdrücke am Tatort zu hinterlassen. Der nicht abbrechbare Balken macht deutlich, dass diese Aktion verpflichtend und nicht optional ist.

Serverseitige Aktionen: Zeige auf dem Client einen Fortschrittsbalken an, während eine serverseitige Aktion asynchron ausgeführt wird. Sobald der Server-Callback zurückgegeben wird, lässt du den Balken entweder bis zum Ende laufen oder blendest ihn abhängig vom serverseitigen Ergebnis vorzeitig aus. Die angezeigte Dauer sollte ungefähr der erwarteten Verarbeitungszeit des Servers entsprechen.