shmup/mud

python mudlib using telnetlib3

Find a file

Jared Miller dbb976be24 Add data-driven combat system with TOML move definitions Combat moves defined as TOML content files in content/combat/, not engine code. State machine (IDLE > TELEGRAPH > WINDOW > RESOLVE) processes timing-based exchanges. Counter relationships, stamina costs, damage formulas all tunable from data files. Moves: punch right/left, roundhouse, sweep, dodge right/left, parry high/low, duck, jump. Combat ends on knockout (PL <= 0) or exhaustion (stamina <= 0).		2026-02-07 21:16:12 -05:00
.claude	Update agent config with new notes	2026-02-07 14:48:24 -05:00
content	Add data-driven combat system with TOML move definitions	2026-02-07 21:16:12 -05:00
docs	Add combat system design documentation	2026-02-07 20:47:41 -05:00
scripts	Add a map renderer	2026-02-07 13:38:32 -05:00
src/mudlib	Add data-driven combat system with TOML move definitions	2026-02-07 21:16:12 -05:00
tests	Add data-driven combat system with TOML move definitions	2026-02-07 21:16:12 -05:00
worlds/earth	Add seed-based terrain world with movement and viewport	2026-02-07 13:27:44 -05:00
.gitignore	Add worktrees to gitignore	2026-02-07 13:46:22 -05:00
demo_terrain.py	Add seed-based terrain world with movement and viewport	2026-02-07 13:27:44 -05:00
DREAMBOOK.md	Add a dreambook	2026-02-07 12:19:49 -05:00
justfile	Add a map renderer	2026-02-07 13:38:32 -05:00
mud.tin	Add fly command with cloud trail effects	2026-02-07 14:48:42 -05:00
pyproject.toml	Exclude worktrees in pyproject	2026-02-07 16:33:03 -05:00
README.md	Add a simple README	2026-02-07 15:42:07 -05:00
uv.lock	Update telnetlib3	2026-02-07 12:21:59 -05:00

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