Spaces:

Surn
/

BattleWords

Running

App Files Files Community

BattleWords / README.md

Surn

Add version info, scrollable sidebar, and radar fix

e63d029 2 months ago

preview code

raw

history blame

6.7 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

Clone the repository:

git clone https://github.com/Oncorporation/BattleWords.git
 cd battlewords

(Optional) Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

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

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:

Add a Dockerfile to your repository root (see Spaces Dockerfile guide).
Push your code to your Hugging Face Space.
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

Click grid squares to reveal letters or empty spaces.
After revealing a letter, enter a guess for a word in the text box.
Earn points for correct guesses and bonus points for unrevealed letters.
The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.

Changelog

0.2.3
- Update version information display
- adjust sonar grid alignment
- fix settings scroll issue
0.2.2
- Add Musical background and settings to toggle sound on/off.
0.2.1
- Add Theme toggle (light/dark/custom) in sidebar.
0.2.0
- Added a loading screen when starting a new game.
- Added a congratulations screen with your final score and tier when the game ends.
0.1.13
- Improved score summary layout for clarity and style.
0.1.12
- Improved score summary layout and styling.
- Enhanced overall appearance and readability.
0.1.11
- Game now ends when all words are found or revealed.
- Added word spacing logic and improved settings.
0.1.10
- Added game mode selector and improved UI feedback.
0.1.9
- Improved background and mobile layout.
0.1.8
- Updated to Python 3.12.
0.1.5
- Added hit/miss indicator and improved grid feedback.
0.1.4
- Radar visualization improved and mobile layout enhanced.
0.1.3
- Added wordlist picker and sort feature.
- Improved score panel and final score display.

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

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.