Dracovia (unbrokenSMP) + DracoviaBridge

Server-Plugin für den Minecraft-Multiplayer-Server Dracovia auf Basis von Paper mit integrierter DracoviaBridge zur automatischen, asynchronen Telemetrie-Synchronisation mit der begleitenden Next.js-Webseite.

---

1. Plattform & Toolchain

• Server-Plattform: Paper API 26.3 (Minecraft 26.3)
• Java-Version: Java 25 Toolchain (kompatibel mit OpenJDK 25–27)
• Buildsystem: Gradle 9.8 mit Kotlin DSL (build.gradle.kts) und Gradle-Wrapper (gradlew)
• Laufzeit-Bibliotheken: org.xerial:sqlite-jdbc:3.50.3.0 (dynamisch über Papers libraries-System bereitgestellt)

---

2. Architektur & Bridge-Komponenten

Die Bridge sammelt Server- und Spielerdaten und überträgt diese ausschließlich über ausgehende HTTPS-Requests an die Webanwendung:

+-------------------------------------------------------------+
|                     Minecraft Server                        |
|                                                             |
|  +---------------------+        +------------------------+  |
|  | BridgeListener      |        | StatsCollector         |  |
|  | (Joins/Leaves/      |        | (Kumulative Statistiken|  |
|  | Deaths/Advancements)|        | über Ticks gestaffelt) |  |
|  +----------+----------+        +-----------+------------+  |
|             |                               |               |
|             +-------------->+<--------------+               |
|                             | (Unveränderliche Schnapp-     |
|                             v  schüsse & Event-Datensätze)  |
|                     +---------------+                       |
|                     | BridgeService |                       |
|                     +-------+-------+                       |
|                             |                               |
|        +--------------------+-------------------+           |
|        | (Hintergrund-Worker)                   |           |
|        v                                        v           |
|  +-----------+                           +--------------+   |
|  | SQLite    |                           | JDK HTTP     |   |
|  | Outbox    +--[Batching & Retries]---->| Client       |   |
|  | (outbox.db)                           | (HTTPS POST) |   |
|  +-----------+                           +------+-------+   |
+-------------------------------------------------|-----------+
                                                  | Outbound
                                                  v HTTPS
                                     +------------------------+
                                     | Dracovia Next.js Web   |
                                     | Ingest & Health API    |
                                     +------------------------+

Kern-Eigenschaften:

• Thread-Sicherheit: Spielwelt- und Spielerdaten werden ausschließlich auf dem Bukkit-Server-Thread gelesen. Sämtliche Serialisierungs-, SQLite- und HTTP-Operationen laufen auf einem separaten Hintergrund-Worker. Der Server-Thread wartet niemals auf Antworten der Website.
• Dauerhafte SQLite-Outbox (outbox.db):
  • Requests werden vor dem Senden persistent gespeichert und erst nach passender Bestätigung (accepted / duplicate) gelöscht.
  • Monotoner Sequenzzähler je Server/Season, der Neustarts überdauert und bei Start mit dem Health-Endpunkt der Website abgeglichen wird.
  • Veraltete Heartbeats und Stats-Snapshots werden durch neuere ersetzt (Coalescing), während Gameplay-Events lückenlos und in Erfassungsreihenfolge erhalten bleiben.
  • Begrenzung: Standardmäßig max. 10.000 Events, 64 MiB Speicherplatz und 7 Tage Aufbewahrung.
• Ausfallsicherheit & Backoff: Exponentieller Backoff mit Jitter für 429/5xx/Netzwerkfehler; automatische Auswertung von Retry-After. Quarantäne für unkorrigierbare Schemafehler.
• Datenschutz & Minimalismus: Keine Übertragung von Chatnachrichten, Konsolenbefehlen, IP-Adressen, Inventarinhalten oder exakten Spielerkoordinaten.

---

3. Konfiguration

Die Einstellungen befinden sich in plugins/unbrokenSMP/config.yml (Abschnitt bridge:):

bridge:
  website-url: "https://dracovia.example"
  server-id: "dracovia-main"
  season-id: "season-1"
  token: ""                     # Token oder Umgebungsvariable DRACOVIA_INGEST_TOKEN
  allow-insecure-http: false    # Nur für lokales Testen auf localhost gestattet

  heartbeat-seconds: 15
  stats-seconds: 60
  events-flush-seconds: 5
  stats-players-per-tick: 2     # Verteilt Leseoperationen über Ticks

  connect-timeout-seconds: 5
  request-timeout-seconds: 15
  backoff-initial-seconds: 2
  backoff-max-seconds: 120

  outbox:
    max-events: 10000
    max-size-mib: 64
    max-age-days: 7             # Maximal 29 Tage (< 30 Tage Website-Retention)

  debug: false

