Agency-Notify: Benachrichtigungen sollten sich wie iOS anfühlen, nicht wie FiveM aus 2014

Das Benachrichtigungs-Ghetto

Benachrichtigungen auf den meisten FiveM-Servern sehen immer noch aus wie das Standard-ESX von 2019. Ein einfacher farbiger Balken oben, vielleicht ein Symbol, eine Textzeile. Spieler haben sich angewöhnt, sie zu ignorieren. Dabei wird ein wichtiger Kommunikationskanal völlig verschwendet.

So sehen moderne Benachrichtigungen aus

Agency-Notify bietet Toast-Benachrichtigungen, die sich sauber stapeln, umfangreiche Inhalte unterstützen (Symbole, Bilder, mehrzeiliger Text, Aktionsschaltflächen) und klar unterscheidbare Schweregrade mit eigenen visuellen Darstellungen bieten. Erfolg, Warnung, Fehler, Info, jeder Typ hat seine eigene Animation, Farbe und Schriftstärke.

Gruppierung verhindert Spam

Wenn drei ähnliche Benachrichtigungen kurz hintereinander erscheinen würden, fasst Agency-Notify sie zu einer gruppierten Benachrichtigung zusammen. Keine drei identischen „Du hast $500 erhalten“-Toasts mehr, die den Bildschirm blockieren. Dieses Verhalten erwarten Spieler von jeder modernen App, und jetzt gibt es das endlich auch in FiveM.

Programmierfreundliche API

Ein Funktionsaufruf genügt, um eine Benachrichtigung aus einem beliebigen Script auszulösen: exports['agency-notify']:Show({title, body, icon, level, duration, actions})Gibt eine ID zurück, mit der du die Benachrichtigung später aktualisieren oder ausblenden kannst. Das ist alles. Keine Framework-Abhängigkeit, keine magischen Globals.

Aus gutem Grund standalone

Agency-Notify ist ein frameworkunabhängiger Baustein. Deine QBCore-Scripts, ESX-Scripts und benutzerdefinierter standalone-Code rufen alle dieselbe API auf. So bleibt die visuelle Sprache deines Servers über Dutzende Scripts verschiedener Autoren hinweg einheitlich.

Installation & Einrichtung

Agency-Notify ist in weniger als zehn Minuten eingerichtet. Lade die Resource aus deiner Tebex-Bibliothek herunter, ziehe den agency-notify Ordner in das resources-Verzeichnis deines Servers und füge ensure agency-notify zu deiner server.cfghinzu. Die Resource benötigt keine Datenbank, der gesamte Benachrichtigungsstatus wird clientseitig im Arbeitsspeicher verwaltet.

Sobald die Resource läuft, kann jedes Script auf deinem Server sofort die Exports-API aufrufen. Um Benachrichtigungen auszulösen, ist nach der Installation keine weitere Konfiguration erforderlich, die Standardeinstellungen sind sofort einsatzbereit.

Konfigurationsoptionen

Öffne config.lua um die visuellen und funktionalen Standardeinstellungen anzupassen:

• Position, Verankerung oben rechts (Standard), oben links, unten rechts oder unten links.
• Maximal sichtbar, wie viele Benachrichtigungen gestapelt werden, bevor ältere ausgeblendet werden. Der Standardwert ist 5.
• Standarddauer, Millisekunden bis zum automatischen Ausblenden. Einzelne Benachrichtigungen können diesen Wert überschreiben.
• Animationsstil", slide-in-right (Standard), fade oder scale. Gilt global für alle Benachrichtigungen.
• Gruppierungszeitraum, Zeitfenster in Millisekunden, in dem identische Benachrichtigungen zusammengefasst werden.
• Sound aktiviert, schalte den dezenten Benachrichtigungston je nach Schweregrad ein oder aus.

Alle Einstellungen befinden sich in einer einzigen, flachen Config-Tabelle. Es gibt keine verschachtelten Strukturen, durch die du dich arbeiten musst, und keine getrennten Client- und Server-Konfigurationen.

Framework-Kompatibilität

Agency-Notify ist zu 100 % standalone. Es importiert keine Frameworks und hat weder eine QBCore- noch eine ESX-Abhängigkeit. Das bedeutet:

• Es funktioniert auf jedem FiveM-Server, unabhängig von deinem Basis-Framework.
• Ein späterer Wechsel des Frameworks macht deine Benachrichtigungsaufrufe nicht unbrauchbar.
• Jedes Script, unabhängig vom Autor, kann Benachrichtigungen über dieselbe API auslösen, ohne wissen zu müssen, welches Framework du verwendest.

Wenn du ein bestehendes Benachrichtigungssystem ersetzt (ox_libs notify, QBCores QBNotify usw.), musst du lediglich den Export-Aufruf in deinen Scripts aktualisieren. Die Signatur ähnelt gängigen Mustern genug, damit Suchen und Ersetzen die meisten Migrationen abdeckt.

Warum das für Roleplay wichtig ist

