🎮 Play Now - No Installation Required! 🎮

---

An interactive browser-based terminal learning game that teaches shell commands through adventure and storytelling.

📖 Overview

Terminal Quest is an immersive browser-based adventure game where you learn real terminal commands by navigating through story-driven levels. Powered by xterm.js, it features a fully simulated virtual file system running directly in your browser—no installation or setup required. Each level presents unique challenges that can only be solved by mastering file system operations and command-line skills in a safe, sandboxed environment.

🖥️ Multi-Environment Support

NEW! Choose your terminal environment:

• macOS Terminal - Use Unix/Mac commands (ls, cat, grep, etc.)
• Windows Command Prompt - Use Windows commands (dir, type, findstr, etc.)
• Linux Terminal - Use Linux commands (ls, cat, grep, etc.)

The game automatically translates commands to work with your selected environment!

✨ Features

• No Installation Required: Play instantly in your browser
• Real Terminal Emulator: Powered by xterm.js for authentic terminal experience
• Interactive Storytelling: Engage with narrative-driven gameplay
• Virtual File System: Fully simulated file system—safe environment to practice without risk
• Progressive Learning: Start with basics, advance to complex operations
• Visual Feedback: ASCII art scenes that change based on your location
• Objective-Based Gameplay: Clear goals to guide your learning
• Multiple Levels: Forest (Beginner), Cabin (Intermediate), Tower (Advanced)
• Cross-Platform Commands: Practice bash/zsh (macOS/Linux) or PowerShell/CMD (Windows)

🚀 Quick Start

Play the Game

👉 Launch Terminal Quest - Opens in your browser, no installation needed!

How to Play

1. Choose your terminal environment (macOS/Linux or Windows)
2. Select a level to begin your quest
3. Read the story and objectives carefully
4. Type terminal commands to navigate and solve challenges
5. Type help to see available commands for your environment
6. Complete all objectives to win the level!

📚 Documentation

• Quick Start Guide - Detailed getting started guide
• Cheat Sheet - Command reference and walkthroughs for all environments
• Developer Guide - For contributors
• Full Documentation - Complete documentation index

🎯 Available Commands

Command	Usage	Description
ls	ls [path]	List directory contents
cd	cd <path>	Change directory
pwd	pwd	Print working directory
mkdir	mkdir <name>	Create a directory
touch	touch <file>	Create a file
mv	mv <src> <dest>	Move/rename file or directory
cp	cp <src> <dest>	Copy file or directory
rm	rm [-r] <path>	Remove file/directory
cat	cat <file>	Display file contents
clear	clear	Clear the screen
help	help	Show help message
exit	exit or quit	Exit the game

🌲 Level 1: Forest (Beginner)

Objectives:

1. Navigate into the forest directory
2. Create a camp directory in the forest
3. Create a fire.txt file in the camp
4. Move oak.txt into the grove directory
5. Create water.txt in the river directory

Skills Learned:

• Basic navigation (cd, pwd, ls)
• Creating files and directories (touch, mkdir)
• Moving files (mv)

📁 Project Structure

terminal-quest/
├── src/
│   ├── engine/              # Core game engine
│   │   ├── commandParser.js     # Parse user input
│   │   ├── commandExecutor.js   # Execute commands
│   │   ├── gameLoop.js          # Main game loop
│   │   ├── stateManager.js      # Game state management
│   │   └── validator.js         # Objective validation
│   │
│   ├── filesystem/          # Virtual file system
│   │   ├── virtualFileSystem.js # VFS implementation
│   │   └── fileUtils.js         # File system utilities
│   │
│   ├── ui/                  # User interface
│   │   ├── renderer.js          # Screen rendering
│   │   ├── asciiLoader.js       # ASCII art loading
│   │   └── prompt.js            # User input handling
│   │
│   ├── levels/              # Game levels
│   │   ├── forest/             # Forest level (beginner)
│   │   ├── cabin/              # Cabin level (intermediate)
│   │   └── tower/              # Tower level (advanced)
│   │
│   ├── data/                # Game data
│   │   └── commands.js         # Command definitions
│   │
│   ├── utils/               # Utilities
│   │   ├── logger.js           # Logging utility
│   │   └── helpers.js          # Helper functions
│   │
│   └── index.js             # Entry point
│
├── package.json
└── README.md

🛠️ Development

Want to contribute or run locally? Great!

Local Setup

# Clone the repository
git clone https://github.com/yourusername/terminal-quest.git
cd terminal-quest

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Adding New Levels

1. Create a new folder in src/levels/
2. Add these files:
   • filesystem.json - Initial file system structure
   • objectives.js - Level objectives
   • index.js - Level configuration
   • ascii/ - Directory with ASCII art scenes

Example level structure:

// src/levels/newlevel/index.js
export const newLevel = {
  name: "Level Name",
  description: "Level description",
  initialFileSystem: parseFileSystemJSON(fsJson),
  objectives: objectives,
  intro: "Introduction text",
  outro: "Completion text",
};

Adding New Commands

1. Add command to src/data/commands.js
2. Implement handler in src/engine/commandExecutor.js
3. Update help text

File System Format

{
  "directory": {
    "file.txt": "File content",
    "subdirectory": {
      "nested.txt": "Nested content"
    }
  }
}

🎨 Customization

Changing Colors

Edit color schemes in the terminal theme configuration in src/io/browser.js:

theme: {
  background: "#1e1e1e",
  foreground: "#d4d4d4",
  cyan: "#11a8cd",
  green: "#0dbc79",
  // ... more colors
}

Adding ASCII Art

Create .txt files in src/levels/[level]/ascii/ directory.

🧪 Testing

# Run the development server with hot reload
npm run dev

# Build and preview production build locally
npm run build
npm run preview

📚 Learning Path

1. Forest Level: Master basic navigation and file operations
2. Cabin Level: Learn intermediate concepts (coming soon)
3. Tower Level: Advanced challenges (coming soon)

🤝 Contributing

This project is designed to be extensible. Feel free to:

• Add new levels
• Create new commands
• Improve ASCII art
• Enhance the story
• Add new features

📝 Technical Details

• Platform: Browser-based web application
• Frontend: JavaScript (ES Modules), Vite
• Terminal Emulator: xterm.js with FitAddon
• Styling: CSS3, Chalk (for ANSI colors)
• Virtual File System: Custom JavaScript implementation
• Architecture: Modular, event-driven game engine
• Deployment: Static hosting (Amplify, Netlify, Vercel compatible)

🔧 Troubleshooting

Commands not working:

• Type help to see available commands for your selected environment
• Check spelling and syntax carefully
• Some commands require arguments (e.g., cd forest)
• Make sure you've selected the correct environment (macOS/Linux vs Windows)

Objectives not completing:

• Use ls to verify files exist
• Use pwd to check your current location
• Ensure files/directories are in the correct location
• Some objectives require exact file/folder names

Browser compatibility:

• Works best in modern browsers (Chrome, Firefox, Safari, Edge)
• Requires JavaScript enabled
• For best experience, use desktop/laptop (mobile is supported but limited)

📄 License

MIT License - See LICENSE file for details

🎓 Educational Use

Terminal Quest is perfect for:

• Teaching terminal basics to beginners
• Reinforcing command-line skills
• Interactive coding bootcamps
• Self-paced learning

---

Ready to start your quest? 🚀 Play Terminal Quest Now - No installation required!