Splash
Start
Completion

🕹️ Project Story: Linux Dungeon

🚀 About the Project

Linux Dungeon is a browser-based fantasy puzzle game that runs entirely in a virtual Linux terminal. Players take on the role of an adventurer trapped in a digital dungeon, where the only way forward is to master real Linux commands. Each room is sealed inside a password-protected .zip file, and players must explore directories, decode clues, and edit configs to advance.

This project was built for the WebVM Hackathon, which challenged developers to create educational Linux experiences using the CheerpX-based virtualization engine.

📚 What Inspired It?

I wanted to make Linux fun and accessible — not through slides, but through an actual quest. Inspired by old-school text adventures, Runescape, and CTFs (Capture the Flag), I envisioned a game where you "dungeon crawl" using Linux knowledge.

Fantasy games like Zork and NetHack sparked the storytelling.
The WebVM terminal gave me the perfect environment: sandboxed, no setup, and fully in-browser.
I wanted to teach and entertain at the same time.

🛠️ How It Was Built

Platform: WebVM, built with CheerpX, a WebAssembly-based x86 virtualizer.
Filesystem Design: I modified the base Debian image in dockerfiles/debian_mini to embed a /game directory.
Rooms: Each room is its own folder, zipped with a password, and hidden until unlocked.
Tech Used:
- vim, cat, grep, find, strings, base64 and more
- ASCII art splash screen using .bashrc
- Custom Dockerfile to compile and bake in game logic
Deployment: GitHub Pages + GitHub Actions to automate WebVM builds

⚡ Challenges Faced

Mounting custom images in WebVM required understanding the internal disk image system.
Proper quote escaping in Docker (bash, echo, zip -P) took several painful iterations.
ASCII rendering in terminals required experimenting with size, clarity, and ANSI coloring.
User onboarding: making it clear what to do (e.g. unzip room1) without hand-holding.
Maintaining compatibility with CheerpX’s runtime expectations — especially with the WORKDIR, user ID, and filesystem structure.

🤖 What I Learned

Deepened my knowledge of Docker layering and Linux image baking
Got hands-on with CheerpX and in-browser x86 emulation
Learned how to turn shell-based learning into actual gameplay
Improved Markdown formatting, GitHub Actions, and static deployment flows

🌟 What’s Next

Add more room types: network puzzles (with Tailscale), scripting tasks, cron jobs
Visual cutscenes (in ASCII art!)
Multiplayer dungeon crawl (via WebSockets)