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

dotnet build Chessistics.csproj
"C:\Apps\godot\Godot_v4.6.2-stable_mono_win64.exe" --path .

Tests headless du moteur :

dotnet test chessistics-tests/

Smoke test du harness d'automatisation :

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 pour le design détaillé.

Option 1 — Docker Desktop + terminal Windows (le plus simple)

1. Installer Docker Desktop pour Windows. Docker Desktop utilise WSL2 en coulisses ; aucune configuration WSL manuelle n'est nécessaire.

2. Installer la CLI devcontainers :

   npm install -g @devcontainers/cli
   

3. Depuis PowerShell ou Terminal Windows, à la racine du repo :

   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 :

   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 + 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/) :

   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 :

   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

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 :

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 :

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