shmup/mud

python mudlib using telnetlib3

Find a file

Jared Miller 6344c09275 Restructure combat moves: single-word commands with variant args The DREAMBOOK always described "punch right/left [target]" as one command with a direction argument, but the implementation had separate TOML files and multi-word command names that the dispatcher couldn't reach (it only matches the first word). Aliases like "pr" also couldn't pass targets because the shared handler tried to re-derive the move from args. Changes: - Merge punch_left/right, dodge_left/right, parry_high/low into single TOML files with [variants] sections - Add command/variant fields to CombatMove for tracking move families - load_move() now returns list[CombatMove], expanding variants - Handlers bound to moves via closures at registration time: variant handler for base commands (punch → parses direction from args), direct handler for aliases and simple moves (pr → move already known) - Core logic in do_attack/do_defend takes a resolved move - Combat doc rewritten as rst with architecture details - Simplify mud.tin aliases (pr/pl/etc are built-in MUD commands now)		2026-02-08 00:20:52 -05:00
.claude	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
content	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
docs	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
scripts	Add a map renderer	2026-02-07 13:38:32 -05:00
src/mudlib	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
tests	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
worlds/earth	Add seed-based terrain world with movement and viewport	2026-02-07 13:27:44 -05:00
.gitignore	Add fast and parallel testing	2026-02-07 22:03:00 -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	Simplify test recipe	2026-02-07 22:49:01 -05:00
mud.tin	Restructure combat moves: single-word commands with variant args	2026-02-08 00:20:52 -05:00
pyproject.toml	Wire client capabilities into Player & terrain	2026-02-07 22:44:45 -05:00
README.md	Add a simple README	2026-02-07 15:42:07 -05:00
uv.lock	Wire client capabilities into Player & terrain	2026-02-07 22:44:45 -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).