Benachrichtigungen sind der wichtigste Kommunikationskanal zwischen Serversystemen und Spielern. Wenn ein Drogendeal abgeschlossen wird, eine rivalisierende Gang dein Gebiet betritt oder ein Admin alle über ein Event informieren muss, läuft all das über Benachrichtigungen. Sieht dieser Kanal veraltet aus oder wird er ignoriert, gehen wichtige Servermitteilungen unbemerkt unter.

Spieler, die ihrem Benachrichtigungssystem vertrauen, achten darauf. Spieler, die eine überladene, hässliche Benachrichtigungsleiste auszublenden gelernt haben, verpassen wichtige Meldungen und fühlen sich nicht auf dem Laufenden. Das Gruppierungssystem von Agency-Notify löst gezielt das Spam-Problem: Löst dein Server während eines Heists schnell drei Benachrichtigungen aus, sehen die Spieler eine zusammengefasste Meldung statt drei Toasts, die um Aufmerksamkeit konkurrieren.

Die Schweregrade (success, warning, error, info) sorgen für eine zusätzliche Signalebene. Spieler lernen schnell: Grün bedeutet gut, Rot bedeutet sofort handeln. Diese Farborientierung verringert die kognitive Belastung in Situationen mit viel Action.

Häufig gestellte Fragen

Kann ich eine Benachrichtigung aktualisieren oder schließen, nachdem sie angezeigt wurde?

Ja. Der Show() Export gibt eine ID zurück. Übergebe diese ID an exports['agency-notify']:Update(id, {body, level}) um den Inhalt zu ändern, oder an exports['agency-notify']:Dismiss(id) um die Benachrichtigung vorzeitig zu entfernen. Das ist nützlich für Fortschrittsbenachrichtigungen, deren Status sich ändert, zum Beispiel „Wird verarbeitet…“ → „Fertig“.

Ersetzt das ox_lib-Benachrichtigungen?

Das ist möglich. Agency-Notify deckt dieselben Anwendungsfälle mit einem anderen visuellen Stil ab. Wenn du die Glassmorphism-Optik passend zu anderen Agency-Scripts möchtest, ist der Wechsel unkompliziert. Wenn dein Server stark in ox_lib integriert ist und dir dessen Look gefällt, kannst du ox_lib weiterhin für Benachrichtigungen verwenden. Es gibt keine Konflikte.

Können Spieler die Position ihrer Benachrichtigungen anpassen?

Nicht standardmäßig. Die Position wird serverseitig konfiguriert. Das ist Absicht: Serverbetreiber bestimmen die visuelle Sprache, nicht einzelne Spieler. Wenn du individuelle Einstellungen ermöglichen möchtest, musst du die Auswahl in einer Datenbank speichern und beim Beitritt über die Spielerdaten übergeben.

Gibt es ein Rate-Limit, um Benachrichtigungs-Spam durch Scripts zu verhindern?

Das Gruppierungssystem übernimmt die Deduplizierung automatisch. Für ein festes Rate-Limit setze Config.RateLimit = true und Config.RateLimitWindow = 1000 (ms) in config.lua. Damit begrenzt du, wie viele unterschiedliche Benachrichtigungen ein einzelnes Script innerhalb des Zeitfensters auslösen kann.

Voraussetzungen

• FiveM-Server (beliebiges Framework oder standalone)
• cfx.re-Konto mit einem gültigen Agency-Notify-Lizenzschlüssel in deinem Keymaster
• Keine Datenbankabhängigkeit
• Keine Abhängigkeiten von externen Resources

Agency-Notify im Vergleich zu Alternativen

Im FiveM-Benachrichtigungs-Ökosystem gibt es mehrere Optionen: ox_lib-Benachrichtigungen, die integrierten Benachrichtigungen von QBCore und verschiedene standalone Scripts. Hier erfährst du, wofür sich die einzelnen Optionen eignen:

ox_lib-Benachrichtigungen sind zuverlässig und werden gut gepflegt, sind stilistisch jedoch an die visuelle Sprache von ox_lib gebunden. Wenn dein Server bereits vollständig auf ox_lib setzt, kann die visuelle Einheitlichkeit wichtiger sein als ein Upgrade. Wenn du einen Stack aufbaust, der primär auf Agency setzt, passt die abgestimmte Optik von Agency-Notify besser.

QBCore-Notify von QBCore ist funktional, aber minimalistisch: keine Gruppierung, keine Update-API, keine Aktionsbuttons. Für grundlegende Anwendungsfälle reicht es aus und kostet nichts extra, wenn du bereits QBCore nutzt. Sobald du mehr als einfache Toast-Benachrichtigungen brauchst, bist du ihm entwachsen.

Agency-Notify richtet sich an Server, denen das Benachrichtigungserlebnis als Produktdetail wichtig ist und die es nicht als nachträglichen Einfall behandeln. Wenn du schon einmal gedacht hast: „Unsere Benachrichtigungen sehen schlecht aus und die Spieler ignorieren sie“, dann löst dieses Script genau dieses Problem.