109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
# Game Grid Persistence
|
|
|
|
## Problem
|
|
|
|
Game grids are currently generated on the fly at every page load in `HomepageController`. There is no persistence — refreshing the page gives a new grid. Players cannot resume a game.
|
|
|
|
## Goal
|
|
|
|
Persist game grids so players can resume their current game. Display a "Start a game" button when no game is in progress. Allow players to abandon a game.
|
|
|
|
## Scope
|
|
|
|
- Grid generation and persistence only
|
|
- No win/loss logic (will be added later)
|
|
- No saving of player input (filled letters)
|
|
|
|
## Data Model
|
|
|
|
### Entity: `Game`
|
|
|
|
| Field | Type | Description |
|
|
|-------------|-------------------------|------------------------------------------------|
|
|
| `id` | int (auto) | Primary key |
|
|
| `user` | ManyToOne → User, nullable | Null for anonymous players |
|
|
| `mainActor` | ManyToOne → Actor | The actor to guess |
|
|
| `status` | string | `in_progress` or `abandoned` (extensible to `won` later) |
|
|
| `startedAt` | DateTimeImmutable | When the game started |
|
|
| `endedAt` | DateTimeImmutable, nullable | When the game ended (abandon or win) |
|
|
|
|
### Entity: `GameRow`
|
|
|
|
| Field | Type | Description |
|
|
|------------|--------------------|------------------------------------------------|
|
|
| `id` | int (auto) | Primary key |
|
|
| `game` | ManyToOne → Game | Parent game |
|
|
| `actor` | ManyToOne → Actor | The actor for this row |
|
|
| `position` | int | Index of the target letter in the actor's name |
|
|
| `rowOrder` | int | Order of this row in the grid |
|
|
|
|
`GameRow` is a separate entity (not JSON) to allow attaching hints/clues per row in a future iteration.
|
|
|
|
## Service: `GameGridGenerator`
|
|
|
|
Extracted from the current `HomepageController::index` logic:
|
|
|
|
1. Select a random main actor via `ActorRepository::findOneRandom()`
|
|
2. For each letter (a-z) in the main actor's name, find a random actor containing that letter
|
|
3. Create a `Game` entity with `status = in_progress` and `startedAt = now`
|
|
4. Create `GameRow` entities with the actor, letter position, and row order
|
|
5. Persist and flush
|
|
6. Return the `Game` entity
|
|
|
|
Also provides a method to compute grid display data (width, middle) from a `Game` and its rows, for passing to the React component.
|
|
|
|
## Routes
|
|
|
|
### `GET /` — Homepage (modified)
|
|
|
|
Current behavior replaced:
|
|
|
|
1. If user is connected → query `GameRepository` for a `Game` with `status = in_progress` for this user
|
|
2. If anonymous → get `current_game_id` from the Symfony session, then look up the `Game` in DB
|
|
3. If a game is found and still `in_progress` → render the grid with an "Abandon" button above it
|
|
4. If no game is found → render a "Start a game" button
|
|
|
|
### `POST /game/start` — Start a new game (new)
|
|
|
|
1. Verify no game is already in progress for this player (connected or session)
|
|
2. Call `GameGridGenerator` to create the game
|
|
3. If user is connected → the game is linked to the user
|
|
4. If anonymous → store `$game->getId()` in session key `current_game_id`
|
|
5. Redirect to `/`
|
|
|
|
### `POST /game/{id}/abandon` — Abandon a game (new)
|
|
|
|
1. Verify the game belongs to the current player (user match or session match)
|
|
2. Set `status = abandoned` and `endedAt = now`
|
|
3. If anonymous → remove `current_game_id` from session
|
|
4. Redirect to `/`
|
|
|
|
Both POST routes use CSRF protection.
|
|
|
|
## Anonymous Session Handling
|
|
|
|
- Session key: `current_game_id` (stores the `Game` ID)
|
|
- Set on game creation, removed on abandon
|
|
- On homepage load: if the stored game ID no longer exists or is not `in_progress`, clean up the session key
|
|
- No migration of anonymous games on login — the anonymous game is lost when the user logs in. Acceptable since we don't save letter input.
|
|
|
|
## Frontend
|
|
|
|
### Template changes (`homepage/index.html.twig`)
|
|
|
|
Three states:
|
|
|
|
1. **No game in progress**: centered "Start a game" button (Twig form, POST to `/game/start`)
|
|
2. **Game in progress**: action bar above the grid with an "Abandon" button (Twig form, POST to `/game/{id}/abandon` with CSRF token), then the React `GameGrid` component below
|
|
3. **After abandon**: redirect to `/`, which shows state 1
|
|
|
|
### React components
|
|
|
|
No changes to `GameGrid`, `GameRow`, `LetterInput`, or `ActorPopover`. They receive the same props (`grid`, `width`, `middle`) — the data source changes from on-the-fly generation to database lookup.
|
|
|
|
## Future Extensibility
|
|
|
|
- **Win logic**: add `won` to the status enum, set `endedAt` on win
|
|
- **Hints/clues per row**: add a relation on `GameRow` (e.g., `GameRowHint` entity)
|
|
- **Game history/stats**: query `Game` entities by user with status filters
|