Matt Johnson
e9231ac24a
- Documents recent infrastructure cleanup (8 CTs destroyed, 35 DNS records removed, Headscale cleanup) - Adds 24 new runbooks covering Authentik, PeerTube, Meshtastic, RECON, Proxmox, Mailcow, Internet Archive, GPU routing - Adds project documentation for headscale, vaultwarden, peertube, matrix, mmud, advbbs, arr stack - Updates services.md, environment.md, caddy.md, authentik.md to match live infrastructure - Removes 4 deprecated runbook duplicates (canonical versions live in projects/) - Adds .gitignore for binary archives and editor temp files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
92 lines
4.7 KiB
Markdown
92 lines
4.7 KiB
Markdown
# MMUD — Mesh Multi-User Dungeon
|
|
|
|
Text-based multiplayer dungeon crawler for Meshtastic LoRa mesh networks. BBS door games (LORD, TradeWars) adapted for 150-char mesh radio constraints, async play, 30-day wipe cycles.
|
|
|
|
## Status
|
|
|
|
**Phase:** Deployed and running — all 6 phases implemented, NPC conversation system live with Gemini 2.5 Flash.
|
|
|
|
## Deployment
|
|
|
|
- **Game Daemon:** CT 109 (192.168.1.109) on utility node, Docker container, Flask dashboard on port 5000
|
|
- **Dashboard:** https://mmud.echo6.co (Last Ember — dark tavern aesthetic)
|
|
- **SIM Nodes:** 6 meshtasticd LXC containers (CT 111-116) on utility
|
|
- EMBR (CT 111) — game server
|
|
- DCRG (CT 112) — broadcast
|
|
- GRST (CT 113) — Grist barkeep NPC
|
|
- MRN (CT 114) — Maren healer NPC
|
|
- TRVL (CT 115) — Torval merchant NPC
|
|
- WSPR (CT 116) — Whisper sage NPC
|
|
- **LLM Backend:** Gemini 2.5 Flash via Google genai SDK (configured in DB `llm_config` table)
|
|
- **Compose:** `/opt/mmud/docker-compose.yml` on CT 109
|
|
- **Admin:** https://mmud.echo6.co/admin (session auth, password in docker env)
|
|
|
|
## Repo
|
|
|
|
`/home/zvx/projects/mmud` (GitHub: zvx-echo6/mmud)
|
|
|
|
The repo contains a `CLAUDE.md` with full architecture, directory structure, and implementation guidance. **Read it first before any work.**
|
|
|
|
## Key Files
|
|
|
|
- `CLAUDE.md` — Architecture, patterns, gotchas
|
|
- `docs/planned.md` — Complete game design document (~950 lines). Source of truth for all mechanics.
|
|
- `docs/npc-lore.md` — NPC deep lore bible (5-layer Hearth-Sworn backstories, 514 lines)
|
|
- `docs/worldbuilding.md` — Surface-level worldbuilding (Legend of Oryn, floor identities)
|
|
- `config.py` — All game constants with rationale
|
|
- `src/db/schema.sql` — Full database schema (migrations in `src/db/migrations/`)
|
|
|
|
## Architecture
|
|
|
|
- **Python 3.11+**, SQLite, Meshtastic Python API, Flask 3.x, Jinja2
|
|
- **Docker:** python:3.11-slim, /data volume for SQLite DB
|
|
- **6-node mesh topology:** EMBR (game), DCRG (broadcast), 4 NPC nodes
|
|
- **150 characters per message** — hard ceiling from Meshtastic LoRa
|
|
- **12 dungeon actions/day**, 30-day epochs, async-first
|
|
- **828+ tests** — `python3 -m pytest tests/ -x -v`
|
|
|
|
## NPC Conversation System
|
|
|
|
NPCs use runtime LLM calls (the one exception to the "no runtime LLM" rule). Key features:
|
|
|
|
- **TX Tag System:** LLM prefixes responses with `[TX:action:detail]` for game mechanics (heal, buy, sell, browse, gamble, hint, recap)
|
|
- **Session Memory:** Per-player per-NPC conversation history with persistent memory summaries
|
|
- **Deep Lore:** Five-layer backstory system (Surface → Observations → History → Truth → Unspeakable)
|
|
- Trigger word detection pushes toward deeper layers
|
|
- Interaction count tracks conversation depth per player per NPC
|
|
- "Soren" is a Layer 5 nuclear trigger for all 4 NPCs
|
|
- **Easter Eggs:** Death memory (Maren), daily gamble (Torval), countdown (Whisper), late-epoch vulnerability (Maren), inter-NPC secret (Torval/Whisper)
|
|
- **DummyBackend:** Keyword-based offline mode for testing without LLM
|
|
|
|
## LLM Configuration
|
|
|
|
- Model configured via `llm_config` table in SQLite DB (not env vars)
|
|
- Currently: Gemini 2.5 Flash (`gemini-2.5-flash`)
|
|
- API key stored in DB, manageable via admin panel at /admin/llm
|
|
- **No `max_output_tokens` restrictions** — Gemini 2.5 Flash thinking tokens consume the budget, causing truncation. All backends have token limits removed.
|
|
- Supports: Google (Gemini), Anthropic (Claude), OpenAI-compatible backends
|
|
|
|
## Development Phases (All Complete)
|
|
|
|
1. **Core Loop** — Message handling, parser, player creation, navigation, combat, death, action budget
|
|
2. **Economy & Progression** — XP, leveling, gold, shops, gear, bank, healer
|
|
3. **Social Systems** — Broadcasts, barkeep, bounty board, player messages, mail
|
|
4. **Epoch Generation** — World gen, LLM narrative pipeline, secrets, bounty pools
|
|
5. **Endgame Modes** — Hold the Line, Raid Boss, Retrieve & Escape, epoch vote
|
|
6. **The Breach** — Breach zone gen, 4 mini-events (Heist, Emergence, Incursion, Resonance)
|
|
|
|
## Gotchas
|
|
|
|
- Gemini 2.5 Flash thinking tokens count against `max_output_tokens` — never set token limits
|
|
- NPC greeting path uses `complete()`, conversation path uses `chat()` — different code paths
|
|
- `npc_memory` table stores `turn_count` for interaction depth tracking
|
|
- Death log table (`death_log`) tracks monster kills for Maren's memory feature
|
|
- Town actions are always free — never charge dungeon actions in town
|
|
- The design doc (`docs/planned.md`) is the source of truth — if code contradicts it, code is wrong
|
|
|
|
## Notes
|
|
|
|
- All regen/HP/damage numbers are targets — will need playtesting
|
|
- SQLite single file DB, no ORM, raw parameterized SQL
|
|
- Every outbound message must fit 150 chars — the formatter is the final gate
|
|
- Container on CT 109 connects to 6 SIM nodes via TCP (ports 4403)
|