| # Wrdler Game Specifications (specs.md) | |
| **Version:** 0.2.4 | |
| **Status:** Production Ready - Leaderboards Implemented | |
| **Last Updated:** 2025-12-08 | |
| ## Overview | |
| Wrdler is a Python/Streamlit vocabulary puzzle game based on BattleWords, but with key differences. The objective is to discover hidden words on a grid by making strategic guesses and using free letter reveals at the game start. | |
| **Current Status:** All 7 sprints complete, 100% tested, fully documented | |
| ## Key Differences from BattleWords | |
| - **Python project** (Streamlit, Python 3.12.8) | |
| - **8x6 grid** (instead of 12x12) | |
| - **One word per row** (instead of 6 words placed anywhere) | |
| - **Horizontal words only** (no vertical placement) | |
| - **No scope/radar visualization** | |
| - **2 free letter guesses at game start** (all instances of chosen letters are revealed) | |
| ## Game Board | |
| - 8 x 6 grid | |
| - Six hidden words: | |
| - One word per row (row 0-5) | |
| - **Word composition:** Exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words | |
| - All placed horizontally (left-right) | |
| - No vertical placement | |
| - No diagonal placement | |
| - Words do not overlap | |
| - Entry point is `app.py` | |
| - **Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms** | |
| ## Gameplay (Core) | |
| - Players start by choosing 2 letters; all instances of those letters are revealed in the grid | |
| - Players click grid squares to reveal letters or empty spaces | |
| - Empty revealed squares are styled with CSS class `empty` | |
| - After any reveal, the app immediately reruns (`st.rerun`) to show the change | |
| - After revealing a letter, players may guess a word by entering it in a text box | |
| - Guess submission triggers an immediate rerun to reflect results | |
| - Only one guess per letter reveal; must uncover another letter before guessing again | |
| - In the default mode, a correct guess allows chaining an additional guess without another reveal | |
| - **The game ends when all six words are guessed or all word letters are revealed** | |
| ## Scoring | |
| - Each correct word guess awards points: | |
| - 1 point per letter in the word | |
| - Bonus points for each hidden letter at the time of guessing | |
| - Score tiers: | |
| - **Legendary:** 45+ points | |
| - **Fantastic:** 42-44 points | |
| - **Great:** 39-41 points | |
| - **Good:** 35-38 points | |
| - **Keep practicing:** <35 points | |
| - **Game over is triggered by either all words being guessed or all word letters being revealed** | |
| ## Core Rules (v0.0.2 - Implemented) | |
| - ✅ 8x6 grid with one word per row | |
| - ✅ Horizontal words only; no vertical placement | |
| - ✅ No overlaps: words do not overlap or share letters | |
| - ✅ No radar/scope visualization (removed in Sprint 3) | |
| - ✅ 2 free letter guesses at game start (implemented in Sprint 4) | |
| - ✅ Incorrect guess history with optional display | |
| - ✅ 10 incorrect guess limit per game | |
| - ✅ Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal) | |
| ## Implemented Features (v0.2.4) | |
| ### Word List Management (v0.2.4) | |
| - ✅ **Filter Wordlist:** Remove words found in `assets/filter.txt` from the selected word list | |
| - ✅ **Sort Wordlist:** Sort words by length and alphabetically | |
| - ✅ **Feedback:** Dialog showing count and list of removed words | |
| ### AI Word Generation (v0.1.0+) | |
| - ✅ **Topic-Based Generation:** Create custom word lists for any theme using AI | |
| - ✅ **Dual Generation Modes:** | |
| - HF Space API (primary): Uses Hugging Face Space when `USE_HF_WORDS=true` | |
| - Local transformers (fallback): Falls back to local models if HF unavailable | |
| - ✅ **Intelligent Word Management:** | |
| - Smart detection separates existing dictionary words from new AI-generated words | |
| - Only saves new words to prevent duplicates in word files | |
| - Automatic retry mechanism (up to 3 attempts) if insufficient words generated | |
| - 1000-word file size limit prevents dictionary bloat | |
| - Auto-sorted by length then alphabetically | |
| - ✅ **Guaranteed Distribution:** Ensures exactly 25 words each of lengths 4, 5, and 6 | |
| - ✅ **Graceful Fallback:** Uses dictionary words if AI generation fails | |
| - ✅ **Enhanced Logging:** Detailed pipeline visibility for debugging | |
| ### Challenge Mode | |
| - ✅ **Game ID Sharing:** Each puzzle generates a shareable link with `?game_id=<sid>` to challenge others with the same word list | |
| - ✅ **Remote Storage:** Game results and leaderboards stored in Hugging Face dataset repos | |
| - ✅ **Leaderboards:** Multi-user leaderboards sorted by score (descending) then time (ascending) | |
| - ✅ **Word List Difficulty:** Calculated and displayed for each challenge | |
| - ✅ **Top 5 Display:** Leaderboard banner shows top 5 players | |
| - ✅ **Optional Sharing:** "Show Challenge Share Links" toggle (default OFF) controls URL visibility | |
| ### Leaderboard System (v0.2.1) ✅ IMPLEMENTED | |
| Wrdler features a comprehensive daily and weekly leaderboard system: | |
| **Core Features:** | |
| - **Daily Leaderboards:** Top 20 scores for each day (resets UTC midnight) | |
| - **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC 00:00) | |
| - **Settings-Based Separation:** Each unique combination of game-affecting settings creates a separate leaderboard: | |
| - `game_mode` (classic, easy, too easy) | |
| - `wordlist_source` (classic.txt, fourth_grade.txt, etc.) | |
| - `show_incorrect_guesses` (boolean) | |
| - `enable_free_letters` (boolean) | |
| - `puzzle_options` (spacer, may_overlap) | |
| - **Sorting:** Scores sorted by: score (desc) → time (asc) → difficulty (desc) | |
| - **Qualification:** Only top 25 (configurable) scores displayed per leaderboard (more can be stored) | |
| **Storage Structure:** | |
| ``` | |
| HF_REPO_ID/games/ | |
| ├── leaderboards/ | |
| │ ├── daily/{YYYY-MM-DD}/{file_id}/settings.json | |
| │ └── weekly/{YYYY-Www}/{file_id}/settings.json | |
| └── {challenge_id}/settings.json | |
| ``` | |
| **File ID Format:** `{wordlist_source}-{game_mode}-{sequence}` | |
| - Example: `classic-classic-0`, `easy-too_easy-1` | |
| - Sanitized (no .txt, lowercase, underscores for spaces) | |
| **Leaderboard Page UI:** | |
| - **Today Tab:** Current daily and weekly leaderboards | |
| - Query params: `?gidd={file_id}` and `?gidw={file_id}` for filtering | |
| - Side-by-side display in two columns | |
| - **Daily Tab:** Last 7 days of daily leaderboards | |
| - Expandable groups per date | |
| - All settings combinations shown | |
| - **Weekly Tab:** Current ISO week leaderboard | |
| - All settings combinations displayed | |
| - **History Tab:** Historical leaderboard browser | |
| - Dropdown selectors for period and settings | |
| - Separate daily and weekly columns | |
| **Integration:** | |
| - Automatic submission after game completion (opt-in) | |
| - Challenge scores also contribute to daily/weekly leaderboards | |
| - Source tracking via `source_challenge_id` field | |
| - Unified JSON format with `entry_type` field (daily/weekly/challenge) | |
| **Discovery:** Folder-based (no index.json) | |
| - Scans period folders for date/week IDs | |
| - Filters by file_id prefix for matching settings | |
| - Loads and verifies full settings match | |
| **Date Display Updates:** | |
| - All leaderboard files use UTC for period boundaries. | |
| - When displaying daily leaderboards, show the UTC period as a PST date range. | |
| - Example: For UTC file date 2025-12-08, display: | |
| 2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC | |
| and | |
| 2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST | |
| The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]` | |
| **Access:** 'Leaderboard' link in the footer navigation at the bottom of the page | |
| ### PWA Support | |
| - ✅ **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile | |
| - Added `service worker` and `manifest.json` | |
| - Basic offline caching of static assets | |
| - INSTALL_GUIDE.md added with platform-specific install steps | |
| - No gameplay logic changes | |
| ### Settings Page (Planned/Upcoming) | |
| - Move all game settings from sidebar to a dedicated settings page (`?page=settings`) requiring a logged in user (OAuth) | |
| ## Storage | |
| ### Current (v0.2.1) | |
| - ✅ Challenge Mode uses remote storage via Hugging Face datasets | |
| - ✅ Game ID is generated from the word list for replay/sharing | |
| ### Planned (Future) | |
| - Local persistent storage for game results and high scores (JSON files) | |
| - Local storage location: `~/.wrdler/data/` | |
| - Privacy-first offline access | |
| ## UI Elements (v0.2.1 - Implemented) | |
| - ✅ 8x6 grid (48 cells total) | |
| - ✅ Free letter guess buttons (2 at game start) - circular green gradient design | |
| - ✅ Text box for word guesses | |
| - ✅ Score display (shows word, base points, bonus points, total score) | |
| - ✅ Guess status indicator (Correct/Try Again) | |
| - ✅ Incorrect guess history display (toggleable) | |
| - ✅ Game ID display and share button in game over dialog | |
| - ✅ Challenge Mode banner with leaderboard (top 5) | |
| - ✅ High score expander in sidebar | |
| - ✅ Player name input in sidebar | |
| - ✅ Checkbox: "Show Challenge Share Links" (default OFF) | |
| - When OFF: | |
| - Challenge Mode header hides the Share Challenge link | |
| - Game Over dialog still supports submitting/creating challenges, but does not display the generated share URL | |
| - Persisted in session state and preserved across "New Game" | |
| ## Word List | |
| - External list at `wrdler/words/wordlist.txt` | |
| - Loaded by `wrdler.word_loader.load_word_list()` with caching | |
| - Filtered to uppercase A-Z, lengths in {4,5,6}; falls back if < 25 per length | |
| ## Generator | |
| - Centralized word loader | |
| - No duplicate word texts are selected | |
| - Horizontal-only word placement | |
| - One word per row in 8x6 grid | |
| - **Word length distribution:** Each puzzle must contain exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words | |
| - No word spacing configuration (fixed one word per row) | |
| ## Entry Point | |
| - The Streamlit entry point is `app.py` | |
| - **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces)** | |
| ## Deployment Requirements | |
| ### Basic Deployment (Offline Mode) | |
| No special configuration needed. The app will run with all core gameplay features. | |
| Optional: Install as PWA from the browser menu (Add to Home Screen/Install app). | |
| ### Challenge Mode Deployment (Remote Storage) | |
| Requires HuggingFace Hub integration for challenge sharing and leaderboards. | |
| **Required Environment Variables:** | |
| ```bash | |
| HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx # or HF_TOKEN (write access required) | |
| HF_REPO_ID=YourUsername/YourRepo # Target HF dataset repository | |
| SPACE_NAME=YourUsername/Wrdler # Your HF Space name for URL generation | |
| ``` | |
| **Optional Environment Variables:** | |
| ```bash | |
| CRYPTO_PK= # Reserved for future challenge signing | |
| ``` | |
| **Setup Steps:** | |
| 1. Create a HuggingFace account at https://huggingface.co | |
| 2. Create a dataset repository (e.g., `YourUsername/WrdlerStorage`) | |
| 3. Generate an access token with `write` permissions: | |
| - Go to https://huggingface.co/settings/tokens | |
| - Click "New token" | |
| - Select "Write" access | |
| - Copy the token (starts with `hf_`) | |
| 4. Create a `.env` file in project root with the variables above | |
| 5. For Hugging Face Spaces deployment, add these as Space secrets | |
| **Repository Structure (automatically created):** | |
| ``` | |
| HF_REPO_ID/ | |
| ├── shortener.json # Short URL mappings (sid -> full URL) | |
| └── games/ | |
| ├── leaderboards/ | |
| │ ├── daily/ | |
| │ │ └── {YYYY-MM-DD}/ # Daily period folders | |
| │ │ └── {file_id}/ # Settings-specific leaderboard | |
| │ │ └── settings.json # entry_type: "daily" | |
| │ └── weekly/ | |
| │ └── {YYYY-Www}/ # Weekly period folders (ISO week) | |
| │ └── {file_id}/ # Settings-specific leaderboard | |
| │ └── settings.json # entry_type: "weekly" | |
| └── {challenge_id}/ | |
| └── settings.json # Challenge data (entry_type: "challenge") | |
| ``` | |
| **Data Privacy:** | |
| - Challenge Mode stores: word lists, scores, times, game modes, player names | |
| - No PII beyond optional player name (defaults to "Anonymous") | |
| - Players control URL visibility via "Show Challenge Share Links" setting | |
| - App functions fully offline when HF credentials not configured | |
| **Deployment Platforms:** | |
| - Local development: Run with `streamlit run app.py` | |
| - Docker: Use provided `Dockerfile` | |
| - Hugging Face Spaces: Dockerfile deployment (recommended) | |
| - Any Python 3.10+ hosting with Streamlit support | |
| ## Development Status | |
| **Current Version:** 0.2.4 (Production Ready - Leaderboards Implemented) | |
| ### Completed ✅ | |
| - **v0.2.4:** Word List Filtering | |
| - Added "Filter Wordlist" button to sidebar | |
| - Implemented blocklist filtering via `assets/filter.txt` | |
| - Added results dialog showing removed words | |
| - **v0.2.1:** Daily and Weekly Leaderboards | |
| - Settings-based leaderboard separation | |
| - Folder-based discovery (no index.json) | |
| - Top 20 displayed entries per leaderboard | |
| - Four-tab leaderboard page (Today, Daily, Weekly, History) | |
| - Automatic score qualification and submission | |
| - Integration with challenge mode | |
| - Query parameter filtering for direct links | |
| - Settings page planned (move from sidebar, OAuth login required) | |
| - **v0.1.1:** Enhanced AI word generation | |
| - Intelligent word saving with duplicate prevention | |
| - Automatic retry mechanism (up to 3 attempts) | |
| - 1000-word file size limit | |
| - Improved HF Space API integration | |
| - Enhanced logging and error handling | |
| - **v0.1.0:** AI word generation foundation | |
| - Topic-based word list creation | |
| - Dual generation modes (HF Space + local) | |
| - Utility modules integration | |
| - **v0.0.2:** All 7 sprints complete | |
| - ✅ 100% test coverage (25/25 tests) | |
| - 📊 Development time: ~12.75 hours (sprints 1-7) | |
| - 📚 Complete documentation | |
| ### Future Roadmap | |
| - Local persistent storage, high score tracking, player statistics, leaderboard caching (future) | |
| - Enhanced UI animations, retry logic, rate limiting, archival script (future) | |
| - AI difficulty tuning, multi-language word generation, i18n (future) | |
| ## Copyright | |
| Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner. | |
| ## Test File Location | |
| All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests. | |