Hugging Face's logo

Spaces:
Surn
/
BattleWords
Running

App Files Community
BattleWords / README.md
Surn's picture
Surn
Refactor UI and enhance styling for score panel
d6fd282
preview code
|
raw
history blame
8.49 kB
metadata
title: BattleWords
emoji: 🎲
colorFrom: blue
colorTo: indigo
sdk: streamlit
sdk_version: 1.50.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.

BattleWords is a vocabulary learning game inspired by classic Battleship mechanics. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.

Features

  • 12x12 grid with six hidden words (2x4-letter, 2x5-letter, 2x6-letter)
  • Words placed horizontally or vertically
  • Radar visualization to help locate word boundaries
  • Reveal grid cells and guess words for points
  • Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
  • Responsive UI built with Streamlit
  • Customizable word lists
  • Wordlist sidebar controls (picker + one-click sort)
  • Deterministic seed support (Beta/Full)
  • Keyboard navigation and guessing (Beta/Full)
  • Daily and practice modes (Full)
  • Leaderboards, persistence, and advanced features (Full)
  • Dockerfile-based deployment supported for Hugging Face Spaces and other container platforms
  • Game ends when all words are guessed or all word letters are revealed

Installation

  1. Clone the repository:
    git clone https://github.com/Oncorporation/BattleWords.git
 cd battlewords
    1. (Optional) Create and activate a virtual environment:
    python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
  2. 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 -p 8501:8501 battlewords

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.md, requirements.md)
  • tests/ – unit tests

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.

Changelog

  • 0.1.12

    • Updated the version to 0.1.12. Added new CSS classes .bold-text and .blue-background for improved text and background styling. Modified .shiny-border to adjust padding and border-radius for a more polished appearance.
    • Refactored _render_score_panel to replace the st.expander-based layout with an HTML-based table, introducing independent column backgrounds, visible gaps, and a new "extra points" calculation. Added a total row with enhanced styling.
    • Reorganized run_app for better layout structure and removed redundant state assignment.

  • 0.1.11

    • Added game-ending condition: the game now ends when all six words are guessed or all word letters are revealed.
    • implemented word spacing logic to prevent adjacent partial words and allow for future enhancements like overlaps.
    • implement loading html overlay and hide grid until ready.
    • Update to Game Summary table: shows words, base points, bonus points, total score; styled with Streamlit's st.table.
    • Show Grid Ticks and Space between words are now in settings.
    • Increase default font size for better readability.
    • Game end now modifies the grid display to show all words and disables further interaction.
    • Update to model for future enhancements

  • 0.1.10

    • Sidebar Game Mode selector: standard (allows guess chaining after correct guesses) and too easy (no chaining; score panel reveals words list).
    • Replaced Hit/Miss with Correct/Try Again status indicator for guesses.
    • UI polish: animated ocean background; metal-scope styled radar retained with session-cached GIF.
    • Footer shows version info (commit, Python, Streamlit).
    • Word list handling: defaults to classic.txt when present; selection persists across new games; sort action rewrites the file and restarts after 5s notice.
    • Documentation updated.
    • fixed wordlist selection persistence bug

  • 0.1.9

    • Background naming cleanup and consistency.
    • Version info surfaced in Settings panel.
    • Mobile layout improvements.

  • 0.1.8

    • Bumped runtime to Python 3.12 (and config/docs updated accordingly).

  • 0.1.5

    • Hit/Miss circular indicator.
    • Completed words render as non-interactive styled cells.
    • Tooltips show cell coordinates for buttons and revealed cells.
    • Stable letter map rebuild after reveals.

  • 0.1.4

    • Radar rewritten as an animated GIF with metallic gradient background and scope overlay.
    • Session-level caching of the generated radar GIF to avoid regeneration during a session.
    • Mobile layout improvements: radar above grid on small screens; tighter grid gaps and horizontal scrolling per row.

  • 0.1.3

    • Sidebar wordlist picker and Sort Wordlist action (length-first then alphabetic) with a 5-second feedback delay before restarting a new game.
    • Score panel improvements, per-word points, and emphasized final score styling.

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 deployable 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 is 3.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.