🎮 AI Escape Room CLI Game

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

Table of Contents

1. 🎯 Game Overview
2. 🎮 How to Play
3. 🚀 Getting Started
4. 📋 Commands Reference
5. 🤖 AI Models
6. 🏆 Leaderboard & Scoring
7. 🔧 API Reference
8. 🎨 Features
9. 🛠️ 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)

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

   /register 
      
   or 
      
   /login

2. 🎯 Create Your First Room

   /newgame

3. 👀 Explore Your Environment

   /look                   # See what's in your room

4. 🔍 Investigate Objects

   /inspect desk           # Examine the desk for clues
   /inspect painting       # Look at the painting

5. 🧩 Solve Puzzles

   /guess safe 1234        # Try to unlock the safe with code 1234
   /guess book shakespeare # Answer a literature puzzle

6. 💡 Get Help When Stuck

   /hint                   # Get a contextual hint
   Ask AI: "What should I do next?"  # Natural language help

7. 🔓 Escape the Room

   /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

# Install globally
npm install @hhoangphuoc/escape-room-cli@latest

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

First Time Setup

# Register your account
/register

# Or start and register interactively
escape-room-cli

With AI Support

# Set your OpenAI API key for AI assistance
export OPENAI_API_KEY="your_api_key_here"

📋 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 | | /cost | Show current session cost and token usage | /cost | | /usage | Show detailed AI usage statistics dashboard | /usage | | /instructions | Show detailed tutorial | /instructions | | /help | Show command list | /help | | /history | Show enhanced conversation history with analytics | /history | | /leaderboard | View top players | /leaderboard | | /end-session | End session and save conversation to Firebase | /end-session |

👤 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:

"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
• 🎯 AI Usage: Lower cost + Less token = Higher ranking

Leaderboard Features

• 🏆 Global Rankings: Top 10 players across all modes
• 📊 Personal Stats: Track your improvement over time
• ⚡ Real-time Updates: Live leaderboard updates

Viewing Leaderboard

/leaderboard        # View top 10 players

🔧 API Reference (For Devs)

Game API Endpoints

Authentication

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

POST /api/game/newgame
Headers: { Authorization: Bearer <token> }
Body: { mode: 'single-room'}
Response: { success: boolean, game: GameData }

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

Game Actions

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

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

Leaderboard

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

Response Types

interface GameData {
  id: string;
  name: string;
  background: string;
  mode: 'single-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
• 📝 Conversation Tracking: Complete conversation history with token usage and cost tracking
• 💰 Advanced Cost Analytics: Per-message cost tracking and session totals

📊 Conversation History & Analytics

Enhanced History Features

The CLI now provides comprehensive conversation tracking and analytics:

📝 /history Command

The /history command now shows:

• Complete conversation timeline with user inputs and AI responses
• Model information showing which AI model generated each response
• Reasoning process for reasoning models (o3, o4, gpt-5)
• Timestamp and metadata for each conversation entry

💾 Automatic Data Persistence

• Game Completion: Conversations automatically saved to Firebase when games complete
• Manual Save: Use /end-session to save conversation data manually
• Historical Access: Retrieve conversation history for past games via API

📈 Usage Analytics

The /usage command provides detailed insights:

• Token consumption across different models
• Cost efficiency analysis for your sessions

🛠️ Development

Project Structure

escape-room-cli/
├── source/
│   ├── components/             # React components
│   │   ├── Instructions.tsx    # Game tutorial
│   │   ├── Leaderboard.tsx     # Score display
│   │   ├── ModelSelector.tsx   # AI model selection
│   │   ├── ConversationHistory.tsx # NEW: Rich conversation history display
│   │   ├── CostMonitor.tsx     # Cost tracking display
│   │   ├── CostDashboard.tsx   # Detailed usage analytics
│   │   └── Terminal.tsx        # Main game interface (enhanced)
│   ├── context/               # React Context
│   │   └── AuthContext.tsx    # Authentication and conversation state (enhanced)
│   ├── utils/                 # Utility functions
│   │   ├── constants.ts       # Game constants
│   │   ├── commandHandlers.ts # Command processing
│   │   ├── commandProcessor.ts # Command routing (enhanced with conversation tracking)
│   │   └── responseTypes.ts   # TypeScript response types (enhanced)
│   └── app.tsx                # Main application
├── dist/                      # Compiled output
├── package.json
└── readme.md

Build Commands

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!

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

# Then start playing
escape-room-cli