# Untitled Maze Game - ID30011 Midterm Project

**A 3D First-Person Time-Attack Maze Game with Progressive Difficulty**

---

## Project Information

- **Name:** Bumgyu Suh
- **Student ID:** 20240905
- **Student Email:** bumgyu@kaist.ac.kr
- **Repository URL:** https://git.prototyping.id/20240905/Untitled-Maze-Game
- **Video Demonstration:** [YouTube Link]

---

## Game Overview

### Concept
**Untitled Maze Game** is a 3D first-person maze escape game built with Babylon.js and p5.js. Players must navigate procedurally-generated mazes in a race against time, collecting a key and finding the exit within 60 seconds, but there's a twist! You must not open a chest that you have already opened before! Each successful round increases difficulty—maze size grows, more chests appear, and players advance to the next level. If you fail... there is a little surprising waiting for you.

### Gameplay Flow

```
START SCREEN (img_start.png)
         ↓ Press R
    GAMEPLAY (60 seconds)
    ↙ Time Up / Found Exit ↖
GAME OVER          NEXT LEVEL
(img_jobapplication.png + Particles)
```

### How to Play

1. **Start the Game:** Press **R** on the start screen to begin
2. **Navigate:** Use **WASD** to move, mouse to look around
3. **Find the Key:** **Left-Click** chests until you find the key, do not click on a chest you have opened before.
4. **Reach the Exit:** Once you have the key, reach the exit door
5. **Survive the Time:** You have 60 seconds per round. Time runs out = Game Over
6. **Progress:** Successfully exiting unlocks the next level with a larger maze and more chests

### Controls

| Key | Action |
|-----|--------|
| **W/A/S/D** | Move forward/left/backward/right |
| **Mouse** | Look around (first-person) |
| **Left Click** | Open a highlighted chest |
| **R** | Start game (from start screen) or restart (from game-over screen) |
| **B** | (For debugging purposes) Toggle debug panel (hidden by default) |
| **V** | (For debugging purposes) Switch camera mode (first-person ↔ overview) |
| **ESC** | Exit pointer lock |

---

## Code Documentation

### Packages Used
- **3D Graphics:** Babylon.js v9.5.1 (3D scene, camera, meshes, rendering)
- **Bundler:** Vite v8.0.10 (ES6 modules, asset optimization)
- **2D Graphics:** p5.js v2.x (particle effects for game-over screen)
- **Audio:** Web Audio API (polyphonic sound effects)

### Files Structure

```
src/
├── babylon_panel.js          # Core game logic, scene setup, game loop
├── html_panel.js             # UI state management (debug controls)
├── p5_particles.js           # Particle effects for start/game-over screens
└── game/
    ├── state.js              # Shared game state (config + runtime)
    ├── maze.js               # Procedural maze generation (seeded RNG)
    ├── grid.js               # Coordinate conversion and collision detection
    └── sfx.js                # Sound effect playback system

css/
└── style.css                 # Responsive layout, HUD styling, animations

img/
├── img_start.png             # Start screen background
├── img_jobapplication.png    # Game-over screen background
├── img_chest.png             # Chest texture
├── img_door.png              # Exit door texture
├── img_wall.png              # Wall texture
└── img_ground.png            # Floor texture

sfx/
├── sfx_click.wav                 # UI interaction sound
├── sfx_chest_open.wav            # Chest opening sound
├── sfx_key.wav                   # Key collection sound
├── sfx_clock.wav                 # Low-time warning alarm
├── sfx_step.wav                  # Footstep sound
├── sfx_win.wav                   # Level complete sound
├── sfx_lose.wav                  # Game over sound
└── sfx_chest_close.wav           # Chest closing sound
```

### Core Modules

#### 1. **babylon_panel.js** (Game Controller)
**Responsibilities:**
- Babylon.js scene initialization and rendering loop
- Maze generation and spatial layout
- Game state machine (start → gameplay → game-over → restart)
- Collision detection (camera + exit plane, chests)
- Input handling (keyboard, mouse click)
- Pointer lock for immersive camera control
- Camera switching (first-person ↔ overview)