Sicherheit: Das Ingestion-Token darf niemals in öffentliche Repositories committet oder in Chatbefehlen übergeben werden. Auf Produktionsservern empfiehlt sich die Umgebungsvariable DRACOVIA_INGEST_TOKEN.

---

4. Befehle & GUI-Integration

Operator-Befehle (Berechtigung: dracovia.bridge.admin):

• /dracovia status — Zeigt Verbindungsstatus, Host, Scope, letzte Quittung, Outbox-Größe und Fehlerstatistiken (Secrets stets maskiert).
• /dracovia test — Prüft den Health-Endpunkt der Website asynchron.
• /dracovia sync — Plant sofort einen Heartbeat- und Statistik-Schnappschuss ein.
• /dracovia reload — Lädt die config.yml neu und startet den Hintergrund-Worker sicher neu.

GUI-Integration:

• Über /via (Main Control) gelangen Administratoren unten rechts in der Werkzeugleiste (Slot 26, Leuchtfeuer-Item) direkt in das Website-Bridge-Menü.
• Bietet Ein-Klick-Aktionen für Statusanzeige, Verbindungstest, Schnappschuss-Synchronisation und Konfigurations-Reload nach dem einheitlichen GUI-Design des Plugins (3 Zeilen, Werkzeugleiste mit schwarzem Glas, Zurück-Pfeil).

---

5. Build & Installation

Kompilieren:

./gradlew build

Das fertige Release-JAR liegt unter: build/libs/Dracovia-1.0-SNAPSHOT.jar

Installation:

1. Dracovia-1.0-SNAPSHOT.jar in das plugins/-Verzeichnis des Paper-Servers kopieren.
2. Server starten, um die Standard-Konfiguration zu generieren.
3. In plugins/unbrokenSMP/config.yml die website-url, server-id, season-id und token eintragen (oder DRACOVIA_INGEST_TOKEN in der Systemumgebung setzen).
4. Mit /dracovia reload die Einstellungen aktivieren.
5. Mit /dracovia status oder /dracovia test die Verbindung prüfen.

---

6. Protokoll-Spezifikation & Test-Harness

• Vollständige Spezifikation: protocol/PROTOCOL.md
• JSON-Schema: protocol/dracovia-v1.schema.json
• Test-Fixtures: protocol/fixtures/
• Integrierter Mock-Server: de.dernickl.dracovia.bridge.test.MockReceiver

Mock-Receiver lokal ausführen:

./gradlew test --tests "*IntegrationMockServerTest*"

---

7. Fehlerbehebung (Troubleshooting)

Problem	Ursache	Lösung
Status: Nicht konfiguriert	URL oder Token fehlen/ungültig	website-url und token in config.yml prüfen.
HTTP 401 (Unauthorized)	Ungültiges oder abgelaufenes Token	Token im Dashboard der Website neu generieren und eintragen.
HTTP 403 (Scope Mismatch)	Token gehört nicht zu serverId/seasonId	server-id und season-id mit den Webseiten-Einstellungen abgleichen.
HTTP 301/302 Redirect	URL leitet weiter (z. B. http -> https)	Kanonische Ziel-URL direkt eintragen. Redirects mit Auth-Headern werden aus Sicherheitsgründen blockiert.
TLS / SSL Handshake Error	Zertifikat ungültig oder abgelaufen	HTTPS-Zertifikat der Webanwendung erneuern/prüfen.
HTTP 429 (Too Many Requests)	Rate-Limit der Website erreicht	Plugin drosselt automatisch via Retry-After. Intervalle ggf. erhöhen.
Statistiken nach Season-Wechsel	Season-ID geändert	Neue Season-ID partitioniert Daten auf der Website. Minecraft-Statistiken sind dauerhaft kumulativ und werden nicht zurückgesetzt.

---

8. Smoke-Test-Checkliste (Paper Server)

• Start: Server startet; initiales server_started-Event wird in Outbox eingereiht.
• Status: /dracovia status zeigt Verbindung zu website-url und korrekte Scopes.
• Join: Spieler betritt Server; player_join-Event und initialer Snapshot werden übertragen.
• Aktivität: Blöcke abbauen, Schaden nehmen, Distanz laufen; regulärer Heartbeat (15s) und Stats-Snapshot (60s) erfassen veränderte Werte.
• Advancement: Sichtbaren Fortschritt erzielen; player_advancement wird mit Key und Titel erfasst.
• Tod: Spieler stirbt; Todesnachricht wird als Plain-Text übermittelt.
• Quit: Spieler verlässt den Server; finaler Stats-Snapshot und player_leave-Event werden generiert.
• Netzwerkausfall: Website-Empfänger stoppen; Events sammeln sich in outbox.db. Nach Wiederherstellung sendet das Plugin frischen Heartbeat und leert die Outbox ohne Duplikate.
• Stop: Server stoppt sauber; Abschluss-Heartbeat (state: "stopping") und server_stopped-Event werden best-effort übermittelt.