MDRPG

A terminal roguelike where the entire game world lives in Markdown files.

Maps, NPCs, items, quests, and save data are all human-readable .md files with YAML frontmatter. The Python engine reads them, runs the game, and writes changes back.

##########
#........#
#..@..G..#
#........#
##########

Philosophy

If it can be represented as a Markdown document, it probably should be.

Game content is designed to be readable, editable, and shareable without touching code. The long-term goal is a community-driven world where contributors can submit new NPCs, maps, and quests through pull requests.

Running the Game

python -m venv .venv
source .venv/bin/activate
pip install textual python-frontmatter
python main.py

Controls: WASD to move, Q or Ctrl+C to quit.

Project Structure

main.py              # Entry point
engine/
  actors.py          # Actor dataclass
  map_loader.py      # Parses vault .md files into Python objects
  game.py            # Textual app, game loop, input handling, and rendering
vault/
  player.md          # Player stats and position
  maps/              # Map files (ASCII grid in body, metadata in frontmatter)
  npcs/              # NPC files

Adding Content

NPCs, maps, and items are plain Markdown files. See existing files in vault/ for the frontmatter schema. No code changes required to add new content.

Status

Early development. Milestone 1 complete — you can explore the dungeon and kill the Suspicious Goose.

Credits

Built with the following open source projects:

• Textual — TUI framework for Python, powers the terminal UI and web serving
• Rich — terminal formatting library (Textual dependency)
• python-frontmatter — parses YAML frontmatter from Markdown vault files
• PyYAML — YAML parsing