# Bellerive — notes pour Claude Code

Ville 3D (style « maquette » isométrique) habitée par des agents IA, inspirée d'autopolis.city, améliorée en continu par une équipe d'agents bâtisseurs dont chaque proposition est validée par Jérôme via un aperçu 3D. Jérôme travaille en français : réponses et interface en français.

## Commandes
- `npm install` puis `npm start` → http://localhost:8080 (ville), /chantier.html (panneau Chantier), /bloc-test.html (prototype du style réaliste)
- `npm run reset` → repart d'une ville neuve (efface `data/`)
- `python3.11 tools/make_assets.py public/models` → régénère les modèles 3D (.glb) ; nécessite Blender en module Python (`pip install bpy==4.5.4`, Python 3.11) ou Blender : `blender -b -P tools/make_assets.py -- public/models`
- Config dans `.env` (voir `.env.example`) : clé Anthropic, ADMIN_TOKEN, budget quotidien, vitesse du temps. Sans clé → mode simulé.

## Astra City (Unreal Engine 5.8) — `unreal/AstraCity/`
Version « simulation 3D » demandée par Jérôme : ville Astra City en C++ Unreal (tout est généré en code, pas de Blueprint).
- Compiler : `"/Users/Shared/Epic Games/UE_5.8/Engine/Build/BatchFiles/Mac/Build.sh" AstraCityEditor Mac Development -project="$PWD/AstraCity.uproject"`
- Lancer : `UnrealEditor.app/Contents/MacOS/UnrealEditor AstraCity.uproject -game -windowed -ResX=1600 -ResY=900` (options : `-starthour=20`, `-timescale=5`, `-autoshots` = captures auto dans `Saved/Screenshots/MacEditor/` puis fermeture).
- Assets : `Scripts/setup_assets.py` (matériaux M_City / M_CityGlass / M_CityLeaf + carte) et `Scripts/import_models.py`, lancés via `UnrealEditor ... -run=pythonscript -script=...`. Modèles Blender préparés par `Scripts/blender_prepare.py` (fusion en un maillage) → `SourceAssets/*.glb`.
- Code : `CityGameMode` (ville, simulation, trajets, vues), `CityBuilding` (façades + intérieurs par type d'étage + postes), `CityAgent` (agents articulés + voitures), `CityPlayerController` (caméra), `CityHUD` (surcouche légère), `CityMaterials` (palette).
- Piège : un clic de souris dans la fenêtre pendant `-autoshots` fausse les captures.

## Architecture
- `server/index.js` : HTTP + WebSocket (`/ws`), API `/api/state`, `/api/agent/:id`, `/api/chantier/*`, `/api/preview/:id` (protégées par ADMIN_TOKEN, en-tête `x-admin-token`).
- `server/sim.js` : habitants. Règles pour le quotidien (sommeil, travail, repas, déplacements, argent) + Claude (Haiku) pour le plan du matin, les conversations, les souvenirs et les « envies ». Repli automatique sur les règles quand le budget est atteint.
- `server/builders.js` : équipe Chantier (Urbaniste → Architecte 3D → Contrôleur), propositions dans `data/proposals/`. Mode simulé = modèles préécrits (`MOCK_BUILDINGS`).
- `server/validate.js` : **seul point d'entrée** des données produites par l'IA (dimensions, collisions, porte libre, lits, pièces 3D). Rien n'est exécuté : l'IA ne produit que du JSON.
- `server/world.js` : emplacements (spots), portes, grille de navigation A* (résolution 0,5).
- `server/catalog.js` : vocabulaire commun (meubles, objets, limites) partagé par validateur, prompts et rendu.
- `server/seed.js` : ville de départ (9 pâtés, 11 bâtiments, 6 terrains libres L1–L6, 14 habitants).
- `public/js/render.js` + `public/js/app.js` : rendu Three.js actuel (style stylisé, primitives). `public/js/chantier.js` : panneau Chantier.
- `public/bloc-test.html` : prototype du **style réaliste** validé par Jérôme (textures procédurales, GTAO + bloom, fin d'après-midi, bâtiments modernes, modèles Blender dans `public/models/`).
- Données persistées dans `data/` (city.json, residents.json, state.json, budget.json, proposals/, history/).

## Décisions de Jérôme
- Rendu type jeu vidéo isométrique (esprit Habbo), mais **3D moderne et réaliste** comme le bloc test (image de référence : quartier moderne, toits-terrasses végétalisés, pistes cyclables, lumière dorée).
- Habitants IA via serveur 24h/24 + clé API Anthropic, avec plafond de budget.
- Équipe Chantier en continu, **aucune construction sans validation** : aperçu 3D (Avant/Après) puis Valider / Refuser / Refaire avec remarques.
- Hébergement visé : VPS (KVM conseillé, 2 vCPU / 4 Go / Ubuntu 24.04), sous-domaine + HTTPS, pm2 + reverse proxy (WebSocket `/ws`). Il possède aussi un serveur WHM en root.
- Préfère que Claude modifie directement les fichiers du projet.

## Prochaines étapes
1. Porter le style du bloc test dans la vraie ville (`render.js`) : kit de façades modernes (voir `building()` dans bloc-test.html), modèles Blender instanciés, post-traitement, ambiance jour/soir/nuit liée à l'horloge du serveur.
2. Remplacer les personnages de `render.js` par `person.glb` (parties articulées : legL/legR/armL/armR, matériaux Shirt/Pants/Skin/Hair/Shoes recolorés).
3. Apprendre le nouveau kit à l'Architecte 3D (catalog.js + prompt `SYSTEM_ARCHITECT` + validate.js) pour que ses propositions aient le style réaliste.
4. Déploiement sur le VPS dès que Jérôme fournit IP, sous-domaine et accès SSH par clé (jamais de mot de passe ni de clé privée dans le chat).

## Pièges connus
- Les feuilles des arbres .glb sont en mode BLEND → forcer `alphaTest`, `transparent = false` et **`depthWrite = true`** sinon elles disparaissent.
- Sur une page publiée comme artefact claude.ai, pas de fetch `data:`/`blob:` : modèles servis en JSON `{glb: base64}` et décodés dans la page.
- Validateur : les meubles d'extérieur (`terrace_table`) doivent être dans la cour devant la façade (bâtiment collé au fond du terrain).