minecraft-atm10-stats/docs/superpowers/specs/2026-10-13-atm10-stats-design.md

ATM10 Stats – Design-Spezifikation

Stand: 2026-10-13 · Status: zur Freigabe

1. Ziel

Ein öffentliches, modernes Statistikportal für den bei Mine-Hoster gehosteten All-The-Mods-10-Server (ATM10). Vorbild für Inhalt und Anmutung ist craftattack.one/stats (Kennzahlen, „Gerade online“, Top-10-Listen); das Portal geht darüber hinaus mit Spielerprofilen, historischen Diagrammen und ATM10-spezifischen Auswertungen (Mods, FTB Quests, Servergesundheit).

Erfolgskriterien:

• Spieler sehen ihre echten Werte innerhalb weniger Sekunden (Ereignisse) bzw. ≤ 5 Minuten (Zähler) nach dem Geschehen.
• Keine erfundenen Daten: Jede angezeigte Kennzahl hat eine dokumentierte, nachprüfbare Quelle.
• Die Mod verursacht keine messbare Tick-Last; kein Datenverlust bei Neustarts von Gameserver oder Backend.
• Betrieb per Docker Compose hinter dem vorhandenen Traefik in der DMZ.

2. Verifizierte Ausgangslage

Quelle: server-snapshot/ (vom Betreiber per SFTP bereitgestellt).

