@hhoangphuoc/escape-room-cli/readme.md

A CLI for playing AI-generated escape room games. Install globally with: npm install -g @hhoangphuoc/escape-room-cli

# 🎮 AI Escape Room CLI Game

**An immersive, AI-powered escape room experience in your terminal!**

## Table of Contents
1. [🎯 Game Overview](#-game-overview)
2. [🎮 How to Play](#-how-to-play)
3. [🚀 Getting Started](#-getting-started)
4. [📋 Commands Reference](#-commands-reference)
5. [🤖 AI Models](#-ai-models)
6. [🏆 Leaderboard & Scoring](#-leaderboard--scoring)
7. [🔧 API Reference](#-api-reference)
8. [🎨 Features](#-features)
9. [🛠️ Development](#-development)

---

## 🎯 Game Overview

**AI Escape Room** is a terminal-based puzzle game where artificial intelligence creates unique, challenging escape room experiences. Each room is dynamically generated with:

- **🏠 Unique Environments**: AI-crafted rooms with immersive backgrounds and storylines
- **🔍 Interactive Objects**: Puzzles, clues, and artifacts to discover and solve
- **🧩 Dynamic Challenges**: Each playthrough offers different puzzles and solutions
- **🏆 Competitive Scoring**: Leaderboard system tracking speed and efficiency
- **🤖 AI Assistance**: Multiple AI models available to help you solve puzzles

### Game Modes
- **Single Room**: Perfect for quick challenges (5-15 minutes)
- **Multi Room**: Extended adventures with connected storylines (30-60 minutes)

### Purpose
This game combines the thrill of escape rooms with the creativity of AI to create:
- Educational puzzle-solving experiences
- Entertainment for puzzle enthusiasts
- A showcase of AI-generated content capabilities
- Competitive leaderboard challenges

## 🎮 How to Play

### Step-by-Step Guide

1. **🚀 Start the Game**
   ```bash
   escape-room-cli --register --name="YourName" --email="your@email.com"
   ```

2. **🎯 Create Your First Room**
   ```bash
   /newgame
   ```

3. **👀 Explore Your Environment**
   ```bash
   /look                   # See what's in your room
   ```

4. **🔍 Investigate Objects**
   ```bash
   /inspect desk           # Examine the desk for clues
   /inspect painting       # Look at the painting
   ```

5. **🧩 Solve Puzzles**
   ```bash
   /guess safe 1234        # Try to unlock the safe with code 1234
   /guess book shakespeare # Answer a literature puzzle
   ```

6. **💡 Get Help When Stuck**
   ```bash
   /hint                   # Get a contextual hint
   Ask AI: "What should I do next?"  # Natural language help
   ```

7. **🔓 Escape the Room**
   ```bash
   /password escape123     # Try the final password
   ```

### Game Flow
```
Start Game → Look Around → Inspect Objects → Solve Puzzles → Find Password → Escape!
     ↓            ↓             ↓              ↓              ↓           ↓
  /newgame    →  /look     →  /inspect    →  /guess     →  /password  → 🎉
```

---

## 🚀 Getting Started

### Prerequisites
- Node.js >= 18.x
- npm (or yarn)
- OpenAI API key (for AI features)

### Installation
```bash
# Install globally
npm install -g @hhoangphuoc/escape-room-cli

# Or run directly
npx @hhoangphuoc/escape-room-cli
```

### First Time Setup
```bash
# Register your account
escape-room-cli --register --name="YourName" --email="your@email.com"

# Or start and register interactively
escape-room-cli
```

### With AI Support
```bash
# Set your OpenAI API key for AI assistance
export OPENAI_API_KEY="your_api_key_here"
escape-room-cli --register --name="YourName" --email="your@email.com"
```

---

## 📋 Commands Reference

### 🎮 Game Commands
| Command | Description | Example |
|---------|-------------|---------|
| `/newgame (optional: [mode])` | Start a new game | `/newgame single-room` |
| `/look` | Examine current room | `/look` |
| `/inspect [object]` | Inspect an object | `/inspect desk` |
| `/guess [object] [answer]` | Solve a puzzle | `/guess safe 1234` |
| `/password [password]` | Try final password | `/password escape123` |
| `/hint` | Get contextual hint | `/hint` |
| `/restart` | Restart current game | `/restart` |

### 🤖 AI & System Commands
| Command | Description | Example |
|---------|-------------|---------|
| `/model` | Change AI model | `/model` |
| `/instructions` | Show detailed tutorial | `/instructions` |
| `/help` | Show command list | `/help` |
| `/history` | Show command history | `/history` |
| `/leaderboard` | View top players | `/leaderboard` |

### 👤 Account Commands
| Command | Description | Example |
|---------|-------------|---------|
| `/register` | Create new account | `/register` |
| `/login` | Log into account | `/login` |
| `/logout` | Log out | `/logout` |

### 💬 Natural Language
You can also ask questions in natural language:
```bash
"What should I do next?"
"How do I solve this puzzle?"
"Can you help me with the safe?"
```

### ⚡ Tab Completion
The CLI supports intelligent tab completion:
- **Commands**: Type `/` and press Tab to see available commands
- **Objects**: In `/inspect` and `/guess` commands, press Tab to auto-complete object names
- **Smart Suggestions**: Contextual suggestions based on current room objects

---

## 🤖 AI Models

The game supports multiple AI models, each with different capabilities:

### Available Models

| Model | Icon | Thinking | Reasoning | Speed | Cost | Best For |
|-------|------|----------|-----------|-------|------|----------|
| **gpt-4.1-mini** | ⚡ | ████░ | ███░░ | █████ | Low | Quick hints, general help |
| **gpt-4.1** | 🧠 | █████ | ████░ | ███░░ | High | Detailed explanations |
| **gpt-4o** | 🎯 | █████ | ████░ | ███░░ | Very High | Complex visual puzzles |
| **o3-mini** | 🔬 | ████░ | █████ | ████░ | Medium | Logical puzzles |
| **o4-mini** | 🚀 | ████░ | █████ | ████░ | Medium | Advanced reasoning |
| **o3** | 💎 | █████ | █████ | ██░░░ | Very High | Ultimate challenges |

### Model Categories
- **🔵 Standard**: General conversation and basic help
- **🟣 Reasoning**: Complex logical challenges and puzzles
- **🟢 Multimodal**: Visual and complex multi-step tasks

Use `/model` to switch between models during gameplay.

---

## 🏆 Leaderboard & Scoring

### Scoring System
Your score is based on:
- **⏱️ Completion Time**: Faster = Better score
- **💡 Hints Used**: Fewer hints = Higher ranking
- **🎯 Game Mode**: Multi-room games worth more points

### Leaderboard Features
- **🏆 Global Rankings**: Top 10 players across all modes
- **📊 Personal Stats**: Track your improvement over time
- **🎮 Mode-Specific**: Separate rankings for single and multi-room
- **⚡ Real-time Updates**: Live leaderboard updates

### Viewing Leaderboard
```bash
/leaderboard        # View top 10 players
```

---

## 🔧 API Reference (For Devs)

### Game API Endpoints

#### Authentication
```http
POST /api/auth/register
Body: { name: string, email: string, apiKey?: string }
Response: { token: string, userId: string }

POST /api/auth/login
Body: { userId: string, apiKey?: string }
Response: { token: string }
```

#### Game Management
```http
POST /api/game/newgame
Headers: { Authorization: Bearer <token> }
Body: { mode: 'single-room' | 'multi-room' }
Response: { success: boolean, game: GameData }

GET /api/game/state
Headers: { Authorization: Bearer <token> }
Response: { game: GameState }
```

#### Game Actions
```http
GET /api/game/look
Headers: { Authorization: Bearer <token> }
Response: { roomName: string, objects: string[], background: string }

GET /api/game/inspect?object=<name>
Headers: { Authorization: Bearer <token> }
Response: { object: ObjectData }

POST /api/game/guess?object=<name>&answer=<answer>
Headers: { Authorization: Bearer <token> }
Response: { success: boolean, object: ObjectData }

POST /api/game/password?password=<password>
Headers: { Authorization: Bearer <token> }
Response: { escaped: boolean, timeElapsed: number }
```

#### AI Chat
```http
POST /api/game/chat
Headers: { Authorization: Bearer <token> }
Body: { message: string, model: string }
Response: { response: string }
```

#### Leaderboard
```http
GET /api/game/leaderboard/games
Headers: { Authorization: Bearer <token> }
Response: { leaderboard: PlayerScore[] }
```

### Response Types
```typescript
interface GameData {
  id: string;
  name: string;
  background: string;
  mode: 'single-room' | 'multi-room';
  currentRoom: number;
  totalRooms: number;
  objectCount: number;
}

interface ObjectData {
  name: string;
  description: string;
  puzzle?: string;
  unlocked: boolean;
  details?: string[];
}

interface PlayerScore {
  userName: string;
  timeElapsed: number;
  hintsUsed: number;
  gameMode: string;
  completedAt: string;
}
```

---

## 🎨 Features

### ✨ Core Features
- **🎯 Dynamic Room Generation**: AI creates unique rooms every time
- **🔍 Interactive Objects**: Puzzles, clues, and hidden secrets
- **🧩 Varied Puzzle Types**: Logic, riddles, codes, and word puzzles
- **🏆 Competitive Scoring**: Speed and efficiency tracking
- **🤖 AI Assistance**: Multiple AI models for different help styles

### 🎪 UI Features
- **🎨 Rich Terminal UI**: Beautiful, responsive terminal interface
- **📱 Intuitive Navigation**: Easy-to-use command system
- **🎮 Full-Screen Overlays**: Instructions, leaderboard, and model selection
- **⚡ Real-time Updates**: Live game state and progress tracking
- **🎯 Visual Feedback**: Color-coded responses and status indicators

### 🔧 Technical Features
- **💾 Persistent State**: Save and resume game progress
- **🌐 API-First Design**: RESTful API for all game operations
- **🎛️ Configurable**: Customizable AI models and game settings

---

## 🛠️ Development

### Project Structure
```
escape-room-cli/
├── source/
│   ├── components/          # React components
│   │   ├── Instructions.tsx # Game tutorial
│   │   ├── Leaderboard.tsx  # Score display
│   │   ├── ModelSelector.tsx # AI model selection
│   │   └── Terminal.tsx     # Main game interface
│   ├── utils/              # Utility functions
│   │   ├── constants.ts    # Game constants
│   │   ├── commandHandlers.ts # Command processing
│   │   └── commandProcessor.ts # Command routing
│   └── app.tsx             # Main application
├── dist/                   # Compiled output
├── package.json
└── readme.md
```

### Build Commands
```bash
npm run build              # Compile TypeScript
npm run dev               # Development with watch
npm start                 # Run compiled CLI
npm run lint             # Code linting
npm run format           # Code formatting
```

### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

---

## 📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

**Ready to escape? Start your adventure now!**

```bash
# Install globally first
npm install -g @hhoangphuoc/escape-room-cli

# Then start playing
escape-room-cli
```