M_Viper/StatusAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
41d0d80811470cfa3fbe1addeacc41c36de804ab
StatusAPI/README.md
M_Viper 45e1e3cbc0 README.md aktualisiert
2026-05-26 12:46:36 +00:00

62 KiB
Raw Blame History

StatusAPI – BungeeCord Plugin

Version: 4.1.4 · 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

  1. Voraussetzungen
  2. Installation
  3. Konfigurationsdateien im Überblick
  4. Module
  5. HTTP-API
  6. Globales Rate-Limit-Framework
  7. Update-Checker
  8. Befehle & Permissions – Komplette Referenz
  9. LuckPerms Integration
  10. Geyser / Bedrock Support
  11. StatusAPIBridge (Backend-Integration)
  12. Debug-Modus
  13. Emoji-Liste
  14. Häufige Fragen & Fehlerbehebung

1. Voraussetzungen

Anforderung Details
BungeeCord Aktuell, Minecraft 1.20+ kompatibel
Java 17 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

  1. Die fertige StatusAPI.jar in den /plugins-Ordner deines BungeeCord-Servers legen.
  2. BungeeCord (neu) starten.
  3. Beim ersten Start werden alle Konfigurationsdateien im Verzeichnis /plugins/StatusAPI/ automatisch erstellt.
  4. Den Server stoppen, die Konfigurationsdateien anpassen (siehe Abschnitt 3) und anschließend neu starten.
  5. 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:

  1. Spieler betritt einen Server.
  2. Das Plugin generiert einen signierten Token (HMAC-SHA256) für den Server.
  3. Spieler gibt /verify <token> auf der Webseite ein.
  4. 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:

  1. Das WordPress-Forum sendet einen POST /forum/notify an die StatusAPI-HTTP-API mit einem API-Key und den Benachrichtigungsdaten (Spielername, Typ, Beitragstitel, URL).
  2. 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 und werden intern als AFK markiert (z. B. für Scoreboard-Platzhalter und Bridge-Integrationen).

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
  • 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

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

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) ──
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 und die Rückkehr-Nachricht angezeigt.

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.

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

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:

  1. discord.enabled: true bzw. telegram.enabled: true gesetzt?
  2. Bot-Token korrekt und gültig?
  3. Beim Discord-Bot: Ist der Bot Mitglied des Servers (Guild) und hat Schreibrechte in den Channels?
  4. 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:

  1. afk.enabled=true gesetzt?
  2. afk.idle_enabled=true gesetzt?
  3. Hat der Spieler die Permission statusapi.afk.bypass? Dann wird er vom Auto-AFK ausgenommen.
  4. 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.

Reference in New Issue View Git Blame Copy Permalink