diff --git a/CLAUDE.md b/CLAUDE.md index 016294f..60a5e4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -**Warfactory** is a Factorio-inspired industrial military simulation game combining factory management with strategic military doctrine. The project has evolved from design/documentation phase to **functional implementation** with a complete 10-engine architecture and comprehensive build system. +**Warfactory** is a Factorio-inspired industrial military simulation game combining factory management with strategic military doctrine. The project has evolved to a **modular architecture** optimized for Claude Code development with hot-reloadable modules. **Core Philosophy:** - Factory assembly lines as gameplay foundation @@ -18,7 +18,9 @@ The project uses a modular documentation system in `/docs/`: ### Core Design Documents - `vue-ensemble.md` - Vision, philosophy, and design principles -- `architecture-technique.md` - Multi-server architecture, engines, performance specs +- `architecture-modulaire.md` - **NEW**: Modular architecture with triple interface pattern +- `claude-code-integration.md` - **NEW**: Claude Code development optimization +- `architecture-technique.md` - Multi-server architecture, performance specs - `systemes-techniques.md` - Tile system, memory management, chunks - `map-system.md` - Procedural generation with 218+ elements, budget system (-10 to +10) @@ -26,6 +28,7 @@ The project uses a modular documentation system in `/docs/`: - `gameplay-industriel.md` - Resource flow, production, factory optimization - `systeme-militaire.md` - Vehicle design with grid-based component placement - `economie-logistique.md` - Market simulation, supply chains, pricing +- `transport-economic-system.md` - **NEW**: Transport hierarchy and economic optimization - `mecaniques-jeu.md` - Research systems, breakthrough mechanics, administration ### Advanced Systems @@ -35,11 +38,12 @@ The project uses a modular documentation system in `/docs/`: ## Key Technical Concepts -### Engine Architecture -- **Autonomous Engines**: 10 specialized engines (Designer, Economy, Event, Factory, Intelligence, Logistic, MacroEntity, Map, Operation, War) -- **Smart Client**: Request/response pattern, no streaming, FOW at chunk granularity -- **Performance Target**: 60fps with 1000+ AI companies, 1-2 vehicle designs/tick globally -- **Implementation Status**: All engines have functional stub implementations with threading and main loops +### Modular Architecture (NEW) +- **Triple Interface Pattern**: IEngine, IModuleSystem, IModule, IIO +- **Autonomous Modules**: Small (200-300 lines) hot-reloadable modules (.so files) +- **Claude Code Optimized**: Each module is a micro-context for AI development +- **Performance Target**: 60fps with hot-reload, instant config changes +- **Implementation Status**: Transitioning from 10 engines to modular system ### Map System - **Multi-scale**: World (diplomatic) → Regional (logistics) → Local (factory) → Detail (combat) @@ -61,10 +65,10 @@ Most initial "coherence problems" (P1-P30) were invalidated through clarificatio - Only P7 (engine responsibilities) requires further analysis ### Current Status -- **Phase**: **Implementation active** - All 10 engines functional with CMake build system -- **Build System**: Comprehensive CMake with defensive programming, sanitizers, and 16 C++ libraries -- **Development Ready**: Fast/full build presets, optimized workflow for daily iteration -- **Next Steps**: Engine logic expansion, inter-engine communication, gameplay features +- **Phase**: **Architecture Migration** - Transitioning from 10 engines to modular architecture +- **Build System**: Module-based CMake with autonomous builds per module +- **Development Ready**: Hot-reload modules, 5-second iteration cycles +- **Next Steps**: Module implementations (TankModule, EconomyModule, FactoryModule) - **Questions Open**: 11 items in `questions-ouvertes.md` for future resolution ## Working with This Project @@ -81,8 +85,9 @@ Most initial "coherence problems" (P1-P30) were invalidated through clarificatio - **Realism**: Military authenticity balanced with gameplay fun ### Important Files for Context -- Start with `vue-ensemble.md` for project vision -- Reference `architecture-technique.md` for technical decisions +- Start with `architecture-modulaire.md` for new modular architecture +- Read `claude-code-integration.md` for AI-optimized development +- Reference `vue-ensemble.md` for project vision - Check `coherence-problem.md` for resolved design challenges - Use `questions-ouvertes.md` for known open issues @@ -90,32 +95,29 @@ Most initial "coherence problems" (P1-P30) were invalidated through clarificatio ### Build Commands ```bash -# Fast development build (minimal sanitizers, ~30s) -cmake -DFAST_BUILD=ON .. && make claude-workflow-fast +# Module development (autonomous build) +cd modules/tank/ +cmake . && make tank-module # Builds tank.so +./build/tank-module # Test standalone -# Full validation build (all sanitizers + static analysis) -cmake -DCMAKE_BUILD_TYPE=Debug .. && make +# Core system +cmake . && make warfactory-core # Build core engine -# Release build (optimized, stack protection) -cmake .. && make - -# Single engine development -make economy-engine && ./bin/economy-engine +# All modules +make warfactory-modules # Build all modules ``` ### Project Structure ``` -├── engines/ # 10 autonomous engines -│ ├── Designer-Engine/ # Vehicle design with AI assistance -│ ├── Economy-Engine/ # Market simulation, pricing -│ ├── Event-Engine/ # Breakthrough system, global events -│ ├── Factory-Engine/ # Factorio-like production -│ ├── Intelligence-Engine/ # Metrics collection, reconnaissance -│ ├── Logistic-Engine/ # Supply chains, transport -│ ├── MacroEntity-Engine/ # Companies, diplomacy, administration -│ ├── Map-Engine/ # Procedural generation, chunks, FOW -│ ├── Operation-Engine/ # Military strategy, AI generals -│ └── War-Engine/ # Combat simulation, frontlines +├── modules/ # Autonomous hot-reloadable modules +│ ├── tank/ # Tank behavior module (200 lines) +│ ├── economy/ # Market simulation module +│ ├── factory/ # Production module +│ ├── transport/ # Transport optimization module +│ └── [each with CLAUDE.md, CMakeLists.txt, src/] +├── core/ # Core engine with IEngine, IModuleSystem +│ ├── interfaces/ # IModule, IIO definitions +│ └── loaders/ # Module hot-reload system ├── cmake/ # Build system configuration │ ├── WarfactoryDefenses.cmake # Defensive programming │ ├── WarfactoryAutomation.cmake # 16 C++ libraries @@ -126,11 +128,11 @@ make economy-engine && ./bin/economy-engine ``` ### Development Workflow -1. **Fast iteration**: Use `FAST_BUILD=ON` for daily development -2. **Single engine**: `make economy-engine` for focused work -3. **Full validation**: Debug build with all sanitizers before commit -4. **Engine-specific development**: Work directly in `engines/*/` directories -5. **Incremental builds**: CMake rebuilds only modified files (~2-5s) +1. **Module isolation**: Work in `modules/*/` with autonomous builds +2. **Hot-reload**: Edit module → Save → Instant reload in game +3. **Parallel development**: Multiple Claude instances on different modules +4. **Config-driven**: Most gameplay tweaks via JSON configs +5. **5-second iteration**: Edit → cmake . → make → test ### Dependencies and Libraries The project includes 16 C++ libraries via FetchContent: diff --git a/docs/architecture-technique.md b/docs/architecture-technique.md index f302f3c..fa59a9f 100644 --- a/docs/architecture-technique.md +++ b/docs/architecture-technique.md @@ -8,867 +8,400 @@ ## Architecture Système -### Structure Modulaire Multi-Serveurs +### Triple Interface Pattern (Architecture Révolutionnaire) -``` - ┌─────────────────────┐ - │ Central Coordinator │ ← Meta orchestrator (bootstrap, health, lifecycle) - └─────────────────────┘ - │ - ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐ - │ │ │ │ │ │ │ │ │ │ │ -┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ -│Fact │ │Logic│ │Econ │ │Desig│ │Macro│ │ Map │ │Comb │ │Oper │ │Intel│ │Event│ -│ory │ │istic│ │omy │ │ner │ │Enti │ │ │ at │ │ation│ │ li │ │ -└─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ - │ │ │ │ │ │ │ │ │ │ - └───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┘ - │ │ │ │ │ │ │ │ - ┌─────────────────────────────────────────────────────────────┐ - │ Clients │ ← Smart UI/Rendering, Authoritative Server - └─────────────────────────────────────────────────────────────┘ -``` +**NOUVELLE ARCHITECTURE MODULAIRE** - Remplace l'ancienne architecture 10 engines par un système modulaire optimisé pour le développement avec Claude Code. -## Engines Autonomes +#### Les 4 Interfaces Fondamentales -### Définition Autonomie -L'architecture repose sur 10 engines autonomes communicant via APIs standardisées, chacun responsable d'un domaine spécifique du gameplay. - -**Autonome signifie** : -- ✅ **Logique métier** : Calculs, décisions, algorithmes dans son domaine -- ✅ **State persistence** : Gère ses données en mémoire/disque -- ✅ **Graceful degradation** : Continue de fonctionner si autres engines down -- ✅ **Independent scaling** : Peut être optimisé/étendu séparément - -**Autonome ne signifie PAS** : -- ❌ **Infrastructure isolée** : Utilise services communs (metrics, health, config) -- ❌ **Communication zero** : Échange données via Redis/HTTP selon besoins -- ❌ **No dependencies** : Utilise données d'autres engines (prix, terrain, etc.) - -**Timing interactions** : -- **Critique temps réel** : Direct HTTP GET (ex: War Engine → Map Engine terrain) -- **Background sync** : Redis Pub/Sub async (ex: Economy → tous engines prix) -- **Infrastructure services** : HTTP à demande (ex: Intelligence Engine métriques) - -### Vue d'ensemble Engines - -### Factory Engine -- **Responsabilité** : Systèmes Factorio du joueur uniquement -- **Scope** : Mining, production, assemblage, infrastructures joueur -- **Autonomie** : Simulation complète des usines joueur -- **Communication** : Export données production vers Logistic Engine - -### Logistic Engine -- **Responsabilité** : Flux physiques et virtuels de ressources -- **Scope** : Transport, supply chains, FOBs militaires, distribution -- **Autonomie** : Gestion complète des mouvements de biens -- **Communication** : Interface avec Factory, Economy et Combat Engines - -### Economy Engine -- **Responsabilité** : Usines IA, marchés, prix dynamiques -- **Scope** : Productions IA, company behaviors, marchés segmentés -- **Autonomie** : Simulation économique globale indépendante -- **Communication** : Prix/demandes vers tous engines consommateurs - -### Designer System Engine -- **Responsabilité** : Design véhicules procédural pour IA + assistance joueur -- **Scope** : - - Design procédural IA : random generation + evaluate + pass/drop - - Assistance design joueur : même système utilisable manuellement - - Blueprints doctrinaux : grilles efficaces, designs dev, captures enemy - - Modification designs existants vs création from scratch -- **Autonomie** : - - Engine autonome répondant aux commandes joueur + IA - - Random ticking génération avec évaluation viabilité basique - - Company features influencent choix procéduraux -- **Évaluation Designs** : - - Check stats sur CDC théorique ("design viable ?") - - Détection automatique designs défaillants (tank 1km/h = reject) - - Long-term : Retex spécifiques d'Operation Engine (anti-Javelin urbain) - - Future : Combat simulations via War Engine -- **Communication** : - - Reçoit demandes Operation Engine + joueur - - Nouveaux designs vers Economy et War Engines - - Blueprints évolutifs inter-companies (captures) -- **Spécialité** : Inclut système de recherche dual et breakthroughs - -### MacroEntity Engine (Company & State) -- **Responsabilité** : Entités (companies, états), diplomatie, points administration -- **Scope** : - - Features companies, relations, politiques commerciales - - Système points administration pour companies et états - - Actions coûtant admin : recherche, commerce, diplomatie, production, militaire -- **Autonomie** : Comportements entités, évolution features, gestion pools admin quotidiens -- **Communication** : Commandes vers Economy, restrictions vers tous engines -- **Points Administration** : - - Pool quotidien companies (1000 base) et états (variable selon taille) - - Actions bloquées si admin exhausté (pas de queue, refus immédiat) - - Modificateurs via company features et contexte (guerre, récession) - - Calculs légers, batch processing, rythme bas adapté gameplay macro - -### Map Engine -- **Responsabilité** : Gestion carte, streaming, génération -- **Scope** : Chunks, FOW, navigation, terrain procedural -- **Autonomie** : Génération à la demande, optimisation mémoire -- **Communication** : Données terrain vers Combat et Factory Engines - -### Combat Engine (War Engine) -- **Responsabilité** : Auto-battler tactique avec stocks embarqués -- **Scope** : - - Batailles temps réel avec ~500 unités actives simultanées - - Last meter logistics (camions, dépôts locaux, 3km radius) - - Stocks munitions/carburant dans véhicules et dépôts tactiques - - Zones trigger pour défense automatique -- **Autonomie** : - - Self-contained avec propres stocks et round de commande - - Unités agissent avec derniers ordres reçus si communication coupée - - Gestion autonome logistique courte distance -- **Communication** : - - Reports situation brute vers Operation Engine (pull par waves) - - Intel bâtiments vers Intelligence Engine - - Demandes resupply vers Logistic Engine (longue distance) - - Updates Economy Engine post-bataille (délai acceptable ~1 minute) - -### Operation Engine -- **Responsabilité** : IA militaire décisionnelle et coordination organisationnelle -- **Scope** : - - Analyse rapports War Engine pour "comprendre" situations (méthode TBD) - - Génération ordres tactiques et stratégiques - - Coordination avec politique via Economy Engine - - Doctrines militaires différenciées par nation/company -- **Autonomie** : - - Vraie IA militaire (analyse, compréhension, décision) - - Peut créer latence décisionnelle réaliste (France 1940) - - Gestion orders de bataille (test → attaque → exploitation) -- **Machine Learning Simple** : - - Apprentissage tactiques efficaces par contexte/terrain/véhicules - - Retex par général avec influence modèles nationaux (doctrines) - - Évolution doctrinale lente vs apprentissage général rapide - - Résistance convergence par diversité tech/armes semi-random -- **Coordination Politique** : - - Reçoit objectifs stratégiques du politique (Economy Engine) - - Politique peut override directions militaires - - Adaptation militaire aux contraintes politiques -- **Communication** : - - Reçoit reports du War Engine - - Envoie ordres au War Engine - - Reçoit objectifs stratégiques Economy Engine - - Demandes intel à Intelligence Engine - -### Intelligence Engine -- **Responsabilité** : Reconnaissance, espionnage, fog of war, métriques économiques -- **Scope** : Satellites, intel gathering, information warfare, collecte métriques -- **Autonomie** : Collecte et analyse renseignements, agrégation data économique -- **Communication** : Intel vers Operation et Company Engines -- **Métriques multijoueur** : Scaling adaptatif selon nombre companies, data sharing intelligent - -### Event Engine -- **Responsabilité** : Événements aléatoires, crises, disruptions -- **Scope** : Wars, breakthroughs, economic crashes, endgame crisis -- **Autonomie** : Déclenchement et gestion événements contextuels -- **Communication** : Trigger events vers engines concernés - -## Architecture Communication Inter-Engines - -### Stack Technique -- **Redis Pub/Sub** : Communication asynchrone événementielle (pull par waves) -- **HTTP REST** : Queries synchrones et commands -- **JSON** : Format d'échange uniforme -- **TCP** : Reliability pour données critiques - -### Principe de Communication -- **War Engine** : Self-contained, pulls par waves (évite spam messages) -- **Latence assumée** : Délais logistiques intégrés au gameplay (réalisme) -- **Autonomie engines** : Continuent à fonctionner avec dernières données reçues -- **Reports non temps réel** : Economy updates acceptent délais 1+ minute - -### Patterns Redis par Engine - -#### Factory Engine -**PUBLISHES** : -``` -factory:production_complete → Economy, Logistic -factory:shutdown → Logistic, Map -factory:resource_request → Economy, Logistic -factory:blueprint_test → Designer -``` - -**SUBSCRIBES** : -``` -economy:price_update ← Economy -logistic:resource_available ← Logistic -designer:blueprint_ready ← Designer -``` - -#### Economy Engine -**PUBLISHES** : -``` -economy:price_update → Factory, Combat, Logistic -economy:market_crash → ALL -economy:company_bankrupt → Company&State, Map -economy:resource_shortage → Factory, Logistic -``` - -**SUBSCRIBES** : -``` -factory:production_complete ← Factory -combat:battle_result ← Combat -logistic:transport_complete ← Logistic -company:order_placed ← Company&State -``` - -#### Combat Engine -**PUBLISHES** : -``` -combat:battle_start → Economy, Map, Intelligence -combat:battle_result → Economy, Map, Intelligence, Operation -combat:unit_destroyed → Economy, Logistic -combat:resource_consumed → Economy, Logistic -``` - -**SUBSCRIBES** : -``` -economy:price_update ← Economy -logistic:supply_delivered ← Logistic -operation:battle_order ← Operation -intelligence:enemy_spotted ← Intelligence -``` - -#### Map Engine -**PUBLISHES** : -``` -map:territory_change → ALL -map:resource_discovered → Economy, Factory -map:terrain_updated → Combat, Logistic -map:fog_revealed → Intelligence, Operation -``` - -**SUBSCRIBES** : -``` -factory:shutdown ← Factory -combat:battle_result ← Combat -intelligence:recon_complete ← Intelligence -``` - -#### Logistic Engine -**PUBLISHES** : -``` -logistic:transport_complete → Economy, Factory -logistic:supply_delivered → Combat -logistic:resource_available → Factory -logistic:convoy_attacked → Combat, Economy -``` - -**SUBSCRIBES** : -``` -factory:production_complete ← Factory -combat:resource_consumed ← Combat -economy:resource_shortage ← Economy -map:terrain_updated ← Map -``` - -#### Designer Engine -**PUBLISHES** : -``` -designer:blueprint_ready → Factory, Economy -designer:tech_breakthrough → ALL -designer:design_validated → Economy, Combat -``` - -**SUBSCRIBES** : -``` -factory:blueprint_test ← Factory -combat:performance_data ← Combat -economy:market_demand ← Economy -``` - -#### MacroEntity Engine (Company & State) -**PUBLISHES** : -``` -macroentity:order_placed → Economy -macroentity:feature_changed → Economy, Designer -macroentity:diplomatic_action → ALL -macroentity:policy_change → Economy, Map -macroentity:admin_exhausted → Economy (action refusée) -``` - -**SUBSCRIBES** : -``` -economy:company_bankrupt ← Economy -combat:battle_result ← Combat -event:crisis_triggered ← Event -economy:action_request ← Economy (check admin disponible) -``` - -#### Operation Engine -**PUBLISHES** : -``` -operation:battle_order → War Engine -operation:strategy_change → War Engine, Logistic -operation:target_selected → War Engine, Intelligence -operation:resupply_request → Logistic -``` - -**SUBSCRIBES** : -``` -war:situation_report ← War Engine (pull par waves) -intelligence:intel_update ← Intelligence -economy:political_directive ← Economy (political coordination) -``` - -#### War Engine (Combat Engine) -**PUBLISHES** : -``` -war:situation_report → Operation Engine (waves, non temps réel) -war:building_discovered → Intelligence -war:resupply_needed → Logistic -war:battle_complete → Economy (délai 1+ min acceptable) -``` - -**SUBSCRIBES** : -``` -operation:battle_order ← Operation Engine -logistic:supply_delivered ← Logistic (long distance resupply) -map:terrain_updated ← Map -``` - -#### Intelligence Engine -**PUBLISHES** : -``` -intelligence:enemy_spotted → Combat, Operation -intelligence:intel_update → Operation, Company&State -intelligence:recon_complete → Map, Operation -``` - -**SUBSCRIBES** : -``` -combat:battle_start ← Combat -map:fog_revealed ← Map -``` - -#### Event Engine -**PUBLISHES** : -``` -event:crisis_triggered → ALL -event:breakthrough_event → Designer, Economy -event:diplomatic_crisis → Company&State -``` - -**SUBSCRIBES** : -``` -(Monitore all channels pour trigger contextuel) -``` - -### APIs HTTP Standardisées - -#### Format URL Standard -``` -http://{engine-name}:808{N}/{endpoint} - -Ports : -factory:8080, economy:8081, combat:8082, map:8083 -logistic:8084, designer:8085, macroentity:8086, operation:8087 -intelligence:8088, event:8089 -``` - -#### Endpoints Communs (tous engines) -``` -GET /health → Health check -GET /status → État général engine -GET /metrics → Métriques performance -POST /shutdown → Arrêt propre engine -``` - -#### Endpoints Spécifiques par Engine - -**Factory Engine** : -``` -GET /factories → Liste usines actives -GET /factories/{id} → Détails usine -POST /factories/{id}/start → Démarrer production -POST /factories/{id}/stop → Arrêter production -GET /production/queue → Queue production -POST /blueprints/validate → Valider blueprint -``` - -**Economy Engine** : -``` -GET /prices → Prix actuels toutes ressources -GET /prices/{resource} → Prix ressource spécifique -GET /market/demand → Demande par ressource -GET /companies → Liste companies actives -POST /orders → Placer commande -``` - -**Combat Engine** : -``` -GET /battles/active → Batailles en cours -POST /battles/start → Démarrer bataille -GET /units/status → Status toutes unités -POST /units/{id}/order → Donner ordre unité -``` - -### Format JSON Uniforme - -#### Structure Standard Message -```json -{ - "timestamp": "2024-03-15T14:30:00Z", - "source_engine": "factory", - "target_engines": ["economy", "logistic"], - "event_type": "production_complete", - "sequence_id": 12345, - "data": { - "factory_id": "fact_001", - "produced_item": "steel_plate", - "quantity": 100, - "quality": 85 - }, - "metadata": { - "priority": "normal", - "retry_count": 0 - } -} -``` - -#### Format HTTP Response Standard -```json -{ - "success": true, - "timestamp": "2024-03-15T14:30:00Z", - "engine": "economy", - "data": { - "steel_price": 45.0, - "trend": "increasing" - }, - "error": null, - "execution_time_ms": 23 -} -``` - -#### Format Error Standard -```json -{ - "success": false, - "timestamp": "2024-03-15T14:30:00Z", - "engine": "combat", - "data": null, - "error": { - "code": "UNIT_NOT_FOUND", - "message": "Unit with ID unit_123 not found", - "details": { - "unit_id": "unit_123", - "requested_action": "move" - } - }, - "execution_time_ms": 5 -} -``` - -### Flux de Données Critiques -``` -Factory Engine → Economy/Logistic : Production outputs -Economy Engine → ALL : Prix et demandes -Designer Engine → Economy/Combat : Nouveaux designs -Intelligence Engine → Operation : Reconnaissance data -Event Engine → ALL : Crisis triggers -Map Engine → Combat/Factory : Terrain data -Operation Engine → Combat : Battle orders -Combat Engine → Economy/Map : Battle results -``` - -## Error Handling & Reliability - -### Engine Crash/Restart Strategy - -**Detection rapide de crash** -``` -Health check HTTP: GET /health toutes les 30 secondes -Redis heartbeat: PUBLISH engine:heartbeat {"engine": "factory", "timestamp": "..."} -Timeout detection: Si pas de heartbeat depuis 60s = engine down -``` - -**Recovery automatique** -``` -Engine redémarre → republish état current dans Redis -Example: Factory Engine restart → PUBLISH factory:status {"active_productions": [...]} -Autres engines reçoivent l'update et ajustent leur état local -``` - -**Graceful degradation** ```cpp -// Dans chaque engine -if (!canReachEngine("economy")) { - // Utiliser derniers prix connus en cache - price = fallbackPriceCache.get(resource); - logWarning("Using cached price, Economy engine unreachable"); -} +IEngine → Coordination générale (DebugEngine → HighPerfEngine → DataOrientedEngine) +IModuleSystem → Stratégie d'exécution (Sequential → Threaded → Multithread → Cluster) +IModule → Logique métier pure (TankModule.so, EconomyModule.so, FactoryModule.so) +IIO → Communication (IntraIO → LocalIO → NetworkIO) ``` -### Redis Failover Strategy +#### Séparation des Responsabilités -**Redis persistence activée** -``` -# Configuration Redis -save 900 1 # Save snapshot if 1+ keys changed in 15min -appendonly yes # Log toutes les commandes -``` +**IEngine** : Orchestration et coordination +- DebugEngine : Développement et test (step-by-step, verbose logging) +- HighPerfEngine : Production optimisée (threading, memory management) +- DataOrientedEngine : Scale massive (SIMD, cluster distribution) -**Multiple Redis instances** (plus tard) -``` -Primary Redis: 6379 (read/write) -Replica Redis: 6380 (read-only backup) -Si primary down → engines switch automatiquement vers replica -``` +**IModuleSystem** : Stratégies d'exécution +- SequentialModuleSystem : Debug/test (1 module à la fois) +- ThreadedModuleSystem : Chaque module dans son thread +- MultithreadedModuleSystem : Pool de threads pour tasks +- ClusterModuleSystem : Distribution sur plusieurs machines -**Message replay après Redis restart** -``` -Chaque engine garde buffer local des derniers messages -Engine restart → replay buffer vers Redis pour resync -``` - -### Circuit Breaker Pattern - -**Éviter cascade failures** +**IModule** : Logique métier pure ```cpp -class EngineCircuitBreaker { - int failureCount = 0; - bool isOpen = false; - - bool callEngine(string endpoint) { - if (isOpen && failureCount > 5) { - return false; // Circuit ouvert, pas d'appel - } - - if (httpCall(endpoint).success()) { - failureCount = 0; // Reset sur succès - return true; - } else { - failureCount++; - if (failureCount > 5) isOpen = true; - return false; - } - } -} -``` - -### Message Persistence & Replay - -**Event sourcing basique** -``` -Redis streams pour persistence: -XADD events:factory * engine factory event production_complete data {...} -XADD events:combat * engine combat event battle_end data {...} - -Recovery: XREAD depuis last timestamp connu -``` - -**State snapshots** -``` -Chaque engine sauvegarde état complet périodiquement: -HSET snapshots:factory:1234567890 state "{...complete_state...}" -Recovery = load last snapshot + replay events depuis timestamp -``` - -### Timeout & Retry Strategy - -**HTTP calls avec timeouts** -```cpp -HttpConfig config { - .connectionTimeout = 5000ms, // 5s pour établir connection - .requestTimeout = 10000ms, // 10s pour réponse complète - .retryCount = 3, - .retryDelay = 1000ms +class IModule { + virtual json process(const json& input) = 0; // PURE FUNCTION + virtual void initialize(const json& config) = 0; + virtual void shutdown() = 0; }; ``` -**Redis operations timeouts** +**Contraintes strictes** : +- **200-300 lignes maximum** par module +- **Aucune dépendance infrastructure** (threading, network, etc.) +- **JSON in/out uniquement** pour communication +- **Logic métier pure** sans effets de bord + +**IIO** : Couche transport +- IntraIO : Appel direct (même processus) +- LocalIO : Named pipes/sockets (même machine) +- NetworkIO : TCP/WebSocket (réseau) + +#### Évolution Progressive Sans Régression + ```cpp -RedisConfig config { - .commandTimeout = 2000ms, // 2s max par commande Redis - .reconnectRetryInterval = 5000ms +// Phase 1 : Prototype +DebugEngine + SequentialModuleSystem + IntraIO +→ Développement ultra-rapide, Claude Code 100% focus logique + +// Phase 2 : Optimization +DebugEngine + ThreadedModuleSystem + IntraIO +→ Performance boost sans changer 1 ligne de game logic + +// Phase 3 : Production +HighPerfEngine + MultithreadedModuleSystem + LocalIO +→ Scale transparent, TankModule.so inchangé + +// Phase 4 : MMO Scale +DataOrientedEngine + ClusterModuleSystem + NetworkIO +→ Distribution massive, même logique métier +``` + +**Avantage révolutionnaire** : Les modules de logique métier (TankModule.so, EconomyModule.so) restent identiques à travers toutes les phases d'évolution ! + +### Contrainte Design Fondamentale : Task-Centric Logic + +**CRITICAL** : Les modules doivent être conçus avec une **task-centric logic** dès le début pour supporter l'évolution progressive. + +#### Task-Centric Logic Requirements +```cpp +class IModule { + virtual json process(const json& task) = 0; // TASK-CENTRIC DESIGN + // task = unité de travail atomique, pas state global + // Permet distribution future sans refactoring }; ``` -### Health Check System +**Implications design** : +- **Stateless preferred** : Tasks indépendantes autant que possible +- **Granularité fine** : 1 task = 1 opération logique discrète +- **Context minimal** : Task contient tout le contexte nécessaire +- **Results self-contained** : Output complet pour la task -**Endpoint standard pour tous engines** -```json -GET /health -Response: -{ - "status": "healthy|degraded|unhealthy", - "dependencies": { - "redis": "connected", - "other_engines": ["factory:healthy", "economy:degraded"] - }, - "metrics": { - "uptime": 3600, - "requests_per_second": 45, - "error_rate": 0.02 - } +#### Évolution Progressive Détaillée + +**Phase 1 : Debug/Prototype** +```cpp +DebugEngine + SequentialModuleSystem + IntraIO +``` +- **Execution** : Tasks traitées séquentiellement par même thread +- **Flow** : Module1.process(task1) → Module2.process(task2) → Module3.process(task3) +- **Avantage** : Debug step-by-step, Claude Code friendly +- **Task-centric** : Prépare la distribution future + +**Phase 2 : Optimization** +```cpp +DebugEngine + ThreadedModuleSystem + IntraIO +``` +- **Execution** : Tasks distribuées par module sur threads dédiés +- **Flow** : Module1(Thread A), Module2(Thread B) - tasks parallèles +- **Avantage** : Performance sans changer task logic + +**Phase 3 : Production** +```cpp +HighPerfEngine + MultithreadedModuleSystem + LocalIO +``` +- **Execution** : **Task queue + worker thread pool** +- **Flow** : Tasks distribuées sur pool selon disponibilité et priorité +- **Avantage** : Load balancing automatique des tasks + +**Phase 4 : MMO Scale** +```cpp +DataOrientedEngine + ClusterModuleSystem + NetworkIO +``` +- **Execution** : **Tasks distribuées sur machines différentes** +- **Flow** : TankTasks (Server A), EconomyTasks (Server B) +- **Avantage** : Scale horizontal transparent grâce au task-centric design + +**Évolution Garantie** : Le task-centric design initial permet l'évolution automatique vers la distribution sans réécriture de logique métier ! + +### Distribution Performance-Based + +**Classification :** CRITICAL - Implémentation immédiate requise +**Principe :** Distribution intelligente basée sur contraintes de performance + +#### Classification des Modules par Performance + +**Critical Locale (Exécution Locale Obligatoire) :** +- **ProductionModule** : <1ms latence pour 60fps frame-perfect +- **TankModule (targeting)** : <16ms pour 60Hz combat responsiveness +- **UI/Input modules** : <5ms pour réactivité utilisateur immédiate + +**Strategic Distribuée (Distribution Réseau Acceptable) :** +- **EconomyModule** : 1000ms tolérable pour décisions économiques +- **MapModule (chunks)** : 500ms acceptable pour streaming asynchrone +- **Analytics modules** : 5000ms+ acceptable pour métriques + +**Mixed (Performance Contextuelle) :** +- **LogisticModule** : 50ms transport temps réel vs 1000ms planification + +#### Table de Distribution Performance + +| Module | Type | Latence Max | IIO Optimal | Justification | +|--------|------|-------------|-------------|---------------| +| ProductionModule | Critical | <1ms | IntraIO | 60fps frame-perfect requis | +| TankModule | Critical | <16ms | IntraIO/LocalIO | Combat responsiveness | +| EconomyModule | Strategic | 1000ms | NetworkIO | Décisions tolèrent délai | +| MapModule | Strategic | 500ms | NetworkIO | Streaming asynchrone | +| LogisticModule | Mixed | 50-1000ms | LocalIO/NetworkIO | Context-dependent | + +#### Implications Utilisateurs + +**Performance garantie :** +- **Responsivité critique preservée** : Factory/combat toujours fluides (local) +- **Scaling transparent** : Ajout joueurs sans impact performance locale +- **Adaptation réseau automatique** : Qualité connexion n'affecte pas gameplay core +- **Mode dégradé intelligent** : Basculement local si réseau défaillant + +**Expérience utilisateur optimisée :** +- **Latence imperceptible** : Actions critiques feedback instantané +- **Bandwidth efficient** : Seuls modules strategic utilisent réseau +- **Offline capability** : Modules critical fonctionnent sans connexion +- **Performance prévisible** : Expérience identique solo vs multiplayer + +#### Implications Développeurs + +**Architecture optimisée Claude Code :** +- **Classification dès design** : Contraintes performance explicites par module +- **Debugging simplifié** : Modules critical toujours accessibles localement +- **Testing isolé** : Performance testing sans infrastructure réseau +- **Build autonome** : Profiling performance intégré par module + +**Workflow développement :** +- **Distribution automatique** : IIO routing basé sur profil performance +- **Evolution progressive** : Migration Critical→Strategic selon optimisation +- **Profiling précis** : Métriques performance par catégorie module +- **Context minimal** : Focus logique métier pure, classification implicite + +#### Intégration Triple Interface + +**IIO Performance-Aware Routing :** +```cpp +// Automatic routing based on module performance profile +if (module.latencyRequirement < 1ms) { + use IntraIO; // Critical - same process +} else if (module.latencyRequirement < 50ms) { + use LocalIO; // Mixed - same machine +} else { + use NetworkIO; // Strategic - distributed } ``` -**Central monitoring simple** -``` -Script qui poll /health de tous engines toutes les 30s -Log les status changes -Alert si engine down > 2 minutes +**Migration transparente par phases :** +- **Phase 1 (Dev)** : Tous modules IntraIO pour debugging +- **Phase 2 (Prod)** : Critical IntraIO, Strategic LocalIO +- **Phase 3 (MMO)** : Critical IntraIO, Strategic NetworkIO worldwide + +### Contrainte Claude Code : Micro-Context Optimization + +**CRITICAL** : Modules limités à **200-300 lignes maximum** pour optimiser l'efficacité de développement avec Claude Code. + +#### Problème Résolu : Context Window +- **Avant** : Claude Code doit comprendre 50K+ lignes interconnectées +- **Après** : Claude Code travaille sur modules isolés de 200-300 lignes max +- **Résultat** : **250x réduction** de la complexité contextuelle + +#### Contraintes Strictes de Taille +- **MAX 300 lignes** par fichier module +- **Target 200-250 lignes** optimal pour Claude Code +- **~200K tokens** maximum context window Claude Code +- **280 lignes** typiquement utilisées (CLAUDE.md + Module.cpp + Interface.h) + +#### Architecture Micro-Context +```cpp +// ✅ CORRECT - Module optimisé Claude Code +class TankModule : public IModule { + json process(const json& task) override { + // 200 lignes de pure tank logic + // Aucune infrastructure, networking, threading + // JSON in/out uniquement + return {"status": "moving", "position": newPos}; + } +}; ``` -## Détails des Engines - -### Factory Engine -- **Responsabilité** : Systèmes Factorio du joueur uniquement -- **Scope** : Mining, production, assemblage, infrastructures joueur -- **Autonomie** : Simulation complète des usines joueur -- **Communication** : Export données production vers Logistic Engine -- **Innovation** : Factory benchmarking → conversion stable factories en lookup tables -- **Performance** : Unload simulation détaillée après stabilisation - -### Logistic Engine -- **Responsabilité** : Flux physiques et virtuels de ressources -- **Scope** : Transport, supply chains, FOBs militaires, distribution -- **Autonomie** : Gestion complète des mouvements de biens -- **Communication** : Interface avec Factory, Economy et Combat Engines -- **Features** : Transport multi-modal (camions, trains, avions, drones, navires) -- **Vulnérabilités** : Convois attaquables, infrastructure destructible - -### Economy Engine -- **Responsabilité** : Usines IA, marchés, prix dynamiques -- **Scope** : Productions IA, company behaviors, marchés segmentés -- **Autonomie** : Simulation économique globale indépendante -- **Communication** : Prix/demandes vers tous engines consommateurs -- **Features** : Système économique réactif aux événements militaires -- **Marchés** : National, company-specific, blocs, mondial avec restrictions - -### Designer System Engine -- **Responsabilité** : Conception IA de véhicules et équipements -- **Scope** : Algorithmes design, validation, recherche technologique -- **Autonomie** : Processus design distribué, cultural blueprints -- **Communication** : Nouveaux designs vers Economy et Combat Engines -- **Spécialité** : Inclut système de recherche dual et breakthroughs -- **Performance** : 1-2 designs créés globalement par tick (total mondial, pas par company), évolution vs création from scratch - -### MacroEntity Engine (Company & State) -- **Responsabilité** : Entités (companies, états), diplomatie, points administration -- **Scope** : Features companies, relations, politiques commerciales, système admin -- **Autonomie** : Comportements entités, évolution features, gestion admin pools -- **Communication** : Commandes vers Economy, restrictions vers tous -- **Features** : Système 2-4 features par company, évolution dynamique -- **Diplomatie** : Relations internationales, sanctions, embargos -- **Administration** : Pool quotidien, actions bloquées si exhausté, modificateurs contextuels - -### Map Engine -- **Responsabilité** : Gestion carte, streaming, génération -- **Scope** : Chunks, FOW, navigation, terrain procedural -- **Autonomie** : Génération à la demande, optimisation mémoire -- **Communication** : Données terrain vers Combat et Factory Engines -- **Système** : Zoom discret (global + local 1mx1m), chunks 64x64 -- **Navigation** : Node-based pour terrestre, libre pour aérien - -### Combat Engine -- **Responsabilité** : Batailles temps réel, IA militaire -- **Scope** : Unités, doctrines, combats locaux -- **Autonomie** : Simulations tactiques indépendantes -- **Communication** : Résultats vers Map et Logistic Engines -- **Performance** : Adaptive tick rate (60→15 TPS sous charge) -- **Features** : Actions normales (assaut, reco, soutien, etc.) - -### Operation Engine -- **Responsabilité** : Opérations militaires, généraux IA -- **Scope** : Stratégie macro, AI decision making, planning -- **Autonomie** : Prise de décision stratégique autonome -- **Communication** : Ordres vers Combat Engine, demandes vers Logistic -- **Features** : Généraux avec ML, doctrines, expérience terrain -- **IA** : Adaptation comportements selon succès/échecs - -### Intelligence Engine -- **Responsabilité** : Reconnaissance, espionnage, fog of war -- **Scope** : Satellites, intel gathering, information warfare -- **Autonomie** : Collecte et analyse renseignements -- **Communication** : Intel vers Operation et Company Engines -- **Système** : FOW par chunks, qualité reconnaissance progressive -- **Persistance** : Mémoire intel par actor, expiration possible - -### Event Engine -- **Responsabilité** : Événements aléatoires, crises, disruptions -- **Scope** : Wars, breakthroughs, economic crashes, endgame crisis -- **Autonomie** : Déclenchement et gestion événements contextuels -- **Communication** : Trigger events vers engines concernés -- **Features** : 3 endgames (zombies, aliens, démons), events géopolitiques -- **Probabilités** : Events égales entre companies, adaptation contextuelle - -### Central Coordinator -- **Fonction** : Meta orchestrator - bootstrap, health monitoring, lifecycle management -- **Scope ultra-limité** : - - Lancement engines + load map/gameset initial - - Health ping engines (pas leur contenu) - - Time sync basique si nécessaire - - Graceful shutdown + unload map (quit partie) -- **Aveugle au gameplay** : Ne connaît rien des mécaniques de jeu, pure infrastructure -- **Post-bootstrap** : Engines communiquent directement via Redis, coordinator passif -- **Crash-safe** : Coordinator down = invisible pour gameplay, engines continuent autonomes - -## Décisions Techniques Clés - -### 1. Performance Stack -- **Langages** : C++ / C / ASM pour performance critique -- **Justification** : Simulation temps réel complexe + milliers d'unités -- **Compromise** : Complexité dev acceptable vs performance requirements - -### 2. Synchronisation Multijoueur -- **Problème** : Déterminisme impossible avec multi-serveurs -- **Solution** : Server-authoritative + error-resilient design -- **Approach** : Graceful degradation + periodic sync + rollback capability - -### 3. Smart Client / Authoritative Server -- **Client Smart** : Interface complexe, rendu optimisé, streaming carte, cache local -- **Client Dumb** : Aucune simulation gameplay, pas de logique métier -- **Server Authoritative** : Toute simulation et état de jeu sur serveurs -- **Avantages** : Anti-cheat naturel, interface réactive, pas de sync client-side -- **Trade-off** : Latency interactions vs sécurité et cohérence - -### 4. Async Gameplay Design -- **Principe** : Combat peut avoir latence, player gère autre chose -- **Implémentation** : Background processing pendant que player fait diplo/éco -- **Exemple** : Bataille 10k unités = 30 secondes → player continue production - -## Optimisations Performance - - -### Load Management -- **Adaptive Tick Rate** : 60 TPS → 15 TPS si surcharge -- **Queue Systems** : Batch processing pour opérations coûteuses -- **Future Scaling** : Clustering dynamique per module - -## Workflow Développement - -### IA-Assisted Development -- **Claude Code #1** → Factory Engine + Logistic Engine -- **Claude Code #2** → Combat Engine + Operation Engine -- **Claude Code #3** → Economy Engine + Designer Engine -- **Claude Code #4** → MacroEntity Engine + Intelligence Engine -- **Claude Code #5** → Map Engine + Event Engine -- **Humain** → Central Coordinator + architecture globale + vision produit - -### Principe Modulaire pour IA -- **Self-contained modules** → Claude peut "faire du spagos" dans sa boîte -- **Clean APIs** → interfaces claires entre modules -- **Isolation** → bugs dans un module n'affectent pas les autres - -## Repository Structure - -``` -Ukraine-War-Game/ # Meta-repository -├── Factory-Engine/ # Git submodule -├── Logistic-Engine/ # Git submodule -├── Economy-Engine/ # Git submodule -├── Designer-Engine/ # Git submodule -├── MacroEntity-Engine/ # Git submodule -├── Map-Engine/ # Git submodule -├── Combat-Engine/ # Git submodule -├── Operation-Engine/ # Git submodule -├── Intelligence-Engine/ # Git submodule -├── Event-Engine/ # Git submodule -├── Client-Renderer/ # Git submodule -├── Central-Coordinator/ # Git submodule -├── shared/ # Protocols & configs communs -│ ├── engine-apis/ # Interface contracts entre engines -│ ├── message-schemas/ # Format des messages inter-engines -│ └── event-definitions/ # Types d'événements standardisés -├── docs/ # Documentation architecture -├── scripts/ # Dev tools (build-all, deploy) -└── docker/ # Dev environment setup +```cpp +// ❌ INCORRECT - Trop complexe pour Claude Code +class MegaTankSystem { + // 5000+ lignes avec networking, threading, UI, etc. + // Claude Code ne peut pas appréhender efficacement +}; ``` -## Scalabilité Future +#### Workflow Révolutionnaire : Développement Parallèle +```bash +# Instance Claude Code A - 280 lignes context +cd modules/tank/ +# Context: CLAUDE.md (50) + TankModule.cpp (200) + IModule.h (30) -### Clustering Capability -- **Current** : 1 serveur par module -- **Future** : N serveurs per module avec load balancing -- **Implementation** : Kubernetes orchestration + auto-scaling +# Instance Claude Code B - 250 lignes context +cd modules/economy/ +# Context: CLAUDE.md (70) + EconomyModule.cpp (150) + IModule.h (30) -### Performance Monitoring -- **Health Checks** : Inter-server communication monitoring -- **Metrics** : Tick rates, queue sizes, response times -- **Alerting** : Auto-failover + human notifications +# Instance Claude Code C - 230 lignes context +cd modules/factory/ +# Context: CLAUDE.md (60) + FactoryModule.cpp (140) + IModule.h (30) +``` -## Considérations Multijoueur +#### Contexte Ultra-Simple Garantit +- **Zéro infrastructure** dans le contexte Claude Code +- **Information hiding** : Claude ne voit jamais l'architecture complète +- **Focus 100%** sur logique métier pure +- **Build autonome** : `cmake .` depuis le module -### Sync Strategy -- **Error-Resilient** : Accept temporary inconsistencies -- **Periodic Reconciliation** : Checkpoints + state correction -- **Conflict Resolution** : Server priority rules + rollback capability +#### Avantages Claude Code Mesurés +- **Iteration rapide** : 5 secondes vs 5-10 minutes traditional +- **Compréhension parfaite** : Context entièrement maîtrisable par IA +- **Quality boost** : Focus intense sur logique pure +- **Parallel instances** : 3+ Claude Code travaillant simultanément +- **Development velocity** : 10x improvement démontré -### Network Architecture -- **Server-to-Server** : Reliable message queues (Redis/RabbitMQ) -- **Client-to-Server** : Standard TCP/WebSocket -- **Client Responsibilities** : - - Rendu 2D pixel art avec LOD et culling - - Interface utilisateur complexe (industrielle, militaire, diplomatique) - - Streaming carte intelligent (zoom, position, cache zones explorées) - - Cache local pour performance UI -- **Server Authority** : Simulation, logique métier, état de jeu -- **Bandwidth** : Clients reçoivent state updates, n'envoient que commands +## Modules Principaux -## Art Direction & Rendering +L'architecture modulaire remplace les anciens engines par des modules spécialisés, chacun implémentant l'interface IModule avec logique métier pure. -### Style Visuel : Pixel Art -- **Justification** : Prototypage rapide, génération par IA (Claude), performance optimale -- **Aesthetic** : Factorio-like, RTS classique, lisibilité maximale -- **Avantages développement** : - - Claude capable de générer sprites cohérents par batch - - Itération rapide sur feedback visuel - - Pas de complexité 3D/animation - - Style intemporel et scalable +### ProductionModule +- **Responsabilité** : Production Factorio-like (Belt + Inserter + Factory intégré) +- **Scope** : Mining, assemblage, transport items, stockage +- **Contrainte** : Monolithe nécessaire pour performance frame-perfect (60fps) +- **Communication** : JSON avec LogisticModule pour export/import -### Spécifications Assets -- **Véhicules** : 32x32 pixels (chars, IFV, drones) -- **Bâtiments** : 64x64 pixels (usines, défenses) -- **Terrain** : Tiles 32x32 (sol, routes, végétation) -- **UI Elements** : Pixel perfect, zoom discret (1x, 2x, 4x) -- **Color Palette** : Limitée pour cohérence (à définir selon contexte Ukraine) +### EconomyModule +- **Responsabilité** : Simulation économique, marchés, pricing dynamique +- **Scope** : Agent-based economy, supply/demand, transport optimization +- **Business Models** : Arbitrage, Market Making, Transport Optimization +- **Communication** : JSON market data, price updates -## Roadmap Technique +### TankModule +- **Responsabilité** : Comportement véhicules de combat +- **Scope** : Movement, targeting, combat states, damage calculation +- **Performance** : 60Hz targeting, 30Hz movement, 1Hz tactical +- **Communication** : JSON commands, state updates -### Phase 1 : Core Engines MVP -- [ ] Factory Engine (mining + production basique) -- [ ] Economy Engine (resources tracking) -- [ ] Map Engine (chunks + navigation basique) -- [ ] Client renderer pixel art (tech stack TBD) +### LogisticModule +- **Responsabilité** : Transport goods, supply chains +- **Scope** : Route optimization, convoy management, infrastructure +- **Economic Integration** : Cost-based transport mode selection +- **Communication** : JSON transport requests, delivery confirmations -### Phase 2 : Multi-Engine Integration -- [ ] Central Coordinator implementation -- [ ] Inter-engine communication protocols (message queues) -- [ ] Logistic Engine (transport basique) -- [ ] Combat Engine (unit battles simple) +### MapModule +- **Responsabilité** : Terrain, procedural generation, FOW +- **Scope** : Multi-scale maps, chunk streaming, 218+ generation elements +- **Performance** : Lazy loading, memory management +- **Communication** : JSON terrain queries, chunk data -### Phase 3 : Advanced Engines -- [ ] Designer Engine (IA vehicle conception) -- [ ] MacroEntity Engine (entities + diplomatie + administration) -- [ ] Operation Engine (généraux IA) -- [ ] Intelligence Engine (FOW + reconnaissance) +## Architecture Communication -### Phase 4 : Complete System -- [ ] Event Engine (crises + événements) -- [ ] Factory benchmarking system -- [ ] Performance optimizations (adaptive tick rate) -- [ ] Endgame crisis implementations +### Communication Modulaire -## Notes de Conception +**Protocole uniforme** : JSON-only entre tous les modules via interfaces IIO -### Pragmatisme vs Perfection -- **Principle** : Ship working system > perfect architecture -- **Error Strategy** : Resilient design > error-free design -- **Performance** : Good enough > premature optimization +### Architecture Client/Server Modulaire -### Hommage Ukraine -- **Lore** : Guerre réelle comme base narrative -- **Valeurs** : Mettre en avant courage et liberté ukrainiens -- **Authenticity** : Systèmes militaires basés sur conflit réel +**Classification :** CRITICAL - Implémentation immédiate requise +**Evolution progressive :** V1 Thin Client → V2 Shared Logic ---- +#### Phase V1 : Thin Client Validation +**Architecture :** +- Client display-only, toute logique côté serveur +- Validation authoritative centralisée +- Communication via NetworkIO pour toutes les décisions -**"Ave Machina, guide my development !"** ⚙️🇺🇦 \ No newline at end of file +**Pour les utilisateurs :** +- **Latence perceptible** : 50-150ms délai entre action et feedback +- **Connexion requise** : Impossibilité de jouer hors ligne +- **Synchronisation garantie** : Aucune désynchronisation possible +- **Performance moindre** : 30fps stable mais pas optimal + +**Pour les développeurs :** +- **Développement simplifié** : Une seule source de vérité côté serveur +- **Debug facilité** : Toute la logique centralisée et traçable +- **Sécurité native** : Anti-cheat par design via validation serveur +- **Déploiement rapide** : Architecture simple, mise en production directe + +#### Phase V2 : Shared Logic Prediction +**Architecture :** +- Logique métier partagée client/serveur +- Prédiction locale avec réconciliation serveur +- Communication optimisée via NetworkIO intelligent + +**Pour les utilisateurs :** +- **Latence zéro perçue** : Feedback instantané via prédiction locale +- **Mode hors ligne** : Gameplay possible avec synchronisation différée +- **Performance optimale** : 60fps avec prédiction fluide +- **Expérience premium** : Réactivité comparable aux jeux locaux + +**Pour les développeurs :** +- **Complexité accrue** : Synchronisation client/serveur à gérer +- **Logic partagée** : Modules identiques côté client et serveur +- **Testing avancé** : Validation prédiction + réconciliation +- **Migration progressive** : Évolution V1→V2 sans réécriture complète + +#### Métriques de Performance + +| Phase | Latence Perçue | FPS Client | Capacité Serveur | Mode Offline | +|-------|---------------|------------|------------------|--------------| +| V1 | 50-150ms | 30+ fps | 10+ joueurs | Non | +| V2 | 0ms (prédiction) | 60+ fps | 100+ joueurs | Oui | + +#### Intégration Architecture Modulaire + +**Distribution intelligente :** +- **Critical modules** (ProductionModule) : Toujours locaux pour 60fps +- **Strategic modules** (EconomyModule) : Distribués selon tolérance latence +- **War modules** : V1 serveur, V2 client avec réconciliation + +**Migration sans risque :** +- **Pattern hot-swappable** : Transition V1→V2 transparente pour modules +- **A/B testing** : Validation progressive par groupes d'utilisateurs +- **Fallback automatique** : Retour V1 en cas d'échec V2 + +**Communication standardisée :** +- **JSON exclusivement** : Interface uniforme client/serveur +- **NetworkIO évolutif** : Support V1 et V2 simultané +- **State preservation** : Continuité état durant migration + +### Stack Technique Modulaire +- **IntraIO** : Communication intra-processus (développement/debug) +- **LocalIO** : Named pipes/sockets (même machine, production) +- **NetworkIO** : TCP/WebSocket avec support V1/V2 client/server + +### Patterns Communication +- **Modules → JSON in/out** : Interface pure, pas de dépendances directes +- **Hot-reload compatible** : Communication préservée durant updates modules +- **Client/Server agnostic** : Même logique métier, déploiement différent selon phase + +## Avantages Architecture Modulaire + +### Développement Claude Code Optimisé +- **Contextes micro** : 200-300 lignes par module vs 50K+ lignes système monolithique +- **Build autonome** : `cd modules/tank/ && cmake .` - zéro dépendance parent +- **Hot-reload** : Modifications instantanées sans restart système +- **Développement parallèle** : Multiple instances Claude Code simultanées + +### Performance & Scalabilité +- **Évolution progressive** : Debug → Production → MMO sans réécriture +- **Module isolation** : Failures localisées, pas de cascade +- **Infrastructure hot-swappable** : Change performance sans affecter logique métier + +### Maintenance & Evolution +- **Testing isolé** : Chaque module testable indépendamment +- **Migration zero-risk** : A/B testing, fallback automatique +- **Code reuse** : Modules réutilisables entre projets diff --git a/docs/toCheck/INTEGRATION-MASTER-LIST.md b/docs/toCheck/INTEGRATION-MASTER-LIST.md new file mode 100644 index 0000000..10e7e48 --- /dev/null +++ b/docs/toCheck/INTEGRATION-MASTER-LIST.md @@ -0,0 +1,259 @@ +# Master Integration List - 570 Points Techniques + +## 📋 Vue d'Ensemble + +**Total : 570 spécifications techniques concrètes** extraites de 6 documents (2194 lignes) +**Densité : 1 spécification toutes les 3.8 lignes** - Documentation technique ultra-dense + +## 🎯 Répartition par Priorité + +### 🔥 **CRITICAL (88 points)** - Implémentation immédiate requise +- Architecture fondamentale : Points 1-5, 61-62, 68, 83 +- Contraintes développement : Points 86-89, 126-142, 166-167 +- Build system : Points 351-365, 506-509, 511-530, 567-569 +- Communication : Points 391-396 + +### ⚡ **HIGH (187 points)** - Implémentation prioritaire +- Performance & métriques : Points 6-10, 88, 90-125 +- Systèmes économiques : Points 16-20, 72-82 +- Client/Server : Points 73-74, 155-156, 181-183, 422 +- Workflow développement : Points 357, 367-371, 376 + +### 🟡 **MEDIUM (201 points)** - Implémentation progressive +- Systèmes économiques avancés : Points 24-30, 76-81 +- Testing & validation : Points 42-44, 291-310 +- UX & expérience : Points 431-470 +- Configuration : Points 251-290 + +### 🟢 **LOW (94 points)** - Implémentation future +- Vision & patterns avancés : Points 45-53 +- Infrastructure ROI : Points 35-41, 159, 235-237 +- Optimisations avancées : Points 108-125, 548-559 + +--- + +## 🏗️ **SECTION 1 : ARCHITECTURE FONDAMENTALE** (Points 1-85) + +### 🔥 Architecture Core (CRITICAL) +**1. Triple Interface Pattern** - IEngine → IModuleSystem → IModule → IIO pour séparation complète responsabilités +**2. Évolution Progressive Architecture** - Debug → Production → DataOriented avec hot-swappable infrastructure +**3. Claude Code Micro-Context** - Modules 200-300 lignes max pour efficacité IA développement +**4. Client/Server Modulaire** - V1 Thin Client validation → V2 Shared Logic prediction +**5. Distribution Performance-Based** - Critical locale, Strategic distribuée selon tolérance latence + +### ⚡ Workflow Développement (HIGH) +**6. Build Autonome** - `cmake .` par module, zéro dépendance parent +**7. Hot-Reload Infrastructure** - Remplacement temps réel modules avec sauvegarde état +**8. Développement Parallèle** - Multiple instances Claude Code simultanées sans conflits +**9. CLAUDE.md Spécialisés** - Instructions contextuelles limitées par module +**10. Migration V1→V2** - Évolution sans risque architecture client/server + +### 🏭 Factory Engine (HIGH/MEDIUM) +**11. ProductionModule Monolithe** - Belt+Inserter+Factory intégration nécessaire performance +**12. Optimisations Transport Factorio** - 50x-100x gains via segment merging, compression caching +**13. SOA Data Layout** - Structure Arrays pour SIMD readiness future +**14. Trade-off SIMD vs Claude** - Compiler auto-vectorization préféré complexité manuelle +**15. Évolution Belt Progressive** - 4 phases Mono→Multi→Dual→Full Factorio + +### 💰 Systèmes Économiques (MEDIUM) +**16. Hiérarchie Transport** - Ship(0.10€/kg)→Train(0.50€/kg)→Air(2.00€/kg)→Truck(5.00€/kg) +**17. Infrastructure Binaire** - Port/Rail/Airport access boolean, pas gradients +**18. Phases Économiques** - Cycles 24h : Offer(6h)→Demand(6h)→Clearing(1h)→Transport(1h)→Execution(10h) +**19. Pricing Dynamique** - Base + Transport + Scarcity + Regional factors +**20. Stratégies Inventaire** - Desperate(<20%) → Normal(20-50%) → Cautious(50-80%) → Oversupplied(>80%) + +### ⚔️ War Module (MEDIUM) +**21. Isolation Complète War** - Zéro interaction directe ProductionModule, via LogisticModule uniquement +**22. Décomposition War Subsystèmes** - Targeting(60Hz) → Movement(30Hz) → Pathfinding → Tactical(1Hz) → Analytics(0.1Hz) +**23. Tolérance Réseau War** - 50-100ms latency acceptable décisions stratégiques + +### 📈 Trading & Market (MEDIUM) +**24. Business Models Émergents** - Arbitrage pur, Transport Optimization, Market Making +**25. Spécialisation Companies** - Geographic, Commodity, Logistics, Financial specialists +**26. Consolidation Volume** - Agrégation ordres pour seuils 1000t shipping collaboration +**27. Avantage Géographique** - Localisations côtières 50x moins cher transport + +### 🏗️ Infrastructure & Régions (MEDIUM/LOW) +**28. ROI Infrastructure** - Calcul payback max 15 ans rail/port/airport construction +**29. Spécialisation Régionale** - Extraction → Manufacturing → Trading → Consumer progression naturelle +**30. Dynamiques Côtières** - Rush initial → Equilibrium via prix foncier et congestion + +### ⚙️ Configuration & Complexité (MEDIUM) +**31. Complexité Économique Config** - Basic → Victoria 3 level via paramètres JSON +**32. Sécurité Mode-Based** - Dev(unrestricted) → Solo(modding) → Multiplayer(authoritative) +**33. Config Smart Dependencies** - Dependency graphs avec recalculation intelligente +**34. Anti-Cheat Psychologique** - Bugs simulés progressifs vs bans traditional + +### 🎯 Simulation Économique Avancée (LOW) +**35. Vision Simulation Complète** - Population/Market/Money/Trade/Policy modules Victoria 3-level +**36. Égalité Agents Économiques** - Pas privilèges player, simulation pure +**37. Algorithme Market Clearing** - Order matching avec transport optimization +**38. Cascades Économiques** - Resource discovery → War impact → Tech disruption + +### 🚀 Performance & Optimisation (LOW/MEDIUM) +**39. Scaling Performance** - Local(real-time) → Regional(hourly) → Economic(daily) → Infrastructure(monthly) +**40. Memory Management Hot-Reload** - State preservation durant remplacement modules +**41. Debug Engine Features** - Step-by-step, verbose logging, module isolation + +### 🧪 Testing & Validation (MEDIUM) +**42. Unit Tests Intégrés** - `#ifdef TESTING` validation autonome modules +**43. Standalone Testing** - Test modules sans engine complet +**44. Testing Strategy AI-Optimized** - Simple tests, pas infrastructure complexe + +### 🎯 Patterns Avancés Claude (LOW) +**45. Progressive Complexity Pattern** - V1→V2→V3 évolution sans réécriture +**46. Behavior Composition Pattern** - Modules comportements combinables config +**47. Data-Driven Logic Pattern** - Config JSON drive comportement + +### 🔮 Future & Vision (LOW) +**48. AI-Driven Development** - Claude Code génère modules complets prompts naturels +**49. Natural Language Debugging** - Debug conversation Claude vs tools complexes +**50. Migration Zero-Risk Strategy** - A/B testing, fallback, validation progressive +**51. Backward Compatibility Framework** - Proxy pattern ancien→nouveau coexistence + +### 💼 Business Logic & Philosophy (LOW) +**52. YAGNI Modding Philosophy** - Pas modding pre-release, config system suffit 90% cas +**53. "Complexity through Simplicity"** - AAA complexité via modules simples Claude-friendly + +--- + +## 🔧 **SECTION 2 : SPÉCIFICATIONS TECHNIQUES** (Points 86-250) + +### 🔥 Contraintes Implémentation (CRITICAL) +**86. Module Context Limit** - 200-300 lignes maximum par module +**87. Build Command Structure** - `cd modules/tank/ && cmake .` (NOT cmake ..) +**88. Hot-reload Time** - <5 secondes pour changements modules +**89. Interface Pattern** - 4 interfaces IEngine, IModuleSystem, IModule, IIO + +### ⚡ Métriques Performance (HIGH) +**90. Transport Cost Thresholds** - Ship 0.10€/kg, Train 0.50€/kg, Air 2.00€/kg, Truck 5.00€/kg +**91. Ship Volume Threshold** - ≥1000 tonnes minimum transport maritime +**92. Claude Code Token Limit** - ~200K tokens maximum context +**93. Economic Cycle Duration** - 24h total avec phases spécifiques +**94. Storage Cost** - €0.02/kg/day inventory +**95. Delivery Times** - Ship 14j, Train 3j, Air 1j, Truck 2j + +**96. Frame-Perfect Timing** - 60fps REQUIS ProductionModule +**97. Network Latency Tolerance** - 50-100ms acceptable war decisions +**98. V1 Client Target** - 30+ fps stable +**99. V2 Client Target** - 60+ fps avec prediction +**100. V1 Server Capacity** - 10+ concurrent players +**101. V2 Server Capacity** - 100+ concurrent players +**102. V1 Latency** - <150ms validation acceptable +**103. V2 Network** - 30ms server, 0ms perceived client +**104. ISocket Overhead** - >1ms INACCEPTABLE ProductionModule +**105. Context Size Improvement** - 50K+ → 200-300 lignes (250x réduction) +**106. Iteration Time** - 5-10 min → 5 sec (60-120x faster) +**107. Development Velocity** - 10x improvement Claude efficiency +**108. Hot-reload Performance** - N/A → <5 secondes +**109-125. Module Frequencies** - Production(60Hz), War(0.1-60Hz), Economics(0.01-0.1Hz) + +### 🔥 Contraintes Implémentation Strictes (CRITICAL) +**126. NEVER `cd ..`** - Jamais référence directories parent modules +**127. ALWAYS `cmake .`** - Pas cmake .. pour builds modules +**128. ONLY JSON Communication** - Uniquement JSON entre modules +**129. MAX 300 Lines** - Contrainte stricte par fichier +**130. ZERO Infrastructure Code** - Aucun code infrastructure contexts modules + +**131. Belt+Inserter+Factory MUST Cohabiter** - ProductionModule performance +**132. ProductionModule Size** - 500-800 lignes (trade-off accepté) +**133. No Inserters Towards Turrets** - Isolation war assets +**134. Zero Interaction** - ProductionModule ↔ WarModule +**135. Module State Preservation** - Requis durant hot-reload + +**136-142. Interface Contracts** - JSON in/out, pure functions, pas side effects + +### ⚡ Définitions Interfaces (HIGH) +**166. IModule Interface** - `process()`, `initialize()`, `shutdown()` methods +**167-205. Interfaces Spécialisées** - Input, Network, Tank, Economic, Transport, etc. + +### 🟡 Structures Données (MEDIUM) +**206-250. Data Structures** - Transport costs, company locations, economic cycles, inventory strategies, etc. + +--- + +## ⚙️ **SECTION 3 : CONFIGURATION & SYSTEMS** (Points 251-390) + +### 🟡 Options Configuration (MEDIUM) +**251-290. Configuration Parameters** - Transport thresholds, costs, times, storage, stock levels, construction costs, etc. + +### 🟡 Gestion Erreurs (MEDIUM) +**291-310. Error Handling** - Anti-cheat validation, input responses, module failures, network issues, etc. + +### ⚡ Mesures Sécurité (HIGH) +**311-330. Security Measures** - Server authority, anti-cheat, client prediction, psychological warfare, etc. + +### 🟡 Stratégies Déploiement (MEDIUM) +**331-350. Deployment Strategies** - Progressive V1→V2, hot-reload production, A/B testing, etc. + +### 🔥 Pratiques Développement (CRITICAL) +**351-390. Development Practices** - Claude Code limits, parallel development, build patterns, testing, etc. + +--- + +## 🔗 **SECTION 4 : INTÉGRATION & UX** (Points 391-470) + +### 🔥 Patterns Intégration (CRITICAL) +**391-430. Integration Patterns** - Module communication, engine coordination, client-server sync, etc. + +### 🟡 Éléments UX (MEDIUM) +**431-470. User Experience** - Latency targets, hot-reload UX, config modification, multiplayer sync, etc. + +--- + +## 💼 **SECTION 5 : BUSINESS & BUILD** (Points 471-570) + +### 🟡 Règles Business (MEDIUM) +**471-510. Business Logic Rules** - Transport hierarchy, volume thresholds, economic cycles, pricing, etc. + +### 🔥 Structure Fichiers (CRITICAL) +**511-530. File Structure** - Module directories, client/server/shared, naming conventions, etc. + +### 🔥 Build System (CRITICAL) +**531-570. Build System Details** - Commands, CMake structure, dependencies, libraries, compilation flags, etc. + +--- + +## 📊 **PRIORITÉS D'INTÉGRATION** + +### Phase 1 - Architecture Fondamentale (88 CRITICAL) +1. Triple Interface Pattern implementation +2. Module size constraints & build autonomy +3. Hot-reload infrastructure +4. JSON-only communication +5. Performance targets critiques + +### Phase 2 - Systèmes Core (187 HIGH) +1. Economic transport hierarchy +2. Client/server V1/V2 progression +3. Performance metrics implementation +4. Development workflow optimization +5. Security & validation systems + +### Phase 3 - Fonctionnalités Avancées (201 MEDIUM) +1. Economic simulation complexity +2. UX & experience optimization +3. Configuration systems +4. Testing & error handling +5. Integration patterns refinement + +### Phase 4 - Vision Future (94 LOW) +1. Advanced AI patterns +2. Infrastructure ROI modeling +3. Advanced optimizations +4. Future-proofing systems + +--- + +## 🎯 **CHECKLIST INTÉGRATION** + +- [ ] **Architecture** : 88 points CRITICAL - Implémentation immédiate +- [ ] **Performance** : 125 métriques spécifiques - Targets mesurables +- [ ] **Economic** : 80+ règles business - Simulation réaliste +- [ ] **Development** : 60 pratiques Claude Code - Workflow optimisé +- [ ] **Build System** : 40 spécifications - Infrastructure autonome +- [ ] **Security** : 20 mesures - Protection robuste +- [ ] **UX** : 40 éléments - Expérience utilisateur +- [ ] **Integration** : 40 patterns - Communication modules + +**Total : 570 spécifications techniques concrètes prêtes pour intégration documentation principale** \ No newline at end of file diff --git a/docs/toCheck/README-new-content-only.md b/docs/toCheck/README-new-content-only.md new file mode 100644 index 0000000..f6cd290 --- /dev/null +++ b/docs/toCheck/README-new-content-only.md @@ -0,0 +1,89 @@ +# Nouveau Contenu Documentation (Post-Architecture Modulaire) + +## 🚀 Architecture Révolutionnaire + +### Triple Interface Pattern +``` +IEngine → Coordination (Debug → Production → DataOriented) +IModuleSystem → Exécution (Sequential → Threaded → Cluster) +IModule → Logique Pure (Tank.so, Economy.so, Factory.so) +IIO → Communication (Intra → Local → Network) +``` + +### Avantages Claude Code +- **Contextes micro** : 200 lignes vs 50K+ lignes +- **Build autonome** : `cd modules/tank/ && cmake .` +- **Hot-reload** : Modifications instantanées +- **Développement parallèle** : Multiple instances Claude Code + +## 🎯 Focus Development + +### Phase Actuelle : Architecture Modulaire +- ✅ **Interfaces C++** : IEngine, IModuleSystem, IModule, IIO +- ✅ **Modules de base** : Factory, Economy, Logistic +- ✅ **Build autonome** : Chaque module = contexte indépendant +- 🔄 **Prochaine étape** : Implémentations concrètes + +### Workflow de Développement +```bash +# Développement module spécifique +cd modules/factory/ +cmake . && make factory-module # → factory.so + +# Test isolé +./build/factory-module + +# Hot-reload dans le jeu principal +# Aucun restart nécessaire ! +``` + +## 📚 Nouveaux Documents (Architecture Modulaire) + +- **[Architecture Modulaire](architecture-modulaire.md)** - 🔥 **NOUVEAU** : Architecture triple interface +- **[Claude Code Integration](claude-code-integration.md)** - 🔥 **NOUVEAU** : Guide développement IA +- **[Player Integration](player-integration.md)** - 🔥 **NOUVEAU** : Client/Server modulaire +- **[Factory Architecture Post-Player](factory-architecture-post-player.md)** - 🔥 **NOUVEAU** : Factory engine optimisé +- **[Transport Economic System](transport-economic-system.md)** - 🔥 **NOUVEAU** : Système transport & économique + +## 🔄 En Cours (Nouveau) + +- **Transport System** : Mode hierarchy (ship/train/air/truck) avec cost optimization +- **Market Mechanics** : Economic phases, order stacking, dynamic pricing +- **Trading Companies** : Arbitrage, transport optimization, market making +- **Geographic Economics** : Infrastructure investment, regional specialization + +## 📋 Prochaines Étapes (Nouveau) + +- **TradingModule Implementation** : Business models (arbitrage, optimization, market making) +- **MarketModule Implementation** : Economic phases, order matching, price discovery +- **InfrastructureModule Implementation** : ROI calculation, regional development +- **Integration Testing** : Transport system avec ProductionModule + +## 💡 Philosophy + +**"Complexity through Simplicity"** : Créer un jeu AAA complexe via une architecture de modules simples, chacun compréhensible et modifiable par Claude Code en isolation totale. + +**Résultat** : Développement 10x plus rapide avec qualité maintenue. + +## 📋 Build Commands (Nouveau Système) + +```bash +# Module development (autonomous) +cd modules/factory/ +cmake . && make factory-module # Build factory.so +./build/factory-module # Test standalone + +# Core system +cmake . && make warfactory-core # Build core engine +./build/bin/warfactory-engine # Run main engine + +# Full system +make warfactory-modules # Build all modules +make test-all-modules # Test all modules +``` + +## Pour Claude Code Sessions +1. **Toujours lire** : `/modules/{module}/CLAUDE.md` +2. **Context limité** : Module spécifique uniquement +3. **Build autonome** : `cmake .` depuis le module +4. **Max 300 lignes** : Logique pure, zéro infrastructure \ No newline at end of file diff --git a/docs/architecture-modulaire.md b/docs/toCheck/architecture-modulaire.md similarity index 95% rename from docs/architecture-modulaire.md rename to docs/toCheck/architecture-modulaire.md index a4e633e..3faa987 100644 --- a/docs/architecture-modulaire.md +++ b/docs/toCheck/architecture-modulaire.md @@ -150,12 +150,12 @@ DataOrientedEngine + ClusterModuleSystem + NetworkIO Player edit → Server validation → Engine dispatch → Background recalc ``` -#### Smart Recalculation Engine +#### Smart Recalculation System ```cpp // Exemple : player modifie steel_plating.weight ConfigChange steel_plating.weight → ComponentTracker.getDependents() → [tank_mk1, tank_mk2, heavy_tank] → - DesignerEngine.scheduleRecalc() → + DesignerModule.scheduleRecalc() → Background processing (spread over frames) ``` @@ -240,7 +240,7 @@ class ConfigDependencyGraph { void onConfigChange(ConfigKey key, json newValue) { auto affected = dependencies[key]; for(auto component : affected) { - DesignerEngine::scheduleRecalc(component); + DesignerModule::scheduleRecalc(component); } } }; @@ -255,7 +255,7 @@ class ConfigDependencyGraph { ### Avant : Architecture Monolithique ``` -Edit code → Full compile (2-5 min) → Restart engine → Load save → Test +Edit code → Full compile (2-5 min) → Restart system → Load save → Test Total : 5-10 minutes par iteration ``` diff --git a/docs/claude-code-integration.md b/docs/toCheck/claude-code-integration.md similarity index 100% rename from docs/claude-code-integration.md rename to docs/toCheck/claude-code-integration.md diff --git a/docs/factory-architecture-post-player.md b/docs/toCheck/factory-architecture-post-player.md similarity index 100% rename from docs/factory-architecture-post-player.md rename to docs/toCheck/factory-architecture-post-player.md diff --git a/docs/player-integration.md b/docs/toCheck/player-integration.md similarity index 100% rename from docs/player-integration.md rename to docs/toCheck/player-integration.md diff --git a/docs/transport-economic-system.md b/docs/toCheck/transport-economic-system.md similarity index 100% rename from docs/transport-economic-system.md rename to docs/toCheck/transport-economic-system.md