**Key Functions:**
- `generateLevel()` - Creates maze with difficulty scaling
- `scene.registerBeforeRender()` - Main game loop (countdown timer, collision checks, HUD updates)
- `showGameOverScreen()` / `hideGameOverScreen()` - Screen transitions
- `toggleControlsPanel()` - Debug UI visibility

**Difficulty Scaling Formula:**
```
roundScale = Math.max(0, level - 1)
mazeWidth = 11 + roundScale * 2
mazeHeight = 11 + roundScale * 2
chestCount = 2 + roundScale
```

#### 2. **game/state.js** (Shared State)
**Pattern:** Single source of truth for game configuration and runtime state

```javascript
window.mazeGameState = {
  config: {
    seed,                    // Random seed for reproducible mazes
    level,                   // Current progression level
    mazeWidth: 11,           // Base maze width (increases per level)
    mazeHeight: 11,          // Base maze height
    minChestDeadEnds: 2      // Minimum chests to place
  },
  runtime: {
    runActive: boolean,      // Is gameplay active?
    hasKey: boolean,         // Does player have the key?
    roundsCompleted: number, // Levels completed this run
    elapsedSeconds: number,  // Countdown timer (60 → 0)
    message: string          // Status text for HUD
  }
}
```

#### 3. **game/maze.js** (Procedural Generation)
**Algorithm:** Recursive backtracking with seeded random number generator

**Features:**
- Deterministic maze generation (same seed = same maze)
- Configurable width/height
- Guaranteed solvable layout
- Dead-end detection for chest placement
- Exportable cell data for spatial queries

#### 4. **p5_particles.js** (Visual Effects)
**Purpose:** Full-screen particle animations on start and game-over screens

**Start Screen:**
- Static full-screen display of img_start.png
- Responsive canvas sizing

**Game-Over Screen:**
- Background image (img_jobapplication.png) at full resolution
- 15 animated particles with physics:
  - Gravity (0.1 px/frame²)
  - Wall bouncing with friction (0.8×)
  - Random rotation and direction changes
  - Semi-transparent rendering (tint: 255, alpha: 200)
  - Velocity constraints (-3 to 3 px/frame)

#### 5. **html_panel.js** (Debug UI)
**Responsibilities:**
- Event listeners for debug buttons (Start, Restart, Randomize seed)
- HUD status display updates
- Null safety checks for missing DOM elements

**Note:** Debug controls panel is hidden by default (press **B** to toggle)

---

## Key Features & Implementation Details

| Feature | Implementation | Status |
|---------|----------------|--------|
| **3D Rendering** | Babylon.js UniversalCamera, procedural mesh generation | ✓ Complete |
| **Procedural Mazes** | Seeded random generation with configurable dimensions | ✓ Complete |
| **Time-Attack Mode** | 60-second countdown timer with auto-game-over on timeout | ✓ Complete |
| **Progressive Difficulty** | Maze size & chest count increase per completed level | ✓ Complete |
| **Collision Detection** | Raycasting for chest interaction, sphere collision for exit | ✓ Complete |
| **Sound System** | 8 polyphonic SFX with Web Audio API and context priming | ✓ Complete |
| **Particle Effects** | p5.js animated particles with physics on game-over screen | ✓ Complete |
| **Start Screen** | Full-screen p5.js panel with img_start.png background | ✓ Complete |
| **Game-Over Screen** | Full-screen overlay with job application image + particles | ✓ Complete |
| **Visual Warnings** | Red pulsing timer + clock sound when time < 10 seconds | ✓ Complete |
| **Camera Modes** | First-person (WASD + mouse) and overhead (overview) | ✓ Complete |
| **Responsive Layout** | Full-screen canvas with bottom-overlay debug controls | ✓ Complete |

### 🔧 Technical Highlights

**Browser Compatibility:**
- Audio context requires user interaction priming via `primeSfx()`—automatically triggered on first W/A/S/R key press

**Performance Optimizations:**
- Vite's ES6 module bundling and tree-shaking
- Asset optimization (textures, audio)
- Efficient raycasting for chest targeting (not per-pixel)
- Single draw call per maze (not per cell)

