Samuel Bouchet
bd1763f372
Delete autonomous_plan.md (fully shipped), PLAN_playtest.md (all P1-P7 done), PLAN_missions.md and PLAN_leveldesign.md (partial — engine done, UI polish + 3 final missions + recurring demands + transformer visuals remain). The surviving TODO list lives in docs/PLAN.md. Also add the 6-step dev loop to CLAUDE.md (take next topic → implement → tests → UI test → docs → commit).
217 lines
8 KiB
Markdown
217 lines
8 KiB
Markdown
# Chessistics
|
||
|
||
Jeu de logistique sur échiquier en Godot 4 / C#. Le joueur place des pièces
|
||
d'échecs sur un plateau ; elles se déplacent automatiquement et transportent
|
||
des ressources entre des productions et des demandes.
|
||
|
||
Voir [`CLAUDE.md`](CLAUDE.md) pour l'architecture (black-box simulation) et
|
||
les conventions internes.
|
||
|
||
## Arborescence
|
||
|
||
```
|
||
Chessistics/
|
||
├─ Scripts/ # Code Godot (présentation)
|
||
│ ├─ Automation/ # Harness autonome (CLI --automation=<dir>)
|
||
│ ├─ Board/ Input/ UI/ Pieces/ Presentation/
|
||
│ └─ Main.cs
|
||
├─ chessistics-engine/ # Moteur pur .NET, sans Godot
|
||
├─ chessistics-tests/ # Tests unitaires xUnit (sans Godot)
|
||
├─ Data/
|
||
│ ├─ campaigns/ # campaign_01.json (7 missions)
|
||
│ └─ levels/ # niveaux legacy
|
||
├─ tools/automation/ # Harness Python stdlib pour piloter Godot
|
||
├─ .devcontainer/ # Image Docker + firewall + Xvfb + Godot Linux
|
||
├─ Scenes/ icon.svg project.godot …
|
||
```
|
||
|
||
## Lancer le jeu (poste Windows direct)
|
||
|
||
Prérequis : Godot 4.6 mono + .NET 9 SDK installés localement.
|
||
|
||
```powershell
|
||
dotnet build Chessistics.csproj
|
||
"C:\Apps\godot\Godot_v4.6.2-stable_mono_win64.exe" --path .
|
||
```
|
||
|
||
Tests headless du moteur :
|
||
|
||
```powershell
|
||
dotnet test chessistics-tests/
|
||
```
|
||
|
||
Smoke test du harness d'automatisation :
|
||
|
||
```powershell
|
||
python tools/automation/smoke.py
|
||
```
|
||
|
||
## Dev container autonome (recommandé pour Claude Code)
|
||
|
||
Le dossier `.devcontainer/` contient une image Docker qui embarque :
|
||
|
||
- **.NET SDK 9.0** (build + tests)
|
||
- **Godot 4.6.2-stable mono Linux x86_64** sous `/opt/godot/godot`
|
||
- **Xvfb** + Mesa software GL pour un framebuffer virtuel 1280×720
|
||
- **Python 3** pour le harness d'automatisation
|
||
- **Claude Code** installé automatiquement (`@anthropic-ai/claude-code`)
|
||
- Un firewall `iptables` qui restreint les sorties réseau à une allow-list
|
||
(GitHub, npm, Anthropic, NuGet, Sentry, Statsig)
|
||
|
||
Claude Code, lancé à l'intérieur, peut donc compiler le projet, exécuter
|
||
les tests, **démarrer une vraie instance de Godot en headless** et lire les
|
||
captures PNG produites — sans dépendance Windows.
|
||
|
||
### Option 1 — Docker Desktop + terminal Windows (le plus simple)
|
||
|
||
1. Installer [Docker Desktop pour Windows](https://www.docker.com/products/docker-desktop/).
|
||
Docker Desktop utilise WSL2 en coulisses ; aucune configuration WSL
|
||
manuelle n'est nécessaire.
|
||
2. Installer la CLI devcontainers :
|
||
|
||
```powershell
|
||
npm install -g @devcontainers/cli
|
||
```
|
||
|
||
3. Depuis PowerShell ou Terminal Windows, à la racine du repo :
|
||
|
||
```powershell
|
||
cd C:\Projets\Chessistics
|
||
devcontainer up --workspace-folder .
|
||
devcontainer exec --workspace-folder . zsh
|
||
```
|
||
|
||
La première commande construit l'image (long le premier coup : Godot +
|
||
.NET à télécharger). La seconde ouvre un shell interactif dans le
|
||
container.
|
||
|
||
4. Dans le container :
|
||
|
||
```bash
|
||
dotnet build Chessistics.csproj
|
||
python3 tools/automation/smoke.py
|
||
claude # lance Claude Code inside the container
|
||
```
|
||
|
||
### Option 2 — VS Code + extension Dev Containers
|
||
|
||
1. Installer Docker Desktop + [VS Code](https://code.visualstudio.com/) +
|
||
l'extension **Dev Containers**.
|
||
2. Ouvrir le dossier du repo dans VS Code.
|
||
3. Palette de commandes → `Dev Containers: Reopen in Container`.
|
||
4. Le terminal intégré est déjà dans le container. Lancer `claude` pour
|
||
démarrer Claude Code.
|
||
|
||
### Option 3 — WSL2 natif (plus performant si Docker Desktop rame)
|
||
|
||
Les bind-mounts Docker Desktop sur `C:\` sont plus lents qu'un fichier
|
||
stocké directement dans le système de fichiers WSL2. Pour un gros projet
|
||
c'est négligeable, mais si la lenteur devient visible :
|
||
|
||
1. Installer WSL2 + Ubuntu depuis le Microsoft Store.
|
||
2. Cloner le repo **à l'intérieur** de WSL2 (pas sur `/mnt/c/`) :
|
||
|
||
```bash
|
||
cd ~ && git clone <url> chessistics && cd chessistics
|
||
```
|
||
|
||
3. Installer Docker dans WSL2 (via `docker.io` apt ou Docker Desktop avec
|
||
intégration WSL2 activée).
|
||
4. Installer la CLI devcontainers :
|
||
|
||
```bash
|
||
npm install -g @devcontainers/cli
|
||
devcontainer up --workspace-folder .
|
||
devcontainer exec --workspace-folder . zsh
|
||
```
|
||
|
||
Avantage : I/O disque natif Linux. Inconvénient : pas d'accès Explorer
|
||
direct aux fichiers (`\\wsl$\Ubuntu\home\…`).
|
||
|
||
### Vérifier que tout fonctionne dans le container
|
||
|
||
```bash
|
||
dotnet --version # -> 9.0.x
|
||
godot --version # -> 4.6.2.stable.mono.official.*
|
||
dotnet test chessistics-tests/ # 102/102
|
||
python3 tools/automation/smoke.py # Godot boots, PNG screenshots written
|
||
ls .automation_runs/smoke/screens/ # 01_loaded.png, 02_placed.png, ...
|
||
```
|
||
|
||
Le harness Python détecte automatiquement Linux et enveloppe Godot dans
|
||
`xvfb-run`. Aucune variable d'environnement à positionner.
|
||
|
||
### Mode YOLO (`--dangerously-skip-permissions`)
|
||
|
||
Dans le container, tu peux lancer Claude Code sans prompt de confirmation à
|
||
chaque action :
|
||
|
||
```bash
|
||
claude --dangerously-skip-permissions
|
||
```
|
||
|
||
Avec ce flag Claude **n'affiche plus de "Allow this tool use? (y/n)"** avant
|
||
chaque appel d'outil (Bash, Edit, Write, etc.). Il agit en continu.
|
||
|
||
Pourquoi c'est raisonnable **dans ce container précis** :
|
||
|
||
| Frontière | Protection |
|
||
|-----------|-----------|
|
||
| Ton OS Windows, `C:\Users\…`, `~/.ssh`, autres projets | Inaccessibles — seul `/workspace` est bind-mounté |
|
||
| Réseau sortant | `iptables` en DROP par défaut ; allow-list : GitHub, npm, Anthropic, NuGet, Sentry, Statsig. Le reste est REJECTé |
|
||
| Privilèges | Claude tourne en user `node` (UID 1000), pas root. `sudo` whitelisté **uniquement** pour `init-firewall.sh` |
|
||
| Secrets | Aucun `~/.ssh`, `~/.aws`, cookies navigateur ou `.env` système montés |
|
||
|
||
Risques résiduels à garder en tête :
|
||
|
||
- **Perte de travail non committé dans `/workspace`.** Le mount est
|
||
read-write, donc un `rm -rf` ou un `git reset --hard` écrase tes fichiers
|
||
locaux. **Commit fréquemment** — c'est la seule garantie contre la perte.
|
||
- **Exfiltration via les domaines autorisés.** GitHub reste joignable : un
|
||
Claude compromis pourrait créer un gist public ou pousser sur un fork. Si
|
||
tu veux réduire ce vecteur, ne fais pas `gh auth login` dans le container,
|
||
ou utilise un PAT fine-grained limité à ce seul repo.
|
||
- **Capabilities `NET_ADMIN`/`NET_RAW`.** Actives pour le container (requis
|
||
par iptables). Exploitables uniquement via root, qui n'est pas accessible
|
||
à Claude en utilisation normale.
|
||
- **Pas de limites CPU/RAM.** Un process qui part en vrille peut saturer ta
|
||
machine jusqu'au prochain `docker stop`. Pas dramatique, juste gênant.
|
||
|
||
Ce que tu **ne risques pas** même en YOLO :
|
||
- Perte de données en dehors du projet
|
||
- Accès à tes autres dépôts, credentials personnelles, réseau domestique
|
||
- Modification de ton OS Windows
|
||
|
||
En pratique, le scénario à éviter : tu as des modifs locales importantes
|
||
non-pushées et Claude fait un `git reset --hard HEAD`. Donc : `git commit`
|
||
avant de lancer un long run autonome.
|
||
|
||
### Personnaliser la version de Godot
|
||
|
||
L'image par défaut pose Godot 4.6.2-stable. Pour changer, modifier
|
||
l'argument de build :
|
||
|
||
```jsonc
|
||
// .devcontainer/devcontainer.json
|
||
"build": {
|
||
"args": {
|
||
"GODOT_VERSION": "4.7.0-stable"
|
||
}
|
||
}
|
||
```
|
||
|
||
Puis `devcontainer up --workspace-folder . --build-no-cache`.
|
||
|
||
## Dépannage
|
||
|
||
| Symptôme | Cause probable | Fix |
|
||
|----------|----------------|-----|
|
||
| `godot --version` donne *no such file* | PATH non mis à jour | `source /etc/profile` ou relancer le shell |
|
||
| Screenshot tout noir | Aucun DISPLAY + pas d'xvfb | Vérifier `which xvfb-run` ; utiliser `godot-xvfb` au lieu de `godot` directement |
|
||
| `dotnet restore` bloque | Firewall bloque `api.nuget.org` | Vérifier que `init-firewall.sh` s'est bien exécuté avec les changements récents |
|
||
| Build Docker échoue au download de Godot | Réseau restreint côté hôte | Retry, ou installer Godot manuellement et commenter les lignes correspondantes |
|
||
| Claude Code demande confirmation à chaque action | Comportement normal hors YOLO | Voir la section *Mode YOLO* ci-dessus |
|
||
|
||
## Licence
|
||
|
||
Voir les fichiers du repo.
|