M_Viper/StatusAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
84853c772774f1863633fab308eb4f275c8f14d6
StatusAPI/README.md
M_Viper 122e7735d5 README.md aktualisiert
2026-05-10 13:16:59 +00:00

22 KiB
Raw Blame History

StatusAPI

Modulares BungeeCord-Plugin für Netzwerkbetrieb, Moderation und Integrationen.
Live-Status · Chat & Support · Verifizierung · Forum-Bridge · Broadcasts · AntiBot · BackendJoinGuard · Scoreboard

Rechtlicher Hinweis Dieses Projekt sowie alle enthaltenen Module, Quelltexte und Ressourcen dürfen nicht verändert, kopiert oder weiterverbreitet werden. Jegliche Nutzung, Modifikation oder Weitergabe ist ausschließlich mit vorheriger schriftlicher Genehmigung des Entwicklers gestattet. © Entwickelt von M_Viper. Alle Rechte vorbehalten.

Übersicht

Dieses Repository enthält zwei aufeinander abgestimmte Plugins:

Plugin Plattform Zweck
StatusAPI BungeeCord (Proxy) HTTP-API, AntiBot, Chat, Moderation, Verify, Forum, Scoreboard
StatusAPIBridge Paper / Spigot (Backend) Sendet Spielerdaten (Health, Kompass, Position, etc.) an StatusAPI
BackendJoinGuard Paper / Spigot (Backend) Verhindert Direktjoins am Proxy vorbei

BackendJoinGuard kann eigenständig betrieben werden oder seine Schutzregeln automatisch per Sync von StatusAPI beziehen.

Inhaltsverzeichnis

StatusAPI

Module

Core & HTTP-API
  • Eigener HTTP-Server über konfigurierbaren Port (statusapi.port, Standard: 9191)
  • JSON-Statusausgabe mit Spieler-, Prefix-, Bedrock-, Netzwerk- und Systemdaten
  • POST-Endpunkte für Broadcast, Broadcast-Abbruch, Forum-Notify und Attack-Events
ScoreboardModule
  • Vollständig konfigurierbares BungeeCord-Sidebar-Scoreboard
  • Flüssige Wave-Animation im Titel (10 fps, HSB-Farbwelle oder eigene Farben)
  • Gradient-Placeholder für farbige Zeilen
  • News-Ticker mit konfigurierbarem Text, Breite und Geschwindigkeit
  • Zeilenrotation – bis zu 20 Varianten pro Zeile
  • Separates Admin-Scoreboard mit eigenen Zeilen
  • /sb-Command zum Ein-/Ausblenden und Umschalten zwischen Player/Admin-Board
NetworkInfo
  • Live-Snapshot für Proxy, Uptime, RAM, CPU, Backends und Ping
  • Ingame-Befehl /netinfo für Statusprüfung
  • Discord-Webhook-Meldungen bei: Server-Start/-Stop, hoher RAM-/Spieler-Auslastung, Attack Detected/Stopped
  • Embed-Modus konfigurierbar: compact oder detailed
AntiBot
  • CPS-basierte Attack-Erkennung mit konfigurierbaren Start- und Stop-Schwellen
  • Pro-IP Rate-Limit mit temporären IP-Blocks
  • Optionaler VPN/Proxy/Hosting-Check via ip-api
  • Profile: strict und high-traffic
  • Laufzeitverwaltung über /antibot (Status, Blocks leeren, IP entblocken, Profil wechseln, Reload)
Chat & Moderation
  • Mehrere Chat-Kanäle, PM-System mit Reply, Ignore-System
  • Mute/Unmute, Mentions, Emoji-Unterstützung, SocialSpy
  • Chat-History und Admin-Infos
  • Report-System inkl. Close-Flow
  • Weiterleitung an Discord und Telegram (konfigurierbar)
Verify, Forum & CommandBlocker
  • Spieler-Verifizierung über Token
  • Forum-Linking und Forum-Benachrichtigungen ingame
  • Command-Blocker mit /cb-Verwaltung
