GAMEPLAY_GUIDE.md

# Wrdler Gameplay Guide
**Version:** 0.0.2
**Last Updated:** 2025-01-31

## Welcome to Wrdler!

Wrdler is a simplified vocabulary puzzle game where you discover 6 hidden words on an 8×6 grid. The game combines strategic letter guessing with word deduction to maximize your score.

---

## Game Overview

### The Grid
- **Size:** 8 columns × 6 rows (48 cells total)
- **Words:** 6 hidden words, one per row
  - **Composition:** Exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
- **Direction:** All words are horizontal (left to right)
- **Goal:** Discover all 6 words before revealing all their letters

### Scoring Tiers
Your final score determines your tier:
- **Fantastic:** 42+ points 🌟
- **Great:** 38-41 points ⭐
- **Good:** 34-37 points ✓
- **Keep practicing:** < 34 points

---

## How to Play

### Step 1: Free Letter Selection

**At the start of every game, you get 2 free letter guesses!**

1. A letter selection interface appears with circular green buttons
2. Click any letter to reveal ALL instances of that letter in the grid
3. Choose strategically - common letters (E, A, R, T) may appear more often
4. After selecting 2 letters, the interface disappears and regular gameplay begins

**Example:**
- You choose **E** → All E's in the grid are revealed
- You choose **A** → All A's in the grid are revealed
- Now you can see some patterns in the words!

### Step 2: Reveal Cells

Click on any unrevealed cell to discover what's underneath:
- **Letter cells** show the letter (blue background)
- **Empty cells** show blank (dark background)

**Strategy Tip:** Reveal cells near already-revealed letters to build word patterns.

### Step 3: Guess Words

After revealing at least one letter:
1. A guess form appears on the right side
2. Type your word guess (case-insensitive)
3. Click "Guess" or press Enter

**Correct Guess:**
- ✓ Word is marked as found
- Points awarded based on word length and unrevealed letters
- All remaining letters in that word are revealed
- You can immediately guess another word (Classic mode)

**Incorrect Guess:**
- ✗ Guess is added to incorrect history
- No points awarded
- 10 incorrect guess limit per game

### Step 4: Complete the Game

The game ends when:
- **All 6 words are guessed** (best outcome!)
- **All word letters are revealed** (auto-complete triggers)

Your final score and tier are displayed in a popup.

---

## Scoring System

### Base Points
- Each word is worth points based on its length:
  - 4-letter word: 4 points
  - 5-letter word: 5 points
  - 6-letter word: 6 points

### Bonus Points
- **Unrevealed Letter Bonus:** +1 point per unrevealed letter in the word
- Example: If you guess a 6-letter word with 3 letters still hidden:
  - Base: 6 points
  - Bonus: 3 points
  - **Total: 9 points**

### Maximum Possible Score
- 6 words × ~8 average points = ~48 points (Fantastic tier!)

---

## Game Modes

### Classic Mode (Default)
- Guess as many times as you want after each reveal
- Chain multiple correct guesses together
- Best for maximizing score

### Too Easy Mode
- Only one guess allowed after each reveal
- Must reveal another cell before guessing again
- More challenging gameplay

*Change mode in the Settings sidebar*

---

## Features & Controls

### Settings Sidebar

**Word Lists:**
- **classic:** Carefully curated words (recommended)
- **fourth_grade:** Elementary-level vocabulary
- **wordlist:** Full word list (harder)

**Game Options:**
- Game Mode: Classic or Too Easy
- Word Spacing: How much space between words
- Show Incorrect Guesses: Toggle incorrect guess history

**Audio:**
- Background Music: Ocean-themed ambient music
- Music Volume: 0-100%
- Sound Effects Volume: Hit/miss/correct/incorrect sounds

### Challenge Mode

Share puzzles with friends:
1. Complete a game
2. Click "Share Challenge" in the game-over popup
3. Copy the short URL (e.g., `?game_id=abc123`)
4. Friends can play the same wordlist and compare scores!

**Leaderboard:**
- Top 5 players displayed
- Sorted by: Highest score → Fastest time
- Submit your result to join the leaderboard

---

## Tips & Strategies

### Free Letter Selection
- **Common letters** (E, A, R, T, O, I, N, S) appear more often
- **Vowels** (A, E, I, O, U) help identify word patterns
- **Consonants** (R, S, T, N) are versatile
- Avoid rare letters (Q, X, Z) unless you see a pattern

### Cell Reveal Strategy
1. Start near free letters to build word patterns
2. Reveal cells at word boundaries (edges of rows)
3. Look for common word endings (-ING, -ED, -ER, -LY)
4. Use process of elimination for remaining letters

### Guessing Strategy
- Guess words with more unrevealed letters for bonus points
- Don't rush - each incorrect guess counts against your limit
- Use word patterns (CVC, CVVC, etc.) to narrow possibilities
- If stuck, reveal one more letter to confirm your guess

### Maximizing Score
1. Select strategic free letters (E + R or A + T)
2. Guess words early while letters are still hidden
3. Use revealed letters to deduce other words
4. Minimize unnecessary reveals

---

