diff --git a/README.md b/README.md index 5470d81..3e2808c 100644 --- a/README.md +++ b/README.md @@ -17,26 +17,27 @@ ## 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. +**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 (made with p5.js). ### Gameplay Flow ``` -START SCREEN (img_start.png) +START SCREEN ↓ Press R GAMEPLAY (60 seconds) ↙ Time Up / Found Exit ↖ -GAME OVER NEXT LEVEL -(img_jobapplication.png + Particles) +GAME OVER NEXT LEVEL +(Job Application +Jumpscare) ``` ### 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. +3. **Find the Key:** **Left-Click** chests until you find the key, do not click on a chest you have opened before (leads to game over) 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 +5. **Survive the Time:** You have 60 seconds per round. Time runs out = Game Over (Job Application Jumpscare ending) 6. **Progress:** Successfully exiting unlocks the next level with a larger maze and more chests ### Controls @@ -56,10 +57,9 @@ GAME OVER NEXT LEVEL ## 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) +- **3D Graphics:** Babylon.js (3D scene, camera, meshes, rendering) +- **2D Graphics:** p5.js (particle effects for game-over screen) +- **Audio:** Web Audio API ### Files Structure @@ -67,12 +67,12 @@ GAME OVER NEXT LEVEL src/ ├── babylon_panel.js # Game orchestrator (scene init, controller, API) ├── html_panel.js # Debug UI state management -├── p5_particles.js # Particle effects for start/game-over screens +├── p5_particles.js # Particle effects for game over screen ├── game/ -│ ├── state.js # ✓ Shared game state (config + runtime) -│ ├── maze.js # ✓ Procedural maze generation (seeded RNG) -│ ├── grid.js # ✓ Coordinate conversion, collision helpers -│ ├── sfx.js # ✓ Sound effect playback system +│ ├── state.js # Shared game state (config + runtime) +│ ├── maze.js # Procedural maze generation (seeded RNG) +│ ├── grid.js # Coordinate conversion, collision helpers +│ ├── sfx.js # Sound effect playback system │ ├── scene-init.js # Babylon.js engine & scene initialization │ ├── camera-manager.js # Camera creation, mode switching, updates │ ├── game-loop.js # Main render loop, game state machine @@ -113,7 +113,7 @@ sfx/ - **controls/**: Input and event handling - **assets/**: Reusable factories (materials, textures) - **ui/**: Visual feedback (HUD, overlays) -- Root level (babylon_panel.js): Main orchestrator that ties everything together +- Root level (babylon_panel.js): Main script that ties everything together ### Core Modules @@ -126,7 +126,7 @@ sfx/ - Input handler registration via `setupInputHandlers()` - Game loop registration via `registerGameLoop()` - Screen transitions via `showGameOverScreen()`, `hideGameOverScreen()`, etc. -- Level generation orchestration +- Level generation coordination - State management and API exposure **Key Flow:** @@ -135,7 +135,7 @@ Page Load → babylon_panel.js ↓ initialize scene, cameras, sphere ↓ setupInputHandlers() → register keyboard/pointer events ↓ registerGameLoop() → register frame-by-frame updates - ↓ showStartScreen() → p5 particle sketch + ↓ showStartScreen() ↓ (user presses R) ↓ startRunFromStartScreen() → generateLevel() ↓ (gameplay loop runs until win/lose) @@ -155,7 +155,7 @@ Page Load → babylon_panel.js **Benefits:** - Encapsulates Babylon.js boilerplate - Easier to swap or test rendering configuration -- Decouples orchestrator from engine details +- Decouples main scene runner from engine details #### 3. **game/camera-manager.js** (Camera Management) **Purpose:** First-person and overview camera creation and switching @@ -380,37 +380,26 @@ Each call to `playSfx()` clones the audio node, allowing multiple sounds to play **Benefits:** - Polyphonic sound effects (no cutting each other off) - Browser-compatible audio context priming -- ES6 imports ensure assets are bundled by Vite - Centralized audio management (easy to add volume controls, reverb, etc.) --- ## 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:** -- Asset optimization (textures, audio) -- Efficient raycasting for chest targeting (not per-pixel) -- Single draw call per maze (not per cell) +| Feature | Implementation | +|---------|----------------| +| **3D Rendering** | Babylon.js UniversalCamera, procedural mesh generation | +| **Procedural Mazes** | Seeded random generation with configurable dimensions | +| **Time-Attack Mode** | 60-second countdown timer with auto-game-over on timeout | +| **Progressive Difficulty** | Maze size & chest count increase per completed level | +| **Collision Detection** | Raycasting for chest interaction, sphere collision for exit | +| **Sound System** | polyphonic sound effects with Web Audio API | +| **Particle Effects** | p5.js animated particles with physics on game-over screen | +| **Start Screen** | Full-screen p5.js panel with starting image | +| **Game-Over Screen** | Full-screen overlay with job application image + particles | +| **Visual Warnings** | Red pulsing timer + clock sound when time < 10 seconds | +| **Camera Modes** | First-person (WASD + mouse) and overhead orbital view | +| **Responsive Layout** | Full-screen canvas with bottom-overlay debug controls | **Code Quality Patterns:** - **Shared State Pattern:** `window.mazeGameState` prevents data coupling across modules @@ -418,21 +407,11 @@ Each call to `playSfx()` clones the audio node, allowing multiple sounds to play - **Observer Pattern:** `registerBeforeRender()` for frame-synchronized updates - **Async/Await:** p5.js async image loading for non-blocking resource loading ---- - -## Known Issues & Limitations - -### ⚠️ Known Problems +**Known Problems** 1. **Pointer Lock Exit:** Pointer lock may be annoying for newcomers to web browser games 2. **Chunk Size Warning:** Built JavaScript is ~9.1 MB due to image assets - Not an issue for local play -### ⭐ 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 @@ -507,7 +486,6 @@ babylon_panel.js (orchestrator) ← high-level control **Decision:** Use seeded random number generator for deterministic maze generation **Rationale:** -- Same seed produces identical maze (perfect for replays/debugging) - Varied layouts via different seeds (infinite replayability) - Better than storing pre-made levels (scalable to any difficulty) - Recursive backtracking ensures every maze is solvable @@ -521,27 +499,17 @@ babylon_panel.js (orchestrator) ← high-level control - **Early Development:** Suggested separating static maze data from dynamic game state (prevents coupling) - **Module Organization:** Proposed logical file structure to improve maintainability - **Code Review:** Reviewed p5.js particle physics, Babylon.js camera control, Web Audio API integration - - **Refactoring (Phase 3):** Assisted with modularizing 570-line monolithic file into 14 focused modules + - **Refactoring:** Assisted with modularizing 570-line monolithic file into 14 focused modules - Extracted scene initialization, camera management, game loop, level generation, collision detection - Created input handler, material factories, HUD updates, screen manager modules - Verified no breaking changes, ensured build compatibility, tested audio bundling + - **Documentation:** ### Resources & Documentation - **Babylon.js Playground:** Reference for collision detection, camera control, and mesh creation -- **p5.js Documentation:** Async setup pattern for p5.js 2.0+ (no `preload()` function) -- **MDN Web Audio API:** Context priming and polyphonic sound playback patterns -- **Vite Documentation:** ES6 module bundling, asset optimization, and build configuration --- ## 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. - +**Untitled Maze Game** was an interesting project as it made me realize that a lot is possible simply through javascript libraries and today's LLMs. AI really saved a lot of time that would have normally taken me hours to debug, and having dialogue with the AI over the code structure and such was quite helpful and interesting. diff --git a/index.html b/index.html index 934dede..2cdc317 100644 --- a/index.html +++ b/index.html @@ -33,7 +33,7 @@