Spaces:
Sleeping
Sleeping
| 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/<ISO-week>/<file_id>/settings.json | |
| - <ISO-week> is the ISO week id (e.g., `2026-W14`). | |
| - <file_id> encodes settings as: `<wordlist>-<game_mode>-<settings_version>-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/<ISO-week>/<wordlist>-<mode>-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 `<iframe>`: | |
| ```html | |
| <iframe src="https://Surn-Battlewords.hf.space?embed=true" title="Battlewords"></iframe> | |
| ``` | |
| 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). | |