Code to Castle: How Procedural Generation Turns Your Repository into a Roguelike Game
From Repository to Dungeon: A New Kind of Hackathon Project
When a developer gets “nerd-sniped” into a challenge, the results can be delightfully unexpected. That’s exactly what happened with the GitHub Copilot CLI Challenge, which led to the creation of GitHub Dungeons—a terminal-based game that transforms any Git repository into a procedurally generated roguelike adventure. Instead of just building another CLI extension, this project turned codebases into explorable maps filled with rooms, corridors, and enemies, all rendered directly in the terminal.
The core idea is simple: every repository becomes a unique dungeon. You navigate with arrow keys, fight bugs (literally), and search for the exit. The twist? The dungeon layout is seeded by your latest commit, so every change reshapes the map. Permadeath is built in—when your HP hits zero, you start over, just like in classic roguelikes from the 1980s.
What Is Procedural Generation?
Procedural generation—often abbreviated as “procgen”—is the algorithmic creation of content rather than manual design. In games, this means levels, maps, enemies, or items are generated at runtime using a set of rules and randomness. Instead of crafting one dungeon, you design a system that produces many.
This approach is what gives roguelikes their replayability:
- Every run is different
- Layouts change every time you play
- Enemy placements and item distributions vary
In GitHub Dungeons, the system is tied directly to your code. The layout is seeded by the latest commit SHA, so the same code always yields the same dungeon—but as you commit changes, the world evolves.
Binary Space Partitioning: The Mapmaking Engine
To turn a codebase into a playable map, the game uses Binary Space Partitioning (BSP). This classic algorithm recursively divides a space into smaller regions, creating rooms and corridors that feel natural. The seed (derived from the commit hash) ensures consistency while still allowing organic variation.
How it works in practice:
- The latest commit SHA seeds a pseudo-random number generator.
- BSP splits the dungeon area into rectangular cells.
- Rooms are placed within cells, and corridors connect them.
- Enemies and items are scattered based on the same seed.
This means that different repositories produce structurally distinct layouts. A side-project with few commits might yield a small, sparse dungeon, while a large repository with many files could generate a sprawling labyrinth.
Roguelike Tradition Meets Modern Code
Roguelikes trace back to games like Rogue (1980), which featured terminal-based adventuring, permadeath, and procedurally generated dungeons. These elements were later formalized in the “Berlin Interpretation,” a set of criteria that define the genre. Surprisingly, these old-school ideas fit perfectly with modern command-line interfaces.
GitHub Dungeons leans heavily into that tradition. It’s written in Go—a language the creator usually doesn’t use—but the power of GitHub Copilot CLI allowed them to focus on behavior rather than syntax. The /yolo command (an alias for /allow-all) became a fitting metaphor: in a roguelike, you truly only live once.
Building a Game with GitHub Copilot CLI
Developing a terminal game with procedural generation in an unfamiliar language could be daunting, but the Copilot CLI acted as a pair programmer. By describing the desired behavior in natural language, the developer could rapidly iterate on dungeon logic, movement handling, and display rendering.
Key benefits included:
- Faster prototyping: No need to look up Go syntax or libraries for every small change.
- Focus on design: The algorithm (BSP) could be described once and refined through prompts.
- Error reduction: The AI suggested common patterns, reducing bugs in collision detection and map generation.
The result is a fully playable roguelike that transforms a static codebase into an interactive experience—all from the command line.
What’s Next for Code-Driven Dungeons?
This project highlights how AI-assisted development can unlock creative possibilities, especially for rapid prototyping. Future enhancements could include:
- Multi-repository dungeons: Combine multiple codebases into a single map.
- Branch-based alternate realities: Different branches generate different dungeons from the same repo.
- Enemy types based on code metrics: More complex files could spawn tougher enemies.
Ultimately, GitHub Dungeons is more than a novelty—it’s a testament to how procedural generation and AI tools can turn the familiar (your code) into the extraordinary (a game). Whether you’re a developer looking for a fun side project or a roguelike fan curious about procedural design, this approach offers a fresh way to explore both code and creativity.