# mudlib

Telnet MUD engine built on telnetlib3. Python 3.12+, managed with uv.

## Commands

- `just check` - lint (ruff --fix + format), typecheck (pyright), test (pytest)
- `just lint` / `just typecheck` / `just test` - individual steps

## Project Layout

- `src/mudlib/` - the engine (commands, world, combat, render, store)
- `tests/` - pytest tests
- `worlds/` - world definition files (yaml/toml, version controlled)
- `notes/` - design docs, daydreaming
- `repos/` - symlinked reference repos (telnetlib3, miniboa). gitignored, not our code

## Architecture

- telnetlib3 is a **dependency**, not vendored. contribute fixes upstream
- telnetlib3 gives us: GMCP, MSDP, NAWS, async server, reader/writer streams
- game loop is tick-based (async task alongside telnet server)
- world definitions live in data files, runtime state lives in memory
- SQLite for persistence (player accounts, progress)
- session mode stack filters what events reach the player (normal/combat/editor)

## Style

- simple > clever
- no mock implementations
- match existing patterns in each file