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