572 lines
15 KiB
Markdown
572 lines
15 KiB
Markdown
# Game Hints System Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Each game row displays a typed hint (film, character, award) about the main actor, replacing the "?" popover button with a type-specific icon.
|
|
|
|
**Architecture:** Two new columns (`hint_type`, `hint_data`) on `GameRow`. Hints are generated at game creation time in `GameGridGenerator`. A new `WikidataAwardGateway` service fetches awards via SPARQL. The React `ActorPopover` component shows a type icon instead of "?" and displays the resolved hint text in the popover.
|
|
|
|
**Tech Stack:** Symfony 8 / Doctrine ORM (backend), React 19 (frontend), Wikidata SPARQL API (awards), Font Awesome (icons)
|
|
|
|
---
|
|
|
|
### Task 1: Add `hintType` and `hintData` columns to `GameRow` entity
|
|
|
|
**Files:**
|
|
- Modify: `src/Entity/GameRow.php`
|
|
|
|
- [ ] **Step 1: Add properties and mapping to `GameRow`**
|
|
|
|
Add after the `$rowOrder` property (line 30):
|
|
|
|
```php
|
|
#[ORM\Column(length: 20)]
|
|
private ?string $hintType = null;
|
|
|
|
#[ORM\Column(length: 255)]
|
|
private ?string $hintData = null;
|
|
```
|
|
|
|
Add getters and setters after `setRowOrder()`:
|
|
|
|
```php
|
|
public function getHintType(): ?string
|
|
{
|
|
return $this->hintType;
|
|
}
|
|
|
|
public function setHintType(string $hintType): static
|
|
{
|
|
$this->hintType = $hintType;
|
|
|
|
return $this;
|
|
}
|
|
|
|
public function getHintData(): ?string
|
|
{
|
|
return $this->hintData;
|
|
}
|
|
|
|
public function setHintData(string $hintData): static
|
|
{
|
|
$this->hintData = $hintData;
|
|
|
|
return $this;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Generate and run migration**
|
|
|
|
```bash
|
|
php bin/console doctrine:migrations:diff
|
|
php bin/console doctrine:migrations:migrate --no-interaction
|
|
```
|
|
|
|
Expected: new migration adding `hint_type` and `hint_data` columns to `game_row`.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/Entity/GameRow.php migrations/
|
|
git commit -m "feat: add hintType and hintData columns to GameRow entity"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Add `MovieRoleRepository::findOneRandomByActor()` method
|
|
|
|
**Files:**
|
|
- Modify: `src/Repository/MovieRoleRepository.php`
|
|
|
|
- [ ] **Step 1: Write the repository method**
|
|
|
|
Replace the commented-out methods with:
|
|
|
|
```php
|
|
/**
|
|
* @param list<int> $excludeMovieRoleIds MovieRole IDs to exclude
|
|
* @return MovieRole|null
|
|
*/
|
|
public function findOneRandomByActor(int $actorId, array $excludeMovieRoleIds = []): ?MovieRole
|
|
{
|
|
$qb = $this->createQueryBuilder('mr')
|
|
->andWhere('mr.actor = :actorId')
|
|
->setParameter('actorId', $actorId);
|
|
|
|
if (!empty($excludeMovieRoleIds)) {
|
|
$qb->andWhere('mr.id NOT IN (:excludeIds)')
|
|
->setParameter('excludeIds', $excludeMovieRoleIds);
|
|
}
|
|
|
|
return $qb
|
|
->orderBy('RANDOM()')
|
|
->setMaxResults(1)
|
|
->getQuery()
|
|
->getOneOrNullResult();
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Commit**
|
|
|
|
```bash
|
|
git add src/Repository/MovieRoleRepository.php
|
|
git commit -m "feat: add findOneRandomByActor to MovieRoleRepository"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Create `WikidataAwardGateway` service
|
|
|
|
**Files:**
|
|
- Create: `src/Service/WikidataAwardGateway.php`
|
|
|
|
- [ ] **Step 1: Create the gateway service**
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace App\Service;
|
|
|
|
use App\Entity\Actor;
|
|
use Symfony\Contracts\HttpClient\HttpClientInterface;
|
|
|
|
class WikidataAwardGateway
|
|
{
|
|
private const SPARQL_ENDPOINT = 'https://query.wikidata.org/sparql';
|
|
|
|
public function __construct(
|
|
private readonly HttpClientInterface $httpClient,
|
|
) {}
|
|
|
|
/**
|
|
* Fetch awards for an actor from Wikidata.
|
|
*
|
|
* @return list<array{name: string, year: int}>
|
|
*/
|
|
public function getAwards(Actor $actor): array
|
|
{
|
|
$sparql = $this->buildQuery($actor->getName());
|
|
|
|
$response = $this->httpClient->request('GET', self::SPARQL_ENDPOINT, [
|
|
'query' => [
|
|
'query' => $sparql,
|
|
'format' => 'json',
|
|
],
|
|
'headers' => [
|
|
'Accept' => 'application/sparql-results+json',
|
|
'User-Agent' => 'LtbxdActorle/1.0',
|
|
],
|
|
]);
|
|
|
|
$data = $response->toArray();
|
|
$awards = [];
|
|
|
|
foreach ($data['results']['bindings'] ?? [] as $binding) {
|
|
$name = $binding['awardLabel']['value'] ?? null;
|
|
$year = $binding['year']['value'] ?? null;
|
|
|
|
if ($name && $year) {
|
|
$awards[] = [
|
|
'name' => $name,
|
|
'year' => (int) substr($year, 0, 4),
|
|
];
|
|
}
|
|
}
|
|
|
|
return $awards;
|
|
}
|
|
|
|
private function buildQuery(string $actorName): string
|
|
{
|
|
$escaped = str_replace('"', '\\"', $actorName);
|
|
|
|
return <<<SPARQL
|
|
SELECT ?awardLabel ?year WHERE {
|
|
?person rdfs:label "{$escaped}"@en .
|
|
?person wdt:P31 wd:Q5 .
|
|
?person p:P166 ?awardStatement .
|
|
?awardStatement ps:P166 ?award .
|
|
?awardStatement pq:P585 ?date .
|
|
BIND(YEAR(?date) AS ?year)
|
|
SERVICE wikibase:label { bd:serviceParam wikibase:language "fr,en" . }
|
|
}
|
|
ORDER BY DESC(?year)
|
|
SPARQL;
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Verify the service is autowired**
|
|
|
|
```bash
|
|
php bin/console debug:container WikidataAwardGateway
|
|
```
|
|
|
|
Expected: service `App\Service\WikidataAwardGateway` is listed.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/Service/WikidataAwardGateway.php
|
|
git commit -m "feat: add WikidataAwardGateway for actor awards from Wikidata SPARQL"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Integrate hint generation into `GameGridGenerator`
|
|
|
|
**Files:**
|
|
- Modify: `src/Service/GameGridGenerator.php`
|
|
|
|
- [ ] **Step 1: Add dependencies to constructor**
|
|
|
|
Update the constructor at line 16-19:
|
|
|
|
```php
|
|
public function __construct(
|
|
private readonly ActorRepository $actorRepository,
|
|
private readonly MovieRoleRepository $movieRoleRepository,
|
|
private readonly WikidataAwardGateway $wikidataAwardGateway,
|
|
private readonly EntityManagerInterface $em,
|
|
) {}
|
|
```
|
|
|
|
Add the import at the top:
|
|
|
|
```php
|
|
use App\Repository\MovieRoleRepository;
|
|
```
|
|
|
|
- [ ] **Step 2: Add hint generation methods**
|
|
|
|
Add these private methods after `computeGridData()`:
|
|
|
|
```php
|
|
/**
|
|
* @param list<int> $usedMovieRoleIds MovieRole IDs already used (for DB exclusion)
|
|
* @param list<string> $usedHintKeys Semantic keys like "film:42" to avoid duplicate hints
|
|
* @return array{type: string, data: string}|null
|
|
*/
|
|
private function generateHint(Actor $mainActor, array &$usedMovieRoleIds, array &$usedHintKeys): ?array
|
|
{
|
|
$types = ['film', 'character', 'award'];
|
|
shuffle($types);
|
|
|
|
foreach ($types as $type) {
|
|
$hint = $this->resolveHint($type, $mainActor, $usedMovieRoleIds, $usedHintKeys);
|
|
if ($hint !== null) {
|
|
return $hint;
|
|
}
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* @param list<int> $usedMovieRoleIds
|
|
* @param list<string> $usedHintKeys
|
|
* @return array{type: string, data: string}|null
|
|
*/
|
|
private function resolveHint(string $type, Actor $mainActor, array &$usedMovieRoleIds, array &$usedHintKeys): ?array
|
|
{
|
|
switch ($type) {
|
|
case 'film':
|
|
$role = $this->movieRoleRepository->findOneRandomByActor(
|
|
$mainActor->getId(),
|
|
$usedMovieRoleIds,
|
|
);
|
|
if ($role === null) {
|
|
return null;
|
|
}
|
|
$movieId = (string) $role->getMovie()->getId();
|
|
$key = 'film:' . $movieId;
|
|
if (in_array($key, $usedHintKeys)) {
|
|
return null;
|
|
}
|
|
$usedMovieRoleIds[] = $role->getId();
|
|
$usedHintKeys[] = $key;
|
|
return ['type' => 'film', 'data' => $movieId];
|
|
|
|
case 'character':
|
|
$role = $this->movieRoleRepository->findOneRandomByActor(
|
|
$mainActor->getId(),
|
|
$usedMovieRoleIds,
|
|
);
|
|
if ($role === null) {
|
|
return null;
|
|
}
|
|
$roleId = (string) $role->getId();
|
|
$key = 'character:' . $roleId;
|
|
if (in_array($key, $usedHintKeys)) {
|
|
return null;
|
|
}
|
|
$usedMovieRoleIds[] = $role->getId();
|
|
$usedHintKeys[] = $key;
|
|
return ['type' => 'character', 'data' => $roleId];
|
|
|
|
case 'award':
|
|
try {
|
|
$awards = $this->wikidataAwardGateway->getAwards($mainActor);
|
|
} catch (\Throwable) {
|
|
return null;
|
|
}
|
|
foreach ($awards as $award) {
|
|
$text = $award['name'] . ' (' . $award['year'] . ')';
|
|
$key = 'award:' . $text;
|
|
if (!in_array($key, $usedHintKeys)) {
|
|
$usedHintKeys[] = $key;
|
|
return ['type' => 'award', 'data' => $text];
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
return null;
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Wire hint generation into `generate()`**
|
|
|
|
Add `$usedMovieRoleIds = [];` and `$usedHintKeys = [];` after `$rowOrder = 0;` (line 31), and add hint assignment after `$row->setRowOrder($rowOrder);` (line 51):
|
|
|
|
```php
|
|
$hint = $this->generateHint($mainActor, $usedMovieRoleIds, $usedHintKeys);
|
|
if ($hint !== null) {
|
|
$row->setHintType($hint['type']);
|
|
$row->setHintData($hint['data']);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/Service/GameGridGenerator.php
|
|
git commit -m "feat: generate hints per row in GameGridGenerator"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Resolve hint display text in `computeGridData()`
|
|
|
|
**Files:**
|
|
- Modify: `src/Service/GameGridGenerator.php`
|
|
|
|
- [ ] **Step 1: Add repositories needed for resolution**
|
|
|
|
Add import:
|
|
|
|
```php
|
|
use App\Repository\MovieRepository;
|
|
```
|
|
|
|
Update constructor:
|
|
|
|
```php
|
|
public function __construct(
|
|
private readonly ActorRepository $actorRepository,
|
|
private readonly MovieRoleRepository $movieRoleRepository,
|
|
private readonly MovieRepository $movieRepository,
|
|
private readonly WikidataAwardGateway $wikidataAwardGateway,
|
|
private readonly EntityManagerInterface $em,
|
|
) {}
|
|
```
|
|
|
|
- [ ] **Step 2: Add hint data to grid output in `computeGridData()`**
|
|
|
|
In the `computeGridData()` method, update the `$grid[]` assignment (around line 105-109) to include hint data:
|
|
|
|
```php
|
|
$hintText = $this->resolveHintText($row);
|
|
|
|
$grid[] = [
|
|
'actorName' => $actor->getName(),
|
|
'actorId' => $actor->getId(),
|
|
'pos' => $pos,
|
|
'hintType' => $row->getHintType(),
|
|
'hintText' => $hintText,
|
|
];
|
|
```
|
|
|
|
- [ ] **Step 3: Add `resolveHintText()` method**
|
|
|
|
```php
|
|
private function resolveHintText(GameRow $row): ?string
|
|
{
|
|
$type = $row->getHintType();
|
|
$data = $row->getHintData();
|
|
|
|
if ($type === null || $data === null) {
|
|
return null;
|
|
}
|
|
|
|
return match ($type) {
|
|
'film' => $this->movieRepository->find((int) $data)?->getTitle(),
|
|
'character' => $this->movieRoleRepository->find((int) $data)?->getCharacter(),
|
|
'award' => $data,
|
|
default => null,
|
|
};
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Update the return type docblock**
|
|
|
|
Update the `@return` annotation of `computeGridData()`:
|
|
|
|
```php
|
|
/**
|
|
* Compute display data (grid, width, middle) from a Game entity for the React component.
|
|
*
|
|
* @return array{grid: list<array{actorName: string, actorId: int, pos: int, hintType: ?string, hintText: ?string}>, width: int, middle: int}
|
|
*/
|
|
```
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/Service/GameGridGenerator.php src/Repository/MovieRepository.php
|
|
git commit -m "feat: resolve hint display text in computeGridData"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: Install Font Awesome and update `ActorPopover` component
|
|
|
|
**Files:**
|
|
- Modify: `assets/react/controllers/ActorPopover.jsx`
|
|
- Modify: `assets/react/controllers/GameGrid.jsx`
|
|
- Modify: `assets/react/controllers/GameRow.jsx`
|
|
|
|
- [ ] **Step 1: Install Font Awesome**
|
|
|
|
```bash
|
|
cd /home/thibaud/ltbxd-actorle && npm install @fortawesome/fontawesome-free
|
|
```
|
|
|
|
- [ ] **Step 2: Import Font Awesome CSS in the app entrypoint**
|
|
|
|
Check the main JS entrypoint:
|
|
|
|
```bash
|
|
head -5 assets/app.js
|
|
```
|
|
|
|
Add at the top of `assets/app.js`:
|
|
|
|
```js
|
|
import '@fortawesome/fontawesome-free/css/all.min.css';
|
|
```
|
|
|
|
- [ ] **Step 3: Update `ActorPopover` to accept hint props**
|
|
|
|
Replace the full content of `assets/react/controllers/ActorPopover.jsx`:
|
|
|
|
```jsx
|
|
import React, { useState } from 'react';
|
|
import { useFloating, useClick, useDismiss, useInteractions, offset, flip, shift } from '@floating-ui/react';
|
|
|
|
const HINT_ICONS = {
|
|
film: 'fa-solid fa-film',
|
|
character: 'fa-solid fa-masks-theater',
|
|
award: 'fa-solid fa-trophy',
|
|
};
|
|
|
|
export default function ActorPopover({ hintType, hintText }) {
|
|
const [isOpen, setIsOpen] = useState(false);
|
|
|
|
const { refs, floatingStyles, context } = useFloating({
|
|
open: isOpen,
|
|
onOpenChange: setIsOpen,
|
|
middleware: [offset(8), flip(), shift()],
|
|
placement: 'left',
|
|
});
|
|
|
|
const click = useClick(context);
|
|
const dismiss = useDismiss(context);
|
|
const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
|
|
|
|
const iconClass = HINT_ICONS[hintType] || 'fa-solid fa-circle-question';
|
|
|
|
return (
|
|
<>
|
|
<button
|
|
ref={refs.setReference}
|
|
{...getReferenceProps()}
|
|
className="popover-trigger"
|
|
type="button"
|
|
>
|
|
<i className={iconClass}></i>
|
|
</button>
|
|
{isOpen && (
|
|
<div
|
|
ref={refs.setFloating}
|
|
style={floatingStyles}
|
|
{...getFloatingProps()}
|
|
className="actor-popover"
|
|
>
|
|
{hintText}
|
|
</div>
|
|
)}
|
|
</>
|
|
);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Update `GameRow` to pass hint props**
|
|
|
|
In `assets/react/controllers/GameRow.jsx`, update the component signature (line 9):
|
|
|
|
```jsx
|
|
export default function GameRow({ actorName, pos, colStart, totalWidth, hintType, hintText }) {
|
|
```
|
|
|
|
Update the `ActorPopover` usage (line 33):
|
|
|
|
```jsx
|
|
<ActorPopover hintType={hintType} hintText={hintText} />
|
|
```
|
|
|
|
- [ ] **Step 5: Update `GameGrid` to pass hint props**
|
|
|
|
In `assets/react/controllers/GameGrid.jsx`, update the `GameRow` rendering (lines 27-33):
|
|
|
|
```jsx
|
|
<GameRow
|
|
key={rowIndex}
|
|
actorName={row.actorName}
|
|
pos={row.pos}
|
|
colStart={middle - row.pos}
|
|
totalWidth={width}
|
|
hintType={row.hintType}
|
|
hintText={row.hintText}
|
|
/>
|
|
```
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add assets/ package.json package-lock.json
|
|
git commit -m "feat: replace ? button with hint type icons in ActorPopover"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: Manual end-to-end verification
|
|
|
|
- [ ] **Step 1: Build frontend assets**
|
|
|
|
```bash
|
|
cd /home/thibaud/ltbxd-actorle && npm run build
|
|
```
|
|
|
|
- [ ] **Step 2: Start a new game and verify**
|
|
|
|
Open the app in a browser, start a new game. Verify:
|
|
- Each row has an icon (film, masks, or trophy) instead of "?"
|
|
- Clicking the icon opens a popover with the hint text
|
|
- Different rows can have different hint types
|
|
- Award hints show the format "Nom du prix (année)"
|
|
|
|
- [ ] **Step 3: Final commit if any adjustments needed**
|