--- title: Battlewords emoji: 🎲 colorFrom: blue colorTo: indigo sdk: streamlit sdk_version: 1.56.0 python_version: 3.12.8 app_port: 8501 app_file: app.py tags: - game - vocabulary - streamlit - education --- # Battlewords > **This project is used by [huggingface.co](https://huggingface.co/spaces/Surn/Battlewords) as a demonstration of interactive word games in Python.** **Current Version:** 0.2.45 BASIC **Branch:** `basic` **Last Updated:** 2026-05-26 Battlewords is a vocabulary learning game inspired by classic Battleship mechanics. ## Recent Changes version 0.2.45 (basic) - UI updates: leaderboard navigation in footer menu, game over dialog integrates leaderboard submission and qualification results, footer links to Leaderboard/Play/Settings pages - Minimal documentation and version bumps version 0.2.44 (basic) - UI Imporovements and refinements version 0.2.43 (basic) - Update streamlit to 1.56.0 for improved security - Fix bug where Hall of Fantastics entries were not saving correctly due to missing `entry_type` in JSON schema File naming convention for Hall of Fantastics The Hall of Fantastics uses an ISO-week based folder layout so each week's leaderboard is stored separately. Files live under the HF dataset at: games/leaderboards/weekly///settings.json - is the ISO week id (e.g., `2026-W14`). - encodes settings as: `---fantastic` (e.g. `classic-classic-0-fantastic`). - `settings_version` is `0` for this release and should be incremented if puzzle/settings variants are introduced. Example path: `games/leaderboards/weekly/2026-W14/classic-classic-0-fantastic/settings.json` version 0.2.41 (basic) - Add Hall of Legends (Legendary runs save and viewable at ?page=hall) - Persist Hall entries using HF-backed Wrdler-compatible JSON schema - Minor UI: move leaderboard/hall routing to query-param `?page=hall` and integrate Hall save into Game Over dialog version 0.2.40 (basic) - Fix missing submit button error - UI refinements for smoother radar/grid rendering and transitions - Fix Game Over Close button behavior - version 0.2.39 (basic) - UI refinements for smooth game over and overlay transitions - Enhanced spinner implementation for improved loading feedback - version 0.2.38 (basic) - Slight delay added before rendering game over overlay to ensure radar and grid render correctly - Cursor sets to Your Guess box after revealing a letter for smoother gameplay flow - Minor UI adjustments and bug fixes - version 0.2.37 (basic) - Basic branch scope enforced: single play experience only - No query-param routing, no footer navigation, no sidebar - Challenge mode / share links / remote storage removed - PWA support removed - No audio system ## Features ### Core Gameplay - 12x12 grid with six hidden words (2x4-letter, 2x5-letter, 2x6-letter) - Words placed horizontally or vertically - Animated radar visualization showing word boundaries - Reveal grid cells and guess words for points - Scoring tiers: OK (<34), Good (34–37), Great (38–41), Fantastic (42-45), Legendary (46+) - Game ends when all words are guessed or all word letters are revealed - Incorrect guess history with tooltip and optional display (enabled by default) - 10 incorrect guess limit per game - Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal) ### Hall of Legends - Legendary runs (`score >= 46`) can be saved to Hall of Legends from the game-over flow. - Hall page is available in development and production at `?page=hall`. - Hall JSON is compatible with Wrdler leaderboard schema (`challenge_id`, `entry_type`, `users`, etc.) with `entry_type` set to `hall`. ### Visuals - Ocean-themed gradient background with wave animations are removed - Responsive UI built with Streamlit ### Word lists - Multiple word lists (classic, fourth_grade, wordlist) - Word lists are loaded locally from `battlewords/words/` ### Deployment & Technical - **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms - No special environment variables required ### Beta (v0.5.0) - Word overlaps on shared letters (crossword-style) - Enhanced responsive layout for mobile/tablet - Keyboard navigation and guessing ### Full (v1.0.0) - Daily puzzle mode with global leaderboards - Practice mode with hints - Multiple difficulty levels - Internationalization (i18n) support ## Installation 1. Clone the repository: ``` git clone https://github.com/Oncorporation/Battlewords.git cd battlewords ``` 2. (Optional) Create and activate a virtual environment: ``` python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` ``` 3. Install dependencies: ( add --system if not using a virutal environment) ``` uv pip install -r requirements.txt --link-mode=copy ``` ## Running Battlewords You can run the app locally using either [uv](https://github.com/astral-sh/uv) or Streamlit directly: ``` uv run streamlit run app.py ``` or ``` streamlit run app.py ``` ### Dockerfile Deployment (Hugging Face Spaces and more) Battlewords supports containerized deployment using a `Dockerfile`. This is the recommended method for deploying to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker) or any Docker-compatible environment. To deploy on Hugging Face Spaces: 1. Add a `Dockerfile` to your repository root (see [Spaces Dockerfile guide](https://huggingface.co/docs/hub/spaces-sdks-docker)). 2. Push your code to your Hugging Face Space. 3. The platform will build and run your app automatically. For local Docker runs: ```sh docker build -t battlewords . docker run -p8501:8501 battlewords ``` ### Environment Variables - `HF_API_TOKEN` (required for HF-backed Hall save/load in deployed environments) - `HF_REPO_ID` (HF dataset/repo used by storage helpers) - `SHORTENER_JSON_FILE` (optional, default: `shortener.json`) - `HALL_OF_LEGENDS_FILE` (optional, Hall JSON path in HF repo) ### Hall of Legends JSON Example (compatible) ```json { "challenge_id": "hall-of-legends/classic-classic-12x12", "entry_type": "hall", "game_mode": "classic", "grid_size": 12, "puzzle_options": { "spacer": 1, "may_overlap": false }, "users": [ { "uid": "20260325T184512Z-A9K2QW", "username": "Charles", "word_list": ["BLADE", "SHORE", "MARKET", "TUNNEL", "RIBBON", "CANDLE"], "score": 49, "time": 132.447291, "timestamp": "2026-03-25T18:45:12.902145+00:00", "word_list_difficulty": 112.3849012231 } ], "created_at": "2026-03-25T18:45:13.111942+00:00", "version": "0.2.40", "show_incorrect_guesses": true, "enable_free_letters": false, "wordlist_source": "classic.txt", "game_title": "Battlewords", "max_display_entries": 30 } ``` ## Folder Structure - `app.py` – Streamlit entry point - `battlewords/` – Python package - `models.py` – data models and types - `word_loader.py` – word list loading and validation - `generator.py` – word placement logic - `logic.py` – game mechanics (reveal, guess, scoring) - `ui.py` – Streamlit UI composition - `words/wordlist.txt` – candidate words - `specs/` – documentation (`specs/specs.mdx`, `specs/requirements.mdx`) ## How to Play 1. Click grid squares to reveal letters or empty spaces. 2. After revealing a letter, enter a guess for a word in the text box. 3. Earn points for correct guesses and bonus points for unrevealed letters. 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.** 5. Start a new run with **New Game**. ## Changelog - version 0.2.42 (basic) - Add Hall of Fantastics (weekly Fantastic runs saved and viewable at ?page=fantastic) - Fantastic runs (scores 42–45) can be saved to a weekly HF-backed leaderboard using Wrdler-style folders under `games/leaderboards/weekly//--0-fantastic/settings.json` - Game-over dialog now prompts Fantastic/Legendary qualifiers to save; Hall of Legends ranking numbers no longer show emoji medals (emojis retained for Hall of Fantastics) - version 0.2.37 (basic) - Removed Challenge Mode / Share Links / Remote Storage (HF) - Removed PWA support - Documentation trimmed to basic branch scope ## Known Issues / TODO - Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection persistence to ensure the chosen file is correctly used by the generator. ## Development Phases - **Proof of Concept (0.1.0):** No overlaps, basic UI, single session. - **Beta (0.5.0):** Overlaps allowed on shared letters, responsive layout, keyboard support, deterministic seed. - **Full (1.0.0):** Enhanced UX, persistence, leaderboards, daily/practice modes, advanced features. See `specs/requirements.md` and `specs/specs.md` for full details and roadmap. ## License BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner. ## Hugging Face Spaces Configuration Battlewords is deployed as a Hugging Face Space. You can use either the YAML config block or a Dockerfile for advanced/custom deployments. To configure your Space with the YAML block, add it at the top of your `README.md`: ```yaml --- title: Battlewords emoji: 🎲 colorFrom: blue colorTo: indigo sdk: streamlit sdk_version:1.25.0 python_version:3.10 app_file: app.py tags: - game - vocabulary - streamlit - education --- ``` **Key parameters:** - `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space. - `sdk`: Use `streamlit` for Streamlit apps. - `sdk_version`: Latest supported Streamlit version. - `python_version`: Python version (default is3.10). - `app_file`: Entry point for your app. - `tags`: List of descriptive tags. **Dependencies:** Add a `requirements.txt` with your Python dependencies (e.g., `streamlit`, etc.). **Port:** Streamlit Spaces use port `8501` by default. **Embedding:** Spaces can be embedded in other sites using an ` ``` For full configuration options, see [Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference) and [Streamlit SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-streamlit).