| # Wrdler Game Specifications (specs.md) | |
| **Version:** 0.0.2 | |
| **Status:** All Features Complete - Ready for Deployment | |
| **Last Updated:** 2025-01-31 | |
| ## Overview | |
| Wrdler is a simplified 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 | |
| - **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: | |
| - Good: 34-37 | |
| - Great: 38-41 | |
| - Fantastic: 42+ | |
| - **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.0.2) | |
| ### 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 | |
| ### 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 | |
| ## Storage | |
| ### Current (v0.0.2) | |
| - ✅ Challenge Mode uses remote storage via Hugging Face datasets | |
| - ✅ Game ID is generated from the word list for replay/sharing | |
| ### Planned (v0.3.0) | |
| - 📋 Local persistent storage for game results and high scores (JSON files) | |
| - 📋 Local storage location: `~/.wrdler/data/` | |
| - 📋 Privacy-first offline access | |
| ## UI Elements (v0.0.2 - 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/ | |
| └── {uid}/ | |
| └── settings.json # Challenge data with users array | |
| ``` | |
| **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 | |
| ### Completed (v0.0.2) ✅ | |
| All 7 sprints complete, 100% test coverage (25/25 tests passing): | |
| - **Sprint 1:** Core data models (rectangular grid support) | |
| - **Sprint 2:** Puzzle generator (horizontal-only, one-per-row) | |
| - **Sprint 3:** Radar visualization removal | |
| - **Sprint 4:** Free letter selection UI | |
| - **Sprint 5:** Grid UI updates for 8×6 display | |
| - **Sprint 6:** Integration testing | |
| - **Sprint 7:** Documentation finalization | |
| **Development Time:** ~12.75 hours | |
| **Test Pass Rate:** 100% (25/25 tests) | |
| **Status:** Ready for deployment! 🚀 | |
| ### Future Roadmap | |
| - **v0.3.0:** Local persistent storage, high score tracking, player statistics | |
| - **v1.0.0:** Enhanced UX, multiple difficulty levels, daily puzzle mode | |
| ## 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. | |