novafarma/docs/guides/CLOSED_CAPTIONS_TESTING.md

🎬 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:

// 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:

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:

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:

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:

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:

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:

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