# StatusAPI – BungeeCord Plugin

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

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

---

## Inhaltsverzeichnis

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)
   - [4.17 HelpModule](#417-helpmodule)
   - [4.18 AfkModule](#418-afkmodule)
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)

---

## 1. Voraussetzungen

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

---

## 2. Installation

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

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

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

---

## 4. Module

### 4.1 ChatModule

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

**Kanalsystem**

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

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

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

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

**Private Nachrichten**

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

**Spieler-Ignore (Blocking)**

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

**Mute-System**

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

**Selbst-Stummschaltung**

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

**Chat-Filter**

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

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

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

**Emoji-Unterstützung**

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

**Mentions (@Spielername)**

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

**HelpOp**

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

**Report-System**

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

**Chat-Log**

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

**Nachrichten-IDs**

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

**Discord-Bridge**

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

**Telegram-Bridge**

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

**Account-Verknüpfung**

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

**Join/Leave-Nachrichten**

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

**Secure Chat Kompatibilität**

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

**ChatBypass**

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

**Wichtige Einstellungen in `chat.yml` (Auszug):**

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

---

### 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
scoreboard.lines.5=&7Spielzeit: &f%playtime%
scoreboard.lines.5.2=&7Leben: &c%health%
scoreboard.lines.5.3=&7Hunger: &#8B4513%foodsym%
```

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

**Platzhalter – Spieler-Scoreboard:**

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

**Zusätzliche Platzhalter – Admin-Scoreboard:**

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

**Ticket-Platzhalter (Supporter/Admin):**

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

**Gradient-Unterstützung**

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

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

---

### 4.3 TablistModule

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

**Layout-Modi**

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

**Spalten-Header-Modi**

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

**Spieler-Anzeige-Modi**

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

**Server-Symbole**

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

**Skin-Cache**

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

**Tab-Größe**

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

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

**Header und Footer**

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

---

### 4.4 AntiBotModule

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

**Profile**

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

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

**Lernmodus (adaptives Scoring)**

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

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

**VPN/Proxy-Check**

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

**Pro-IP-Limiter**

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

**Sicherheitslog**

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

**Admin-Befehl `/antibot`:**

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

**Vollständige Konfiguration in `network-guard.properties`:**

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

---

### 4.5 MultiAccountGuard

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

**Prüfmethoden (unabhängig aktivierbar):**

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

**Konfliktverhalten:**

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

**Temporärer IP-Bann:**

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

**Staff-Benachrichtigung:**

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

**Discord-Webhook:**

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

**Bypass-Permission:**

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

**Vollständige Konfiguration in `network-guard.properties`:**

```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 <token>` auf der Webseite ein.
4. Das Plugin sendet den Token an die WordPress-Instanz zur Verifikation.

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

**Konfiguration in `verify.properties`:**

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

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

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

> Servernamen werden **case-insensitiv** verglichen.

---

### 4.9 ForumBridgeModule

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

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

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

**Konfiguration in `verify.properties`:**

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

---

### 4.10 BroadcastModule

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

**Ingame-Befehl:**

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

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

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

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

**Geplante Broadcasts:**

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

**URLs in Broadcasts:**

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

**API-Key-Schutz:**

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

**Konfiguration in `verify.properties`:**

```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>       – Befehl blockieren
/cb remove <befehl>    – 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 <servername>` wechselt direkt zum angegebenen Server.

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

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

**Vollständige Konfiguration in `serverswitcher.properties`:**

```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=<UUID>` oder `GET /stats/player?name=<Name>` abgerufen werden. Updates kommen über `POST /stats/update` (Kills/Deaths via StatusAPIBridge) und `POST /punishment/update` (Straf-Daten).

---

### 4.16 CustomCommandModule

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

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

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

---

### 4.17 HelpModule

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

**Konfiguration in `verify.properties`:**

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

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

**Verwendung:**

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

**Seitenaufteilung:**

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

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

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

---

### 4.18 AfkModule

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

**Funktionen:**

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

**Nametag-Prefix**

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

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

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

**Title-Nachrichten-Paare**

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

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

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

Vorkonfigurierte Beispiele (Auszug aus dem Standard-Config):

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

**Title-Anzeige ohne Blinken**

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

**Gradient-Unterstützung**

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

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

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

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

**Befehl:**

```
/afk   – AFK-Status manuell ein-/ausschalten
```

**Vollständige Konfiguration in `afk.properties`:**

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

afk.enabled=true

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

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

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

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

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

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

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

---

## 5. HTTP-API

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

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

**Port-Konfiguration in `verify.properties`:**

```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=<UUID>"
```

---

## 6. Globales Rate-Limit-Framework

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

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

Konfigurierbare Parameter pro Scope:
- `window-ms` – Größe des Zeitfensters in Millisekunden
- `max-actions` – Maximale Aktionen innerhalb des Fensters
- `block-ms` – Blockierungsdauer in Millisekunden bei Überschreitung

---

## 7. Update-Checker

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

---

## 8. Befehle & Permissions – Komplette Referenz

### Admin-Befehle

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

### Ingame-Hilfe

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

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

### Chat-Befehle

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

### Account-Verknüpfung

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

### Scoreboard

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

### Vanish & Netzwerk

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

### AFK

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

### Forum & Verify

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

### Permissions-Referenz

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

---

## 9. LuckPerms Integration

StatusAPI nutzt LuckPerms als Soft-Dependency für:

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

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

**Empfohlene LuckPerms-Einrichtung:**

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

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

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

---

## 10. Geyser / Bedrock Support

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

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

---

## 11. StatusAPIBridge (Backend-Integration)

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

Die StatusAPIBridge sendet folgende Daten an den Proxy:

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

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

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

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

---

## 12. Debug-Modus

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

**Aktivierung in `verify.properties`:**

```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
emoji:
  mappings:
    ":meinEmoji:": "\uD83E\uDD84"   # 🦄 Einhorn
```

---

## 14. Häufige Fragen & Fehlerbehebung

**Der HTTP-Server startet nicht / Port belegt**

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

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

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

**Chat-Nachrichten werden von Paper abgelehnt**

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

**Die Economy zeigt überall 0 an**

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

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

Weise diesen Spielern die Permission manuell zu:
```
lp user <Name> permission set statusapi.multiaccountguard.bypass true
```

**Die Discord/Telegram-Bridge sendet keine Nachrichten**

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

**`/statusapi reload` lädt nicht alle Einstellungen neu**

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

**Tab-Liste zeigt nicht alle Spalten an**

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

**VPN/Proxy-Check blockiert zu viele legitime Spieler**

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

**Die Ingame-Hilfe zeigt den falschen Befehlsnamen**

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

**Spieler werden nicht automatisch AFK gesetzt**

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

**AFK-Title wird nicht angezeigt**

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

**AFK-Prefix erscheint nicht über dem Spieler-Kopf**

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