# 🎬 Closed Captions & Visual Sound Cues Testing Guide

## 📋 Overview
This guide covers testing for the enhanced Visual Sound Cue System, including:
- ✅ Closed Captions with sound effects
- ✅ Speaker names & colors
- ✅ Directional arrows (< Sound >)
- ✅ Background opacity slider
- ✅ Fishing bobber visual queue

---

## 🎯 Features to Test

### 1. **Closed Captions [SOUND EFFECT]**

#### Test Cases:
- [ ] **Damage Sound**: `[DAMAGE TAKEN]` appears when player takes damage
- [ ] **Pickup Sound**: `[PICKED UP: Item Name]` appears when collecting items
- [ ] **Harvest Sound**: `[CROP HARVESTED]` appears when harvesting crops
- [ ] **Building Sound**: `[BUILDING PLACED]` appears when placing buildings
- [ ] **Digging Sound**: `[DIGGING SOUND]` appears when digging
- [ ] **Planting Sound**: `[PLANTING SOUND]` appears when planting
- [ ] **Footsteps**: `[FOOTSTEPS]` appears when walking
- [ ] **Door Sound**: `[DOOR OPENS]` appears when opening doors
- [ ] **Chest Sound**: `[CHEST OPENS]` appears when opening chests
- [ ] **Water Sound**: `[WATER SPLASH]` appears near water
- [ ] **Fire Sound**: `[FIRE CRACKLING]` appears near fire
- [ ] **Explosion**: `[EXPLOSION!]` appears with screen flash
- [ ] **UI Click**: `[CLICK]` appears on button clicks
- [ ] **UI Hover**: `[HOVER]` appears on button hover

#### How to Test:
```javascript
// In browser console (F12):
const visualCues = game.scene.scenes[1].visualSoundCues;

// Test different sound effects
visualCues.onSoundPlayed('damage', { direction: 'left', amount: 25 });
visualCues.onSoundPlayed('pickup', { item: 'Carrot' });
visualCues.onSoundPlayed('harvest');
visualCues.onSoundPlayed('build');
visualCues.onSoundPlayed('dig');
visualCues.onSoundPlayed('plant');
visualCues.onSoundPlayed('footsteps', { direction: 'right' });
visualCues.onSoundPlayed('door');
visualCues.onSoundPlayed('chest');
visualCues.onSoundPlayed('water');
visualCues.onSoundPlayed('fire');
visualCues.onSoundPlayed('explosion');
visualCues.onSoundPlayed('ui_click');
visualCues.onSoundPlayed('ui_hover');
```

---

### 2. **Speaker Names & Colors**

#### Predefined Speakers:
- 🟢 **Player**: Green (`#00ff00`)
- 🟡 **NPC**: Yellow (`#ffff00`)
- 🔴 **Enemy**: Red (`#ff0000`)
- 🔵 **System**: Cyan (`#00ffff`)
- ⚪ **Narrator**: White (`#ffffff`)

#### Test Cases:
- [ ] Speaker name appears above subtitle
- [ ] Speaker name has correct color
- [ ] Speaker name is bold
- [ ] Speaker name can be toggled on/off
- [ ] Custom speakers can be added

#### How to Test:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Test different speakers
visualCues.showSubtitle('Hello, adventurer!', 3000, 'NPC');
visualCues.showSubtitle('You found a treasure!', 3000, 'System');
visualCues.showSubtitle('GRRRR!', 3000, 'Enemy');
visualCues.showSubtitle('I need help!', 3000, 'Player');
visualCues.showSubtitle('Long ago, in a distant land...', 5000, 'Narrator');

// Add custom speaker
visualCues.addSpeakerColor('Merchant', '#ffa500'); // Orange
visualCues.showSubtitle('Welcome to my shop!', 3000, 'Merchant');

// Toggle speaker names
visualCues.toggleSpeakerNames(false); // Hide speaker names
visualCues.showSubtitle('This has no speaker name', 3000, 'NPC');
visualCues.toggleSpeakerNames(true); // Show speaker names
```

---

### 3. **Directional Arrows (< Sound >)**

#### Test Cases:
- [ ] Left arrow (◄) appears for sounds from the left
- [ ] Right arrow (►) appears for sounds from the right
- [ ] Both arrows appear for omnidirectional sounds
- [ ] Arrows pulse/animate
- [ ] Arrows can be toggled on/off
- [ ] Arrows disappear when subtitle hides

#### How to Test:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Test directional arrows
visualCues.showSubtitle('Sound from the left', 3000, 'System', 'left');
setTimeout(() => {
    visualCues.showSubtitle('Sound from the right', 3000, 'System', 'right');
}, 3500);
setTimeout(() => {
    visualCues.showSubtitle('Sound from everywhere', 3000, 'System', 'both');
}, 7000);

// Test with actual game sounds
visualCues.onSoundPlayed('footsteps', { direction: 'left' });
visualCues.onSoundPlayed('enemy_growl', { direction: 'right' });
visualCues.onSoundPlayed('damage', { direction: 'left', amount: 10 });

// Toggle directional arrows
visualCues.toggleDirectionalArrows(false); // Disable
visualCues.showSubtitle('No arrows', 3000, 'System', 'left');
visualCues.toggleDirectionalArrows(true); // Enable
```

