mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-20 13:50:46 +00:00
9aae3f9443
- Created SoundManager class for handling audio playback using Phaser's sound system. - Added methods for preloading, initializing, and playing sounds with volume control. - Integrated UI sound helpers for easier sound attachment to DOM elements. - Updated game.js to initialize sound manager and preload sounds. - Modified interactions.js, unlock-system.js, and panels.js to play appropriate sounds on interactions. - Created SOUND_SYSTEM_QUICK_REFERENCE.md for documentation on sound system usage. - Optimized NPCBarkSystem and NPCManager with caching and event listener cleanup.
11 KiB
11 KiB
Sound System Architecture Diagram
System Components
┌─────────────────────────────────────────────────────────────┐
│ BREAK ESCAPE GAME │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Phaser Game Instance (game.js) │ │
│ │ - Manages scenes, physics, rendering │ │
│ └──────────────────┬───────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SoundManager (sound-manager.js) │ │
│ │ │ │
│ │ Preload Phase: │ │
│ │ • Load all 34 audio assets │ │
│ │ • Register with Phaser.sound │ │
│ │ │ │
│ │ Create Phase: │ │
│ │ • Initialize sound objects │ │
│ │ • Set default volumes │ │
│ │ • Attach to window.soundManager │ │
│ │ │ │
│ │ Runtime: │ │
│ │ • Play/stop sounds │ │
│ │ • Manage volumes (master + categories) │ │
│ │ • Toggle enable/disable │ │
│ └──────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │ Game │ │ UI Sound │ │ Game │ │
│ │ Systems │ │ Helpers │ │ Events │ │
│ │ │ │ │ │ │ │
│ │ Interact. │ │ DOM attach │ │ Door knock │ │
│ │ Unlock │ │ Quick play │ │ Chair roll │ │
│ │ Panels │ │ Categorize │ │ Messages │ │
│ └────────────┘ └────────────┘ └──────────────┘ │
│ │ │ │ │
└────────┼──────────────┼───────────────┼──────────────────────┘
│ │ │
└──────────────┴───────────────┘
│
▼
┌────────────────────────────┐
│ Phaser Sound System │
│ │
│ • Sound pooling │
│ • 3D audio (reserved) │
│ • Effects & filters │
│ • Playback control │
└────────────────────────────┘
│
▼
┌────────────────────────────┐
│ Web Audio API │
│ (Browser Native) │
│ │
│ • Decoding │
│ • Mixing │
│ • Output routing │
└────────────────────────────┘
│
▼
┌────────────────────────────┐
│ Audio Files (MP3) │
│ /assets/sounds/ │
│ │
│ • 34 sounds total │
│ • GASP & custom effects │
└────────────────────────────┘
Data Flow
Sound Playback Flow
User Action (Click, Item pickup, etc.)
│
▼
Event Handler
│
▼
playUISound('click') / playGameSound('name')
│
▼
UI Sound Helper (ui-sounds.js)
│
▼
window.soundManager.play() or specific method
│
▼
SoundManager retrieves Phaser sound object
│
├─ Get volume from category settings
├─ Apply master volume multiplier
└─ Call Phaser audio.play()
│
▼
Phaser Sound Object
│
▼
Web Audio API
│
▼
Speaker Output
Volume Cascade
Master Volume (0-1)
│
├─ Category Volume: UI (0-1)
│ └─ ui_click_1, ui_click_2, etc.
│
├─ Category Volume: Interactions (0-1)
│ └─ item_interact_*, lock_interact_*, door_knock
│
├─ Category Volume: Notifications (0-1)
│ └─ ui_alert_*, ui_notification_*, ui_reject
│
├─ Category Volume: Effects (0-1)
│ └─ lockpick_*, chair_roll, message_received
│
└─ Category Volume: Music (0-1)
└─ (reserved for future use)
Final Volume = Master × Category × Sound
Integration Points
1. Game Core
js/core/game.js
├─ preload()
│ ├─ Create SoundManager instance
│ └─ soundManager.preloadSounds()
│
└─ create()
├─ Create new SoundManager
├─ soundManager.initializeSounds()
└─ window.soundManager = soundManager
2. Interaction System
js/systems/interactions.js
├─ Item Collection (3 places)
│ └─ playUISound('item')
│
└─ Event: Object interaction starts
└─ playUISound('interaction')
3. Unlock System
js/systems/unlock-system.js
└─ handleUnlock()
├─ playUISound('lock')
└─ Continues with unlock logic
4. UI/Panels
js/ui/panels.js
├─ showPanel()
│ └─ playUISound('notification')
│
└─ togglePanel()
└─ playUISound('notification') if showing
5. Mini-Games
js/minigames/lockpicking/lockpicking-game-phaser.js
├─ preload()
│ ├─ load.audio('lockpick_binding')
│ ├─ load.audio('lockpick_click')
│ └─ ... (8 sounds)
│
└─ create()
├─ sound.add('lockpick_binding')
└─ ... (store references)
Usage:
├─ Lock manipulation → sounds.click.play()
├─ Tension applied → sounds.tension.play()
├─ Pin set → sounds.set.play()
└─ Lock opened → sounds.success.play()
Sound Categories & Volumes
┌─────────────┬──────────────┬─────────────────────────────┐
│ Category │ Default Vol. │ Contains │
├─────────────┼──────────────┼─────────────────────────────┤
│ UI │ 0.7 │ Clicks, confirms │
│ Interact │ 0.8 │ Items, locks, doors │
│ Notif │ 0.6 │ Alerts, notifications │
│ Effects │ 0.85 │ Game-specific effects │
│ Music │ 0.5 │ (Reserved) │
└─────────────┴──────────────┴─────────────────────────────┘
Global Access Points
// Main entry point
window.soundManager
// Methods
.play(soundName, options)
.stop(soundName)
.stopAll()
.playUIClick()
.playUINotification()
.playItemInteract()
.playLockInteract()
.setMasterVolume(vol)
.setCategoryVolume(cat, vol)
.toggle()
.setEnabled(bool)
.isEnabled()
// Via UI helpers
playUISound(type) // 'click', 'notification', 'item', 'lock', etc.
playGameSound(name) // Direct sound name
attachUISound(elem, type)
Performance Characteristics
Memory
- Audio preloaded but not decoded until first play
- Decoded audio cached by Phaser
- Estimate: ~2-4MB for all 34 sounds
CPU
- Minimal CPU usage during playback
- Phaser handles efficient streaming
- Can play multiple sounds simultaneously
Network
- All sounds loaded on game start
- ~1-2 seconds additional load time
- Typical: 2-5MB total download
Error Handling
Try to play sound
├─ If soundManager exists
│ ├─ If sound name exists
│ │ └─ Play with category volume
│ └─ If sound name missing
│ └─ Warning: "Sound not found"
└─ If soundManager missing
└─ Warning: "Sound Manager not initialized"
Result: Graceful degradation, game continues
Testing Checklist
┌─ Load Phase
│ ├─ All 34 sounds preload successfully
│ └─ No 404 errors in console
│
├─ Init Phase
│ ├─ window.soundManager exists
│ └─ All 34 sounds initialized
│
├─ Playback
│ ├─ Item pickup plays sound
│ ├─ Lock attempt plays sound
│ ├─ UI panel open plays sound
│ ├─ Lockpicking sounds work
│ └─ All random variants play
│
├─ Volume Control
│ ├─ Master volume works
│ ├─ Category volumes work
│ └─ Mix adjusts correctly
│
├─ State Management
│ ├─ Toggle on/off works
│ ├─ Enable/disable works
│ └─ Stop all works
│
└─ Performance
├─ No audio lag
├─ No memory leaks
└─ Smooth playback