Hugging Face's logo

Spaces:
Surn
/
BattleWords
Running

App Files Community
BattleWords
File size: 4,311 Bytes 
032159d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b66ffa9
032159d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7f5ea9e
032159d
 
 
 
 
 
 
 
 
 
 
 
 
 
4e65519
032159d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7f5ea9e
032159d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
---
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
---

# BattleWords

> **This project is used by [huggingface.co](https://huggingface.co/spaces/Surn/BattleWords) 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
- Deterministic seed support (Beta/Full)
- Keyboard navigation and guessing (Beta/Full)
- Overlapping words on shared letters (Beta)
- Daily and practice modes (Full)
- Leaderboards, persistence, and advanced features (Full)
- **Game ends when all words are guessed or all word letters are revealed**

## Installation
1. Clone the repository:
   ```
   git clone
    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:
    ```
    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
```

## 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.**

## 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. To configure your Space, add a YAML block 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 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>`:

```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).