python mudlib using telnetlib3
Jared Miller
0f7404cb12
The variant handler now supports prefix matching for directional variants. This allows 'pa hi' to match 'parry high', 'pa lo' to match 'parry low', etc. Implementation: - First tries exact match on variant key - Falls back to prefix matching if no exact match - Returns unique match if exactly one variant starts with the prefix - Shows disambiguation message if multiple variants match - Shows error with valid options if no variants match Tests cover exact match, prefix match, ambiguous prefix, no match, single-char prefix, case-insensitivity, and preservation of target args. |
||
|---|---|---|
| .claude | ||
| content | ||
| docs | ||
| scripts | ||
| src/mudlib | ||
| tests | ||
| worlds/earth | ||
| .gitignore | ||
| demo_terrain.py | ||
| 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).