claude.md

BattleWords - Project Context

Project Overview

BattleWords is a vocabulary learning game inspired by Battleship mechanics, built with Streamlit and Python 3.12. Players reveal cells on a 12x12 grid to discover hidden words and earn points for strategic guessing.

Current Version: 0.2.6 Repository: https://github.com/Oncorporation/BattleWords.git Live Demo: https://huggingface.co/spaces/Surn/BattleWords

Core Gameplay

• 12x12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)
• Words placed horizontally or vertically, no overlaps
• Players click cells to reveal letters or empty spaces
• After revealing a letter, players can guess words
• Scoring: word length + bonus for unrevealed letters
• Game ends when all words are guessed or all word letters revealed

Scoring Tiers

• Fantastic: 42+ points
• Great: 38-41 points
• Good: 34-37 points
• Keep practicing: < 34 points

Technical Architecture

Technology Stack

• Framework: Streamlit 1.50.0
• Language: Python 3.12.8
• Visualization: Matplotlib, NumPy
• Data Processing: Pandas, Altair
• Testing: Pytest
• Code Quality: Flake8, MyPy
• Package Manager: UV (modern Python package manager)

Project Structure

battlewords/
├── app.py                    # Streamlit entry point
├── battlewords/              # Main package
│   ├── __init__.py          # Version: 0.2.6
│   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
│   ├── generator.py         # Puzzle generation with deterministic seeding
│   ├── logic.py             # Game mechanics (reveal, guess, scoring)
│   ├── ui.py                # Streamlit UI (~1170 lines)
│   ├── word_loader.py       # Word list management
│   ├── audio.py             # Background music system
│   ├── version_info.py      # Version display
│   └── words/               # Word list files
│       ├── classic.txt      # Default word list
│       └── wordlist.txt     # Additional words
├── tests/                   # Unit tests
├── specs/                   # Documentation
├── .env                     # Environment variables
├── pyproject.toml          # Project metadata
├── requirements.txt        # Dependencies
├── uv.lock                 # UV lock file
└── Dockerfile              # Container deployment

Key Features

Game Modes

1. Classic Mode: Allows consecutive guessing after correct answers
2. Too Easy Mode: Single guess per reveal

Puzzle Generation

• Deterministic seeding support for reproducible puzzles
• Configurable word spacing (spacer: 0-2)
  • 0: Words may touch
  • 1: At least 1 blank cell between words (default)
  • 2: At least 2 blank cells between words
• Validation ensures no overlaps, proper bounds, correct word distribution

UI Components

• Radar Visualization: Animated matplotlib GIF showing word boundaries
  • Displays pulsing rings at last letter of each word
  • Hides rings for guessed words
  • Three-layer composition: gradient background, scope image, animated rings
  • Cached per-puzzle with signature matching
• Game Grid: Interactive 12x12 button grid
• Score Panel: Real-time scoring with client-side timer
• Settings Sidebar: Word list picker, game mode, spacing, audio controls
• Theme System: Ocean gradient background with animations
• Audio System: Background music with volume control

Recent Fixes (cc-01 branch)

• Radar Alignment Issue: Fixed inconsistent sizing of animated rings layer
  • Added fig.subplots_adjust(left=0, right=0.9, top=0.9, bottom=0)
  • Set fig.patch.set_alpha(0.0) for transparent background
  • Maintains 2% margin for tick visibility while ensuring consistent layer alignment

Data Models

Core Classes

@dataclass
class Coord:
    x: int  # row, 0-based
    y: int  # col, 0-based

@dataclass
class Word:
    text: str
    start: Coord
    direction: Direction  # "H" or "V"
    cells: List[Coord]

@dataclass
class Puzzle:
    words: List[Word]
    radar: List[Coord]
    may_overlap: bool
    spacer: int
    uid: str  # Unique identifier for caching

@dataclass
class GameState:
    grid_size: int
    puzzle: Puzzle
    revealed: Set[Coord]
    guessed: Set[str]
    score: int
    last_action: str
    can_guess: bool
    game_mode: str
    points_by_word: Dict[str, int]
    start_time: Optional[datetime]
    end_time: Optional[datetime]

Development Workflow

Running Locally

# Install dependencies
uv pip install -r requirements.txt --link-mode=copy

# Run app
uv run streamlit run app.py
# or
streamlit run app.py

Docker Deployment

docker build -t battlewords .
docker run -p 8501:8501 battlewords

Testing

pytest tests/

Current Development Branch

Branch: cc-01 Purpose: Bug fixes and improvements, specifically radar graphic alignment

Git Configuration

• Remote ONCORP: https://github.com/Oncorporation/BattleWords.git (main remote)
• Remote Hugging: https://huggingface.co/spaces/Surn/BattleWords (deployment)

Known Issues

• Word list loading bug: App may not select proper word lists in some environments
  • Investigation needed in word_loader.get_wordlist_files() and load_word_list()
  • Sidebar selection persistence needs verification

Future Roadmap

Beta (0.5.0)

• Word overlaps on shared letters (crossword-style)
• Enhanced responsive layout
• Keyboard navigation and guessing
• Deterministic seed UI

Full (1.0.0)

• Daily puzzle mode
• Practice mode
• Leaderboards
• Persistent storage
• Enhanced UX features

Deployment Targets

• Hugging Face Spaces: Primary deployment platform
• Docker: Containerized deployment for any platform
• Local: Development and testing

Notes for Claude

• Project uses modern Python features (3.12+)
• Heavy use of Streamlit session state for game state management
• Matplotlib figures are converted to PIL images and animated GIFs
• Client-side JavaScript for timer updates without page refresh
• CSS heavily customized for game aesthetics
• All file paths should be absolute when working in WSL environment
• Current working directory: /mnt/d/Projects/Battlewords