Spelling Bee Game - Discovery Challenge

🎯 Learning Objectives

• Implement Web Speech API for text-to-speech functionality
• Build interactive game logic with JavaScript
• Use LocalStorage for data persistence
• Create engaging educational user interfaces
• Practice prompt engineering and user experience design

🚀 Getting Started (See Results in 30 Seconds!)

Prerequisites

• Modern web browser (Chrome, Firefox, Safari, Edge)
• Local web server (Live Server extension in VS Code, or Python's http.server)

Quick Start

# If using VS Code:
# 1. Open this folder in VS Code
# 2. Install Live Server extension if not installed
# 3. Right-click on index.html → "Open with Live Server"

# If using Python:
cd project-02-spelling-bee
python3 -m http.server 8000
# Then open: http://localhost:8000

# Or simply open index.html in your browser!

🎯 What's Already Working

• ✅ Complete HTML structure with game interface (fully working)
• ✅ Professional CSS styling with animations (fully working)
• ✅ Word database with 60+ words across 3 difficulty levels (fully working)
• ✅ Game state management system (fully working)
• ✅ UI update functions and event listeners (fully working)
• ✅ Hint system with progressive difficulty (70% complete - working but basic)
• ⚠️ TODO: Text-to-speech pronunciation (30% complete - needs your work!)
• ⚠️ TODO: Answer validation logic (40% complete - needs your work!)
• ⚠️ TODO: Score calculation system (50% complete - needs enhancement!)
• ⚠️ TODO: Difficulty progression (20% complete - needs your work!)
• ⚠️ TODO: High score persistence with LocalStorage (0% complete - needs your work!)

📋 Tasks to Complete

TODO 1: Implement Text-to-Speech (Medium)

Location: script.js - Line ~58 Success Criteria:

• Browser speaks the word when "Hear Word" button is clicked
• Voice is clear and at appropriate speed (rate: 0.8)
• Handles browsers without speech support gracefully
• No console errors during pronunciation

Hint: Use the Web Speech API's SpeechSynthesisUtterance

Resources:

• MDN Web Speech API

TODO 2: Complete Answer Validation (Easy)

Location: script.js - Line ~86 Success Criteria:

• Correctly identifies matching spellings (case-insensitive)
• Calls handleCorrectAnswer() when spelling is right
• Calls handleIncorrectAnswer() when spelling is wrong
• Shows appropriate feedback to user

Hint: Use toLowerCase() for case-insensitive comparison

TODO 3: Implement Score Calculation (Easy)

Location: script.js - Line ~106 Success Criteria:

• Awards 5 points for easy words, 10 for medium, 15 for hard
• Adds streak bonus (streak x 2 points)
• Subtracts hint penalty (hints used x 2 points)
• Updates score display correctly

Enhancement Ideas:

• Add time bonuses for quick answers
• Multiply score based on streak milestones

TODO 4: Build Difficulty Progression System (Medium)

Location: script.js - Line ~126 Success Criteria:

• Tracks consecutive wrong answers
• Suggests easier difficulty after 3 wrong answers
• Suggests harder difficulty after 5 correct answers
• Displays helpful messages to encourage players

Enhancement Ideas:

• Auto-adjust difficulty based on performance
• Provide targeted practice for frequently missed words

TODO 5: Implement High Score Persistence (Hard)

Location: script.js - Line ~143 Success Criteria:

• Saves scores to localStorage with timestamp and difficulty
• Loads and displays top 5 scores on page load
• Sorts scores correctly (highest first)
• Handles edge cases (first time playing, corrupted data)

Hint: Use JSON.stringify() and JSON.parse() for localStorage

Resources:

• MDN LocalStorage

🚀 Extension Challenges

Challenge One: Multi-Prompt Buttons (Easy)

Add preset instruction buttons for different question types:

• "What colors do you see in this scene?"
• "How many objects are visible?"
• "Describe the lighting and mood"

Challenge 2: Word Definition API (Medium)

Integrate a dictionary API to show definitions:

• Fetch from Dictionary API
• Display definition after correct answer
• Cache definitions for offline use

Challenge 3: Timed Mode (Advanced)

Add a timer challenge:

• 30-second countdown per word
• Bonus points for fast answers
• Progressive time pressure

Challenge 4: Multiplayer Mode (Advanced)

Create a turn-based two-player mode:

• Alternating turns
• Head-to-head scoring
• Winner announcement

🛠️ Troubleshooting

Issue: Speech API not working

Solution:

1. Check browser compatibility (works in Chrome, Safari, Edge)
2. Ensure page is served over HTTPS or localhost
3. Try different voices: speechSynthesis.getVoices()

Issue: LocalStorage not saving

Solution:

1. Check browser console for errors
2. Ensure you're not in private/incognito mode
3. Verify localStorage is enabled in browser settings
4. Check storage quota (usually 5-10MB available)

Issue: Words not randomizing properly

Solution:

1. Check shuffleArray() function is being called
2. Verify word database is loaded correctly
3. Ensure usedWords array is being updated

Issue: Score not calculating correctly

Solution:

1. Add console.log() statements to track score changes
2. Verify difficulty values match expected points
3. Check that streak and hints are updating properly

📚 Technologies Used

• HTML5: Semantic markup, form inputs, accessibility features
• CSS3: Grid, Flexbox, animations, responsive design
• Vanilla JavaScript ES6+: Async/await, arrow functions, destructuring
• Web Speech API: Text-to-speech synthesis
• LocalStorage API: Client-side data persistence

🎓 Learning Resources

• Web Speech API Guide
• LocalStorage Tutorial
• JavaScript Game Development
• Responsive Web Design

💡 Tips for Success

1. Test incrementally: After completing each TODO, test immediately
2. Read error messages: Browser console (F12) provides debugging clues
3. Use console.log(): Track variable values and function calls
4. Ask for help: Use AI assistants (Claude, ChatGPT) to explain concepts
5. Experiment: Try different approaches and learn from mistakes
6. Document your code: Add comments explaining complex logic

🎮 Game Features Breakdown

Implemented Features (70%)

• ✅ Word database with 60+ words (15 easy, 20 medium, 25 hard)
• ✅ Difficulty selection system
• ✅ Progressive hint system (category -> first letter -> definition -> sentence)
• ✅ Animated feedback for correct/incorrect answers
• ✅ Streak tracking and display
• ✅ Responsive mobile-friendly design

Your Tasks (30%)

• ⚠️ Text-to-speech word pronunciation
• ⚠️ Answer validation logic
• ⚠️ Advanced score calculation with bonuses
• ⚠️ Adaptive difficulty suggestions
• ⚠️ High score persistence system

🧪 Testing Checklist

Before submitting, verify:

• Start game and hear word pronounced correctly
• Correct spellings are accepted (test with 3+ words)
• Incorrect spellings are rejected with feedback
• Score increases appropriately based on difficulty
• Streak bonus is applied correctly
• Hints reduce points when used
• High scores are saved and persist after refresh
• Game works on mobile devices
• No console errors during gameplay

Good luck! Remember: Every expert coder started as a beginner. Embrace the learning process and enjoy building! 🐝✨