## Visual Indicators

### Cell States
- **Unrevealed:** Gray with "?" symbol
- **Letter (revealed):** Light blue background, white text
- **Empty (revealed):** Dark gray background
- **Completed word:** Dark blue background (all letters guessed)

### Free Letter Buttons
- **Available:** Green gradient, circular
- **Disabled:** Gray, after 2 selections

### Guess Form
- **Enabled:** After revealing at least one letter
- **Disabled:** Before any reveals

---

## Progressive Web App (PWA)

Install Wrdler on your device:

**Desktop (Chrome/Edge):**
1. Click the install icon in the address bar
2. Click "Install"

**Mobile (iOS Safari):**
1. Tap the Share button
2. Tap "Add to Home Screen"

**Mobile (Android Chrome):**
1. Tap the menu (three dots)
2. Tap "Add to Home Screen"

Once installed, Wrdler works offline with basic caching!

---

## Keyboard Shortcuts

- **Enter:** Submit word guess (when guess form is focused)
- **Escape:** Dismiss game-over popup (if visible)

---

## Troubleshooting

### "You must reveal a cell before guessing"
- Click on an unrevealed cell first
- The guess form enables after your first reveal

### "Incorrect guess" or "Not in word list"
- Check spelling (case doesn't matter)
- Verify the word is in the current word list
- Try revealing more letters for confirmation

### Free letter buttons not appearing
- Refresh the page
- Start a new game
- Check that you haven't already used 2 free letters

### Challenge Mode not working
- Ensure HF credentials are configured (see README)
- Check internet connection
- Verify the `game_id` parameter in the URL

---

## Scoring Examples

### Example 1: Early Guess
- Word: **STREAM** (6 letters)
- Revealed letters: 2 (S, T from free letters)
- Unrevealed: 4 (R, E, A, M)
- **Score:** 6 (word) + 4 (bonus) = **10 points**

### Example 2: Late Guess
- Word: **SMILE** (5 letters)
- Revealed letters: 4 (S, M, I, L)
- Unrevealed: 1 (E)
- **Score:** 5 (word) + 1 (bonus) = **6 points**

### Example 3: Auto-Complete
- Word: **FROG** (4 letters)
- All letters revealed through cell clicks
- Automatically marked as found
- **Score:** 4 (word) + 0 (bonus) = **4 points**

---

## Game Flow Diagram

```
┌─────────────────────┐
│   START NEW GAME    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Select 2 Free      │
│  Letters (A, E)     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Reveal Cells       │
│  (Click grid)       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Guess Words        │
│  (Type + Enter)     │
└──────────┬──────────┘
           │
           ▼
    ┌──────┴──────┐
    │             │
┌───▼──┐      ┌───▼──┐
│ ✓ OK │      │ ✗ NO │
└───┬──┘      └───┬──┘
    │             │
    │             ▼
    │     ┌───────────────┐
    │     │ Incorrect +1  │
    │     └───────┬───────┘
    │             │
    └─────┬───────┘
          │
          ▼
    ┌─────────────┐
    │ All words   │
    │ guessed?    │
    └──────┬──────┘
           │
      ┌────┴────┐
      │         │
   ┌──▼──┐   ┌─▼──┐
   │ YES │   │ NO │
   └──┬──┘   └─┬──┘
      │        │
      ▼        │
┌──────────┐   │
│ GAME END │◄──┘
│ Show     │
│ Score    │
└──────────┘
```

---

## Advanced Tips

### Optimal Free Letter Strategy
Research shows these combinations are most effective:
1. **E + A** - Most common vowels
2. **E + R** - Common vowel + consonant
3. **A + T** - Versatile combination
4. **E + S** - Vowel + plural ending

### Speed Play
- Practice common word patterns (CVCC, CCVC, etc.)
- Memorize frequent word endings
- Use process of elimination quickly
- Don't overthink - trust your instincts

### Challenge Mode Strategy
- Play multiple times with same word list
- Learn common words in each list
- Practice with classic list before challenges
- Aim for < 2 minutes completion time

---

## Credits

Wrdler is based on BattleWords but simplified for a more accessible word puzzle experience.

**Changes from BattleWords:**
- 8×6 grid (was 12×12)
- Horizontal words only (no vertical)
- No radar visualization
- 2 free letter guesses at start
- Streamlined gameplay

**Development:**
- 7 sprints completed (v0.0.2)
- 100% integration test pass rate
- Mobile-responsive design
- PWA support

---

## Support & Feedback

Having issues or suggestions?
- Report bugs: https://github.com/Oncorporation/Wrdler/issues
- Ask questions: See README.md
- Contribute: Pull requests welcome!

---

## Quick Reference Card

| Action | How To |
|--------|--------|
| **Select free letter** | Click green circular button |
| **Reveal cell** | Click gray "?" cell |
| **Guess word** | Type in form + Enter |
| **New game** | Click "New Game" button |
| **Change settings** | Open sidebar (← icon) |
| **Share challenge** | Click "Share" in game-over popup |
| **Install PWA** | Click install icon in browser |

---

**Enjoy playing Wrdler! 🎲**