specs/specs.md

Battlewords Game Requirements (specs.md)

Overview

Battlewords is inspired by the classic Battleship game, but uses words instead of ships. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.

Game Board

• 12 x 12 grid.
• Six hidden words:
  • Two four-letter words
  • Two five-letter words
  • Two six-letter words
• Words are placed horizontally (left-right) or vertically (top-down), not diagonally.
• Words may touch edges or corners but do not overlap unless a future mode allows shared letters.
• Entry point is app.py.
• Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms.

Gameplay (Common)

• Players click grid squares to reveal letters or empty spaces.
• Empty revealed squares are styled with CSS class empty.
• After any reveal, the app immediately reruns (st.rerun) to show the change.
• Use radar pulses to locate word boundaries (first and last letters).
• After revealing a letter, players may guess a word by entering it in a text box.
• Guess submission triggers an immediate rerun to reflect results.
• Only one guess per letter reveal; must uncover another letter before guessing again.
• In the default mode, a correct guess allows chaining an additional guess without another reveal.
• The game ends when all six words are guessed or all word letters are revealed.

Scoring

• Each correct word guess awards points:
  • 1 point per letter in the word
  • Bonus points for each hidden letter at the time of guessing
• Score tiers:
  • Good: 34-37
  • Great: 38-41
  • Fantastic: 42+
• Game over is triggered by either all words being guessed or all word letters being revealed.

POC (0.1.0) Rules

• No overlaps: words do not overlap or share letters.
• UI: basic grid, radar, and guess form.
• No keyboard interaction requirement.
• Seed is optional and not standardized.

Beta (0.5.0) Additions

• Optional validation pass to avoid unintended adjacent partial words (content curation rule).
• Cell rendering with consistent sizing and responsive layout (desktop/mobile).
• Keyboard support for navigation and guessing (custom JS via st.html or a component).
• Deterministic seed support to reproduce puzzles (e.g., daily seed derived from date).

Full (1.0.0) Rules

• No overlaps: words do not overlap or share letters.
• Enhanced UX polish (animations, accessibility, themes).
• Persistence, leaderboards, and additional modes as specified in requirements.
• Deterministic daily mode and practice mode supported.

New Features (v0.3.0)

• Game ID Sharing: Each puzzle generates a deterministic game ID based on the word list. Players can share URLs with ?game_id=ABC123 to challenge others with the same words.
• Persistent Storage: Game results and high scores are saved locally in ~/.battlewords/data/.
• High Scores: Top scores are tracked and displayed in the sidebar, filterable by wordlist and game mode.
• Player Name: Optional player name is saved with results.

Storage

• Game results and high scores are stored in JSON files for privacy and offline access.
• Game ID is generated from the sorted word list for replay/sharing.

UI Elements

• 12x12 grid
• Radar screen (shows last letter locations); y-axis inverted so (0,0) is top-left
• Text box for word guesses
• Score display (shows word, base points, bonus points, total score)
• Guess status indicator (Correct/Try Again)
• Game ID display and share button in game over dialog.
• High score expander in sidebar.
• Player name input in sidebar.

Word List

• External list at battlewords/words/wordlist.txt.
• Loaded by battlewords.word_loader.load_word_list() with caching.
• Filtered to uppercase A�Z, lengths in {4,5,6}; falls back if < 25 per length.

Generator

• Centralized word loader.
• No duplicate word texts are selected.

Entry Point

• The Streamlit entry point is app.py.
• A Dockerfile can be used for containerized deployment (recommended for Hugging Face Spaces).

Copyright

BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

v0.2.20: Remote Storage and Shortened game_id URL

Game Sharing

• Each puzzle can be shared via a link containing a game_id querystring (short id / sid)
• game_id resolves to a settings JSON on the storage server (HF repo)
• JSON fields:
  • word_list (list of 6 uppercase words)
  • score (int), time (int seconds) [metadata only]
  • game_mode (e.g., classic, too easy)
  • grid_size (e.g., 12)
  • puzzle_options (e.g., { spacer, may_overlap })
• On load with game_id, fetch and apply: word_list, game_mode, grid_size, puzzle_options

High Scores

• Repository maintains highscores/highscores.json for top scores
• Local highscores remain supported for offline use

UI/UX

• Show the current game_id (sid) and a �Share Challenge� link
• When loading with a game_id, indicate the puzzle is a shared challenge

Security/Privacy

• Only game configuration and scores are stored; no personal data is required
• game_id is a short reference; full URL is stored in a repo JSON shortener index

Challenge Mode & Leaderboard

• When loading a shared challenge via game_id, the leaderboard displays all user results for that challenge.
• Sorting: The leaderboard is sorted by highest score (descending), then by fastest time (ascending).
• Results are stored remotely in a Hugging Face dataset repo and updated via the app.