Espectral: building a UHC Minecraft platform with AI agents

I run the Espectral project, a Minecraft UHC (Ultra Hardcore) network.

The platform has several moving parts: Java Paper plugins that run the game modes, a Python analytics pipeline and web dashboard, a JavaScript replay UI, Discord bots, in-game polling campaigns, and a local RAG context system. I have tried to be explicit about what is implemented, what is locally tested, and what is still experimental or planned.

Evidence at a glance

Output	Scope	Validation snapshot
Game-server logs	About 1,800 compressed logs	Pulled from production and rebuilt into the analytics DB
Analytics DB	About 1.9 GB SQLite database	Deterministic rebuild and table-level acceptance checks
Chat corpus	About 504,000 Discord messages and 246,000 Minecraft messages	Ingested into the analytics DB, identity resolution reviewed locally
Java plugin refactor	97 files changed, 42 subagent tasks, 8 review gates	119 passing tests plus a full automated game-cycle smoke test at that checkpoint
Later plugin test run	217 discovered tests	199 passed, 18 skipped, 0 failed
Backend and replay tests	70 focused tests	Replay API, sample loading, and UI core covered
Domain tests	60 tests	FSM, services, and config versioning
Scenario verification	39 scenarios	Behaviorally verified with local test server and bots; 1 experimental

The numbers above are snapshots from recorded checkpoints, not a live scoreboard. I refreshed them when the project was at a stable state.

System architecture

flowchart LR
    A["Paper UHC server<br/>EspectralUHC plugin"] -->|metrics + telemetry JSONL| B[Analytics host]
    B -->|parse + rebuild| C[SQLite analytics DB]
    C --> D[FastAPI web app]
    D --> E[JavaScript replay UI with Leaflet]
    D --> F[Admin + public dashboards]
    G[Discord bot / BalasGPT] -->|hosting, tokens, alerts| A
    B -->|replay links + summaries| G
    H[Discord + MC chat logs] --> B
    I[RAG index] -.->|context for chatbot| G

Loading

The diagram shows five main roles.

Component	Role
Java plugin	Records what happens during a UHC game and writes per-second telemetry and metrics to JSONL files.
Python analytics pipeline	Pulls those files plus server logs, parses them, resolves identities, and builds a SQLite database.
FastAPI web app	Serves public and staff dashboards, exposes replay metadata, and accepts ingestion hooks.
JavaScript replay UI	Reads the telemetry through the API and renders a timeline, player list, and Leaflet-based map.
Discord bot	Handles scheduling, hosting commands, token accounting, and can pull RAG context from the chat corpus.

Document index

Case studies

Document	What it covers
Platform overview	Java plugins, Python services, JavaScript replay UI, data flow, and the role of AI
Java plugin refactor	Clean architecture migration, scenario porting, and verification
Data and identity pipeline	Server logs, Discord ingest, identity resolution, player profiles, and enrichment
Telemetry and replays	Per-second UHC telemetry, replay ingestion, and the browser and viewer
Polling integration	In-game polls driven from the Palanctral dashboard
RAG system	Local RAG indexing and retrieval for the chat corpus
Production operations	Deploys, cron jobs, monitoring, and incident response

Workflow and safety

Document	What it covers
Agentic development workflow	How I work with agents through Oh My Pi
Verification and safety	Test harness, review gates, and safety rules

Supporting documents

Document	What it covers
Evidence index	Metrics, claims, and the validation boundaries for each
Agent hallucination analysis	Unsupported agent claims and the controls I added
Telemetry data loss	A restart-cycle data loss incident and the hardening that followed

Implemented versus experimental work

Area	Status
Java plugin clean architecture migration	Implemented and locally tested
39 UHC scenarios	Verified behaviorally; 1 scenario marked experimental
Replay browser and replay viewer	Implemented and exercised with live-game data; longer-term coverage is still limited
Palanctral analytics pipeline and web dashboard	Deployed on the analytics host and serving traffic
Discord ingestion	Corpus and incremental ingestion implemented; continuous production-to-database freshness is still being hardened
In-game polling integration	Locally tested and wired to the plugin and dashboard
RAG indexing and retrieval	Source corpus, indexer, and local integration ready; production population and retrieval-quality evaluation are not fully established
Paid custom UHC token workflow	Local prototype only; not presented as a live system
Many Java scenario files	Implemented, but not all behaviorally verified yet

I do not claim that every component is production-ready. What I do claim is that the implemented parts are real, measured, and tested to the level shown above, and that I know exactly where the remaining gaps are.