README.md

metadata

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 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: <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 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 or any Docker-compatible environment.

To deploy on Hugging Face Spaces:

1. Add a Dockerfile to your repository root (see Spaces Dockerfile guide).
2. Push your code to your Hugging Face Space.
3. The platform will build and run your app automatically.

For local Docker runs:

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)

{
  "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:

---
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>:

<iframe src="https://Surn-Battlewords.hf.space?embed=true" title="Battlewords"></iframe>

For full configuration options, see Spaces Config Reference and Streamlit SDK Guide.