AutoMessage & CustomCommands
  • Rotierende Auto-Nachrichten aus messages.txt (intervallgesteuert)
  • Eigene Command-Mappings über customcommands.yml
  • Optionaler /chat-Command (steuerbar per Konfiguration)
  • Reload via /bcmds

HTTP API

Basis-URL: http://<proxy-ip>:9191 – Port konfigurierbar über statusapi.port.

Methode Pfad Beschreibung Auth
GET / Voller Netzwerk-Status als JSON –
POST /broadcast Broadcast senden oder planen x-api-key
POST /broadcast/cancel Geplanten Broadcast abbrechen x-api-key
POST /cancel Alias für /broadcast/cancel x-api-key
POST /forum/notify Forum-Notification an Proxy x-api-key / Forum-Secret
POST /network/attack Attack-Event an Discord-Webhook melden x-api-key
GET /network/backendguard/config Guard-Regeln für BackendJoinGuard Sync x-api-key
POST /scoreboard/health Spieler-HP aktualisieren intern
POST /scoreboard/compass Spieler-Yaw aktualisieren intern
POST /scoreboard/tps Server-TPS aktualisieren intern
POST /player/world Spieler-Welt aktualisieren intern
POST /player/data Koordinaten, Gamemode, Exp, Food, Speed intern

Commands (StatusAPI)

Netzwerk & Schutz

Command Beschreibung
/netinfo Netzwerk- und Systemstatus anzeigen
/antibot status AntiBot-Status anzeigen
/antibot clearblocks Alle aktiven IP-Blocks entfernen
/antibot unblock <ip> Einzelne IP entblocken
/antibot profile <strict|high-traffic> Profil wechseln und speichern
/antibot reload AntiBot-Konfiguration neu laden

Verify & Forum

Command Beschreibung
/verify <token> Account verifizieren
/forumlink <token> Account mit Forum verknüpfen
/forum Forum-Benachrichtigungen anzeigen

Chat, Support & Moderation

Command Beschreibung
/channel [kanal] Kanal wechseln oder Liste anzeigen
/helpop <text> Support-Anfrage an Team
/msg <spieler> <text> Private Nachricht senden
/r <text> Auf letzte PM antworten
/ignore <spieler> Spieler ignorieren
/unignore <spieler> Ignore entfernen
/chatmute <spieler> [minuten] Spieler muten
/chatunmute <spieler> Mute aufheben
/chataus Chat-Empfang toggeln
/broadcast <text> Broadcast an alle senden
/emoji Emoji-Liste anzeigen
/socialspy PMs mitlesen toggeln
/chatreload Chat-Konfiguration neu laden
/chatinfo <spieler> Admin-Infos zu einem Spieler
/chathist [spieler] [anzahl] Chat-History anzeigen
/mentions Mention-Benachrichtigungen toggeln
/chatbypass Nächste Nachricht am Plugin vorbei senden
/discordlink, /dlink Discord-Linktoken erstellen
/telegramlink, /tlink Telegram-Linktoken erstellen
/unlink <discord|telegram|all> Verknüpfung aufheben
/report <spieler> <grund> Spieler melden
/reports [all] Reports ansehen
/reportclose <id> Report schließen

CommandBlocker

Command Beschreibung
/cb add <command> Command blockieren
/cb remove <command> Blockierung aufheben
/cb list Alle blockierten Commands anzeigen
/cb reload CommandBlocker neu laden

CustomCommands

Command Beschreibung
/bcmds customcommands.yml neu laden
/chat <text> Text als Chat senden oder Slash-Command ausführen

Permissions (StatusAPI)

Permission Beschreibung
statusapi.update.notify Update-Benachrichtigungen empfangen
statusapi.netinfo Zugriff auf /netinfo
statusapi.antibot Zugriff auf /antibot
statusapi.automessage Zugriff auf /automessage reload
statusapi.bcmds Zugriff auf CustomCommand-Funktionen
chat.channel.local Zugang zum Local-Kanal
chat.channel.trade Zugang zum Trade-Kanal
chat.channel.staff Zugang zum Staff-Kanal
chat.helpop.receive HelpOp-Nachrichten empfangen
chat.mute Spieler muten / unmuten
chat.broadcast Broadcasts senden
chat.socialspy Private Nachrichten mitlesen
chat.admin.bypass Nicht mutbar / nicht blockierbar
chat.admin.notify Benachrichtigungen über Mutes und Blocks
chat.report Spieler reporten (/report)
chat.color Farbcodes (&a, &b, …) im Chat nutzen
chat.color.format Formatierungen (&l, &o, &n, …) im Chat nutzen
chat.filter.bypass Anti-Spam, Caps und Blacklist umgehen
commandblocker.bypass Command-Blocker umgehen
commandblocker.admin CommandBlocker verwalten (/cb)