Fakt	Beleg
Minecraft 1.21.1	DataVersion: 3955 in world/stats/*.json
NeoForge 21.1.x, Java 21	Modliste (*-neoforge-1.21.1-*), MC 1.21.1 setzt Java 21 voraus. Exakte NeoForge-/Java-Version: fehlt im Log-Ausschnitt → wird von der Mod beim Start ermittelt und gemeldet
464 Mod-JARs	mod-list.txt
FTB Quests 2101.1.36, FTB Teams 2101.1.11, FTB Chunks, FTB Ranks, FTB Essentials	mod-list.txt
Quest-Fortschritt pro Team als SNBT (task_progress, completed, started, claimed_rewards, completion_count)	world-ftbquests/*.snbt
Spark 1.10.124 installiert	mod-list.txt (wird nicht als API genutzt)
Log enthält Login (UUID + IP), Join/Leave, Advancements/Goals/Challenges im Klartext, „Can't keep up“	latest.log
Server läuft mit ~2,2 GB Heap und hat Lags bis 10 s	latest.log (AllTheLeaks, Can't keep up)
Mine-Hoster: SFTP-Vollzugriff, eigene Mods in mods/ möglich	Mine-Hoster-Support (SFTP-, Mods-, Modpack-Artikel)
Ausgehendes HTTPS vom Gameserver	unbekannt → Hybrid-Design (Push + SFTP-Pull)

Mod-spezifische Zähler, die bereits in Vanilla-Stats auftauchen: apotheosis:world_tiers_activated, lootr:looted_stat, waystones:waystone_activated. Item-/Block-Statistiken enthalten Einträge aus u. a. mekanism, powah, mysticalagriculture, ars_nouveau, irons_spellbooks, modern_industrialization, oritech, create, refinedstorage, draconicevolution, silentgear, occultism, theurgy, xycraft_world, minecolonies.

Nicht installiert (daher keine Integration): Blood Magic, Botania.

Datenschutz: latest.log enthält Spieler-IP-Adressen. server-snapshot/ wird nicht versioniert; Testfixtures aus dem Log werden anonymisiert (IP entfernt).

3. Architektur

 Mine-Hoster (ATM10, NeoForge 1.21.1)                 Eigener Server in der DMZ
 ┌──────────────────────────────┐   HTTPS POST    OPNsense → Traefik → Docker Compose
 │ atmstats (serverseitige Mod) │ ──────────────▶ ┌────────────────────────────────┐
 │  Event-Hooks, Outbox-Journal │  Bearer + HMAC  │ api     Fastify/TS: ingest,    │
 │  async Sender mit Backoff    │                 │         REST, SSE, admin       │
 └──────────────────────────────┘                 │ worker  SFTP-Pull, Snapshots,  │
        ▲ world/stats, world/ftbquests,           │         Retention              │
        │ config/ftbquests, logs                  │ web     Next.js (App Router)   │
        └───────────── SFTP-Pull ◀────────────────│ db      PostgreSQL 16          │
                                                  │ backup  pg_dump täglich        │
                                                  └────────────────────────────────┘

Monorepo:

mod/        NeoForge-Mod (Gradle, Java 21, ModDevGradle)
backend/    api + worker (TypeScript, Fastify, gemeinsamer Code, zwei Entrypoints)
web/        Next.js-Frontend (TypeScript)
shared/     gemeinsame TS-Typen + Zod-Schemas (Ingest-Protokoll, API-DTOs)
deploy/     docker-compose.yml, .env.example, Backup-Skript
tools/      Simulator (sendet realistische Mod-Batches), Fixture-Anonymisierer
docs/       README-Ergänzungen, ARCHITECTURE, DATA-SOURCES, OPERATIONS

3.1 Datenquellen und Zuständigkeit

Daten	Primärquelle	Fallback
Online-Status, Sessions	Mod: Login/Logout-Events	SFTP: Log-Parser (joined/left the game, UUID of player)
Gesamtzähler (Stats)	SFTP: world/stats/<uuid>.json (maßgeblich, absolut)	—
Zähler zwischen Speicherungen	Mod: 5-min-Snapshot der Live-ServerStatsCounter online Spieler (absolute Werte)	—
Tode (Ursache, Killer, Dimension, Position grob)	Mod: LivingDeathEvent	Log: nicht verlässlich (Death-Messages lokalisiert/mod-abhängig) → nur Zähler aus Stats
Spieler-/Boss-Kills mit Waffe/Dimension	Mod: LivingDeathEvent mit Spieler als Quelle	Stats minecraft:killed (nur Zähler)
Advancements	Mod: AdvancementEvent.AdvancementEarnEvent	Log-Parser (has made the advancement/reached the goal/completed the challenge)
Dimensionswechsel	Mod: PlayerChangedDimensionEvent	—
FTB-Quest-Fortschritt	Mod liest world/ftbquests/*.snbt (eigener Thread, nur bei Änderung)	SFTP: dieselben Dateien
Quest-Definitionen (Kapitel, Titel)	Mod liest config/ftbquests/quests/** beim Start	SFTP
Teams	SNBT-Dateien von FTB Teams/Quests (world/ftbteams/ wird beim Bau verifiziert)	SFTP
Versionen, Modliste	Mod: ModList, SharedConstants, System.getProperty("java.version") beim Start	Log-Header (falls vorhanden)
Servergesundheit (MSPT/TPS, Spieler, geladene Chunks, Heap)	Mod: eigene Messung über ServerTickEvent.Pre/Post, 60-s-Aggregat	Log: „Can't keep up“-Zählung

Konfliktregel für Zähler: Werte sind absolut (nicht Deltas). stat_current übernimmt pro Schlüssel den Wert mit dem neuesten Beobachtungszeitpunkt; ein kleinerer Wert ersetzt einen größeren nur, wenn er aus einer neueren Stats-Datei stammt (z. B. nach Admin-Reset). Damit sind wiederholte und verspätete Lieferungen unschädlich.

Quest-Texte: Titel können als Übersetzungsschlüssel vorliegen (ftbquestslangsplitter ist installiert). Die Mod liest zusätzlich config/ftbquests/quests/lang/en_us.snbt bzw. die Lang-Dateien, falls vorhanden; sonst wird die Quest-ID angezeigt. Exakte Pfade werden in der Umsetzung anhand einer Kopie von config/ftbquests/ verifiziert, bevor der Parser fest verdrahtet wird.

3.2 Bewusst nicht unterstützt

Ohne verlässliche, dokumentierte serverseitige Quelle oder nur mit ungeprüften Mod-Interna erreichbar; wird im Portal unter „Datenquellen“ transparent ausgewiesen:

• Energieproduktion/-verbrauch von Maschinen (Mekanism, Powah …)
• Inhalte von AE2-/Refined-Storage-Netzwerken
• Mana, Zauber, Source (Ars Nouveau, Iron's Spellbooks), Occultism-Rituale
• MineColonies-Kolonien
• exakte Spielerposition/Heatmaps (Datenschutz + Last)

Spätere Erweiterung ist über das Ereignisprotokoll möglich (neue Event-Typen), jeweils erst nach Prüfung der jeweiligen Mod-API gegen die installierte Version.

4. Mod atmstats

• NeoForge 21.1.x (Build gegen die zur ATM10-Version passende Version), Java 21, ModDevGradle. Mod-ID atmstats.
• Rein serverseitig: displayTest = "IGNORE_ALL_VERSION" in neoforge.mods.toml; Clients brauchen die Mod nicht. Keine Registrierungen (Blöcke, Items, Netzwerkpakete).
• Keine Compile-Abhängigkeit auf andere Mods.

4.1 Threading und Last

• Event-Handler auf dem Server-Thread erzeugen nur kleine, unveränderliche Event-Objekte und legen sie in eine ConcurrentLinkedQueue (O(1), keine I/O, keine Serialisierung).
• Stats-Snapshot alle 5 min (konfigurierbar): auf dem Server-Thread werden je online Spieler die Zählerwerte in ein Object2IntMap kopiert; Serialisierung und Versand erfolgen im Mod-eigenen Daemon-Thread. Der Snapshot wird über mehrere Ticks verteilt, falls viele Spieler online sind (max. 2 Spieler/Tick).
• Ein einzelner Daemon-Worker-Thread: Queue → Journal → Sender. SNBT-Dateilesen ebenfalls dort (nur bei geänderter mtime, alle 2 min).
• Tick-Messung: System.nanoTime() in Pre/Post, Aggregat (avg/p95/max MSPT) im Ringpuffer, Versand einmal pro Minute.

4.2 Zuverlässigkeit

• Event-ID: UUIDv7 (zeitlich sortierbar), erzeugt beim Entstehen des Events.
• Outbox-Journal: <server>/atmstats/outbox/ als Segmentdateien (JSON Lines, fsync beim Rotieren, max. 1 MB/Segment). Ein Segment wird erst gelöscht, wenn das Backend alle IDs bestätigt hat.
• Begrenzung: max. 50 MB bzw. 7 Tage; bei Überschreitung werden die ältesten Stats-Snapshots zuerst verworfen (sind durch spätere ersetzbar), Ereignisse zuletzt; Verwerfen wird geloggt.
• Beim Serverstopp (ServerStoppingEvent): Queue synchron ins Journal flushen (Zeitlimit 2 s), Session-Ende für alle online Spieler erzeugen.
• Beim Start: Journal-Segmente werden erneut gesendet; ein server_start-Event ermöglicht dem Backend, offene Sessions eines Absturzes zu schließen.
• Versand: java.net.http.HttpClient (HTTP/2, TLS-Verifikation an), Batches bis 500 Events/256 KB, gzip, Timeout 10 s. Backoff exponentiell 1 s → 5 min mit Jitter. Bei 4xx (außer 408/429) wird der Batch nicht endlos wiederholt, sondern in outbox/rejected/ abgelegt und geloggt.
• Startup-Selbsttest: GET /api/ingest/ping → Ergebnis ins Log („atmstats: backend reachable / NOT reachable: “). Damit wird die offene Frage „ausgehendes HTTPS erlaubt?“ beim ersten Start beantwortet.

4.3 Konfiguration (config/atmstats-server.toml, NeoForge ModConfigSpec)

enabled, endpoint, serverId, token, hmacSecret, statsSnapshotMinutes (5), questScanMinutes (2), healthIntervalSeconds (60), maxOutboxMb (50). Ohne Token bleibt die Mod passiv (nur Log-Hinweis).

4.4 Protokoll (Version 1)

POST /api/ingest
Authorization: Bearer <token>
X-ATM-Server: <serverId>
X-ATM-Timestamp: <unix ms>
X-ATM-Signature: hex(HMAC-SHA256(secret, timestamp + "." + sha256(body)))
Content-Encoding: gzip
{ "protocol": 1, "events": [ { "id": "<uuidv7>", "type": "...", "ts": <ms>, ...payload } ] }
→ 200 { "accepted": ["<id>", ...], "duplicate": ["<id>", ...], "rejected": [{ "id", "reason" }] }

Event-Typen: server_start (Versionen, Modliste), server_stop, player_join, player_leave, player_death, entity_kill, advancement, dimension_change, stats_snapshot (absolute Werte je Kategorie), quest_progress (Team-ID, abgeschlossene Quest-IDs mit Zeitstempel, Task-Fortschritt-Zähler), quest_defs (Kapitel/Quests/Titel, nur bei Änderung, mit Hash), team_info, health. Schemas als Zod in shared/ und als JSON-Schema-Testfixtures, gegen die auch die Java-Serialisierung getestet wird.

5. Backend

TypeScript, Node 22 LTS, Fastify, Zod, pg mit SQL (kein ORM), Migrationen mit node-pg-migrate. Zwei Prozesse aus einer Codebasis:

api

• GET /api/ingest/ping (authentifiziert), POST /api/ingest. Prüft Token (konstante Zeit), Zeitfenster ±5 min, HMAC; Rate-Limit; Body-Limit 2 MB entpackt. Verarbeitung pro Batch in einer Transaktion: INSERT INTO events … ON CONFLICT (event_id) DO NOTHING, nur neu eingefügte Events werden projiziert (sessions, deaths, stat_current …). Danach Benachrichtigung via pg_notify('atm_live', …).
• Öffentlich: GET /api/overview, /api/online, /api/leaderboards (Liste der Boards), /api/leaderboards/:board?period=all|30d|7d, /api/players?search=, /api/players/:uuid, /api/players/:uuid/history?metric=&range=, /api/players/:uuid/items?mod=, /api/mods (Modliste + Aktivität je Mod), /api/quests (Kapitelfortschritt), /api/server (Versionen, Health-Verlauf), /api/sources (Datenquellen-Status: letzter Push, letzter SFTP-Sync), /api/avatar/:uuid (Proxy-Cache für Spielerköpfe, 24 h; keine Besucher-IPs an Dritte).
• GET /api/live (SSE): abonniert LISTEN atm_live; Events online, death, advancement, quest, counters; Heartbeat 25 s, Last-Event-ID-Resume aus einem In-Memory-Ringpuffer (500 Einträge).
• Admin (/api/admin/*): Login mit Benutzer/Passwort (argon2id), Session-Cookie (httpOnly, Secure, SameSite=Strict), CSRF-Token im Header, Login-Rate-Limit. Funktionen: Status Mod/SFTP, letzte Fehler, manueller Sync, Spieler ausblenden/einblenden, Ingest-Token rotieren (Anzeige einmalig). Erster Admin wird per CLI (npm run admin:create) angelegt.
• Ausgeblendete Spieler erscheinen in keiner öffentlichen Antwort.
• Sicherheitsheader (über Fastify-Helmet), CORS nur eigene Domain.

worker

• SFTP-Pull (ssh2-sftp-client) alle 15 min (konfigurierbar): Verzeichnislisten von world/stats, world/advancements, world/ftbquests, config/ftbquests/quests, logs/latest.log. Herunterladen nur bei geänderter Größe/mtime (Zustand in sync_state); Log inkrementell ab Byte-Offset, Rotation erkannt über kleineren Größenwert. Ergebnisse durchlaufen dieselben Projektionen wie Ingest (synthetische, deterministische Event-IDs aus Datei+Inhalt-Hash → idempotent).
• Advancements-Dateien (world/advancements/<uuid>.json) liefern die vollständige Liste erreichter Advancements inkl. Zeitpunkten.
• Snapshot-Job: stündlich stat_snapshots (Auswahl relevanter Metriken je Spieler), täglich um 00:05 Tageswerte; Retention: stündlich 30 Tage, täglich unbegrenzt; server_health Minutenwerte 14 Tage, danach Stundenaggregate.
• Sitzungsbereinigung: offene Sessions ohne Lebenszeichen > 10 min nach server_start werden mit letztem bekannten Zeitpunkt geschlossen.
• Job-Locking über pg_try_advisory_lock, damit Jobs nie doppelt laufen.

Der Worker ist optional: ohne SFTP-Zugangsdaten läuft das System nur mit Push. Ohne erreichbaren Push läuft es nur mit Pull (dann Online-Status und Tode mit bis zu 15 min Verzögerung bzw. nur als Zähler).

6. Datenbank

Kern-Tabellen (Details in Migrationen):

• players(uuid PK, name, first_seen, last_seen, hidden bool)
• name_history(uuid, name, seen_at)
• teams(team_id PK, name, type), team_members(team_id, uuid)
• events(event_id PK, server_id, type, ts, received_at, source 'push'|'sftp', payload jsonb)
• sessions(id, uuid, started_at, ended_at, end_reason)
• stat_current(uuid, category, key, value bigint, observed_at, source, PK(uuid, category, key))
• stat_snapshots(uuid, metric, bucket timestamptz, granularity 'hour'|'day', value bigint)
• deaths(event_id, uuid, ts, dimension, cause, killer_type, killer_name)
• kills(event_id, uuid, ts, dimension, victim_type, is_boss, weapon)
• advancements(uuid, advancement_id, achieved_at, title, PK(uuid, advancement_id))
• quest_defs(quest_id PK, chapter_id, chapter_title, title, def_hash)
• quest_progress(team_id, quest_id, completed_at, PK(team_id, quest_id))
• server_info(id, started_at, mc_version, neoforge_version, java_version, mods jsonb)
• server_health(bucket, mspt_avg, mspt_p95, mspt_max, tps, players, chunks, heap_used_mb, heap_max_mb)
• sync_state(path PK, size, mtime, offset, hash, synced_at)
• admin_users, admin_sessions, ingest_tokens(id, hash, created_at, revoked_at)

Ranglisten werden aus stat_current mit Indizes auf (category, key, value DESC) berechnet. Abgeleitete Metriken (z. B. Gesamtstrecke = Summe aller *_one_cm, Items je Mod = Summe nach Namespace) liegen als SQL-Views vor. Eine Materialized View leaderboard_cache wird höchstens alle 60 s REFRESH … CONCURRENTLY aktualisiert.

7. Ranglisten (Start-Set, alle aus belegten Quellen)

Board	Metrik
Dauerzocker	minecraft:custom/minecraft:play_time (Ticks → h)
Friedhof	minecraft:custom/minecraft:deaths
Monsterjäger	minecraft:custom/minecraft:mob_kills
Abrissbirne	Summe minecraft:mined/*
Weltenbummler	Summe minecraft:custom/*_one_cm (→ km)
Flieger	minecraft:custom/minecraft:fly_one_cm
Diamantenbank	minecraft:mined/minecraft:diamond_ore + deepslate_diamond_ore (Abbau, nicht Besitz – so ausgewiesen)
Techniker	Summe crafted+used in Tech-Namespaces (mekanism, mekanismgenerators, powah, modern_industrialization, oritech, create, immersiveengineering, appliedenergistics2, refinedstorage, draconicevolution, integrateddynamics, pneumaticcraft)
Magier	dito Magie-Namespaces (ars_nouveau, ars_elemental, ars_additions, irons_spellbooks, occultism, theurgy, rootsclassic, forbidden_arcanus, evilcraft, reliquary)
Farmer	dito (mysticalagriculture, mysticalagradditions, productivebees, botanypots, pamhc2*, farmersdelight, herbsandharvest)
Questmeister	Anzahl abgeschlossener Quests des Teams (Teamleaderboard + Spieler über Mitgliedschaft)
Abenteurer	Anzahl Advancements
Schatzjäger	lootr:looted_stat
Weltenstufe	apotheosis:world_tiers_activated

Die Namespace-Kategorien liegen in einer editierbaren Konfigurationsdatei (backend/config/mod-categories.json) und werden mit der echten Modliste abgeglichen; Namespaces ohne installierte Mod werden ignoriert und geloggt.

8. Frontend

Next.js (App Router), TypeScript, Tailwind CSS, Recharts. Dunkles, eigenständiges Gaming-Design (kein Nachbau von craftattack-Assets), responsiv, zugänglich (Kontrast, Tastatur, prefers-reduced-motion). Server-Rendering mit kurzer Revalidierung; Live-Teile clientseitig per SSE.

Seiten:

• / Übersicht: Kennzahlen (Online, Spielstunden gesamt, Tode, Quests, Advancements), „Gerade online“, Live-Ticker, Top-10-Karten.
• /leaderboards und /leaderboards/[board] (Zeitraum all/30d/7d aus Snapshots).
• /players (Suche) und /players/[name]: Kopf, Spielzeit, Sessions-Heatmap (Wochentag × Stunde), Verlaufsdiagramme, Bewegung nach Art, Kampf (Kills nach Mob, Todesursachen), Items nach Mod (Tabs mined/crafted/used/picked_up), Advancements, Team-Quests, Rangpositionen.
• /atm10: Aktivität je Mod/Kategorie, Quest-Kapitelfortschritt, meistgenutzte Mods.
• /server: Versionen (MC, NeoForge, Java, ATM10-Modliste mit Suche), TPS/MSPT-, Spieler- und Heap-Verlauf.
• /sources: Datenquellen, Aktualität, Einschränkungen (aus DATA-SOURCES).
• /admin: Login, Status, Sync, Spieler ausblenden, Token-Rotation.

9. Deployment und Betrieb

• deploy/docker-compose.yml: db (postgres:16-alpine, Volume), api, worker, web, backup. Nur web und api hängen am externen Traefik-Netz (TRAEFIK_NETWORK); db nur im internen Netz.
• Traefik-Labels: Router Host(${DOMAIN}) && PathPrefix(/api) → api, Host(${DOMAIN}) → web; Entrypoint/Cert-Resolver per .env. Optionale Middleware ipAllowList für /api/ingest (INGEST_ALLOWED_IPS).
• OPNsense: eingehend 443 → Traefik (bereits vorhanden); für den Pull-Fallback ausgehend DMZ-Host → Mine-Hoster-SFTP-Host/-Port.
• Healthchecks für alle Container; api und worker warten auf DB und führen Migrationen beim Start aus (Advisory-Lock).
• Backup: täglicher pg_dump -Fc mit 14-Tage-Rotation in ein Volume; Restore-Anleitung in OPERATIONS.md.
• Logs strukturiert (pino, JSON), keine Tokens/IPs im Log.

10. Tests

• Mod (JUnit 5, ohne Minecraft-Laufzeit): Journal (Schreiben, Rotation, Recovery nach abgeschnittener letzter Zeile), Backoff, Batch-Bildung, HMAC, JSON gegen Schema-Fixtures, SNBT-Parser an den echten Quest-Dateien. Minecraft-abhängiger Code ist dünn und von der Logik getrennt. Zusätzlich manueller Testlauf auf einem lokalen NeoForge-Server (runServer).
• Backend (Vitest + Postgres im Compose-Testprofil): Ingest-Auth (falsches Token, abgelaufener Zeitstempel, falsche Signatur), Idempotenz (gleicher Batch doppelt), Projektionen, Stats-Parser an echten world/stats-Dateien, Log-Parser an anonymisiertem Log, Ranglisten-SQL, SSE.
• Frontend: Komponententests (Vitest + Testing Library) und Playwright-Smoke-Test gegen den Compose-Stack mit Simulator-Daten.
• Simulator (tools/simulator): erzeugt signierte Batches im echten Protokoll.

11. Dokumentation

README.md (Überblick, Schnellstart), docs/ARCHITECTURE.md, docs/DATA-SOURCES.md (jede Kennzahl → Quelle, Aktualität, Einschränkungen), docs/OPERATIONS.md (Deployment Traefik/OPNsense, Mod-Installation per Mine-Hoster-SFTP, Konfiguration, Token-Rotation, Backup/Restore, Neustartverhalten, Fehlerbilder), mod/README.md.

12. Offene Punkte, die in der Umsetzung geklärt werden

1. Exakte NeoForge-Version des Servers → Mod-Build gegen 21.1.x; Kompatibilität innerhalb 21.1 ist gegeben, finale Version per Startup-Log bestätigen.
2. Ausgehendes HTTPS bei Mine-Hoster → Selbsttest beim ersten Start.
3. Struktur von config/ftbquests/quests/ und world/ftbteams/ → Betreiber stellt Kopie bereit, bevor Quest-Titel/Team-Namen-Parser finalisiert werden; bis dahin werden Quest-IDs angezeigt. → Geklärt am 13.10.2026 anhand der echten Dateien, siehe docs/DATA-SOURCES.md.
4. SFTP-Host/Port/Benutzer → .env des Betreibers (nicht im Repo).