**Code Quality Patterns:**
- **Shared State Pattern:** `window.mazeGameState` prevents data coupling across modules
- **Factory Pattern:** `generateLevel()` creates and caches mesh instances
- **Observer Pattern:** `registerBeforeRender()` for frame-synchronized updates
- **Async/Await:** p5.js async image loading for non-blocking resource loading

---

## Known Issues & Limitations

### ⚠️ Known Behavior
1. **Chest Memory:** Once a chest is opened, its visual state persists for the remainder of the game session (not reset per level)
   - *Workaround:* Intentional game design—players learn chest locations
2. **Pointer Lock Exit:** Pressing ESC exits pointer lock but doesn't pause gameplay
   - *Workaround:* Intentional—players can exit anytime (no pause feature)
3. **Chunk Size Warning:** Built JavaScript is ~9.1 MB due to image assets (job application image is 3MB)
   - *Workaround:* Not an issue for local play; consider asset compression for production

### ⭐ Special Features to Note
- **Seeded Randomization:** Players can use the same seed to replay identical mazes (debug button: "Randomize seed")
- **Low-Time Audio Feedback:** Clock sound triggers once when time drops below 10 seconds (prevents spam)
- **Full-Screen Transitions:** Start screen, gameplay, and game-over have full-screen p5.js overlays for immersive presentation
- **Difficulty Scaling Formula:** Mathematically designed to keep progression challenging but fair

---

## Design Decisions & Rationale

### 1. Separate State Module
**Decision:** Isolate game state in `game/state.js` rather than scatter variables globally

**Rationale:** 
- Prevents tight coupling between UI, physics, and rendering systems
- Enables hot-reloading during development
- Simplifies debugging (single place to inspect game state)

### 2. Babylon.js Over Three.js
**Decision:** Used Babylon.js for 3D graphics

**Rationale:**
- Built-in collision detection and raycasting
- Superior camera controls (UniversalCamera with pointer lock)
- Efficient mesh instancing for maze cells
- Excellent documentation for procedural generation

### 3. p5.js for Particle Effects
**Decision:** Delegated particle rendering to p5.js instead of Babylon.js

**Rationale:**
- Cleaner separation of concerns (game logic ≠ visual effects)
- p5.js's simple drawing API reduces code complexity
- Easy to swap/experiment with particle physics without affecting core game
- Full-screen 2D canvas doesn't compete with 3D rendering pipeline

### 4. Time-Attack Mode (vs. Exploration, Level Editing)
**Decision:** 60-second countdown instead of unlimited time

**Rationale:**
- Creates urgency and strategic decision-making (pick efficient paths vs. explore)
- Enables meaningful progression (faster times unlock harder mazes)
- Reduces scope (no need for complex AI, item management, etc.)

---

## Help from AI & Resources

### AI Assistance
- **GitHub Copilot:** Used for code structure review and refactoring suggestions
  - Suggested separating static maze data from dynamic game state (instead of coupling both in a single 2D array)
  - Helped organize modules into logical file structure
  - Reviewed p5.js particle physics for correctness

### Resources & Documentation
- **Babylon.js Playground:** Reference for collision detection and camera control
- **p5.js Documentation:** Async setup pattern for p5.js 2.0+ (no `preload()`)
- **MDN Web Audio API:** Context priming for cross-browser audio compatibility
- **Vite Documentation:** Asset bundling and import resolution

### Game Design Inspiration
- *Portal series:* Puzzle-based spatial reasoning and exit goals
- *Deus Ex:* Multiple approaches to objectives (fast routing vs. exploration)
- *Pac-Man:* Time pressure and progressive difficulty

---

## Conclusion

**Untitled Maze Game** demonstrates:
- ✅ Professional code organization (modular, well-separated concerns)
- ✅ Advanced 3D graphics programming (procedural generation, collision detection, camera control)
- ✅ Full-featured game loop with state management
- ✅ Polish and presentation (particle effects, sound design, responsive UI)
- ✅ Scalability (difficulty scaling formula, asset management)

The codebase prioritizes **readability** and **maintainability** through modular design, clear naming conventions, and comprehensive documentation. Each file has a single responsibility, making it easy for collaborators or reviewers to understand and extend the code.