Files

M_Viper dd183203cd README.md aktualisiert

2026-05-30 05:42:58 +00:00

65 KiB

Raw Blame History

StatusAPI – BungeeCord Plugin

Version: 4.1.5 · Autor: M_Viper · Plattform: BungeeCord · Minecraft: 1.20+

StatusAPI ist ein umfassendes BungeeCord-Plugin, das als zentrale Schaltstelle für dein Minecraft-Netzwerk dient. Es vereint Chat-Management, Anti-Bot-Schutz, Scoreboard, Tablist, Wirtschaft, Vanish, Forum-Anbindung, Spielerstatistiken, einen integrierten HTTP-Server und vieles mehr in einem vollständig modularen Plugin.

Inhaltsverzeichnis

Voraussetzungen
Installation
Konfigurationsdateien im Überblick
Module
HTTP-API
Globales Rate-Limit-Framework
Update-Checker
Befehle & Permissions – Komplette Referenz
LuckPerms Integration
Geyser / Bedrock Support
StatusAPIBridge (Backend-Integration)
Debug-Modus
Emoji-Liste
Häufige Fragen & Fehlerbehebung

1. Voraussetzungen

Anforderung	Details
BungeeCord	Aktuell, Minecraft 1.20+ kompatibel
Java	21 oder höher
LuckPerms	Empfohlen (Soft-Dependency) – für Prefix/Suffix im Chat, Scoreboard und Tablist
Geyser-BungeeCord	Optional (Soft-Dependency) – für Bedrock-Spieler-Unterstützung
MySQL/MariaDB	Nur für das EconomyModule erforderlich

2. Installation

Die fertige StatusAPI.jar in den /plugins-Ordner deines BungeeCord-Servers legen.
BungeeCord (neu) starten.
Beim ersten Start werden alle Konfigurationsdateien im Verzeichnis /plugins/StatusAPI/ automatisch erstellt.
Den Server stoppen, die Konfigurationsdateien anpassen (siehe Abschnitt 3) und anschließend neu starten.
Für einen Teilreload von Scoreboard und Tablist kann /statusapi reload genutzt werden, ohne den Server neu starten zu müssen.

Hinweis Economy: Das EconomyModule benötigt eine laufende MySQL-Datenbank. Die Verbindungsdaten müssen in verify.properties eingetragen sein, bevor der Server startet. Die Tabelle bc_accounts wird beim ersten Start automatisch erstellt.

Hinweis Paper-Backend: Damit der Chat-Proxy korrekt funktioniert, muss auf jedem Paper-Backend-Server in der paper-global.yml folgendes gesetzt sein:
messages:
  reject-chat-unsigned: false

3. Konfigurationsdateien im Überblick

Alle Konfigurationsdateien befinden sich unter /plugins/StatusAPI/ und werden beim ersten Start automatisch erstellt.

Datei	Zuständig für
`verify.properties`	Hauptkonfiguration – Port, Server-Definitionen, WordPress/Forum-Anbindung, Economy-Datenbank, AutoMessage, CommandBlocker, Broadcast, BackendGuard, HelpModule
`chat.yml`	Alle Chat-Einstellungen: Kanäle, Filter, Private Nachrichten, Discord/Telegram-Bridge, Emoji, Rate-Limit, Mute, Reports, Join/Leave-Nachrichten, Mentions
`filter.yml`	Zusätzliche Wort-Blacklist für den Chat-Filter (ergänzt `chat.yml`, beide Listen werden zusammengeführt)
`scoreboard.properties`	Scoreboard-Layout, Zeilen, Platzhalter, Animationen, Regenbogen, News-Ticker
`network-guard.properties`	AntiBot, MultiAccountGuard, NetworkInfo, BackendGuard-Sync
`welcome.yml`	Zufällige Willkommensnachrichten beim Einloggen
`messages.txt`	AutoMessage-Texte (eine Nachricht pro Zeile, `§`-Farbcodes werden unterstützt)
`blocked-commands.yml`	Liste der vom CommandBlocker gesperrten Befehle
`customcommands.yml`	Eigene Proxy-Befehle (wird beim ersten Start erstellt)
`tablist.properties`	Tablist-Layout, Header/Footer, Spalten, Server-Symbole (wird beim ersten Start erstellt)
`serverswitcher.properties`	Konfiguration des ServerSwitchers – Befehl, Farben, Whitelist
`afk.properties`	AFK-Modul – Timeout, Title-Nachrichten-Paare, Animationen
`broadcasts.schedules`	Interne Datei – gespeicherte, geplante Broadcasts (wird automatisch verwaltet)
`antibot-security.log`	Sicherheitslog des AntiBotModuls – geblockte IPs, VPN/Proxy-Treffer
`mutes.dat`	Persistente Speicherung aktiver Mutes (automatisch)
`blocks.dat`	Persistente Speicherung von Spieler-Ignores (automatisch)
`reports.dat`	Offene Reports (automatisch)
`accounts.dat`	Discord/Telegram-Verknüpfungen (automatisch)
`forum-notifs.dat`	Ausstehende Forum-Benachrichtigungen (automatisch)
`stats/`	Ordner mit Spielerstatistiken (eine Datei pro Spieler, automatisch)

4. Module

4.1 ChatModule

Das ChatModule ist das Herzstück der Netzwerkkommunikation. Es übernimmt vollständig die Steuerung des gesamten Proxy-Chats und bietet ein umfangreiches Featureset:

Kanalsystem

Spieler können zwischen konfigurierbaren Chat-Kanälen wechseln. Standardmäßig vorkonfiguriert:

Kanal	Symbol	Sichtbarkeit	Permission
`global`	G	Netzwerkweit	– (kein Login erforderlich)
`local`	L	Nur aktueller Server	`chat.channel.local`
`trade`	T	Netzwerkweit	`chat.channel.trade`
`staff`	S	Netzwerkweit	`chat.channel.staff`

Jeder Kanal wird in chat.yml definiert und unterstützt:

Eigenes Chat-Format mit Platzhaltern: {server}, {prefix}, {player}, {suffix}, {message}, {channel}
Eigene Farbe und Symbol
local-only: true für server-lokale Sichtbarkeit
Discord-Webhook-URL für diesen Kanal
Discord-Channel-ID (für Bot-Integration)
Telegram-Chat-ID und optionale telegram-thread-id (Themen-Gruppen)
use-admin-bridge: true für automatische Weiterleitung an den Admin-Kanal