Konfiguration (StatusAPI)

verify.properties – Core, Verify, Broadcast, Forum, Port

statusapi.port=9191
wp_verify_url=https://deine-domain.tld
server.<Name>.id=<id>
server.<Name>.secret=<secret>
broadcast.enabled=true
broadcast.api_key=<key>
forum.enabled=true
forum.api_secret=<key>
automessage.enabled=true
automessage.interval=300
automessage.file=messages.txt
automessage.prefix=&8[&bInfo&8]

network-guard.properties – NetworkInfo, Webhook, AntiBot, BackendJoinGuard

networkinfo.enabled=true
networkinfo.webhook.enabled=true
networkinfo.webhook.url=<discord_webhook>
networkinfo.webhook.embed_mode=detailed
networkinfo.attack.api_key=<attack_api_key>

antibot.enabled=true
antibot.profile=high-traffic

backendguard.enforcement_enabled=true
backendguard.log_blocked_attempts=true
backendguard.kick_message=&cBitte verbinde dich nur ueber den Proxy-Server.
backendguard.allowed_proxy_ips=127.0.0.1,::1
backendguard.allowed_proxy_cidrs=10.0.0.0/24
backendguard.sync.api_key=<sync_key>

Weitere Konfigurationsdateien

Datei Inhalt
chat.yml Kanäle, Formate, PM, Reports, Filter, Logging, Discord/Telegram, Linking
blocked-commands.yml Liste der geblockten Commands
customcommands.yml Eigene Befehle, Aliase, Sender-Typen
messages.txt AutoMessage-Texte (Zeilen mit # und Leerzeilen werden ignoriert)
scoreboard.properties Scoreboard-Konfiguration (siehe ScoreboardModule)

ScoreboardModule

Das ScoreboardModule zeigt ein vollständig konfigurierbares Sidebar-Scoreboard auf BungeeCord-Ebene. Spielerdaten werden über StatusAPIBridge vom Backend-Server in Echtzeit geliefert.

Features (Scoreboard)

  • Wave-Titel-Animation – flüssige HSB-Farbwelle (10 fps), Farben frei konfigurierbar
  • Gradient-Placeholder – %gradient:FARBE1:FARBE2:TEXT% für farbige Zeilen
  • News-Ticker – konfigurierbarer Lauftext von rechts nach links (10 fps)
  • Zeilenrotation – pro Zeile bis zu 20 Varianten, wechseln automatisch
  • Admin-Scoreboard – eigenes Objective mit eigenen Zeilen, automatisch für Spieler mit Permission
  • Kompass – Himmelsrichtungs-Anzeige mit farbigen Buchstaben, zentriert
  • Herzen & Hunger – ♥♥♥♥♥♡♡♡♡♡ / ◆◆◆◆◆◇◇◇◇◇
  • Separator-Styles – frei wählbar (Striche, Wellen, Gradient, leer, …)
  • Toggle-Command – /sb zum Ein-/Ausblenden, /sb admin / /sb player zum Umschalten

Placeholders

Spieler-Placeholders (werden von StatusAPIBridge geliefert)

Placeholder Beschreibung
%player% Spielername
%rank% Rang (LuckPerms Prefix)
%server% Aktueller Server (erster Buchstabe groß)
%health% Leben als Herz-Symbole ♥♥♥♡♡
%hearts% Leben als Zahl
%food% Hunger als Zahl (0–20)
%foodsym% Hunger als Symbole ◆◆◆◇◇
%compass% Kompass-Balken zentriert
%ping% Ping in ms
%online% Anzahl Online-Spieler
%maxplayers% Max. Spieleranzahl
%money% Kontostand (Economy)
%time% Aktuelle Uhrzeit
%date% Aktuelles Datum
%playtime% Spielzeit der Session TT HH:MM:SS
%x% %y% %z% Koordinaten
%world% Welt-Name
%gamemode% Spielmodus (SURVIVAL, CREATIVE, …)
%exp% XP-Level
%speed% Laufgeschwindigkeit
%news% News-Ticker
%line% Trennlinie (konfigurierbar)

Admin-Placeholders (BungeeCord-seitig)

Placeholder Beschreibung
%tps% Server-TPS
%ram% RAM-Nutzung
%proxymem% Proxy RAM
%uptime% Proxy-Laufzeit HH:MM:SS
%servers% Anzahl verbundener Backend-Server

Spezial-Placeholders

Placeholder Beschreibung
%gradient:F1:F2:TEXT% Farbverlauf von F1 nach F2 über TEXT (beliebig viele Stopps)
%line% Trennlinie aus scoreboard.separator
%news% News-Ticker-Fenster

Farben für Gradient: Hex (#RRGGBB, &#RRGGBB) oder Minecraft-Codes (&0–&f).

Konfiguration (Scoreboard)

Datei: plugins/StatusAPI/scoreboard.properties

scoreboard.enabled=true
scoreboard.update_interval=500          # Millisekunden, min. 250
scoreboard.title=&lViper Network        # Kein Farbcode → Wave übernimmt Farbe
scoreboard.admin_title=&l[Admin] Panel
scoreboard.admin_permission=statusapi.scoreboard.admin

# Wave-Animation
scoreboard.rainbow.enabled=true
scoreboard.rainbow.mode=wave            # wave | chars | line
scoreboard.rainbow.speed=10             # 1=sehr langsam, 10=normal, 50=schnell
scoreboard.rainbow.colors=#FF0000,#FF6600,#FFFF00,#00FF00,#00FFFF,#0000FF,#FF00FF

# News-Ticker
scoreboard.news.text=Willkommen auf Viper Network!
scoreboard.news.prefix=&8[&6News&8] &r  # Leer lassen zum Deaktivieren
scoreboard.news.width=20
scoreboard.news.speed=1

# Zeilenrotation (Sekunden pro Variante)
scoreboard.rotation_interval=4

# Separator für %line%
scoreboard.separator=&8&m--------------------

# Zeilen (max. 15 sichtbar, bis zu 20 definierbar)
# scoreboard.lines.N       = Variante 1 (dauerhaft)
# scoreboard.lines.N.2     = Variante 2 (rotiert nach rotation_interval Sekunden)
# scoreboard.lines.N.3     = Variante 3  usw.
scoreboard.lines.1=%line%
scoreboard.lines.2=%gradient:&b:&f:&b:&l> Player Info:%
scoreboard.lines.3=&7%rank% &f%player%
scoreboard.lines.4=
scoreboard.lines.5=&7Spielzeit: &f%playtime%
scoreboard.lines.5.2=&7Leben: &c%health%
scoreboard.lines.5.3=&7Hunger: &#8B4513%foodsym%
scoreboard.lines.6=
scoreboard.lines.7=%gradient:&b:&f:&b:&l> Money:%
scoreboard.lines.8=&a$%money%
scoreboard.lines.9=
scoreboard.lines.10=%gradient:&b:&f:&b:&l> Server Info:%
scoreboard.lines.11=&f%server%
scoreboard.lines.11.2=&7Ping: &f%ping%ms &8| &7Online: &f%online%
scoreboard.lines.12=
scoreboard.lines.13=%news%
scoreboard.lines.14=%line%
scoreboard.lines.15=&7%compass%

# Admin-Zeilen (eigenes Objective, automatisch für Spieler mit Admin-Permission)
scoreboard.admin_lines.1=%line%
scoreboard.admin_lines.2=%gradient:&b:&f:&b:&l> Player Info:%
scoreboard.admin_lines.3=&7%rank% &f%player%
scoreboard.admin_lines.4=&7Gamemode: &f%gamemode%
scoreboard.admin_lines.5=&7Leben: &c%health%
scoreboard.admin_lines.5.2=&7Hunger: &#8B4513%foodsym%
scoreboard.admin_lines.6=
scoreboard.admin_lines.7=%gradient:&b:&f:&b:&l> Server Info:%
scoreboard.admin_lines.8=&f%server% &8| &7RAM: &e%ram%
scoreboard.admin_lines.8.2=&7Proxy: &f%uptime%
scoreboard.admin_lines.9=
scoreboard.admin_lines.10=&7TPS: &a%tps%
scoreboard.admin_lines.11=
scoreboard.admin_lines.12=&7Spieler: &f%online% &8| &7%maxplayers%
scoreboard.admin_lines.13=%news%
scoreboard.admin_lines.14=%line%
scoreboard.admin_lines.15=&7%compass%
scoreboard.admin_lines.15.2=&7Pos: X:&f%x% &7Y:&f%y% &7Z:&f%z%

Separator-Stile

Stil Wert
Standard &8&m--------------------
Doppelt &8&m====================
Wellig &8&m~~~~~~~~~~~~~~~~~~~~
Dünn &8&m────────────────────
Dick &8&m════════════════════
Diamanten &8◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇
Gradient %gradient:&8:&7:────────────────────%
Leer (leer lassen)

Commands (Scoreboard)

Command Aliase Beschreibung
/scoreboard /sb, /togglesb Scoreboard ein-/ausblenden (Toggle)
/sb hide Scoreboard ausblenden
/sb show Scoreboard einblenden
/sb player Player-Scoreboard anzeigen
/sb admin Admin-Scoreboard anzeigen (Permission erforderlich)

Permission: statusapi.scoreboard.admin – Admin-Scoreboard + /sb admin

StatusAPIBridge

StatusAPIBridge läuft auf jedem Backend-Server (Spigot/Paper) und sendet Spielerdaten in Echtzeit an StatusAPI.

Gesendete Daten

Datenpunkt Endpunkt Beschreibung
Health POST /scoreboard/health Aktuelle HP
Kompass (Yaw) POST /scoreboard/compass Blickrichtung (0–360°)
TPS POST /scoreboard/tps Server-TPS
Welt POST /player/world Welt-Name
Position, Gamemode, Exp, Food, Speed POST /player/data Erweiterte Spielerdaten

Konfiguration (StatusAPIBridge)

Datei: plugins/StatusAPIBridge/config.yml

statusapi-url: "http://127.0.0.1:9191"
scoreboard-sync-interval-ticks: 20   # Ticks zwischen Daten-Pushes (20 = 1s)
compass-threshold: 0.5               # Minimale Yaw-Änderung für Kompass-Update (Grad)

BackendJoinGuard

BackendJoinGuard verhindert, dass Spieler Backend-Server direkt betreten und damit den Proxy-Schutz umgehen. Das Plugin prüft beim Login die Quell-IP – nur konfigurierte Proxy-IPs oder CIDR-Netze werden durchgelassen.

Wichtig: BackendJoinGuard kommt auf jeden Backend-Server, nicht auf den Proxy.

Betriebsarten

Modus Beschreibung
Standalone Nutzt ausschließlich die lokale config.yml
StatusAPI Sync Lädt Schutzregeln regelmäßig von StatusAPI; lokale Werte bleiben als Fallback erhalten

Commands & Permissions (BackendJoinGuard)

Command Permission Beschreibung
/backendguard reload backendguard.admin Config neu laden und bei aktivem Sync sofort neu abrufen

Konfiguration (BackendJoinGuard)

Datei: plugins/BackendJoinGuard/config.yml

Lokaler Schutz

enforcement-enabled: true
log-blocked-attempts: true
kick-message: "&cBitte verbinde dich nur ueber den Proxy-Server."

allowed-proxy-ips:
  - "127.0.0.1"
  - "::1"
  - "185.123.45.67"

allowed-proxy-cidrs:
  - "10.0.0.0/24"

StatusAPI Sync

statusapi-sync:
  enabled: true
  base-url: "http://127.0.0.1:9191"
  endpoint-path: "/network/backendguard/config"
  api-key: "DEIN_SYNC_KEY"
  interval-seconds: 60
  log-sync-errors: true

Typische Szenarien

Szenario allowed-proxy-ips base-url
Alles auf einer Maschine 127.0.0.1, ::1 http://127.0.0.1:9191
Proxy auf separatem Host 185.123.45.67 http://185.123.45.67:9191
Internes Netz (CIDR) 10.0.0.10 + CIDR 10.0.0.0/24 http://10.0.0.10:9191

Voraussetzungen & Installation

Voraussetzungen

Komponente Pflicht Optional
BungeeCord Proxy ✅
Minecraft 1.20+ ✅
Java 8+ ✅
LuckPerms ✅
Geyser-BungeeCord ✅
Discord Webhook / Bot ✅
Telegram Bot ✅
WordPress / Forum-Backend ✅

StatusAPI installieren (Proxy)

1. StatusAPI.jar        →  plugins/ auf dem Proxy
2. Proxy starten        →  Konfigurationsdateien werden erzeugt
3. Proxy stoppen
4. Konfigurationen anpassen:
     verify.properties · chat.yml · network-guard.properties · scoreboard.properties
5. Proxy neu starten

StatusAPIBridge installieren (Backend)

1. StatusAPIBridge.jar  →  plugins/ auf jedem Backend-Server
2. Server starten       →  config.yml wird erzeugt
3. config.yml anpassen  →  statusapi-url auf Proxy-IP setzen
4. Server neu starten

BackendJoinGuard installieren (Backend)

1. BackendJoinGuard.jar  →  plugins/ auf jedem Backend-Server
2. Server starten        →  config.yml wird erzeugt
3. config.yml anpassen
4. Server neu starten  oder  /backendguard reload ausführen

StatusPulse Companion (WordPress)

Im Repository unter wordpress/statuspulse liegt ein WordPress-Admin-Plugin. Damit lassen sich StatusAPI-Verbindung, Attack-Key und Attack-Testflows direkt im WordPress-Backend bedienen. Erfordert StatusAPI ≥ 4.1.0.

Troubleshooting

StatusAPI

Problem Mögliche Ursachen & Lösung
API nicht erreichbar statusapi.port prüfen · Firewall / Portfreigabe prüfen · Proxy-Konsole auf HTTP-Server-Startmeldung prüfen
Attack-Meldungen fehlen in Discord networkinfo.webhook.enabled und .url prüfen · networkinfo.attack.enabled und api_key-Header prüfen
AntiBot zu hart / zu weich antibot.profile auf strict oder high-traffic setzen · Schwellwerte in network-guard.properties feinjustieren · /antibot reload ausführen

ScoreboardModule

Problem Mögliche Ursachen & Lösung
Scoreboard verschwindet nach Join scoreboard.update_interval muss mind. 250ms sein – nicht auf 1 setzen
Wave-Titel hängt / springt scoreboard.rainbow.speed reduzieren · Empfohlen: 10–30
Hex-Farben werden nicht angezeigt Titel ohne feste Farb-Codes schreiben: &lViper Network statt &6&lViper Network
News-Ticker stoppt kurz Normal – 4-Zeichen-Pause zwischen Durchläufen · scoreboard.news.speed erhöhen
Kompass nicht mittig COMPASS_WIN in der Quellcode-Konstante anpassen (Standard: 19)
too many queued packets update_interval zu niedrig – auf mind. 500ms erhöhen

StatusAPIBridge

Problem Mögliche Ursachen & Lösung
Herzen zeigen immer voll StatusAPIBridge nicht installiert oder statusapi-url falsch konfiguriert
Kompass bewegt sich nicht Bridge läuft, aber Spieler steht still – PlayerMoveEvent sendet nur bei Bewegung

BackendJoinGuard

Problem Mögliche Ursachen & Lösung
Spieler werden trotz Proxy geblockt Proxy-IP in allowed-proxy-ips korrekt eintragen · Bei mehreren Segmenten CIDR-Eintrag nutzen
Sync mit StatusAPI funktioniert nicht base-url und Port prüfen · api-key muss identisch zu backendguard.sync.api_key sein
Reference in New Issue View Git Blame Copy Permalink