mg/wordsearch
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add game logic design spec

Browse Source 
Defines data models (Category, CategoryWord, Game, Word), board
factory, REST API endpoints, and dual-input frontend design for the
word search game.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Mathew Sir Guest the best
2026-05-06 22:28:24 -06:00
co-authored by Claude Opus 4.6
commit 85045f2a5f
1 changed files with 248 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-05-06-game-logic-design.md
+248
View File
@@ -0,0 +1,248 @@
# Word Search Game Logic Design
## Context
The project has a Tornado web server with two stub pages (main, game) and a dark teal Bootstrap theme. No game logic exists yet. This spec defines the data layer (SQLAlchemy + Alembic + SQLite), board generation, REST API, and frontend interaction needed to make the word search game playable.
The design prioritizes server-side game logic for testability and cheat resistance, while keeping the frontend interactive enough for both text and click-based input.
## Data Models
All models use SQLAlchemy ORM with a SQLite database file (e.g. `wordsearch.db`).
### Category
| Column | Type | Notes |
|--------|-------------|--------------------|
| id | Integer PK | Auto-increment |
| name | String(50) | Unique, e.g. "animals" |
### CategoryWord
| Column | Type | Notes |
|-------------|-------------|------------------------|
| id | Integer PK | Auto-increment |
| category_id | Integer FK | References Category.id |
| word | String(20) | Uppercase, e.g. "TIGER" |
Unique constraint on `(category_id, word)`.
### Game
| Column | Type | Notes |
|--------------|--------------|------------------------------------|
| id | String(36) PK | UUID as string |
| category_id | Integer FK | References Category.id |
| board_size | Integer | Grid dimension (N x N), default 10 |
| grid | JSON | 2D array of single uppercase chars |
| status | String(20) | "in_progress" or "completed" |
| started_at | DateTime | Set on creation (UTC) |
| completed_at | DateTime | Nullable, set when all words found |
### Word
| Column | Type | Notes |
|-----------|--------------|----------------------------------------|
| id | Integer PK | Auto-increment |
| game_id | String(36) FK | References Game.id |
| text | String(20) | The placed word, uppercase |
| start_row | Integer | 0-indexed row of first letter |
| start_col | Integer | 0-indexed column of first letter |
| direction | String(2) | One of: E, W, N, S, NE, NW, SE, SW |
| found | Boolean | Default false |
| found_at | DateTime | Nullable, set when word is matched |
## Direction Encoding
Directions map to (row_delta, col_delta):
- E = (0, +1), W = (0, -1)
- S = (+1, 0), N = (-1, 0)
- SE = (+1, +1), SW = (+1, -1)
- NE = (-1, +1), NW = (-1, -1)
## Board Factory
Module: `game/factory.py`
Class `BoardFactory`:
1. **Input**: `category_id`, `board_size` (default 10), `word_count` (default 8)
2. **Query**: Fetch all `CategoryWord` rows for the category. Filter to words that fit within `board_size`. Randomly select `word_count` words.
3. **Placement loop**: For each word, try random (row, col, direction) positions. A position is valid if:
- The word fits within grid bounds
- Each cell is either empty or already contains the same letter (overlap is allowed)
- Max placement attempts per word: 100. If exceeded, skip the word.
4. **Fill**: Remaining empty cells get random uppercase letters (A-Z).
5. **Output**: Returns a `Game` object and list of `Word` objects (not yet committed to DB).
## Database Setup
- **Engine**: SQLAlchemy with `sqlite:///wordsearch.db` (file in project root)
- **Session**: A session factory created at app startup, passed to handlers via `Application.settings`
- **Alembic**: Configured with `alembic init`, migrations in `alembic/versions/`
- **Seed data**: An initial migration or seed script populates `Category` and `CategoryWord` tables with at least 3 categories (~20-30 words each):
- Animals (TIGER, DOLPHIN, EAGLE, etc.)
- Colors (CRIMSON, VIOLET, AMBER, etc.)
- Food (PIZZA, SUSHI, MANGO, etc.)
## API Endpoints
All API handlers inherit from a base that sets `Content-Type: application/json`.
### GET /api/categories
Returns all available categories.
**Response:**
```json
[
{"id": 1, "name": "animals"},
{"id": 2, "name": "colors"},
{"id": 3, "name": "food"}
]
```
### POST /api/game/new
**Request body:**
```json
{"category_id": 1, "board_size": 12}
```
`board_size` is optional (default 10, clamped to 8-20).
**Behavior**: Creates a new game via `BoardFactory`, persists to DB, returns game state.
**Response** (same format as GET /api/game/<id>):
```json
{
"id": "uuid",
"board_size": 12,
"category": "animals",
"grid": [["A","B",...], ...],
"words": [
{"text": "TIGER", "found": false},
...
],
"started_at": "2026-05-06T12:00:00Z",
"status": "in_progress"
}
```
Note: word positions (start_row, start_col, direction) are NOT sent to the client. The client only knows the word text and whether it's been found.
### GET /api/game/{id}
Returns the current game state in the same format as above. Includes `completed_at` if finished.
### POST /api/game/{id}/guess
**Request body** (text guess):
```json
{"word": "TIGER"}
```
**Request body** (click guess):
```json
{"cells": [{"row": 0, "col": 3}, {"row": 0, "col": 4}, ...]}
```
**Validation (text guess)**:
1. Uppercase the input
2. Check if the word exists in this game's `Word` list
3. Check if it hasn't already been found
4. If valid: mark `found=true`, set `found_at`
**Validation (click guess)**:
1. Extract the letter at each (row, col) from the grid
2. Concatenate to form a word string
3. Check if that word exists and the cells match the stored placement coordinates
4. If valid: mark found
**Response**:
```json
{
"correct": true,
"word": "TIGER",
"cells": [{"row": 0, "col": 3}, {"row": 0, "col": 4}, ...],
"words": [...updated word list...],
"status": "in_progress",
"completed_at": null
}
```
When `correct` is true, `cells` contains the word's actual grid positions so the frontend can highlight them. When the last word is found, `status` changes to `"completed"` and `completed_at` is set.
## Frontend (game.html)
### Game Setup
On the `/game` page, before a game starts:
- A dropdown to pick a category (populated from a `GET /api/categories` endpoint)
- A board size selector (range input or dropdown, 8-20, default 10)
- A "New Game" button
### Game Board
After starting a game:
- The grid renders as an HTML `<table>` with one letter per `<td>`, styled with the teal theme
- A word list sidebar shows all target words, with found words crossed off and highlighted
- A timer displays elapsed seconds since `started_at`
### Text Input
- An input field below the grid with a "Submit" button
- On submit: `POST /api/game/{id}/guess` with `{word: input_value}`
- If correct: highlight the word's cells on the grid in accent color, cross off the word in the list
- If incorrect: brief shake animation or "not found" flash message
### Click Selection
- Clicking a cell starts a selection, subsequent clicks extend it
- Selected cells highlight in a temporary color
- A "Submit Selection" button sends `POST /api/game/{id}/guess` with the cell coordinates
- Clear selection on successful match or via a "Clear" button
- Constraint: clicks must form a straight line (horizontal, vertical, or diagonal). Frontend validates this before submitting.
### Game Complete
When all words are found:
- Stop the timer
- Show a completion banner with elapsed time
- Offer a "Play Again" button that returns to game setup
## Project Structure (new/modified files)
```
ai_demo_backend/
├── app.py # Add db session setup, new API routes
├── db.py # SQLAlchemy engine + session factory
├── models/
│ ├── __init__.py
│ ├── category.py # Category, CategoryWord
│ └── game.py # Game, Word
├── game/
│ ├── __init__.py
│ └── factory.py # BoardFactory
├── handlers/
│ ├── api.py # API handlers (new game, guess, categories)
│ ├── game.py # (existing, updated)
│ └── main.py # (existing, unchanged)
├── templates/
│ ├── game.html # (existing, rewritten with game UI)
│ └── ...
├── static/
│ ├── css/theme.css # (existing, extended with grid styles)
│ └── js/game.js # Frontend game logic
├── alembic/ # Alembic migrations directory
├── alembic.ini # Alembic config
└── seed.py # Optional: seed script for categories
```
## Future Scaling Considerations
- The `Game` model already supports multiple concurrent games via UUID. The current UI only shows one game at a time, but the API is stateless per game ID.
- To support multiple users: add a `player_id` or session token to `Game`.
- To support leaderboards: query `Game` rows with `status=completed`, ordered by `completed_at - started_at`.
- Categories and words in the DB means they can be managed via an admin interface or API later.