Dungeons and Scripts

Dungeons and Scripts is a text-based adventure game that uses
a DSL called MiniScriptRoom (.msr) to define rooms, enemies, choices, and the narrative flow of the game.
The project includes a lexer, parser, virtual machine (VM), and ASCII art for immersive terminal gameplay.

---

Installation

Requirements

• Python 3.12+
• uv (or standard pip)

Clone the repository and install dependencies:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

---

Running the Game

Run the main game with:

python main.py

You will see a menu with adventure cartridges:

Enter the cartridge number:
1. Cursed Forest
2. Demon Fortress
3. Death in Space
4. Dark Castle

To exit, type 0.

---

Writing .msr Scripts

The .msr files define the adventure logic using the MiniScriptRoom language.
Here’s a basic example:

room start {
  text "You are in a dark room with two exits."

  choice "Go to the hallway" -> hallway
  choice "Explore the darkness" -> death
}

room hallway {
  text "You enter the hallway and hear footsteps."

  enemy "Goblin" goblin 10
  attack

  goto treasure
}

room treasure {
  text "You found a chest full of gold. Congratulations!"
}

room death {
  text "You tripped and fell into a bottomless pit. Game over."
}

---

Available Tokens

Token	Example	Description
room	room hallway { ... }	Defines a room
text	text "You see a shadow..."	Displays text to the player
choice	choice "Go right" -> right	Creates a player choice
goto	goto next_room	Jumps directly to another room
enemy	enemy "Goblin" goblin 10	Creates an enemy with name, ID, and HP
attack	attack	Starts a combat sequence
hero	hero "Arthur" HP 20	Defines hero name and HP (optional)

---

Debugging

Helper scripts for .msr code inspection:

View Tokens and AST

python debug/debug_lexer.py scripts/dark_castle.msr
python debug/debug_parser.py scripts/dark_castle.msr

Run Game Directly

python debug/debug_vm.py scripts/dark_castle.msr

---

ASCII Art

Enemies have associated ASCII art files.
Place them inside the ascii/ directory with matching filenames:

ascii/
├── goblin.txt
├── goblin_injured.txt
├── goblin_dead.txt
├── security_drone.txt
├── ancient_spirit.txt