mud/.claude/CLAUDE.md

mudlib

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

Commands

• just check - lint (ruff --fix + format), typecheck (pyright), test (pytest)
• just lint / just typecheck / just test - individual steps

Project Layout

• src/mudlib/ - the engine (commands, world, combat, render, store)
• tests/ - pytest tests
• worlds/ - world definition files (yaml/toml, version controlled)
• notes/ - design docs, daydreaming
• repos/ - symlinked reference repos (telnetlib3, miniboa). gitignored, not our code

Architecture

• 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 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)

Style

• simple > clever
• no mock implementations
• match existing patterns in each file