mudlib

Telnet MUD engine built on telnetlib3. Python 3.12+, managed with uv.

Commands

src/mudlib/ - the engine (commands, world, combat, render, store)
tests/ - pytest tests
content/ - content definitions (commands, combat moves) loaded at runtime
worlds/ - world definition files (yaml/toml, version controlled)
docs/ - project knowledge (see below)
DREAMBOOK.md - the vision, philosophy, wild ideas. not a spec
scripts/ - standalone tools (map renderer, etc)
build/ - generated output (gitignored)
repos/ - symlinked reference repos, gitignored, not our code. includes:
- repos/viola/ - DFillmore/viola z-machine interpreter (working, global state)
- repos/zvm/ - sussman/zvm z-machine interpreter (clean architecture, half-built)
- repos/telnetlib3/, repos/miniboa/ - telnet libraries

Consult docs/index.rst when starting unfamiliar work to find relevant docs.

Three categories in docs/. Plain text or rst, not markdown.

docs/how/ - how things work. write one when you build something non-obvious. terrain generation, command system, etc. aimed at someone reading the code who wants the "why did we do it this way" context.
docs/why/ - design philosophy. telnet-first, text worlds, etc. the reasoning behind big decisions. doesn't change often.
docs/lessons/ - things we learned the hard way. write one when you hit a real bug or gotcha that cost time. charset-vs-mtts, etc. include the fix so we don't repeat it.

Update docs when:

telnetlib3 is a dependency, not vendored. contribute fixes upstream
telnetlib3 gives us: GMCP, MSDP, NAWS, async server, reader/writer streams
game loop is tick-based (async task alongside telnet server)
world is toroidal (wraps in both axes). terrain noise tiles seamlessly
world definitions live in data files, runtime state lives in memory
SQLite for persistence (player accounts, progress)
session mode stack filters what events reach the player (normal/combat/editor)
combat system: state machine with TOML-defined moves (attacks, defends, counters). see docs/how/combat.rst
- moves with directional variants (punch left/right) use a single TOML with [variants] sections
- commands are always single words; direction is an argument, not part of the command name
content loading: TOML definitions for commands and combat moves, loaded at startup
entity model: Entity base class, Player and Mob subclasses sharing common interface
editor mode: in-world text editor with syntax highlighting and search/replace
IF mode: interactive fiction via dfrotz subprocess, mode stack integration, spectator broadcasting. see docs/how/if-terminal.txt