feat(npc): Add audio feedback for NPC bark notifications with message received sound

2026-02-20 13:50:46 +00:00 · 2025-10-31 21:10:07 +00:00
parent 40da85dac4
commit 34f1739484
4 changed files with 304 additions and 1 deletions
--- a/planning_notes/npc/SOUND_EFFECTS_IMPLEMENTATION.md
+++ b/planning_notes/npc/SOUND_EFFECTS_IMPLEMENTATION.md
@@ -0,0 +1,242 @@
+# NPC Sound Effects Implementation
+
+**Status:** ✅ Complete (2024-10-31)
+
+## Overview
+Added audio feedback to the NPC bark notification system. All bark notifications now play a sound effect when they appear, providing audio cues for player attention.
+
+## Implementation
+
+### Files Modified
+- **`js/core/game.js`** (+3 lines)
+  - Added `this.load.audio('message_received', ...)` in preload function
+  - Loads sound through Phaser's audio system
+- **`js/systems/npc-barks.js`** (+65 lines, modified)
+  - Replaced HTML5 Audio with Phaser sound manager
+  - Added lazy loading fallback
+  - Integrated sound playback into `showBark()` method
+
+### Sound Asset Used
+- **`assets/sounds/message_received.mp3`**
+  - Already existed in project
+  - Used for phone message notifications
+  - Now also used for NPC bark notifications
+  - **Loaded through Phaser's audio system** (Web Audio API)
+
+## Features
+
+### 1. Sound Preloading (Phaser)
+```javascript
+// In game.js preload()
+this.load.audio('message_received', 'assets/sounds/message_received.mp3');
+
+// In npc-barks.js
+loadBarkSound() {
+  if (window.game && window.game.sound) {
+    this.barkSound = window.game.sound.add('message_received');
+    this.barkSound.setVolume(0.5); // 50% volume
+  }
+}
+```
+- Sound loaded once during Phaser's preload phase
+- Managed by Phaser's Web Audio API system
+- Automatically pooled for efficient playback
+- Default volume: 50%
+
+### 2. Sound Playback (Phaser)
+```javascript
+playBarkSound() {
+  if (!this.soundEnabled) return;
+  
+  // Lazy load if not available during init
+  if (!this.barkSound && window.game && window.game.sound) {
+    this.loadBarkSound();
+  }
+  
+  if (!this.barkSound) return;
+  
+  this.barkSound.play(); // Phaser handles pooling
+}
+```
+- Uses Phaser's `.play()` method (cleaner than HTML5 Audio)
+- Phaser automatically handles sound pooling and memory management
+- Lazy loading fallback if sound manager not ready during init
+- No need to manually reset `currentTime` (Phaser handles this)
+
+### 3. Sound Control
+```javascript
+setSoundEnabled(enabled) {
+  this.soundEnabled = enabled;
+}
+```
+- Allows disabling sounds globally
+- Useful for settings/preferences
+- Default: enabled
+
+### 4. showBark() Integration
+```javascript
+showBark(payload = {}) {
+  const playSound = payload.playSound !== false; // Default true
+  
+  if (playSound) {
+    this.playBarkSound();
+  }
+  // ... rest of bark creation
+}
+```
+- Sound enabled by default for all barks
+- Can be disabled per-bark via `playSound: false` in payload
+- Respects global `soundEnabled` setting
+
+## What Gets Sound?
+
+### ✅ All Bark Notifications
+1. **Event-triggered barks**
+   - Door unlocks
+   - Item pickups
+   - Room discoveries
+   - Lockpicking attempts
+   - CEO office entry
+   - Any other event-mapped reactions
+
+2. **Timed messages**
+   - Scheduled NPC messages
+   - Delivered at specific game times
+   - Automatically trigger barks with sound
+
+3. **Manual barks**
+   - Any `npcManager.showBark()` calls
+   - Any `barkSystem.showBark()` calls
+
+### ❌ No Sound
+- Opening phone-chat minigame (no sound yet)
+- Closing phone-chat minigame (no sound yet)
+- Clicking barks (visual only)
+- Choice selections in conversations (visual only)
+
+## Usage Examples
+
+### Default (Sound Enabled)
+```javascript
+// Sound plays automatically
+npcManager.showBark({
+  npcId: 'helper_npc',
+  npcName: 'Tech Support',
+  text: 'Found something interesting!'
+});
+```
+
+### Disable Sound for Specific Bark
+```javascript
+// Silent bark (no sound)
+npcManager.showBark({
+  npcId: 'helper_npc',
+  npcName: 'Tech Support',
+  text: 'This is a quiet message...',
+  playSound: false
+});
+```
+
+### Disable All Sounds
+```javascript
+// Turn off bark sounds globally
+window.npcManager.barkSystem.setSoundEnabled(false);
+
+// Turn them back on
+window.npcManager.barkSystem.setSoundEnabled(true);
+```
+
+## Testing
+
+### In-Game Testing
+1. Refresh the game page to load updated code
+2. Start CEO Exfiltration scenario
+3. Test scenarios that trigger barks:
+   - Pick up an item → Should hear sound
+   - Walk through a door → Should hear sound
+   - Unlock a door → Should hear sound
+   - Enter CEO office → Should hear sound
+
+### Volume Testing
+- Default volume: 50% (0.5)
+- Can be adjusted by modifying `this.barkSound.volume` in `loadBarkSound()`
+- Recommended range: 0.3 - 0.7 (30% - 70%)
+
+## Browser Compatibility
+
+### Phaser Audio System
+- **Chrome/Edge**: ✅ Full Web Audio API support
+- **Firefox**: ✅ Full Web Audio API support
+- **Safari**: ✅ Full Web Audio API support
+- **Mobile browsers**: ✅ Good support (Phaser handles fallbacks)
+
+### Autoplay Policy
+Modern browsers restrict autoplay. Phaser handles this automatically:
+- ✅ **Works automatically**: Phaser unlocks audio context on first user interaction
+- ✅ **No console warnings**: Phaser manages audio context lifecycle
+- ✅ **Sounds triggered by user actions**: Always work (clicking, walking)
+- ✅ **Better than HTML5 Audio**: Phaser's Web Audio API is more reliable
+
+### Advantages Over HTML5 Audio
+1. **Unified audio management**: All game audio through one system
+2. **Better performance**: Web Audio API vs Audio Tag
+3. **Sound pooling**: Multiple simultaneous sounds without creating new instances
+4. **No autoplay issues**: Phaser handles audio context unlocking
+5. **Consistent volume control**: Tied to game's master volume
+6. **Future-ready**: Can add spatial audio, filters, analyzers, etc.
+
+## Future Enhancements
+
+### Potential Additions
+1. **Phone open/close sounds**
+   - Add `phone_open.mp3` sound when opening phone-chat
+   - Add `phone_close.mp3` sound when closing phone-chat
+
+2. **Choice selection sound**
+   - Subtle click sound when selecting dialogue choices
+   - Could use existing `GASP_UI_Clicks_*.mp3` sounds
+
+3. **Typing indicator sound**
+   - Quiet keyboard sound during typing animation
+   - Adds to realism of text messaging
+
+4. **Volume slider in settings**
+   - UI control for adjusting bark volume
+   - Persist preference to localStorage
+
+5. **Different sounds per NPC type**
+   - Helper NPCs: friendly notification sound
+   - Adversary NPCs: alert/warning sound
+   - Neutral NPCs: standard notification
+
+6. **Sound variations**
+   - Randomly pick from multiple notification sounds
+   - Prevents repetition fatigue
+   - Could use `GASP_UI_Notification_1.mp3` through `_6.mp3`
+
+## Implementation Stats
+
+- **Lines added:** ~68 total
+  - `game.js`: +3 lines (audio loading)
+  - `npc-barks.js`: +65 lines (Phaser sound integration)
+- **Files modified:** 2 (`game.js`, `npc-barks.js`)
+- **Breaking changes:** None
+- **Default behavior:** Sound enabled
+- **Asset used:** Existing (`message_received.mp3`)
+- **Audio system:** Phaser Web Audio API (consolidated)
+
+## Next Steps
+
+### Priority 3: NPC Avatars
+- Create 3 default 32x32px pixel-art avatars
+- Add avatar support to scenarios
+- Display avatars in barks and conversations
+
+### Priority 2 Continued: More Events
+- Implement `objective_completed` event
+- Implement `evidence_collected` event
+- Implement `player_detected` event
+
+---
+**Status:** ✅ Implementation complete, ready for testing
+**Date:** 2024-10-31