Server-Farben sind ebenfalls pro Server in chat.yml unter server-colors: konfigurierbar – sowohl mit &-Codes als auch mit Hex-Farben (&#RRGGBB).

Private Nachrichten

Spieler können sich über /msg private Nachrichten schicken und mit /r auf die letzte Nachricht antworten. Der Absender und Empfänger sehen jeweils eigene, konfigurierbare Formate. Social Spy erlaubt Admins mit der Permission chat.socialspy, alle privaten Nachrichten mitzulesen.

Spieler-Ignore (Blocking)

Spieler können andere Spieler mit /ignore blockieren. Geblockte Spieler können keine Nachrichten, PMs oder HelpOps an den Blocker senden. Der Blockstatus wird persistent in blocks.dat gespeichert und überlebt Serverneustarts.

Mute-System

Admins mit der Permission chat.mute können Spieler mit /chatmute <Spieler> [Minuten] stummschalten. Ein Mute ohne Minutenangabe nutzt die konfigurierte Standard-Dauer. Gemutete Spieler können weder im Chat schreiben noch Private Nachrichten senden. Mutes werden persistent in mutes.dat gespeichert. Spieler mit chat.admin.bypass können nicht gemutet werden.

Selbst-Stummschaltung

Spieler können ihren eigenen Chat-Empfang mit /chataus ein- und ausschalten, ohne andere zu beeinflussen.

Chat-Filter

Der Chat-Filter schützt vor verschiedenen Arten von unerwünschtem Inhalt:

Anti-Spam: Begrenzt Nachrichten in einem Zeitfenster; konfigurierbare Anzahl, Fensterbreite und Blockdauer
Duplikat-Check: Verhindert das Senden identischer Nachrichten direkt hintereinander
Wort-Blacklist: Wörter aus chat.yml (Sektion blacklist) und filter.yml werden zusammengeführt und case-insensitiv als Teilwort geprüft; Treffer werden durch **** ersetzt
Caps-Filter: Blockiert Nachrichten, die eine konfigurierbare Mindestlänge haben und einen zu hohen Großbuchstaben-Anteil aufweisen
Anti-Werbung: Erkennt Domain-Links über eine TLD-Liste und blockiert diese; Domains auf der Whitelist (z. B. die eigene Server-Adresse) werden ausgenommen. Die blockierten TLDs sind frei konfigurierbar.

Spieler mit der Permission chat.filter.bypass sind von allen Filtern ausgenommen.

Emoji-Unterstützung

Spieler können Emoji-Kürzel wie :smile:, :fire: oder :crown: im Chat verwenden. Diese werden automatisch in Unicode-Zeichen umgewandelt. Bedrock-Spieler erhalten bei Bedarf einen Fallback-Text. Alle Emojis und ihre Zuordnungen sind in chat.yml unter emoji.mappings vollständig anpassbar. Standard-Emojis sind bereits vorkonfiguriert (über 35 Stück).

Mentions (@Spielername)

Spieler können andere im Chat mit @Spielername erwähnen. Der erwähnte Spieler erhält eine hervorgehobene Nachricht (konfigurierbare Farbe) und einen Ton (ENTITY_EXPERIENCE_ORB_PICKUP oder eigener). Mentions können von jedem Spieler individuell über /mentions deaktiviert werden. Highlight-Farbe, Ton und Toggle-Funktion sind in chat.yml konfigurierbar.

HelpOp

Spieler können mit /helpop <Nachricht> eine Hilfeanfrage an das Team senden. Spieler mit der Permission chat.helpop.receive erhalten diese Anfragen im Spiel. Ein konfigurierbarer Cooldown verhindert Spam. HelpOp-Nachrichten können optional auch an Discord und Telegram weitergeleitet werden.

Report-System

Spieler können andere Spieler mit /report <Spieler> <Grund> melden. Das System speichert den Grund, den letzten Chatverlauf des gemeldeten Spielers und eine Report-ID. Admins können offene Reports mit /reports [all] einsehen und mit /reportclose <ID> schließen. Ein konfigurierbarer Cooldown verhindert Spam. Neue Reports können optional per Discord-Webhook und/oder Telegram-Chat-ID gemeldet werden. Reports werden persistent in reports.dat gespeichert.

Chat-Log

Alle Chat-Nachrichten werden optional in tageweise aufgeteilte Log-Dateien geschrieben. Die Aufbewahrungsdauer ist konfigurierbar (Standard: 7 Tage). Admins können den Log über /chathist [Spieler] [Anzahl] direkt im Spiel einsehen.

Nachrichten-IDs

Jede Chat-Nachricht erhält eine klickbare ID (sichtbar für Admins). Ein Klick kopiert die ID in die Zwischenablage (nützlich für Reports und Moderation).

Discord-Bridge

Der Chat kann bidirektional mit Discord verbunden werden. Voraussetzung ist ein Discord-Bot-Token und die Guild-ID. Nachrichten werden per Polling vom Discord-Bot empfangen (konfigurierbares Intervall). Jeder Kanal, HelpOp und Join/Leave-Meldungen können an separate Discord-Webhooks oder Channels geleitet werden. Spieler können ihren Minecraft-Account über /discordlink mit Discord verknüpfen, sodass ihr Minecraft-Name im Discord-Chat erscheint. Ein separater Admin-Channel-ID für Staff-Kanal und HelpOp ist konfigurierbar.

Telegram-Bridge

Analog zur Discord-Bridge kann der Chat mit Telegram verbunden werden. Unterstützt werden reguläre Gruppen sowie Themen-Gruppen (mit telegram-thread-id pro Kanal). Spieler können ihren Account über /telegramlink verknüpfen. Sowohl ein normaler Admin-Chat als auch ein optionales Thema dafür (admin-topic-id) sind konfigurierbar.

Account-Verknüpfung

Spieler erhalten nach /discordlink oder /telegramlink einen temporären Token (Standard: 10 Minuten gültig), den sie dem jeweiligen Bot senden. Nach erfolgreicher Verknüpfung wird im Spiel und im Chat eine Bestätigung angezeigt. Mit /unlink <discord|telegram|all> kann die Verknüpfung jederzeit aufgehoben werden. Verknüpfungen werden persistent in accounts.dat gespeichert.

Join/Leave-Nachrichten

Join- und Leave-Nachrichten beim Betreten oder Verlassen des Netzwerks sind vollständig anpassbar, inklusive LuckPerms-Platzhaltern ({prefix}, {suffix}). Vanished Spieler erzeugen keine normalen Join/Leave-Meldungen. Admins sehen optional eine dezente Admin-Meldung für vanished Spieler. Auch Join/Leave-Nachrichten können an Discord und Telegram weitergeleitet werden.

Secure Chat Kompatibilität

Das ChatModule ist mit dem BungeeCord Secure Chat (1.19+) kompatibel. Nachrichten werden so verarbeitet, dass Paper-Backend-Server sie akzeptieren (erfordert reject-chat-unsigned: false in der Paper-Konfiguration).

ChatBypass

Mit /chatbypass kann ein Spieler das ChatModule für die nächste Eingabe überspringen. Dies ist für externe Plugin-Dialoge (z. B. CMI-Dialoge) gedacht, die direkt mit dem Backend kommunizieren.

Wichtige Einstellungen in chat.yml (Auszug):

default-channel: "global"
chatlog:
  enabled: true
  retention-days: 7
rate-limit:
  chat:
    enabled: true
    window-ms: 2500
    max-actions: 3
    block-ms: 6000
  private-messages:
    enabled: true
    window-ms: 5000
    max-actions: 4
    block-ms: 10000
mute:
  default-duration-minutes: 60
discord:
  enabled: false
  bot-token: "YOUR_BOT_TOKEN_HERE"
  guild-id: "YOUR_GUILD_ID"
  poll-interval: 3
telegram:
  enabled: false
  bot-token: "YOUR_TELEGRAM_BOT_TOKEN"
  poll-interval: 3
account-linking:
  enabled: true
  token-expire-minutes: 10

4.2 ScoreboardModule

Das ScoreboardModule zeigt jedem Spieler eine individualisierte Sidebar (Scoreboard) an. Es gibt drei automatisch zugewiesene Ansichten:

Ansicht	Voraussetzung	Titel-Standard
Spieler	Standard für alle	`&lViper Network`
Supporter	Permission `statusapi.scoreboard.supporter`	`&l[Support] Panel`
Admin	Permission `statusapi.scoreboard.admin`	`&l[Admin] Panel`

Spieler können das Scoreboard mit /scoreboard hide ausblenden, mit /scoreboard show wieder einblenden und mit /scoreboard player oder /scoreboard admin die Ansicht manuell überschreiben.

Zeilen-Konfiguration

Bis zu 15 Zeilen sind möglich. Jede Zeile kann mehrere Varianten haben, zwischen denen automatisch rotiert wird:

scoreboard.lines.5=&7Spielzeit: &f%playtime%
scoreboard.lines.5.2=&7Leben: &c%health%
scoreboard.lines.5.3=&7Hunger: &#8B4513%foodsym%

Der Rotationsintervall wird über scoreboard.rotation_interval (Sekunden) gesteuert.

Platzhalter – Spieler-Scoreboard:

Platzhalter	Beschreibung
`%player%`	Spielername
`%rank%`	LuckPerms-Prefix
`%money%`	Kontostand (formatiert)
`%server%`	Aktueller Server
`%compass%`	Himmelsrichtung (via StatusAPIBridge)
`%health%`	Aktuelle Leben (via StatusAPIBridge)
`%hearts%`	Leben als Herz-Symbole
`%ping%`	Ping in ms
`%online%`	Anzahl online Spieler
`%maxplayers%`	Maximale Spielerzahl
`%time%`	Aktuelle Uhrzeit (konfigurierbare Zeitzone & Format)
`%date%`	Aktuelles Datum
`%playtime%`	Gesamte Spielzeit des Spielers
`%x%` / `%y%` / `%z%`	Koordinaten (via StatusAPIBridge)
`%world%`	Aktuelle Welt (via StatusAPIBridge)
`%gamemode%`	Spielmodus (via StatusAPIBridge)
`%exp%`	Erfahrungslevel (via StatusAPIBridge)
`%food%`	Hunger-Level (via StatusAPIBridge)
`%foodsym%`	Hunger als Symbole
`%speed%`	Laufgeschwindigkeit (via StatusAPIBridge)
`%news%`	Laufender News-Ticker
`%line%`	Konfigurierbare Trennlinie

Zusätzliche Platzhalter – Admin-Scoreboard:

Platzhalter	Beschreibung
`%tps%`	TPS des Backend-Servers (via StatusAPIBridge)
`%ram%`	RAM-Auslastung des Proxys
`%proxymem%`	Proxy-Speicher
`%uptime%`	Proxy-Laufzeit
`%servers%`	Anzahl verbundener Server

Ticket-Platzhalter (Supporter/Admin):

Platzhalter	Beschreibung
`%ticket_my_open%`	Eigene offene Tickets (Spieler)
`%ticket_open%`	Alle offenen Tickets gesamt
`%ticket_claimed%`	Alle Tickets in Bearbeitung
`%ticket_rating_good%`	Positive Ticket-Bewertungen
`%ticket_rating_bad%`	Negative Ticket-Bewertungen
`%ticket_rating_pct%`	Bewertungs-Prozentwert

Gradient-Unterstützung

Texte können Farbverläufe nutzen: %gradient:FARBE1:FARBE2:TEXT%. Als Farben sind Hex-Werte (#FF6600 oder &#FF6600) und Minecraft-Codes (&a) möglich. Es können beliebig viele Farb-Stopps angegeben werden.

scoreboard.lines.2=%gradient:&b:&f:&b:&l> Player Info:%

Regenbogen-Animation

Der Scoreboard-Titel kann animiert werden. Drei Modi stehen zur Verfügung:

wave – Fließende Farbwelle über den Text
chars – Jeder Buchstabe bekommt eine eigene Regenbogenfarbe
line – Einheitliche Farbe wechselt

Geschwindigkeit und Farben sind frei konfigurierbar. Ohne eigene Farben wird der volle HSB-Regenbogen genutzt.

News-Ticker

Der Platzhalter %news% zeigt einen laufenden Text an. Text, Prefix, Breite und Geschwindigkeit werden in scoreboard.properties unter scoreboard.news.* eingestellt.

Laufschrift (Ticker)

Ein weiterer animierter Text kann über scoreboard.ticker.text konfiguriert werden. Dieser läuft als eigenständiger Ticker und kann ebenfalls im Scoreboard platziert werden.

PlaceholderAPI-Unterstützung

Das Scoreboard erkennt automatisch alle %token%-Platzhalter in .properties-Dateien, die nicht nativ unterstützt werden, und leitet diese an die StatusAPIBridge weiter, die sie über PlaceholderAPI auf dem Backend-Server auflöst. Die erkannten Token werden über GET /papi/tokens der Bridge bereitgestellt.

Wichtige Einstellungen in scoreboard.properties (Auszug):

scoreboard.enabled=true
scoreboard.update_interval=500
scoreboard.rotation_interval=4
scoreboard.timezone=Europe/Berlin
scoreboard.money_format=#,##0.00
scoreboard.rainbow.enabled=true
scoreboard.rainbow.mode=wave
scoreboard.rainbow.speed=10
scoreboard.admin_permission=statusapi.scoreboard.admin
scoreboard.supporter_permission=statusapi.scoreboard.supporter

4.3 TablistModule

Das TablistModule gestaltet die Tab-Liste (Spielerliste) des Netzwerks vollständig.

Layout-Modi

compact – Kompakte Darstellung mit Header und Footer als kurzer Text
Erweiterter Modus – Mehrzeiliger Header/Footer mit bis zu drei Zeilen

Spalten-Header-Modi

none – Kein Spalten-Header (Standard, empfohlen für die meisten Setups)
full – Großer Spalten-Header über jeder Spalte
small – Spaltenname erscheint nur im Tab-Header/Footer

Spieler-Anzeige-Modi

server – Spieler werden nach Server gruppiert (Standard)
custom – Alle Spieler zusammen, sortiert von links nach rechts nach Rang

Server-Symbole

Neben jedem Spielernamen kann ein farbiges Server-Symbol erscheinen, das dem aktuellen Server des Spielers entspricht. Symbole werden in tablist.properties konfiguriert.

Skin-Cache

Spieler-Skins werden gecacht und für die Tab-Liste verwendet. Platzhalter-Slots (leere Slots) erhalten einen grauen Standardkopf.

Tab-Größe

Die Tab-Liste unterstützt bis zu 180 Slots (9 Spalten à 20 Zeilen). Die Größe muss in der BungeeCord config.yml unter tab-list-size entsprechend gesetzt sein.

Wichtig: BungeeCord config.yml – tab-list-size muss auf den konfigurierten Wert gesetzt werden, sonst werden nicht alle Spalten angezeigt. Das Plugin gibt beim Start eine Warnung aus, falls der Wert nicht übereinstimmt.

Header und Footer

Im kompakten Modus werden Header und Footer aus tablist.properties über eigene Felder konfiguriert. Im erweiterten Modus stehen drei Zeilen für Header und Footer zur Verfügung. Alle Zeilen unterstützen Farbcodes und Platzhalter wie %online%.

4.4 AntiBotModule

Das AntiBotModule schützt das Netzwerk vor automatisierten Bot-Angriffen (Verbindungs-Floods). Es überwacht die Verbindungsrate in Echtzeit.

Profile

In network-guard.properties kann über antibot.profile eines von zwei Profilen gewählt werden. Die Profil-Werte sind Referenzwerte; einzelne Parameter darunter überschreiben das Profil bei Bedarf.

Profil	Empfohlen für	Besonderheiten
`strict`	Kleine Server	max_cps=120, start_cps=220, stop_cps=120, VPN-Check aktiv, block_seconds=900
`high-traffic`	Große Netzwerke	max_cps=180, start_cps=300, stop_cps=170, VPN-Check deaktiviert, block_seconds=600

Lernmodus (adaptives Scoring)

Der Lernmodus ist ein zentrales Feature: Statt sofort zu blockieren, vergibt das System Punkte für verdächtige Muster. Erst wenn ein konfigurierbarer Schwellenwert überschritten wird, blockiert das Modul die Verbindung. Punkte nehmen mit der Zeit ab (Decay).

Ereignis	Standard-Punkte
Sehr schnelle Verbindungsfolge (Rapid)	12
IP-Rate überschritten	30
VPN/Proxy erkannt	40
Hosting-Provider erkannt	30
Angriffsmodus aktiv	12
Hohe CPS	10

VPN/Proxy-Check

Optional kann über den Dienst ip-api.com geprüft werden, ob eine Verbindung von einem VPN, Proxy oder Hosting-Anbieter kommt. Erkannte IPs werden gecacht (Standard: 30 Minuten), um API-Anfragen zu reduzieren. VPN- und Hosting-Blockierung können unabhängig voneinander aktiviert werden.

Pro-IP-Limiter

Jede IP-Adresse kann in einem konfigurierbaren Zeitfenster nur eine bestimmte Anzahl von Verbindungen aufbauen. Bei Überschreitung wird die IP für eine konfigurierbare Dauer geblockt.

Sicherheitslog

Alle sicherheitsrelevanten Ereignisse (geblockte IPs, VPN/Proxy-Treffer, Lernmodus-Blockierungen) werden optional in antibot-security.log gespeichert und sind über GET /antibot/security-log der HTTP-API abrufbar.

Admin-Befehl /antibot:

/antibot status                – Aktuellen AntiBot-Status anzeigen
/antibot clearblocks           – Alle blockierten IPs entsperren
/antibot unblock <IP>          – Eine einzelne IP entsperren
/antibot profile <strict|high-traffic> – Profil wechseln
/antibot reload                – Konfiguration neu laden

Vollständige Konfiguration in network-guard.properties:

antibot.enabled=true
antibot.profile=high-traffic
antibot.max_cps=180
antibot.attack.start_cps=300
antibot.attack.stop_cps=170
antibot.attack.stop_grace_seconds=25
antibot.ip.max_connections_per_minute=24
antibot.ip.block_seconds=600
antibot.kick_message=Zu viele Verbindungen von deiner IP. Bitte warte kurz.
antibot.vpn_check.enabled=false
antibot.vpn_check.block_proxy=true
antibot.vpn_check.block_hosting=true
antibot.vpn_check.cache_minutes=30
antibot.vpn_check.timeout_ms=2500
antibot.security_log.enabled=true
antibot.security_log.file=antibot-security.log
antibot.learning.enabled=true
antibot.learning.score_threshold=100
antibot.learning.decay_per_second=2
antibot.learning.state_window_seconds=120

4.5 MultiAccountGuard

Der MultiAccountGuard verhindert, dass ein Spieler gleichzeitig mit mehreren Accounts online ist.

Prüfmethoden (unabhängig aktivierbar):

IP-Check: Gleiche IP mit unterschiedlichem Namen wird erkannt und blockiert
UUID-Check: Gleiche UUID mit unterschiedlichem Namen wird erkannt (relevant für Bedrock-Edge-Cases über Geyser)

Konfliktverhalten:

multiaccountguard.kick_existing=false (Standard): Der neue Verbindungsversuch wird abgelehnt, der bereits eingeloggte Account bleibt.
multiaccountguard.kick_existing=true: Der bestehende Account wird rausgeworfen, der neue verbindet sich.

Temporärer IP-Bann:

Nach einer konfigurierbaren Anzahl von Konflikten (Standard: 3) wird die IP temporär gebannt (Standard: 5 Minuten). Dies funktioniert in Verbindung mit dem AntiBotModule.

Staff-Benachrichtigung:

Spieler mit der Permission statusapi.staff.notify erhalten bei jedem Konflikt eine Ingame-Meldung mit dem Namen des blockierten Spielers, dem bestehenden Account und der IP.

Discord-Webhook:

Jeder Konflikt kann optional per Discord-Webhook gemeldet werden. Der Webhook aus networkinfo.webhook.url wird automatisch verwendet.

Bypass-Permission:

Die Permission statusapi.multiaccountguard.bypass hat keinen Default-Wert und muss explizit vergeben werden:
lp user <Spielername> permission set statusapi.multiaccountguard.bypass true

Vollständige Konfiguration in network-guard.properties:

multiaccountguard.enabled=true
multiaccountguard.check_ip=true
multiaccountguard.check_uuid=true
multiaccountguard.kick_existing=false
multiaccountguard.kick_message=&cDu bist bereits mit einem anderen Account online!\n&7Bitte trenne deinen anderen Account zuerst.
multiaccountguard.staff_notify.enabled=true
multiaccountguard.staff_notify.format=&8[&cMAG&8] &e{blocked} &7wurde blockiert &8(2. Account von &e{existing}&8) &7| IP: &f{ip}
multiaccountguard.tempban.enabled=true
multiaccountguard.tempban.max_attempts=3
multiaccountguard.tempban.duration_secs=300
multiaccountguard.webhook.enabled=true

4.6 NetworkInfoModule

Das NetworkInfoModule überwacht den Proxy in Echtzeit und stellt Systemdaten bereit.

Funktionen:

Echtzeit-Netzwerkstatus-Endpunkt (integriert in den HTTP-Status-Endpoint GET /)
Befehl /netinfo für detaillierte Proxy- und Systeminfos (Permission: statusapi.netinfo)
Discord-Webhook-Benachrichtigungen bei Serverstart/-stop, Speicher-Warnungen, TPS-Abfall und Angriffen

Embed-Modi für Discord-Webhooks:

compact – Kurze Textnachrichten
detailed – Strukturierte Embeds mit Feldern

Alert-Schwellwerte:

Einstellung	Bedeutung
`networkinfo.alert.memory_percent=90`	Warnung ab 90% RAM-Auslastung
`networkinfo.alert.player_percent=95`	Warnung ab 95% der maximalen Spielerzahl
`networkinfo.alert.tps_threshold=18.0`	Warnung wenn Proxy-TPS unter 18 fallen
`networkinfo.alert.cooldown_seconds=300`	Mindestabstand zwischen Warnungen (5 Min.)

Angriffs-Benachrichtigungen:

Das NetworkInfoModule kann Angriffs-Meldungen vom AntiBotModule entgegennehmen und über Discord weiterleiten. Absender-Quelle und API-Key für den POST /network/attack-Endpunkt sind konfigurierbar.

BackendGuard-Sync:

Das NetworkInfoModule liefert über GET /network/backendguard/config die BackendGuard-Konfiguration (erlaubte Proxy-IPs und CIDRs) an Backend-Server. Diese nutzen die Konfiguration, um direkte Verbindungen zu blockieren, die nicht über den Proxy laufen. Optional kann ein API-Key für diesen Endpunkt vergeben werden.

networkinfo.enabled=true
networkinfo.command.enabled=true
networkinfo.include_player_names=false
networkinfo.webhook.enabled=false
networkinfo.webhook.url=
networkinfo.webhook.embed_mode=detailed
networkinfo.webhook.check_seconds=30
networkinfo.attack.enabled=true
networkinfo.attack.api_key=
backendguard.enforcement_enabled=true
backendguard.allowed_proxy_ips=127.0.0.1,::1
backendguard.allowed_proxy_cidrs=10.0.0.0/24
backendguard.sync.api_key=

4.7 VanishModule

Das VanishModule erlaubt Admins, sich unsichtbar zu machen.

Effekte eines vanished Spielers:

Erscheint nicht in der Tab-Liste für normale Spieler
Erzeugt keine normalen Join/Leave-Nachrichten
Ist für normale Spieler nicht sichtbar
Wird in /vanishlist aufgeführt

Admin-Sichtbarkeit: Admins mit der Bypass-Permission (chat.admin.bypass) sehen vanished Spieler in der Tab-Liste und erhalten eine dezente Ingame-Meldung (konfigurierbar mit vanish-show-to-admins: true in chat.yml).

/vanish [Spieler]   – Vanish für sich selbst oder einen anderen Spieler ein-/ausschalten
/vanishlist          – Alle aktuell unsichtbaren Spieler anzeigen

4.8 VerifyModule

Das VerifyModule ermöglicht die Verknüpfung von Minecraft-Accounts mit einem WordPress-Forum (WP Business Forum Plugin).

Ablauf:

Spieler betritt einen Server.
Das Plugin generiert einen signierten Token (HMAC-SHA256) für den Server.
Spieler gibt /verify <token> auf der Webseite ein.
Das Plugin sendet den Token an die WordPress-Instanz zur Verifikation.

Multi-Server-Support: Jeder Server kann eine eigene ID und ein eigenes Secret haben. Die Verknüpfung erfolgt server-spezifisch.

Konfiguration in verify.properties:

wp_verify_url=https://deine-seite.de
forum.api_secret=SICHERES_PASSWORT

# Pro Server: Name, ID und Secret
server.Lobby=&bLobby
server.Lobby.id=64
server.Lobby.secret=GeheimesWortFuerLobby789

server.survival=&aSurvival
server.survival.id=68
server.survival.secret=GeheimesWortFuerSurvival789

Servernamen werden case-insensitiv verglichen.

4.9 ForumBridgeModule

Das ForumBridgeModule verbindet das WP Business Forum mit dem Minecraft-Netzwerk.

Funktionen:

Forum-Benachrichtigungen werden ingame angezeigt (klickbar mit Hover-Text und Link zum Forum-Beitrag)
Ausstehende Benachrichtigungen werden persistent in forum-notifs.dat gespeichert
Beim Login werden ausstehende Benachrichtigungen nach einer konfigurierbaren Verzögerung zugestellt (forum.login_delay_seconds)
Veraltete Benachrichtigungen werden automatisch nach 30 Tagen bereinigt
Spieler können ihren Forum-Account über /forumlink <token> mit ihrem Minecraft-Account verknüpfen
Alle ausstehenden Benachrichtigungen werden mit /forum angezeigt

Ablauf einer Forum-Benachrichtigung:

Das WordPress-Forum sendet einen POST /forum/notify an die StatusAPI-HTTP-API mit einem API-Key und den Benachrichtigungsdaten (Spielername, Typ, Beitragstitel, URL).
StatusAPI prüft den API-Key und stellt die Benachrichtigung dem Spieler zu – direkt, wenn er online ist, oder beim nächsten Login.

Konfiguration in verify.properties:

forum.enabled=true
wp_verify_url=https://deine-seite.de
forum.api_secret=SICHERES_PASSWORT
forum.login_delay_seconds=3

4.10 BroadcastModule

Das BroadcastModule ermöglicht das Senden von Nachrichten an alle Spieler im Netzwerk.

Ingame-Befehl:

/broadcast <Nachricht>   – Netzwerkweiten Broadcast senden (Permission: chat.broadcast)
/bc <Nachricht>          – Alias
/alert <Nachricht>       – Alias

Über die HTTP-API (POST /broadcast):

Das Broadcast-System ist vollständig über die HTTP-API steuerbar. Unterstützte Parameter:

Parameter	Beschreibung
`message`	Die Nachricht (Pflicht, außer bei `scheduleTime`)
`type`	Broadcast-Typ (z. B. `global`)
`prefix`	Optionaler eigener Prefix (überschreibt Konfiguration)
`prefixColor`	Prefix-Farbe
`bracketColor`	Klammer-Farbe
`messageColor`	Nachrichten-Farbe
`source`	Absendername (Standard: `PulseCast`)
`scheduleTime`	Unix-Timestamp (Sekunden oder Millisekunden) für geplante Broadcasts
`recur`	Wiederholungsintervall (`none`, `hourly`, `daily`, etc.)
`clientScheduleId`	Eindeutige ID für diesen Broadcast (für Stornierung nötig)

Geplante Broadcasts:

Broadcasts können für einen zukünftigen Zeitpunkt geplant und optional wiederholt werden. Mit POST /broadcast/cancel und der clientScheduleId können sie storniert werden. Geplante Broadcasts überleben Serverneustarts (gespeichert in broadcasts.schedules).

URLs in Broadcasts:

HTTP/HTTPS-URLs in Broadcast-Nachrichten werden automatisch als anklickbare TextComponents eingebettet.

API-Key-Schutz:

Der Broadcast-Endpunkt kann optional mit einem API-Key geschützt werden (broadcast.api_key in verify.properties).

Konfiguration in verify.properties:

broadcast.enabled=true
broadcast.prefix=[Broadcast]
broadcast.prefix-color=&c
broadcast.message-color=&f
broadcast.format=%prefixColored% %messageColored%
# broadcast.api_key=GEHEIMER_API_KEY

4.11 AutoMessageModule

Das AutoMessageModule sendet automatisch Nachrichten in regelmäßigen Abständen an alle Spieler. Nachrichten werden aus der Datei messages.txt zufällig ausgewählt.

Format der messages.txt: Eine Nachricht pro Zeile. Minecraft-Farbcodes mit § werden unterstützt.

Konfiguration in verify.properties:

automessage.enabled=true
automessage.interval=300        # Intervall in Sekunden (Standard: 5 Minuten)
automessage.prefix=             # Optionaler Prefix vor jeder Nachricht (leer = deaktiviert)
automessage.file=messages.txt

/automessage reload   – Konfiguration und Nachrichtendatei neu laden (Permission: statusapi.automessage)

4.12 CommandBlockerModule

Das CommandBlockerModule blockiert die Ausführung bestimmter Befehle auf dem Proxy. Blockierte Befehle werden in blocked-commands.yml definiert.

Zusätzliches Command-Rate-Limit:

Der CommandBlocker enthält ein eigenes Rate-Limit für Befehle (unabhängig vom globalen Chat-Rate-Limit), das Befehl-Spam verhindert.

Einstellung	Standard
Zeitfenster	3.000 ms
Max. Befehle im Fenster	8
Blockdauer bei Überschreitung	6.000 ms

Verwaltungsbefehl /cb:

/cb list               – Alle blockierten Befehle anzeigen (Permission: commandblocker.admin)
/cb add <befehl>       – Befehl blockieren
/cb remove <befehl>    – Befehl entsperren
/cb reload             – Konfiguration neu laden

Konfiguration in verify.properties:

commandblocker.enabled=true
commandblocker.bypass.permission=commandblocker.bypass

4.13 ServerSwitcherModule

Das ServerSwitcherModule ermöglicht Spielern einen schnellen Serverwechsel über ein interaktives Chat-Menü oder direkt per Befehl.

Chat-Menü: /go ohne Argument öffnet ein klickbares Chat-Menü, das alle verfügbaren Server mit Status (online/offline/aktuell) anzeigt. Server können per Klick betreten werden.

Direktwechsel: /go <servername> wechselt direkt zum angegebenen Server.

Tab-Completion: Servernamen werden im Tab-Complete vorgeschlagen.

Server-Whitelist: Optional kann eine Whitelist in serverswitcher.properties definiert werden, sodass nur bestimmte Server im Menü erscheinen.

Vollständige Konfiguration in serverswitcher.properties:

serverswitcher.enabled=true
serverswitcher.permission=serverswitcher.use
serverswitcher.command=go
serverswitcher.aliases=wechsel,switch
# Optionale Whitelist (leer = alle Server anzeigen):
# serverswitcher.whitelist=lobby,survival,skyblock
serverswitcher.color.header=&8&m---&r &6&lServer-Menü &8&m---
serverswitcher.color.entry=&7>> &e
serverswitcher.color.online=&a
serverswitcher.color.offline=&c
serverswitcher.color.self=&7(Aktuell)

4.14 EconomyModule

Das EconomyModule stellt eine netzwerkweite Währung bereit, die über alle Server synchronisiert ist.

Datenbankanbindung: Kontostände werden in einer MySQL-Datenbank (Tabelle bc_accounts) gespeichert. Die Tabelle wird automatisch erstellt.

Zusammenspiel mit NexEco: Das EconomyModule auf dem Proxy teilt die Datenbank mit dem Spigot-seitigen Plugin NexEco. Die eigentliche Wirtschaftslogik (Transaktionen, /pay, /ecoadmin) läuft auf den Spigot-Servern. Der Proxy synchronisiert Kontostände für Scoreboard und Tablist.

HTTP-API-Integration: Balance-Updates werden über POST /economy/update vom Backend (via StatusAPIBridge) an den Proxy gemeldet. Der Proxy stellt den aktuellen Kontostand über GET /economy/player bereit.

Konfiguration in verify.properties:

economy.mysql.host=localhost
economy.mysql.port=3306
economy.mysql.database=survivalplus
economy.mysql.username=root
economy.mysql.password=
economy.start-balance=500.0

4.15 StatsModule

Das StatsModule erfasst und speichert Spielerstatistiken automatisch und macht sie über die HTTP-API zugänglich.

Erfasste Daten pro Spieler:

Kategorie	Daten
Basis	UUID, Name, Erster Login, Letzter Login, Gesamte Spielzeit, Anzahl Joins
Kampf	Kills, Deaths (via StatusAPIBridge)
Wirtschaft	Kontostand, Gesamteinnahmen, Gesamtausgaben, Transaktionsanzahl
Strafen	Bans, Mutes, Warns, Letzter Strafzeitpunkt, Letzter Straftyp, Punishment-Score

Statistiken werden pro Spieler in eigenen Dateien im stats/-Unterordner gespeichert und beim Login geladen. Die Spielzeit wird live berechnet (aktive Session + gespeicherte Zeit).

HTTP-API: Spielerstatistiken können über GET /stats/player?uuid=<UUID> oder GET /stats/player?name=<Name> abgerufen werden. Updates kommen über POST /stats/update (Kills/Deaths via StatusAPIBridge) und POST /punishment/update (Straf-Daten).

4.16 CustomCommandModule

Das CustomCommandModule ermöglicht die Definition eigener Proxy-Befehle über customcommands.yml.

Zusätzlich registriert das Modul automatisch den Befehl /chat, der es Spielern erlaubt, Nachrichten über den Chat-Befehl zu senden (nützlich für Plugin-Kompatibilität).

/bcmds reload   – Konfiguration neu laden (Permission: statusapi.bcmds)

4.17 HelpModule

Das HelpModule stellt eine vollständige, seitenbasierte Ingame-Hilfe bereit. Der Befehlsname ist frei konfigurierbar – normale Spieler sehen nur allgemeine Befehle, Admins und OPs erhalten zusätzlich alle Admin-Seiten.

Konfiguration in verify.properties:

# ===========================
# INGAME HILFE
# ===========================
# Befehlsname für die Ingame-Hilfe (Standard: help)
# Beispiele:
#   statusapi.help=vn    →  /vn help
#   statusapi.help=sapi  →  /sapi help
statusapi.help=help

# Permission, die Admin-Seiten in der Hilfe freischaltet
# (OPs sehen die Admin-Seiten automatisch)
statusapi.help.permission=statusapi.admin

Verwendung:

Eingabe	Ergebnis
`/<befehl>`	Kurzer Hinweis auf `/<befehl> help`
`/<befehl> help`	Hilfe – Seite 1
`/<befehl> help 2`	Hilfe – Seite 2
`/<befehl> help 3`	Seite 3 (nur für Admins / OP sichtbar)
`/<befehl> help 4`	Seite 4 (nur für Admins / OP sichtbar)

Seitenaufteilung:

Seite	Inhalt	Sichtbar für
1	Allgemein, Chat (Teil 1)	Alle Spieler
2	Chat (Teil 2), Account-Verknüpfungen	Alle Spieler
3	Admin: StatusAPI, AntiBot, Vanish	Nur Admins / OP
4	Admin: Chat-Administration, Reports, Tools	Nur Admins / OP

Die Navigations-Buttons ◀ und ▶ am Ende jeder Seite sind klickbar – Spieler können direkt im Chat blättern, ohne den Befehl erneut einzugeben.

Hinweis: Der Befehlsname wird nur beim Serverstart registriert. Eine Änderung von statusapi.help erfordert einen vollständigen Serverneustart – ein /statusapi reload reicht hier nicht.

4.18 AfkModule

Das AfkModule erkennt inaktive Spieler automatisch und bietet einen manuellen /afk-Befehl. AFK-Spieler erhalten einen dauerhaft sichtbaren Title-Screen, werden intern als AFK markiert und bekommen über die StatusAPIBridge einen sichtbaren [AFK]-Prefix im Nametag über ihrem Kopf.

Funktionen:

Manuelles Umschalten des AFK-Status per /afk
Automatische AFK-Erkennung nach konfigurierbarer Inaktivitätsdauer (Standard: 5 Minuten)
Aufhebung des AFK-Status bei jeder Chat-Eingabe oder Bewegung (via StatusAPIBridge)
Dauerhaft sichtbarer Title-Screen solange der Spieler AFK ist – kein automatisches Ausblenden, kein Blinken
Automatischer [AFK]-Prefix im Nametag über dem Spieler-Kopf (via Plugin-Message an StatusAPIBridge)
Zufällig gewählte, thematisch passende Title-Nachrichten-Paare (AFK-Nachricht + Rückkehr-Nachricht)
Vollständige Gradient-Unterstützung im Title (%gradient:FARBE1:FARBE2:...:TEXT%)
Bypass-Permission für Spieler, die nicht automatisch AFK gesetzt werden sollen

Nametag-Prefix

Sobald ein Spieler AFK geht, sendet das AfkModule eine Plugin-Message über den Channel statusapi:afk an alle Spigot-Server. Die StatusAPIBridge empfängt diese Nachricht und stellt dem LuckPerms-Prefix des Spielers automatisch &7[AFK] voran. Beim Zurückkehren wird der Prefix sofort wiederhergestellt.

Voraussetzung: StatusAPIBridge muss auf allen Backend-Servern installiert und aktiv sein. Der Nametag-Prefix erfordert nametag-enabled=true in der StatusAPIBridge-Konfiguration.

Der [AFK]-Prefix-Text und seine Farbe können direkt im Quellcode der StatusAPIBridge unter applyNametag() angepasst werden (Standard: &7[AFK] ).

Title-Nachrichten-Paare

Für jeden AFK-Eintritt wird zufällig ein Nachrichten-Paar gewählt und für die gesamte AFK-Dauer beibehalten. Beim Verlassen des AFK-Status wird die zugehörige Rückkehr-Nachricht angezeigt. Bis zu 20 Paare können konfiguriert werden.

Das Format pro Paar: setTitle|setSubtitle||unsetTitle|unsetSubtitle

| trennt Title und Subtitle innerhalb einer Seite
|| trennt die AFK-Nachricht (links) von der Rückkehr-Nachricht (rechts)

Vorkonfigurierte Beispiele (Auszug aus dem Standard-Config):

AFK-Title	AFK-Subtitle	Rückkehr-Title	Rückkehr-Subtitle
`[AFK]` (Gradient)	Wahrscheinlich auf dem Klo...	Willkommen zurück! (Gradient)	War das Klo sauber?
`[AFK]` (Gradient)	Eingeschlafen. Bitte nicht wecken.	Aufgewacht! (Gradient)	Der Wecker hat funktioniert
`[AFK]` (Gradient)	Error 404: Spieler nicht gefunden	Spieler wieder online! (Gradient)	404 behoben
`[AFK]` (Gradient)	Kaffeepause. Die wichtigste Pause.	Koffein erfolgreich zugeführt! (Gradient)	Jetzt wieder einsatzbereit

Title-Anzeige ohne Blinken

Die Anzeigezeiten (fade_in, stay, fade_out) werden dem Client nur einmalig beim AFK-Eintritt übermittelt. Nachfolgende Refresh-Pakete erneuern ausschließlich Title und Subtitle – ohne erneute Timing-Übertragung. Dadurch bleibt der Title stabil stehen, ohne bei jedem Refresh-Intervall eine neue Einblend-Animation auszulösen.

Gradient-Unterstützung

Title-Zeilen unterstützen dieselbe Gradient-Syntax wie Scoreboard und Tablist:

%gradient:FARBE1:FARBE2:...:TEXT%

Farben können Minecraft-Codes (&b, &f) oder Hex-Werte (#RRGGBB, &#RRGGBB) sein. Beliebig viele Farb-Stopps sind möglich.

afk.title.pair.1=%gradient:&b:&f:&b:&l [AFK] %|&8Wahrscheinlich auf dem Klo...||%gradient:&a:&f:&a:&l Willkommen zurück! %|&7War das Klo sauber?

Befehl:

/afk   – AFK-Status manuell ein-/ausschalten

Vollständige Konfiguration in afk.properties:

# =====================================================
# AfkModule – /afk Befehl & automatische AFK-Erkennung
# =====================================================

afk.enabled=true

# Automatisch AFK setzen nach X Sekunden ohne Aktivität
afk.idle_enabled=true
afk.idle_seconds=300

# Berechtigung zum Umgehen des auto-AFK
afk.permission.bypass=statusapi.afk.bypass

# ── Title-Anzeigezeiten (in Ticks, 20 Ticks = 1 Sekunde) ──
# fade_in / fade_out werden nur beim ersten Einblenden gesendet –
# Refresh-Pakete enthalten keine Timing-Daten (verhindert Blink-Effekt).
afk.title.fade_in=10
afk.title.stay=100
afk.title.fade_out=10

# ── Nachrichten-Paare ─────────────────────────────────────
# Format: setTitle|setSubtitle||unsetTitle|unsetSubtitle
#   |  trennt Title und Subtitle innerhalb einer Seite
#   || trennt AFK-Nachricht (links) von Rückkehr-Nachricht (rechts)
# Gradient: %gradient:FARBE1:FARBE2:...:TEXT%
# Es wird zufällig ein Paar gewählt (max. 20 Paare).

afk.title.pair.1=%gradient:&b:&f:&b:&l [AFK] %|&8Wahrscheinlich auf dem Klo...||%gradient:&a:&f:&a:&l Willkommen zurück! %|&7War das Klo sauber?
afk.title.pair.2=%gradient:&b:&f:&b:&l [AFK] %|&8Hat den Stecker gezogen||%gradient:&a:&f:&a:&l Wieder eingesteckt! %|&7Der Strom ist zurück
afk.title.pair.3=%gradient:&b:&f:&b:&l [AFK] %|&8Eingeschlafen. Bitte nicht wecken.||%gradient:&a:&f:&a:&l Aufgewacht! %|&7Der Wecker hat funktioniert
# ... (bis zu 20 Paare möglich)

Hinweis: Die afk.properties wird beim ersten Start automatisch erstellt und enthält 15 vorkonfigurierte, humorvolle Nachrichten-Paare.

Integration mit StatusAPIBridge: Wenn die Bridge eine Koordinatenänderung meldet (POST /player/data), wird der AFK-Status des Spielers automatisch aufgehoben, die Rückkehr-Nachricht angezeigt und der Nametag-Prefix sofort wiederhergestellt.

5. HTTP-API

StatusAPI startet einen eigenen HTTP-Server auf dem in verify.properties konfigurierten Port (Standard: 9191). Der Server läuft in einem eigenen Thread mit 4 Worker-Threads und wird automatisch neugestartet, wenn er unerwartet stoppt (Watchdog-Task alle 15 Sekunden).

Sicherheitshinweis: Der HTTP-Server ist ausschließlich für die interne Kommunikation zwischen Backend-Servern und dem Proxy gedacht. Der Port sollte niemals öffentlich erreichbar sein (Firewall-Regel empfohlen).

Port-Konfiguration in verify.properties:

statusapi.port=9191

Vollständige Endpunkt-Übersicht

Methode	Pfad	Auth	Beschreibung
`GET`	`/health`	–	Erreichbarkeitscheck, gibt `{"success":true,"online":true,"last_request_age_ms":...}` zurück
`GET`	`/`	–	Vollständiger Netzwerkstatus als JSON (Spieler, Server, RAM, TPS, AntiBot)
`GET`	`/antibot/security-log`	–	Letzte 250 Sicherheitsereignisse aus dem AntiBot-Log
`GET`	`/network/backendguard/config`	API-Key (optional)	BackendGuard-Konfiguration für Backend-Server (erlaubte Proxy-IPs und CIDRs)
`GET`	`/stats/player?uuid=...`	–	Spielerstatistiken (Basis, Kampf, Wirtschaft, Strafen)
`GET`	`/stats/player?name=...`	–	Spielerstatistiken per Name
`GET`	`/economy/player?uuid=...`	–	Kontostand eines Spielers
`GET`	`/papi/tokens`	–	Alle erkannten PAPI-Platzhalter aus den Configs als JSON-Array
`POST`	`/broadcast`	API-Key (optional)	Sofortiger oder geplanter Broadcast an alle Spieler
`POST`	`/broadcast/cancel`	–	Geplanten Broadcast stornieren (per `clientScheduleId`)
`POST`	`/forum/notify`	API-Key	Forum-Benachrichtigung an einen Spieler senden
`POST`	`/network/attack`	API-Key	Angriffs-Event melden (löst Discord-Webhook aus)
`POST`	`/economy/update`	–	Kontostand eines Spielers im Proxy aktualisieren (von StatusAPIBridge)
`POST`	`/punishment/update`	–	Straf-Daten eines Spielers aktualisieren
`POST`	`/stats/update`	–	Kills, Deaths und Spielzeit eines Spielers aktualisieren
`POST`	`/scoreboard/health`	–	Leben eines Spielers für Scoreboard aktualisieren
`POST`	`/scoreboard/compass`	–	Himmelsrichtung eines Spielers für Scoreboard aktualisieren
`POST`	`/scoreboard/tps`	–	TPS des Backend-Servers für Scoreboard aktualisieren
`POST`	`/player/world`	–	Aktuelle Welt eines Spielers aktualisieren
`POST`	`/player/data`	–	Koordinaten, Gamemode, Exp, Food, Speed eines Spielers aktualisieren
`POST`	`/player/papi`	–	Aufgelöste PlaceholderAPI-Werte vom Backend empfangen
`POST`	`/ticket/update`	–	Ticket-Daten für Scoreboard-Platzhalter aktualisieren

Beispiele

Netzwerkstatus abrufen:

curl http://localhost:9191/

Sofortigen Broadcast senden:

curl -X POST http://localhost:9191/broadcast \
  -H "Content-Type: application/json" \
  -d '{"message": "&eServer-Neustart in 5 Minuten!", "source": "System"}'

Broadcast für 18:00 Uhr planen (wiederholt täglich):

curl -X POST http://localhost:9191/broadcast \
  -H "Content-Type: application/json" \
  -d '{
    "message": "&aGuten Abend! Tagesrückblick...",
    "scheduleTime": 1716048000,
    "recur": "daily",
    "clientScheduleId": "daily-evening-msg"
  }'

Geplanten Broadcast stornieren:

curl -X POST http://localhost:9191/broadcast/cancel \
  -H "Content-Type: application/json" \
  -d '{"clientScheduleId": "daily-evening-msg"}'

Spielerstatistiken abrufen:

curl "http://localhost:9191/stats/player?uuid=<UUID>"

6. Globales Rate-Limit-Framework

Das GlobalRateLimitFramework ist eine zentrale Komponente, die von mehreren Modulen gemeinsam genutzt wird (ChatModule, CommandBlockerModule). Es implementiert ein gleitendes Zeitfenster-Modell:

Aktionen werden in einem konfigurierbaren Zeitfenster gezählt.
Wird die maximale Aktionszahl überschritten, wird der Akteur für eine konfigurierbare Dauer blockiert.
Blockierungen gelten pro Modul-Scope und Spieler (UUID).
Das Framework ist thread-safe und verwendet ConcurrentHashMap für minimale Sperrkonflikte.

Konfigurierbare Parameter pro Scope:

window-ms – Größe des Zeitfensters in Millisekunden
max-actions – Maximale Aktionen innerhalb des Fensters
block-ms – Blockierungsdauer in Millisekunden bei Überschreitung

7. Update-Checker

StatusAPI prüft automatisch alle 6 Stunden, ob eine neue Version verfügbar ist. Die Prüfung erfolgt über die Gitea/Forgejo-API des Entwickler-Repositorys. Bei einer neuen Version erscheint eine Warnung in der Server-Konsole mit der neuen Versionsnummer und einem Download-Link. Spieler und Admins mit der Permission statusapi.update.notify werden beim Login ebenfalls benachrichtigt.

8. Befehle & Permissions – Komplette Referenz

Admin-Befehle

Befehl	Aliases	Permission	Beschreibung
`/statusapi reload`	`/sapi reload`	`statusapi.admin`	Scoreboard & Tablist neu laden
`/statusapi help`	`/sapi help`	`statusapi.admin`	Hilfe anzeigen
`/netinfo`	–	`statusapi.netinfo`	Proxy- und Systeminfos anzeigen
`/antibot status`	–	`statusapi.antibot`	AntiBot-Status anzeigen
`/antibot clearblocks`	–	`statusapi.antibot`	Alle blockierten IPs entsperren
`/antibot unblock <IP>`	–	`statusapi.antibot`	Einzelne IP entsperren
`/antibot profile <name>`	–	`statusapi.antibot`	Profil wechseln
`/antibot reload`	–	`statusapi.antibot`	AntiBot-Konfiguration neu laden
`/automessage reload`	–	`statusapi.automessage`	AutoMessage-Konfiguration neu laden
`/bcmds reload`	–	`statusapi.bcmds`	Custom Commands neu laden
`/cb list`	–	`commandblocker.admin`	Blockierte Befehle anzeigen
`/cb add <befehl>`	–	`commandblocker.admin`	Befehl blockieren
`/cb remove <befehl>`	–	`commandblocker.admin`	Befehl entsperren
`/cb reload`	–	`commandblocker.admin`	CommandBlocker neu laden

Ingame-Hilfe

Befehl	Aliases	Permission	Beschreibung
`/<befehl> help [seite]`	–	–	Ingame-Hilfe anzeigen (Befehlsname via `statusapi.help` in `verify.properties` konfigurierbar)

Admin-Seiten (Seite 3 & 4) sind nur für OPs und Spieler mit der unter statusapi.help.permission konfigurierten Permission sichtbar.

Chat-Befehle

Befehl	Aliases	Permission	Beschreibung
`/channel [name]`	`/ch`, `/kanal`	je nach Kanal	Kanal wechseln oder Kanalliste anzeigen
`/helpop <Nachricht>`	–	–	Hilfeanfrage an das Team senden
`/msg <Spieler> <Nachricht>`	`/tell`, `/w`, `/whisper`	–	Private Nachricht senden
`/r <Nachricht>`	`/reply`, `/antwort`	–	Auf letzte private Nachricht antworten
`/ignore <Spieler>`	`/block`	–	Spieler ignorieren
`/unignore <Spieler>`	`/unblock`	–	Spieler nicht mehr ignorieren
`/chatmute <Spieler> [Min.]`	`/gmute`	`chat.mute`	Spieler stummschalten
`/chatunmute <Spieler>`	`/gunmute`	`chat.mute`	Stummschaltung aufheben
`/chataus`	`/togglechat`, `/chaton`, `/chatoff`	–	Eigenen Chat-Empfang umschalten
`/broadcast <Nachricht>`	`/bc`, `/alert`	`chat.broadcast`	Netzwerkweiten Broadcast senden
`/emoji`	`/emojis`	–	Alle verfügbaren Emojis anzeigen
`/socialspy`	`/spy`	`chat.socialspy`	Private Nachrichten mitlesen umschalten
`/chatreload`	–	`statusapi.admin`	Chat-Konfiguration neu laden
`/chatinfo <Spieler>`	–	`chat.admin.bypass`	Chat-Infos eines Spielers anzeigen
`/chathist [Spieler] [Anz.]`	–	`chat.admin.bypass`	Chat-History anzeigen
`/mentions`	`/mention`	–	Mention-Benachrichtigungen umschalten
`/chatbypass`	`/cbp`	–	ChatModule für nächste Eingabe überspringen
`/report <Spieler> <Grund>`	–	`chat.report`	Spieler melden
`/reports [all]`	–	`chat.admin.bypass`	Offene Reports anzeigen
`/reportclose <ID>`	–	`chat.admin.bypass`	Report schließen

Account-Verknüpfung

Befehl	Aliases	Beschreibung
`/discordlink`	`/dlink`	Discord-Account verknüpfen (gibt Token aus)
`/telegramlink`	`/tlink`	Telegram-Account verknüpfen (gibt Token aus)
`/unlink <discord\|telegram\|all>`	–	Verknüpfung aufheben

Scoreboard

Befehl	Aliases	Beschreibung
`/scoreboard`	`/sb`, `/togglesb`	Scoreboard ein-/ausblenden
`/scoreboard hide`	–	Scoreboard ausblenden
`/scoreboard show`	–	Scoreboard einblenden
`/scoreboard player`	–	Zur Spieler-Ansicht wechseln
`/scoreboard admin`	–	Zur Admin-Ansicht wechseln (falls Permission vorhanden)

Vanish & Netzwerk

Befehl	Aliases	Permission	Beschreibung
`/vanish [Spieler]`	`/v`	–	Vanish ein-/ausschalten
`/vanishlist`	`/vlist`	–	Alle unsichtbaren Spieler anzeigen
`/go [servername]`	`/wechsel`, `/switch`	`serverswitcher.use`	Server-Menü öffnen oder direkt wechseln

AFK

Befehl	Aliases	Permission	Beschreibung
`/afk`	–	–	AFK-Status manuell ein-/ausschalten

Forum & Verify

Befehl	Aliases	Beschreibung
`/verify <token>`	–	Account mit WordPress-Forum verifizieren
`/forumlink <token>`	`/fl`	Minecraft-Account mit Forum verknüpfen
`/forum`	–	Ausstehende Forum-Benachrichtigungen anzeigen

Permissions-Referenz

Permission	Standard	Beschreibung
`statusapi.admin`	OP	StatusAPI-Administrationsbefehle (reload, help)
`statusapi.update.notify`	OP	Update-Benachrichtigung beim Login erhalten
`statusapi.netinfo`	OP	Zugriff auf `/netinfo`
`statusapi.antibot`	OP	Zugriff auf `/antibot`
`statusapi.automessage`	OP	Zugriff auf `/automessage reload`
`statusapi.bcmds`	OP	Zugriff auf `/bcmds reload`
`statusapi.scoreboard.admin`	false	Admin-Scoreboard-Ansicht
`statusapi.scoreboard.supporter`	false	Supporter-Scoreboard-Ansicht
`statusapi.afk.bypass`	false	Nicht automatisch AFK gesetzt werden
`statusapi.multiaccountguard.bypass`	keiner	Mehrere Accounts gleichzeitig erlauben (muss manuell vergeben werden!)
`statusapi.staff.notify`	false	MAG-Warnungen im Spiel empfangen
`chat.channel.local`	true	Zugang zum Local-Kanal
`chat.channel.trade`	true	Zugang zum Trade-Kanal
`chat.channel.staff`	false	Zugang zum Staff-Kanal
`chat.helpop.receive`	false	HelpOp-Nachrichten empfangen
`chat.mute`	false	Spieler muten/unmuten (`/chatmute`, `/chatunmute`)
`chat.broadcast`	false	Broadcasts senden (`/broadcast`)
`chat.socialspy`	false	Alle PMs mitlesen (`/socialspy`)
`chat.admin.bypass`	OP	Kann nicht gemuted/geblockt werden; sieht Reports, ChatInfo, ChatHist
`chat.admin.notify`	false	Benachrichtigungen über Mutes und Blocks erhalten
`chat.report`	true	Spieler reporten (`/report`)
`chat.color`	false	Farbcodes (`&a`, `&b`, ...) im Chat nutzen
`chat.color.format`	false	Formatierungen (`&l`, `&o`, `&n`, `&m`, `&k`) im Chat nutzen
`chat.filter.bypass`	false	Alle Chat-Filter umgehen
`commandblocker.bypass`	OP	CommandBlocker für alle Befehle umgehen
`commandblocker.admin`	OP	CommandBlocker verwalten (`/cb`)
`serverswitcher.use`	false	Zugriff auf `/go` (Serverwechsel)

9. LuckPerms Integration

StatusAPI nutzt LuckPerms als Soft-Dependency für:

Chat: Prefix und Suffix aus LuckPerms werden im Chat-Format, Join/Leave-Nachrichten und dem {prefix}/{suffix}-Platzhalter eingesetzt.
Scoreboard: Der Platzhalter %rank% wird aus dem LuckPerms-Prefix befüllt.
Tablist: Rang-basierte Sortierung im custom-Modus.
HTTP-Status (GET /): Der Prefix jedes Online-Spielers wird im JSON-Statusbericht mit ausgegeben.
Nametag (via StatusAPIBridge): Der LuckPerms-Prefix wird als Nametag über dem Spieler-Kopf angezeigt. AFK-Spieler erhalten automatisch einen [AFK]-Zusatz vor ihrem Prefix.

Wenn LuckPerms nicht installiert ist, sind Prefix und Suffix leer – alle anderen Funktionen bleiben vollständig erhalten.

Empfohlene LuckPerms-Einrichtung:

lp group default permission set chat.channel.local true
lp group default permission set chat.channel.trade true
lp group default permission set chat.report true

lp group supporter permission set chat.channel.staff true
lp group supporter permission set chat.helpop.receive true
lp group supporter permission set statusapi.scoreboard.supporter true
lp group supporter permission set statusapi.staff.notify true

lp group admin permission set statusapi.admin true
lp group admin permission set statusapi.netinfo true
lp group admin permission set statusapi.antibot true
lp group admin permission set chat.admin.bypass true
lp group admin permission set chat.admin.notify true
lp group admin permission set chat.mute true
lp group admin permission set chat.broadcast true
lp group admin permission set chat.socialspy true
lp group admin permission set chat.filter.bypass true
lp group admin permission set commandblocker.bypass true
lp group admin permission set statusapi.scoreboard.admin true

10. Geyser / Bedrock Support

StatusAPI erkennt Bedrock-Spieler automatisch über Geyser-BungeeCord. Zur Erkennung wird primär die Floodgate-API genutzt; als Fallback wird geprüft, ob die UUID des Spielers im Most-Significant-Bit den Wert 0 hat (typisch für Floodgate-UUIDs).

Anpassungen für Bedrock-Spieler:

Emojis: Bedrock-Spieler erhalten einen Fallback-Text statt Unicode-Emojis, wenn emoji.bedrock-support: true in chat.yml aktiviert ist.
Chat-Format: Der Geyser-Präfix (.) wird intern verarbeitet, sodass Bedrock-Spieler korrekt erkannt werden.
HTTP-Status: Das isBedrock-Feld im Spieler-JSON des Statusendpunkts zeigt an, ob es sich um einen Bedrock-Spieler handelt. Optional wird auch die bedrockId ausgegeben.

11. StatusAPIBridge (Backend-Integration)

Viele Platzhalter im Scoreboard werden von den Backend-Servern (Spigot/Paper) über die HTTP-API geliefert. Dafür ist das zugehörige Spigot-Plugin StatusAPIBridge erforderlich, das auf jedem Backend-Server installiert werden muss.

Die StatusAPIBridge sendet folgende Daten an den Proxy:

Endpunkt	Daten
`POST /scoreboard/health`	Aktuelle Lebenspunkte des Spielers
`POST /scoreboard/compass`	Himmelsrichtung des Spielers
`POST /scoreboard/tps`	TPS des Backend-Servers
`POST /player/world`	Aktuelle Welt des Spielers
`POST /player/data`	Koordinaten (x, y, z), Gamemode, Exp, Food, Speed – löst außerdem AFK-Aufhebung aus
`POST /economy/update`	Aktueller Kontostand (von NexEco via Vault)
`POST /stats/update`	Kills, Deaths, Spielzeit
`POST /punishment/update`	Straf-Daten (von einem Punishment-Plugin)
`POST /ticket/update`	Ticket-Daten (von einem Ticket-System)
`POST /player/papi`	Aufgelöste PlaceholderAPI-Werte für eigene `%token%`-Platzhalter

Zusätzlich empfängt die StatusAPIBridge Plugin-Messages vom Proxy:

Channel	Richtung	Beschreibung
`statusapi:afk`	Proxy → Bridge	AFK-Status-Änderung eines Spielers – Bridge aktualisiert den Nametag-Prefix sofort

Die StatusAPIBridge fragt über GET /papi/tokens ab, welche PlaceholderAPI-Platzhalter der Proxy benötigt, löst diese auf dem Spigot-Server auf und sendet die Ergebnisse zurück.

12. Debug-Modus

Der Debug-Modus gibt zusätzliche Informationen in der Konsole aus (Modul-Aktivierungen, Konfigurationsladungen, Kanal-Routing, etc.). Er ist standardmäßig deaktiviert.

Aktivierung in verify.properties:

debug=true

13. Emoji-Liste

Alle vordefinierten Emojis können direkt im Chat verwendet werden, indem das jeweilige Kürzel eingegeben wird (z. B. :fire:). Neue Emojis können jederzeit in chat.yml unter emoji.mappings hinzugefügt werden.

Kürzel	Emoji	Kürzel	Emoji	Kürzel	Emoji
`:smile:`	😊	`:laugh:`	😄	`:sad:`	😢
`:cry:`	😭	`:angry:`	😠	`:heart:`	❤️
`:fire:`	🔥	`:star:`	⭐	`:check:`	✅
`:x:`	❌	`:warning:`	⚠️	`:thumbsup:`	👍
`:thumbsdown:`	👎	`:wave:`	👋	`:clap:`	👏
`:sword:`	⚔️	`:shield:`	🛡️	`:diamond:`	💎
`:crown:`	👑	`:skull:`	💀	`:sun:`	☀️
`:moon:`	🌙	`:tree:`	🌳	`:house:`	🏠
`:money:`	💰	`:rocket:`	🚀	`:rainbow:`	🌈
`:ghost:`	👻	`:gift:`	🎁	`:cake:`	🎂
`:chicken:`	🐔	`:pig:`	🐷	`:creeper:`	💣
`:gg:`	🎮

Hinweis Bedrock: Bedrock-Spieler erhalten bei aktiviertem emoji.bedrock-support: true statt des Unicode-Zeichens einen lesbaren Fallback-Text (z. B. [Herz]), falls ihr Client das Zeichen nicht darstellen kann.

Eigene Emojis hinzufügen – Eintrag in chat.yml:

emoji:
  mappings:
    ":meinEmoji:": "\uD83E\uDD84"   # 🦄 Einhorn

14. Häufige Fragen & Fehlerbehebung

Der HTTP-Server startet nicht / Port belegt

Prüfe, ob Port 9191 (oder der in verify.properties eingestellte Port) von einem anderen Prozess belegt wird. Der StatusAPI-HTTP-Watchdog meldet in der Konsole, wenn der Server-Thread unerwartet stoppt und neu gestartet wird.

Das Scoreboard zeigt keine Echtzeit-Daten (Koordinaten, TPS, Leben, etc.)

Diese Werte werden von den Backend-Servern über die HTTP-API gemeldet. Dafür muss StatusAPIBridge auf jedem Spigot/Paper-Backend-Server installiert und korrekt konfiguriert sein.

Chat-Nachrichten werden von Paper abgelehnt

Paper prüft Chat-Signaturen. Da BungeeCord die Nachrichtenformatierung übernimmt, muss in der paper-global.yml auf jedem Backend-Server messages.reject-chat-unsigned: false gesetzt sein.

Die Economy zeigt überall 0 an

Prüfe die MySQL-Verbindungsdaten in verify.properties. Die Tabelle bc_accounts muss existieren (wird automatisch erstellt). NexEco auf den Spigot-Servern muss dieselbe Datenbank nutzen und die StatusAPIBridge muss Balance-Updates senden.

MultiAccountGuard blockiert legitime Spieler (z. B. Admins mit mehreren Accounts)

Weise diesen Spielern die Permission manuell zu:

lp user <Name> permission set statusapi.multiaccountguard.bypass true

Die Discord/Telegram-Bridge sendet keine Nachrichten

Prüfe in chat.yml:

discord.enabled: true bzw. telegram.enabled: true gesetzt?
Bot-Token korrekt und gültig?
Beim Discord-Bot: Ist der Bot Mitglied des Servers (Guild) und hat Schreibrechte in den Channels?
Beim Telegram-Bot: Hat der Bot Schreibrechte in der Gruppe/dem Kanal?

/statusapi reload lädt nicht alle Einstellungen neu

Der Befehl lädt nur Scoreboard und Tablist neu. Chat, AntiBot, Economy und andere Module erfordern einen vollständigen Serverneustart für Konfigurationsänderungen. Der Chat kann separat über /chatreload neu geladen werden.

Tab-Liste zeigt nicht alle Spalten an

Die Anzahl der Spalten wird durch tab-list-size in der BungeeCord config.yml begrenzt. StatusAPI gibt beim Start eine Warnung aus, falls der Wert nicht ausreicht. Setze tab-list-size auf den in tablist.properties konfigurierten Wert (Standard: 180).

VPN/Proxy-Check blockiert zu viele legitime Spieler

Reduziere die Scoring-Punkte für VPN/Proxy-Treffer oder erhöhe den antibot.learning.score_threshold. Alternativ: antibot.vpn_check.block_hosting=false setzen, da viele legitime Nutzer über Cloud-Anbieter spielen.

Die Ingame-Hilfe zeigt den falschen Befehlsnamen

Den Wert von statusapi.help in verify.properties anpassen und den Server neu starten. Ein /statusapi reload reicht nicht – Befehle werden nur beim Serverstart registriert.

Spieler werden nicht automatisch AFK gesetzt

Prüfe in afk.properties:

afk.enabled=true gesetzt?
afk.idle_enabled=true gesetzt?
Hat der Spieler die Permission statusapi.afk.bypass? Dann wird er vom Auto-AFK ausgenommen.
Der Idle-Check läuft alle 10 Sekunden – es kann bis zu afk.idle_seconds + 10 Sekunden dauern, bis AFK ausgelöst wird.

AFK-Title wird nicht angezeigt

Prüfe, ob mindestens ein afk.title.pair.* in afk.properties korrekt konfiguriert ist. Das Format setTitle|setSubtitle||unsetTitle|unsetSubtitle muss exakt eingehalten werden – insbesondere das doppelte || als Trenner zwischen AFK- und Rückkehr-Nachricht.

AFK-Prefix erscheint nicht über dem Spieler-Kopf

Prüfe folgende Punkte:

Ist StatusAPIBridge auf dem Backend-Server installiert und läuft sie fehlerfrei?
Ist nametag-enabled=true in der StatusAPIBridge-Konfiguration gesetzt?
Ist LuckPerms auf dem Backend-Server installiert? Der Nametag-Prefix basiert auf dem LuckPerms-Prefix.
Prüfe in der Konsole des Backend-Servers, ob Plugin-Messages auf dem Channel statusapi:afk ankommen (Debug-Modus aktivieren).

65 KiB Raw Blame History Unescape Escape

StatusAPI – BungeeCord Plugin

Inhaltsverzeichnis

1. Voraussetzungen

2. Installation

3. Konfigurationsdateien im Überblick

4. Module

4.1 ChatModule

4.2 ScoreboardModule

4.3 TablistModule

4.4 AntiBotModule

4.5 MultiAccountGuard

4.6 NetworkInfoModule

4.7 VanishModule

4.8 VerifyModule

4.9 ForumBridgeModule

4.10 BroadcastModule

4.11 AutoMessageModule

4.12 CommandBlockerModule

4.13 ServerSwitcherModule

4.14 EconomyModule

4.15 StatsModule

4.16 CustomCommandModule

4.17 HelpModule

4.18 AfkModule

5. HTTP-API

Vollständige Endpunkt-Übersicht

Beispiele

6. Globales Rate-Limit-Framework

7. Update-Checker

8. Befehle & Permissions – Komplette Referenz

Admin-Befehle

Ingame-Hilfe

Chat-Befehle

Account-Verknüpfung

Scoreboard

Vanish & Netzwerk

AFK

Forum & Verify

Permissions-Referenz

9. LuckPerms Integration

10. Geyser / Bedrock Support

11. StatusAPIBridge (Backend-Integration)

12. Debug-Modus

13. Emoji-Liste

14. Häufige Fragen & Fehlerbehebung

65 KiB

Raw Blame History