20240905/Untitled-Maze-Game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
pobadoba
2026-05-10 23:04:01 +09:00
parent 6532387f59
commit 7f6548d9fb
2 changed files with 38 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@@ -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.