---

### 4. **Background Opacity Slider**

#### Test Cases:
- [ ] Default opacity is 0.8 (80%)
- [ ] Opacity can be changed from 0.0 to 1.0
- [ ] Opacity change is visible immediately
- [ ] Opacity setting is saved to localStorage
- [ ] Opacity persists after page reload

#### How to Test:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Show subtitle to see background
visualCues.showSubtitle('Testing opacity...', 5000, 'System');

// Test different opacity levels
visualCues.setSubtitleOpacity(1.0);   // Fully opaque
visualCues.setSubtitleOpacity(0.5);   // 50% transparent
visualCues.setSubtitleOpacity(0.2);   // 20% opaque
visualCues.setSubtitleOpacity(0.0);   // Fully transparent
visualCues.setSubtitleOpacity(0.8);   // Back to default

// Test clamping (values outside 0-1)
visualCues.setSubtitleOpacity(1.5);   // Should clamp to 1.0
visualCues.setSubtitleOpacity(-0.5);  // Should clamp to 0.0

// Verify setting is saved
console.log('Current opacity:', visualCues.settings.subtitleOpacity);
```

---

### 5. **Fishing Bobber Visual Queue**

#### Test Cases:
- [ ] Indicator appears in center of screen
- [ ] Shows orange circle background
- [ ] Shows exclamation mark (!)
- [ ] Shows "FISH BITING! Press E" text
- [ ] Pulses 5 times
- [ ] Fades in and out smoothly
- [ ] Can be toggled on/off

#### How to Test:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Test fishing bobber cue
visualCues.showFishingBobberCue();

// Test with fishing sound
visualCues.onSoundPlayed('fishing_cast');
setTimeout(() => {
    visualCues.onSoundPlayed('fishing_bite');
}, 2000);

// Toggle fishing bobber
visualCues.toggleFishingBobber(false); // Disable
visualCues.onSoundPlayed('fishing_bite'); // Should not show
visualCues.toggleFishingBobber(true); // Enable
visualCues.onSoundPlayed('fishing_bite'); // Should show
```

---

## 🎮 Integration Testing

### Test All Features Together:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Scenario 1: NPC Conversation
visualCues.showSubtitle('Hello there!', 3000, 'NPC', 'left');
setTimeout(() => {
    visualCues.showSubtitle('Can you help me?', 3000, 'NPC', 'left');
}, 3500);

// Scenario 2: Combat
visualCues.onSoundPlayed('enemy_growl', { direction: 'right' });
setTimeout(() => {
    visualCues.onSoundPlayed('damage', { direction: 'right', amount: 15 });
}, 1000);

// Scenario 3: Fishing
visualCues.onSoundPlayed('fishing_cast');
setTimeout(() => {
    visualCues.onSoundPlayed('fishing_bite');
}, 3000);

// Scenario 4: Achievement
visualCues.onSoundPlayed('achievement', { message: 'First Harvest!' });
```

---

## ⚙️ Settings Testing

### Test All Toggle Functions:
```javascript
const visualCues = game.scene.scenes[1].visualSoundCues;

// Test all toggles
visualCues.toggleSubtitles(false);
visualCues.toggleSubtitles(true);

visualCues.toggleSpeakerNames(false);
visualCues.toggleSpeakerNames(true);

visualCues.toggleDirectionalArrows(false);
visualCues.toggleDirectionalArrows(true);

visualCues.toggleFishingBobber(false);
visualCues.toggleFishingBobber(true);

visualCues.toggleHeartbeat(false);
visualCues.toggleHeartbeat(true);

visualCues.toggleDamageIndicator(false);
visualCues.toggleDamageIndicator(true);

visualCues.toggleScreenFlash(false);
visualCues.toggleScreenFlash(true);

// Verify settings are saved
console.log('Current settings:', visualCues.settings);
```

---

## 📊 Expected Results

### ✅ Success Criteria:
1. All closed captions appear with correct text
2. Speaker names display with correct colors
3. Directional arrows appear and animate correctly
4. Opacity slider works smoothly (0.0 - 1.0)
5. Fishing bobber cue is visible and animated
6. All settings can be toggled on/off
7. Settings persist after page reload
8. No console errors
9. Performance remains smooth (60 FPS)

### ❌ Known Issues:
- None currently

---

## 🐛 Bug Reporting

If you find any issues, please report:
1. **What you were testing**
2. **What you expected to happen**
3. **What actually happened**
4. **Console errors** (if any)
5. **Steps to reproduce**

---

## 📝 Notes

- All features are designed for accessibility (deaf/hard-of-hearing players)
- Directional arrows help identify sound source location
- Speaker colors help distinguish between different characters
- Opacity control allows customization for different visual preferences
- Fishing bobber cue ensures players don't miss fishing opportunities

---

**Last Updated**: 2025-12-12  
**Version**: 2.5.0  
**Status**: ✅ Ready for Testing