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