Chessistics/README.md

# 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.

Voir [`autonomous_plan.md`](autonomous_plan.md) pour le design détaillé.

### 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.

### 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 `--dangerously-skip-permissions` | Comportement normal en container sandbox | Accepter si tu es conscient du modèle de confiance |

## Licence

Voir les fichiers du repo.