python mudlib using telnetlib3
Jared Miller
65a080608a
QuetzalParser._parse_stks() creates a new ZStackManager and sets it on zmachine._stackmanager, but ZCpu._stackmanager and ZOpDecoder._stack still pointed to the old empty stack. After restore, all stack ops (local var reads, routine returns, stack pops) used the wrong stack, causing the interpreter to crash on the first command. |
||
|---|---|---|
| .claude | ||
| content | ||
| docs | ||
| scripts | ||
| src/mudlib | ||
| tests | ||
| worlds/earth | ||
| .dockerignore | ||
| .gitignore | ||
| compose.yml | ||
| demo_terrain.py | ||
| Dockerfile | ||
| DREAMBOOK.md | ||
| justfile | ||
| mud.tin | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
mudlib
A telnet MUD engine. No client needed — just telnet and you're in.
Built on telnetlib3, Python 3.12+, managed with uv.
Quickstart
uv sync
just run
Then connect: telnet localhost 6789
Commands
just check # lint + typecheck + test
just run # start the server
just debug # start with debug logging
just render # generate world map HTML
What's in here
src/mudlib/— the engine (commands, world, combat, rendering, storage)tests/— pytest testsworlds/— world definitions (yaml/toml)docs/— internal knowledge baseDREAMBOOK.md— vision and wild ideas
How it works
The world is a toroidal 2D grid of terrain tiles, not discrete rooms. Players see a viewport centered on their position. Terrain types have mechanics — shallow water slows you, mountains block you, forests hide you.
Combat is timing-based with telegraphed moves and cooldown management, not turn-based.
The server runs a tick-based async game loop alongside the telnet server. SQLite handles persistence. Session mode stacks filter what reaches the player depending on context (exploring, fighting, composing, solving puzzles).