Hugging Face's logo

Spaces:
Surn
/
wrdler
Running

App Files Community
wrdler / GAMEPLAY_GUIDE.md
Surn's picture
Surn
Leaderboards Documentation
38961b4
preview code
|
raw
history blame contribute delete
12.9 kB

A newer version of the Streamlit SDK is available: 1.52.1

Upgrade

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

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?

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