From 9b3346c99da90c266d4566d9aaa28d89d5a7c1d0 Mon Sep 17 00:00:00 2001 From: M_Viper Date: Thu, 21 May 2026 16:51:10 +0000 Subject: [PATCH] README.md aktualisiert --- README.md | 1806 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 1125 insertions(+), 681 deletions(-) diff --git a/README.md b/README.md index 78e3dd7..ab164cb 100644 --- a/README.md +++ b/README.md @@ -1,772 +1,1216 @@ -# StatusAPI +# StatusAPI – BungeeCord Plugin -

- - - - -

+> **Version:** 4.1.2 · **Autor:** M_Viper · **Plattform:** BungeeCord · **Minecraft:** 1.20+ -

- 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, Ticket-Daten 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. +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 -- [StatusAPI](#statusapi-1) - - [Module](#module) - - [HTTP API](#http-api) - - [Commands](#commands-statusapi) - - [Permissions](#permissions-statusapi) - - [Konfiguration](#konfiguration-statusapi) -- [ScoreboardModule](#scoreboardmodule) - - [Features](#features-scoreboard) - - [Placeholders](#placeholders) - - [Konfiguration](#konfiguration-scoreboard) - - [Commands](#commands-scoreboard) -- [StatusAPIBridge](#statusapibridge) -- [BackendJoinGuard](#backendjoinguard-1) - - [Betriebsarten](#betriebsarten) - - [Commands & Permissions](#commands--permissions-backendjoinguard) - - [Konfiguration](#konfiguration-backendjoinguard) -- [TicketSystem-Integration](#ticketsystem-integration) -- [Voraussetzungen & Installation](#voraussetzungen--installation) -- [Troubleshooting](#troubleshooting) +1. [Voraussetzungen](#1-voraussetzungen) +2. [Installation](#2-installation) +3. [Konfigurationsdateien im Überblick](#3-konfigurationsdateien-im-überblick) +4. [Module](#4-module) + - [4.1 ChatModule](#41-chatmodule) + - [4.2 ScoreboardModule](#42-scoreboardmodule) + - [4.3 TablistModule](#43-tablistmodule) + - [4.4 AntiBotModule](#44-antibotmodule) + - [4.5 MultiAccountGuard](#45-multiaccountguard) + - [4.6 NetworkInfoModule](#46-networkinfomodule) + - [4.7 VanishModule](#47-vanishmodule) + - [4.8 VerifyModule](#48-verifymodule) + - [4.9 ForumBridgeModule](#49-forumbridgemodule) + - [4.10 BroadcastModule](#410-broadcastmodule) + - [4.11 AutoMessageModule](#411-automessagemodule) + - [4.12 CommandBlockerModule](#412-commandblockermodule) + - [4.13 ServerSwitcherModule](#413-serverswitchermodule) + - [4.14 EconomyModule](#414-economymodule) + - [4.15 StatsModule](#415-statsmodule) + - [4.16 CustomCommandModule](#416-customcommandmodule) +5. [HTTP-API](#5-http-api) +6. [Globales Rate-Limit-Framework](#6-globales-rate-limit-framework) +7. [Update-Checker](#7-update-checker) +8. [Befehle & Permissions – Komplette Referenz](#8-befehle--permissions--komplette-referenz) +9. [LuckPerms Integration](#9-luckperms-integration) +10. [Geyser / Bedrock Support](#10-geyser--bedrock-support) +11. [StatusAPIBridge (Backend-Integration)](#11-statusapibridge-backend-integration) +12. [Debug-Modus](#12-debug-modus) +13. [Emoji-Liste](#13-emoji-liste) +14. [Häufige Fragen & Fehlerbehebung](#14-häufige-fragen--fehlerbehebung) --- -## StatusAPI +## 1. Voraussetzungen -### 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 und Supporter-Scoreboard mit eigenen Zeilen und Permissions -- `/sb`-Command zum Ein-/Ausblenden und Umschalten zwischen Player/Supporter/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` - -
+| 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 | --- -### HTTP API +## 2. Installation -Basis-URL: `http://:9191` – Port konfigurierbar über `statusapi.port`. +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. -| Methode | Pfad | Beschreibung | Auth | +> **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: +> ```yaml +> 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 | +| `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 | +| `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 | |---|---|---|---| -| `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 | -| `POST` | `/ticket/update` | TicketSystem-Daten aktualisieren (von StatusAPIBridge) | intern | +| `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 -### Commands (StatusAPI) +Server-Farben sind ebenfalls pro Server in `chat.yml` unter `server-colors:` konfigurierbar – sowohl mit `&`-Codes als auch mit Hex-Farben (`&#RRGGBB`). -#### Netzwerk & Schutz +**Private Nachrichten** -| Command | Beschreibung | -|---|---| -| `/netinfo` | Netzwerk- und Systemstatus anzeigen | -| `/antibot status` | AntiBot-Status anzeigen | -| `/antibot clearblocks` | Alle aktiven IP-Blocks entfernen | -| `/antibot unblock ` | Einzelne IP entblocken | -| `/antibot profile ` | Profil wechseln und speichern | -| `/antibot reload` | AntiBot-Konfiguration neu laden | +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. -#### Verify & Forum +**Spieler-Ignore (Blocking)** -| Command | Beschreibung | -|---|---| -| `/verify ` | Account verifizieren | -| `/forumlink ` | Account mit Forum verknüpfen | -| `/forum` | Forum-Benachrichtigungen anzeigen | +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. -#### Chat, Support & Moderation +**Mute-System** -| Command | Beschreibung | -|---|---| -| `/channel [kanal]` | Kanal wechseln oder Liste anzeigen | -| `/helpop ` | Support-Anfrage an Team | -| `/msg ` | Private Nachricht senden | -| `/r ` | Auf letzte PM antworten | -| `/ignore ` | Spieler ignorieren | -| `/unignore ` | Ignore entfernen | -| `/chatmute [minuten]` | Spieler muten | -| `/chatunmute ` | Mute aufheben | -| `/chataus` | Chat-Empfang toggeln | -| `/broadcast ` | Broadcast an alle senden | -| `/emoji` | Emoji-Liste anzeigen | -| `/socialspy` | PMs mitlesen toggeln | -| `/chatreload` | Chat-Konfiguration neu laden | -| `/chatinfo ` | 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 ` | Verknüpfung aufheben | -| `/report ` | Spieler melden | -| `/reports [all]` | Reports ansehen | -| `/reportclose ` | Report schließen | +Admins mit der Permission `chat.mute` können Spieler mit `/chatmute [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. -#### CommandBlocker +**Selbst-Stummschaltung** -| Command | Beschreibung | -|---|---| -| `/cb add ` | Command blockieren | -| `/cb remove ` | Blockierung aufheben | -| `/cb list` | Alle blockierten Commands anzeigen | -| `/cb reload` | CommandBlocker neu laden | +Spieler können ihren eigenen Chat-Empfang mit `/chataus` ein- und ausschalten, ohne andere zu beeinflussen. -#### CustomCommands +**Chat-Filter** -| Command | Beschreibung | -|---|---| -| `/bcmds` | `customcommands.yml` neu laden | -| `/chat ` | Text als Chat senden oder Slash-Command ausführen | +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. -### Permissions (StatusAPI) +Spieler mit der Permission `chat.filter.bypass` sind von allen Filtern ausgenommen. -| 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`) | +**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). -### Konfiguration (StatusAPI) +**Mentions (@Spielername)** -#### `verify.properties` – Core, Verify, Broadcast, Forum, Port +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. -```properties -statusapi.port=9191 -wp_verify_url=https://deine-domain.tld -server..id= -server..secret= -broadcast.enabled=true -broadcast.api_key= -forum.enabled=true -forum.api_secret= -automessage.enabled=true -automessage.interval=300 -automessage.file=messages.txt -automessage.prefix=&8[&bInfo&8] +**HelpOp** + +Spieler können mit `/helpop ` 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 ` 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 ` 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 ` 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):** + +```yaml +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 ``` -#### `network-guard.properties` – NetworkInfo, Webhook, AntiBot, BackendJoinGuard +--- + +### 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: ```properties -networkinfo.enabled=true -networkinfo.webhook.enabled=true -networkinfo.webhook.url= -networkinfo.webhook.embed_mode=detailed -networkinfo.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= -``` - -#### 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. - -Es gibt drei separate Scoreboards, die automatisch anhand der Spieler-Permission zugewiesen werden: - -| Board | Permission | Beschreibung | -|---|---|---| -| Spieler-Board | *(keine)* | Standard-Scoreboard für alle Spieler | -| Supporter-Board | `statusapi.scoreboard.supporter` | Zeigt Ticket-Übersicht und Support-relevante Infos | -| Admin-Board | `statusapi.scoreboard.admin` | Vollständige Server- und Ticket-Statistiken | - -> Admin hat Vorrang vor Supporter – hat ein Spieler beide Permissions, sieht er das Admin-Board. - ---- - -### 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), nur im Spieler-Board -- **Zeilenrotation** – pro Zeile bis zu 20 Varianten, wechseln automatisch -- **Drei Scoreboards** – Spieler, Supporter, Admin – je eigenes Objective, Titel und Zeilen -- **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 (nur Spieler-Board) | -| `%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 | - -#### TicketSystem-Placeholders - -Werden alle 5 Sekunden von **StatusAPIBridge** über `POST /ticket/update` an StatusAPI gesendet. Voraussetzung: **TicketSystem** läuft auf demselben Backend-Server wie StatusAPIBridge. - -| Placeholder | Verfügbar für | Beschreibung | -|---|---|---| -| `%ticket_my_open%` | Spieler, Supporter, Admin | Eigene aktive Tickets (OPEN + CLAIMED + FORWARDED) | -| `%ticket_open%` | Supporter, Admin | Alle unbearbeiteten Tickets (Status: OPEN) | -| `%ticket_claimed%` | Admin | Alle Tickets in Bearbeitung (Status: CLAIMED) | -| `%ticket_rating_good%` | Admin | Positive Bewertungen gesamt | -| `%ticket_rating_bad%` | Admin | Negative Bewertungen gesamt | -| `%ticket_rating_pct%` | Admin | Prozentsatz positiver Bewertungen (oder `-` wenn keine) | - -#### 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` - -```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.supporter_title=&l[Support] Panel -scoreboard.admin_permission=statusapi.scoreboard.admin -scoreboard.supporter_permission=statusapi.scoreboard.supporter - -# 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 (nur Spieler-Board) -scoreboard.news.text=Willkommen auf Viper Network! -scoreboard.news.prefix=&8[&6News&8] &r -scoreboard.news.width=20 -scoreboard.news.speed=1 - -# Zeilenrotation (Sekunden pro Variante) -scoreboard.rotation_interval=4 - -# Separator für %line% -scoreboard.separator=&8&m-------------------- - -# =================================================== -# SPIELER-ZEILEN (max. 15 sichtbar) -# scoreboard.lines.N = Variante 1 (dauerhaft) -# scoreboard.lines.N.2 = Variante 2 (rotiert nach rotation_interval Sekunden) -# =================================================== -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: B4513%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% - -# =================================================== -# SUPPORTER-ZEILEN -# =================================================== -scoreboard.supporter_lines.1=%line% -scoreboard.supporter_lines.2=%gradient:&6:&f:&6:&l> Support Panel:% -scoreboard.supporter_lines.3=&7%rank% &f%player% -scoreboard.supporter_lines.4=&7Ping: &f%ping%ms &8| &7%server% -scoreboard.supporter_lines.5= -scoreboard.supporter_lines.6=%gradient:&6:&f:&6:&l> Tickets:% -scoreboard.supporter_lines.7=&7Offen: &c%ticket_open% -scoreboard.supporter_lines.8=&7Meine Tickets: &e%ticket_my_open% -scoreboard.supporter_lines.9= -scoreboard.supporter_lines.10=%gradient:&6:&f:&6:&l> Server Info:% -scoreboard.supporter_lines.11=&7Online: &f%online% &8/ &7%maxplayers% -scoreboard.supporter_lines.12=&7Zeit: &f%time% -scoreboard.supporter_lines.13= -scoreboard.supporter_lines.14=%line% -scoreboard.supporter_lines.15=&7%compass% - -# =================================================== -# ADMIN-ZEILEN -# =================================================== -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: B4513%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=%gradient:&b:&f:&b:&l> Tickets:% -scoreboard.admin_lines.13=&7Offen: &c%ticket_open% &8| &7Aktiv: &e%ticket_claimed% -scoreboard.admin_lines.14=&7Bewertung: &a%ticket_rating_good%&8/&c%ticket_rating_bad% &7(&f%ticket_rating_pct%&7%&7) -scoreboard.admin_lines.15=%line% -scoreboard.admin_lines.15.2=&7%compass% ``` -#### Separator-Stile +Der Rotationsintervall wird über `scoreboard.rotation_interval` (Sekunden) gesteuert. -| Stil | Wert | +**Platzhalter – Spieler-Scoreboard:** + +| Platzhalter | Beschreibung | |---|---| -| 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)* | +| `%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. + +```properties +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):** + +```properties +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 +``` --- -### Commands (Scoreboard) +### 4.3 TablistModule -| Command | Aliase | Beschreibung | -|---|---|---| -| `/scoreboard` | `/sb`, `/togglesb` | Scoreboard ein-/ausblenden (Toggle) | -| `/sb hide` | | Scoreboard ausblenden | -| `/sb show` | | Scoreboard einblenden | -| `/sb player` | | Spieler-Scoreboard anzeigen | -| `/sb supporter` | | Supporter-Scoreboard anzeigen (Permission erforderlich) | -| `/sb admin` | | Admin-Scoreboard anzeigen (Permission erforderlich) | +Das TablistModule gestaltet die Tab-Liste (Spielerliste) des Netzwerks vollständig. -**Permissions:** +**Layout-Modi** -| Permission | Beschreibung | -|---|---| -| `statusapi.scoreboard.admin` | Admin-Scoreboard + `/sb admin` | -| `statusapi.scoreboard.supporter` | Supporter-Scoreboard (automatisch, kein Command nötig) | +- `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%`. --- -## StatusAPIBridge +### 4.4 AntiBotModule -StatusAPIBridge läuft auf jedem **Backend-Server** (Spigot/Paper) und sendet Spielerdaten in Echtzeit an StatusAPI. +Das AntiBotModule schützt das Netzwerk vor automatisierten Bot-Angriffen (Verbindungs-Floods). Es überwacht die Verbindungsrate in Echtzeit. -### Gesendete Daten +**Profile** -| Datenpunkt | Endpunkt | Beschreibung | +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 | |---|---|---| -| 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 | -| TicketSystem-Daten | `POST /ticket/update` | Ticket-Statistiken (alle 5 Sekunden, falls TicketSystem installiert) | +| `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 | -### TicketSystem-Daten (automatisch) +**Lernmodus (adaptives Scoring)** -Ist das **TicketSystem**-Plugin auf demselben Backend-Server installiert, liest StatusAPIBridge die Daten per Reflection und sendet sie alle 5 Sekunden: +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). -- Globale Werte (Anzahl offener Tickets, Tickets in Bearbeitung, Bewertungen) – nur bei Änderung -- Pro Spieler: Anzahl eigener aktiver Tickets (OPEN + CLAIMED + FORWARDED) +| 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 | -Es wird keine harte Abhängigkeit zum TicketSystem benötigt – fehlt es, passiert nichts. +**VPN/Proxy-Check** -### Konfiguration (StatusAPIBridge) +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. -Datei: `plugins/StatusAPIBridge/config.yml` +**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 – Eine einzelne IP entsperren +/antibot profile – Profil wechseln +/antibot reload – Konfiguration neu laden +``` + +**Vollständige Konfiguration in `network-guard.properties`:** + +```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 permission set statusapi.multiaccountguard.bypass true +> ``` + +**Vollständige Konfiguration in `network-guard.properties`:** + +```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. + +```properties +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 ` 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`:** + +```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 ` 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`:** + +```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 – Netzwerkweiten Broadcast senden (Permission: chat.broadcast) +/bc – Alias +/alert – 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`:** + +```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`:** + +```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 blockieren +/cb remove – Befehl entsperren +/cb reload – Konfiguration neu laden +``` + +**Konfiguration in `verify.properties`:** + +```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 ` 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`:** + +```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`:** + +```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=` oder `GET /stats/player?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) +``` + +--- + +## 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`:** + +```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:** +```bash +curl http://localhost:9191/ +``` + +**Sofortigen Broadcast senden:** +```bash +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):** +```bash +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:** +```bash +curl -X POST http://localhost:9191/broadcast/cancel \ + -H "Content-Type: application/json" \ + -d '{"clientScheduleId": "daily-evening-msg"}' +``` + +**Spielerstatistiken abrufen:** +```bash +curl "http://localhost:9191/stats/player?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 ` | – | `statusapi.antibot` | Einzelne IP entsperren | +| `/antibot profile ` | – | `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 ` | – | `commandblocker.admin` | Befehl blockieren | +| `/cb remove ` | – | `commandblocker.admin` | Befehl entsperren | +| `/cb reload` | – | `commandblocker.admin` | CommandBlocker neu laden | + +### Chat-Befehle + +| Befehl | Aliases | Permission | Beschreibung | +|---|---|---|---| +| `/channel [name]` | `/ch`, `/kanal` | je nach Kanal | Kanal wechseln oder Kanalliste anzeigen | +| `/helpop ` | – | – | Hilfeanfrage an das Team senden | +| `/msg ` | `/tell`, `/w`, `/whisper` | – | Private Nachricht senden | +| `/r ` | `/reply`, `/antwort` | – | Auf letzte private Nachricht antworten | +| `/ignore ` | `/block` | – | Spieler ignorieren | +| `/unignore ` | `/unblock` | – | Spieler nicht mehr ignorieren | +| `/chatmute [Min.]` | `/gmute` | `chat.mute` | Spieler stummschalten | +| `/chatunmute ` | `/gunmute` | `chat.mute` | Stummschaltung aufheben | +| `/chataus` | `/togglechat`, `/chaton`, `/chatoff` | – | Eigenen Chat-Empfang umschalten | +| `/broadcast ` | `/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 ` | – | `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 ` | – | `chat.report` | Spieler melden | +| `/reports [all]` | – | `chat.admin.bypass` | Offene Reports anzeigen | +| `/reportclose ` | – | `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 ` | – | 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 | + +### Forum & Verify + +| Befehl | Aliases | Beschreibung | +|---|---|---| +| `/verify ` | – | Account mit WordPress-Forum verifizieren | +| `/forumlink ` | `/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.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 | +| `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`:** + +```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`: ```yaml -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) +emoji: + mappings: + ":meinEmoji:": "\uD83E\uDD84" # 🦄 Einhorn ``` --- -## BackendJoinGuard +## 14. Häufige Fragen & Fehlerbehebung -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. +**Der HTTP-Server startet nicht / Port belegt** -> **Wichtig:** BackendJoinGuard kommt auf **jeden Backend-Server**, nicht auf den Proxy. +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.)** -### Betriebsarten +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. -| 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 | +**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. -### Commands & Permissions (BackendJoinGuard) +**Die Economy zeigt überall 0 an** -| Command | Permission | Beschreibung | -|---|---|---| -| `/backendguard reload` | `backendguard.admin` | Config neu laden und bei aktivem Sync sofort neu abrufen | +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)** -### Konfiguration (BackendJoinGuard) - -Datei: `plugins/BackendJoinGuard/config.yml` - -#### Lokaler Schutz - -```yml -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" +Weise diesen Spielern die Permission manuell zu: +``` +lp user permission set statusapi.multiaccountguard.bypass true ``` -#### StatusAPI Sync +**Die Discord/Telegram-Bridge sendet keine Nachrichten** -```yml -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 -``` +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? -#### Typische Szenarien +**`/statusapi reload` lädt nicht alle Einstellungen neu** -| 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` | +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** -## TicketSystem-Integration +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). -StatusAPI und StatusAPIBridge unterstützen eine optionale Integration mit dem **TicketSystem**-Plugin. Die Verbindung ist vollständig Reflection-basiert – es sind keine harten Abhängigkeiten nötig. +**VPN/Proxy-Check blockiert zu viele legitime Spieler** -### Architektur - -``` -TicketSystem (Bukkit) - ↓ Reflection (alle 5s) -StatusAPIBridge → POST /ticket/update → StatusAPI (BungeeCord) → Scoreboard -``` - -### Voraussetzungen - -- TicketSystem ist auf demselben Backend-Server installiert wie StatusAPIBridge -- StatusAPIBridge sendet die Daten automatisch – keine zusätzliche Konfiguration nötig - -### Verfügbare Placeholder im Scoreboard - -| Placeholder | Für wen | Beschreibung | -|---|---|---| -| `%ticket_my_open%` | Spieler, Supporter, Admin | Eigene aktive Tickets (OPEN + CLAIMED + FORWARDED) | -| `%ticket_open%` | Supporter, Admin | Alle offenen Tickets (noch unbearbeitet) | -| `%ticket_claimed%` | Admin | Alle Tickets in Bearbeitung | -| `%ticket_rating_good%` | Admin | Positive Bewertungen gesamt | -| `%ticket_rating_bad%` | Admin | Negative Bewertungen gesamt | -| `%ticket_rating_pct%` | Admin | Prozentsatz positiver Bewertungen | - -### PlaceholderAPI (PAPI) - -Das TicketSystem selbst stellt über die Klasse `TicketPlaceholderExpansion` ebenfalls PAPI-Placeholder bereit (Prefix: `ticketsystem`): - -| PAPI-Placeholder | Beschreibung | -|---|---| -| `%ticketsystem_my_open%` | Eigene aktive Tickets des Spielers | -| `%ticketsystem_admin_open%` | Alle offenen Tickets (Status: OPEN) | -| `%ticketsystem_admin_claimed%` | Alle Tickets in Bearbeitung (Status: CLAIMED) | -| `%ticketsystem_admin_rating_good%` | Positive Bewertungen gesamt | -| `%ticketsystem_admin_rating_bad%` | Negative Bewertungen gesamt | -| `%ticketsystem_admin_rating_total%` | Alle Bewertungen gesamt | -| `%ticketsystem_admin_rating_percent%` | Prozentsatz positiver Bewertungen | - -> Diese PAPI-Placeholder sind unabhängig von StatusAPI und können in jedem PAPI-kompatiblen Plugin genutzt werden (z.B. andere Scoreboard-Plugins, Chat-Plugins). - ---- - -## Voraussetzungen & Installation - -### Voraussetzungen - -| Komponente | Pflicht | Optional | -|---|---|---| -| BungeeCord Proxy | ✅ | | -| Minecraft 1.20+ | ✅ | | -| Java 8+ | ✅ | | -| LuckPerms | | ✅ | -| Geyser-BungeeCord | | ✅ | -| Discord Webhook / Bot | | ✅ | -| Telegram Bot | | ✅ | -| WordPress / Forum-Backend | | ✅ | -| TicketSystem (Bukkit) | | ✅ | -| PlaceholderAPI (Bukkit) | | ✅ | - -### 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 | -| Supporter-Board wird nicht angezeigt | Permission `statusapi.scoreboard.supporter` prüfen · `scoreboard.supporter_permission` in `scoreboard.properties` prüfen | -| Supporter sieht Admin-Board | Normal – Admin-Permission hat Vorrang über Supporter-Permission | - -### 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 | -| Ticket-Placeholder zeigen immer 0 | TicketSystem nicht auf demselben Server wie StatusAPIBridge · Konsole auf `[TicketPush]`-Fehler prüfen | - -### 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 | \ No newline at end of file +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. \ No newline at end of file