gh-dungeons 🎮

A procedurally generated roguelike dungeon crawler that turns your repos into a unique playable game!

Built using GitHub Copilot CLI for the GitHub Copilot CLI Challenge.

Installation

gh extension install leereilly/gh-dungeons

Or build from source:

git clone https://github.com/leereilly/gh-dungeons
cd gh-dungeons
go build -o gh-dungeons

Usage

Navigate to any Git repository and run:

gh dungeons

WASD, arrow keys, and Vim keys (because of course)

Controls

Key	Action
↑ w k	Move up
↓ s j	Move down
← a h	Move left
→ d l	Move right
y u b n	Diagonal movement
q Esc	Quit

Gameplay

• You are @ with 20 HP
• Bugs b - Weak enemies (1 HP, 1 damage)
• Scope Creeps c - Tougher enemies (3 HP, 2 damage)
• Health Potions + - Restore 3 HP
• Door > - Descend to the next level

Features

• BSP-tree dungeon generation - procedurally created rooms and corridors
• Fog of war - limited vision radius, explored areas stay visible
• Enemy AI - enemies chase you when in line of sight
• Auto-attack - automatically attack adjacent enemies
• Stats tracking - kills and levels cleared
• And way, way, waaay more - intentionally undocumented, but there for you to discover as new ones are added.

Objective

Survive 5 dungeon levels by finding the hidden door > on each floor. Kill bugs and scope creeps, collect potions, and make it to the end!

Super, super hard mode with permanent permadeath

If you're insane, you can set up a pre-commit hook that forces you to beat the game or lose your staged changes 😆

# Create the pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
gh dungeons
if [ $? -ne 0 ]; then
    echo "You died! Your changes have been stashed into oblivion..."
    git stash && git stash drop stash@{0}
    exit 1
fi
EOF

# Make it executable
chmod +x .git/hooks/pre-commit

Now every commit requires you to survive the dungeon. Lose, and your changes are gone forever. 💀

WARNING: Be very careful you understand what this is doing before attempting. You could lose work / sanity.

Documentation

For technical documentation aimed at modders, contributors, and those who want to understand or extend the game, see the docs/ directory:

• Architecture — System overview, entry points, build commands
• Dungeon Generation — BSP algorithm explained with ASCII diagrams
• Entities — Complete reference for player, enemies, items
• Seeding — Deterministic RNG and reproducibility
• Modding Guide — Step-by-step guides for adding content

License

MIT