Spaces:
Running
Running
| # Battlewords Game Requirements (specs.md) | |
| ## Overview | |
| Battlewords is inspired by the classic Battleship game, but uses words instead of ships. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed. | |
| ## Game Board | |
| - 12 x 12 grid. | |
| - Six hidden words: | |
| - Two four-letter words | |
| - Two five-letter words | |
| - Two six-letter words | |
| - Words are placed horizontally (left-right) or vertically (top-down), not diagonally. | |
| - Words may touch edges or corners but do not overlap unless a future mode allows shared letters. | |
| - Entry point is `app.py`. | |
| - **Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms.** | |
| ## Gameplay (Common) | |
| - 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. | |
| - Use radar pulses to locate word boundaries (first and last letters). | |
| - 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.** | |
| ## POC (0.1.0) Rules | |
| - No overlaps: words do not overlap or share letters. | |
| - UI: basic grid, radar, and guess form. | |
| - No keyboard interaction requirement. | |
| - Seed is optional and not standardized. | |
| ## Beta (0.5.0) Additions | |
| - Optional validation pass to avoid unintended adjacent partial words (content curation rule). | |
| - Cell rendering with consistent sizing and responsive layout (desktop/mobile). | |
| - Keyboard support for navigation and guessing (custom JS via `st.html` or a component). | |
| - Deterministic seed support to reproduce puzzles (e.g., daily seed derived from date). | |
| ## Full (1.0.0) Rules | |
| - No overlaps: words do not overlap or share letters. | |
| - Enhanced UX polish (animations, accessibility, themes). | |
| - Persistence, leaderboards, and additional modes as specified in requirements. | |
| - Deterministic daily mode and practice mode supported. | |
| ## UI Elements | |
| - 12x12 grid | |
| - Radar screen (shows last letter locations); y-axis inverted so (0,0) is top-left | |
| - Text box for word guesses | |
| - Score display (shows word, base points, bonus points, total score) | |
| - Guess status indicator (Correct/Try Again) | |
| ## Word List | |
| - External list at `battlewords/words/wordlist.txt`. | |
| - Loaded by `battlewords.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. | |
| ## Entry Point | |
| - The Streamlit entry point is `app.py`. | |
| - **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces).** | |
| ## Copyright | |
| BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner. | |