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.

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

Licence

Voir les fichiers du repo.