# Wrdler Gameplay Guide

Version 0.3.2

**Last Updated:** 2026-04-15

## 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.

---


## Recent Changes (v0.3.2)
See `README.md` for the canonical release notes: [Recent Changes (v0.3.2)](README.md#recent-changes-v032)

---

## 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 ✓
- **OK:** < 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

---

## Leaderboards (Daily & Weekly)

Wrdler features a robust leaderboard system to track top performances:

- **Daily Leaderboards:** Top 20 scores for each day (UTC midnight reset)
- **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC)
- **Settings-Based:** Each unique combination of game-affecting settings (game mode, wordlist, free letters, etc.) has its own leaderboard. You compete only with players using the same settings.
- **Qualification:** Only the top 20 scores (sorted by score, then time, then difficulty) are displayed for each leaderboard. You can still submit your score even if you don't qualify for the top 20.
- **Automatic Submission:** After each game, you can submit your score to the leaderboards from the game over popup. Challenge submissions also submit to leaderboards.
- **Leaderboard Page:** Access the Leaderboards from the sidebar to view daily, weekly, and historical results, filtered by your current settings.

### How to View Leaderboards
- Open the sidebar and click the "🏆 Leaderboards" button
- Browse daily, weekly, and historical leaderboards
- See your rank and compare with other players using the same settings

---

## Challenge Mode (Updated)

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!

**Challenge Leaderboard:**
- Top 5 players for each challenge are displayed in the Challenge Mode banner
- Sorted by: Highest score → Fastest time → Highest difficulty
- Submit your result to join the challenge leaderboard and the daily/weekly leaderboards

---

## Leaderboard Submission & Ranking
- After each game, enter your name (optional) and submit your score to the leaderboards
- If your score qualifies for the top 20, your rank will be displayed
- You can view your ranking for both daily and weekly leaderboards in the game over popup
- All leaderboard data is stored securely in the cloud (Hugging Face repository)

---

## 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! 🎲**
