mud/README.md

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 tests
• worlds/ — world definitions (yaml/toml)
• docs/ — internal knowledge base
• DREAMBOOK.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).