diff --git a/AlternativesAnalysis.md b/AlternativesAnalysis.md new file mode 100644 index 0000000..bc58082 --- /dev/null +++ b/AlternativesAnalysis.md @@ -0,0 +1,911 @@ +# Analyse des Alternatives Techniques - AISSIA + +**Date:** 27 octobre 2025 +**Contexte:** Analyse comparative de toutes les options techniques discutées pour le développement d'AISSIA + +--- + +## Table des Matières + +1. [Résumé Exécutif](#résumé-exécutif) +2. [Alternatives Backend](#alternatives-backend) +3. [Alternatives Frontend](#alternatives-frontend) +4. [Alternatives Architecture](#alternatives-architecture) +5. [Alternatives Déploiement](#alternatives-déploiement) +6. [Matrice de Décision](#matrice-de-décision) +7. [Décision Finale et Justifications](#décision-finale-et-justifications) + +--- + +## Résumé Exécutif + +### Besoin Principal +Assistant personnel proactif avec : +- Détection hyperfocus en temps réel +- Interventions vocales contextuelles +- Planning intelligent avec IA +- Monitoring applicatif natif +- Cross-platform (Windows/Mac/Linux en priorité) + +### Décision Finale Retenue +**C++ Modulaire (WarFactory Engine) + ImGui + Claude Haiku 4.5** + +**Raisons clés :** +1. ✅ Réutilisation moteur existant déjà développé +2. ✅ Types stricts C++ (pas de wildcode) +3. ✅ Hot-reload ultra-rapide (0.4ms) +4. ✅ Architecture modulaire éprouvée +5. ✅ Tout local (privacy, $0 hosting, offline-first) + +--- + +## Alternatives Backend + +### Option 1 : Node.js Pur (Sans C++) + +**Architecture :** +``` +Electron/Tauri Frontend + ↓ +Node.js Backend (localhost) + ↓ active-win (npm) +Monitoring Apps +``` + +**✅ Avantages :** +- Rapide à développer (écosystème npm riche) +- Pas de complexité build C++ +- Hot-reload natif (nodemon) +- Cross-platform via packages npm (`active-win`, etc.) +- Debugging simple (Chrome DevTools) + +**❌ Inconvénients :** +- Pas de types stricts (TypeScript aide mais pas natif) +- "Wildcode" JavaScript (moins structuré que C++) +- Performance inférieure au C++ natif +- Monitoring apps limité (dépend de packages npm) +- Pas de réutilisation du moteur WarFactory + +**Verdict :** ❌ Rejeté - Manque de types stricts et pas de réutilisation code existant + +--- + +### Option 2 : C++ Core + Node.js Wrapper (N-API) + +**Architecture :** +``` +Frontend (React/Vue) + ↓ WebSocket +Node.js Backend + ↓ N-API binding +C++ Core Modules (.node addons) + ↓ Win32/AppKit/X11 +Native OS APIs +``` + +**✅ Avantages :** +- Performance native C++ pour monitoring critique +- Écosystème Node.js pour glue code +- N-API stable et bien documenté +- Cross-platform (compile .node pour chaque OS) +- Bon compromis performance/productivité + +**❌ Inconvénients :** +- Complexité build (node-gyp + CMake) +- Debugging complexe (C++ crash + JS context) +- Maintenance deux langages (C++ + JS/TS) +- Setup environnement compliqué (Python, build tools) +- Pas de réutilisation directe moteur WarFactory + +**Verdict :** ⚠️ Viable mais complexe - Bonne option si besoin écosystème Node.js + +--- + +### Option 3 : Rust + Node (N-API) + +**Architecture :** +``` +Frontend (React/Vue) + ↓ WebSocket +Node.js Backend + ↓ N-API (neon-bindings) +Rust Core Modules + ↓ Windows/macOS/Linux APIs +Native OS APIs +``` + +**✅ Avantages :** +- Sécurité mémoire Rust (moins de segfaults que C++) +- Performance native équivalente C++ +- N-API via `neon-bindings` bien maintenu +- Écosystème cargo moderne +- Moins de bugs mémoire qu'en C++ + +**❌ Inconvénients :** +- Courbe d'apprentissage Rust (ownership, lifetimes) +- Pas de réutilisation moteur WarFactory (écrit en C++) +- Complexité build similaire à C++ +- Debugging Rust + Node.js complexe +- Temps de compilation Rust élevé + +**Verdict :** ❌ Rejeté - Pas de réutilisation code existant + courbe apprentissage + +--- + +### Option 4 : C++ Pur (WarFactory Engine Réutilisé) + +**Architecture :** +``` +ImGui UI (C++) + ↓ IPC (IntraIO) +WarFactory Engine Core + ↓ DLL/SO Loader +AISSIA Modules (.dll/.so) + - MonitoringModule.dll + - SchedulerModule.dll + - AIModule.dll + - VoiceModule.dll + - StorageModule.dll + ↓ Win32/AppKit/X11 +Native OS APIs +``` + +**✅ Avantages :** +- ✅ **Réutilisation moteur existant** (WarFactory déjà développé et testé) +- ✅ **Types stricts C++** (pas de wildcode) +- ✅ **Hot-reload ultra-rapide** (0.4ms iteration) +- ✅ **Architecture modulaire éprouvée** (IModule, IIO, IEngine) +- ✅ **Performance maximale** (natif C++) +- ✅ **Cross-platform** (DLL/SO loader Windows/Linux/Mac) +- ✅ **Build autonome** (chaque module : `cmake .`) +- ✅ **Développement parallèle** (multiples modules simultanés) +- ✅ **ImGui intégré** (déjà dans WarFactory) +- ✅ **Zéro coût backend** (tout local) + +**❌ Inconvénients :** +- Courbe apprentissage C++ si pas expert +- Debugging segfaults plus compliqué que JS +- UI ImGui moins moderne que React/Vue (mais suffisant MVP) +- Mobile difficile (mais pas priorité MVP) + +**Verdict :** ✅ **RETENU** - Meilleur rapport réutilisation/performance/types stricts + +--- + +### Option 5 : C# .NET + Electron.NET + +**Architecture :** +``` +Electron.NET (C# backend) + ↓ .NET Core +C# Modules + ↓ Win32 API (P/Invoke) +Native Windows APIs +``` + +**✅ Avantages :** +- Types stricts C# (fortement typé) +- Win32 API facile via P/Invoke +- Écosystème .NET riche +- Debugging Visual Studio excellent +- UI moderne via Electron + +**❌ Inconvénients :** +- Electron.NET moins mature que Electron classique +- Cross-platform limité (Win32 spécifique Windows) +- Pas de réutilisation moteur WarFactory (écrit en C++) +- Performance inférieure au C++ natif +- Dépendance .NET Runtime + +**Verdict :** ❌ Rejeté - Pas de réutilisation WarFactory + moins performant que C++ + +--- + +### Option 6 : FastAPI (Python) + Flutter + +**Architecture :** +``` +Flutter Frontend (Mobile + Desktop) + ↓ REST API / WebSocket +FastAPI Backend (Python) + ↓ pywin32 / AppKit bindings +Native OS APIs +``` + +**✅ Avantages :** +- Développement rapide (Python + Flutter) +- UI moderne cross-platform (Flutter) +- Intégration IA facile (Python) +- Mobile natif (Android/iOS) + +**❌ Inconvénients :** +- Pas de types stricts (Python dynamique) +- Performance médiocre (Python) +- Nécessite backend séparé (complexité déploiement) +- Pas de réutilisation WarFactory +- Coût hosting backend ($10-50/mois) + +**Verdict :** ❌ Rejeté - Pas de types stricts + coût hosting + pas réutilisation + +--- + +## Alternatives Frontend + +### Option 1 : Dear ImGui (C++ Intégré) + +**Architecture :** +```cpp +// ui-imgui.dll module +class UIModule : public IModule { + void Render() { + ImGui::Begin("AISSIA Dashboard"); + // Render planning, tasks, settings + ImGui::End(); + } +}; +``` + +**✅ Avantages :** +- ✅ Déjà intégré dans WarFactory +- ✅ Natif C++ (même langage que modules) +- ✅ Hot-reloadable comme les autres modules +- ✅ Rapide à prototyper +- ✅ Performance native +- ✅ Pas de dépendance externe + +**❌ Inconvénients :** +- UI moins moderne que React/Vue +- Styling limité (look "debug tool") +- Pas mobile-friendly + +**Verdict :** ✅ **RETENU pour MVP** - Rapidité prototypage + intégration parfaite + +--- + +### Option 2 : Electron (React/Vue) + +**Architecture :** +``` +Electron App (React/Vue UI) + ↓ WebSocket +C++ Backend (WarFactory Engine) + ↓ ui-websocket.dll module +IPC Bridge +``` + +**✅ Avantages :** +- UI moderne et professionnelle +- Écosystème riche (React components) +- Hot-reload frontend natif +- Design système avancé (Tailwind, Material UI) +- Cross-platform desktop + +**❌ Inconvénients :** +- Complexité accrue (2 processus : Electron + C++ backend) +- Build plus lourd (Electron bundle ~150MB) +- Latence IPC WebSocket +- Maintenance deux stacks (JS + C++) + +**Verdict :** ⚠️ **Phase 2** - Si besoin UX premium après MVP + +--- + +### Option 3 : Tauri (Rust/JS) + +**Architecture :** +``` +Tauri App (React/Vue UI) + ↓ IPC (Rust bindings) +C++ Backend via FFI +``` + +**✅ Avantages :** +- Léger (~10MB vs 150MB Electron) +- Sécurité accrue (Rust backend) +- UI moderne (React/Vue) +- Performance native + +**❌ Inconvénients :** +- FFI C++ ↔ Rust complexe +- Tauri moins mature qu'Electron +- Pas de réutilisation directe WarFactory +- Courbe apprentissage Tauri + +**Verdict :** ❌ Rejeté - Complexité FFI + pas mature + +--- + +### Option 4 : Flutter Desktop + +**Architecture :** +``` +Flutter Desktop App + ↓ Platform Channels +C++ Backend (WarFactory Engine) +``` + +**✅ Avantages :** +- UI moderne cross-platform +- Performance native (compiled) +- Hot-reload Flutter +- Mobile future facile + +**❌ Inconvénients :** +- Platform Channels C++ ↔ Dart complexe +- Flutter Desktop moins mature que Web/Mobile +- Build setup compliqué +- Dépendance Dart/Flutter toolchain + +**Verdict :** ❌ Rejeté pour MVP - Complexité intégration + +--- + +### Option 5 : Qt (C++) + +**Architecture :** +```cpp +QApplication app; +MainWindow window; // Qt Widgets +// Intégré directement dans C++ backend +``` + +**✅ Avantages :** +- Natif C++ (même langage) +- UI professionnelle +- Cross-platform mature +- Intégration parfaite avec WarFactory + +**❌ Inconvénients :** +- Licence Qt (GPL ou commercial $$$) +- Complexité Qt framework +- Build setup lourd (qmake/CMake) +- Courbe apprentissage élevée + +**Verdict :** ❌ Rejeté - Licence + complexité vs ImGui + +--- + +## Alternatives Architecture + +### Option 1 : Monolithe (Tout dans un exécutable) + +**Architecture :** +```cpp +// aissia.exe - tout en un +int main() { + MonitoringSystem monitor; + SchedulerSystem scheduler; + AISystem ai; + VoiceSystem voice; + UISystem ui; + + while (running) { + monitor.update(); + scheduler.update(); + ai.update(); + // ... + } +} +``` + +**✅ Avantages :** +- Simple à déployer (1 fichier .exe) +- Pas de complexité DLL/SO +- Debugging simple (tout dans un processus) + +**❌ Inconvénients :** +- Pas de hot-reload +- Rebuild complet à chaque modification (5+ min) +- Impossible de développer modules en parallèle +- Couplage fort entre systèmes +- Pas de réutilisation composants + +**Verdict :** ❌ Rejeté - Pas de hot-reload + temps dev long + +--- + +### Option 2 : Microservices (Services séparés) + +**Architecture :** +``` +monitoring-service.exe (Port 3001) +scheduler-service.exe (Port 3002) +ai-service.exe (Port 3003) +voice-service.exe (Port 3004) + ↓ HTTP REST +API Gateway (Port 3000) + ↓ +Frontend +``` + +**✅ Avantages :** +- Scaling horizontal facile +- Déploiement indépendant services +- Isolation complète +- Technologie différente par service + +**❌ Inconvénients :** +- Complexité déploiement (5+ processus) +- Latence réseau entre services +- Orchestration complexe (Docker, K8s) +- Overkill pour usage personnel +- Debugging distribué difficile + +**Verdict :** ❌ Rejeté - Over-engineering pour MVP + +--- + +### Option 3 : Architecture Modulaire DLL/SO (WarFactory) + +**Architecture :** +``` +aissia-core.exe (Engine WarFactory) + ↓ DLL/SO Loader +modules/ + monitoring.dll + scheduler.dll + ai.dll + voice.dll + storage.dll + ui.dll +``` + +**✅ Avantages :** +- ✅ **Hot-reload ultra-rapide** (0.4ms) +- ✅ **Build autonome** par module (`cmake .`) +- ✅ **Développement parallèle** (multiples devs/modules) +- ✅ **Isolation** (crash module ≠ crash app) +- ✅ **Réutilisation** (modules entre projets) +- ✅ **Architecture éprouvée** (WarFactory) +- ✅ **Testing isolé** par module + +**❌ Inconvénients :** +- Setup initial DLL loader (déjà fait dans WarFactory) +- Gestion version modules (résolu par gameconfig.json) + +**Verdict :** ✅ **RETENU** - Meilleur compromis modularité/performance + +--- + +### Option 4 : Plugin System (Shared Libraries) + +**Architecture :** +Similaire à Option 3 mais sans l'architecture complète WarFactory (IEngine, IModuleSystem, IIO, etc.) + +**✅ Avantages :** +- Modularité +- Hot-reload possible + +**❌ Inconvénients :** +- Réinventer la roue (WarFactory existe déjà) +- Pas de pub/sub IIO +- Pas de task scheduler +- Pas de configuration IDataTree + +**Verdict :** ❌ Rejeté - WarFactory fait mieux + +--- + +## Alternatives Déploiement + +### Option 1 : Local-Only (Tout sur machine utilisateur) + +**Architecture :** +``` +User Machine +├── aissia-core.exe +├── modules/*.dll +├── aissia.db (SQLite) +└── gameconfig.json +``` + +**✅ Avantages :** +- ✅ **$0 coût hosting** +- ✅ **Privacy maximale** (données jamais uploaded) +- ✅ **Offline-first** (fonctionne sans internet) +- ✅ **Latence zéro** (tout local) +- ✅ **Simple à déployer** (copier dossier) + +**❌ Inconvénients :** +- Pas de sync multi-devices (sauf cloud storage manuel) +- Backup manuel utilisateur +- Pas de mobile (difficile sans backend) + +**Verdict :** ✅ **RETENU pour MVP** - Privacy + $0 coût + simplicité + +--- + +### Option 2 : Cloud Backend (Serveur centralisé) + +**Architecture :** +``` +User Machine (Frontend) + ↓ HTTPS REST +Cloud Server (Backend) + ↓ +PostgreSQL Database +Redis Cache +S3 Storage +``` + +**✅ Avantages :** +- Sync multi-devices automatique +- Backup automatique +- Mobile facile (API REST) +- Analytics centralisées + +**❌ Inconvénients :** +- Coût hosting ($10-50/mois minimum) +- Privacy concerns (données sur serveur tiers) +- Dépendance internet +- Complexité déploiement (Docker, scaling) +- RGPD compliance nécessaire + +**Verdict :** ❌ Rejeté pour MVP - Coût + privacy + complexité + +**Possible Phase 3** : Sync optionnel cloud pour multi-devices + +--- + +### Option 3 : Hybride (Local + Sync Optionnel) + +**Architecture :** +``` +User Machine (Primary) +├── aissia-core.exe (local) +├── aissia.db (SQLite local) +└── Sync Service (optionnel) + ↓ HTTPS (si activé) +Cloud Sync Server (optionnel) + └── Backup DB + sync delta +``` + +**✅ Avantages :** +- Fonctionnement 100% local par défaut +- Sync optionnel si utilisateur veut +- Privacy par défaut (opt-in cloud) +- Coût scaling progressif + +**❌ Inconvénients :** +- Complexité sync (conflict resolution) +- Deux modes à maintenir (local + cloud) +- Backend à développer même si optionnel + +**Verdict :** ⚠️ **Phase 2/3** - Commence local, ajoute sync si besoin + +--- + +### Option 4 : P2P Sync (Syncthing-like) + +**Architecture :** +``` +User Machine A User Machine B + ↓ ↓ + └───── P2P Network ─────┘ + (Syncthing, IPFS) +``` + +**✅ Avantages :** +- Pas de serveur centralisé ($0 coût) +- Privacy maximale +- Sync multi-devices sans cloud + +**❌ Inconvénients :** +- Complexité P2P (NAT traversal, discovery) +- Conflict resolution difficile +- Dépendance Syncthing/IPFS +- Setup utilisateur complexe + +**Verdict :** ❌ Rejeté - Complexité vs bénéfice + +--- + +## Matrice de Décision + +### Backend + +| Option | Types Stricts | Performance | Réutilisation WarFactory | Complexité | Verdict | +|--------|---------------|-------------|--------------------------|------------|---------| +| Node.js pur | ❌ | ⭐⭐ | ❌ | ⭐⭐⭐⭐⭐ | ❌ Rejeté | +| C++ + Node Wrapper | ⚠️ | ⭐⭐⭐⭐ | ⚠️ | ⭐⭐⭐ | ⚠️ Viable | +| Rust + Node | ✅ | ⭐⭐⭐⭐ | ❌ | ⭐⭐ | ❌ Rejeté | +| **C++ Pur (WarFactory)** | ✅ | ⭐⭐⭐⭐⭐ | ✅ | ⭐⭐⭐ | ✅ **RETENU** | +| C# .NET | ✅ | ⭐⭐⭐ | ❌ | ⭐⭐⭐⭐ | ❌ Rejeté | +| Python FastAPI | ❌ | ⭐⭐ | ❌ | ⭐⭐⭐⭐⭐ | ❌ Rejeté | + +### Frontend + +| Option | Rapidité Proto | Intégration C++ | UI Moderne | Mobile | Verdict | +|--------|----------------|-----------------|------------|--------|---------| +| **ImGui** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ❌ | ✅ **MVP** | +| Electron | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ | ⚠️ Phase 2 | +| Tauri | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ | ❌ Rejeté | +| Flutter | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ✅ | ❌ Rejeté | +| Qt | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⚠️ | ❌ Rejeté | + +### Architecture + +| Option | Hot-Reload | Dev Parallèle | Réutilisation | Complexité | Verdict | +|--------|------------|---------------|---------------|------------|---------| +| Monolithe | ❌ | ❌ | ❌ | ⭐⭐⭐⭐⭐ | ❌ Rejeté | +| Microservices | ✅ | ✅ | ✅ | ⭐ | ❌ Over-eng | +| **DLL/SO Modulaire** | ⭐⭐⭐⭐⭐ | ✅ | ✅ | ⭐⭐⭐ | ✅ **RETENU** | +| Plugin System | ⭐⭐⭐ | ✅ | ⚠️ | ⭐⭐⭐⭐ | ❌ Rejeté | + +### Déploiement + +| Option | Coût | Privacy | Offline | Sync Multi-Device | Verdict | +|--------|------|---------|---------|-------------------|---------| +| **Local-Only** | $0 | ⭐⭐⭐⭐⭐ | ✅ | ❌ | ✅ **MVP** | +| Cloud Backend | $10-50/mois | ⭐⭐ | ❌ | ✅ | ❌ Rejeté | +| Hybride | $0-10/mois | ⭐⭐⭐⭐ | ✅ | ⚠️ | ⚠️ Phase 2 | +| P2P Sync | $0 | ⭐⭐⭐⭐⭐ | ✅ | ⚠️ | ❌ Complexe | + +--- + +## Décision Finale et Justifications + +### Stack Retenue : C++ Modulaire (WarFactory) + ImGui + Local-Only + +**Architecture Finale :** +``` +┌─────────────────────────────────────┐ +│ ImGui UI (ui-imgui.dll) │ +│ - Planning dashboard │ +│ - Task management │ +│ - Settings │ +└─────────────┬───────────────────────┘ + │ IntraIO (IPC local) +┌─────────────▼───────────────────────┐ +│ aissia-core.exe │ +│ (WarFactory Engine) │ +│ ┌────────────────────────────────┐ │ +│ │ ICoordinationModule │ │ +│ │ IEngine (DebugEngine) │ │ +│ │ IModuleSystem (Sequential) │ │ +│ └────────────────────────────────┘ │ +│ │ +│ Modules (DLL/SO): │ +│ ├── monitoring.dll │ +│ ├── scheduler.dll │ +│ ├── ai.dll │ +│ ├── voice.dll │ +│ ├── storage.dll (SQLite) │ +│ └── ui-imgui.dll │ +└─────────────┬───────────────────────┘ + │ HTTPS +┌─────────────▼───────────────────────┐ +│ Claude Haiku 4.5 API │ +│ (Seul service externe) │ +└─────────────────────────────────────┘ +``` + +### Justifications par Critère + +#### 1. **Réutilisation de Code** +✅ **WarFactory engine réutilisé à 100%** +- IModule, IEngine, IModuleSystem, IIO déjà implémentés +- Hot-reload system déjà testé et fonctionnel (0.4ms) +- Build system CMake déjà configuré +- Configuration IDataTree/IDataNode déjà fait +- **Économie : ~3-4 semaines de développement** + +#### 2. **Types Stricts (Exigence forte)** +✅ **C++ natif avec headers stricts** +- Pas de "wildcode" JavaScript/Python +- Interfaces bien définies (IModule.h, IIO.h, etc.) +- Compilation time type checking +- Auto-completion IDE complète + +#### 3. **Performance** +✅ **Performance native maximale** +- C++ compilé natif (vs interprété Python/JS) +- Win32 API direct (vs wrappers npm) +- Hot-reload 0.4ms (vs 5+ min rebuild monolithe) +- Latence zéro (tout local, pas de réseau) + +#### 4. **Développement Rapide** +✅ **Itérations ultra-rapides** +- Hot-reload 0.4ms = feedback instantané +- Build autonome par module (`cmake .`) +- ImGui rapide à prototyper (vs React/Vue setup) +- Développement parallèle modules + +#### 5. **Cross-Platform** +✅ **Windows/Mac/Linux supportés** +- DLL/SO loader fonctionne sur tous OS +- Win32 API (Windows), AppKit (Mac), X11/Wayland (Linux) +- CMake cross-compilation facile +- ImGui natif sur tous OS + +#### 6. **Privacy & Coût** +✅ **Tout local, $0 hosting** +- Données jamais uploadées (sauf appels Claude API) +- SQLite local (pas de PostgreSQL distant) +- Pas de serveur backend à maintenir +- Offline-first (fonctionne sans internet sauf IA) + +#### 7. **Simplicité Déploiement** +✅ **Copier-coller dossier = fonctionne** +``` +aissia/ +├── aissia-core.exe +├── modules/*.dll +├── gameconfig.json +└── aissia.db +``` +- Pas de Docker, K8s, services cloud +- Pas d'installation complexe +- Portable (USB key = fonctionne) + +#### 8. **Évolutivité Future** +✅ **Architecture permet évolution progressive** + +**Phase 1 (MVP - 2 semaines)** : +- ImGui UI intégrée +- Modules core (monitoring, scheduler, AI, voice, storage) +- Local-only, offline-first +- Windows primary target + +**Phase 2 (Production - 4 semaines)** : +- Electron/Tauri UI (si besoin UX premium) +- WebSocket IPC (ui-websocket.dll module) +- Mac/Linux support complet +- Configuration avancée + +**Phase 3 (Extension - 8+ semaines)** : +- Sync cloud optionnel (sync-service.dll module) +- Mobile app (Flutter/React Native via NetworkIO) +- Analytics avancées +- Intégrations tierces (calendrier, etc.) + +--- + +## Alternatives Non Retenues - Raisons Détaillées + +### Pourquoi Pas Node.js ? +1. ❌ Pas de types stricts natifs (TypeScript aide mais runtime JS) +2. ❌ "Wildcode" (moins structuré que C++) +3. ❌ Performance inférieure (interprété vs compilé) +4. ❌ Pas de réutilisation WarFactory +5. ❌ Monitoring apps limité (dépend packages npm) + +**Conclusion** : Gain rapidité dev annulé par manque types + performance + +--- + +### Pourquoi Pas Rust ? +1. ❌ Pas de réutilisation WarFactory (écrit en C++) +2. ❌ Courbe apprentissage ownership/lifetimes +3. ❌ FFI C++ ↔ Rust complexe si besoin interop +4. ⚠️ Compilation lente (vs C++) + +**Conclusion** : Sécurité mémoire intéressante mais pas prioritaire vs réutilisation + +--- + +### Pourquoi Pas Flutter/Electron UI ? +1. ⚠️ Complexité accrue (2 stacks : C++ + JS/Dart) +2. ⚠️ IPC WebSocket latency (vs IntraIO) +3. ⚠️ Build lourd (150MB Electron bundle) +4. ⚠️ Maintenance frontend séparé + +**Conclusion** : Meilleure UX mais pas critique MVP. **Phase 2 si besoin.** + +--- + +### Pourquoi Pas Cloud Backend ? +1. ❌ Coût hosting ($10-50/mois minimum) +2. ❌ Privacy concerns (données uploadées) +3. ❌ Dépendance internet (vs offline-first) +4. ❌ Complexité déploiement (Docker, scaling) +5. ❌ RGPD compliance nécessaire + +**Conclusion** : Over-engineering pour usage personnel. **Phase 3 optionnel.** + +--- + +### Pourquoi Pas Microservices ? +1. ❌ Over-engineering extrême pour usage solo +2. ❌ Complexité orchestration (5+ processus) +3. ❌ Latence réseau inter-services +4. ❌ Debugging distribué difficile + +**Conclusion** : Overkill total. Architecture modulaire DLL/SO suffit amplement. + +--- + +## Risques et Mitigations + +### Risque 1 : Complexité C++ pour Nouveaux Modules +**Probabilité** : Moyenne +**Impact** : Moyen + +**Mitigation** : +- Templates modules prêts (MonitoringModule.h, etc.) +- Documentation WarFactory complète (`docs/`) +- Interfaces simples (IModule = 4 méthodes) +- Hot-reload = feedback rapide (pas de frustration build) + +--- + +### Risque 2 : ImGui UI Pas Assez Moderne +**Probabilité** : Élevée +**Impact** : Faible (MVP) → Moyen (Production) + +**Mitigation** : +- MVP = dogfooding personnel (UI simple suffit) +- Phase 2 = Electron/Tauri si besoin UX premium +- Architecture modulaire = swap ui-imgui.dll → ui-electron.dll facile + +--- + +### Risque 3 : Pas de Mobile (Android/iOS) +**Probabilité** : Faible (pas priorité MVP) +**Impact** : Moyen (si commercialisation) + +**Mitigation** : +- Phase 3 = NetworkIO + Flutter/React Native mobile app +- Backend C++ reste inchangé (modules via NetworkIO) +- Desktop = priorité usage personnel + +--- + +### Risque 4 : Debugging Segfaults C++ +**Probabilité** : Moyenne +**Impact** : Moyen + +**Mitigation** : +- AddressSanitizer activé (détection immédiate bugs mémoire) +- Modules isolés (crash module ≠ crash app) +- Hot-reload = retry rapide après fix +- GDB integration (stack traces précises) + +--- + +## Métriques de Succès Architecture + +### Vitesse Développement +- ✅ **Hot-reload < 1s** : 0.4ms mesuré WarFactory +- ✅ **Build module < 5s** : `cmake . && make` autonome +- ✅ **Iteration cycle < 10s** : Edit → Build → Test + +### Performance Runtime +- ✅ **App startup < 2s** : Engine + modules load +- ✅ **UI latency < 100ms** : ImGui render 60fps +- ✅ **Monitoring overhead < 1% CPU** : Background tracking + +### Maintenabilité +- ✅ **Modules indépendants** : Build autonome `cmake .` +- ✅ **Tests isolés** : Chaque module testable seul +- ✅ **Documentation complète** : `aissia/docs/` (copié WarFactory) + +--- + +## Conclusion + +**Décision Finale Validée** : **C++ Modulaire (WarFactory) + ImGui + Local-Only** + +**Facteurs Décisifs :** +1. ✅ **Réutilisation WarFactory** = économie 3-4 semaines +2. ✅ **Types stricts C++** = exigence satisfaite +3. ✅ **Hot-reload 0.4ms** = productivité maximale +4. ✅ **$0 coût hosting** = viable long-terme +5. ✅ **Privacy par design** = offline-first +6. ✅ **Architecture éprouvée** = risque réduit + +**Next Steps** : +1. Créer structure modules/ (MonitoringModule, SchedulerModule, etc.) +2. Implémenter MonitoringModule.dll (Win32 API tracking) +3. Implémenter SchedulerModule.dll (planning logic) +4. Intégrer Claude Haiku API (AIModule.dll) +5. Implémenter VoiceModule.dll (SAPI TTS + Whisper STT) +6. Créer UI ImGui basique (ui-imgui.dll) + +**Timeline Estimé MVP** : 2 semaines avec hot-reload architecture + +--- + +**Document Version:** 1.0 +**Date:** 27 octobre 2025 +**Status:** ✅ Décision Validée diff --git a/CDCDraft.md b/CDCDraft.md new file mode 100644 index 0000000..9f9d3dc --- /dev/null +++ b/CDCDraft.md @@ -0,0 +1,1164 @@ +# Cahier des Charges - AISSIA (AI Smart Schedule & Interactive Assistant) + +**Version:** 0.4 - Architecture Hybride Proposée +**Date:** 27 octobre 2025 +**Auteur:** Alexis Trouvé + +--- + +## 1. Contexte et Problématique + +### 1.1 Besoin Utilisateur +Difficulté majeure dans la gestion du temps et des priorités, caractérisée par : +- **Hyperfocus** : Incapacité à stopper une tâche une fois démarrée (travail ou jeu vidéo) +- **Absence de limites claires** : Continuer jusqu'à épuisement physique ("body tell me I can't") +- **Multi-tâches impossibles** : Difficulté à gérer 2-3 activités différentes dans une journée +- **Régulation de l'attention défaillante** : Besoin d'un système externe pour gérer les transitions + +### 1.2 Solution Proposée +Assistant personnel intelligent et proactif qui : +- Pense le planning en arrière-plan +- Intervient de manière proactive (pas seulement réactif) +- S'adapte aux patterns comportementaux de l'utilisateur +- Force les transitions quand nécessaire + +--- + +## 2. Objectifs du Projet + +### 2.1 Objectifs Fonctionnels +1. **Planning Intelligent** : IA qui organise automatiquement les tâches selon priorités et contraintes +2. **Assistant Proactif** : Détection d'hyperfocus et intervention automatique +3. **Tracking Automatique** : Suivi du temps passé sur chaque activité +4. **Interaction Naturelle** : Dialogue avec l'IA pour ajuster le planning en temps réel +5. **Notifications Intelligentes** : Rappels adaptatifs basés sur le contexte + +### 2.2 Objectifs Techniques +- **Dev Windows-first** : Développement et debug 100% sur Windows avec WarFactory engine +- **Déploiement flexible** : Mode local (DLL) OU mode cloud (WASM + PWA) selon besoin +- **Hot-reload dev** : 0.4ms iteration en mode local (WarFactory) +- **Cross-platform automatique** : Deploy sur tous OS via Docker/WASM (sans effort dev) +- **Mobile optionnel** : PWA installable (Phase 2+, pas obligatoire MVP) +- **Offline-first** : Fonctionne en local (SQLite) ou avec sync cloud optionnel +- **Performance** : Native en local (DLL), quasi-native en WASM (~2x plus lent acceptable) +- **Privacy** : Mode local = données jamais uploadées, mode cloud = processing client-side +- **Coûts optimisés** : $0 en mode local, $3-5/mois en mode cloud (70% processing client) + +### 2.3 Objectifs Business +- **Usage personnel** : Version pour usage propre en priorité +- **Commercialisation** : Potentiel de monétisation futur (Freemium) +- **Itérations courtes** : Cycles de développement de 1-2 semaines +- **Versions fonctionnelles** : Chaque itération doit produire une version utilisable + +--- + +## 3. Fonctionnalités + +### 3.1 MVP - Phase 1 (Semaines 1-2) + +#### Gestion des Tâches +- ✅ Création/édition/suppression de tâches +- ✅ Priorités (Haute/Moyenne/Basse) +- ✅ Durée estimée +- ✅ Deadlines optionnelles +- ✅ Tags/catégories + +#### Tracking du Temps +- ✅ Timer manuel (start/stop) +- ✅ Historique du temps passé par tâche +- ✅ Vue journalière/hebdomadaire + +#### IA Basique +- ✅ Suggestions de planning pour la journée +- ✅ Réorganisation des tâches selon priorités +- ✅ Estimation durée réaliste basée sur historique + +#### Notifications +- ✅ Rappels de début de tâche +- ✅ Alertes de fin de tâche planifiée +- ✅ Notifications push sur tous les appareils + +#### Authentification +- ✅ Inscription/connexion email/password +- ✅ Synchronisation multi-appareils + +### 3.2 Phase 2 - IA Proactive (Semaines 3-4) + +#### Détection d'Hyperfocus +- ⏳ Analyse du temps passé vs temps planifié +- ⏳ Détection de patterns anormaux (>2h sans pause) +- ⏳ Alertes progressives (douce → insistante → forcée) + +#### Assistant Conversationnel +- ⏳ Chat avec l'IA pour ajuster le planning +- ⏳ Commandes vocales (optionnel) +- ⏳ Suggestions contextuelles ("Tu devrais faire une pause") + +#### Apprentissage des Patterns +- ⏳ Analyse des heures productives +- ⏳ Détection des activités "dangereuses" (jeux vidéo, etc.) +- ⏳ Adaptation du planning selon l'état de fatigue + +#### Interventions Proactives +- ⏳ Blocage d'applications (optionnel, sur demande) +- ⏳ Rappels de breaks forcés +- ⏳ Réorganisation automatique si dérive détectée + +### 3.3 Phase 3 - Fonctionnalités Avancées (Semaines 5+) + +#### Intelligence Contextuelle +- 🔮 Détection automatique d'activité (via tracking d'apps) +- 🔮 Prédiction des risques d'hyperfocus +- 🔮 Suggestions de planning optimal selon l'énergie + +#### Intégrations +- 🔮 Calendrier (Google, Outlook) +- 🔮 Outils de productivité (Notion, Todoist) +- 🔮 Tracking d'activité (RescueTime, ActivityWatch) + +#### Gamification (Optionnel) +- 🔮 Système de points/récompenses +- 🔮 Streaks (jours consécutifs avec planning respecté) +- 🔮 Achievements + +#### Analytics +- 🔮 Rapports hebdomadaires/mensuels +- 🔮 Visualisations de productivité +- 🔮 Insights IA sur les habitudes + +--- + +## 4. Architecture Technique + +### 4.1 Proposition Architecturale : Architecture Hybride WarFactory + WASM + +**PROPOSITION ARCHITECTURALE** : AISSIA pourrait réutiliser l'architecture modulaire WarFactory avec compilation multi-target optionnelle (DLL/SO/WASM). + +**⚠️ IMPORTANT - Phases d'implémentation :** +- **Phase 1 (local_dev) = OBLIGATOIRE** : Cible principale MVP avec WarFactory DLL Windows uniquement +- **Phase 2 (POC WASM) = VALIDATION** : Tester faisabilité avant engagement +- **Phase 3 (production_pwa) = CONDITIONNELLE** : Seulement si Phase 2 validée ET besoin justifié + +**Concept Révolutionnaire : Meilleur des Deux Mondes** + +``` +MÊME code C++ (IModule WarFactory) + ↓ CMake multi-target +├─ monitoring.dll (Dev Windows local + Hot-reload 0.4ms) +├─ monitoring.so (Serveur Linux Docker - Phase 3) +└─ monitoring.wasm (Client PWA browser - Phase 3) + +UN SEUL CODE, TROIS DÉPLOIEMENTS ! +``` + +**Architecture Hybride Proposée (À valider par POC) :** +- 🎯 **Réutilisation WarFactory** : Interfaces IModule/IEngine/IIO/ITaskScheduler inchangées (validé) +- 🎯 **Développement 100% Windows** : Visual Studio 2022, DLL, ImGui, hot-reload 0.4ms (validé) +- ⚠️ **Modules C++ écrits UNE FOIS** : Compilés en DLL (dev), SO (serveur), WASM (browser) (hypothétique - à tester) +- ⚠️ **Déploiement flexible** : gameconfig.json bascule entre mode `local_dev` et `production_pwa` (hypothétique) +- ✅ **MVP = Mode Local OBLIGATOIRE** : aissia-core.exe + DLL + ImGui + SQLite ($0 coût) +- ⚠️ **Production optionnelle CONDITIONNELLE** : React PWA + WASM client + Docker serveur ($3-5/mois) - SI Phase 2 validée +- ⚠️ **Cross-platform automatique** : Docker + WASM = tourne partout sans effort (hypothétique - complexité à évaluer) +- ⚠️ **Mobile optionnel** : PWA installable (Phase 3+, SEULEMENT si besoin validé) + +**Raisons de cette proposition :** +- ✅ **Réutilisation code existant** : Économie 3-4 semaines dev (WarFactory validé) +- ✅ **Hot-reload ultra-rapide** : 0.4ms en mode local_dev (DLL validé) +- ✅ **Types stricts C++** : Pas de "wildcode", headers et interfaces bien définis (validé) +- ✅ **Modularité** : Chaque fonctionnalité = module isolé (200-300 lignes, validé WarFactory) +- ✅ **Évolution progressive** : Commencer local ($0), décider cloud plus tard (stratégie validée) +- ⚠️ **Performance maximale** : Native en local (validé), quasi-native en WASM (hypothétique - à benchmarker) +- ✅ **Développement parallèle** : Multiples modules développés simultanément (validé WarFactory) +- ✅ **Coûts minimaux Phase 1** : $0 en MVP garanti +- ⚠️ **Pipeline flexible hypothétique** : Un seul codebase, multiples déploiements (complexité à évaluer) + +### 4.2 Modes de Déploiement + +**AISSIA propose DEUX modes de déploiement distincts, potentiellement sélectionnables via `gameconfig.json` :** + +**⚠️ Clarification priorités :** +- **Mode 1 (local_dev) = OBLIGATOIRE** : Cible MVP, sera implémenté en Phase 1 +- **Mode 2 (production_pwa) = OPTIONNEL** : Sera considéré SEULEMENT si Phase 2 (POC WASM) validée + +#### Mode 1 : `local_dev` (MVP - Phase 1 OBLIGATOIRE) + +**Architecture :** +``` +┌─────────────────────────────────────┐ +│ Windows PC │ +│ ┌───────────────────────────────┐ │ +│ │ aissia-core.exe │ │ +│ │ (WarFactory Engine) │ │ +│ │ ├─ IEngine (DebugEngine) │ │ +│ │ ├─ IModuleSystem (Sequential)│ │ +│ │ └─ IIO (IntraIO) │ │ +│ └───────────────────────────────┘ │ +│ ┌───────────────────────────────┐ │ +│ │ Modules DLL │ │ +│ │ ├─ monitoring.dll │ │ +│ │ ├─ scheduler.dll │ │ +│ │ ├─ ai.dll │ │ +│ │ ├─ voice.dll │ │ +│ │ ├─ storage.dll │ │ +│ │ └─ ui-imgui.dll │ │ +│ └───────────────────────────────┘ │ +│ SQLite local (aissia.db) │ +└─────────────────────────────────────┘ +``` + +**Caractéristiques :** +- ✅ **Hot-reload** : 0.4ms (750,000x plus rapide que rebuild complet) +- ✅ **UI** : Dear ImGui (C++, intégré WarFactory) +- ✅ **Storage** : SQLite local (aissia.db) +- ✅ **Coût** : $0 (tout local) +- ✅ **Privacy** : Données jamais uploadées (sauf appels Claude API) +- ✅ **Performance** : Native C++ (pas de WASM overhead) +- ✅ **Development** : Visual Studio 2022, debugging natif + +**Utilisation :** +```json +// gameconfig.json +{ + "active_mode": "local_dev" +} +``` + +--- + +#### Mode 2 : `production_pwa` (Phase 3 - CONDITIONNEL, après validation Phase 2) + +**Architecture :** +``` +┌────────────────────────┐ ┌───────────────────────────────┐ +│ CLIENT (PWA - Vercel) │ │ SERVEUR (fly.io) │ +│ ┌────────────────────┐ │ │ ┌───────────────────────────┐ │ +│ │ React + TypeScript │ │ │ │ Docker Linux │ │ +│ │ - Dashboard UI │ │ │ │ Backend C++ │ │ +│ │ - Task management │ │ │ │ ├─ auth.so │ │ +│ └────────────────────┘ │ │ │ ├─ sync.so │ │ +│ ┌────────────────────┐ │ │ │ ├─ ai-proxy.so │ │ +│ │ WASM Modules │ │ │ │ └─ monitoring.so │ │ +│ │ ├─ scheduler.wasm │ │ │ │ PostgreSQL │ │ +│ │ ├─ voice.wasm │ │ │ └───────────────────────────┘ │ +│ │ └─ storage.wasm │ │ │ Port: 8080 (WebSocket) │ +│ └────────────────────┘ │ └───────────────────────────────┘ +│ IndexedDB (cache) │ ▲ +│ Service Worker │ │ WebSocket +└────────┬───────────────┘ │ + │ │ + └──────────────────────────────┘ +``` + +**Caractéristiques :** +- ✅ **UI** : React moderne + Tailwind CSS +- ✅ **Storage** : Hybrid (IndexedDB client + PostgreSQL serveur) +- ✅ **Coût** : $3-5/mois (fly.io + Vercel gratuit) +- ✅ **Mobile** : PWA installable iOS/Android +- ✅ **Scalable** : 70% processing client = coûts serveur minimaux +- ✅ **Cross-platform** : Fonctionne sur tous devices +- ⚠️ **Performance** : WASM ~2x plus lent que C++ natif (acceptable) + +**Utilisation :** +```json +// gameconfig.json +{ + "active_mode": "production_pwa" +} +``` + +--- + +### 4.3 Stack Technologique Détaillée + +#### Développement (Windows - Les Deux Modes) +- **IDE** : Visual Studio 2022 / VSCode +- **Compilateur** : + - MSVC (Windows DLL) + - GCC/Clang (Linux SO via Docker) + - Emscripten (WASM browser) +- **Build System** : CMake (multi-target) +- **Containerization** : Docker Desktop (builds Linux SO) +- **Version Control** : Git + GitHub +- **CI/CD** : GitHub Actions + +#### Mode `local_dev` - Modules C++ (DLL) +- **Core Engine** : WarFactory (aissia-core.exe) + - IEngine (DebugEngine) + - IModuleSystem (SequentialModuleSystem) + - IIO (IntraIO pour communication locale) + - ICoordinationModule (charge gameconfig.json) +- **Modules DLL** : + - `monitoring.dll` : Win32 API tracking apps (GetForegroundWindow) + - `scheduler.dll` : Algorithmes planning, détection procrastination + - `ai.dll` : Claude Haiku API integration + - `voice.dll` : SAPI TTS (Windows) + Whisper.cpp STT + - `storage.dll` : SQLite local (aissia.db) + - `ui-imgui.dll` : Interface ImGui +- **Base de données** : SQLite local (aissia.db) +- **Coût** : $0 (tout local, sauf appels Claude API $10-20/mois) + +#### Mode `production_pwa` - Backend Serveur (SO) +- **Runtime** : Docker Linux container (Alpine ou Ubuntu) +- **Langage** : C++20 +- **Modules Serveur (SO)** : + - `auth.so` : Authentification JWT + - `sync.so` : Synchronisation données PostgreSQL + - `ai-proxy.so` : Proxy sécurisé pour Claude API (cache API key) + - `monitoring.so` : Tracking apps (optionnel, serveur dédié) + - `websocket-server.so` : API WebSocket pour clients PWA +- **Base de données** : PostgreSQL (fly.io managed) +- **Déploiement** : fly.io ($3-5/mois) + +#### Mode `production_pwa` - Frontend Client (WASM) +- **Framework** : React 18 + TypeScript +- **Build** : Vite (hot-reload ultra-rapide) +- **UI Library** : Tailwind CSS + shadcn/ui +- **State Management** : Zustand ou Jotai (léger) +- **Modules Client (WASM)** : + - `scheduler.wasm` : Algorithmes de planning (client-side) + - `voice.wasm` : TTS/STT via Web Speech API + - `storage.wasm` : Cache local IndexedDB +- **Offline** : Service Workers + IndexedDB +- **Notifications** : Web Push API +- **Déploiement** : Vercel (gratuit) + +--- + +### 4.4 Modules C++ Partagés (Un Code, Trois Targets) + +**Concept Clé** : Chaque module C++ implémente `IModule` de WarFactory et compile en 3 targets : + +```cpp +// modules/scheduler/src/SchedulerModule.cpp +// MÊME CODE pour DLL/SO/WASM ! + +class SchedulerModule : public IModule { +public: + json process(const json& input) override { + // Logique pure (200-300 lignes) + if (IsProcrastinating(input)) { + return { + {"event", "intervention_needed"}, + {"urgency", "high"} + }; + } + return {{"status", "ok"}}; + } + + void setConfiguration(const IDataNode& config, + IIO* io, + ITaskScheduler* scheduler) override { + m_io = io; + m_io->subscribe("task_changed", [this](const json& e) { + process(e); + }); + } + + json getHealthStatus() override { + return {{"status", "healthy"}}; + } + + void shutdown() override { /* cleanup */ } + +private: + IIO* m_io = nullptr; +}; + +// ======== EXPORTS MULTI-TARGET ======== + +#ifdef _WIN32 +// Export DLL Windows (dev local) +extern "C" __declspec(dllexport) +IModule* CreateModule() { + return new SchedulerModule(); +} +#endif + +#ifdef __linux__ +// Export SO Linux (serveur Docker) +extern "C" +IModule* CreateModule() { + return new SchedulerModule(); +} +#endif + +#ifdef __EMSCRIPTEN__ +// Export WASM (client browser) +#include +extern "C" { + EMSCRIPTEN_KEEPALIVE + const char* ProcessScheduler(const char* inputJson) { + static SchedulerModule module; + json input = json::parse(inputJson); + json result = module.process(input); + static std::string output = result.dump(); + return output.c_str(); + } +} +#endif +``` + +**Compilation :** +```cmake +# modules/scheduler/CMakeLists.txt (extrait) +# Target 1: DLL (Windows) +add_library(scheduler MODULE src/SchedulerModule.cpp) +set_target_properties(scheduler PROPERTIES SUFFIX ".dll") + +# Target 2: SO (Linux) +add_library(scheduler MODULE src/SchedulerModule.cpp) +set_target_properties(scheduler PROPERTIES SUFFIX ".so") + +# Target 3: WASM (Browser) +add_executable(scheduler src/SchedulerModule.cpp) +set_target_properties(scheduler PROPERTIES SUFFIX ".wasm") +target_link_options(scheduler PRIVATE -s WASM=1) +``` + +**Build Script :** +```powershell +# scripts/build-all.ps1 +# Build DLL (dev Windows) +cmake -B build-windows -G "Visual Studio 17 2022" +cmake --build build-windows --config Release + +# Build SO (serveur Linux via Docker) +docker build -t aissia-backend -f docker/Dockerfile.backend . + +# Build WASM (client browser via Emscripten) +emcmake cmake -B build-wasm +emmake make -C build-wasm +``` + +**Résultat :** +``` +build-windows/modules/scheduler.dll (Dev local) +build-linux/modules/scheduler.so (Serveur Docker) +build-wasm/modules/scheduler.wasm (Client PWA) +``` + +#### Communication Client-Serveur +- **Protocole** : WebSocket (temps réel) + REST API (fallback) +- **Format** : JSON pour messages +- **Events Pub/Sub** : + - Client → Serveur : `task_created`, `user_action`, `sync_request` + - Serveur → Client : `ai_suggestion`, `sync_complete`, `notification` +- **Authentification** : JWT tokens (localStorage client) +- **Sécurité** : HTTPS/WSS obligatoire, CORS configuré + +--- + +### 4.5 Configuration gameconfig.json (Unifié) + +**Un seul fichier de configuration bascule entre les deux modes :** + +```json +{ + "deployment_modes": { + "local_dev": { + "enabled": true, + "description": "Dev Windows local avec hot-reload WarFactory", + "modules": [ + {"name": "MonitoringModule", "type": "dll", "execution": "local"}, + {"name": "SchedulerModule", "type": "dll", "execution": "local"}, + {"name": "AIModule", "type": "dll", "execution": "local"}, + {"name": "VoiceModule", "type": "dll", "execution": "local"}, + {"name": "StorageModule", "type": "dll", "execution": "local"}, + {"name": "UIModule", "type": "dll", "execution": "local"} + ], + "io": "IntraIO", + "engine": "DebugEngine", + "ui": "ImGui", + "storage": "SQLite", + "cost": "$0" + }, + + "production_pwa": { + "enabled": false, + "description": "PWA React + WASM client + Serveur Docker", + "client_modules_wasm": [ + {"name": "SchedulerModule", "file": "scheduler.wasm"}, + {"name": "VoiceModule", "file": "voice.wasm"}, + {"name": "StorageModule", "file": "storage.wasm"} + ], + "server_modules_so": [ + {"name": "AuthModule", "file": "auth.so"}, + {"name": "SyncModule", "file": "sync.so"}, + {"name": "AIProxyModule", "file": "ai-proxy.so"}, + {"name": "MonitoringModule", "file": "monitoring.so"} + ], + "io": "WebSocket", + "engine": "HighPerfEngine", + "ui": "React PWA", + "storage": "PostgreSQL + IndexedDB", + "cost": "$3-5/mois" + } + }, + + "active_mode": "local_dev" +} +``` + +**Bascule entre modes :** +```json +// Mode local (MVP - Phase 1 OBLIGATOIRE) +"active_mode": "local_dev" + +// Mode production (Phase 3 CONDITIONNEL - seulement si Phase 2 validée) +"active_mode": "production_pwa" +``` + +--- + +### 4.6 Risques Techniques de l'Architecture Multi-Target + +**⚠️ ATTENTION : Cette section documente les risques identifiés de la compilation multi-target (DLL/SO/WASM).** + +#### Risques Majeurs Identifiés + +| Risque | Impact | Probabilité | Mitigation Proposée | +|--------|--------|-------------|---------------------| +| **Complexité CMake multi-target** | Élevé | Moyenne | Phase 2 POC validera faisabilité avant engagement | +| **Maintenance 3 builds par module** | Moyen | Élevée | Si trop complexe, rester mode `local_dev` uniquement | +| **Performance WASM insuffisante** | Élevé | Moyenne | Benchmarks Phase 2, accepter 2x overhead max | +| **Debugging WASM complexe** | Moyen | Élevée | Développer en DLL (facile), compiler WASM uniquement prod | +| **Différences comportementales DLL/SO/WASM** | Élevé | Faible | Tests automatisés sur 3 targets, CI/CD obligatoire | +| **Emscripten limitations (threads, I/O)** | Moyen | Moyenne | Design modules sans dépendances système (pure logic) | +| **Overhead développement pipeline** | Moyen | Élevée | Si Phase 2 montre complexité excessive, ABANDONNER multi-target | + +#### Stratégie de Validation (Phase 2) + +**Avant tout engagement Phase 3, Phase 2 DOIT valider :** + +1. **POC Technique** (2-3 jours max) : + - Créer `HelloModule.cpp` minimal (IModule WarFactory) + - Compiler en `.dll` (Windows MSVC) + - Compiler en `.wasm` (Emscripten) + - Tester intégration React + WASM + - **Go/No-Go** : Si POC échoue ou trop complexe, ARRÊTER ici + +2. **Benchmark Performance** (1 jour) : + - Mesurer overhead WASM vs DLL natif + - Algorithme test : SchedulerModule (calculs intensifs) + - **Critère acceptation** : WASM < 2x DLL + - **Go/No-Go** : Si WASM > 2x, reconsidérer architecture + +3. **Évaluation Complexité Build** (1 jour) : + - Setup complet Emscripten + Docker + - Temps build 3 targets (DLL + SO + WASM) + - **Critère acceptation** : < 30 min build complet CI/CD + - **Go/No-Go** : Si build > 30 min, trop lent pour itérations + +#### Scénarios de Sortie + +**Si Phase 2 invalide multi-target :** + +- **Option A (recommandée)** : Rester 100% mode `local_dev` + - MVP fonctionnel DLL Windows uniquement + - $0 coût, 0.4ms hot-reload conservé + - Abandon PWA/WASM, focus usage perso desktop + +- **Option B** : Pivot vers architecture alternative + - Évaluer Electron (desktop cross-platform) + - Évaluer Flutter Desktop + - Réévaluer AlternativesAnalysis.md + +**⚠️ ACCEPTER L'ÉCHEC MULTI-TARGET :** +Le mode `local_dev` seul reste une excellente solution pour le besoin initial (hyperfocus management personnel). L'architecture multi-target est un BONUS, pas une nécessité. + +--- + +### 4.7 Architecture Système (Hypothétique - Si Phase 3) + +``` +┌───────────────────────────────────────────────────────────────┐ +│ DÉVELOPPEMENT (Windows PC) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Visual Studio 2022 / VSCode │ │ +│ │ /modules/ │ │ +│ │ ├─ SchedulerModule/ (C++) │ │ +│ │ ├─ StorageModule/ (C++) │ │ +│ │ ├─ VoiceModule/ (C++) │ │ +│ │ └─ AIModule/ (C++) │ │ +│ │ │ │ +│ │ Build Scripts: │ │ +│ │ → .dll (Windows dev local) │ │ +│ │ → .so (Linux serveur via Docker) │ │ +│ │ → .wasm (Browser client via Emscripten) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────────────────┘ + │ + │ Git Push + ▼ +┌───────────────────────────────────────────────────────────────┐ +│ CI/CD (GitHub Actions) │ +│ 1. Build backend Linux (Docker) │ +│ 2. Build modules WASM (Emscripten) │ +│ 3. Deploy backend → fly.io │ +│ 4. Deploy PWA + WASM → Vercel │ +└───────────────────────────────────────────────────────────────┘ + │ + ┌────────────────┴────────────────┐ + ▼ ▼ +┌────────────────────────┐ ┌───────────────────────────────┐ +│ SERVEUR (fly.io) │ │ CLIENT (PWA - Vercel) │ +│ Docker Linux │ │ React + TypeScript │ +│ ┌──────────────────┐ │ │ ┌─────────────────────────┐ │ +│ │ Backend C++ │ │ │ │ UI Components (React) │ │ +│ │ - AuthModule.so │ │ │ │ - Dashboard │ │ +│ │ - SyncModule.so │ │ │ │ - Task management │ │ +│ │ - AIProxy.so │ │ │ │ - Settings │ │ +│ │ - Monitoring.so │ │ │ └─────────────────────────┘ │ +│ │ - WebSocket API │ │ │ │ +│ └──────────────────┘ │ │ ┌─────────────────────────┐ │ +│ PostgreSQL/SQLite │ │ │ WASM Modules (C++) │ │ +│ Port: 8080 (WSS) │ │ │ - scheduler.wasm │ │ +└────────┬───────────────┘ │ │ - voice.wasm │ │ + │ │ │ - storage.wasm │ │ + │ WebSocket │ │ (IndexedDB wrapper) │ │ + └────────────────────┤ └─────────────────────────┘ │ + │ │ + │ Service Worker (offline) │ + │ Web Push API (notifications) │ + └────────────────────────────────┘ + │ + ┌────────────────────┼────────────────────┐ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ Windows PC │ │ iPhone │ │ Android │ + │ (Chrome PWA) │ │ (Safari PWA) │ │ (Chrome PWA) │ + └──────────────┘ └──────────────┘ └──────────────┘ + │ │ │ + └────────────────────┴────────────────────┘ + │ + Tous accèdent à la même PWA + https://aissia.app + +┌───────────────────────────────────────────────────────────────┐ +│ SERVICES EXTERNES │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Claude Haiku 4.5 API (Anthropic) │ │ +│ │ - Appelé UNIQUEMENT par le serveur (API key sécurisée) │ │ +│ │ - Planning suggestions, conversational AI │ │ +│ │ - Coût: ~$10-20/mois usage personnel │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────────────────┘ +``` + +### 4.8 Répartition Client/Serveur (Hypothétique - Phase 3 uniquement) + +| Module | Où ? | Raison | Impact Coût Serveur | +|--------|------|--------|---------------------| +| **SchedulerModule** | ✅ Client (WASM) | Algorithmes purs, pas d'I/O | **Économie $$$** | +| **VoiceModule** | ✅ Client (Web Speech API) | TTS/STT natif browser | **Économie $$$** | +| **StorageModule** | 🔀 Hybrid | IndexedDB client + PostgreSQL serveur | **Économie $$** | +| **UIModule** | ✅ Client (React) | Rendu interface | **Économie $$$** | +| **AIModule** | ❌ Serveur uniquement | Sécurité API key Claude | Nécessaire | +| **AuthModule** | ❌ Serveur uniquement | Sécurité credentials | Nécessaire | +| **SyncModule** | ❌ Serveur uniquement | Base de données centrale | Nécessaire | +| **MonitoringModule** | ❌ Serveur uniquement | Tracking apps desktop impossible en browser | Optionnel | + +**Résultat :** +- **70% du processing sur client** (gratuit pour l'utilisateur) +- **Serveur minimaliste** : Auth + Sync + AI proxy + Monitoring +- **Coût serveur** : $3-5/mois au lieu de $20-30/mois + +### 4.9 Communication Client-Serveur (Hypothétique - Phase 3 uniquement) + +**WebSocket Events (Temps Réel) :** + +```typescript +// Client PWA → Serveur +{ + "event": "task_created", + "data": { + "task_id": "123", + "title": "Finir le CDC", + "priority": "high" + } +} + +// Serveur → Client PWA +{ + "event": "ai_suggestion", + "data": { + "message": "Tu devrais faire une pause, ça fait 2h que tu codes", + "urgency": "medium", + "actions": ["dismiss", "take_break"] + } +} +``` + +**Module WASM (Client-side) :** + +```cpp +// SchedulerModule.cpp (compilé en .wasm) +extern "C" { + // Exporté vers JavaScript + EMSCRIPTEN_KEEPALIVE + bool IsProcrastinating(const char* currentApp, const char* tasksJson) { + // Logique pure C++, tourne dans le browser + json tasks = json::parse(tasksJson); + return CheckProcrastination(currentApp, tasks); + } +} +``` + +```typescript +// Frontend React appelle le module WASM +import schedulerModule from './wasm/scheduler.wasm'; + +const isProcrastinating = schedulerModule.IsProcrastinating( + 'steam.exe', + JSON.stringify(currentTasks) +); + +if (isProcrastinating) { + // Affiche alerte côté client, pas besoin du serveur ! + showNotification('Retourne au travail !'); +} +``` + +**Avantages de cette architecture :** +- ✅ Réactivité instantanée (pas de latence réseau) +- ✅ Fonctionne offline (modules WASM = autonomes) +- ✅ Coûts serveur minimaux +- ✅ Scalabilité : 1000 utilisateurs = même coût serveur + +### 4.10 Modèle de Données (Simplifié) + +``` +User +- id, email, password_hash, created_at +- settings (JSON: notifications, ai_proactivity_level, etc.) + +Task +- id, user_id, title, description +- priority (high/medium/low) +- estimated_duration, actual_duration +- deadline, status (todo/in_progress/done) +- tags[], category + +TimeEntry +- id, user_id, task_id +- start_time, end_time, duration +- auto_tracked (boolean) + +AIInteraction +- id, user_id, timestamp +- type (suggestion/alert/chat) +- context (JSON), ai_response + +Schedule +- id, user_id, date +- planned_tasks[] (ordered list) +- ai_generated (boolean) +``` + +--- + +## 5. Contraintes et Exigences + +### 5.1 Contraintes Techniques +- ✅ **Dev Windows uniquement** : Développement, debug, et tests 100% sur Windows +- ✅ **Cross-platform automatique** : Via Docker (serveur) et WASM (client) +- ✅ **Mobile via PWA** : Progressive Web App (pas d'app native Android/iOS) +- ✅ **Performance** : WASM ~2x plus lent que C++ natif (acceptable) +- ✅ **Offline-first** : Service Workers + IndexedDB + modules WASM autonomes +- ✅ **Sécurité** : JWT auth, HTTPS/WSS obligatoire, API keys serveur uniquement +- ✅ **Pipeline stable** : GitHub Actions (reproductible, pas de surprises) + +### 5.2 Contraintes Budget +- 💰 **Mode local_dev (MVP)** : $0 hosting + $10-20/mois Claude API = **$10-20/mois total** +- 💰 **Mode production_pwa (Phase 3)** : + - Serveur fly.io : $3-5/mois + - Frontend Vercel : $0 (gratuit) + - Claude API : $10-20/mois + - **Total** : $13-25/mois +- 🎯 **Optimisation production_pwa** : 70% processing client → économie serveur massive +- 📊 **Monétisation future** : Freemium (gratuit: 50 requêtes IA/jour, client-side illimité) + +### 5.3 Contraintes Développement +- 🔄 **Itérations courtes** : Cycles de 1-2 semaines +- ✅ **Versions fonctionnelles** : Chaque release doit être utilisable +- 🪟 **Dev Windows-first** : Zéro VM/émulateurs, tout sur Windows +- 🐋 **Docker Desktop** : Seul prérequis pour builds cross-platform +- 🧪 **Tests** : Jest (frontend), Google Test (backend C++) +- 📝 **Documentation** : README, architecture diagrams, module interfaces +- 🤖 **CI/CD automatique** : GitHub Actions (build + deploy automatique) + +--- + +## 6. Planification (Roadmap) + +**⚠️ IMPORTANT - Structure des phases :** +- **Phase 0 + Phase 1 = OBLIGATOIRES** : Cible MVP mode `local_dev` +- **Phase 2 = VALIDATION** : POC multi-target (Go/No-Go décision) +- **Phase 3 = CONDITIONNELLE** : Seulement SI Phase 2 validée +- **Phase 4 = HYPOTHÉTIQUE** : Dépend succès Phase 3 + +### Phase 0 - Setup (Semaine 0) - OBLIGATOIRE +- [ ] Copier interfaces WarFactory (IModule, IEngine, IIO, ITaskScheduler, IDataTree) +- [ ] Structure projet modules/ (MonitoringModule/, SchedulerModule/, etc.) +- [ ] CMakeLists.txt pour DLL Windows (Phase 1 uniquement, SO/WASM Phase 2+) +- [ ] gameconfig.json initial (mode `local_dev` uniquement) +- [ ] Scripts build Windows (build-dll.ps1) +- [ ] ⚠️ Setup Docker Desktop (OPTIONNEL - seulement si Phase 2) +- [ ] ⚠️ Setup Emscripten SDK (OPTIONNEL - seulement si Phase 2) + +### Phase 1 - MVP Local (Semaines 1-2) - OBLIGATOIRE + +**Objectif** : Version locale fonctionnelle avec hot-reload WarFactory (mode `local_dev` DLL uniquement) + +**Core Engine :** +- [ ] aissia-core.exe (WarFactory engine) + - IEngine (DebugEngine) + - IModuleSystem (SequentialModuleSystem) + - IIO (IntraIO) + - ICoordinationModule (charge gameconfig.json) + +**Modules DLL (Windows) :** +- [ ] MonitoringModule.dll + - Win32 API (GetForegroundWindow) + - Tracking temps par application + - Publish event "app_changed" +- [ ] SchedulerModule.dll + - Planning algorithmes basiques + - Détection procrastination contextuelle + - Publish event "intervention_needed" +- [ ] AIModule.dll + - Claude Haiku 4.5 API integration + - Context building pour suggestions + - Subscribe "intervention_needed", publish "ai_response" +- [ ] VoiceModule.dll + - SAPI TTS (Windows text-to-speech) + - Whisper.cpp STT (speech-to-text local) + - Subscribe "ai_response", speak() +- [ ] StorageModule.dll + - SQLite local (aissia.db) + - CRUD tâches, historique, métriques +- [ ] UIModule-ImGui.dll + - Dear ImGui interface + - Dashboard planning + - Settings + +**Bénéfices Phase 1 :** +- ✅ Hot-reload 0.4ms +- ✅ Développement ultra-rapide +- ✅ $0 coût (tout local) +- ✅ Dogfooding immédiat (usage perso) +- ✅ Interventions vocales proactives (besoin core) + +--- + +### Phase 2 - POC WASM (Semaines 3-4) - VALIDATION (Go/No-Go) + +**⚠️ CRITIQUE : Cette phase décide si Phase 3 est viable ou non.** + +**Objectif** : Valider faisabilité multi-target (WASM) + performance acceptable + +**⚠️ RÈGLE : Phase 1 DOIT être complétée et fonctionnelle AVANT Phase 2.** + +**POC Expérimental :** +- [ ] Compiler SchedulerModule.wasm (test WASM simple) +- [ ] Frontend React minimal (Vite + TypeScript) +- [ ] Intégrer scheduler.wasm dans React +- [ ] Tester performance WASM vs DLL (benchmark) +- [ ] Évaluer complexité build Emscripten + +**Validation Phase 2 (Go/No-Go) :** +- ⚠️ Performance WASM acceptable pour scheduler ? (< 2x DLL) +- ⚠️ Complexité build supportable ? (< 30 min CI/CD) +- ⚠️ Debugging WASM pas trop problématique ? +- ⚠️ Intérêt réel mobile PWA validé par usage Phase 1 ? + +**🚦 Décision Go/No-Go :** +- **✅ GO (Phase 3)** : Si TOUS les critères validés ET besoin mobile confirmé +- **❌ NO-GO (Arrêt)** : Si UN SEUL critère invalidé → Rester mode `local_dev` définitif + +**⚠️ NO-GO n'est PAS un échec :** Mode `local_dev` seul répond parfaitement au besoin initial. + +--- + +### Phase 3 - Production PWA (Semaines 5-8) - CONDITIONNELLE (Seulement si Phase 2 GO) + +**⚠️ ATTENTION : Cette phase n'existe QUE si Phase 2 validée.** + +**Objectif** : Déploiement cloud avec PWA React + WASM client + +**Backend Docker (Serveur SO) :** +- [ ] auth.so (JWT authentication) +- [ ] sync.so (PostgreSQL synchronisation) +- [ ] ai-proxy.so (Claude API proxy, sécurise API key) +- [ ] websocket-server.so (API temps réel pour clients) +- [ ] Dockerfile backend (Alpine Linux) +- [ ] Deploy fly.io ($3-5/mois) + +**Frontend PWA React :** +- [ ] UI complète (Tailwind + shadcn/ui) +- [ ] scheduler.wasm intégré +- [ ] voice.wasm (Web Speech API) +- [ ] storage.wasm (IndexedDB wrapper) +- [ ] Service Workers (offline) +- [ ] Web Push notifications +- [ ] PWA manifest (installable) +- [ ] Deploy Vercel (gratuit) + +**CI/CD GitHub Actions :** +- [ ] Build multi-target automatique (DLL/SO/WASM) +- [ ] Deploy backend fly.io +- [ ] Deploy frontend Vercel +- [ ] Tests automatisés + +**Mode Dual Opérationnel :** +- Développement Windows : `local_dev` (DLL + ImGui + hot-reload) +- Production : `production_pwa` (WASM + React + Cloud) + +--- + +### Phase 4 - Optimisation & Monétisation (Semaines 9-12) - HYPOTHÉTIQUE (Dépend Phase 3) +- [ ] Système Freemium (rate limiting IA) +- [ ] Paiements Stripe (backend) +- [ ] Landing page marketing +- [ ] Beta publique (early access) +- [ ] Optimisations performance WASM +- [ ] Monitoring & observability (Sentry, Prometheus) + +--- + +## 7. Risques et Mitigations + +| Risque | Probabilité | Impact | Mitigation | +|--------|-------------|--------|------------| +| Coût IA trop élevé | Moyenne | Élevé | Caching côté serveur, rate limiting, 70% processing client | +| Complexité WASM | Moyenne | Moyen | Commencer simple (scheduler.wasm), monter progressivement | +| Performance WASM insuffisante | Faible | Moyen | WASM ~2x C++ natif acceptable, fallback serveur possible | +| Docker/Emscripten setup difficile | Faible | Faible | Scripts d'installation automatiques, docs détaillées | +| Adoption utilisateur faible | Élevée | Élevé | Dogfooding (usage perso), beta privée, feedback loops courts | +| Problèmes de privacy | Faible | Critique | Processing client-side, JWT auth, HTTPS/WSS, pas de tracking | +| PWA pas assez "native" | Moyenne | Moyen | Web Push, Service Workers, install prompt, works offline | +| Hyperfocus sur le dev du projet | Élevée | Moyen | Utiliser l'app elle-même pour se contraindre 😅 | + +--- + +## 8. KPIs de Succès + +### Phase 1 - MVP Local +- ✅ aissia-core.exe fonctionnel (WarFactory engine) +- ✅ 6 modules DLL opérationnels (monitoring, scheduler, ai, voice, storage, ui) +- ✅ Hot-reload 0.4ms validé +- ✅ Utilisation personnelle quotidienne (dogfooding) +- ✅ Réduction mesurable de l'hyperfocus (via tracking) +- ✅ Interventions vocales proactives fonctionnelles + +### Phase 2 - POC WASM (Validation) +- ⚠️ SchedulerModule.wasm compilé et fonctionnel +- ⚠️ Performance WASM acceptable (< 2x C++ natif) +- ⚠️ Intégration React + WASM validée +- ⚠️ Décision Go/No-Go pour Phase 3 + +### Phase 3 - Production PWA (Si Phase 2 validée) +- 📊 PWA déployée et fonctionnelle (desktop + mobile) +- 📊 100 utilisateurs actifs (beta privée) +- 📊 80%+ retention hebdomadaire +- 📊 NPS > 50 +- 💰 $500 MRR (objectif monétisation) +- 🚀 Coût serveur < $10/mois pour 100 users (grâce à WASM client-side) +- ⚡ PWA installée sur 50%+ des devices utilisateurs + +--- + +## 9. Stack Finale Retenue + +### Architecture Hybride : WarFactory + Multi-Target (DLL/SO/WASM) + +**Concept Révolutionnaire :** +``` +MÊME code C++ (IModule WarFactory) + ↓ CMake multi-target +├─ .dll (Dev Windows local - Hot-reload 0.4ms) +├─ .so (Serveur Linux Docker - Phase 3) +└─ .wasm (Client PWA browser - Phase 3) +``` + +**Mode 1 : `local_dev` (Phase 1 MVP) :** +- **Dev** : Windows 10/11, Visual Studio 2022, WarFactory engine +- **Modules** : DLL (monitoring, scheduler, ai, voice, storage, ui-imgui) +- **UI** : Dear ImGui (C++, intégré) +- **Storage** : SQLite local (aissia.db) +- **Coût** : $0 hosting + $10-20/mois Claude API + +**Mode 2 : `production_pwa` (Phase 3 - Optionnel) :** +- **Backend** : C++ modules (.so), Docker Linux, fly.io ($3-5/mois) +- **Frontend** : React + TypeScript, WASM modules, Vercel (gratuit) +- **Mobile** : PWA installable (pas d'app native) +- **Coût** : $3-5/mois serveur + $10-20/mois Claude API + +**Pourquoi cette architecture hybride :** +- ✅ **Réutilisation WarFactory** : Économie 3-4 semaines dev +- ✅ **Hot-reload 0.4ms** : Productivité maximale en dev local +- ✅ **Types stricts C++** : Pas de wildcode, interfaces bien définies +- ✅ **Évolution progressive** : Commence local ($0), migre cloud si besoin +- ✅ **Modules écrits UNE FOIS** : Compilés en DLL/SO/WASM automatiquement +- ✅ **Déploiement flexible** : gameconfig.json bascule entre modes +- ✅ **Coûts minimaux** : $0 en MVP, $3-5/mois optionnel production +- ✅ **Mobile optionnel** : PWA Phase 3 si besoin validé + +**Évolution par phases :** +- **Phase 0** : Setup projet (interfaces WarFactory, CMakeLists multi-target) +- **Phase 1 (MVP)** : Mode `local_dev` (DLL + ImGui + SQLite local) +- **Phase 2 (Validation)** : POC WASM (test performance + faisabilité) +- **Phase 3 (Production)** : Mode `production_pwa` (WASM + React + Cloud) SI validé + +**Pourquoi PAS d'autres options :** +- ❌ **Pas de WarFactory** : Perte 3-4 semaines dev + hot-reload 0.4ms +- ❌ **Cloud obligatoire dès MVP** : Coûts permanents + complexité inutile +- ❌ **App native mobile** : Trop complexe, pas prioritaire +- ❌ **Flutter/Node.js** : Pas de réutilisation WarFactory + wildcode +- ❌ **Electron seul** : Poids énorme, pas cross-platform mobile + +--- + +## 10. Prochaines Étapes + +### Immédiat (Aujourd'hui) +1. ✅ **CDC draft finalisé** : Architecture proposée et documentée +2. **Validation faisabilité technique** : + - POC : Hello World C++ → WASM + - Test setup Emscripten sur Windows + - Vérifier performance WASM acceptable +3. **Création structure projet** (si POC validé) : + ``` + aissia/ + ├── modules/ # C++ modules sources + │ ├── SchedulerModule/ + │ ├── StorageModule/ + │ ├── AIProxyModule/ + │ └── AuthModule/ + ├── backend/ # Serveur C++ Docker + ├── frontend/ # PWA React + ├── scripts/ # Build scripts (build-all.ps1) + ├── .github/workflows/ # CI/CD + └── docs/ # Documentation + ``` +3. **Setup environnement Windows** : + - Installer Docker Desktop + - Installer Emscripten SDK + - Tester builds multi-target (DLL/SO/WASM) + +### Cette Semaine (Phase 0) +4. **Boilerplates** : + - Backend C++ minimal (CMake, WebSocket server) + - Frontend React minimal (Vite + TypeScript) + - Premier module WASM (hello world) +5. **CI/CD GitHub Actions** : + - Build automatique DLL/SO/WASM + - Deploy fly.io (backend) + Vercel (frontend) +6. **gameconfig.json initial** : + - Configuration modules basique + - Définir stratégie déploiement (client vs serveur) + +### Semaine Prochaine (Phase 1) +7. **MVP fonctionnel** : + - Auth + CRUD tâches + - scheduler.wasm opérationnel + - PWA déployée et accessible + +--- + +## Notes + +### Principes de Design +- Ce projet répond à un besoin personnel réel +- La proactivité de l'IA est **critique** (pas juste un assistant réactif) +- L'hyperfocus est le problème #1 à résoudre +- Commercialisation = bonus, pas l'objectif principal du MVP + +### Contraintes Retenues (Draft) +- 🎯 **Dev 100% Windows** (confort dev prioritaire) +- 🎯 **Cross-platform automatique** (Docker + WASM) +- 🎯 **Mobile via PWA** (pas de dev natif Android/iOS) +- 🎯 **Coûts minimaux** (70% client-side processing) +- 🎯 **Pipeline stable** (GitHub Actions, zéro surprise) + +### Décisions Architecturales Proposées (À valider) +1. **Modules C++ partagés** : 1 codebase → DLL/SO/WASM +2. **Client-first** : Déporter calculs sur client pour économiser serveur +3. **PWA installable** : Équivalent app native sans complexité dev +4. **gameconfig.json** : Configuration flexible du déploiement + +--- + +**Status:** 📐 **Architecture Hybride Proposée** - En phase de conception et validation (POC requis) +**Version:** 0.4 - Architecture Hybride Proposée (Hypothétique) +**Date:** 27 octobre 2025 + +### Proposition Architecturale (À Valider) + +**Architecture Proposée : Hybride WarFactory + Multi-Target Conditionnel** + +**Concept (Hypothétique) :** +- Un seul code C++ (IModule WarFactory) +- Compilé en 3 targets : DLL (dev local OBLIGATOIRE), SO (serveur CONDITIONNEL), WASM (browser CONDITIONNEL) +- Deux modes de déploiement : `local_dev` (Phase 1 MVP OBLIGATOIRE) et `production_pwa` (Phase 3 CONDITIONNELLE) + +**Avantages validés Phase 1 :** +- ✅ Réutilise WarFactory (économie 3-4 semaines validée) +- ✅ Hot-reload 0.4ms en mode local (validé WarFactory) +- ✅ $0 coût en mode local (garanti) +- ✅ Types stricts C++ (validé) + +**Avantages hypothétiques Phase 3 (À valider Phase 2) :** +- ⚠️ Évolution progressive vers cloud si besoin (hypothétique) +- ⚠️ Multi-target DLL/SO/WASM viable (à tester) + +**Questions ouvertes avant implémentation :** +- ⚠️ Faisabilité réelle compilation multi-target (DLL/SO/WASM) ? +- ⚠️ Complexité CMakeLists.txt multi-target supportable ? +- ⚠️ Performance WASM réellement acceptable (~2x C++ natif) ? +- ⚠️ Effort réel intégration React + WASM ? +- ⚠️ gameconfig.json peut vraiment basculer entre modes sans friction ? + +### Prochaines Étapes + +**🎯 PRIORITÉ ABSOLUE - Phase 1 (Mode local_dev uniquement) :** + +1. **Setup Phase 0** : + - Interfaces WarFactory + - Structure projet modules/ + - CMakeLists.txt DLL Windows uniquement (PAS multi-target encore) + - gameconfig.json mode `local_dev` uniquement + +2. **Implémentation Phase 1** : + - aissia-core.exe (WarFactory engine) + - 6 modules DLL (monitoring, scheduler, ai, voice, storage, ui-imgui) + - Validation dogfooding usage personnel + +**⚠️ SEULEMENT si Phase 1 complète ET besoin mobile confirmé → Phase 2 (POC WASM)** + +**Phase 2 (Validation multi-target) - CONDITIONNEL :** +- POC hello-world .dll + .wasm +- Benchmark performance WASM vs DLL +- Décision Go/No-Go pour Phase 3 + +**Phase 3+ - CONDITIONNEL (Dépend résultat Phase 2)** + +### État Actuel + +- 📝 CDC rédigé avec architecture hybride proposée (v0.4) +- 📝 Alternatives analysées et documentées (AlternativesAnalysis.md) +- 📚 Documentation WarFactory copiée dans docs/ +- 📝 Retour externe Claude reçu et intégré +- 📝 Section risques techniques ajoutée +- ⏸️ **Phase 1 (local_dev) validée** : Architecture WarFactory DLL prouvée +- ⚠️ **Phases 2-3 (multi-target) hypothétiques** : POC requis avant engagement +- ⏸️ **Pas encore d'implémentation** : Conception et validation uniquement + +### Notes Importantes + +- **✅ Phase 1 = GO** : Mode `local_dev` est validé et sera implémenté +- **⚠️ Phases 2-3 = CONDITIONNEL** : Multi-target reste hypothétique jusqu'à POC Phase 2 +- **Ne PAS setup Emscripten/Docker avant Phase 2** : Éviter complexité prématurée +- **Architecture multi-target = proposition, pas garantie** : Peut être abandonnée +- **Focus MVP Phase 1** : Livrer version locale fonctionnelle d'abord +- **Accepter local_dev seul comme succès** : Si multi-target invalide, pas un échec diff --git a/docs/00-overview/README.md b/docs/00-overview/README.md new file mode 100644 index 0000000..33d3aac --- /dev/null +++ b/docs/00-overview/README.md @@ -0,0 +1,161 @@ +# Documentation Warfactory + +## 🏭 Vue d'Ensemble du Projet + +Warfactory est un jeu de simulation industrielle militaire inspiré de Factorio, utilisant une **architecture modulaire révolutionnaire** optimisée pour le développement avec **Claude Code**. + +## 📚 Documentation Principale + +### Architecture & Design +- **[Vue Ensemble](vue-ensemble.md)** - Vision, philosophie et design du jeu +- **[Architecture Technique](architecture-technique.md)** - Multi-serveur, engines, spécifications +- **[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 + +### Systèmes de Jeu +- **[Gameplay Industriel](gameplay-industriel.md)** - Production, ressources, optimisation +- **[Système Militaire](systeme-militaire.md)** - Design véhicules, combat +- **[Économie & Logistique](economie-logistique.md)** - Marchés, chaînes d'approvisionnement +- **[Mécaniques de Jeu](mecaniques-jeu.md)** - Recherche, progression, administration + +### Systèmes Techniques +- **[Systèmes Techniques](systemes-techniques.md)** - Tiles, mémoire, chunks +- **[Map System](map-system.md)** - Génération procédurale, 218+ éléments +- **[Arbre Technologique](arbre-technologique.md)** - 3000+ technologies +- **[Métriques Joueur](metriques-joueur.md)** - Analytics (3.1GB par partie) + +### Résolution de Problèmes +- **[Coherence Problem](coherence-problem.md)** - Contradictions résolues +- **[Questions Ouvertes](questions-ouvertes.md)** - 11 items à résoudre + +### Planification +- **[Contexte Narratif](contexte-narratif.md)** - Background et univers +- **[DLC Prévus](dlc-prevus.md)** - Contenus futurs +- **[Updates Long Terme](updates-long-terme.md)** - Roadmap + +## 🚀 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 ! +``` + +## 🎮 Vision du Jeu + +### Concept Core +- **Factory + Military** : Production industrielle + doctrine militaire +- **Échelles multiples** : Local (usines) → Régional (logistique) → Global (diplomatie) +- **Progression** : PMC → Entreprise → Corporation → Super-pouvoir + +### Mécaniques Principales +1. **Production Factorio-like** : Chaînes d'assemblage, optimisation +2. **Design véhicules** : Grille irrégulière, placement composants +3. **Combat auto-battler** : Frontlines persistantes, supervision joueur +4. **Économie dynamique** : Marchés, inflation, cycles économiques + +## 📖 Comment Utiliser Cette Documentation + +### Pour les Développeurs +1. **Commencer par** : [Architecture Modulaire](architecture-modulaire.md) +2. **Puis** : [Claude Code Integration](claude-code-integration.md) +3. **Ensuite** : [Vue Ensemble](vue-ensemble.md) pour le contexte + +### Pour les Game Designers +1. **Commencer par** : [Vue Ensemble](vue-ensemble.md) +2. **Puis** : [Gameplay Industriel](gameplay-industriel.md) +3. **Ensuite** : [Système Militaire](systeme-militaire.md) + +### 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 + +## 🔄 Statut du Projet + +### ✅ Complété +- **Design complet** : 15+ documents de spécification +- **Architecture modulaire** : Triple interface implémentée +- **Build system** : CMake + defensive programming +- **Structure modules** : Factory, Economy, Logistic + +### 🔄 En Cours +- **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 +- **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 Quick Reference + +```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 +``` + +## 🔧 Legacy Documentation + +### Ancienne Architecture (référence) +- **[Engines Documentation](./engines/)** - Anciens engines (supplanté par modules) +- **[Client Documentation](./client/)** - Interface system +- **[Server Documentation](./serveur/)** - Coordination (supplanté par IEngine) + +Ces documents restent utiles pour comprendre le design original, mais l'implémentation actuelle utilise l'architecture modulaire. \ No newline at end of file diff --git a/docs/00-overview/contexte-narratif.md b/docs/00-overview/contexte-narratif.md new file mode 100644 index 0000000..d0ff545 --- /dev/null +++ b/docs/00-overview/contexte-narratif.md @@ -0,0 +1,100 @@ +# Contexte narratif + +## Inspiration Ukraine + +### Motivation morale +L'Ukraine parce qu'ils sont des héros, parce qu'ils meurent pour leur liberté et pour la nôtre. Sachant ce que je sais aujourd'hui, j'ai l'obligation morale de mettre en avant leur combat et leur valeur. + +Je l'oublie parfois mais la conclusion s'impose systématiquement. + +### Justification artistique +Effectivement il serait plus simple de faire un monde généré procéduralement ou whatever mais à travers l'art (ce JV) l'imaginaire collectif doit se souvenir qu'il y a des gens qui meurent pour leur liberté. + +De ce point de vue là, je pense qu'il devient injustifiable de drop l'Ukraine. + +### Origine du concept +Sans parler que c'est de leur combat qu'a été le concept de ce jeu. Je leur dois ce jeu et ma liberté à "faible prix (relativement parlant)" peut-être autant qu'à mes ancêtres. + +**SLAVA UKRAINI !** + +## Lore géopolitique + +### Contexte géopolitique +**Les russes les méchants c'est sûr !** + +**Scénarios géopolitiques** : +- Une victoire russe en Ukraine provoque une agression chinoise sur Taiwan +- Une victoire russe en Ukraine prépare les prochains conflits en Europe + +### Intégration du lore réel +Le lore IRL doit être intégré autant que possible sans être overwhelming. + +### Problématique nucléaire +**Les nukes** : +Nations → nukes → utilisations ? → c'est chiant + +## Terrain de combat PMC + +### Zones d'opération +- Amérique du Sud dans les zones peu peuplées +- Madagascar +- Afrique +- Ouest de la Chine +- Russie +- Moyen-Orient + +## Scénarios de crise (Endgame Crisis) + +Au moins trois options avec leurs propres conséquences, mécaniques et variations. + +### 1. Zombie Apocalypse (militaire) + +**Défi principal** : Être surtout très rapide pour neutraliser les menaces quand elles apparaissent et de tenir les lignes si la manœuvre a échoué. + +**Types d'invasion** : +- **Romero zombie** : lent mais solide +- **Fast zombie** : rapide mais fragile +- **Bunny zombie** : Il saute c'est très fort mais très fragile +- **Classique + spéciaux** + +**Objectifs** : +- Garder le plus de gens en vie possible +- Trouver le(s) laboratoire(s) d'origine +- Y établir une base +- Rechercher le vaccin + +### 2. Invasion ET (militaire) + +**Caractéristiques de l'ennemi** : +- Technologie supérieure et très aérienne +- Résolument hostile +- Plusieurs stratégies possibles + +**Axes stratégiques possibles** : +- Destruction des systèmes énergétiques +- Destruction des assets navals +- Invasion des points stratégiques + +**Objectifs** : +- Surtout survivre +- La survie des états peut donner un sacré boost sur la défense planétaire +- Pour les vaincre il faut détruire le vaisseau mère ainsi que toutes les Ancres aliennes sur la planète + +### 3. Demon Portal Invasion (militaire) + +**Mécaniques** : +- Impossible de savoir où le portail suivant va s'ouvrir +- Il faut être prêt à agir vite et fort pour détruire les portails qui laisseront rentrer des démons tant qu'ils ne seront pas détruits + +**Stratégie ennemie** : +- Les démons ayant pour objectif de tout détruire +- La plupart des ouvertures de portail se feront dans les villes pour occasionner un max de dégâts + +**Mécaniques de pression** : +- C'est la course pour éviter les victimes +- Si trop de victimes → appelle des démons majeurs +- Et puis du démon mangeur de monde + +## Inspiration choix géopolitiques + +Peut-être s'inspirer d'Undertale pour la partie choix géopolitique. \ No newline at end of file diff --git a/docs/00-overview/dlc-prevus.md b/docs/00-overview/dlc-prevus.md new file mode 100644 index 0000000..cde7d30 --- /dev/null +++ b/docs/00-overview/dlc-prevus.md @@ -0,0 +1,15 @@ +# DLC Prévus + +## Inspiration RimWorld + +Le projet prévoit des extensions inspirées des DLC de RimWorld : + +### DLC Planifiés +- **Anomaly** - *À définir* +- **Biotech** - *À définir* +- **Ideology** - *À définir* +- **Odyssey** - *À définir* + +--- + +*Détails et mécaniques à développer ultérieurement* \ No newline at end of file diff --git a/docs/00-overview/vue-ensemble.md b/docs/00-overview/vue-ensemble.md new file mode 100644 index 0000000..0430913 --- /dev/null +++ b/docs/00-overview/vue-ensemble.md @@ -0,0 +1,268 @@ +# Warfactory : Vue d'Ensemble du Projet + +## Vision Globale + +**Warfactory** est un RTS/4X révolutionnaire fusionnant la profondeur industrielle de Factorio avec une simulation militaire réaliste et une économie mondiale dynamique. Le projet allie l'hommage moral à l'Ukraine avec une architecture technique modulaire ultra-innovante, optimisée pour le développement assisté par IA. + +**Innovation Centrale** : Un système économique où TOUS les acteurs (joueur, IA, États) suivent exactement les mêmes règles économiques, créant une simulation authentique et éducative des marchés mondiaux. + +## Concept de Jeu et Progression + +### De PMC à Géant Industriel +**Progression naturelle** : +- **Phase PMC** : Opérations irrégulières limitées, contrats d'État +- **Phase Industrielle** : Production civile/militaire, expansion géographique +- **Phase Géopolitique** : Influence mondiale, doctrines militaires, crises planétaires + +**Liberté d'échelle** : Philosophie bac à sable permettant au joueur de rester artisan local ou de défier Lockheed Martin selon ses ambitions. + +### Principe "Skip vs Optimize" +**Design fondamental** : Tous les systèmes peuvent être automatisés ou micro-gérés +- **Skip** : Solutions automatisées, efficacité réduite mais accessibles +- **Optimize** : Contrôle manuel complet, efficacité maximale +- **Hybride** : Mix selon préférences et contexte + +Exemples concrets : +- **Production** : Usines tout-en-un vs layouts Factorio optimisés +- **Combat** : IA tactique vs commande directe +- **Commerce** : Auto-trade vs négociation manuelle + +## Systèmes Industriels Intégrés + +### Architecture Factorio-like Avancée +**Cœur productif** : +- **Production modulaire** : Belts, inserters, factories avec évolution progressive +- **4 phases de complexité** : Mono → Multi-lanes → Bidirectionnel → Full Factorio +- **Qualité d'assemblage** : Placement optimal vs automatique avec pénalités réalistes + +**Innovation : Dual Production System** : +- **Production brute** : Transformation ressources primaires (minerai → plaques) +- **Assemblage précis** : Placement composants selon grilles vehicules + +### Flexibilité de Reconversion Industrielle +**Mécaniques réalistes** basées sur similarité des processus : +- **Facile** : Tables fer → Blindages (même matériaux, processus similaires) +- **Complexe** : Tables → Canons (précision usinage, alliages spéciaux) +- **Impossible** : Menuiserie → Production hydrogène (zéro overlap technologique) + +## Système Militaire Révolutionnaire + +### Conception de Véhicules par Grilles +**Innovation gameplay** : Design sur châssis irréguliers avec zones spécialisées + +**Interface intuitive** : +- **Pick & Place** : Drag & drop composants avec rotations A/E +- **Snap toggle** : R pour alignement grille +- **Validation temps réel** : Contraintes poids/énergie vérifiées durant placement + +**Diversité massive** : +- **Châssis nommés** : "Griffon" (chenillé), "Viper" (modulaire), "Fennec" (ultra-léger) +- **3 layers** : Châssis → Systèmes → Armes & Capteurs +- **1000+ composants** : Formes uniques, jamais carrées ni 1x1 + +### Système d'Amélioration Générique +**Améliorations universelles** stackables avec rendements décroissants : +- **High ROF** : +20% cadence, +40% chaleur (stack 1), puis +10%/+40% (stack 2) +- **Efficiency** : -20% consommation, -15% performance +- **Reliability** : +30% durabilité, -10% performance + +**Coût exponentiel** : 1.25^n per stack avec malus cumulatifs linéaires + +## Économie Mondiale Simulée + +### Égalité Économique Fondamentale +**RÈGLE NON-NÉGOCIABLE** : Le joueur n'a AUCUN privilège économique artificiel + +```cpp +// INTERDIT - Avantage joueur +if(agent.isPlayer()) order.cost *= 0.9f; + +// OBLIGATOIRE - Traitement égal +float cost = calculateRealTransportCost(order); +agent.processOrder(order, cost); +``` + +**Résultat** : Réussite basée sur compréhension économique réelle, pas sur privilèges artificiels. + +### Système de Companies avec Features +**Chaque IA company** a 2-4 features définissant ses capacités : +- **Domaines** : Metal, Electronic, Tank, Plane, Wood, Food, Engine, Cannon, Missile +- **Modificateurs** : Quality, Quantity, Speed, Cost, Modularity, Innovation + +**Exemple** : Company "Metal + Plane + Quantity + Electronic" excelle en avions métalliques de masse avec électronique embarquée, mais manque raffinement vs spécialistes Quality. + +### Transport Multi-Modal Réaliste +**Hiérarchie des coûts** (indicative) : +- **Maritime** : ~0.10€/kg (volume massif, ultra-économique) +- **Ferroviaire** : ~0.50€/kg (grandes quantités, infrastructure) +- **Aérien** : ~2.00€/kg (rapide, coûteux) +- **Routier** : ~5.00€/kg (flexible, dernier kilomètre) + +**Impact stratégique** : Localisation côtière = avantage économique 50x + +### Marchés Segmentés et Restrictions +**Types de marchés** : +- **Nationaux** : Par pays avec politiques douanières +- **Companies privés** : Accords bilatéraux +- **Blocs multinationaux** : UE, OTAN avec préférences +- **Mondial** : Marché libre avec sanctions possibles + +**Doubles verrous** : Companies ET États peuvent bloquer accès + +## Architecture Technique Révolutionnaire + +### Modularité Claude Code Optimisée +**Innovation développement** : Architecture modulaire révolutionnaire pour développement IA + +**Contraintes strictes** : +- **200-300 lignes max** par module (EXCEPTION : ProductionModule 500-800) +- **Build autonome** : `cd modules/tank/ && cmake .` - zéro dépendance parent +- **Hot-reload 0.4ms** : Modifications instantanées sans restart +- **Développement parallèle** : 3+ instances Claude Code simultanées + +### Interface System IMMUTABLE +**5 interfaces fondamentales** (JAMAIS modifiées une fois finalisées) : +```cpp +ICoordinationModule → Orchestrateur global système +IEngine → Coordination locale (Debug → HighPerf → DataOriented) +IModuleSystem → Stratégie d'exécution (Sequential → Threaded → Cluster) +IModule → Logique métier pure (TankModule.so, EconomyModule.so) +IIO → Communication (IntraIO → LocalIO → NetworkIO) +``` + +### Évolution Progressive Sans Régression +```cpp +// Phase 1 : Prototype +DebugEngine + SequentialModuleSystem + IntraIO + +// Phase 2 : Optimization +DebugEngine + ThreadedModuleSystem + IntraIO + +// Phase 3 : Production +HighPerfEngine + MultithreadedModuleSystem + LocalIO + +// Phase 4 : MMO Scale +DataOrientedEngine + ClusterModuleSystem + NetworkIO +``` + +**Avantage révolutionnaire** : Modules métier inchangés à travers toutes les phases ! + +## Carte et Exploration + +### Architecture Multi-Échelles +**2 niveaux discrets** : +- **Large Map** : Carte mondiale éditable, navigation node-based +- **Local Map** : Tiles 1m×1m, chunks 64×64, style Factorio précis + +### Génération Procédurale par Budget de Points +**Innovation système** : Chaque tile reçoit score (-10 à +10) équilibrant automatiquement risques/récompenses + +**218+ éléments** avec tendances régionales : +- **Bassins pétroliers** : Pétrole ×5 probabilité, terrains marécageux ×2 +- **Zones ex-minières** : Fer/charbon ×3-4, teritons ×8, pollution héritée ×3 +- **Régions forestières** : Forêt dense ×3-4, grottes ×2-3, pentes abruptes ×2 + +**Découverte stratifiée** : +- **Visible** : Relief, végétation, structures surface +- **Caché niveau 1** : Prospection géologique (gisements souterrains) +- **Caché niveau 2** : Magnétométrie (anomalies, structures enfouies) +- **Caché niveau 3** : Analyse NRBC (contaminations invisibles) + +## Arbre Technologique Massif + +### 3000+ Technologies pour Rejouabilité Infinie +**Principe découverte** : Player ne recherche PAS toutes les technologies ! +- **Discovery organique** : Breakthrough via gameplay naturel +- **10-50 techs éligibles** simultanément (jamais 3000) +- **Système de passerelles** : Expertise dans un domaine débloque prototypes dans autres + +**Exemple passerelles Châssis** : +``` +Métallurgie Avancée → [PROTOTYPE] Châssis Composite +Électronique → [PROTOTYPE] Châssis Smart +Moteur → [PROTOTYPE] Châssis Performance +``` + +## Contexte Narratif et Éthique + +### Hommage à l'Ukraine +**Motivation morale fondamentale** : "L'Ukraine parce qu'ils sont des héros, parce qu'ils meurent pour leur liberté et pour la nôtre." + +**Intégration authentique** : +- **Géographie réelle** : Ukraine, Europe sur carte mondiale +- **Contexte historique** : Zones post-industrielles, vestiges soviétiques +- **Enjeux géopolitiques** : Résistance démocratique vs autoritarisme + +### Crises Endgame +**3 scénarios apocalyptiques** avec mécaniques distinctes : +- **Zombie Apocalypse** : Vitesse de réaction, lignes de défense +- **Invasion ET** : Technologie supérieure aérienne, survie planétaire +- **Demon Portal** : Portails imprévisibles, course contre extermination + +## Interface Utilisateur Révolutionnaire + +### Système IUI Data-Agnostic +**Architecture générique** supportant tous types de contenu : +- **Enums type-safe** : `DataType::ECONOMY`, `RequestType::GET_PRICES` +- **Windowing hiérarchique** : Parent → Dock → Split → Tab → Window +- **Hybrid Sizing System** : Cibles pourcentage avec contraintes pixels + +**Layout professionnel** : Topbar économique + panel companies + carte stratégique + console + +## Performance et Scalabilité + +### Fréquences Modulaires Optimisées +- **ProductionModule** : 60Hz (frame-perfect factory) +- **TankModule Targeting** : 60Hz (combat réactif) +- **TankModule Movement** : 30Hz (positions) +- **TankModule Tactical** : 1Hz (décisions stratégiques) +- **EconomyModule** : 0.01-0.1Hz (cycles économiques) + +### Targets Performance +- **V1 Client** : 30+ fps, 10+ joueurs serveur +- **V2 Client** : 60+ fps, 100+ joueurs serveur avec prédiction locale + +## Philosophie de Design Avancée + +### "Complexity through Simplicity" +**Complexité AAA** émergeant de modules simples Claude-friendly : +- **Modules 200 lignes** = compréhension IA parfaite +- **Interactions complexes** = gameplay émergent sophistiqué +- **Testing granulaire** = fiabilité et débug facilités + +### Configuration vs Modding +**Philosophy YAGNI** : Configuration JSON couvre 90% besoins modding +```json +{ + "tank_mk2_custom": { + "health": 150, "speed": 30, + "weapons": ["cannon_105mm", "mg_coaxial"] + }, + "aggressive_ai": { + "engagement_range": 1000, + "retreat_threshold": 20 + } +} +``` + +## État Actuel et Roadmap + +### PRODUCTION-READY Achievements +- ✅ **Core Interfaces COMPLETE** : Architecture modulaire immutable finalisée +- ✅ **UI System COMPLETE** : IUI + ImGuiUI avec hybrid sizing révolutionnaire +- ✅ **Hot-Reload 0.4ms** : Workflow développement révolutionné +- ✅ **Configuration System** : IDataTree avec validation SHA256 +- ✅ **Cross-Platform Pipeline** : Linux dev → Windows .exe automatisé + +### Next Phases +1. **Phase 2** : Implémentations concrètes (DebugEngine, JSONDataTree) +2. **Phase 3** : Modules gameplay (ProductionModule, TankModule) +3. **Phase 4** : Integration économique et multijoueur + +## Conclusion : Une Vision Révolutionnaire + +Warfactory transcende les genres traditionnels en unifiant industrie, stratégie militaire et simulation économique authentique dans une architecture technique révolutionnaire. + +Le projet honore l'héroïsme ukrainien tout en repoussant les limites du développement assisté par IA, créant un gameplay émergent d'une profondeur inégalée où chaque choix - industriel, militaire, économique - résonne à travers un système interconnecté d'une complexité et d'un réalisme saisissants. + +**Slava Ukraini !** \ No newline at end of file diff --git a/docs/01-architecture/architecture-modulaire.md b/docs/01-architecture/architecture-modulaire.md new file mode 100644 index 0000000..8f196dd --- /dev/null +++ b/docs/01-architecture/architecture-modulaire.md @@ -0,0 +1,423 @@ +# Architecture Modulaire - Warfactory + +## Concept Révolutionnaire + +L'architecture modulaire Warfactory transforme le développement de jeux complexes en utilisant une approche **micro-modules** optimisée pour Claude Code. Chaque module est un micro-contexte de 200-300 lignes de logique métier pure. + +## Core Interface Architecture + +### Architecture Fondamentale + +```cpp +ICoordinationModule → Orchestrateur global système +IEngine → Orchestration locale +IModuleSystem → Stratégies d'exécution +IModule → Logique métier pure +IIO → Communication et transport +ITaskScheduler → Délégation de tâches +``` + +### IEngine - Orchestration + +**Responsabilité** : Coordination générale du système et évolution performance + +```cpp +class IEngine { +public: + virtual void initialize() = 0; + virtual void update(float deltaTime) = 0; + virtual void shutdown() = 0; + virtual void setModuleSystem(std::unique_ptr) = 0; +}; +``` + +**Implémentations disponibles :** +- **DebugEngine** : Développement et test (step-by-step, verbose logging) +- **HighPerfEngine** : Production optimisée (threading, memory management) +- **DataOrientedEngine** : Scale massive (SIMD, cluster distribution) + +### IModuleSystem - Stratégies d'Exécution + +**Responsabilité** : Détermine comment et quand les modules s'exécutent + +```cpp +class IModuleSystem { +public: + virtual void registerModule(const std::string& name, std::unique_ptr) = 0; + virtual void processModules(float deltaTime) = 0; + virtual void setIOLayer(std::unique_ptr) = 0; + virtual json queryModule(const std::string& name, const json& input) = 0; +}; +``` + +**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 + +### IModule - Logique Métier Pure + +**Responsabilité** : Logique de jeu spécialisée sans infrastructure + +```cpp +class IModule { +public: + virtual json process(const json& input) = 0; // PURE FUNCTION + virtual void initialize(const json& config) = 0; // Configuration + virtual void shutdown() = 0; // Cleanup + + // Hot-reload support + virtual json getState() = 0; // Save state + virtual void setState(const json& state) = 0; // Restore state +}; +``` + +**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 - Communication + +**Responsabilité** : Abstraction transport entre modules + +```cpp +class IIO { +public: + virtual json send(const std::string& target, const json& message) = 0; + virtual json receive(const std::string& source) = 0; + virtual void broadcast(const json& message) = 0; +}; +``` + +**Implémentations transport :** +- **IntraIO** : Appel direct (même processus) +- **LocalIO** : Named pipes/sockets (même machine) +- **NetworkIO** : TCP/WebSocket (réseau) + +## Modules Spécialisés + +### ProductionModule (Exception Critique) + +**Particularité** : Belt+Inserter+Factory DOIVENT cohabiter pour performance + +```cpp +class ProductionModule : public IModule { + // EXCEPTION: 500-800 lignes acceptées + // Raison: ISocket overhead >1ms inacceptable pour 60 FPS + + Belt beltSystem; + Inserter inserterSystem; + Factory factorySystem; + +public: + json process(const json& input) override { + // Frame-perfect coordination required + auto beltData = beltSystem.update(input); + auto inserterData = inserterSystem.update(beltData); + auto factoryData = factorySystem.update(inserterData); + + return factoryData; + } +}; +``` + +### TankModule + +```cpp +class TankModule : public IModule { + // Targeting: 60Hz + // Movement: 30Hz + // Tactical: 1Hz + // Analytics: 0.1Hz + +public: + json process(const json& input) override { + auto context = getCurrentContext(input); + + if (shouldUpdateTargeting(context)) { + return processTargeting(input); // 60Hz + } + + if (shouldUpdateMovement(context)) { + return processMovement(input); // 30Hz + } + + if (shouldUpdateTactical(context)) { + return processTactical(input); // 1Hz + } + + return processAnalytics(input); // 0.1Hz + } +}; +``` + +### EconomyModule + +```cpp +class EconomyModule : public IModule { + // Economic cycles: 0.01-0.1Hz + +public: + json process(const json& input) override { + auto marketData = input["market"]; + + // Slow economic simulation + auto priceUpdates = calculatePriceDiscovery(marketData); + auto supplyDemand = updateSupplyDemand(marketData); + auto transportOptim = optimizeTransportCosts(marketData); + + return { + {"prices", priceUpdates}, + {"supply_demand", supplyDemand}, + {"transport", transportOptim} + }; + } +}; +``` + +### LogisticModule + +```cpp +class LogisticModule : public IModule { + // Variable frequency: 50ms → 1000ms + +public: + json process(const json& input) override { + auto context = input["context"]; + + if (context["urgent"]) { + return processRealTimeTransport(input); // 50ms + } + + return processPlanning(input); // 1000ms + } +}; +``` + +## Isolation et Communication + +### Règles d'Isolation Strictes + +**War Module Isolation :** +```cpp +// ✅ CORRECT - War assets via LogisticModule +LogisticModule → TurretSupply → Ammunition +LogisticModule → VehicleSupply → Fuel/Parts + +// ❌ FORBIDDEN - Direct factory interaction +ProductionModule → TankModule // ZERO interaction +FactoryInserter → Turret // NO direct supply +``` + +**Supply Chain Architecture :** +```cpp +// ✅ CORRECT - Unidirectional flow +ProductionModule ↔ LogisticModule // Export/Import only +LogisticModule ↔ WarModule // Supply war assets + +// ❌ FORBIDDEN - Any direct war interaction +ProductionModule ↔ TankModule // ZERO interaction +ProductionModule ↔ TurretModule // ZERO interaction +``` + +### Communication JSON + +**Standard Message Format :** +```json +{ + "timestamp": 1234567890, + "source": "TankModule", + "target": "LogisticModule", + "action": "request_supply", + "data": { + "item": "ammunition", + "quantity": 100, + "priority": "high" + } +} +``` + +**Response Format :** +```json +{ + "timestamp": 1234567891, + "source": "LogisticModule", + "target": "TankModule", + "status": "completed", + "data": { + "delivered": 100, + "eta": "30s", + "cost": 50.0 + } +} +``` + +## Hot-Reload Architecture + +### State Preservation + +```cpp +class TankModule : public IModule { +private: + json persistentState; + +public: + json getState() override { + return { + {"position", currentPosition}, + {"health", currentHealth}, + {"ammunition", ammunitionCount}, + {"target", currentTarget} + }; + } + + void setState(const json& state) override { + currentPosition = state["position"]; + currentHealth = state["health"]; + ammunitionCount = state["ammunition"]; + currentTarget = state["target"]; + } +}; +``` + +### Hot-Reload Workflow + +```cpp +class ModuleLoader { + void reloadModule(const std::string& modulePath) { + // 1. Save state + auto state = currentModule->getState(); + + // 2. Unload old module + unloadModule(modulePath); + + // 3. Load new module + auto newModule = loadModule(modulePath); + + // 4. Restore state + newModule->setState(state); + + // 5. Continue execution + registerModule(newModule); + } +}; +``` + +## Claude Code Development + +### Workflow Optimisé + +```bash +# 1. Claude travaille dans contexte isolé +cd modules/tank/ +# Context: CLAUDE.md (50 lignes) + TankModule.cpp (200 lignes) + IModule.h (30 lignes) +# Total: 280 lignes vs 50K+ dans architecture monolithique + +# 2. Development cycle ultra-rapide +edit("src/TankModule.cpp") # Modification logique pure +cmake . && make tank-module # Build autonome (5 secondes) +./build/tank-module # Test standalone + +# 3. Hot-reload dans jeu principal +# Engine détecte changement → Reload automatique → Game continue +``` + +### Parallel Development + +```bash +# Instance Claude A - Tank Logic +cd modules/tank/ +# Context: 200 lignes tank behavior + +# Instance Claude B - Economy Logic +cd modules/economy/ +# Context: 250 lignes market simulation + +# Instance Claude C - Factory Logic +cd modules/factory/ +# Context: 300 lignes production optimization + +# Zero conflicts, parallel commits, modular architecture +``` + +## Évolution Progressive + +### Phase 1 : Prototype (Debug) +```cpp +DebugEngine + SequentialModuleSystem + IntraIO +→ Développement ultra-rapide, Claude Code 100% focus logique +→ Step-by-step debugging, verbose logging +→ Validation concepts sans complexité infrastructure +``` + +### Phase 2 : Optimization (Threading) +```cpp +DebugEngine + ThreadedModuleSystem + IntraIO +→ Performance boost sans changer 1 ligne de game logic +→ Chaque module dans son thread dédié +→ Parallélisation automatique +``` + +### Phase 3 : Production (High Performance) +```cpp +HighPerfEngine + MultithreadedModuleSystem + LocalIO +→ Scale transparent, modules inchangés +→ Pool de threads optimisé +→ Communication inter-processus +``` + +### Phase 4 : Scale Massive (Distribution) +```cpp +DataOrientedEngine + ClusterModuleSystem + NetworkIO +→ Distribution multi-serveurs +→ SIMD optimization automatique +→ Claude Code développe toujours modules 200 lignes +``` + +## Avantages Architecture + +### Pour Claude Code +- **Micro-contexts** : 200-300 lignes vs 50K+ lignes +- **Focus logique** : Zéro infrastructure, pure game logic +- **Iteration speed** : 5 secondes vs 5-10 minutes +- **Parallel development** : 3+ instances simultanées +- **Hot-reload** : Feedback instantané + +### Pour Performance +- **Modular scaling** : Chaque module à sa fréquence optimale +- **Resource allocation** : CPU budget précis par module +- **Evolution path** : Debug → Production sans réécriture +- **Network tolerance** : Latence adaptée par module type + +### Pour Maintenance +- **Isolation complète** : Failures localisées +- **Testing granular** : Chaque module testable indépendamment +- **Code reuse** : Modules réutilisables entre projets +- **Documentation focused** : Chaque module auto-documenté + +## Implementation Roadmap + +### Étape 1 : Core Infrastructure +- Implémenter IEngine, IModuleSystem, IModule, IIO interfaces +- DebugEngine + SequentialModuleSystem + IntraIO +- Module loader avec hot-reload basique + +### Étape 2 : Premier Module +- TankModule.cpp (200 lignes) +- Test standalone +- Intégration avec core + +### Étape 3 : Modules Core +- EconomyModule, FactoryModule, LogisticModule +- Communication JSON entre modules +- State preservation + +### Étape 4 : Performance +- ThreadedModuleSystem +- Optimisation hot-reload +- Métriques performance + +Cette architecture révolutionnaire permet de développer des jeux AAA complexes avec Claude Code en utilisant des micro-contextes de 200 lignes, tout en conservant la puissance architecturale nécessaire pour des systèmes distribués massifs. \ No newline at end of file diff --git a/docs/01-architecture/architecture-technique.md b/docs/01-architecture/architecture-technique.md new file mode 100644 index 0000000..423566e --- /dev/null +++ b/docs/01-architecture/architecture-technique.md @@ -0,0 +1,924 @@ +# Architecture Technique + +## Vision Globale + +**Concept** : RTS/4X hybride hommageant l'Ukraine avec système industriel complexe (Factorio-like), simulation militaire réaliste et gestion géopolitique. + +**Innovation clé** : Architecture multi-serveurs modulaire permettant scaling horizontal et développement parallèle par IA. + +## Architecture Système + +### Core Interface Architecture + +**ARCHITECTURE MODULAIRE** - Système modulaire optimisé pour le développement avec Claude Code. + +#### Les 5 Interfaces Fondamentales + +```cpp +ICoordinationModule → Orchestrateur global système (MainServer, déploiement, config) +IEngine → Coordination locale (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) +``` + +#### Architecture de Déploiement Global + +``` +MainServer Process: +├── CoordinationModule (Global Orchestrator) +│ ├── Loads gameconfig.json via IDataTree +│ ├── Manages local IEngine + modules +│ └── Launches remote servers + engines +├── Local IEngine (manages local modules) +│ ├── IModuleSystem (Sequential/Threaded/etc.) +│ └── Local Modules (.so files) +└── Remote Servers (launched by coordination) + ├── Remote IEngine (manages remote modules) + ├── IModuleSystem (execution strategy) + └── Remote Modules (.so files) +``` + +#### Séparation des Responsabilités + +**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) + +**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 + +**ICoordinationModule** : Orchestrateur global système +- Premier module lancé, dernier fermé +- Charge gameconfig.json via IDataTree +- Déploie modules selon topologie (local/distant) +- Synchronise configurations entre tous les modules + +**IModule** : Logique métier pure (BREAKING CHANGES) +```cpp +class IModule { + virtual json process(const json& input) = 0; // PURE FUNCTION + virtual void setConfiguration(const IDataNode& configNode, IIO* io, ITaskScheduler* scheduler) = 0; // NEW + virtual const IDataNode& getConfiguration() = 0; // NEW + virtual json getHealthStatus() = 0; // NEW - detailed JSON instead of bool + virtual void shutdown() = 0; + // initialize() method REMOVED +}; +``` + +**Contraintes strictes** : +- **200-300 lignes maximum** par module (EXCEPTION: ProductionModule 500-800 lignes) +- **Aucune dépendance infrastructure** (threading, network, etc.) +- **JSON in/out uniquement** pour communication +- **Logic métier pure** sans effets de bord + +**Exception ProductionModule** : +- **Belt+Inserter+Factory DOIVENT cohabiter** dans le même module pour performance critique +- **500-800 lignes acceptées** pour ce module spécifiquement +- **Raison** : ISocket overhead >1ms inacceptable pour production 60 FPS +- **Trade-off conscient** : Complexité accrue mais performance garantie + +### Décomposition War en Subsystèmes Asynchrones + +**Principe** : Le module War décomposé en subsystèmes avec fréquences d'exécution différentes + +**Subsystèmes identifiés** : +- **Targeting** : Acquisition et tracking des cibles (haute fréquence) +- **Movement** : Déplacement et physique des unités (fréquence moyenne) +- **Pathfinding** : Calcul des routes optimales (à la demande) +- **Tactical** : Décisions tactiques et IA (basse fréquence) +- **Analytics** : Métriques et statistiques de combat (très basse fréquence) + +**Avantages de la désynchronisation** : +- **Performance** : Chaque système tourne à sa fréquence optimale +- **Scalabilité** : Distribution possible sur threads/cores différents +- **Modularité** : Systèmes indépendants plus faciles à maintenir +- **Réactivité** : Systèmes critiques (targeting) restent fluides + +**Tolérance Réseau War** : +- **50-100ms de latence acceptable** pour décisions stratégiques +- Combat n'est pas frame-perfect comme un FPS +- Synchronisation relaxée suffisante pour RTS/stratégie +- Permet joueurs avec connexions moyennes + +**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 +// 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 +}; +``` + +**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 + +#### É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 +} +``` + +**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 + +### Build Autonome par Module + +**Classification :** HIGH - Implémentation prioritaire +**Principe :** `cmake .` depuis chaque module, zéro dépendance parent + +#### Structure de Build Autonome + +**Directory pattern requis :** +``` +modules/tank/ +├── CMakeLists.txt # Autonomous build config +├── CLAUDE.md # Module-specific instructions +├── src/ +│ ├── TankModule.cpp # 200 lignes max +│ └── TankModule.h # Interface pure +├── tests/ +│ └── tank_test.cpp # Standalone testing +└── build/ # Local build artifacts + └── tank.so # Hot-reloadable module +``` + +**CMake autonome pattern :** +```cmake +# NEVER cmake .. - ALWAYS cmake . +cmake_minimum_required(VERSION 3.20) +project(TankModule) + +# Self-contained dependencies +find_package(nlohmann_json REQUIRED) + +# Pure module compilation +add_library(tank MODULE src/TankModule.cpp) +target_link_libraries(tank nlohmann_json::nlohmann_json) + +# Standalone testing +add_executable(tank-test tests/tank_test.cpp) +target_link_libraries(tank-test tank) +``` + +#### Implications Utilisateurs + +**Performance développement révolutionnaire :** +- **Build ultra-rapide** : 5 secondes vs 5 minutes (60x faster) +- **Debugging isolé** : Test module sans infrastructure complète +- **Parallélisme naturel** : Multiple builds simultanés sans conflit +- **Stabilité accrue** : Modification module N n'affecte jamais module M + +**Expérience développeur optimisée :** +- **Context switching minimal** : Focus total sur logique module +- **Error isolation parfaite** : Compilation errors localisées uniquement +- **Testing granulaire** : Validation unitaire immédiate et autonome +- **Hot-reload ready** : Module.so prêt pour remplacement instantané + +#### Implications Développeurs + +**Architecture modulaire pure :** +- **Zero dependencies up** : Jamais `#include "../core/engine.h"` +- **Self-contained units** : Chaque module = micro-projet autonome +- **Interface contracts only** : Communication via JSON/IModule uniquement +- **Infrastructure agnostic** : Module ignore engine/system hosting + +**Workflow Claude Code révolutionnaire :** +- **Micro-context focus** : 200-300 lignes + CMakeLists.txt + CLAUDE.md total +- **Parallel instances** : 3+ Claude Code travaillant simultanément +- **Build verification** : `cmake . && make` validation automatique +- **Development velocity** : 10x improvement mesurable + +#### Contraintes Strictes CRITICAL + +**NEVER patterns (violations = build failure) :** +- `cd ..` ou `cmake ..` - Toujours rester dans module directory +- `#include "../"` - Aucune référence parent directory +- Dependency sur `core/` ou `shared/` - Module = island complet +- Shared C++ objects - JSON communication exclusive + +**ALWAYS patterns (required for autonomy) :** +- `cd modules/tank/ && cmake .` - Build depuis module directory +- Interface-only dependencies - IModule.h via find_package uniquement +- Local build artifacts - `build/` directory dans module +- Standalone testing - Tests s'exécutent sans infrastructure +- Unit tests intégrés - `#ifdef TESTING` validation autonome modules +- Behavior composition - Modules comportements combinables via config JSON + +#### Métriques de Performance + +| Metric | Avant (Monolithe) | Après (Autonome) | Amélioration | +|--------|-------------------|------------------|--------------| +| Build time | 2-5 min | <5 sec | 24-60x faster | +| Context size | 50K+ lignes | 200-300 lignes | 250x smaller | +| Parallel dev | 1 instance | 3+ instances | 3x+ throughput | +| Error isolation | Project-wide | Module-only | Perfect isolation | +| Iteration cycle | 5-10 min | 5 sec | 60-120x faster | + +### Hot-Reload Infrastructure + +**Classification :** HIGH - Implémentation prioritaire +**Principe :** Remplacement temps réel modules DLL/SO avec sauvegarde état + +#### Architecture Hot-Reload + +**Platform Support :** +- **Primary** : .dll (Windows gaming natif) +- **Future** : .so (Linux server/dev support) +- **Unified interface** : Même mécanisme, extension différente + +**Workflow cible :** +```bash +# Edit TankModule.cpp → Save → Auto-rebuild tank.dll +# Système détecte changement → Hot-reload → Game continue +# <5 secondes total sans interruption +``` + +#### Mécanisme Technique + +**Windows DLL Hot-Reload :** +```cpp +// State preservation avant reload +json moduleState = currentModule->exportState(); + +// Hot-swap DLL +FreeLibrary(tankDLL); // Décharge ancienne +tankDLL = LoadLibrary(L"tank.dll"); // Charge nouvelle version + +// State restoration après reload +auto createFunc = GetProcAddress(tankDLL, "CreateTankModule"); +newModule = createFunc(); +newModule->importState(moduleState); // Restore état +``` + +**Build DLL autonome :** +```cmake +# modules/tank/CMakeLists.txt +add_library(tank SHARED src/TankModule.cpp) +set_target_properties(tank PROPERTIES + SUFFIX ".dll" # Windows primary + POSITION_INDEPENDENT_CODE ON # Linux SO ready +) +``` + +#### Implications Utilisateurs + +**Développement révolutionnaire :** +- **Feedback instantané** : Changements visibles immédiatement sans restart +- **Flow state preserved** : Concentration maintenue, zéro interruption +- **Session continuity** : Données de jeu préservées pendant développement +- **Real-time testing** : Validation changements en contexte réel + +**Expérience gameplay optimisée :** +- **Config tweaking live** : Modification paramètres à chaud +- **Balance updates instant** : Ajustements gameplay sans redémarrage +- **Bug fixes immediate** : Corrections appliquées en temps réel +- **A/B testing dynamic** : Switch comportements dynamiquement + +#### Implications Développeurs + +**Workflow ultra-optimisé :** +- **Edit → Save → Test** : Cycle 5 secondes vs 5 minutes (60x faster) +- **State preservation** : Contexte développement totalement maintenu +- **Debug facilité** : Isolation précise des changements +- **Experimentation rapide** : Testing hypothèses ultra-rapide + +**Architecture requirements :** +- **State serialization** : JSON export/import complet état module +- **Interface stability** : IModule contracts préservés pendant reload +- **Memory safety** : Cleanup automatique ancien module, zéro leak +- **Thread safety** : Hot-swap sans race conditions + +#### File Watching & Auto-Rebuild + +**Monitoring automatique :** +```cpp +// File system watcher +FileWatcher watcher("modules/tank/"); +watcher.onChange("*.cpp", [](){ + rebuildModule("tank"); + hotReloadModule("tank.dll"); +}); +``` + +**Build pipeline intégré :** +- **Change detection** : .cpp modification trigger auto-build +- **Compilation rapide** : Module isolé <5 sec build +- **Success validation** : Hot-reload seulement si build réussi +- **Error handling** : Fallback ancien module si échec + +#### Contraintes & Performance + +**Requirements techniques :** +- **Interface compatibility** : IModule contracts identiques pre/post reload +- **State serializability** : Toutes données JSON-serializable +- **No static globals** : État encapsulé dans instances module +- **Export functions** : CreateModule, DestroyModule standardisées + +**Performance impact :** +- **Reload time** : <5 secondes garantis (target <2 sec) +- **Runtime overhead** : <1% en production (hot-reload disabled) +- **Memory usage** : Temporairement doublé pendant transition +- **Gaming performance** : Zéro impact, Windows DLL natif + +### 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}; + } +}; +``` + +```cpp +// ❌ INCORRECT - Trop complexe pour Claude Code +class MegaTankSystem { + // 5000+ lignes avec networking, threading, UI, etc. + // Claude Code ne peut pas appréhender efficacement +}; +``` + +#### 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) + +# Instance Claude Code B - 250 lignes context +cd modules/economy/ +# Context: CLAUDE.md (70) + EconomyModule.cpp (150) + IModule.h (30) + +# Instance Claude Code C - 230 lignes context +cd modules/factory/ +# Context: CLAUDE.md (60) + FactoryModule.cpp (140) + IModule.h (30) +``` + +#### 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 + +#### 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 + +## Performance Scaling Architecture (Point 39) + +**Hiérarchie temporelle optimisée** pour balance performance/complexité : + +### 4 Tiers Performance +```cpp +enum PerformanceTier { + LOCAL_REALTIME, // Transport mode selection (real-time) + REGIONAL_HOURLY, // Market clearing (hourly) + ECONOMIC_DAILY, // Complex modeling (daily) + INFRASTRUCTURE_MONTHLY // Long-term investment (monthly) +}; +``` + +### Local Decisions (Real-time) +- **Target** : 60fps gameplay garanti +- **Scope** : Factory production, transport mode selection, player input +- **Constraint** : Zero network latency impact +- **Budget** : 16ms per frame maximum + +### Regional Coordination (Hourly) +- **Target** : Market clearing operations +- **Scope** : Order matching, price updates, transport assignment +- **Tolerance** : 50-100ms network delays acceptable +- **Budget** : 5-10 seconds processing time + +### Economic Simulation (Daily) +- **Target** : Complex economic modeling +- **Scope** : Demographics, market volatility, AI behaviors +- **Frequency** : 0.01-0.1Hz processing +- **Budget** : Up to 30 seconds computation acceptable + +### Infrastructure Planning (Monthly) +- **Target** : Long-term strategic calculations +- **Scope** : ROI analysis, regional development, policy changes +- **Tolerance** : High latency, batch processing +- **Budget** : Several minutes computation acceptable + +**Architecture Benefits** : +- **Performance isolation** : Critical path (60fps) protected from complex simulation +- **Resource allocation** : CPU budget approprié per tier +- **Network optimization** : Frequency matching network tolerance +- **Modular scaling** : Each module operates at optimal frequency +- **Development velocity** : 10x improvement démontré + +## Modules Principaux + +L'architecture modulaire remplace les anciens engines par des modules spécialisés, chacun implémentant l'interface IModule avec logique métier pure. + +### 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) +- **Frequency** : 60Hz processing pour frame-perfect timing +- **War Isolation** : ZERO interaction directe avec WarModule/TankModule +- **Communication** : JSON avec LogisticModule pour export/import uniquement + +### EconomyModule +- **Responsabilité** : Simulation économique, marchés, pricing dynamique +- **Scope** : Agent-based economy, supply/demand, transport optimization +- **Frequency** : 0.01-0.1Hz (cycles économiques lents) +- **Business Models** : Arbitrage, Market Making, Transport Optimization +- **Communication** : JSON market data, price updates + +### TankModule +- **Responsabilité** : Comportement véhicules de combat +- **Scope** : Movement, targeting, combat states, damage calculation +- **Frequency** : 0.1-60Hz (Targeting 60Hz → Movement 30Hz → Tactical 1Hz → Analytics 0.1Hz) +- **Factory Isolation** : Aucune interaction directe avec ProductionModule +- **Turret Supply** : Approvisionnement via LogisticModule uniquement +- **Communication** : JSON commands, state updates + +### LogisticModule +- **Responsabilité** : Transport goods, supply chains, turret supply +- **Scope** : Route optimization, convoy management, infrastructure, war asset supply +- **Frequency** : Variable (50ms temps réel → 1000ms planification) +- **War Integration** : Approvisionne turrets/war assets, PAS inserters directs +- **Economic Integration** : Cost-based transport mode selection +- **Communication** : JSON transport requests, delivery confirmations + +### MapModule +- **Responsabilité** : Terrain, procedural generation, FOW +- **Scope** : Multi-scale maps, chunk streaming, 218+ generation elements +- **Frequency** : Variable selon context (streaming asynchrone) +- **Performance** : Lazy loading, memory management + +## Module Frequencies & Isolation Rules + +### Frequency Specifications (Points 109-125) + +**Performance-Critical Modules :** +- **ProductionModule** : 60Hz (frame-perfect factory operations) +- **TankModule Targeting** : 60Hz (combat responsiveness) +- **TankModule Movement** : 30Hz (position updates) + +**Strategic Modules :** +- **TankModule Tactical** : 1Hz (strategic decisions) +- **TankModule Analytics** : 0.1Hz (long-term analysis) +- **EconomyModule** : 0.01-0.1Hz (economic cycles) + +**Context-Dependent Modules :** +- **LogisticModule** : 50ms (real-time) → 1000ms (planning) +- **MapModule** : Asynchronous (on-demand streaming) + +### Isolation Rules (Points 133-134) + +**War Module Isolation :** +```cpp +// ✅ CORRECT - War assets via LogisticModule +LogisticModule → TurretSupply → Ammunition +LogisticModule → VehicleSupply → Fuel/Parts + +// ❌ FORBIDDEN - Direct factory interaction +ProductionModule → TankModule // ZERO interaction +FactoryInserter → Turret // NO direct supply +``` + +**ProductionModule Isolation :** +```cpp +// ✅ CORRECT - Only LogisticModule interface +ProductionModule ↔ LogisticModule // Export/Import only +LogisticModule ↔ WarModule // Supply war assets + +// ❌ FORBIDDEN - Any direct war interaction +ProductionModule ↔ TankModule // ZERO interaction +ProductionModule ↔ TurretModule // ZERO interaction +``` + +**Supply Chain Architecture :** +- **Factory → Logistics → War** (unidirectional flow) +- **NO shortcuts** : Direct factory-to-war connections prohibited +- **Reason** : Module isolation, testability, hot-reload safety +- **Communication** : JSON terrain queries, chunk data + +## Architecture Communication + +### Communication Modulaire + +**Protocole uniforme** : JSON-only entre tous les modules via interfaces IIO + +### Architecture Client/Server Modulaire + +**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 + +**Performance Targets (Points 98-103) :** +- **V1 Client Target** : 30+ fps stable (Point 98) +- **V1 Server Capacity** : 10+ concurrent players (Point 100) +- **V1 Latency** : <150ms validation acceptable (Point 102) + +**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 + +**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 + +**Performance Targets (Points 99-103) :** +- **V2 Client Target** : 60+ fps avec prediction (Point 99) +- **V2 Server Capacity** : 100+ concurrent players (Point 101) +- **V2 Network** : 30ms server, 0ms perceived client (Point 103) + +**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 (Point 10) :** +**Évolution sans risque architecture client/server** + +- **Pattern hot-swappable** : Transition V1→V2 transparente pour modules +- **A/B testing** : Validation progressive par groupes d'utilisateurs (10% → 50% → 100%) +- **Fallback automatique** : Retour V1 en cas d'échec V2 +- **Zéro réécriture** : V1 code reste valide, V2 = extension progressive +- **Forward-compatible** : Architecture V1 compatible V2 dès le design initial + +**Exemple migration progressive :** +```cpp +// Code adaptable V1/V2 sans réécriture +if (config.enable_v2_prediction) { + // V2: Client prediction + server validation +} else { + // V1: Server authoritative (fallback sûr) +} +``` + +**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 + +## Development Philosophy & Patterns + +### Point 51 : Backward Compatibility Framework +**Proxy pattern ancien→nouveau coexistence** + +```cpp +// Backward compatibility via proxy pattern +class LegacyTankAdapter : public IModule { + std::unique_ptr legacySystem; + std::unique_ptr modernSystem; + bool useModern = false; + +public: + json process(const json& input) override { + if (useModern && modernSystem->isReady()) { + try { + return modernSystem->process(input); + } catch (const std::exception&) { + // Fallback to legacy on failure + return legacySystem->processLegacy(convertToOldFormat(input)); + } + } + return legacySystem->processLegacy(convertToOldFormat(input)); + } + + void enableModernSystem() { useModern = true; } + void fallbackToLegacy() { useModern = false; } +}; +``` + +**Benefits Architecture :** +- **Zero-risk migration** : Ancien système reste fonctionnel +- **A/B testing** : Switch runtime entre old/new +- **Progressive rollout** : Migration progressive users +- **Instant rollback** : Retour automatique si problème + +### Point 52 : YAGNI Modding Philosophy +**Pas modding pre-release, config system suffit 90% cas** + +**Philosophy :** Configuration-driven flexibility plutôt que modding infrastructure complexe + +```json +// Config-driven "modding" via JSON +{ + "tank_variants": { + "tank_mk1": { + "health": 100, + "speed": 35, + "armor": "medium", + "weapons": ["cannon_75mm"] + }, + "tank_mk2_custom": { + "health": 150, + "speed": 30, + "armor": "heavy", + "weapons": ["cannon_105mm", "mg_coaxial"] + } + }, + "behavior_mods": { + "aggressive_ai": { + "engagement_range": 1000, + "retreat_threshold": 20, + "target_priority": "closest" + } + } +} +``` + +**Architecture Benefits :** +- **90% modding needs** : Config JSON couvre la majorité des besoins +- **Zero complexity** : Pas infrastructure modding complexe +- **Claude-friendly** : Config changes = instant AI comprehension +- **Runtime modification** : Hot-reload configs sans restart + +**Future Extension :** +```cpp +// When modding eventually needed (post-release) +class ModdingInterface : public IModule { + json process(const json& input) override { + // Modding hooks will be added here later + // For now, config-driven behavior is sufficient + return processConfigDriven(input); + } +}; +``` + +### Point 53 : "Complexity through Simplicity" +**AAA complexité via modules simples Claude-friendly** + +**Core Philosophy :** Complex gameplay emerges from interaction of simple, well-designed modules + +```cpp +// Simple tank module (200 lines) +class TankModule : public IModule { + json process(const json& input) override { + // Simple tank behavior: move, shoot, retreat + return processSimpleTankLogic(input); + } +}; + +// Simple economy module (250 lines) +class EconomyModule : public IModule { + json process(const json& input) override { + // Simple market: supply, demand, price discovery + return processSimpleMarket(input); + } +}; + +// Complex gameplay emerges from interaction +// Tank + Economy = Resource-constrained warfare +// Tank + Factory = Production-line optimization +// Economy + Factory = Industrial economic simulation +``` + +**Emergent Complexity Examples :** + +**Simple Rules → Complex Behavior :** +```cpp +// Rule 1: Tanks need fuel (EconomyModule) +// Rule 2: Fuel costs money (MarketModule) +// Rule 3: Money comes from production (FactoryModule) +// Rule 4: Production needs resources (LogisticModule) + +// Emergent behavior: Complex supply-chain warfare +// Players must balance factory output, resource extraction, +// economic planning, and military operations +``` + +**Architecture Benefits :** +- **Claude comprehension** : Each module easily understood by AI +- **Debugging simplicity** : Issues isolated to specific modules +- **Testing granularity** : Simple modules = simple tests +- **Development velocity** : Small contexts = fast iteration + +**AAA Complexity Achieved Through :** +- **Module interaction** : Simple rules create complex systems +- **Configuration depth** : JSON configs add sophistication +- **Emergent gameplay** : Player strategies emerge naturally +- **Progressive revelation** : Complexity unlocked gradually diff --git a/docs/01-architecture/behavior-composition-patterns.md b/docs/01-architecture/behavior-composition-patterns.md new file mode 100644 index 0000000..15c5c61 --- /dev/null +++ b/docs/01-architecture/behavior-composition-patterns.md @@ -0,0 +1,305 @@ +# Behavior Composition Patterns - Warfactory + +**Philosophy** : Modules comportements combinables via configuration JSON pour AI flexibility + +## Point 46 : Behavior Composition Pattern + +### Concept Core + +**Modular Behaviors** : Chaque comportement AI = module autonome combinable + +```cpp +// Base behavior interface +class IBehaviorModule : public IModule { +public: + virtual json process(const json& context) = 0; + virtual float getWeight() const = 0; + virtual bool shouldActivate(const json& triggers) const = 0; +}; +``` + +### Behavior Module Examples + +#### AggressiveBehavior Module +```cpp +class AggressiveBehavior : public IBehaviorModule { + json process(const json& context) override { + auto enemy_detected = context["enemy_detected"].get(); + auto health = context["health"].get(); + + if (enemy_detected && health > 50.0f) { + return { + {"action", "attack"}, + {"priority", "high"}, + {"target_selection", "closest_enemy"} + }; + } + + return {{"action", "patrol"}}; + } + + float getWeight() const override { return 0.8f; } // High aggression + + bool shouldActivate(const json& triggers) override { + return triggers.contains("enemy_nearby") || triggers.contains("under_attack"); + } +}; +``` + +#### CautiousBehavior Module +```cpp +class CautiousBehavior : public IBehaviorModule { + json process(const json& context) override { + auto health = context["health"].get(); + auto enemy_count = context["enemy_count"].get(); + + if (health < 30.0f || enemy_count > 2) { + return { + {"action", "retreat"}, + {"priority", "critical"}, + {"retreat_direction", "base"} + }; + } + + return {{"action", "defensive_position"}}; + } + + float getWeight() const override { return 0.6f; } // Moderate caution + + bool shouldActivate(const json& triggers) override { + return triggers.contains("low_health") || triggers.contains("outnumbered"); + } +}; +``` + +#### EconomicBehavior Module +```cpp +class EconomicBehavior : public IBehaviorModule { + json process(const json& context) override { + auto resources = context["resources"].get(); + auto factory_status = context["factory_active"].get(); + + if (resources < 100 && factory_status) { + return { + {"action", "gather_resources"}, + {"priority", "medium"}, + {"resource_type", "preferred"} + }; + } + + return {{"action", "optimize_production"}}; + } + + float getWeight() const override { return 0.4f; } // Economic focus + + bool shouldActivate(const json& triggers) override { + return triggers.contains("low_resources") || triggers.contains("economic_opportunity"); + } +}; +``` + +### Composition Engine + +#### BehaviorCompositionEngine +```cpp +class BehaviorCompositionEngine : public IModule { +private: + std::map> behaviors; + json composition_config; + +public: + void initialize(const json& config) override { + composition_config = config["behavior_composition"]; + + // Load configured behavior modules + for (const auto& behavior_name : composition_config["modules"]) { + loadBehaviorModule(behavior_name); + } + } + + json process(const json& context) override { + std::vector behavior_outputs; + std::vector weights; + + // Process all active behaviors + for (const auto& [name, behavior] : behaviors) { + if (shouldActivateBehavior(name, context)) { + auto output = behavior->process(context); + behavior_outputs.push_back(output); + weights.push_back(getBehaviorWeight(name)); + } + } + + // Compose final decision + return composeBehaviors(behavior_outputs, weights); + } + +private: + bool shouldActivateBehavior(const std::string& name, const json& context) { + auto triggers = extractTriggers(context); + return behaviors[name]->shouldActivate(triggers); + } + + float getBehaviorWeight(const std::string& name) { + auto weights = composition_config["weights"]; + if (weights.contains(name)) { + return weights[name].get(); + } + return behaviors[name]->getWeight(); + } + + json composeBehaviors(const std::vector& outputs, const std::vector& weights) { + // Weighted decision composition + json final_decision; + float total_weight = 0.0f; + + // Calculate weighted priorities + for (size_t i = 0; i < outputs.size(); ++i) { + auto priority = getPriorityValue(outputs[i]["priority"]); + auto weighted_priority = priority * weights[i]; + + if (weighted_priority > total_weight) { + final_decision = outputs[i]; + total_weight = weighted_priority; + } + } + + return final_decision; + } +}; +``` + +### Configuration-Driven Composition + +#### Example Configuration +```json +{ + "behavior_composition": { + "modules": ["aggressive", "cautious", "economic"], + "weights": { + "aggressive": 0.7, + "cautious": 0.8, + "economic": 0.3 + }, + "triggers": { + "low_health": "switch_to_cautious", + "enemy_nearby": "activate_aggressive", + "low_resources": "activate_economic" + }, + "priority_matrix": { + "critical": 1.0, + "high": 0.8, + "medium": 0.5, + "low": 0.2 + }, + "dynamic_weights": { + "health_modifier": { + "high_health": {"aggressive": 1.2, "cautious": 0.8}, + "low_health": {"aggressive": 0.3, "cautious": 1.5} + } + } + } +} +``` + +#### Advanced Composition Features +```json +{ + "behavior_composition": { + "modules": ["aggressive", "cautious", "economic", "tactical"], + "composition_strategy": "weighted_priority", + "context_modifiers": { + "time_of_day": { + "night": {"cautious": 1.3, "aggressive": 0.7}, + "day": {"aggressive": 1.1, "tactical": 1.2} + }, + "resource_level": { + "abundant": {"economic": 0.5, "aggressive": 1.3}, + "scarce": {"economic": 1.5, "cautious": 1.2} + } + }, + "behavior_transitions": { + "aggressive_to_cautious": { + "trigger": "health < 25%", + "transition_time": 2.0 + }, + "economic_to_aggressive": { + "trigger": "resources > 500", + "transition_time": 1.0 + } + } + } +} +``` + +### Usage Examples + +#### Tank AI Composition +```json +{ + "tank_ai": { + "modules": ["aggressive", "tactical", "survival"], + "weights": {"aggressive": 0.8, "tactical": 0.9, "survival": 1.0}, + "context": "combat_heavy" + } +} +``` + +#### Economic AI Composition +```json +{ + "company_ai": { + "modules": ["economic", "cautious", "opportunistic"], + "weights": {"economic": 1.0, "cautious": 0.6, "opportunistic": 0.4}, + "context": "market_trading" + } +} +``` + +#### Diplomatic AI Composition +```json +{ + "diplomatic_ai": { + "modules": ["cooperative", "strategic", "economic"], + "weights": {"cooperative": 0.7, "strategic": 0.9, "economic": 0.5}, + "context": "international_relations" + } +} +``` + +## Architecture Benefits + +### Development Advantages +- **Module Reusability** : Behaviors réutilisables entre différents AI agents +- **Easy Testing** : Chaque behavior testable indépendamment +- **Claude-Friendly** : Modules 200 lignes max, comprehensibles par IA +- **Hot-Reload** : Modification behaviors sans restart système + +### Gameplay Advantages +- **AI Diversity** : Combinations créent personnalités AI distinctes +- **Dynamic Adaptation** : Behaviors s'adaptent selon context/triggers +- **Emergent Complexity** : Interactions behaviors créent sophistication émergente +- **Player Customization** : Players peuvent configurer AI allies + +### Performance Benefits +- **Selective Activation** : Seuls behaviors pertinents s'activent +- **Lightweight Composition** : JSON processing minimal overhead +- **Parallel Processing** : Behaviors processables en parallèle +- **Efficient Caching** : Composition results cachables + +## Implementation Strategy + +### Phase 1 : Core Behaviors +- Implement basic behavior modules (Aggressive, Cautious, Economic) +- Simple weighted composition +- JSON configuration loading + +### Phase 2 : Advanced Composition +- Context modifiers et dynamic weights +- Behavior transitions +- Priority matrices sophistiquées + +### Phase 3 : AI Personalities +- Predefined personality templates +- Player customization interface +- Emergent behavior analysis \ No newline at end of file diff --git a/docs/01-architecture/claude-code-integration.md b/docs/01-architecture/claude-code-integration.md new file mode 100644 index 0000000..fcb8e1b --- /dev/null +++ b/docs/01-architecture/claude-code-integration.md @@ -0,0 +1,502 @@ +# Intégration Claude Code : Guide Technique + +## 🎯 Objectif : Développement IA-First + +Cette architecture est spécifiquement conçue pour **maximiser l'efficacité de Claude Code** dans le développement de jeux complexes. + +## 🧠 Contraintes Cognitives de l'IA + +### Problème Fondamental : Context Window +- **Claude Code limite** : ~200K tokens de contexte +- **Jeu AAA typique** : 500K+ lignes de code interconnectées +- **Résultat** : IA ne peut pas appréhender le système complet + +### Solution : Micro-Contexts Autonomes +```cpp +// Au lieu de ça (impossible pour l'IA) : +TankSystem.cpp (5000 lignes) + +PhysicsEngine.cpp (8000 lignes) + +NetworkLayer.cpp (3000 lignes) + +GraphicsRenderer.cpp (12000 lignes) += 28000 lignes interconnectées + +// On fait ça (parfait pour l'IA) : +TankModule.cpp (200 lignes) += Logique pure, zéro dépendance +``` + +## 🏗️ Architecture Claude Code Friendly + +### Structure Cognitive Optimale + +``` +warfactory/ +├── modules/tank/ # 🎯 Claude travaille ICI +│ ├── CLAUDE.md # Instructions spécialisées +│ ├── CMakeLists.txt # Build autonome (cmake .) +│ ├── shared/ # Headers locaux +│ ├── src/TankModule.cpp # 200 lignes PURE logic +│ └── build/ # → tank.so +└── [reste du projet invisible pour Claude] +``` + +### Principe : Information Hiding Cognitif +- **Claude voit SEULEMENT** : TankModule.cpp + CLAUDE.md + interfaces +- **Claude ne voit JAMAIS** : Engine architecture, networking, threading +- **Résultat** : Focus 100% sur logique métier + +## 📋 Workflow Claude Code Optimisé + +### 1. Session Initialization +```bash +# Claude démarre TOUJOURS dans un module spécifique +cd modules/tank/ + +# Context loading minimal +files_to_read = [ + "CLAUDE.md", # 50 lignes d'instructions + "src/TankModule.cpp", # 200 lignes de logic + "shared/IModule.h" # 30 lignes d'interface +] +# Total : 280 lignes vs 50K+ dans architecture classique +``` + +### 2. Development Loop +```bash +# 1. Claude lit le contexte micro +read("src/TankModule.cpp") + +# 2. Claude modifie la logique pure +edit("src/TankModule.cpp") + +# 3. Test instantané +cmake . && make tank-module +./build/tank-module + +# 4. Hot-reload dans le jeu +# Aucune recompilation complète ! +``` + +### 3. Parallel Development +**Point 8 - Développement Parallèle :** Multiple instances Claude Code simultanées sans conflits + +```bash +# Instance Claude A +cd modules/tank/ && work_on("tank logic") + +# Instance Claude B +cd modules/economy/ && work_on("market simulation") + +# Instance Claude C +cd modules/ai/ && work_on("behavior trees") + +# Zero conflicts, parallel development +``` + +**Architecture de non-conflit :** +- **Isolation complète** : Chaque module = contexte indépendant +- **Builds autonomes** : `cmake .` par module, zéro dépendance parent +- **État séparé** : Aucun fichier partagé entre modules +- **Git-friendly** : Commits isolés par module + +## 🎯 Instructions CLAUDE.md Spécialisées +**Point 9 - CLAUDE.md Spécialisés :** Instructions contextuelles limitées par module + +**Principe révolutionnaire :** +- **CLAUDE.md global** : Trop générique, 150+ lignes, inefficace +- **CLAUDE.md par module** : Ultra-spécialisé, 50 lignes max, efficacité maximale +- **Instructions contextuelles** : Tank ≠ Economy ≠ Factory ≠ War + +### Template Type par Module + +#### modules/tank/CLAUDE.md +```markdown +# Tank Module - Pure Combat Logic + +## Context +You work EXCLUSIVELY on tank behavior. No networking, no threading. + +## Responsibilities +- Movement: acceleration, turning, terrain interaction +- Combat: targeting, firing, armor calculations +- States: idle, moving, attacking, destroyed + +## Interface Contract +Input JSON: {"type": "move", "direction": "north", "speed": 0.8} +Output JSON: {"position": [x, y], "facing": angle, "status": "moving"} + +## File Limits +- TankModule.cpp: Max 250 lines +- Pure logic only: No sockets, threads, engine dependencies +- JSON in/out: All communication via JSON messages + +## Build Commands +cmake . && make tank-module # Builds tank.so +./build/tank-module # Test standalone + +NEVER leave this directory or reference parent paths! +``` + +#### modules/economy/CLAUDE.md +```markdown +# Economy Module - Pure Market Logic + +## Context +You work EXCLUSIVELY on economic simulation. No infrastructure. + +## Responsibilities +- Market dynamics: supply/demand, pricing +- Trading: buy/sell orders, market makers +- Economics: inflation, market cycles + +## Interface Contract +Input: {"type": "trade", "item": "steel", "quantity": 100, "action": "buy"} +Output: {"status": "executed", "price": 5.2, "total": 520.0} + +## Focus Areas +1. Market algorithms (supply/demand curves) +2. Price discovery mechanisms +3. Economic modeling + +NEVER reference networking, threading, or parent directories! +``` + +### Contraintes Strictes pour Claude +1. **NEVER `cd ..`** ou référence parent +2. **ALWAYS `cmake .`** (pas cmake ..) +3. **ONLY JSON communication** avec autres modules +4. **MAX 300 lignes** par fichier +5. **ZERO infrastructure code** dans le contexte + +## 🔧 Build System Cognitif + +### Autonomous Build : Zero Mental Overhead + +```cmake +# modules/tank/CMakeLists.txt +cmake_minimum_required(VERSION 3.20) +project(TankModule) # Self-contained + +# Everything local +include_directories(shared) +add_library(tank-module SHARED src/TankModule.cpp) + +# Local build directory +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/build) +``` + +**Avantage Claude** : Aucun concept de "projet parent" à comprendre ! + +### Hot-Reload pour Rapid Iteration +```cpp +// Engine hot-reload automatique +class ModuleLoader { + void reloadIfChanged(const std::string& modulePath) { + if(fileChanged(modulePath)) { + unloadModule(modulePath); + loadModule(modulePath); // Reload .so + // Game continue sans interruption ! + } + } +}; +``` + +**Workflow Claude** : Edit → Save → See changes instantly in game + +## 🧪 Testing Strategy : AI-Optimized + +### Unit Tests Intégrés +```cpp +// Dans TankModule.cpp +#ifdef TESTING +void runTests() { + // Test 1: Movement + auto input = json{{"type", "move"}, {"direction", "north"}}; + auto result = process(input); + assert(result["status"] == "moving"); + + // Test 2: Combat + input = json{{"type", "attack"}, {"target", "enemy_1"}}; + result = process(input); + assert(result["action"] == "fire"); + + std::cout << "✅ All tank tests passed!" << std::endl; +} +#endif +``` + +### Standalone Testing +```bash +# Claude peut tester sans le engine complet +cd modules/tank/ +make tank-module +./build/tank-module # Run standalone avec tests intégrés +``` + +**Avantage IA** : Testing sans infrastructure complexe ! + +## 🔄 Hot-Reload Architecture + +### Module State Preservation +```cpp +class TankModule { +private: + json persistentState; // Sauvegardé lors hot-reload + +public: + json getState() override { + return persistentState; // Engine sauvegarde l'état + } + + void setState(const json& state) override { + persistentState = state; // Restore après reload + } +}; +``` + +### Seamless Development +1. **Claude modifie** TankModule.cpp +2. **Engine détecte** file change +3. **Automatic save** module state +4. **Reload .so** avec nouveau code +5. **Restore state** → Game continue +6. **Test immediately** nouvelles modifications + +## 🎮 Debug Mode : IA Paradise + +### Debug Engine Features +```cpp +class DebugEngine : public IEngine { + // Execution step-by-step pour analyse + void stepMode() { processOneModule(); } + + // Logging détaillé pour Claude + void verboseLogging() { + log("Module tank input: " + input.dump()); + log("Module tank output: " + output.dump()); + } + + // Module isolation pour debugging + void isolateModule(const std::string& name) { + // Run ONLY this module, others = mock + } +}; +``` + +### Claude Debug Workflow +```bash +# 1. Set debug mode +echo '{"debug_mode": true, "isolated_module": "tank"}' > config/debug.json + +# 2. Run with step mode +./warfactory-engine --step-mode + +# 3. Claude voit EXACT input/output de son module +# Perfect pour comprendre les interactions ! +``` + +## 📊 Métriques Claude Code + +### Avant : Architecture Monolithique +- **Context size** : 50K+ lignes (impossible) +- **Build time** : 2-5 minutes +- **Iteration cycle** : Edit → Compile → Restart → Test (10+ min) +- **Bug localization** : Needle in haystack +- **Parallel work** : Impossible (conflicts) + +### Après : Architecture Modulaire +- **Context size** : 200-300 lignes (parfait) +- **Build time** : 5-10 secondes +- **Iteration cycle** : Edit → Hot-reload → Test (30 sec) +- **Bug localization** : Surgical precision +- **Parallel work** : 3+ Claude instances + +### ROI Development +- **Claude efficiency** : 10x improvement +- **Development speed** : 5x faster iteration +- **Code quality** : Higher (focused contexts) +- **Bug density** : Lower (isolated modules) + +## 🚀 Advanced Claude Patterns + +### Pattern 1: Progressive Complexity +```cpp +// Iteration 1: Basic tank (Claude commence simple) +class TankModule { + json process(const json& input) { + if(input["type"] == "move") return basicMove(); + return {{"status", "idle"}}; + } +}; + +// Iteration 2: Add combat (Claude étend) +json process(const json& input) { + if(input["type"] == "move") return advancedMove(); + if(input["type"] == "attack") return combat(); + return {{"status", "idle"}}; +} + +// Iteration 3: Add AI (Claude sophistique) +// Etc... Progression naturelle +``` + +### Pattern 2: Behavior Composition +```cpp +// Claude peut composer behaviors facilement +class TankModule { + MovementBehavior movement; + CombatBehavior combat; + AiBehavior ai; + + json process(const json& input) { + auto context = getCurrentContext(); + + if(ai.shouldMove(context)) return movement.process(input); + if(ai.shouldAttack(context)) return combat.process(input); + return ai.idle(context); + } +}; +``` + +### Pattern 3: Data-Driven Logic +```cpp +// Claude travaille avec config, pas hard-coding +class TankModule { + json tankConfig; // Loaded from config/tanks.json + + json process(const json& input) { + auto stats = tankConfig["tank_mk1"]; + auto speed = stats["max_speed"].get(); + auto armor = stats["armor_thickness"].get(); + + // Logic basée sur data, pas constantes + return processWithStats(input, speed, armor); + } +}; +``` + +## 🔮 Future Claude Integration + +### Point 48 : AI-Driven Development +**Claude Code génère modules complets via prompts naturels** + +```bash +# Future workflow: Natural language → Working module +User: "Create a tank module with advanced combat AI" + +Claude: +1. Generates TankModule.cpp (250 lines) +2. Includes behavior trees, targeting systems +3. Auto-generates unit tests +4. Configures build system +5. Hot-reloads into running game +6. Result: Fully functional tank AI in minutes +``` + +**Technical Implementation:** +```cpp +class AIModuleGenerator { + json generateModule(const std::string& prompt) { + auto spec = parseNaturalLanguage(prompt); + auto code = generateSourceCode(spec); + auto tests = generateUnitTests(spec); + auto config = generateConfig(spec); + + return { + {"source", code}, + {"tests", tests}, + {"config", config}, + {"build_commands", generateBuild(spec)} + }; + } +}; +``` + +**Benefits:** +- **Rapid prototyping** : Idée → Module fonctionnel en minutes +- **AI pair programming** : Claude comprend context et génère code adapté +- **Automatic optimization** : Claude optimise performance selon targets +- **Self-validating code** : Tests générés automatiquement + +### Point 49 : Natural Language Debugging +**Debug conversation Claude vs tools complexes** + +```bash +# Traditional debugging (avoid) +gdb ./warfactory +(gdb) break TankModule::process +(gdb) run +(gdb) print variables... +# 20+ commands, complex analysis + +# Natural Language Debugging (future) +User: "Tank moves too slowly in mud terrain" + +Claude Debug Session: +🔍 Analyzing TankModule... +📊 Current speed: 28 (expected: 35) +🎯 Issue found: terrain modifier not applied correctly +📝 Location: TankModule.cpp line 142 +⚡ Suggested fix: Update terrain calculation +✅ Fix applied: Tank speed now correct + +# Single conversation → Problem solved +``` + +**Technical Architecture:** +```cpp +class NaturalLanguageDebugger { + void analyzeIssue(const std::string& description) { + // 1. Parse natural language problem description + auto issue = parseIssueDescription(description); + + // 2. Analyze relevant module state + auto moduleState = getModuleState(issue.moduleName); + + // 3. Compare expected vs actual behavior + auto analysis = performAnalysis(issue, moduleState); + + // 4. Generate human-readable explanation + auto explanation = generateExplanation(analysis); + + // 5. Suggest specific fixes + auto suggestions = generateFixSuggestions(analysis); + + // 6. Apply fixes if approved + if(user.approves(suggestions)) { + applyFixes(suggestions); + } + } +}; +``` + +**Debug Conversation Examples:** +``` +User: "Economy module prices seem unstable" +Claude: Detected oscillation in price calculation. Market clearing frequency too high. + Suggested fix: Reduce clearing cycle from 1h to 4h. + +User: "Tank targeting is weird" +Claude: Found issue: Target selection prioritizes distance over threat. + Current: target = findClosest(enemies) + Better: target = findBestThreat(enemies, threatMatrix) + +User: "Factory belt isn't working" +Claude: Belt module shows input blockage. + Problem: Inserter rate 30/min > Belt capacity 20/min + Fix: Upgrade belt or reduce inserter speed +``` + +**Benefits:** +- **Intuitive debugging** : Description naturelle → Solution précise +- **Context-aware analysis** : Claude comprend module interactions +- **Proactive suggestions** : Fixes suggérés avant implementation +- **Learning system** : Claude améliore analysis avec experience + +--- + +## Conclusion + +Cette architecture transforme Claude Code d'un **assistant de développement** en **développeur principal** capable de créer des systèmes de jeu complexes de manière autonome. + +**Clé du succès** : Réduire la complexité cognitive à un niveau où l'IA peut exceller, tout en maintenant la puissance architecturale nécessaire pour un jeu AAA. \ No newline at end of file diff --git a/docs/01-architecture/player-integration.md b/docs/01-architecture/player-integration.md new file mode 100644 index 0000000..c389e7c --- /dev/null +++ b/docs/01-architecture/player-integration.md @@ -0,0 +1,397 @@ +# Intégration du Joueur dans l'Architecture Modulaire + +## 🎯 Problème Identifié + +**Architecture modulaire parfaite... mais où est le joueur ?** + +L'architecture triple interface actuelle gère brillamment la logique métier et la performance, mais il manque un élément crucial : **l'interaction humaine**. + +### Gaps Actuels +- ❌ **Pas d'inputs** clavier/souris +- ❌ **Pas de réactivité UI** temps réel +- ❌ **Client/Server separation** manquante +- ❌ **Multiplayer architecture** non définie + +## 📋 Solution : Client/Server Modulaire + +### Architecture Duale Proposée + +``` +ClientEngine (Local, Réactif) ←→ ServerEngine (Distribué, Autoritaire) +├─ InputModule ├─ TankModule +├─ UIModule ├─ CombatModule +├─ RenderModule ├─ EconomyModule +└─ NetworkModule └─ NetworkModule +``` + +### Principe : Même Architecture, Contexte Différent + +**Client Modules** : Focus UX, réactivité, prédiction +**Server Modules** : Focus logique, autorité, performance + +**Code Sharing** : Logique métier identique, contexte d'exécution différent + +## 🚀 Plan de Développement : 2 Phases Progressives + +### **Phase 1 : V1 - Thin Client (Validation Rapide)** + +#### Objectifs V1 +- ✅ **Validation architecture** : Prouver que l'approche modulaire fonctionne +- ✅ **Focus core logic** : TankModule, CombatModule opérationnels +- ✅ **Gameplay jouable** : Latence acceptable pour validation concept +- ✅ **Claude Code friendly** : Développement parallèle client/server + +#### Architecture V1 : Simple & Efficace + +``` +ClientEngine (Thin) +├─ InputModule → Capture inputs → JSON messages +├─ NetworkModule → WebSocket client → Send to server +└─ RenderModule → Display server state → Simple rendering + +ServerEngine (All Logic) +├─ TankModule → Authoritative tank logic +├─ CombatModule → Game mechanics & physics +├─ EconomyModule → Market simulation +└─ NetworkModule → WebSocket server → Broadcast state +``` + +#### Flow V1 : Server-Authoritative + +``` +Player Input → ClientEngine → Network → ServerEngine → Game Logic → Network → ClientEngine → Display + 50ms 5ms 30ms 20ms 30ms 5ms 10ms +Total : ~150ms latency (acceptable pour validation) +``` + +#### Développement V1 : Claude Code Parallel + +```bash +# Instance Claude A : Client Input +cd modules/client/input/ +cmake . && make input-module # → input.so + +# Instance Claude B : Server Logic +cd modules/server/tank/ +cmake . && make tank-module # → tank.so + +# Instance Claude C : Network +cd modules/shared/network/ +cmake . && make network-module # → network.so +``` + +#### Modules V1 Implementation + +##### InputModule (Client) +```cpp +class InputModule : public ModuleBase { + json process(const json& input) override { + // Keyboard/mouse events → Structured commands + if(input["type"] == "keydown") { + if(input["key"] == "w") return {{"command", "move"}, {"direction", "north"}}; + if(input["key"] == "space") return {{"command", "attack"}}; + } + return {{"command", "idle"}}; + } +}; +``` + +##### NetworkModule (Client) +```cpp +class ClientNetworkModule : public ModuleBase { + json process(const json& input) override { + // Send commands to server via WebSocket + if(input["command"] != "idle") { + webSocketClient.send(input.dump()); + } + + // Receive server state updates + if(webSocketClient.hasMessage()) { + return json::parse(webSocketClient.receive()); + } + + return {{"status", "connected"}}; + } +}; +``` + +##### TankModule (Server) - **Même logique qu'avant !** +```cpp +class TankModule : public ModuleBase { + json process(const json& input) override { + // IDENTICAL logic to single-player version + if(input["command"] == "move") return handleMovement(input); + if(input["command"] == "attack") return handleCombat(input); + return getCurrentState(); + } +}; +``` + +### **Phase 2 : V2 - Client Prediction (Polish UX)** + +#### Objectifs V2 +- ✅ **Réactivité client** : Illusion 0ms lag via prédiction +- ✅ **Code sharing** : Logique métier partagée client/server +- ✅ **Smooth gameplay** : Corrections invisibles, UX fluide +- ✅ **Competitive ready** : Performance multijoueur AAA + +#### Architecture V2 : Shared Logic + Prediction + +``` +SharedGameLogic.so (Code Commun) +├─ TankLogic.cpp +├─ CombatLogic.cpp +└─ PhysicsLogic.cpp + +ClientEngine (Predictive) ServerEngine (Authoritative) +├─ ClientTankModule (Shared + prediction) ├─ ServerTankModule (Shared + validation) +├─ SyncModule (reconciliation) ├─ ValidationModule (anti-cheat) +└─ PredictionModule (client-side) └─ PersistenceModule (save/load) +``` + +#### Flow V2 : Client Prediction + Server Authority + +``` +Player Input → Immediate Client Prediction + Network to Server → Server Validation → Client Reconciliation + 0ms 5ms 30ms 20ms 5ms +User Experience : 0ms (predicted), Corrections invisibles +``` + +#### Migration V1 → V2 : Zero-Risk Evolution + +```cpp +// 1. Extract Shared Logic (TankModule → SharedTankLogic.so) +class SharedTankLogic { + static json CalculateMovement(const json& tank, const json& input) { + // SINGLE SOURCE OF TRUTH for both client & server + return processMovement(tank, input); + } +}; + +// 2. Client Prediction (ClientTankModule) +class ClientTankModule : public ModuleBase { + json process(const json& input) override { + // Immediate prediction using shared logic + auto predicted = SharedTankLogic::CalculateMovement(currentState, input); + + // Send to server for validation + networkModule.send(input); + + return predicted; // Display immediately + } +}; + +// 3. Server Validation (ServerTankModule) +class ServerTankModule : public ModuleBase { + json process(const json& input) override { + // Authoritative calculation using SAME shared logic + auto authoritative = SharedTankLogic::CalculateMovement(serverState, input); + + // Anti-cheat validation + if(validateInput(input)) { + return authoritative; + } + + return {{"error", "invalid_input"}}; + } +}; +``` + +## 🛠️ Implementation Strategy + +### Développement V1 : Thin Client + +#### 1. Client Modules +```bash +modules/client/ +├─ input/ # InputModule : Clavier/souris → JSON +├─ render/ # RenderModule : Server state → Display +└─ network/ # NetworkModule : WebSocket client +``` + +#### 2. Server Modules (Extension Actuelle) +```bash +modules/server/ +├─ tank/ # TankModule : Combat logic (EXISTING) +├─ economy/ # EconomyModule : Market logic (EXISTING) +├─ network/ # NetworkModule : WebSocket server +└─ persistence/ # PersistenceModule : Save/load state +``` + +#### 3. Shared Infrastructure +```bash +modules/shared/ +├─ protocol/ # ProtocolModule : Client/server messages +├─ serialization/ # SerializationModule : JSON optimization +└─ compression/ # CompressionModule : Network optimization +``` + +### Développement V2 : Shared Logic + +#### 1. Logic Extraction +```bash +modules/shared/logic/ +├─ tank-logic/ # SharedTankLogic.so +├─ combat-logic/ # SharedCombatLogic.so +└─ physics-logic/ # SharedPhysicsLogic.so +``` + +#### 2. Client Prediction +```bash +modules/client/prediction/ +├─ tank-prediction/ # ClientTankModule with prediction +├─ sync/ # SyncModule : Reconciliation +└─ interpolation/ # InterpolationModule : Smooth corrections +``` + +#### 3. Server Authority +```bash +modules/server/authority/ +├─ validation/ # ValidationModule : Anti-cheat +├─ simulation/ # SimulationModule : Server-side physics +└─ persistence/ # PersistenceModule : World state +``` + +## 🎮 Claude Code Development Workflow + +### V1 Development : Parallel Instances + +```bash +# Claude Instance A : Client Input +cd modules/client/input/ +# Context : 200 lignes input handling +# Focus : Keyboard/mouse → JSON commands +# Build : cmake . && make input-module + +# Claude Instance B : Server Tank Logic +cd modules/server/tank/ +# Context : 250 lignes tank logic (EXISTING) +# Focus : Command processing, game state +# Build : cmake . && make tank-module + +# Claude Instance C : Network Protocol +cd modules/shared/protocol/ +# Context : 180 lignes network messages +# Focus : JSON serialization, WebSocket +# Build : cmake . && make protocol-module +``` + +### V2 Development : Shared Logic Focus + +```bash +# Claude Instance A : Shared Tank Logic +cd modules/shared/logic/tank/ +# Context : 200 lignes pure tank logic +# Focus : Movement, combat calculations +# Used by : BOTH client prediction AND server authority + +# Claude Instance B : Client Prediction +cd modules/client/prediction/tank/ +# Context : 150 lignes prediction + SharedTankLogic +# Focus : Immediate response, reconciliation +# Build : Links SharedTankLogic.so + +# Claude Instance C : Server Authority +cd modules/server/authority/tank/ +# Context : 180 lignes validation + SharedTankLogic +# Focus : Anti-cheat, persistence +# Build : Links SharedTankLogic.so +``` + +## 📊 Success Metrics & Validation + +### V1 Success Criteria +- [ ] **Player Control** : Tank respond to WASD + mouse +- [ ] **Multiplayer** : 2+ players see synchronized world +- [ ] **Hot-Reload** : Server modules reload without client disconnect +- [ ] **Latency** : <150ms acceptable for core gameplay validation +- [ ] **Claude Code** : 3+ parallel development instances + +### V2 Success Criteria +- [ ] **Instant Response** : Input feels 0ms via client prediction +- [ ] **Smooth Corrections** : No jittering during server reconciliation +- [ ] **Logic Sync** : Client/server calculations stay identical +- [ ] **Hot-Reload** : Both engines support module hot-reload +- [ ] **Performance** : 60fps client, server handles 100+ concurrent players + +### Performance Targets + +#### V1 Targets (Validation) +- **Client FPS** : 30+ fps stable +- **Server Capacity** : 10+ concurrent players +- **Network** : 150ms acceptable latency +- **Development** : Claude Code 200-line contexts + +#### V2 Targets (Production) +- **Client FPS** : 60+ fps with prediction +- **Server Capacity** : 100+ concurrent players +- **Network** : 30ms server latency, 0ms perceived client latency +- **Development** : Shared logic reduces duplication by 80% + +## 🎯 Development Priority & Timeline + +### Immediate : Start V1 (80% effort) +1. **Week 1-2** : InputModule + NetworkModule basique +2. **Week 3-4** : Server TankModule integration + basic rendering +3. **Week 5-6** : Multi-player testing + hot-reload validation +4. **Week 7-8** : Polish V1 + documentation + +### Future : V2 When V1 Stable (20% effort) +1. **Extract** : Shared logic from working V1 modules +2. **Implement** : Client prediction with shared logic +3. **Test** : Prediction accuracy vs server authority +4. **Deploy** : Seamless V1 → V2 migration + +### Development Philosophy +- **V1 first** : Prove architecture works end-to-end +- **Claude Code optimized** : 200-line contexts maintained +- **Hot-reload everywhere** : Both client and server modules +- **Progressive enhancement** : V1 → V2 without code rewrite + +## 🔄 Integration avec Architecture Existante + +### Extension Naturelle +L'architecture modulaire actuelle **s'étend parfaitement** pour supporter client/server : + +```cpp +// EXISTING : Single-player modules +TankModule.so → Pure tank logic + +// V1 EXTENSION : Server-side modules +ServerTankModule.so → Same logic + network authority + +// V2 EVOLUTION : Client + Server + Shared +SharedTankLogic.so → Pure logic (used by both) +ClientTankModule.so → SharedLogic + prediction +ServerTankModule.so → SharedLogic + validation +``` + +### Code Reuse Maximized +- **0% rewrite** : TankModule.cpp devient ServerTankModule.cpp +- **Logic preserved** : Même algorithmes, contexte d'exécution différent +- **Claude Code contexts** : Toujours 200-300 lignes par module +- **Hot-reload maintained** : Architecture triple interface intacte + +## 🎮 User Experience Vision + +### V1 Experience : Functional +- **Responsive** : 150ms latency acceptable pour validation +- **Multiplayer** : Joueurs voient le même monde +- **Development** : Hot-reload permet iteration rapide + +### V2 Experience : Polished +- **Instant** : Inputs feel immediate via prediction +- **Smooth** : Corrections invisibles à l'utilisateur +- **Competitive** : Prêt pour gameplay multijoueur sérieux + +**Résultat** : Architecture modulaire + Player integration = **Jeu AAA développé avec Claude Code** à vitesse révolutionnaire ! 🚀 + +--- + +## Conclusion + +L'intégration du joueur dans l'architecture modulaire suit la même philosophie : + +**"Complexity through Simplicity"** : Chaque module (client ou server) reste simple (200 lignes), mais l'ensemble crée une expérience multijoueur complexe et performante. + +**Claude Code** continue à travailler sur des contextes micro-simples, mais produit maintenant un **jeu multijoueur complet** ! \ No newline at end of file diff --git a/docs/02-systems/CLIMATE_SIMULATION_SYSTEM.md b/docs/02-systems/CLIMATE_SIMULATION_SYSTEM.md new file mode 100644 index 0000000..3712d86 --- /dev/null +++ b/docs/02-systems/CLIMATE_SIMULATION_SYSTEM.md @@ -0,0 +1,488 @@ +# Climate Simulation System + +**Status**: Designed - Ready for Implementation +**Scope**: Realistic climate patterns through mobile wind regions and convergence zones +**Integration**: Uses existing TectonicRegions framework + +## System Overview + +Revolutionary climate simulation using **mobile wind regions** that spawn, evolve, and interact to create emergent weather patterns. Solves the "Sahara vs Congo" problem through **Inter-Tropical Convergence Zones (ITCZ)** and **planetary rotation bands** without complex 3D atmospheric physics. + +### Key Innovations +- **Mobile WindRegions** with token-based distribution system +- **ITCZ gravitational zones** based on continental mass +- **Planetary rotation bands** for realistic circulation patterns +- **Emergent storm evolution** from simple wind interactions +- **Destruction token system** for persistent terrain effects + +## Core Concepts + +### WindRegion Mobile Entities +```json +"wind_region": { + "position": [x, y], + "wind_strength": 1.0, // Base intensity (decays over time) + "wetness": 0.0, // Moisture content (gained over ocean) + "velocity": [vx, vy], // Movement vector + "wind_tokens": 100, // Distributed to tiles + "decay_per_move": 0.02, // -2% strength per movement + "decay_per_tile": 0.01 // -1% strength per tile crossed +} +``` + +### ITCZ Convergence Zones +```json +"itcz_zone": { + "center": [x, y], + "gravitational_range": "sqrt(landmass_area) * 50", + "aspiration_strength": "landmass_mass / distance^2", + "amplification_factor": 3.0, // Wind strength multiplier at center + "latitude_requirement": [0.45, 0.55] // Equatorial band only +} +``` + +## Simulation Architecture + +### Phase 1: Landmass Analysis and ITCZ Generation + +**Uses Existing TectonicRegions:** +```cpp +// Analyze continental masses from existing tectonic data +std::vector continents = groupTectonicRegions(); + +// Generate water masses by inverse analysis +std::vector oceans = detectOceanBasins(continents); + +// Place ITCZ zones on qualifying equatorial landmasses +for (auto& continent : continents) { + if (continent.latitude >= 0.45 && continent.latitude <= 0.55 && + continent.area > MIN_LANDMASS_SIZE) { + createITCZ(continent.center, sqrt(continent.area)); + } +} +``` + +**ITCZ Requirements:** +- **Latitude Band**: 45-55% of map height (equatorial) +- **Minimum Landmass**: 10,000+ tiles +- **Ocean Proximity**: Within 800km for moisture source +- **Continental Heating**: Large thermal mass for convection + +### Phase 2: WindRegion Spawning System + +**Procedural Spawn Rules:** +```json +"wind_spawn_system": { + "spawn_locations": "ocean_masses_only", + "spawn_frequency": "water_mass_size / 1000", + "initial_strength": "water_temperature * evaporation_factor", + "region_size": "sqrt(water_mass_area) / 10", + "tokens_per_region": "base_tokens * size_factor", + "spawn_distribution": "random_within_water_region_biased_toward_center" +} +``` + +**Note**: WindRegions spawn aléatoirement dans le rayon de la waterRegion avec une distribution de spawn plutôt vers le centre pour éviter les spawns en bordure systématiques. + +**Spawn Distribution:** +- **Large Oceans** (Pacific): Big regions, high frequency +- **Medium Seas** (Mediterranean): Medium regions, moderate frequency +- **Small Bays**: Small regions, low frequency +- **No Land Spawning**: All weather originates from water bodies + +### Phase 3: Movement and Planetary Circulation + +**Planetary Rotation Bands** (based on real 10hPa atmospheric data): +```json +"planetary_circulation": { + "polar_jet_north": { + "latitude_range": [0.10, 0.25], + "direction": "west_to_east", + "strength": 1.8 + }, + "calm_transition_1": { + "latitude_range": [0.25, 0.40], + "movement": "chaos_plus_procedural" + }, + "equatorial_trades": { + "latitude_range": [0.40, 0.60], + "direction": "east_to_west", + "strength": 1.5 + }, + "calm_transition_2": { + "latitude_range": [0.60, 0.75], + "movement": "chaos_plus_procedural" + }, + "polar_jet_south": { + "latitude_range": [0.75, 0.95], + "direction": "west_to_east", + "strength": 1.8 + } +} +``` + +**Movement Calculation:** +```cpp +Vector2 movement = + planetary_rotation_band * 0.6 + // 60% planetary circulation + equator_to_pole_bias * 0.2 + // 20% thermal circulation + terrain_deflection * 0.1 + // 10% topographic influence + random_variation * 0.1; // 10% chaos +``` + +### Phase 4: WindRegion Evolution and Interactions + +**Dynamic Evolution:** +```cpp +void updateWindRegion(WindRegion& region) { + // Gain moisture over water + if (currentTile.isOcean()) { + region.wetness += OCEAN_MOISTURE_GAIN; + } + + // Repulsion from other regions = acceleration + // NOTE: Not physical repulsion - proxy for spatial competition and turbulence + // Prevents region stacking while creating realistic dispersion patterns + // CRITIQUE POINT: May cause "force field" effect around ITCZ zones where regions + // oscillate/scatter instead of converging due to attraction vs repulsion conflict. + // Alternative approaches: density-based drift, no interaction, or collision division. + // TODO: Implement as configurable algorithm options for empirical testing. + float repulsion = calculateRepulsionForce(region, nearbyRegions); + region.wind_strength += repulsion * ACCELERATION_FACTOR; + + // Movement decay + region.wind_strength *= (1.0 - DECAY_PER_MOVE); + + // Tile crossing cost + region.wind_strength *= (1.0 - DECAY_PER_TILE); + + // Die when too weak + if (region.wind_strength < MINIMUM_THRESHOLD) { + destroyRegion(region); + } +} +``` + +**ITCZ Gravitational Effects:** +```cpp +void applyITCZGravity(WindRegion& region) { + for (auto& itcz : active_itcz_zones) { + float distance = calculateDistance(region.position, itcz.center); + + if (distance < itcz.gravitational_range) { + // Attraction force (inverse square law) + // NOTE: "Gravitational" metaphor for influence strength, not literal physics + // Like saying someone has "gravitas" - clear semantic meaning for developers + float attraction = itcz.mass / (distance * distance); + Vector2 pull_direction = normalize(itcz.center - region.position); + + // Apply attraction + region.velocity += pull_direction * attraction; + + // Amplification effect as region approaches + float proximity = (itcz.range - distance) / itcz.range; + float amplification = 1.0 + (itcz.max_amplification * proximity); + + region.wind_strength *= amplification; + region.wetness *= amplification; + } + } +} +``` + +### Phase 5: Storm Classification and Token Distribution + +**Climate Zone Classification:** +```cpp +// Simple thresholds for climate zone determination +const float HIGH_WIND_THRESHOLD = 2.0; +const float FLOOD_THRESHOLD = 1.5; +const float HURRICANE_WIND = 2.5; +const float HURRICANE_RAIN = 2.0; + +bool isHighWindZone(const WindRegion& region) { + return region.wind_strength >= HIGH_WIND_THRESHOLD; +} + +bool isFloodZone(const WindRegion& region) { + return region.wetness >= FLOOD_THRESHOLD; +} + +bool isHurricaneZone(const WindRegion& region) { + return region.wind_strength >= HURRICANE_WIND && region.wetness >= HURRICANE_RAIN; +} +``` + +**Token Distribution System:** +```cpp +void distributeTokens(WindRegion& region) { + // Basic climate tokens for all regions + int wind_tokens = static_cast(region.wind_strength * 10); + int rain_tokens = static_cast(region.wetness * 10); + + WorldTile& tile = world_map.getTile(region.position); + tile.addTokens("wind", wind_tokens); + tile.addTokens("rain", rain_tokens); + + // Special climate zone tokens for extreme weather + if (isHighWindZone(region)) { + tile.addTokens("highWind", 1); // Hostile to forests + } + if (isFloodZone(region)) { + tile.addTokens("flood", 1); // Forces wetlands/marshes + } + if (isHurricaneZone(region)) { + tile.addTokens("hurricane", 1); // Specialized hurricane biome + } + + // Consume distributed tokens from region + region.wind_tokens -= wind_tokens; + region.rain_tokens -= rain_tokens; +} +``` + +## Geographic Climate Patterns + +### Realistic Climate Formation + +**Congo Basin (Rainforest):** +``` +1. Large African landmass → Strong ITCZ at equator +2. Atlantic wind regions spawn → Move east via trade winds +3. ITCZ aspiration → Convergence at Congo → Amplification ×3 +4. Super-humid storms → Massive rain token distribution +5. Result: Dense rainforest biome +``` + +**Sahara Desert:** +``` +1. Sahara latitude (25-35°N) → Outside ITCZ band +2. No convergence zone → Wind regions pass through +3. Continental distance → Low initial moisture +4. Subtropical high pressure → Air descends (simulated via movement patterns) +5. Result: Minimal rain tokens → Desert biome +``` + +**Egypt/Algeria Coastal:** +``` +1. Mediterranean wind regions → Moderate moisture +2. Coastal proximity → Some rain tokens +3. Sahara interior → Moisture depleted inland +4. Result: Mediterranean coastal climate → Desert interior gradient +``` + +### Emergent Seasonal Patterns + +**ITCZ Strength Variation:** +```json +"seasonal_modulation": { + "itcz_strength_summer": 1.5, // Stronger convection + "itcz_strength_winter": 0.8, // Weaker convection + "spawn_rate_summer": 1.3, // More wind regions + "spawn_rate_winter": 0.7 // Fewer wind regions +} +``` + +**Results:** +- **Monsoon Seasons**: ITCZ amplification cycles +- **Hurricane Seasons**: Increased spawn rates + ITCZ amplification +- **Dry Seasons**: Reduced ITCZ strength + lower spawn rates + +## Climate Zone Effects on Biome Generation + +### Token-Based Biome Classification + +**Climate Token Usage:** +```cpp +BiomeType classifyBiome(const WorldTile& tile) { + int total_rain = tile.getAccumulatedTokens("rain"); + int total_wind = tile.getAccumulatedTokens("wind"); + int highWind_tokens = tile.getAccumulatedTokens("highWind"); + int flood_tokens = tile.getAccumulatedTokens("flood"); + int hurricane_tokens = tile.getAccumulatedTokens("hurricane"); + + // Special climate zones override normal biome classification + if (hurricane_tokens > 0) { + return BiomeType::HURRICANE_ZONE; // Specialized storm-resistant vegetation + } + if (flood_tokens > FLOOD_THRESHOLD) { + return BiomeType::WETLANDS; // Forced marshes/swamps + } + if (highWind_tokens > STORM_THRESHOLD) { + // High wind prevents forest growth + if (total_rain > 300) { + return BiomeType::STORM_PRAIRIE; // Grasslands that can handle wind + } else { + return BiomeType::BADLANDS; // Sparse, wind-resistant vegetation + } + } + + // Normal biome classification using basic rain/wind tokens + if (total_rain > 500) { + return BiomeType::TROPICAL_RAINFOREST; + } else if (total_rain < 50) { + return BiomeType::HOT_DESERT; + } + // ... additional normal biome logic +} +``` + +**Climate Zone Characteristics:** +- **Hurricane Zones** → Storm-resistant palms, specialized coastal vegetation +- **Flood Zones** → Wetlands, marshes, swamp vegetation mandatory +- **High Wind Zones** → No forests allowed, prairie/badlands only +- **Normal Zones** → Standard biome classification by rain/temperature + +## Performance Characteristics + +### Computational Complexity +- **Wind Regions**: O(n) for n active regions (~50-200 simultaneously) +- **ITCZ Calculations**: O(m) for m convergence zones (~5-15 globally) +- **Token Distribution**: O(tiles_visited) per region movement +- **Total per cycle**: O(n × average_movement_distance) + +### Memory Usage +- **WindRegion**: 32 bytes per region +- **ITCZ Zone**: 24 bytes per zone +- **Token accumulation**: Uses existing tile data structure +- **Estimated total**: <5MB for global weather simulation + +### Generation Time +- **Landmass analysis**: 1-2 seconds (one-time setup) +- **Per simulation cycle**: 10-50ms for 100-200 wind regions +- **Full climate stabilization**: 100-500 cycles → 10-30 seconds total + +## Integration with Existing Systems + +### TectonicRegions Reuse +```cpp +// Leverage existing tectonic analysis +class ClimateSystem { + void initializeFromTectonics(const std::vector& regions) { + auto continents = groupRegionsByProximity(regions); + auto oceans = calculateOceanBasins(continents); + + generateITCZFromContinents(continents); + setupWindSpawnFromOceans(oceans); + } +}; +``` + +### RegionalInfluence Framework +```cpp +// Wind regions as mobile regional influences +class WindRegion : public RegionalInfluence { + void applyInfluenceToTile(WorldTile& tile) override { + distributeTokens(tile); + + // Create regional influence for persistent effects + if (isStormLevel()) { + createPersistentInfluence(tile, getStormType()); + } + } +}; +``` + +### Biome Generation Integration +```cpp +// Use accumulated climate tokens for biome classification +BiomeType classifyBiome(const WorldTile& tile) { + int total_rain = tile.getAccumulatedTokens("rain"); + int total_wind = tile.getAccumulatedTokens("wind"); + float temperature = tile.getTemperature(); + + if (total_rain > 500 && temperature > 20.0f) { + return BiomeType::TROPICAL_RAINFOREST; + } else if (total_rain < 50 && temperature > 15.0f) { + return BiomeType::HOT_DESERT; + } + // ... additional biome logic +} +``` + +## Implementation Priority + +### Phase 1: Core Framework (1-2 weeks) +1. WindRegion class and basic movement +2. Token distribution system +3. Simple spawn from ocean detection +4. Basic planetary circulation bands + +### Phase 2: ITCZ System (1-2 weeks) +1. Landmass analysis from TectonicRegions +2. ITCZ generation and gravitational effects +3. Wind region amplification mechanics +4. Storm classification system + +### Phase 3: Advanced Features (1-2 weeks) +1. Destruction token system and persistent effects +2. Seasonal variation and modulation +3. Performance optimization +4. Integration with biome generation + +### Phase 4: Tuning and Validation (1 week) +1. Parameter adjustment for realistic patterns +2. Verification of Congo/Sahara differentiation +3. Performance profiling and optimization +4. Documentation and examples + +## Configuration Example + +```json +{ + "climate_simulation": { + "wind_spawn_system": { + "base_spawn_rate": 0.1, + "ocean_size_factor": 0.001, + "max_concurrent_regions": 200 + }, + "planetary_circulation": { + "trade_winds_strength": 1.5, + "jet_stream_strength": 1.8, + "calm_zone_chaos": 0.3 + }, + "itcz_system": { + "latitude_band": [0.45, 0.55], + "min_landmass_size": 10000, + "max_ocean_distance": 800, + "amplification_max": 3.0 + }, + "storm_thresholds": { + "high_wind_min": 2.0, + "flood_wetness_min": 1.5, + "hurricane_wind_min": 2.5, + "hurricane_rain_min": 2.0 + }, + "token_distribution": { + "wind_token_factor": 10, + "rain_token_factor": 10, + "climate_zone_rate": 1 + } + } +} +``` + +**Note**: All parameters are hot-reloadable via the modular configuration system. Magic numbers are intentionally externalizable for real-time tuning during development - adjust values, save config, see immediate results without recompilation. +``` + +## Scientific Accuracy vs Gameplay + +### Scientifically Inspired Elements +- ✅ ITCZ formation from continental heating +- ✅ Planetary circulation bands (trade winds, jet streams) +- ✅ Storm formation from wind-moisture interaction +- ✅ Geographic influence on climate patterns +- ✅ Persistent landscape effects from weather + +### Gameplay Simplifications +- ⚠️ 2D simulation instead of 3D atmospheric layers +- ⚠️ Simplified storm evolution (no pressure systems) +- ⚠️ Discrete token system instead of continuous fields +- ⚠️ Accelerated timeframes for practical simulation + +### Result +**Plausible climate science** that creates **engaging gameplay** with **emergent complexity** from **simple, understandable rules**. + +--- + +**Status**: System designed and ready for implementation. Provides realistic climate differentiation (Sahara vs Congo) through elegant mobile region simulation using existing tectonic framework. \ No newline at end of file diff --git a/docs/02-systems/GEOLOGICAL_SIMULATION_SYSTEM.md b/docs/02-systems/GEOLOGICAL_SIMULATION_SYSTEM.md new file mode 100644 index 0000000..892d0a7 --- /dev/null +++ b/docs/02-systems/GEOLOGICAL_SIMULATION_SYSTEM.md @@ -0,0 +1,1886 @@ +# Geological Simulation System + +**Status**: Designed - Ready for Implementation +**Scope**: Complete planetary formation from accretion to industrial-ready geology +**Duration**: 4.65 billion years simulation in 95 cycles + +## System Overview + +Revolutionary geological simulation system that generates realistic planetary geology through scientifically-inspired processes. Creates diverse, coherent geology with proper resource distribution for industrial gameplay. + +### Key Innovations +- **RegionalInfluence framework** adapted for geological processes +- **Tectonic regions** as simple circles with forces (not complex mesh) +- **Carbon region system** for realistic coal/oil formation +- **Dynamic sea level** affecting all geological processes +- **Optimized 24-byte tiles** supporting geological temperature ranges + +## Simulation Phases + +### Phase 1: Planetary Accretion (30 cycles × 100M years = 3.0 Ga) + +**Initial Conditions**: +- Temperature: -100°C (space cold) +- Elevation: -30,000m (no surface) +- Empty planetary core + +**Process - Meteorite Bombardment**: +``` +For each wave (100M years): + 1. Generate 100-500 random meteorite impacts + 2. Each impact adds: + - Kinetic energy → heat (up to +2000°C) + - Mass → elevation change (+crater formation) + - Metal composition → resource deposits + 3. Heavy metals sink to planetary core + 4. Core temperature drives volcanic eruptions + 5. Eruptions redistribute core metals to surface + 6. Gradual cooling between waves +``` + +**Expected Results**: +- Surface elevation: -30,000m → -15,000m +- Core composition: 80% iron, 15% nickel, 5% precious metals +- Crater-based geology with metal deposits +- Temperature stabilization around 1000-1500°C + +### Phase 2: Tectonic Formation (25 cycles × 100M years = 2.5 Ga) + +**Reduced Meteorite Activity**: +```cpp +// Phase 2 meteorite parameters (reduced from Phase 1) +impacts_per_wave = rng.randInt(10, 50); // 10x reduction +meteorite_mass = rng.randFloat(10^12, 10^15); // Smaller impacts +impact_probability = 0.3f; // 30% chance per cycle +``` + +**Tectonic Region System**: +```cpp +struct TectonicRegion { + uint32_t region_id; + float center_x, center_y; // Mobile center (world coordinates) + float radius; // Current radius (tiles) + float velocity_x, velocity_y; // Movement (tiles per cycle) + float mass; // For repulsive force calculations + RegionType type; // OCEANIC, CONTINENTAL, VOLCANIC + + // Evolution parameters + float split_probability; // Chance to divide (0.01 = 1% per cycle) + float growth_rate; // Radius change per cycle (+/- tiles) + float stability; // Resistance to external forces + + // Formation tracking + int formation_cycle; // When this region was created + uint32_t parent_region_id; // If split from another region +}; + +enum class RegionType { + OCEANIC, // Dense, subducts under continental + CONTINENTAL, // Light, forms mountains when compressed + VOLCANIC, // Active volcanic zone (temporary) +}; +``` + +**Tectonic Physics Engine**: +```cpp +void updateTectonicRegions(float time_step) { + // 1. Calculate repulsive forces between all regions + for (auto& region1 : tectonic_regions) { + Vector2 total_force = {0.0f, 0.0f}; + + for (auto& region2 : tectonic_regions) { + if (region1.region_id == region2.region_id) continue; + + float distance = calculateDistance(region1.center, region2.center); + float overlap = (region1.radius + region2.radius) - distance; + + if (overlap > 0) { + // Collision detected! + Vector2 repulsion_direction = normalize(region1.center - region2.center); + + // Force magnitude: F = k * overlap^2 / (mass1 + mass2) + float force_magnitude = REPULSION_CONSTANT * overlap * overlap / + (region1.mass + region2.mass); + + Vector2 repulsion_force = repulsion_direction * force_magnitude; + total_force += repulsion_force; + + // Create volcanic zone at collision point + createVolcanicZone(region1, region2, overlap); + } + } + + // Apply acceleration: a = F/m + Vector2 acceleration = total_force / region1.mass; + region1.velocity_x += acceleration.x * time_step; + region1.velocity_y += acceleration.y * time_step; + + // Apply velocity damping (friction) + region1.velocity_x *= VELOCITY_DAMPING; + region1.velocity_y *= VELOCITY_DAMPING; + } + + // 2. Update positions and sizes + for (auto& region : tectonic_regions) { + // Move regions + region.center_x += region.velocity_x * time_step; + region.center_y += region.velocity_y * time_step; + + // Boundary wrapping (world is spherical) + wrapCoordinates(region.center_x, region.center_y); + + // Evolve size + region.radius += region.growth_rate * time_step; + region.radius = std::clamp(region.radius, MIN_REGION_RADIUS, MAX_REGION_RADIUS); + + // Check for splitting + if (region.radius > SPLIT_THRESHOLD && + rng.probability(region.split_probability * time_step)) { + splitTectonicRegion(region); + } + } +} +``` + +**Volcanic Zone Creation**: +```cpp +void createVolcanicZone(TectonicRegion& r1, TectonicRegion& r2, float collision_intensity) { + // Volcanic zone at intersection point + Vector2 intersection = calculateIntersectionCenter(r1, r2); + float volcanic_radius = collision_intensity * VOLCANIC_RADIUS_FACTOR; + + // Create temporary volcanic region + TectonicRegion volcanic_zone = { + .center_x = intersection.x, + .center_y = intersection.y, + .radius = volcanic_radius, + .type = RegionType::VOLCANIC, + .formation_cycle = current_cycle, + .split_probability = 0.05f, // High chance to break apart + .growth_rate = -0.1f // Shrinks over time + }; + + // Apply volcanic influence to affected tiles + RegionalInfluence volcanic_influence = { + .type = "volcanic_mountain_formation", + .intensity = collision_intensity, + .properties = json{ + {"elevation_bonus", collision_intensity * 500.0f}, // +500m per intensity + {"temperature_bonus", collision_intensity * 300.0f}, // +300°C + {"resource_deposits", json::array({"iron", "sulfur", "rare_metals"})}, + {"volcanic_features", json::array({"volcano", "hot_springs", "lava_tubes"})} + } + }; + + applyRegionalInfluence(volcanic_influence, intersection.x, intersection.y, volcanic_radius); + tectonic_regions.push_back(volcanic_zone); +} +``` + +**Region Splitting Algorithm**: +```cpp +void splitTectonicRegion(TectonicRegion& parent) { + // Create two child regions + float split_distance = parent.radius * 0.4f; + Vector2 split_direction = randomUnitVector(); + + TectonicRegion child1 = parent; + TectonicRegion child2 = parent; + + // Assign new IDs + child1.region_id = next_region_id++; + child2.region_id = next_region_id++; + child1.parent_region_id = parent.region_id; + child2.parent_region_id = parent.region_id; + + // Separate positions + child1.center_x += split_direction.x * split_distance; + child1.center_y += split_direction.y * split_distance; + child2.center_x -= split_direction.x * split_distance; + child2.center_y -= split_direction.y * split_distance; + + // Reduce sizes + child1.radius *= 0.7f; + child2.radius *= 0.7f; + + // Opposite velocities (moving apart) + child1.velocity_x = split_direction.x * SPLIT_VELOCITY; + child1.velocity_y = split_direction.y * SPLIT_VELOCITY; + child2.velocity_x = -split_direction.x * SPLIT_VELOCITY; + child2.velocity_y = -split_direction.y * SPLIT_VELOCITY; + + // Replace parent with children + removeRegion(parent); + addRegion(child1); + addRegion(child2); + + // Create rift valley between children + createRiftValley(child1, child2); +} +``` + +**Expected Results**: +- Surface elevation: -15,000m → -5,000m (+10km crustal thickening) +- Formation of 15-25 stable tectonic regions +- Mountain ranges at collision zones (+1000-3000m elevation) +- Rift valleys where regions separate (-500m elevation) +- Distinct continental vs oceanic regions + +### Phase 3: Hydrological Cycles (25 cycles × 20M years = 0.5 Ga) + +**Dynamic Sea Level System**: +```cpp +struct OceanLevel { + float current_sea_level; // Global reference (meters) + float ice_volume; // Polar ice volume (km³) + float thermal_expansion_factor; // Ocean thermal expansion coefficient + float tectonic_basin_volume; // Total oceanic basin volume + + void updateSeaLevel(float global_temperature, float volcanic_co2) { + // 1. Ice volume changes (glaciation/melting) + float target_ice_volume = calculateIceVolume(global_temperature); + float ice_change = (target_ice_volume - ice_volume) * 0.1f; // 10% change per cycle + ice_volume += ice_change; + + // Sea level change: 1 km³ ice = +2.7mm sea level + float ice_effect = -ice_change * 0.0027f; + + // 2. Thermal expansion + float thermal_effect = (global_temperature - 15.0f) * thermal_expansion_factor; + + // 3. Tectonic effects (basin formation/destruction) + float tectonic_effect = (tectonic_basin_volume - baseline_basin_volume) * 0.001f; + + // 4. Update sea level + current_sea_level += ice_effect + thermal_effect + tectonic_effect; + current_sea_level = std::clamp(current_sea_level, -200.0f, +100.0f); // Realistic bounds + } + + float calculateIceVolume(float global_temp) const { + if (global_temp < -5.0f) return MAX_ICE_VOLUME; // Ice age + if (global_temp > 25.0f) return 0.0f; // No ice + return MAX_ICE_VOLUME * (25.0f - global_temp) / 30.0f; // Linear interpolation + } +}; +``` + +**Hydraulic Erosion System**: +```cpp +void applyHydraulicErosion(float cycle_duration_years) { + const float HYDRAULIC_EFFICIENCY = 10.0f; // 10x more effective than tectonic + + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + float elevation = tile.getElevation(); + + if (elevation > current_sea_level) { + // CONTINENTAL EROSION + + // 1. Calculate water flow (slope-based) + float average_neighbor_elevation = calculateAverageNeighborElevation(x, y); + float slope = elevation - average_neighbor_elevation; + float water_flow = std::max(0.0f, slope * 0.01f); // Flow intensity + + // 2. Erosion rate based on elevation and flow + float elevation_factor = (elevation - current_sea_level) / 1000.0f; // Higher = more erosion + float erosion_rate = water_flow * elevation_factor * HYDRAULIC_EFFICIENCY; + + // 3. Apply erosion + float erosion_amount = erosion_rate * cycle_duration_years / 1000000.0f; // Per million years + tile.setElevation(elevation - erosion_amount); + + // 4. Transport sediments downstream + transportSediments(tile, x, y, erosion_amount); + + } else if (elevation > current_sea_level - 200.0f) { + // COASTAL EROSION + + float depth_below_sea = current_sea_level - elevation; + float coastal_erosion_rate = 50.0f; // Intense coastal erosion + + if (depth_below_sea < 50.0f) { // Shallow coastal zone + float erosion_amount = coastal_erosion_rate * cycle_duration_years / 1000000.0f; + tile.setElevation(elevation - erosion_amount); + + // Form beaches and deltas + if (hasRiverInput(x, y)) { + formDelta(tile, x, y); + } + } + + } else { + // DEEP OCEAN - sediment deposition + + float sedimentation_rate = calculateSedimentInput(x, y); + float deposition_amount = sedimentation_rate * cycle_duration_years / 1000000.0f; + tile.setElevation(elevation + deposition_amount); + } + } + } +} + +void transportSediments(WorldTile& source_tile, int x, int y, float sediment_amount) { + // Find steepest downhill direction + auto [target_x, target_y] = findSteepestDescentDirection(x, y); + + if (target_x != x || target_y != y) { + WorldTile target_tile = world_map->getTile(target_x, target_y); + + // Deposit sediments at target + float current_elevation = target_tile.getElevation(); + target_tile.setElevation(current_elevation + sediment_amount * 0.5f); // 50% deposition + + // Create river network + createRiverSegment(x, y, target_x, target_y); + + // Continue transport if target is above sea level + if (target_tile.getElevation() > current_sea_level) { + transportSediments(target_tile, target_x, target_y, sediment_amount * 0.5f); + } + } +} +``` + +**River Network Formation**: +```cpp +struct RiverNetwork { + std::unordered_map> river_connections; // tile -> downstream tiles + std::unordered_map flow_volumes; // tile -> water volume + + void createRiverSegment(int from_x, int from_y, int to_x, int to_y) { + uint32_t from_index = from_y * map_width + from_x; + uint32_t to_index = to_y * map_width + to_x; + + // Add connection + river_connections[from_index].push_back(to_index); + + // Increase flow volume + flow_volumes[to_index] += flow_volumes[from_index] + 1.0f; + + // Mark tiles as having river features + WorldTile from_tile = world_map->getTile(from_x, from_y); + WorldTile to_tile = world_map->getTile(to_x, to_y); + + from_tile.setFlag(TileFlags::HAS_RIVER, true); + to_tile.setFlag(TileFlags::HAS_RIVER, true); + } + + void formDelta(WorldTile& tile, int x, int y) { + // Delta formation where river meets ocean + RegionalInfluence delta_influence = { + .type = "river_delta", + .intensity = flow_volumes[y * map_width + x] / 100.0f, // Intensity based on river size + .properties = json{ + {"elevation_bonus", 10.0f}, // Slight elevation increase + {"sediment_richness", 1.5f}, // Rich sediments + {"features", json::array({"wetlands", "fertile_soil", "natural_harbors"})} + } + }; + + applyRegionalInfluence(delta_influence, x, y, 5.0f); // 5-tile radius + } +}; +``` + +**Climate Integration**: +```cpp +void updateGlobalClimate(float cycle_duration) { + // 1. Volcanic CO2 emissions + float volcanic_co2 = calculateVolcanicCO2Emissions(); + atmospheric_co2 += volcanic_co2; + + // 2. Weathering CO2 absorption + float weathering_absorption = calculateWeatheringRate() * cycle_duration; + atmospheric_co2 -= weathering_absorption; + + // 3. Temperature from CO2 (greenhouse effect) + global_temperature = BASE_TEMPERATURE + log(atmospheric_co2 / BASELINE_CO2) * CLIMATE_SENSITIVITY; + + // 4. Update sea level based on new temperature + ocean_level.updateSeaLevel(global_temperature, volcanic_co2); + + // 5. Regional climate effects + updateRegionalClimate(); +} + +void updateRegionalClimate() { + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + float elevation = tile.getElevation(); + + // Temperature varies with elevation (lapse rate: -6.5°C/km) + float local_temperature = global_temperature - (elevation / 1000.0f) * 6.5f; + + // Distance from ocean affects temperature (continental effect) + float ocean_distance = calculateDistanceToOcean(x, y); + float continental_effect = ocean_distance / 1000.0f * 2.0f; // +2°C per 1000km inland + local_temperature += continental_effect; + + tile.setTemperature(local_temperature); + + // Humidity based on proximity to water and temperature + float humidity = calculateHumidity(ocean_distance, local_temperature, elevation); + tile.setHumidity(humidity); + } + } +} +``` + +**Expected Results**: +- Surface elevation: -5,000m → 0m (modern sea level) +- Formation of permanent river networks draining to oceans +- Coastal features: deltas, beaches, fjords, cliffs +- Climate zones established based on elevation and ocean proximity +- Sedimentary basins filled with eroded material + +### Phase 4: Carboniferous Period (35 cycles × 10M years = 0.35 Ga) + +**Dynamic Forest System**: +```cpp +// Forest seeds are continuously created and destroyed by geological events +void manageDynamicForests(GMap& map, int cycle) { + // Always seed new forests with base probability + seedNewForests(map); + + // Existing forests attempt to expand + expandExistingForests(map); + + // Geological events destroy forests + destroyForestsByGeologicalEvents(map, cycle); +} + +void seedNewForests(GMap& map) { + for (each_tile) { + float seed_probability = base_forest_seed_rate; + + // Environmental modifiers + if (tile.getTemperature() >= 15.0f && tile.getTemperature() <= 35.0f) { + seed_probability *= temperature_bonus; // Optimal temperature + } + if (tile.getHumidity() > 0.4f) { + seed_probability *= humidity_bonus; // Sufficient moisture + } + if (tile.getElevation() < 2000.0f) { + seed_probability *= elevation_bonus; // Below treeline + } + + if (random() < seed_probability) { + createForestSeed(tile); + } + } +} + +void expandExistingForests(GMap& map) { + for (each_forest_tile) { + for (each_neighbor) { + if (isViableForForest(neighbor) && random() < forest_expansion_rate) { + expandForestTo(neighbor); + } + } + } +} + +void destroyForestsByGeologicalEvents(GMap& map, int cycle) { + // Volcanic eruptions destroy forests + for (auto& volcanic_event : getCurrentVolcanicEvents(cycle)) { + destroyForestsInRadius(volcanic_event.center, volcanic_event.destruction_radius); + } + + // Major floods destroy forests + for (each_tile_with_extreme_water_level) { + if (tile.getWaterLevel() > flood_destruction_threshold) { + destroyForest(tile); + } + } + + // Extreme erosion destroys forests + for (each_tile) { + if (getCurrentErosionRate(tile) > erosion_destruction_threshold) { + destroyForest(tile); + } + } + + // Climate extremes destroy forests + if (tile.getTemperature() < -10.0f || tile.getTemperature() > 50.0f) { + destroyForest(tile); + } +} +``` + +**Carbon Region System**: +```cpp +struct CarbonRegion { + uint32_t region_id; + float center_x, center_y; // Position (world coordinates) + float radius; // Affected area (tiles) + float carbon_mass; // Total carbon content (megatons) + int formation_cycle; // When this region was created + CarbonType type; // Current state: COAL, OIL, GAS + + // Tectonic attachment + uint32_t attached_tectonic_region_id; // Moves with tectonic plate + float attachment_strength; // 0.8-1.0 (strong attachment) + + // Conversion tracking + float original_coal_mass; // Initial coal amount + float conversion_progress; // 0.0-1.0 (coal→oil conversion) + int cycles_underwater; // How long submerged +}; + +enum class CarbonType { + COAL, // Terrestrial formation + OIL, // Marine conversion + NATURAL_GAS // Late-stage oil maturation +}; +``` + +**Forest Growth and Coal Formation**: +```cpp +void processForestGrowth(int cycle) { + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + + if (isForestSuitable(tile, x, y)) { + float biomass_potential = calculateBiomassPotential(tile); + float forest_density = std::min(1.0f, biomass_potential); + + if (forest_density > 0.3f) { // Minimum density for coal formation + // Create or enhance carbon region + CarbonRegion* existing_region = findNearestCarbonRegion(x, y, 5.0f); + + if (existing_region) { + // Add to existing region + enhanceCarbonRegion(*existing_region, forest_density); + } else { + // Create new carbon region + CarbonRegion new_region = createCarbonRegion(x, y, forest_density, cycle); + carbon_regions.push_back(new_region); + } + } + } + } + } + + // Merge nearby carbon regions + mergeCarbonRegions(); +} + +bool isForestSuitable(const WorldTile& tile, int x, int y) { + float elevation = tile.getElevation(); + float temperature = tile.getTemperature(); + float humidity = tile.getHumidity(); + + return (elevation > current_sea_level + 10.0f) && // Above sea level + (elevation < current_sea_level + 1000.0f) && // Not too mountainous + (temperature >= 10.0f && temperature <= 30.0f) && // Temperate range + (humidity > 0.4f) && // Sufficient moisture + (!tile.getFlag(TileFlags::VOLCANIC_ACTIVE)); // Not volcanically active +} + +CarbonRegion createCarbonRegion(int x, int y, float forest_density, int cycle) { + CarbonRegion region; + region.region_id = next_carbon_region_id++; + region.center_x = x; + region.center_y = y; + region.radius = forest_density * 8.0f; // Dense forests = larger regions + region.carbon_mass = forest_density * 100.0f; // Base carbon mass (megatons) + region.formation_cycle = cycle; + region.type = CarbonType::COAL; + + // Attach to nearest tectonic region + TectonicRegion* nearest_tectonic = findNearestTectonicRegion(x, y); + if (nearest_tectonic) { + region.attached_tectonic_region_id = nearest_tectonic->region_id; + region.attachment_strength = 0.9f; // Strong attachment + } + + return region; +} +``` + +**Carbon Region Movement and Merging**: +```cpp +void updateCarbonRegionMovement(float time_step) { + for (auto& carbon_region : carbon_regions) { + TectonicRegion* tectonic = getTectonicRegion(carbon_region.attached_tectonic_region_id); + + if (tectonic) { + // Move with tectonic plate + carbon_region.center_x += tectonic->velocity_x * carbon_region.attachment_strength * time_step; + carbon_region.center_y += tectonic->velocity_y * carbon_region.attachment_strength * time_step; + + // Handle tectonic collisions + if (tectonic->isInCollision()) { + float collision_stress = tectonic->getCollisionIntensity(); + + if (collision_stress > 2.0f) { + // High stress can redistribute carbon deposits + redistributeCarbonDeposit(carbon_region, collision_stress); + } + } + } + } +} + +void mergeCarbonRegions() { + for (size_t i = 0; i < carbon_regions.size(); ++i) { + for (size_t j = i + 1; j < carbon_regions.size(); ++j) { + float distance = calculateDistance(carbon_regions[i].center, carbon_regions[j].center); + float merge_threshold = (carbon_regions[i].radius + carbon_regions[j].radius) * 0.8f; + + if (distance < merge_threshold) { + // Merge regions + CarbonRegion merged; + merged.region_id = next_carbon_region_id++; + merged.center_x = (carbon_regions[i].center_x + carbon_regions[j].center_x) / 2.0f; + merged.center_y = (carbon_regions[i].center_y + carbon_regions[j].center_y) / 2.0f; + merged.radius = sqrt(carbon_regions[i].radius * carbon_regions[i].radius + + carbon_regions[j].radius * carbon_regions[j].radius); + merged.carbon_mass = carbon_regions[i].carbon_mass + carbon_regions[j].carbon_mass; + merged.formation_cycle = std::min(carbon_regions[i].formation_cycle, carbon_regions[j].formation_cycle); + merged.type = CarbonType::COAL; // Combined regions start as coal + + // Remove original regions and add merged + carbon_regions.erase(carbon_regions.begin() + j); + carbon_regions.erase(carbon_regions.begin() + i); + carbon_regions.push_back(merged); + + break; // Start over after modification + } + } + } +} +``` + +**Coal to Oil Conversion**: +```cpp +void processCoalToOilConversion(int current_cycle) { + const float CONVERSION_RATE_PER_CYCLE = 0.05f; // 5% per cycle (10M years) + const float NATURAL_GAS_RATIO = 0.15f; // 15% of oil becomes gas + + for (auto& coal_region : carbon_regions) { + if (coal_region.type == CarbonType::COAL && isRegionUnderwater(coal_region)) { + coal_region.cycles_underwater++; + + // Only convert if underwater for multiple cycles (pressure + time) + if (coal_region.cycles_underwater >= 3) { + float conversion_amount = coal_region.carbon_mass * CONVERSION_RATE_PER_CYCLE; + + if (conversion_amount > 1.0f) { // Minimum threshold + // Create oil region at same location + CarbonRegion oil_region = coal_region; + oil_region.region_id = next_carbon_region_id++; + oil_region.type = CarbonType::OIL; + oil_region.carbon_mass = conversion_amount; + oil_region.radius *= 0.8f; // Oil regions are more concentrated + oil_region.formation_cycle = current_cycle; + + // Create natural gas as byproduct + if (conversion_amount > 10.0f) { + CarbonRegion gas_region = oil_region; + gas_region.region_id = next_carbon_region_id++; + gas_region.type = CarbonType::NATURAL_GAS; + gas_region.carbon_mass = conversion_amount * NATURAL_GAS_RATIO; + gas_region.radius *= 1.2f; // Gas spreads more widely + + carbon_regions.push_back(gas_region); + } + + // Reduce original coal region + coal_region.carbon_mass -= conversion_amount; + coal_region.conversion_progress += CONVERSION_RATE_PER_CYCLE; + + // Add oil region + carbon_regions.push_back(oil_region); + + // Remove depleted coal regions + if (coal_region.carbon_mass < 1.0f) { + // Mark for removal + coal_region.carbon_mass = 0.0f; + } + } + } + } + } + + // Remove depleted regions + carbon_regions.erase( + std::remove_if(carbon_regions.begin(), carbon_regions.end(), + [](const CarbonRegion& region) { return region.carbon_mass < 1.0f; }), + carbon_regions.end() + ); +} + +bool isRegionUnderwater(const CarbonRegion& region) { + // Check if majority of region is below sea level + int underwater_tiles = 0; + int total_tiles = 0; + + int radius_int = static_cast(region.radius); + for (int dy = -radius_int; dy <= radius_int; ++dy) { + for (int dx = -radius_int; dx <= radius_int; ++dx) { + float distance = sqrt(dx*dx + dy*dy); + if (distance <= region.radius) { + int x = static_cast(region.center_x) + dx; + int y = static_cast(region.center_y) + dy; + + if (world_map->isValidCoordinate(x, y)) { + WorldTile tile = world_map->getTile(x, y); + total_tiles++; + + if (tile.getElevation() < current_sea_level - 50.0f) { // 50m underwater minimum + underwater_tiles++; + } + } + } + } + } + + return (static_cast(underwater_tiles) / total_tiles) > 0.6f; // 60% underwater +} +``` + +**Resource Application to Tiles**: +```cpp +void applyCarbonRegionsToTiles() { + for (const auto& region : carbon_regions) { + int radius_int = static_cast(region.radius); + + for (int dy = -radius_int; dy <= radius_int; ++dy) { + for (int dx = -radius_int; dx <= radius_int; ++dx) { + float distance = sqrt(dx*dx + dy*dy); + if (distance <= region.radius) { + int x = static_cast(region.center_x) + dx; + int y = static_cast(region.center_y) + dy; + + if (world_map->isValidCoordinate(x, y)) { + WorldTile tile = world_map->getTile(x, y); + float influence = 1.0f - (distance / region.radius); // Gradient from center + + // Apply resource based on carbon type + switch (region.type) { + case CarbonType::COAL: + addResourceToTile(tile, "coal", region.carbon_mass * influence); + break; + case CarbonType::OIL: + addResourceToTile(tile, "petroleum", region.carbon_mass * influence); + break; + case CarbonType::NATURAL_GAS: + addResourceToTile(tile, "natural_gas", region.carbon_mass * influence); + break; + } + } + } + } + } + } +} +``` + +**Expected Results**: +- **Dynamic forest evolution**: Forests continuously seed, expand, and get destroyed by geological events +- **Multiple forest generations**: Layers of carbon deposits from different geological periods +- **Realistic forest patterns**: Forests avoid active volcanic zones, extreme climates, and flood-prone areas +- **Coal deposit diversity**: Various ages and qualities of coal from different forest cycles +- **Oil formation**: Submerged forest areas naturally convert to petroleum over time +- **Geological storytelling**: Each coal seam represents a specific period of forest growth and burial + +### Phase 5: Pre-Faunal Stabilization (15 cycles × 10M years = 0.15 Ga) + +**Maturation-Only Phase - No New Formation**: +```cpp +void processStabilizationCycle(int cycle) { + // 1. HYDROCARBON MATURATION (no new formation) + continueHydrocarbonMaturation(); + + // 2. PETROLEUM MIGRATION TO TRAPS + migratePetroleumToGeologicalTraps(); + + // 3. FINAL EROSION PHASE + applyFinalErosion(); + + // 4. SOIL LAYER DEVELOPMENT + developSoilLayers(); + + // 5. CLIMATE STABILIZATION + stabilizeClimate(); + + // 6. GEOLOGICAL STRUCTURE FINALIZATION + finalizeGeologicalStructures(); +} +``` + +**Continued Hydrocarbon Maturation**: +```cpp +void continueHydrocarbonMaturation() { + const float REDUCED_CONVERSION_RATE = 0.03f; // Slower than Carboniferous (3% per cycle) + + for (auto& coal_region : carbon_regions) { + if (coal_region.type == CarbonType::COAL && isRegionUnderwater(coal_region)) { + // Continue coal→oil conversion at reduced rate + float conversion_amount = coal_region.carbon_mass * REDUCED_CONVERSION_RATE; + + if (conversion_amount > 0.5f) { // Lower threshold for final conversion + processCoalToOilConversion(coal_region, conversion_amount); + } + } + } + + // Oil→Gas maturation for old oil deposits + for (auto& oil_region : carbon_regions) { + if (oil_region.type == CarbonType::OIL) { + int oil_age = current_cycle - oil_region.formation_cycle; + + if (oil_age > 10 && oil_region.carbon_mass > 5.0f) { // Mature oil deposits + float gas_conversion = oil_region.carbon_mass * 0.02f; // 2% oil→gas + + createNaturalGasFromOil(oil_region, gas_conversion); + } + } + } +} +``` + +**Petroleum Migration to Geological Traps**: +```cpp +struct GeologicalTrap { + float center_x, center_y; + float capacity; // Maximum hydrocarbon storage + float current_fill; // Current hydrocarbon content + TrapType type; // ANTICLINE, FAULT, SALT_DOME, STRATIGRAPHIC + float formation_cycle; // When trap was formed +}; + +enum class TrapType { + ANTICLINE, // Upward fold in rock layers + FAULT_TRAP, // Hydrocarbon blocked by fault + SALT_DOME, // Hydrocarbon trapped around salt intrusion + STRATIGRAPHIC // Trapped between different rock types +}; + +void migratePetroleumToGeologicalTraps() { + // 1. Identify geological traps from tectonic history + std::vector traps = identifyGeologicalTraps(); + + // 2. Migrate oil and gas to nearest suitable traps + for (auto& hydrocarbon_region : carbon_regions) { + if (hydrocarbon_region.type == CarbonType::OIL || hydrocarbon_region.type == CarbonType::NATURAL_GAS) { + GeologicalTrap* nearest_trap = findNearestTrap(hydrocarbon_region, traps); + + if (nearest_trap && nearest_trap->current_fill < nearest_trap->capacity) { + float migration_amount = calculateMigrationAmount(hydrocarbon_region, *nearest_trap); + + // Move hydrocarbons to trap + nearest_trap->current_fill += migration_amount; + hydrocarbon_region.carbon_mass -= migration_amount; + + // Concentrate hydrocarbons in trap location + concentrateHydrocarbonsAtTrap(*nearest_trap, hydrocarbon_region.type, migration_amount); + } + } + } +} + +std::vector identifyGeologicalTraps() { + std::vector traps; + + // Find anticlines (upward folds) from tectonic compression + for (const auto& tectonic_region : tectonic_regions) { + if (tectonic_region.type == RegionType::CONTINENTAL) { + // Look for elevation highs within the region (potential anticlines) + auto high_points = findElevationHighsInRegion(tectonic_region); + + for (const auto& point : high_points) { + GeologicalTrap anticline = { + .center_x = point.x, + .center_y = point.y, + .capacity = calculateAnticlineCapacity(point), + .current_fill = 0.0f, + .type = TrapType::ANTICLINE, + .formation_cycle = tectonic_region.formation_cycle + }; + traps.push_back(anticline); + } + } + } + + // Find fault traps from tectonic collisions + for (const auto& collision_zone : historical_tectonic_collisions) { + GeologicalTrap fault_trap = { + .center_x = collision_zone.center_x, + .center_y = collision_zone.center_y, + .capacity = collision_zone.intensity * 50.0f, // Capacity based on collision intensity + .current_fill = 0.0f, + .type = TrapType::FAULT_TRAP, + .formation_cycle = collision_zone.formation_cycle + }; + traps.push_back(fault_trap); + } + + return traps; +} +``` + +**Final Erosion and Surface Formation**: +```cpp +void applyFinalErosion() { + const float FINAL_EROSION_RATE = 5.0f; // Reduced from active hydrological phase + + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + float elevation = tile.getElevation(); + + if (elevation > current_sea_level) { + // Expose coal seams through erosion + exposeCoalSeams(tile, x, y); + + // Carve final river valleys + carveRiverValleys(tile, x, y); + + // Form final coastal features + if (elevation < current_sea_level + 100.0f) { // Coastal zone + formCoastalFeatures(tile, x, y); + } + } + } + } +} + +void exposeCoalSeams(WorldTile& tile, int x, int y) { + // Check if there are coal deposits below current elevation + CarbonRegion* coal_region = findCoalRegionAt(x, y); + + if (coal_region && coal_region->type == CarbonType::COAL) { + float erosion_depth = calculateErosionDepth(tile); + + if (erosion_depth > 50.0f) { // Significant erosion + // Expose coal seam at surface + tile.setFlag(TileFlags::SURFACE_COAL, true); + + // Add surface coal resource + addResourceToTile(tile, "surface_coal", coal_region->carbon_mass * 0.1f); + } + } +} +``` + +**Soil Development System**: +```cpp +void developSoilLayers() { + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + + if (tile.getElevation() > current_sea_level + 5.0f) { // Above sea level + SoilType soil = determineSoilType(tile, x, y); + float soil_depth = calculateSoilDepth(tile, x, y); + + // Apply soil influence + RegionalInfluence soil_influence = { + .type = "soil_development", + .intensity = soil_depth / 10.0f, // Depth in meters / 10 + .properties = json{ + {"soil_type", getSoilTypeName(soil)}, + {"fertility", calculateSoilFertility(soil, tile)}, + {"drainage", calculateSoilDrainage(soil, tile)}, + {"ph_level", calculateSoilPH(soil, tile)} + } + }; + + applyRegionalInfluence(soil_influence, x, y, 1.0f); + } + } + } +} + +enum class SoilType { + CLAY, // Heavy, nutrient-rich, poor drainage + SAND, // Light, good drainage, low nutrients + LOAM, // Balanced, ideal for agriculture + PEAT, // Organic-rich, acidic, wetland areas + ROCKY, // Thin soil, mountainous areas + ALLUVIAL // River deposits, very fertile +}; + +SoilType determineSoilType(const WorldTile& tile, int x, int y) { + float elevation = tile.getElevation(); + float temperature = tile.getTemperature(); + float humidity = tile.getHumidity(); + + // River deltas and floodplains + if (tile.getFlag(TileFlags::HAS_RIVER) && elevation < current_sea_level + 50.0f) { + return SoilType::ALLUVIAL; + } + + // Wetland areas + if (humidity > 0.8f && elevation < current_sea_level + 20.0f) { + return SoilType::PEAT; + } + + // Mountainous areas + if (elevation > current_sea_level + 1000.0f) { + return SoilType::ROCKY; + } + + // Climate-based soil formation + if (temperature > 20.0f && humidity < 0.3f) { + return SoilType::SAND; // Arid regions + } else if (temperature < 10.0f && humidity > 0.6f) { + return SoilType::CLAY; // Cold, wet regions + } else { + return SoilType::LOAM; // Temperate regions + } +} +``` + +**Final Climate Stabilization**: +```cpp +void stabilizeClimate() { + // Reduce climate variability and volcanic activity + volcanic_activity_level *= 0.8f; // 20% reduction per cycle + climate_stability += 0.1f; // Increase stability + + // Establish final climate zones + for (int y = 0; y < map_height; ++y) { + for (int x = 0; x < map_width; ++x) { + WorldTile tile = world_map->getTile(x, y); + + ClimateZone zone = determineClimateZone(tile, x, y); + applyClimateZone(tile, zone); + } + } +} + +enum class ClimateZone { + ARCTIC, // < -10°C, low precipitation + SUBARCTIC, // -10 to 0°C, moderate precipitation + TEMPERATE, // 0 to 20°C, variable precipitation + SUBTROPICAL, // 20 to 30°C, high precipitation + TROPICAL, // > 30°C, very high precipitation + ARID, // Any temperature, very low precipitation + MEDITERRANEAN // Warm, dry summers, mild wet winters +}; +``` + +**Final Geological State**: +```cpp +struct FinalGeologicalState { + // TERRAIN + ✅ stable_continents; // Continental masses established + ✅ ocean_basins; // Deep ocean basins + ✅ mountain_ranges; // Various ages, realistic erosion + ✅ river_networks; // Mature drainage systems + ✅ coastal_features; // Beaches, cliffs, deltas, fjords + + // RESOURCES + ✅ coal_deposits; // Continental basins, exposed seams + ✅ oil_fields; // Sedimentary basins, geological traps + ✅ natural_gas; // Associated with oil, separate fields + ✅ metal_deposits; // From meteorite impacts and volcanism + + // CLIMATE + ✅ climate_zones; // Stable temperature/precipitation patterns + ✅ soil_types; // Mature soil development + ✅ seasonal_patterns; // Established weather cycles + + // READY FOR INDUSTRIAL GAMEPLAY + ✅ resource_accessibility; // Surface coal, shallow oil, metal ores + ✅ transportation_routes; // Rivers, coastal access, terrain variety + ✅ strategic_locations; // Resource clusters, defensive positions + ✅ environmental_challenges; // Climate zones, terrain obstacles +}; +``` + +**Expected Results**: +- **Complete geological maturity**: All major processes stabilized +- **Industrial-ready resources**: Coal seams exposed, oil in accessible traps +- **Realistic geography**: Mountain ranges, river valleys, coastal plains +- **Climate diversity**: Multiple biomes and environmental conditions +- **Strategic complexity**: Resource distribution creates interesting gameplay choices +- **Historical coherence**: Geological features tell the story of planetary formation + +## Phase 6: Climate Simulation and Biome Generation + +### Overview +After geological stabilization, run advanced climate simulation using mobile WindRegions and Inter-Tropical Convergence Zones (ITCZ) to establish realistic temperature, humidity, and wind patterns. Creates emergent weather patterns through wind region interactions rather than predefined climate zones. + +**Key Innovation**: Revolutionary climate simulation using **mobile wind regions** that spawn, evolve, and interact to create emergent weather patterns. Solves the "Sahara vs Congo" problem through **Inter-Tropical Convergence Zones (ITCZ)** and **planetary rotation bands** without complex 3D atmospheric physics. + +### Climate Simulation Architecture + +**Phase 6.1: Landmass Analysis and ITCZ Generation** + +Uses existing TectonicRegions from Phase 2: +```cpp +// Analyze continental masses from existing tectonic data +std::vector continents = groupTectonicRegions(); + +// Generate water masses by inverse analysis +std::vector oceans = detectOceanBasins(continents); + +// Place ITCZ zones on qualifying equatorial landmasses +for (auto& continent : continents) { + if (continent.latitude >= 0.45 && continent.latitude <= 0.55 && + continent.area > MIN_LANDMASS_SIZE) { + createITCZ(continent.center, sqrt(continent.area)); + } +} +``` + +**ITCZ Requirements:** +- **Latitude Band**: 45-55% of map height (equatorial) +- **Minimum Landmass**: 10,000+ tiles +- **Ocean Proximity**: Within 800km for moisture source +- **Continental Heating**: Large thermal mass for convection + +**Phase 6.2: WindRegion Spawning System** + +Mobile WindRegions spawn from ocean masses: +```json +"wind_spawn_system": { + "spawn_locations": "ocean_masses_only", + "spawn_frequency": "water_mass_size / 1000", + "initial_strength": "water_temperature * evaporation_factor", + "spawn_distribution": "random_within_water_region_biased_toward_center" +} +``` + +**WindRegion Mobile Entities:** +```json +"wind_region": { + "position": [x, y], + "wind_strength": 1.0, // Base intensity (decays over time) + "wetness": 0.0, // Moisture content (gained over ocean) + "velocity": [vx, vy], // Movement vector + "wind_tokens": 100, // Distributed to tiles + "decay_per_move": 0.02, // -2% strength per movement + "decay_per_tile": 0.01 // -1% strength per tile crossed +} +``` + +**Phase 6.3: Movement and Planetary Circulation** + +Planetary rotation bands based on real atmospheric data: +```json +"planetary_circulation": { + "polar_jet_north": { + "latitude_range": [0.10, 0.25], + "direction": "west_to_east", + "strength": 1.8 + }, + "equatorial_trades": { + "latitude_range": [0.40, 0.60], + "direction": "east_to_west", + "strength": 1.5 + }, + "polar_jet_south": { + "latitude_range": [0.75, 0.95], + "direction": "west_to_east", + "strength": 1.8 + } +} +``` + +**Movement Calculation:** +```cpp +Vector2 movement = + planetary_rotation_band * 0.6 + // 60% planetary circulation + equator_to_pole_bias * 0.2 + // 20% thermal circulation + terrain_deflection * 0.1 + // 10% topographic influence + random_variation * 0.1; // 10% chaos +``` + +**Phase 6.4: WindRegion Evolution and Interactions** + +Dynamic evolution with ITCZ gravitational effects: +```cpp +void updateWindRegion(WindRegion& region) { + // Gain moisture over water + if (currentTile.isOcean()) { + region.wetness += OCEAN_MOISTURE_GAIN; + } + + // Repulsion from other regions = acceleration + // NOTE: Not physical repulsion - proxy for spatial competition and turbulence + // Prevents region stacking while creating realistic dispersion patterns + // CRITIQUE POINT: May cause "force field" effect around ITCZ zones where regions + // oscillate/scatter instead of converging due to attraction vs repulsion conflict. + // Alternative approaches: density-based drift, no interaction, or collision division. + // TODO: Implement as configurable algorithm options for empirical testing. + float repulsion = calculateRepulsionForce(region, nearbyRegions); + region.wind_strength += repulsion * ACCELERATION_FACTOR; + + // Movement decay + region.wind_strength *= (1.0 - DECAY_PER_MOVE); + + // Die when too weak + if (region.wind_strength < MINIMUM_THRESHOLD) { + destroyRegion(region); + } +} +``` + +**ITCZ Gravitational Effects:** +```cpp +void applyITCZGravity(WindRegion& region) { + for (auto& itcz : active_itcz_zones) { + float distance = calculateDistance(region.position, itcz.center); + + if (distance < itcz.gravitational_range) { + // Attraction force (inverse square law) + // NOTE: "Gravitational" metaphor for influence strength, not literal physics + // Like saying someone has "gravitas" - clear semantic meaning for developers + float attraction = itcz.mass / (distance * distance); + Vector2 pull_direction = normalize(itcz.center - region.position); + + // Apply attraction + region.velocity += pull_direction * attraction; + + // Amplification effect as region approaches + float proximity = (itcz.range - distance) / itcz.range; + float amplification = 1.0 + (itcz.max_amplification * proximity); + + region.wind_strength *= amplification; + region.wetness *= amplification; + } + } +} +``` + +**Phase 6.5: Token Distribution and Climate Zone Formation** + +Climate zone classification using token accumulation: +```cpp +void distributeTokens(WindRegion& region) { + // Basic climate tokens for all regions + int wind_tokens = static_cast(region.wind_strength * 10); + int rain_tokens = static_cast(region.wetness * 10); + + WorldTile& tile = world_map.getTile(region.position); + tile.addTokens("wind", wind_tokens); + tile.addTokens("rain", rain_tokens); + + // Special climate zone tokens for extreme weather + if (isHighWindZone(region)) { + tile.addTokens("highWind", 1); // Hostile to forests + } + if (isFloodZone(region)) { + tile.addTokens("flood", 1); // Forces wetlands/marshes + } + if (isHurricaneZone(region)) { + tile.addTokens("hurricane", 1); // Specialized hurricane biome + } +} +``` + +### Climate Zone Effects on Biome Generation + +**Token-Based Biome Classification:** +```cpp +BiomeType classifyBiome(const WorldTile& tile) { + int total_rain = tile.getAccumulatedTokens("rain"); + int total_wind = tile.getAccumulatedTokens("wind"); + int highWind_tokens = tile.getAccumulatedTokens("highWind"); + int flood_tokens = tile.getAccumulatedTokens("flood"); + int hurricane_tokens = tile.getAccumulatedTokens("hurricane"); + + // Special climate zones override normal biome classification + if (hurricane_tokens > 0) { + return BiomeType::HURRICANE_ZONE; // Specialized storm-resistant vegetation + } + if (flood_tokens > FLOOD_THRESHOLD) { + return BiomeType::WETLANDS; // Forced marshes/swamps + } + if (highWind_tokens > STORM_THRESHOLD) { + // High wind prevents forest growth + if (total_rain > 300) { + return BiomeType::STORM_PRAIRIE; // Grasslands that can handle wind + } else { + return BiomeType::BADLANDS; // Sparse, wind-resistant vegetation + } + } + + // Normal biome classification using basic rain/wind tokens + if (total_rain > 500) { + return BiomeType::TROPICAL_RAINFOREST; + } else if (total_rain < 50) { + return BiomeType::HOT_DESERT; + } + // ... additional normal biome logic +} +``` + +**Climate Zone Characteristics:** +- **Hurricane Zones** → Storm-resistant palms, specialized coastal vegetation +- **Flood Zones** → Wetlands, marshes, swamp vegetation mandatory +- **High Wind Zones** → No forests allowed, prairie/badlands only +- **Normal Zones** → Standard biome classification by rain/temperature + +### Geographic Climate Patterns + +**Realistic Climate Formation Examples:** + +**Congo Basin (Rainforest):** +``` +1. Large African landmass → Strong ITCZ at equator +2. Atlantic wind regions spawn → Move east via trade winds +3. ITCZ aspiration → Convergence at Congo → Amplification ×3 +4. Super-humid storms → Massive rain token distribution +5. Result: Dense rainforest biome +``` + +**Sahara Desert:** +``` +1. Sahara latitude (25-35°N) → Outside ITCZ band +2. No convergence zone → Wind regions pass through +3. Continental distance → Low initial moisture +4. Subtropical high pressure → Air descends (simulated via movement patterns) +5. Result: Minimal rain tokens → Desert biome +``` + +### Configuration Integration + +**Climate Configuration (Hot-Reloadable):** +```json +{ + "climate_simulation": { + "wind_spawn_system": { + "base_spawn_rate": 0.1, + "ocean_size_factor": 0.001, + "max_concurrent_regions": 200 + }, + "planetary_circulation": { + "trade_winds_strength": 1.5, + "jet_stream_strength": 1.8, + "calm_zone_chaos": 0.3 + }, + "itcz_system": { + "latitude_band": [0.45, 0.55], + "min_landmass_size": 10000, + "max_ocean_distance": 800, + "amplification_max": 3.0 + }, + "storm_thresholds": { + "high_wind_min": 2.0, + "flood_wetness_min": 1.5, + "hurricane_wind_min": 2.5, + "hurricane_rain_min": 2.0 + } + } +} +``` + +**Note**: All parameters are hot-reloadable via the modular configuration system. Magic numbers are intentionally externalizable for real-time tuning during development - adjust values, save config, see immediate results without recompilation. + +### Performance Characteristics + +**Computational Complexity:** +- **Wind Regions**: O(n) for n active regions (~50-200 simultaneously) +- **ITCZ Calculations**: O(m) for m convergence zones (~5-15 globally) +- **Token Distribution**: O(tiles_visited) per region movement +- **Total per cycle**: O(n × average_movement_distance) + +**Memory Usage:** +- **WindRegion**: 32 bytes per region +- **ITCZ Zone**: 24 bytes per zone +- **Token accumulation**: Uses existing tile data structure +- **Estimated total**: <5MB for global weather simulation + +**Generation Time:** +- **Landmass analysis**: 1-2 seconds (one-time setup) +- **Per simulation cycle**: 10-50ms for 100-200 wind regions +- **Full climate stabilization**: 100-500 cycles → 10-30 seconds total + +## Phase 7: Budget Assignment and Natural Features + +### Random Budget Assignment (Normal Distribution) + +After climate and hydrology stabilization, assign budget scores to each tile using a bell curve distribution: + +```cpp +void assignBudgetScores(GMap& map) { + std::random_device rd; + std::mt19937 gen(rd()); + std::normal_distribution budget_dist(0.0f, 3.0f); // Mean=0, σ=3 + + for (int y = 0; y < map.getHeight(); y++) { + for (int x = 0; x < map.getWidth(); x++) { + float budget_value = budget_dist(gen); + int8_t budget = static_cast(std::clamp(budget_value, -10.0f, 10.0f)); + + WorldTile tile = map.getTile(x, y); + tile.setTargetBudgetScore(budget); + } + } +} +``` + +**Budget Distribution:** +- **68%** of tiles: budget score -3 to +3 +- **95%** of tiles: budget score -6 to +6 +- **Rare extremes**: -10/-9 and +9/+10 scores for unique locations + +### Natural Features Placement (Uniform Random) + +Place natural geological features randomly across the map with uniform distribution: + +```cpp +void placeNaturalFeatures(GMap& map, FeatureManager& feature_manager) { + std::random_device rd; + std::mt19937 gen(rd()); + std::uniform_real_distribution prob_dist(0.0f, 1.0f); + + const float FEATURE_CHANCE = 0.05f; // 5% of tiles get features + + for (int y = 0; y < map.getHeight(); y++) { + for (int x = 0; x < map.getWidth(); x++) { + if (prob_dist(gen) < FEATURE_CHANCE) { + // Natural features from gameData configuration + std::vector available_features = { + "cave", "hot_spring", "canyon", "plateau", + "marsh", "oasis", "geyser", "cliff", "gorge", + "natural_bridge", "sinkhole", "spring" + }; + + std::uniform_int_distribution feature_dist(0, available_features.size() - 1); + std::string feature = available_features[feature_dist(gen)]; + + feature_manager.placeFeature(feature, x, y); + } + } + } +} +``` + +## Phase 8: Resource Region Conversion + +### Regional Influence to Resource Features + +Convert abstract regional influences from geological simulation into concrete resource features on the map: + +```cpp +void convertRegionsToFeatures(GMap& map, FeatureManager& feature_manager) { + std::random_device rd; + std::mt19937 gen(rd()); + + for (auto& region : map.getRegionalInfluences()) { + // Semi-random feature count per region (1-8 features) + std::uniform_int_distribution feature_count_dist(1, 8); + int feature_count = feature_count_dist(gen); + + for (int i = 0; i < feature_count; i++) { + // Random position within region radius + auto [x, y] = getRandomPositionInRegion(region); + + // Region influence strength determines feature quality + float distance = getDistanceFromCenter(region, x, y); + float influence_strength = region.getInfluenceAt(distance); + + // Place appropriate features based on region type + placeRegionalFeature(region, x, y, influence_strength, feature_manager); + } + } +} + +void placeRegionalFeature(const RegionalInfluence& region, int x, int y, + float strength, FeatureManager& feature_manager) { + + if (region.getType() == "tectonic_plate") { + // Tectonic regions: metal deposits + if (strength > 0.8f) { + feature_manager.placeFeature("rich_iron_ore", x, y); + } else if (strength > 0.6f) { + feature_manager.placeFeature("copper_deposit", x, y); + } else if (strength > 0.4f) { + feature_manager.placeFeature("tin_deposit", x, y); + } else { + feature_manager.placeFeature("stone_quarry", x, y); + } + } + + else if (region.getType() == "carbon_region") { + // Carbon regions: coal and oil deposits + if (strength > 0.7f) { + feature_manager.placeFeature("rich_coal_seam", x, y); + } else if (strength > 0.5f) { + feature_manager.placeFeature("oil_well", x, y); + } else if (strength > 0.3f) { + feature_manager.placeFeature("coal_outcrop", x, y); + } else { + feature_manager.placeFeature("peat_bog", x, y); + } + } + + else if (region.getType() == "volcanic_zone") { + // Volcanic regions: geothermal and rare minerals + if (strength > 0.8f) { + feature_manager.placeFeature("geothermal_vent", x, y); + } else if (strength > 0.6f) { + feature_manager.placeFeature("sulfur_deposit", x, y); + } else if (strength > 0.4f) { + feature_manager.placeFeature("obsidian_field", x, y); + } else { + feature_manager.placeFeature("hot_spring", x, y); + } + } + + else if (region.getType() == "recent_meteorite_crater") { + // Recent meteorite impacts: rare metals and exotic materials + // NOTE: Different from Phase 1 planetary accretion meteorites + if (strength > 0.9f) { + feature_manager.placeFeature("platinum_deposit", x, y); + } else if (strength > 0.7f) { + feature_manager.placeFeature("rare_earth_deposit", x, y); + } else if (strength > 0.5f) { + feature_manager.placeFeature("gold_vein", x, y); + } else { + feature_manager.placeFeature("impact_glass", x, y); + } + } +} + +std::pair getRandomPositionInRegion(const RegionalInfluence& region) { + std::random_device rd; + std::mt19937 gen(rd()); + + // Random angle and distance within region radius + std::uniform_real_distribution angle_dist(0.0f, 2.0f * M_PI); + std::uniform_real_distribution radius_dist(0.0f, region.getRadius()); + + float angle = angle_dist(gen); + float distance = radius_dist(gen); + + int x = static_cast(region.getCenterX() + distance * cos(angle)); + int y = static_cast(region.getCenterY() + distance * sin(angle)); + + return {x, y}; +} +``` + +### Resource Feature Characteristics + +**Influence Strength Distribution:** +- **0.8-1.0**: Premium resources (rich deposits, rare materials) +- **0.6-0.8**: High-quality resources (standard industrial deposits) +- **0.4-0.6**: Medium-quality resources (adequate for basic industry) +- **0.2-0.4**: Low-quality resources (marginal extraction) +- **0.0-0.2**: Minimal resources (trace amounts only) + +**Regional Resource Mapping:** +- **Tectonic Regions**: Iron, copper, tin, stone → Industrial base materials +- **Carbon Regions**: Coal, oil, peat → Energy resources +- **Volcanic Zones**: Geothermal, sulfur, obsidian → Specialized materials +- **Recent Meteorite Craters**: Platinum, rare earths, gold → Advanced technology materials + +**Feature Distribution:** +- **1-8 features per region** (semi-random count) +- **Position**: Random within region radius +- **Quality**: Determined by distance from region center (closer = better) +- **Type**: Fixed by region type, quality by influence strength + +## Planetary Mass Conservation System + +### Core-Based Mass Conservation + +To maintain realistic mass conservation throughout geological simulation, the system uses a planetary core that absorbs eroded material and releases it through volcanic activity: + +```cpp +struct PlanetaryCore { + float core_mass; // Accumulated eroded material + float surface_mass; // Current surface terrain mass + float max_core_capacity; // Core saturation threshold + float volcanic_overflow_rate; // Rate of volcanic material expulsion (0.1-0.3) + float total_planetary_mass; // Constant after Phase 1 (meteorite bombardment) + + // Derived values + float core_pressure_ratio; // core_mass / max_core_capacity + int pending_volcanic_events; // Queued volcanic eruptions +}; + +void updateMassConservation(PlanetaryCore& core) { + // Validation: Total mass conservation + assert(core.core_mass + core.surface_mass == core.total_planetary_mass); + + // Core overflow triggers volcanic activity + if (core.core_mass > core.max_core_capacity) { + float overflow = core.core_mass - core.max_core_capacity; + float volcanic_expulsion = overflow * core.volcanic_overflow_rate; + + // Transfer mass from core to pending volcanic events + core.core_mass -= volcanic_expulsion; + + // Queue volcanic events proportional to overflow + int new_volcanic_events = static_cast(volcanic_expulsion / volcanic_event_mass_threshold); + core.pending_volcanic_events += new_volcanic_events; + + // Store remaining material for future volcanism + core.pending_volcanic_material += volcanic_expulsion; + } +} +``` + +### Erosion to Core Transfer + +All erosion processes transfer material to the planetary core rather than redistributing on surface: + +```cpp +void erodeToCore(WorldTile& tile, float erosion_amount, PlanetaryCore& core) { + // Remove material from surface + float current_elevation = tile.getElevation(); + tile.setElevation(current_elevation - erosion_amount); + + // Transfer to planetary core + core.core_mass += erosion_amount; + core.surface_mass -= erosion_amount; + + // Track erosion for geological history + tile.addFlag(TileFlags::ERODED_THIS_CYCLE); +} + +// Apply to all erosion processes +void riverErosion(WorldTile& tile, float water_flow, PlanetaryCore& core) { + if (water_flow > erosion_threshold) { + float erosion_amount = water_flow * erosion_rate_factor; + erodeToCore(tile, erosion_amount, core); + } +} + +void glacialErosion(WorldTile& tile, float ice_thickness, PlanetaryCore& core) { + float erosion_amount = ice_thickness * glacial_erosion_factor; + erodeToCore(tile, erosion_amount, core); +} +``` + +### Volcanic Overflow System + +Core overflow creates realistic volcanic activity that returns material to surface: + +```cpp +void processVolcanicOverflow(GMap& map, PlanetaryCore& core) { + while (core.pending_volcanic_events > 0) { + // Select volcanic location based on geological factors + auto [x, y] = selectVolcanicLocation(map); + + // Calculate eruption magnitude + float eruption_material = core.pending_volcanic_material / core.pending_volcanic_events; + + // Create volcanic eruption + createVolcanicEruption(map, x, y, eruption_material); + + // Update core state + core.surface_mass += eruption_material; + core.pending_volcanic_material -= eruption_material; + core.pending_volcanic_events--; + } +} + +std::pair selectVolcanicLocation(const GMap& map) { + // Prefer locations with: + // - Active tectonic boundaries + // - Existing volcanic history + // - High core pressure influence + + std::vector> candidate_locations; + + for (auto& tectonic_region : map.getTectonicRegions()) { + if (tectonic_region.getActivity() > volcanic_activity_threshold) { + // Add boundary tiles as candidates + auto boundary_tiles = tectonic_region.getBoundaryTiles(); + candidate_locations.insert(candidate_locations.end(), + boundary_tiles.begin(), boundary_tiles.end()); + } + } + + // Weight by distance from core pressure points + return selectWeightedRandom(candidate_locations); +} + +void createVolcanicEruption(GMap& map, int center_x, int center_y, float material_amount) { + // Deposit material in volcanic pattern + int eruption_radius = static_cast(sqrt(material_amount / volcanic_density_factor)); + + for (int dy = -eruption_radius; dy <= eruption_radius; dy++) { + for (int dx = -eruption_radius; dx <= eruption_radius; dx++) { + float distance = sqrt(dx*dx + dy*dy); + if (distance <= eruption_radius) { + int x = center_x + dx; + int y = center_y + dy; + + if (map.isValidCoordinate(x, y)) { + // Volcanic deposition decreases with distance + float deposition_factor = 1.0f - (distance / eruption_radius); + float local_deposition = material_amount * deposition_factor / (M_PI * eruption_radius * eruption_radius); + + WorldTile tile = map.getTile(x, y); + tile.setElevation(tile.getElevation() + local_deposition); + + // Mark as volcanic terrain + tile.setFlag(TileFlags::VOLCANIC_DEPOSIT, true); + } + } + } + } +} +``` + +### Mass Conservation Benefits + +**Perfect Conservation:** +- Total planetary mass remains constant after Phase 1 +- All eroded material is accounted for in core +- Volcanic activity returns material to surface +- No material created or destroyed + +**Realistic Geological Activity:** +- Core pressure drives continuing volcanism +- Volcanic activity decreases as core pressure reduces +- Natural equilibrium between erosion and volcanic deposition +- Geological activity persists throughout simulation + +**Simplified Implementation:** +- No complex sediment transport calculations +- No surface redistribution algorithms +- Single mass conservation equation +- Volcanic activity emerges naturally from core overflow + +**Gameplay Benefits:** +- Ongoing geological activity creates dynamic world +- Volcanic regions provide unique resource opportunities +- Erosion/volcanism balance creates varied topography +- Long-term geological processes affect industrial planning + +## Technical Architecture + +### WorldTileData Structure (32 bytes) +```cpp +struct WorldTileData { + // Terrain (11 bytes) - Always accessed, geological simulation ready + uint16_t terrain_type_id; // 65k terrain types + uint16_t biome_type_id; // Biome classification + uint16_t elevation; // -11km to +32km range + int16_t temperature; // -3276°C to +3276°C (0.1°C precision) + uint8_t humidity; // 0-100% (0.4% precision) + uint8_t wind_data; // 4 bits direction + 4 bits intensity + uint8_t water_level; // Accumulated water for river formation + + // Metadata (21 bytes) - Generation and gameplay + int8_t target_budget_score; // -10 to +10 + uint32_t regional_influence_id; // → Regional influence data + uint8_t influence_strength; // 0-255 + uint32_t tile_flags; // State flags + uint32_t feature_set_id; // → Feature collection + uint8_t padding2[7]; // Future expansion space +}; +``` + +### RegionalInfluence System +- **TectonicRegions**: Mobile circular regions with physics +- **CarbonRegions**: Carbon deposit tracking with tectonic attachment +- **VolcanicZones**: Created dynamically at tectonic collisions +- **SeaLevelInfluence**: Global parameter affecting all processes + +### FeatureManager Integration +- Simple helper interface for placing geological features +- Handles feature set creation and tile updates automatically +- Used by generation algorithms, doesn't do generation itself + +## Performance Characteristics + +### Memory Usage +- **1M tiles**: 32MB core tile data (increased from 24MB for hydrology) +- **Feature sets**: Sparse, shared between similar tiles +- **Geological regions**: ~10-50 regions vs millions of tiles +- **Climate wind regions**: ~50-200 mobile regions during simulation +- **Total estimated**: <125MB for complete planetary geology + advanced climate simulation + +### Computational Complexity +- **Tectonic simulation**: O(n²) for n regions (~25 regions = 625 operations) +- **Meteorite impacts**: O(k) for k impacts per wave +- **Sea level effects**: O(tiles) single pass +- **Carbon processes**: O(regions) sparse operations +- **Climate simulation**: O(n × movement_distance) for n wind regions (~50-200 regions) + +### Generation Time +- **Geological phases**: 10-20 seconds for complete 4.65 billion year simulation +- **Climate simulation**: 10-30 seconds for 100-500 climate cycles +- **Total estimated**: 20-50 seconds for complete world generation +- **Progressive**: Can display intermediate results during generation +- **Deterministic**: Same seed produces identical geology and climate + +## Implementation Priority + +### Phase 1: Core Architecture (1-2 weeks) +1. RegionalInfluence and RegionalInfluenceManager classes +2. TectonicRegion basic structure and physics +3. Simple meteorite impact system +4. Basic tile elevation/temperature updates + +### Phase 2: Full Geology (2-3 weeks) +1. Complete tectonic interaction system +2. Dynamic sea level integration +3. Carbon region formation and conversion +4. Volcanic zone creation + +### Phase 3: Polish (1-2 weeks) +1. Parameter tuning for realistic results +2. Performance optimization +3. Generation progress reporting +4. Validation and debugging tools + +## Scientific Accuracy vs Gameplay + +### Scientifically Inspired Elements +- ✅ Late Heavy Bombardment period +- ✅ Planetary differentiation (metals sink to core) +- ✅ Tectonic processes creating mountains/valleys +- ✅ Carboniferous period forest→coal formation +- ✅ Marine conditions for oil formation +- ✅ Sea level variations affecting geology +- ✅ ITCZ formation from continental heating +- ✅ Planetary circulation bands (trade winds, jet streams) +- ✅ Realistic climate differentiation (Congo vs Sahara) + +### Gameplay Simplifications +- ⚠️ Tectonic regions as circles (not realistic plate shapes) +- ⚠️ Fixed map size instead of planetary expansion +- ⚠️ Simplified core-mantle dynamics +- ⚠️ Compressed timescales for practical generation +- ⚠️ 2D wind simulation instead of 3D atmospheric layers +- ⚠️ Discrete token system instead of continuous climate fields +- ⚠️ Mobile wind regions as simplified weather systems + +### Result +**Plausible geology and climate** that creates **interesting gameplay** with **emergent weather patterns** without requiring PhD in atmospheric science to understand or debug. + +## Integration Points + +### WorldGenerationModule +- Orchestrates all geological phases +- Manages simulation state and progression +- Provides query interface for generated geology + +### FeatureManager +- Places geological features based on simulation results +- Handles feature set optimization and tile updates +- Simple interface for placement algorithms + +### RegionalInfluenceManager +- Core system managing all regional effects +- Handles tectonic regions, carbon regions, volcanic zones +- Provides influence application to tiles + +### Future Extensions +- **Dynamic climate**: Real-time weather systems during gameplay +- **Mineral resource modeling**: Detailed ore deposit formation +- **Advanced erosion**: River network evolution during gameplay +- **Geological time compression**: Speed up/slow down specific phases +- **Seasonal climate**: Monthly/yearly climate variations +- **Climate change**: Long-term climate evolution from industrial activity + +--- + +**Status**: System designed and ready for implementation. All major components specified with clear interfaces and realistic performance targets. Scientific accuracy balanced with implementation complexity for practical game development. \ No newline at end of file diff --git a/docs/02-systems/HYBRID_SIZE_SYSTEM.md b/docs/02-systems/HYBRID_SIZE_SYSTEM.md new file mode 100644 index 0000000..b1c29f3 --- /dev/null +++ b/docs/02-systems/HYBRID_SIZE_SYSTEM.md @@ -0,0 +1,46 @@ +# 🎯 **Hybrid Sizing System - Revolutionary UI Layout** + +## Overview + +The **Hybrid Sizing System** is a breakthrough UI layout approach that combines **responsive percentage targets** with **absolute pixel constraints** to achieve both flexible responsive design and guaranteed usability. + +## 💡 **Core Concept** + +Traditional UI systems force you to choose: +- **Percentages**: Responsive but can become unusable (too small/large) +- **Pixels**: Fixed size but not responsive + +**Hybrid System**: Target percentages, respect absolute constraints. + +## 📐 **Mathematical Formula** + +```cpp +float final_size = clamp(percentage_target, absolute_min, absolute_max); +``` + +Where: +- `percentage_target = (percentage / 100.0f) * parent_size` +- `absolute_min` = minimum usable size in pixels +- `absolute_max` = maximum reasonable size in pixels + +## 🎯 **Example in Action** + +### Configuration +```json +{ + "size": {"width": "20%"}, // Target 20% of parent + "min_size": {"width": 250}, // Never smaller than 250px + "max_size": {"width": 400} // Never larger than 400px +} +``` + +### Results Across Screen Sizes + +| Screen Width | 20% Target | Constraints | **Final Size** | Status | +|-------------|-----------|-------------|----------------|--------| +| 1000px | 200px | 250-400px | **250px** | ⚖️ Clamped to minimum | +| 1400px | 280px | 250-400px | **280px** | ✅ Percentage achieved | +| 1800px | 360px | 250-400px | **360px** | ✅ Percentage achieved | +| 2500px | 500px | 250-400px | **400px** | ⚖️ Clamped to maximum | + +This hybrid system represents a **fundamental advancement** in UI layout technology. diff --git a/docs/02-systems/SIZE_CONSTRAINTS_GUIDE.md b/docs/02-systems/SIZE_CONSTRAINTS_GUIDE.md new file mode 100644 index 0000000..627ec1c --- /dev/null +++ b/docs/02-systems/SIZE_CONSTRAINTS_GUIDE.md @@ -0,0 +1,166 @@ +# 📏 Size Constraints Guide + +## Overview + +Le système IUI supporte maintenant les **contraintes de taille en pixels** pour tous les types de fenêtres et docks. + +## ⚙️ Types de contraintes + +### **min_size** - Taille minimum +```json +{ + "min_size": {"width": 200, "height": 150} +} +``` +- Empêche l'utilisateur de rendre la fenêtre trop petite +- Garantit que le contenu reste utilisable +- **Obligatoire** pour les fenêtres critiques (console, alerts) + +### **max_size** - Taille maximum +```json +{ + "max_size": {"width": 800, "height": 600} +} +``` +- Empêche les fenêtres de dominer l'écran +- Maintient la cohérence de l'interface +- Utile pour les popups et dialogs + +### **size** - Taille initiale +```json +{ + "size": {"width": 400, "height": 300} +} +``` +- Taille au moment de la création +- Sera **clampée** entre min_size et max_size +- Si hors limites, ajustée automatiquement + +## 🏗️ Usage par type de fenêtre + +### **Docks** +```cpp +ui->createDock("sidebar", DockType::TABBED, DockPosition::LEFT, { + {"size", {{"width", 300}}}, + {"min_size", {{"width", 200}, {"height", 300}}}, + {"max_size", {{"width", 500}, {"height", 1000}}}, + {"resizable", true} +}); +``` + +### **Splits** +```cpp +ui->createSplit("main_split", Orientation::HORIZONTAL, { + {"min_panel_size", 80}, // Chaque panel min 80px + {"min_size", {{"width", 600}, {"height", 400}}}, // Split total min 600x400 + {"split_ratio", 0.6} // 60% / 40% +}); +``` + +### **Content Windows** +```cpp +ui->showData(DataType::ECONOMY, { + {"content", {...}}, + {"window", { + {"id", "economy_dash"}, + {"size", {{"width", 350}, {"height", 250}}}, + {"min_size", {{"width", 300}, {"height", 200}}}, // Lisibilité + {"max_size", {{"width", 600}, {"height", 400}}}, // Pas trop invasif + {"resizable", true} + }} +}); +``` + +### **Floating Windows** +```cpp +ui->showData(DataType::ALERTS, { + {"content", {...}}, + {"window", { + {"floating", true}, + {"size", {{"width", 400}, {"height", 200}}}, + {"min_size", {{"width", 320}, {"height", 150}}}, // Alert lisible + {"max_size", {{"width", 600}, {"height", 300}}}, // Pas trop grosse + {"closeable", true} + }} +}); +``` + +## 📋 Recommandations par usage + +### **Console/Log windows** +- **min_size**: `{"width": 400, "height": 100}` (au moins 3-4 lignes) +- **max_size**: `{"width": 2000, "height": 300}` (pas trop haute) + +### **Economy/Data tables** +- **min_size**: `{"width": 250, "height": 200}` (colonnes lisibles) +- **max_size**: `{"width": 500, "height": 600}` (pas trop large) + +### **Maps/Graphics** +- **min_size**: `{"width": 300, "height": 300}` (détails visibles) +- **max_size**: `{"width": 1200, "height": 1200}` (performance) + +### **Inventory grids** +- **min_size**: `{"width": 200, "height": 150}` (grid 2x2 minimum) +- **max_size**: `{"width": 400, "height": 500}` (pas trop de scroll) + +### **Settings/Dialogs** +- **min_size**: `{"width": 320, "height": 240}` (tous contrôles visibles) +- **max_size**: `{"width": 500, "height": 400}` (taille raisonnable) + +### **Alert popups** +- **min_size**: `{"width": 300, "height": 120}` (texte lisible) +- **max_size**: `{"width": 500, "height": 250}` (pas invasif) + +## 🔄 Comportement automatique + +### **Clamping** +Si `size` est hors des limites : +```cpp +// Taille demandée : 100x50 +// min_size : 200x150 +// max_size : 800x600 +// → Résultat : 200x150 (clampée au minimum) +``` + +### **Resize interactif** +- L'utilisateur ne peut **jamais** redimensionner en dessous de `min_size` +- L'utilisateur ne peut **jamais** redimensionner au-dessus de `max_size` +- Les **cursors de resize** changent quand les limites sont atteintes + +### **Split constraints** +```cpp +{ + "min_panel_size": 80, // Chaque panel minimum 80px + "split_ratio": 0.7 // Mais peut être ajusté si ça viole min_panel_size +} +``` + +## ⚡ Performance + +- **Enums** pour types communs = comparaisons int rapides +- **JSON** pour config flexible = parse une fois à la création +- **Pixel constraints** appliquées côté implémentation (ImGui, HTML, etc.) +- **Zero overhead** si pas de contraintes spécifiées + +## 🎯 Exemple complet + +```cpp +// Créer layout avec contraintes +ui->createDock("main_sidebar", DockType::TABBED, DockPosition::LEFT, { + {"min_size", {{"width", 250}, {"height", 400}}}, + {"max_size", {{"width", 500}, {"height", 1000}}} +}); + +// Ajouter contenu avec contraintes +ui->showData(DataType::ECONOMY, { + {"content", {{"prices", {...}}}}, + {"window", { + {"parent", "main_sidebar"}, + {"dock", "tab"}, + {"min_size", {{"width", 240}, {"height", 200}}}, + {"max_size", {{"width", 450}, {"height", 600}}} + }} +}); +``` + +**Résultat** : Interface qui reste **utilisable** à toutes les tailles ! 🚀 \ No newline at end of file diff --git a/docs/02-systems/economie-logistique.md b/docs/02-systems/economie-logistique.md new file mode 100644 index 0000000..869d5cf --- /dev/null +++ b/docs/02-systems/economie-logistique.md @@ -0,0 +1,459 @@ +# Économie et Logistique + +## Vue d'ensemble + +L'économie de Warfactory est un système dynamique multi-acteurs où companies et états interagissent sur des marchés segmentés, avec une logistique automatisée intelligente qui supporte les opérations militaires et industrielles. + +## Stratégies d'Inventaire + +### Niveaux de Stock et Comportements d'Achat +Les companies IA adaptent leur comportement commercial selon leurs niveaux de stock : + +**Desperate (<20% capacité)** : +- Achète à n'importe quel prix +- Accepte qualité inférieure +- Priorise livraison rapide sur coût +- Peut payer 2-3x prix marché + +**Normal (20-50% capacité)** : +- Comportement équilibré +- Prix marché standard accepté +- Trade-offs normaux qualité/prix/délai + +**Cautious (50-80% capacité)** : +- Sélectif sur prix +- Attend offres avantageuses +- Peut différer achats non-critiques +- Cherche optimisation coûts + +**Oversupplied (>80% capacité)** : +- Vente aggressive surplus +- Prix cassés pour libérer stockage +- Peut vendre sous coût production +- Cherche liquidation rapide + +### Impact Gameplay +- **Opportunités trading** : Acheter à oversupplied, vendre à desperate +- **Cycles économiques** : Alternance pénuries/surplus créent volatilité +- **Stratégie stockage** : Balance entre coûts inventory et opportunités manquées + +### Consolidation Volume Émergente +**Effet économique naturel** : Les constraints transport créent collaboration forcée entre companies + +**Mécanisme économique** : +- **Transport Cost Limits** : Buyers définissent seuils acceptables (ex: "transport max 15% valeur goods") +- **Example pratique** : Iron 10€/kg → Transport max 1.50€/kg acceptable +- **Ship 0.10€/kg** ✅ viable, **Truck 5.00€/kg** ❌ rejeté (trop cher) +- **Natural collaboration** : Consolidation ordres pour atteindre viabilité Ship transport + +**Strategic implications** : +- **Pas threshold hard-codé** : Émergence via pure rationalité économique +- **Collaboration competitive** : Concurrents forcés coopérer pour transport viable +- **Timing decisions** : Attendre consolidation (50x moins cher) vs urgence livraison +- **Market psychology** : Economic pressure crée coopération naturelle + +### Spécialisation Régionale Émergente +**Progression économique naturelle** : Extraction → Manufacturing → Trading → Consumer + +**Regional Economic Development Phases :** +1. **Coastal advantage phase** : Early transport cost benefits (Ship 0.10€/kg) +2. **Infrastructure investment phase** : Economic pressure drives development (ROI <15 ans) +3. **Economic equilibrium phase** : Costs equalize across regions via infrastructure +4. **Competitive specialization phase** : Regions find comparative advantages + +**Natural Geographic Specialization :** +- **Resource-based clustering** : Mining operations near natural deposits +- **Manufacturing optimization** : Production centers minimize transport costs +- **Trading hub emergence** : Infrastructure convergence creates commercial centers +- **Realistic urban development** : Economic forces drive settlement patterns + +**Market Forces driving specialization :** +- **Coastal rush** → **Land premiums** → **Congestion costs** → **Capacity bottlenecks** +- **Pure economic pressure** (no artificial forcing) +- **Infrastructure ROI** drives regional transformation +- **Regional competition** for transport access and advantages + +## Acteurs Économiques + +### Companies privées +- **Joueur** : Company initiale avec avantage technologique (Factorio-like) +- **Multinationales** : Thales, Dassault, Lockheed Martin, etc. +- **Concurrents IA** : Companies générées avec productions automatisées +- **Coûts opérationnels** : Workers + salaires pour companies IA vs électricité seule joueur + +### Système de Features Company +**Principe** : Chaque company IA a 2-4 features qui définissent ses capacités et spécialisations + +#### Types de Features +**Domaines de production** : +- **Metal** : Métallurgie, alliages, structures métalliques +- **Electronic** : Circuits, capteurs, processeurs, systèmes avancés +- **Tank** : Véhicules blindés, systèmes de combat terrestre +- **Plane** : Aéronautique, avionique, systèmes volants +- **Wood** : Foresterie, produits bois, dérivés organiques +- **Food** : Agro-alimentaire, bio-ressources +- **Engine** : Moteurs, propulsion, systèmes mécaniques +- **Cannon** : Armement direct, artillerie, systèmes balistiques +- **Missile** : Armement guidé, roquettes, systèmes de navigation + +**Modificateurs de qualité** : +- **Quality** : Production haut de gamme, précision, durabilité +- **Quantity** : Production de masse, efficacité volume +- **Speed** : Production rapide, délais courts +- **Cost** : Production économique, optimisation prix +- **Modularity** : Designs modulaires, adaptabilité, standardisation +- **Innovation** : R&D focus, breakthrough technologies, expérimentation + +**Autres propositions** : +- **Stealth** : Furtivité, signature réduite, camouflage +- **Repair** : Maintenance, reconstruction, durabilité terrain +- **Transport** : Logistique, mobilité, capacité transport +- **Communication** : Réseaux, coordination, guerre électronique + +#### Exemples de Companies +**Point 272 - "Metal, Plane, Quantity, Electronic"** : +- **Produit** : Mass metal aircraft with embedded electronics - Avions métalliques de masse avec électronique embarquée + +**Point 273 - Avantages** : Volume, complete integration, optimized costs - Excelle production grandes quantités systèmes intégrés où électronique et structures optimalement combinées durant production masse, avantages coûts via volume maintenant intégration sophistiquée + +**Point 274 - Faiblesses** : Perhaps less refinement than quality specialist - Peut manquer précision et raffinement des concurrents spécialisés Quality, produisant appareils capables mais pas cutting-edge en performance ou durabilité + +**Point 275 - "Tank, Quality"** : +- **Produit** : High-end tanks, precision assembly - Véhicules blindés premium avec ingénierie précision et caractéristiques performance supérieures commandant prix premium + +**Point 276 - Limites** : Must buy electronics on external markets - Manque capacités Electronic internes, forcé acheter composants électroniques fournisseurs externes, augmente coûts, crée dépendances supply chain, limite intégration systèmes électroniques avancés + +**Point 277 - Dépendances** : Complex supply chain for non-mastered components - Manque capacités internes force développer relations supply complexes pour composants hors expertise, créant complexité logistique, problèmes contrôle qualité potentiels, vulnérabilité disruption supply chain + +#### Dynamiques des Features + +**Influence sur recherche** : +- **Features → Research paths** : Capacités influencent fortement directions R&D +- **Synergies via tech** : "Metal + Tank" unlock recherches blindage spécialisées +- **Pas d'exclusions strictes** : Features coexistent, synergies via recherche + +**Évolution des Companies** : + +**Point 281 - Mortalité** : Company mortality: Companies can disappear (example: "Food + Tank" = fatal dispersion) - Companies avec combinaisons features mal synergiques ou échec compétitif peuvent disparaître du jeu, exemples extrêmes comme Food + Tank représentant dispersion stratégique fatale + +**Point 282 - Naissance** : Company birth: New companies according to contextual needs - Nouvelles companies émergent réponse gaps marché, opportunités technologiques, besoins régionaux, features initiales déterminées par conditions marché spécifiques créant demande nouvelles capacités + +**Point 283 - Changement features** : Feature changes: Possible randomly during financial decline - Companies subissant stress financier peuvent subir changements features aléatoires durant restructuration, pivot nouveaux marchés, perte capacités contraintes budget, créant évolution dynamique capacités + +**Point 284 - Acquisition** : Acquisition: Random events allow gaining new features - Companies peuvent gagner nouvelles features via événements acquisition, opportunités fusion, breakthroughs technologiques expandant capacités et changeant position marché potentiellement + +**Point 285 - Perte (overflow)** : Loss: Events if >4 features (overflow) - Companies accumulant >4 features via acquisitions/expansion font face événements overflow forçant perte features, représentant limitation réaliste companies ne peuvent maintenir capacités diverses illimitées simultanément + +#### Events Aléatoires + +**Types d'events** : +- **Guerres** : Dégradation/amélioration relations, génération companies militaires +- **Crises locales** : Peuvent déclencher crises globales en cascade +- **Breakthroughs technologiques** : Nouvelles capacités, disruption marché +- **Probabilités égales** : Company "Quality" n'a pas plus de chances que "Cost" + +**Impacts contextuels** : +- **Guerre → Tank companies** : Génération companies spécialisées combat +- **Blocus → Innovation locale** : Développement alternatives domestiques +- **Crisis → Consolidation** : Fusion/disparition companies faibles + +**Contexte Géographique** : +- **Génération locale** : Features selon contexte (guerre → companies Tank) +- **Build-up progressif** : Nouvelles companies commencent basiques, s'améliorent +- **Adaptation étatique** : État sans électronique → dev company électronique médiocre + +#### Capacité Économique des États + +**Limitation companies** : +- **Capacité par état** : Nombre companies selon économie nationale +- **Ressources partagées** : Grosses companies consomment capacité économique +- **Avantage émergents** : États faibles = innovation possible (pas de monopoles internes) + +**Mécaniques d'adaptation** : + +**Point 289 - Besoin critique** : Critical need: Lack of electronics → birth of Electronic company (poor quality) - Quand marchés manquent capacités essentielles comme électronique, nouvelles companies émergent pour combler gaps même si qualité initiale pauvre, représentant réponses marché désespérées à pénuries critiques + +- **Substitution** : Mieux que rien > dépendance externe totale +- **Prix explosion** : Pénurie → développement alternatifs locaux + +#### Dégradation Qualité et Adaptation + +**Composants inférieurs** : + +**Point 292 - Design constraints** : Local electronics = larger components on grid - Composants électroniques domestiques de companies nouvelles/inférieures nécessitent typiquement plus espace physique grilles design véhicules comparé alternatives avancées importées + +**Point 293 - Chaleur excessive** : Excessive heat: More overheating, additional radiators required - Composants électroniques locaux inférieurs génèrent typiquement plus chaleur perdue qu'alternatives avancées, nécessitant systèmes refroidissement et radiateurs additionnels consommant espace et poids véhicule + +- **Variations design** : Adaptation véhicules aux composants disponibles +- **Courbe apprentissage** : Amélioration progressive vers standards internationaux + +**Point 296 - Trade-offs** : Autonomy vs optimal performance - Marchés doivent équilibrer autonomie supply et sécurité contre performance optimale, alternatives domestiques fournissant indépendance au coût efficacité technique + +#### Position du Joueur + +**Liberté totale** : +- **Pas de features** : Joueur non-contraint par système company +- **Choix gameplay naturels** : Spécialisation émerge des décisions +- **Factorio advantage** : Flexibilité vs modèles figés IA +- **Concurrence efficacité** : "Tank, Quantity, Cost" = défi mais surmontable + +#### Récupération et Recyclage + +**Déconstruction produits** : +- **Composants recovery** : Démontage pour pièces détachées +- **Économie circulaire** : Réutilisation en cas de pénurie +- **Stratégie backup** : Alternative aux supply chains rompues + +## Système de Conception IA + +### Défis d'Implémentation + +**Problématique conception** : +- **IA utilise grille** : Même système conception que joueur +- **Complexité computationnelle** : Génération designs = coûteux +- **Performance temps réel** : Impossible si IA réfléchit comme humain + +### Solutions d'Implémentation + +**Distribution temporelle** : +- **1-2 designs par tick globalement** : Performance acceptable (total mondial, toutes companies confondues) +- **Milliers de ticks** : Designs émergent progressivement +- **Background invisible** : Processus conception non-visible joueur + +**Évolution vs Création** : +- **Modification designs existants** : T-72 → T-80 → T-90 (style russe) +- **Plus rapide et réaliste** : Companies IRL évoluent designs +- **Historical accuracy** : Progression technologique authentique + +**Système de Validation** : +- **Features comme filtres** : Tank sans arme = design invalide +- **Règles de base** : Guidelines pour IA (tank = châssis + moteur + arme) +- **Validation cohérence** : Features influencent acceptation designs + +**Probabilités vs Rigidité** : +- **"Innovation" = plus tentatives** : Pas timing fixe, plus d'essais +- **Réactivité réaliste** : Companies IRL prennent 6+ mois réagir +- **Market dynamics** : Joueur ne peut répondre à toutes demandes simultanément + +### Doctrines Culturelles Nationales + +**Système de Doctrine** : +- **Influences multiples** : Companies, généraux, tactiques et choix économiques +- **Transmission** : Nouvelles entités héritent tendances nationales +- **Probabilités ajustées** : Bonus/malus selon affinité culturelle + +#### Exemple : États-Unis +**Features dominantes** : "Quality", "Electronic", "Innovation" +- **Companies** : +60% chance Quality/Electronic, -40% chance Speed/Cost +- **Généraux** : Tactiques tech-intensive, support aérien, logistique lourde +- **Économie** : Préférence R&D, investissements long terme, high-tech + +#### Exemple : France +**Features dominantes** : "Speed", "Modularity", "Innovation" +- **Companies** : +50% chance Speed/Modularity, -30% chance Quantity +- **Généraux** : Doctrines flexibles, combined arms, mobilité +- **Économie** : Cycles courts, adaptabilité, export diversifié + +**Mécaniques d'Influence** : +- **Génération companies** : Probabilités pondérées par doctrine nationale +- **Formation généraux** : Schools nationales influencent styles command +- **Décisions étatiques** : Orientations économiques selon culture +- **Adaptation** : Companies étrangères s'adaptent progressivement à culture locale + +### Blueprints Culturels + +**Héritage par Company** : +- **Blueprints intégrés** : Chaque company hérite culture design + doctrine nationale +- **Examples** : + - Company russe "Tank, Quantity" : T-34 style (low profile, sloped armor) + - Company allemande "Tank, Quality" : Leopard style (modular, precision) + - Company américaine "Tank, Electronic" : Abrams style (high-tech, digital) + +**Identités technologiques** : +- **Thales** : Blueprints électronique française (intégration, miniaturisation) +- **Dassault** : Blueprints aéro français (Rafale DNA = agile, multirole) +- **Lockheed** : Blueprints US (stealth, high-tech, expensive) + +**Évolution culturelle** : +- **Regional influences** : Companies même région partagent styles + doctrine +- **Feature evolution** : "Quality" améliore précision blueprints existants +- **Acquisition heritage** : Racheter company = récupérer blueprints + culture +- **Doctrine inheritance** : Nouvelles companies adoptent doctrine nationale + +**Émergence** : +- **Nouvelles companies** : Héritent blueprints régionaux/culturels + doctrine +- **Innovation contextuelle** : "Tank, Innovation" japonaise → blueprints hyper-modulaires +- **Adaptation locale** : "Engine, Cost" chinoise → moteurs économiques volumineux +- **Cultural drift** : Companies étrangères développent hybrides doctrine/origine + +### États +- **Statut hybride** : États = companies spécialisées avec production propre +- **Capacités** : Production, commandes, restrictions commerciales +- **Politique** : Sanctions, embargos, accords commerciaux +- **Exemple** : État ukrainien produit + commande mais ne réquisitionne pas + +## Marchés Segmentés + +### Types de marchés +- **National** : Marché par pays (ex: marché ukrainien) +- **Company-specific** : Marchés privés entre companies +- **Blocs multinationaux** : UE, OTAN, etc. +- **Mondial** : Marché global ouvert + +### Restrictions d'accès +- **Doubles verrous** : Blocages possibles par companies ET états +- **Exemples** : + - France bloque ventes Thales → joueur + - Thales bloque directement → joueur + - Ukraine bloque importations → concurrent +- **Scope** : Matériel industriel, biens production, consommation (électricité, acier) + +## Système de Prix Dynamiques + +### Facteurs d'influence +- **Offre/Demande** : Mécaniques classiques d'économie de marché +- **Événements militaires** : Conflits modifient prix selon proximité/impact +- **Pénuries** : Prix fonction durée estimée résolution ("2 mois" vs "5 ans") +- **Production adaptative** : Ajustement selon signaux marché + +### Exemples concrets +- **Bataille massive** → pénurie composants blindage → prix x3 +- **Victoire ukrainienne** → confiance économique → investissements +- **Embargo russe** → rareté métaux spécifiques → alternatives recherchées + +## Système Logistique + +### Transport Multi-Modal +**Moyens disponibles** : +- **Camions** : Flexibles, tous terrains, capacité limitée +- **Trains** : Grande capacité, nécessite infrastructure rails +- **Avions cargo** : Rapides, coûteux en pétrole, capacité moyenne +- **Drones** : Livraison précise, capacité faible, autonomes +- **Navires** : Très grande capacité, lents, limités aux côtes/rivières + +**Caractéristiques** : +- **Poids max** : Limitation par véhicule +- **Volume** : Pour véhicules transportés (pas pour biens standards) +- **Coût indirect** : Consommation carburant (15 avions pour tables = inefficient) + +### Hiérarchie des Coûts de Transport (Indicatif) +**Note** : Ces valeurs sont purement indicatives pour donner une échelle relative + +**Transport Maritime** : ~0.10€/kg +- Volume massif (>1000 tonnes minimum) +- Lent mais ultra-économique +- Limité aux zones côtières/ports + +**Transport Ferroviaire** : ~0.50€/kg +- Grandes quantités +- Efficace longue distance +- Nécessite infrastructure rails + +**Transport Aérien** : ~2.00€/kg +- Rapide mais coûteux +- Idéal urgences/haute valeur +- Capacité limitée + +**Transport Routier** : ~5.00€/kg +- Dernier kilomètre +- Flexible mais cher +- Tous terrains + +**Impact Économique** : +- Localisation critique pour compétitivité +- Zones côtières = avantage massif (50x moins cher) +- Infrastructure détermine viabilité business models + +### Supply Chain Militaire + +**Architecture FOB** : +- **Forward Operating Bases** : Une ou plusieurs par armée +- **Stocks décentralisés** : Chaque FOB stocke équipements/munitions +- **Distribution autonome** : Armées gèrent propre logistique finale + +**Ravitaillement Combat** : +- **Temps réel possible** : Livraison pendant batailles +- **Trade-off tactique** : Unité ravitaillée + ravitailleur immobilisées +- **Durée** : Définie par design ravitailleur ET ravitaillé +- **Vulnérabilité** : Moment critique exploitable par ennemi + +### Infrastructure et Vulnérabilités + +**Attaques possibles** : +- **Convois** : Cibles mobiles attaquables +- **Infrastructure** : Destruction ponts, rails, dépôts +- **Pas d'espionnage** : Sabotage physique uniquement + +**Protection** : +- **Escortes** : Défense convois prioritaires +- **Redondance** : Routes alternatives préplanifiées +- **Réparation** : Reconstruction infrastructure critique + +## Ressources et Extraction + +### Système de Propriété +**Hiérarchie ownership** : +- **États** : Master ownership des ressources territoriales +- **Companies** : Droits d'exploitation accordés/achetés +- **Joueur** : Doit obtenir droits pour exploiter +- **Revente droits** : Possible si non-rentable + +**Future** : Système réquisition état en temps de guerre + +### Géopolitique des Ressources +**Ressources stratégiques** : +- **Titanium** : Aérospatial, blindages avancés +- **Lithium** : Batteries, électronique +- **Terres rares** : Processeurs, optiques avancées +- **Contrôle = Pouvoir** : Monopole ressource = leverage diplomatique + +## Mécaniques de Marché + +### Information et Trading +**Transparence** : +- **Information parfaite** : Prix publics connus de tous +- **Qualité négociateur** : Influence commerce inter-entités +- **Marché ouvert** : Système buy/sell orders (style hôtel des ventes) + +### Manipulation Économique +**Pénuries artificielles** : +- **Possible théoriquement** : Achat massif pour créer rareté +- **Limites pratiques** : Nécessite moyens immenses +- **Multi-marchés** : Difficile créer pénurie mondiale +- **Contre-mesures** : Marchés alternatifs, substituts + +### Dynamiques Prix +**Facteurs influençant** : +- **Proximité conflit** : Prix locaux augmentent près combats +- **Durée résolution** : "2 mois" vs "5 ans" = prix différents +- **Volume disponible** : Stocks mondiaux vs production +- **Routes commerciales** : Blocage routes = prix régionaux explosent + +## Économie de Guerre + +### Changement de Priorités Étatiques +**Principe** : États adaptent leurs commandes selon contexte +- **Temps de paix** : Nourriture, biens civils, infrastructure +- **Temps de guerre** : Réduction tables civiles, augmentation tanks/munitions +- **Companies compliance** : Tentative d'adaptation aux nouvelles commandes étatiques +- **Limites culturelles** : Company bois ne peut pas faire tanks instantanément + +### Système de Rationnement +**Déclenchement** : En cas de pénuries critiques +- **Priorités étatiques** : Garantie besoins essentiels (nourriture) +- **Malus production** : Effets négatifs sur économie générale +- **Stratégie militaire** : Attaque infrastructure alimentaire = guerre totale +- **Ciblage intelligent** : Détruire supply chains ennemies pour forcer rationnement + +### Finances et Crédit +**Système bancaire** : +- **Emprunts companies** : Financement expansion/reconversion +- **Taux variables** : Selon risque et contexte économique +- **Défauts possibles** : Faillites en cas de mauvaise gestion + +### Supply Chain Vulnerabilities +**Effet cascade** : +- **Single point of failure** : Usine critique détruite → paralysie secteur +- **Interdépendances** : Composants → sous-assemblages → produits finis +- **Substituts** : Recherche alternatives en cas de rupture +- **Stockages stratégiques** : Buffer contre disruptions temporaires \ No newline at end of file diff --git a/docs/02-systems/factory-architecture-post-player.md b/docs/02-systems/factory-architecture-post-player.md new file mode 100644 index 0000000..a42e1d1 --- /dev/null +++ b/docs/02-systems/factory-architecture-post-player.md @@ -0,0 +1,431 @@ +# Rapport : Architecture Factory Game Post-Intégration Joueur + +## 🏗️ Factory Engine & Optimisation de Performance + +### Leçons Factorio (Analyse des Devlogs) + +L'analyse des devlogs de Factorio révèle des optimisations cruciales pour les factory games : + +#### Transport Lines Revolution +- **Merger segments adjacents** : Fusionner les tapis roulants contigus en lignes logiques uniques +- **Gains de performance** : x50-100 amélioration via réduction complexité algorithmique +- **Principe** : Traiter une ligne de 100 segments comme 1 entité plutôt que 100 entités séparées + +#### Compression Caching Intelligent +- **Items "collés"** : Une fois optimisés, ils restent dans cet état +- **Cache des gaps** : Mémoriser les espaces vides pour optimisation O(1) +- **Principe** : Éviter recalculation constante d'états stables + +#### Bulk Inserters Strategy +- **Attendre main pleine** : Différer mouvement jusqu'à stack optimal +- **Garantir efficacité** : Maximiser items par transfert +- **Principe** : Batch operations vs individual transfers + +#### SIMD & Vectorization +- **Processing parallèle** : 8+ items simultanément avec AVX2 +- **Gains massifs** : Performance x4-8 sur opérations critiques +- **Complexité élevée** : Optimisation manuelle requise + +### Décision Architecture Performance + +**SIMD = Trop complexe pour Claude Code** + +**Analyse coût/bénéfice** : +- ✅ **Gains** : Performance x4-8 sur boucles critiques +- ❌ **Coûts** : Code complexe, debugging difficile, contexte Claude Code explosé + +**Solutions alternatives** : +- **Compiler auto-vectorization** : GCC/Clang optimisations automatiques +- **Abstraction layers** : Libraries tierces (Intel TBB, etc.) +- **GPU compute** : Déléguer calculs lourds au GPU +- **Privilégier simplicité** : Architecture maintenable vs optimisation prématurée + +## 🎯 Architecture Modulaire Factory + +### Règle d'Or de Distribution + +**Performance-Based Module Distribution** : + +``` +Performance CRITIQUE → Same Module (belt+inserter+factory) +Performance IMPORTANTE → Same Process (logic, UI) +Performance MOYENNE → Same Machine (audio, debug) +Performance INDIFF → Network (analytics, telemetry) +``` + +### ProductionModule = Monolithe Nécessaire + +**Décision architecturale clé** : Belt + Inserter + Factory DOIVENT cohabiter + +#### Justification Technique +- **Interactions frame-perfect** : 60fps timing critique +- **Interdépendances serrées** : Item transfer nécessite coordination exacte +- **ISocket overhead** : Communication inter-module trop lente (>1ms inacceptable) +- **Performance native** : Appels directs vs sérialisation JSON + +#### Trade-off Accepté +- **Modularité** : Sacrifiée pour ProductionModule +- **Performance** : Priorité absolue sur factory core +- **Claude Code** : Module plus gros (500-800 lignes) mais logique cohérente + +### Autres Modules Restent Séparés + +Les systèmes non-critiques maintiennent la modularité : + +#### PowerModule (Distribution Énergie) +- **Responsabilités** : Génération, distribution, stockage énergie +- **Performance** : Updates périodiques (10Hz acceptable) +- **Communication** : Via IIO avec ProductionModule + +#### LogicModule (Automation) +- **Responsabilités** : Circuits, combinators, automation intelligente +- **Performance** : Réactif mais pas frame-critical +- **Communication** : Signals vers ProductionModule + +#### LogisticModule (Transport Longue Distance) +- **Responsabilités** : Trains, robots, transport inter-bases +- **Performance** : Planification long-terme (1Hz acceptable) +- **Communication** : Coordination avec ProductionModule + +#### WarModule (Combat & Stratégie) +- **Responsabilités** : Combat, défense, stratégie militaire +- **Performance** : Décisions stratégiques (0.1Hz acceptable) +- **Communication** : Isolation complète avec ProductionModule + +## ⚔️ War Module Architecture + +### Isolation Gameplay Complète + +**Principe fondamental** : Zero interaction directe ProductionModule ↔ WarModule + +#### Séparation Stricte +- **Pas d'inserters vers turrets** : Logistique autonome pour war assets +- **Interface via LogisticModule** uniquement : Munitions, réparations transitent +- **Combat isolated** : War logic complètement indépendant de factory logic + +#### Avantages Architecture +- **Debugging isolé** : Bug war ≠ crash factory +- **Performance séparée** : War optimization n'impacte pas factory FPS +- **Development parallèle** : Claude Code sur war logic sans comprendre factory + +### War = Orchestrateur Tactique + +**Décomposition en sous-systèmes spécialisés** : + +#### TargetingModule +- **Responsabilité** : Acquisition et tracking cibles +- **Performance** : Real-time (60Hz) pour précision combat +- **Algorithmes** : Line of sight, range calculation, target prioritization + +#### MovementModule +- **Responsabilité** : Coordination et déplacement unités +- **Performance** : Smooth interpolation (30Hz) +- **Algorithmes** : Formation keeping, collision avoidance, unit coordination + +#### PathfindingModule +- **Responsabilité** : Calcul routes optimales +- **Performance** : Async computation (background threads) +- **Algorithmes** : A*, hierarchical pathfinding, flow fields + +#### TacticalModule +- **Responsabilité** : Stratégie de bataille et décisions +- **Performance** : Strategic thinking (1Hz) +- **Algorithmes** : Decision trees, strategy evaluation, resource allocation + +#### TacticalAnalyticsModule +- **Responsabilité** : Intelligence et prédictions +- **Performance** : Deep analysis (0.1Hz) +- **Algorithmes** : Pattern recognition, threat assessment, predictive modeling + +### Distribution Network Friendly + +**War = Décisions stratégiques** (échelle temps : secondes/minutes) +**Factory = Optimisation temps réel** (échelle temps : frames/millisecondes) + +#### Latency Tolerance +- **50-100ms acceptable** pour décisions tactiques +- **Network distribution possible** pour tous sous-modules war +- **Load balancing** : Spread war computation across servers + +#### Scalability Natural +- **Solo game** : War modules local +- **Multiplayer** : War modules distribués par faction +- **MMO** : War clusters par région géographique + +## 🏭 Composition Factory Engine + +### ProductionModule Complet + +**Composants intégrés pour performance optimale** : + +#### Production (Core Manufacturing) +- **Assemblers** : Recipe processing, input/output management +- **Mining** : Resource extraction, ore processing +- **Integration** : Direct memory access, zero-copy transfers + +#### Transport (Unified Movement System) +- **Belts** : Item transport, compression, line optimization +- **Underground** : Tunneling, space efficiency +- **Splitters** : Flow control, item routing +- **Pipes** : Fluid transport, pressure systems + +#### Logistics (Item Transfer) +- **Inserters** : Precise item movement, timing critical +- **Filters** : Item selection, routing logic +- **Stack optimization** : Bulk transfers, efficiency maximization + +#### Storage (Inventory Management) +- **Chests** : Static storage, capacity management +- **Buffers** : Flow smoothing, production decoupling +- **Inventaires** : Item tracking, slot management + +### Évolution Progressive Belts + +**Complexité croissante pour maintenir Claude Code compatibility** : + +#### Phase 1 : Mono-item Belts (Claude Code Friendly) +- **1 item type par belt** : Logique simple, 200 lignes code +- **No lane splitting** : Éviter complexité algorithmique +- **Direct transfer** : Item A → Item A uniquement + +#### Phase 2 : Multi-item Belts +- **Mixed items** : Multiple types sur même belt +- **Simple queuing** : FIFO sans optimisation +- **Claude Code** : 300 lignes, logique encore gérable + +#### Phase 3 : Dual-lane Belts +- **Left/right lanes** : Indépendance partielle +- **Lane preference** : Routing intelligent +- **Claude Code** : 400-500 lignes, limite complexity + +#### Phase 4 : Full Factorio Complexity (SIMD Optimized) +- **Advanced compression** : Gap elimination, chunk processing +- **Vector operations** : AVX2 parallel processing +- **Human Code** : Optimisation manuelle, SIMD intrinsics + +### Data Layout Future-Proof + +**Structure SOA (Structure of Arrays) dès le début** : + +```cpp +// SOA Layout pour SIMD readiness +struct BeltSystem { + std::vector positions_x; // [x0, x1, x2, x3, ...] + std::vector positions_y; // [y0, y1, y2, y3, ...] + std::vector item_types; // [t0, t1, t2, t3, ...] + std::vector speeds; // [s0, s1, s2, s3, ...] +}; + +// Future SIMD processing ready: +// __m256 pos_x = _mm256_load_ps(&positions_x[i]); +``` + +**Avantages** : +- **SIMD ready** : Pas de refactoring data layout futur +- **Cache efficient** : Memory access patterns optimaux +- **Claude Code compatible** : Simple vectors, pas de complex structs + +## 💰 Simulation Économique Complexe + +### Full Economic Simulation Vision + +**Objectif** : Victoria 3-level economic complexity dans factory game context + +#### PopulationModule (Demographics) +- **Classes démographiques** : Workers, Engineers, Managers avec besoins différentiés +- **Population growth** : Birth/death rates, migration patterns +- **Social mobility** : Education, promotion, class transitions + +#### MarketModule (Price Discovery) +- **Supply/demand dynamics** : Real-time price adjustment +- **Market makers** : AI traders, liquidity provision +- **Price volatility** : Speculation, market shocks, bubbles + +#### MoneyModule (Monetary System) +- **Currency flow** : Money creation, circulation, destruction +- **Banking system** : Loans, interest rates, credit +- **Inflation modeling** : Money supply effects, price indexes + +#### TradeModule (International Commerce) +- **Import/export** : International trade flows +- **Exchange rates** : Currency valuation, forex markets +- **Trade policies** : Tariffs, quotas, trade agreements + +#### PolicyModule (Government Intervention) +- **Fiscal policy** : Taxation, government spending +- **Monetary policy** : Interest rates, money supply control +- **Regulation** : Industry oversight, market intervention + +### Complexité Progressive + +**Start Simple → Scale Complex** : + +#### Phase 1 : Basic Economics +- **1 population class** : Generic workers +- **5 core goods** : Iron, copper, coal, steel, circuits +- **Simple supply/demand** : Linear price adjustment + +#### Phase 2 : Intermediate Economics +- **3 population classes** : Workers, engineers, managers +- **20 goods categories** : Expanded resource tree +- **Market dynamics** : Price volatility, speculation + +#### Phase 3 : Complex Economics +- **Full demographic model** : Age, education, skills +- **100+ goods** : Complete production chains +- **Advanced policies** : Government intervention, regulation + +#### Configuration-Driven Complexity +```json +{ + "economic_complexity": "intermediate", + "population_classes": 3, + "market_volatility": 0.15, + "government_intervention": true +} +``` + +### Emergent Behavior Objectif + +**Economic Events Cascade Through System** : + +#### Resource Discovery Chain +1. **New ore deposit found** → Increased supply +2. **Ore prices crash** → Mining companies struggle +3. **Workers migrate** → Regional population shift +4. **New markets emerge** → Economic boom in region + +#### War Economic Impact +1. **Military conflict** → Supply chain disruption +2. **Resource scarcity** → Price inflation +3. **War production** → Economic restructuring +4. **Post-war recession** → Market readjustment + +#### Technology Economic Impact +1. **Automation breakthrough** → Productivity gains +2. **Labor displacement** → Unemployment spike +3. **Wage pressure** → Social unrest +4. **Government intervention** → Economic policy changes + +#### Player Decision Ripples +- **Factory expansion** → Local job creation → Population growth +- **Resource hoarding** → Artificial scarcity → Price manipulation +- **Technology research** → Industry disruption → Economic transformation + +## 🔧 Architecture Finale Optimisée + +### Core Game (Local Performance) + +**Performance-critical systems remain local** : + +```cpp +ProductionModule { + // Monolithe nécessaire pour performance + Belt + Inserter + Factory + Storage + // 500-800 lignes, acceptable pour Claude Code + // Frame-perfect coordination, zero ISocket overhead +} + +LogicModule { + // Automation réactive + Circuits + Combinators + Smart Automation + // 200-300 lignes, pure logic, Claude Code friendly +} +``` + +### Distributed Services (Network Tolerant) + +**Strategic systems leverage network distribution** : + +```cpp +PowerModule { + // Updates périodiques (10Hz acceptable) + Generation + Distribution + Storage + // Network latency irrelevant for power planning +} + +LogisticModule { + // Planification long-terme (1Hz acceptable) + Trains + Robots + Inter-base Transport + // Route planning can handle 50-100ms latency +} + +WarModule { + // Stratégie militaire (0.1-1Hz acceptable) + Targeting + Movement + Pathfinding + Tactical + Analytics + // Strategic decisions tolerant to network delays +} + +EconomicModule { + // Simulation complexe (0.01-0.1Hz acceptable) + Population + Market + Money + Trade + Policy + // Economic modeling happens on longer timescales +} +``` + +### Benefits Architecture Finale + +#### Performance Optimization +- **Critical systems local** : Zero network latency impact +- **Strategic systems distributed** : Horizontal scaling possible +- **Natural separation** : Performance requirements dictate architecture + +#### Development Efficiency +- **Claude Code** : Travaille sur modules simples (200-500 lignes) +- **Human optimization** : Focus sur performance kernels critiques +- **Parallel development** : Teams work on different performance tiers + +#### Scaling Flexibility +- **Solo laptop** : All modules local pour development +- **Multiplayer server** : Critical local, strategic distributed +- **MMO factory game** : Full distribution avec même architecture + +#### Evolution Support +- **Progressive complexity** : Start simple, add sophistication +- **No architectural refactoring** : Module boundaries stable +- **Performance tuning** : Individual module optimization + +## 🎮 Gameplay Vision Unifiée + +**Factory Game avec Simulation Économique Complète** : + +### Gameplay Layers + +#### Production Layer (Real-time, Local) +- **Optimisation factory** : Belt throughput, inserter timing +- **Resource flow** : Efficient material processing +- **Performance critical** : 60fps responsive, frame-perfect + +#### Automation Layer (Reactive, Local) +- **Smart systems** : Circuits, combinators, adaptive logic +- **Responsive control** : React to production changes +- **Low latency** : Sub-second response times + +#### Strategic Layer (Planned, Distributed) +- **Military strategy** : Unit coordination, tactical planning +- **Long-term decisions** : Base expansion, technology research +- **Network tolerant** : Seconds to minutes decision cycles + +#### Economic Layer (Emergent, Distributed) +- **Market dynamics** : Supply/demand, price discovery +- **Complex simulation** : Population, policies, international trade +- **Deep computation** : Minutes to hours for complex economic modeling + +### Unified Experience + +**Chaque aspect du jeu optimisé selon ses contraintes naturelles** : + +- **Factory optimization** → Immediate feedback, tactical decisions +- **Economic strategy** → Long-term planning, strategic thinking +- **Military coordination** → Medium-term tactics, resource allocation +- **Automation intelligence** → Reactive adaptation, efficiency optimization + +**Résultat** : Factory game qui évolue naturellement vers simulation économique complexe sans sacrifier performance core gameplay. + +--- + +## Conclusion + +L'architecture post-intégration joueur révèle des trade-offs cruciaux entre modularité et performance. En acceptant un ProductionModule monolithique pour les systèmes critiques tout en maintenant la modularité pour les systèmes stratégiques, nous obtenons le meilleur des deux mondes : + +**Performance native** où nécessaire + **Modularité Claude Code** où possible = **Factory game AAA avec développement IA-optimized**. \ No newline at end of file diff --git a/docs/02-systems/gameplay-industriel.md b/docs/02-systems/gameplay-industriel.md new file mode 100644 index 0000000..ac37ecf --- /dev/null +++ b/docs/02-systems/gameplay-industriel.md @@ -0,0 +1,210 @@ +# Gameplay industriel + +## Progression des ressources + +### Ordre d'acquisition théorique + +**Ressources de base** : +- Bois → Coffre +- Pierre → Mur en pierre +- Scrap → Chaudière (alimentation vapeur dans un rayon de 1 case) + +**Machines de base** : +- Assembleur à vapeur +- Four + +**Chaîne de production** : +- Charbon de bois < bois +- Fer < minerais de fer / scrap + charbon de bois +- Engrenage < Fer +- Cuivre < minerais de cuivre + charbon de bois +- Bobine de cuivre < cuivre +- Sable < pierre +- Verre < sable +- Circuit électronique primitif < Bobine de cuivre + bois + verre + +## Gameloop par phases + +### Early +- Exploitation et production +- Scrap et bois +- Recherche +- Électricité et commerce + +### Mid +- Charbon et fer/cuivre/silice +- Acide sulfurique/nitrique +- Explosifs basiques/munitions +- Électronique +- Roquettes +- Assemblage et diplomatie +- Licences civiles +- Combat +- Radar + +### Mid late +- Pétrole et alu/titane/gold +- Plastique/explosifs avancés +- Circuits avancés +- Licences militaires +- Tourelles de défenses (AA, terrestre, gun) +- Missiles, C&C basique + +### Late game +- Nucléaire et platine/composite +- Processeurs + +## Philosophie Bac à Sable + +### Liberté d'Échelle Joueur +Warfactory est conçu comme un **bac à sable économique** où le joueur définit sa propre échelle d'opération selon ses préférences : + +**Spectrum complet possible** : +- **Artisan local** : Production tables, meubles, objets du quotidien +- **PME spécialisée** : Focus niche (électronique, composants spécifiques) +- **Industriel régional** : Usines moyennes, marchés nationaux +- **Géant multinational** : Concurrent direct Thales/Lockheed Martin, marchés globaux + +**Principe fondamental** : **Aucune progression forcée**. Le joueur peut rester petit artisan toute la partie s'il le souhaite, ou scale selon ses ambitions. + +### Principe Skip vs Optimize + +**Philosophie design core** : **"Tous les systèmes du jeu doivent pouvoir être skippés"** + +Le joueur choisit son niveau d'engagement selon ses préférences, compétences et temps disponible : + +**Spectrum d'engagement** : +- **Skip/Commodité** : Solutions automatisées, efficacité réduite mais accessibles +- **Partial engagement** : Hybride manuel/auto selon systèmes +- **Full optimization** : Contrôle manuel complet, efficacité maximale + +**Exemples d'application** : +- **Production** : Factory tout-en-un (médiocre) vs layouts Factorio optimisés +- **Design véhicules** : Templates basiques vs design manuel précis +- **Recherche** : Auto-tech vs chemins research focused +- **Commerce** : Auto-trade vs négociation manuelle +- **Militaire** : Templates doctrinaux vs tactiques custom + +**Avantages** : +- **Accessibilité** : Nouveaux joueurs peuvent progresser sans frustration +- **Depth préservée** : Experts peuvent optimiser chaque aspect +- **Rejouabilité** : Même joueur peut changer d'approche selon contexte +- **Respect du temps** : Adaptation aux contraintes personnelles + +### Flexibilité de Reconversion Industrielle + +#### Mécaniques de Switch Production +La difficulté de reconversion dépend de la **similarité des processus industriels** : + +**Reconversion Facile** (même ligne de production, ajustements mineurs) : +- **Tables fer → Blindages véhicules** : Même matériaux (acier), découpe/soudage similaire +- **Électronique civile → Électronique militaire** : Composants proches, normes différentes +- **Moteurs civils → Moteurs militaires** : Base commune, specifications renforcées + +**Reconversion Complexe** (nouvelles machines, formation, supply chain) : +- **Tables fer → Canons d'artillerie** : Précision usininage, alliages spéciaux, timing critique +- **Textile → Électronique** : Processus complètement différents +- **Alimentaire → Composites avancés** : Matériaux et techniques sans rapport + +**Reconversion Impossible** (reconstruction usine complète) : +- **Menuiserie → Production hydrogène** : Zéro overlap technologique +- **Pharmacie → Moteurs fusée** : Secteurs totalement disjoints + +#### Impact Gameplay +- **Diversification intelligente** : Choisir productions complémentaires +- **Flexibilité stratégique** : Réagir aux événements (guerre → switch civil→militaire) +- **Spécialisation vs Généralisme** : Trade-off entre efficacité et adaptabilité + +## Systèmes de production + +### Factory +- **Extraction** +- **Minage** +- **Style** : Factorio-like + +### Agriculture +- Concept à explorer + +### Production +- **Style** : Factorio-like +- **Assemblage** : Voir l'aspect conception avant + +#### Assemblage et qualité +L'idée est que puisque la conception se fait sur une grille, il faut placer les éléments sur une frame par des machines spéciales. Pour ce faire, il faut des bras spéciaux et placer dans un ordre correct. Si ce n'est pas respecté parfaitement, on observera une réduction dans la qualité du matériel. + +**Exemple de placement** : +- Cases marron : éléments déjà placés plus tôt +- Élément vert à placer : bonne façon par la droite (flèche rouge) +- Placement par la gauche (flèche rose) : possible mais réduction qualité +- Composant bleu : 2 façons correctes (droite et arrière, flèches jaunes) + +**Problème identifié** : +- "Chain des bras c'est pas ouf. Même si les machines changent de forme c'est clairement pas suffisant. Il faut plus. Visuellement c'est pauvre." + +### Logistique +- **Style** : Factorio-like +- **Évolution progressive des convoyeurs** (4 phases) + +#### Phases d'évolution Belt System +**Phase 1 - Mono** : +- Convoyeur basique unidirectionnel +- Une seule voie, items espacés uniformément +- Simplicité maximale pour MVP et early game + +**Phase 2 - Multi** : +- Multiple lanes par convoyeur (2-3 voies parallèles) +- Permet tri et routage plus sophistiqué +- Introduction filtres et priorités basiques + +**Phase 3 - Dual** : +- Convoyeurs bidirectionnels sur même tile +- Optimisation espace avec flux retour +- Complexité routing augmentée + +**Phase 4 - Full Factorio** : +- Système complet avec toute la complexité Factorio +- Splitters, underground belts, priorités avancées +- Balancers, circuits logiques, filtres complexes +- Optimisations performance requises (segment merging, compression) + +### Électricité +- **Principe** : Très simple pour gagner en performance par rapport à Factorio +- **Pas de calcul dynamique** des consommations en entrée +- **Pas de balance** de consommation du réseau + +## Systèmes de Production + +### Dual Production System +**Système production brut** : +- Transforme ressources primaires en matériaux (minerai fer → plaques fer) +- Production de masse, standardisée +- Focus sur volume et efficacité + +**Système d'assemblage** : +- Prend matériaux et les place dans lignes d'assemblage +- Création produits finis (plaques acier → armure tank) +- Focus sur qualité et précision + +### Flexibilité production (style Factorio) +**Reconfiguration selon complexité** : +- **Simple** : Tables → blindages bois (reconfiguration manufacturateurs, même layout) +- **Complexe** : Tables fer → canons tank (refaire usines complètes - matériaux, timing, titane) +- **Radical** : Tables → hydrogène (reconstruction totale usines) + +**Dépendance recettes** : Facilité changement selon similarité matériaux/process + +### Avantage compétitif joueur +**Joueur** : +- **Factorio-like** : Design optimisé, consommation électricité seule +- **Efficacité maximale** : Pas de workers, pas de salaires + +**IA Companies/États** : +- **Bâtiments simples** : Production sans design joueur +- **Coûts opérationnels** : Workers + salaires requis +- **Joueur peut accéder** : Mais moins efficace que ses propres designs + +### Commandes et autonomie +- **Pas de suggestions IA** : Joueur gère sa production seul +- **Commandes externes** : États/Companies peuvent commander au joueur +- **État ukrainien** : Company parmi d'autres (produit, commande, pas réquisition) + diff --git a/docs/02-systems/map-system.md b/docs/02-systems/map-system.md new file mode 100644 index 0000000..798e447 --- /dev/null +++ b/docs/02-systems/map-system.md @@ -0,0 +1,1001 @@ +# Map System + +## Vue d'ensemble + +Le système de carte de Warfactory utilise une architecture hybride combinant une **carte globale réelle éditable** avec des **cartes locales générées** pour optimiser performance et gameplay. + +## Architecture Multi-Niveaux + +### Zoom Discret - 2 Niveaux +**Large Map (Carte Globale)** : +- **Carte monde** : Scope planétaire complet +- **V1 développement** : Carte faite à la main pour tests +- **Éditable** : Modifications possibles selon besoins gameplay +- **Navigation longue distance** : Node-based system +- **Scope** : Pays, régions, logistique macro + +**Zoom Local (Tiles de Jeu)** : +- **Taille tiles** : 1m x 1m (précision Factorio) +- **Chunks locaux** : 64x64 tiles (64m x 64m) [proposition] +- **Cartes générées** : Créées à la demande par serveur +- **Style Factorio** : Placement précis usines, bras, tapis roulants +- **Persistent** : Gardées en mémoire une fois générées +- **Scope** : Construction détaillée, combat local + +## Système de Navigation + +### Navigation Longue Distance +**Transport Terrestre** : +- **Node routier** : Réseau routier principal +- **Node rail** : Infrastructure ferroviaire +- **Node maritime** : Ports et voies navigables + +**Transport Aérien** : +- **Point A to Point B** : Navigation directe sans contraintes nodes +- **Pas de réseau** : Vol libre dans espace aérien + +### Chunks Imbriqués +**Optimisation logarithmique** : +- **Hiérarchie chunks** : Structure imbriquée pour performance +- **Navigation intelligente** : Pathfinding optimisé +- **Streaming efficace** : Chargement sélectif selon zoom + +## Gameplay et Construction + +### Échelles de Construction +**Niveau Local (Style Factorio)** : +- **Bras (inserter)** : Taille = taille joueur +- **Usines joueur** : 2x2, 3x3, 4x4, parfois plus grandes +- **Usines IA/personnel** : 40x30, 10x10, 15x30 (grandes installations) +- **Infrastructure** : Tapis roulants, réseaux électriques + +**Niveau Global** : +- **Placement macro** : Positionnement bases, régions industrielles +- **Infrastructure** : Routes, rails, ports +- **Effets cascade** : Modifications locales → impact global + +## Combat et Intégration + +### Combat Local sur Vraie Map +**Principe** : +- **Pas d'instances** : Combat sur cartes locales réelles +- **Continuité** : Même terrain que construction +- **Persistance** : Dégâts restent après combat + +**Intégration Logistique** : +- **Routes visualisées** : Infrastructure visible sur map +- **Supply lines** : Convois suivent réseau routier/rail +- **Vulnérabilités** : Infrastructure attaquable + +## Streaming et Performance + +### Système de Chargement +**Client-Side** : +- **Streaming intelligent** : Charge zone selon zoom/position +- **Unload automatique** : Libère mémoire zones non-visitées +- **Performance optimale** : Affiche uniquement écran visible + +**Multi-joueur** : +- **Synchronisation serveur** : Redistribue changements aux joueurs en zone +- **Pas de conflit** : Système chunk résout collisions + +### Transitions de Vue +**Zoom automatique** : +- **Seuil automatique** : Switch auto global→local selon niveau zoom +- **Boutons directs** : "Zoom on player" pour accès rapide +- **Transition fluide** : Passage seamless entre niveaux + +**Isolation joueurs** : +- **Pas de notifications** : Connexion/déconnexion autres joueurs invisible +- **Pas de chat** : Communication uniquement via système messages (futur) +- **Isolation totale** : 10 joueurs sur pays différents peuvent s'ignorer complètement + +### Optimisation Visuelle +**Rendu Local** : +- **Joueur voit** : Sa tile + tiles adjacentes +- **Caméras optionnelles** : Accès distant aux usines du joueur +- **Performance** : Ultra-simple, affichage écran uniquement + +## Fog of War et Reconnaissance + +### Système de Mémoire +**FOW par Chunks** : +- **Full Black** : Zones jamais visitées +- **Mémoire persistante** : Client garde info zones explorées +- **Granularité** : Par chunk, pas de micro-FOW + +### Intel Gathering Progressif +**Qualité reconnaissance** : +- **Satellite bas** : "Bâtiments ukrainiens en Ukraine" +- **Satellite high-end** : "Usines tanks Company X spécifique" +- **Progression détail** : Bâtiment → Usine → Usine armement → Usine armement Company X + +### Persistance Intelligence +**Mémoire par Actor** : +- **Sauvegarde info** : État/Company garde intel collecté +- **Expiration possible** : Info peut devenir obsolète +- **Partage conditionnel** : Selon alliances/accords + +## Map Éditable et Modifications + +### Carte Globale Réelle +**Base authentique** : +- **Géographie réelle** : Ukraine, Europe, monde selon scope +- **Modifiable** : Adaptations pour gameplay/équilibrage +- **Infrastructure réelle** : Routes, villes, ports existants + +### Répercussions Croisées +**Local → Global** : +- **Destruction infrastructure** : Pont local → route globale coupée +- **Constructions majeures** : Nouvelle usine → impact économique régional + +**Global → Local** : +- **Artillerie longue portée** : Dégâts route globale → terrain local +- **Événements macro** : Bombe nucléaire → dégradation locale généralisée + +## Structures de Données Techniques + +### Architecture Chunks Optimisée + +**Tile Structure Principal (Terrain)** : +```cpp +struct Tile { + uint16_t terrain_type; // 2 bytes (65k types terrain possibles) + uint8_t elevation; // 1 byte (0-255 hauteur) + uint16_t building_id; // 2 bytes (ref vers building) + uint16_t flags; // 2 bytes (passable, destructible, etc.) + uint8_t padding; // 1 byte (alignment mémoire) +}; // = 8 bytes par tile +``` + +**Chunk Principal 64x64** : +- **Taille** : 4096 tiles × 8 bytes = 32KB par chunk +- **Usage** : Terrain, navigation, construction, combat local +- **Fréquence** : Chargé souvent, dense + +**Combat Multi-Chunks** : +- **Batailles étendues** : Combat s'étend naturellement sur dizaines/centaines de chunks +- **Frontlines persistantes** : Guerre dure 1 an dans le monde (ex: base Bakhmut) +- **Capacité système** : "Milliers d'unités" = réparties sur grande zone géographique +- **Streaming intelligent** : Charge chunks actifs selon position unités/player + +**Système Ressources par Patches (Factorio-like)** : +```cpp +// Patches alignés sur grille tiles, mais pas forcément sur chunks +struct ResourcePatch { + uint16_t resourceId; // Fer, cuivre, pétrole, uranium, etc. + uint64_t original_quantity; // Quantité initiale (future-proof) + uint64_t remaining_quantity; // Ce qui reste actuellement + uint8_t base_richness; // Richesse de base (items/sec/drill) + set tiles; // Grid de tiles occupées (ex: L-shape sur grille) + uint32_t active_drills; // Nombre de drills qui minent + BoundingBox bounds; // Zone couverte par le patch + + float getCurrentExtractionRate() { + if (remaining_quantity == 0) { + return 0.0f; // STOP NET - patch épuisé + } + + double depletion_ratio = (double)remaining_quantity / original_quantity; + // Formule diminishing returns : rate = base * (1 - (1-depletion)/2) + float efficiency = 1.0f - (1.0f - depletion_ratio) / 2.0f; + return base_richness * efficiency; + } + + float getTotalOutput() { + return getCurrentExtractionRate() * active_drills; + } + + bool isExhausted() { + return remaining_quantity == 0; + } +}; + +struct MiningDrill { + Point2D position; + uint8_t coverage_area; // 1-25 tiles selon tech + ResourcePatch* target_patch; // Référence au patch miné + + float getOutput() { + if (!target_patch || target_patch->isExhausted()) { + return 0.0f; // Drill inutile si patch épuisé + } + return target_patch->getCurrentExtractionRate(); + } +}; +``` + +**Mécaniques d'Extraction** : +- **Partage équitable** : N drills = N × extraction_rate du patch +- **Diminishing returns** : Plus le patch s'épuise, moins il est efficace +- **Arrêt brutal** : 0% restant = 0 extraction (pas de résiduel) +- **Exemple** : Patch 50% épuisé = 75% d'efficacité par drill + +**Exemples de Capacité** : +- **Patch fer standard** : 10 millions d'unités +- **Gisement pétrole** : 1 milliard d'unités (quasi-infini) +- **Mine uranium** : 100 millions d'unités (extraction très lente) + +**Avantages Architecture** : +- **Séparation claire** : Terrain vs ressources = systèmes indépendants +- **Performance** : Terrain chargé en continu, ressources à la demande +- **Extensibilité** : 65k terrain types = variantes urbain/rural/industriel +- **Mémoire optimisée** : Pas de ressources stockées dans chaque tile +- **Alignment CPU** : Padding assure performance mémoire + +### Metadata Chunks +```cpp +struct ChunkMeta { + int32_t chunk_x, chunk_y; // Position globale + uint32_t generation_seed; // Pour reproduction terrain + bool is_dirty; // Modifié depuis last save + timestamp last_access; // Pour LRU unloading + uint16_t active_buildings; // Compteur optimisation + vector; // Bâtiments multi-tiles +}; // ~1-5KB selon buildings présents +``` + +**Total Footprint par Chunk** : +- Terrain : 32KB (toujours chargé) +- Ressources : 0-16KB (selon density, sparse) +- Metadata : 1-5KB (selon buildings) +- **Total** : 33-53KB par chunk = très raisonnable + +## Génération et Persistance + +### Cartes Locales +**Génération à la demande** : +- **Serveur génère** : Selon besoins joueur/combat +- **Persistance** : Sauvegarde une fois créée avec seed +- **Reproduction** : Même seed = même terrain généré + +**Seed System** : +```cpp +// Génération déterministe par chunk +uint32_t chunk_seed = global_seed ^ (chunk_x << 16) ^ chunk_y; +// Assure reproduction exacte du terrain +``` + +**Déclencheurs génération** : +- **Joueur visite** : Zone explorée première fois +- **Combat déclaré** : Battlefield généré automatiquement +- **Construction** : Développement industriel local + +## Architecture Modulaire de Génération Procédurale + +### Principe de Modularité +**Design pour IA** : Chaque module = interface simple + logic testable + règles claires + +```cpp +class IGenerator { +public: + virtual void generate(ChunkData& chunk, GenerationContext& context) = 0; + virtual void validate(const ChunkData& chunk) = 0; + virtual bool canGenerate(const GenerationContext& context) = 0; +}; +``` + +### Modules de Génération + +#### TerrainGenerator +```cpp +class TerrainGenerator : public IGenerator { +private: + PerlinNoiseGenerator elevation; + PerlinNoiseGenerator moisture; + BiomeClassifier biomes; + +public: + void generate(ChunkData& chunk, GenerationContext& context) override { + // Génère elevation, biomes, terrain de base + // Input: chunk position, global seed + // Output: terrain_type pour chaque tile + } +}; +``` + +#### RoadNetworkGenerator +```cpp +class RoadNetworkGenerator : public IGenerator { +private: + DelaunayTriangulation connectivity; + MinimumSpanningTree optimizer; + +public: + void generate(ChunkData& chunk, GenerationContext& context) override { + // Génère réseau routier cohérent + // Input: terrain, points d'intérêt, chunks voisins + // Output: routes principales + secondaires + } +}; +``` + +#### BuildingLayoutGenerator +```cpp +class BuildingLayoutGenerator : public IGenerator { +private: + BSPTreePartitioner space_divider; + BuildingTemplateManager templates; + ZoningCalculator land_use; + +public: + void generate(ChunkData& chunk, GenerationContext& context) override { + // Place bâtiments selon zoning et templates + // Input: terrain, routes, zone type (urbain/rural/industriel) + // Output: bâtiments positionnés avec types + } +}; +``` + +#### DestructionSystem +```cpp +class DestructionSystem : public IGenerator { +private: + DamagePatternLibrary patterns; + HistoricalEventProcessor events; + +public: + void generate(ChunkData& chunk, GenerationContext& context) override { + // Applique destruction selon contexte historique + // Input: bâtiments, événements historiques (guerra, bombardements) + // Output: ruines, cratères, infrastructures endommagées + } +}; +``` + +### Growth Engine Modulaire + +#### PopulationGrowthCalculator +```cpp +class PopulationGrowthCalculator { +private: + DemographicModel demographics; + EconomicFactors economy; + +public: + float calculateGrowthRate(const RegionData& region, float time_delta) { + // Calcule croissance population selon facteurs + // Input: population actuelle, économie, sécurité + // Output: taux de croissance (peut être négatif) + } +}; +``` + +#### LandValueCalculator +```cpp +class LandValueCalculator { +private: + ProximityAnalyzer proximity; + InfrastructureEvaluator infrastructure; + SafetyAssessment security; + +public: + float calculateValue(const TileCoordinate& tile, const RegionContext& context) { + // Évalue valeur foncière d'une tile + // Input: position, infrastructure proche, sécurité + // Output: valeur relative (0.0-1.0) + } +}; +``` + +#### DemandCalculator +```cpp +class DemandCalculator { +private: + ResidentialDemand residential; + CommercialDemand commercial; + IndustrialDemand industrial; + +public: + DemandProfile calculateDemand(const RegionData& region) { + // Calcule besoins en construction par type + // Input: population, économie, infrastructure existante + // Output: demande résidentiel/commercial/industriel + } +}; +``` + +#### ExpansionSiteFinder +```cpp +class ExpansionSiteFinder { +private: + SuitabilityAnalyzer suitability; + ConstraintChecker constraints; + +public: + vector findSites(const DemandProfile& demand, const RegionData& region) { + // Trouve emplacements optimaux pour expansion + // Input: demande calculée, terrain disponible + // Output: sites classés par priorité + } +}; +``` + +#### DevelopmentExecutor +```cpp +class DevelopmentExecutor { +private: + ConstructionPlanner planner; + ResourceRequirementCalculator resources; + +public: + bool executeDevelopment(const ExpansionSite& site, const DevelopmentPlan& plan) { + // Exécute construction selon plan et ressources + // Input: site choisi, plan de développement + // Output: succès/échec + modifications terrain + } +}; +``` + +### Pipeline de Génération + +```cpp +class ChunkGenerationPipeline { +private: + vector> generators; + +public: + void generateChunk(ChunkData& chunk, const GenerationContext& context) { + // Pipeline séquentiel : + // 1. TerrainGenerator (base) + // 2. RoadNetworkGenerator (infrastructure) + // 3. BuildingLayoutGenerator (structures) + // 4. DestructionSystem (histoire) + + for (auto& generator : generators) { + if (generator->canGenerate(context)) { + generator->generate(chunk, context); + generator->validate(chunk); + } + } + } +}; +``` + +### Avantages Architecture + +**Pour l'IA** : +- **Interfaces claires** : Chaque module a input/output définis +- **Testabilité** : Chaque générateur testable indépendamment +- **Évolution** : Nouveaux générateurs ajoutables facilement +- **Debug** : Isolation des problèmes par module + +**Pour le Gameplay** : +- **Cohérence** : Règles de génération explicites +- **Flexibilité** : Modules activables selon contexte +- **Performance** : Génération à la demande par module +- **Continuité** : Coordination entre chunks via GenerationContext + +### Contexte de Génération + +```cpp +struct GenerationContext { + uint32_t global_seed; + ChunkCoordinate position; + RegionType region_type; // Urbain, rural, industriel + HistoricalEvents events; // Guerres, bombardements passés + NeighborChunkData neighbors; // Chunks déjà générés + CompanyInfluences companies; // Companies dominantes région + StatePolicy policies; // Politiques état local + GeographicalBias bias; // Modificateurs région (+montagne, -marécage) + FixedZones fixed_zones; // Zones prédéfinies (Tchernobyl, etc.) +}; +``` + +## Système de Génération Procédurale par Points avec Tendances Régionales + +### Vision Globale + +#### Principe Fondamental +Chaque tile de la carte mondiale est générée selon un **budget de points** qui détermine ce qui s'y trouve. Les éléments ont des valeurs positives (ressources, opportunités) ou négatives (dangers, contraintes). La génération combine des éléments pour atteindre exactement le score cible, créant automatiquement un équilibre risque/récompense. + +#### Innovation Clé : Tendances Régionales +Au-dessus du système de points, des **zones géographiques** influencent la probabilité d'apparition de certains éléments, créant des régions spécialisées réalistes : bassins pétroliers, zones minières historiques, régions forestières, zones post-industrielles. + +### Anatomie d'une Tile + +#### Budget de Points +Chaque tile reçoit un **score cible** (-10 à +10) qui détermine son "potentiel" : +- **Scores positifs** : Zones riches mais souvent avec contraintes +- **Score zéro** : Terrain équilibré ou neutre +- **Scores négatifs** : Zones dangereuses ou difficiles + +#### Philosophie de Design +- **Équilibre automatique** : Richesse compensée par contraintes +- **Variété émergente** : Mêmes éléments, contextes différents +- **Cohérence géographique** : Éléments appropriés aux régions via tendances régionales +- **Découverte progressive** : Certains éléments cachés nécessitent exploration +- **Spécialisation territoriale** : Régions développent identités distinctes + +## Typologie des Éléments + +### Ressources Naturelles (Positives) +**Minerais de Base** +- Fer = +1 point +- Cuivre = +1 point +- Charbon = +1 point +- Plomb = +1 point + +**Minerais Précieux** +- Bauxite = +2 points +- Étain = +2 points +- Titane = +3 points +- Magnésium = +2 points +- Tungstène = +3 points +- Chrome = +2 points +- Antimoine = +2 points + +**Métaux Précieux** +- Gold = +4 points +- Platine = +5 points +- Silver = +3 points +- Iridium = +6 points + +**Ressources Énergétiques & Chimiques** +- Lithium = +4 points +- Thorium = +3 points +- Soufre = +1 point +- Phosphore = +1 point +- Natron = +1 point + +**Ressources Organiques** +- Bois dur = +1 point +- Terre noire = +1 point +- Zinc = +2 points + +**Ressources Énergétiques** +- Pétrole = +3 points +- Gaz naturel = +2 points +- Uranium = +5 points + +**Ressources Organiques** +- Forêt dense = +1 point +- Zone de chasse = +1 point +- Eau douce = +1 point + +### Vestiges et Structures (Variables) +**Vestiges Anciens** +- Ruines antiques = +1 point (matériaux récupérables) +- Ruines médiévales = +1 point +- Vestiges industriels = +1 point (scrap métallique) + +**Ruines Inutiles** +- Ruines effondrées = -1 point (obstruction) +- Décombres = -1 point +- Structures instables = -2 points + +### Contraintes Géologiques (Négatives) +**Terrain Difficile** +- Marécages = -1 point +- Terrain rocailleux = -1 point +- Pentes abruptes = -2 points +- Instabilité géologique = -3 points + +**Contaminations Historiques** +- Pollution minière ancienne = -2 points +- Contamination chimique = -2 points +- Pollution radioactive = -3 points +- Radiations intenses = -5 points + +### Features Géologiques Spéciales +**Formations Naturelles** +- Grottes = +1 point (abri, ressources cachées) +- Sources thermales = +1 point +- Gisements de sel = +1 point +- Météorite = +5 points (métaux rares et précieux concentrés) +- Forêt pétrifiée = +2 points (silice, attraction géologique) +- Geysers d'eau chaude = +2 points (énergie, tourisme thermal) +- Cheminées de fées = +1 point (formation érosive unique) +- Arche naturelle = +1 point (pont rocheux, point de repère) +- Pilier rocheux isolé = +1 point (formation érosive, nidification) +- Mesa = +1 point (plateau isolé, position défensive) + +**Features Géographiques Aquatiques** +- Lac = +1 point (eau douce, transport) +- Lac avec île centrale = +2 points (position défensive, mystère) +- Étang = +1 point (ressource eau locale) +- Marécage = 0 points (ressources +2, difficultés terrain -2) +- Delta fluvial = +2 points (terres fertiles, voies navigation) +- Fjord = +1 point (port naturel protégé) +- Cascade = +1 point (énergie hydraulique) +- Geyser = +2 points (énergie géothermique, attraction) +- Source de rivière = +2 points (eau pure, position stratégique) +- Île fluviale = +1 point (position défensive sur cours d'eau) +- Archipel = +3 points (multiple positions défensives, pêche) +- Atoll = +2 points (lagon protégé, récif corallien) +- Crique isolée = +2 points (port caché, protection tempêtes) +- Crique avec îlot = +3 points (mouillage protégé, mystère) +- Skerry = +1 point (îlot rocheux, navigation difficile) +- Tombolo = +2 points (île reliée par banc de sable) +- Lac asséché = 0 points (sel +2, aridité -2) + +**Features Géographiques Terrestres** +- Canyon = 0 points (protection +2, accès difficile -2) +- Plateau élevé = +1 point (position dominante, vents) +- Vallée encaissée = +1 point (protection, microclimat) +- Plaine fertile = +2 points (agriculture excellente) +- Steppe = 0 points (pâturages +1, aridité -1) +- Dunes mobiles = -1 point (instabilité terrain) +- Oasis = +3 points (eau précieuse en zone aride) +- Col de montagne = +1 point (passage stratégique) +- Cirque glaciaire = +1 point (amphithéâtre naturel) +- Gorge = 0 points (passage étroit +1, accès limité -1) +- Glacier = +1 point (réserve d'eau douce, terrain difficile) +- Colline marécageuse = 0 points (position élevée +1, humidité -1) +- Caldeira = +3 points (sol volcanique fertile, géothermie) +- Isthme = +2 points (contrôle liaison terrestre) +- Vallée isolée = +2 points (protection totale, autarcie) +- Montagne isolée = +1 point (point de repère, position dominante) +- Cratère géant = +4 points (formation spectaculaire, minerais) +- Plateau désertique = 0 points (position élevée +1, aridité -1) +- Badlands = -1 point (érosion sévère, sol pauvre) +- Oasis de glace = +2 points (eau en zone arctique) +- Gouffre = -2 points (danger naturel, accès souterrain) + +**Features Géographiques Côtières** +- Baie protégée = +2 points (port naturel excellent) +- Falaises = 0 points (défense +2, accès -2) +- Plage de sable = +1 point (débarquement, tourisme) +- Récif corallien = +1 point (protection naturelle) +- Estuaire = +2 points (commerce fluvial-maritime) +- Presqu'île = +1 point (position défensive) +- Détroit = +2 points (contrôle passage maritime) +- Île côtière = +2 points (avant-poste maritime, défense) +- Falaises côtières = +1 point (défense naturelle, position élevée) +- Rift côtier = +1 point (formation géologique, accès limité) + +**Features Industrielles Historiques** +- Terikon = 0 points (pollution -2, scrap +2) [voir exemple détaillé section Score -1] +- Ville fantôme = -1 point (infrastructure +2, dangers -3) +- Usine textile abandonnée = 0 points (machinerie +2, amiante -2) +- Centrale thermique désaffectée = -1 point (infrastructure +3, pollution -4) +- Aciérie en ruines = +1 point (scrap métallique massif +3, contamination -2) +- Raffinerie abandonnée = -2 points (infrastructure +2, pollution toxique -4) +- Complexe chimique = -3 points (équipements +3, contamination sévère -6) +- Moulin industriel = +1 point (machinerie +2, roue hydraulique +1, délabrement -2) +- Briqueterie abandonnée = +1 point (argile locale +2, fours +1, fumées -2) +- Verrerie en ruines = +1 point (sable siliceux +2, équipements +1, débris -2) +- Papeterie désaffectée = 0 points (machinerie +2, pollution rivière -2) +- Distillerie illégale = +1 point (équipements cuivre +2, isolation +1, réputation -2) +- Scierie abandonnée = +1 point (outillage +3, bois stocké +1, rouille -3) + +**Cimetières de Véhicules** +- Cimetière de tanks = +2 points (scrap métallique militaire) +- Cimetière de voitures = +1 point (scrap métallique civil) +- Cimetière d'avions = +3 points (alliages aviation rares) +- Déchèterie à ciel ouvert = -1 point (pollution -3, scrap +2) +- Épave de train = +2 points (acier massif +3, accident historique -1) +- Cimetière de bateaux = +2 points (acier naval +3, corrosion -1) +- Dépotoir électronique = +1 point (métaux rares +3, toxicité -2) +- Station-service abandonnée = 0 points (cuves enterrées +1, contamination sol -1) + +**Sites Militaires Abandonnés** +- Base Cold War abandonnée = +1 point (bunkers +3, contamination -2) +- Zone de guerre ancienne (WW1) = 0 points (munitions dangereuses -2, scrap +2) +- Bunker Nazi enterré = +2 points (fortifications +3, histoire -1) +- Site de lancement de missiles = +3 points (infrastructure +4, contamination -1) +- Champ de mines inactif = -2 points (danger résiduel -3, déminage +1) +- Base navale abandonnée = +2 points (installations portuaires +3, rouille -1) +- Aérodrome militaire = +2 points (piste +3, hangars +1, carburant résiduel -2) +- Dépôt de munitions = -1 point (explosifs dangereux -4, métaux +3) +- Radar abandonné = +1 point (équipements électroniques +2, position élevée +1, obsolescence -2) + +**Sites Culturels & Naturels** +- Tribu indigène = +2 points (connaissances locales, guides) +- Village abandonné = 0 points (bâtiments +1, isolement -1) +- Monastère en ruines = +1 point (archives historiques, position élevée) +- Site archéologique = +2 points (artefacts, valeur scientifique) +- Phare abandonné = +1 point (position côtière stratégique) +- Château fort = +2 points (position défensive, pierre de taille) +- Observatoire astronomique = +1 point (optiques précises, site isolé) +- Cimetière historique = +1 point (patrimoine, position centrale) +- Université abandonnée = +2 points (laboratoires +3, bibliothèques +1, délabrement -2) +- Hôpital en ruines = 0 points (équipements médicaux +2, contamination -2) +- Prison désaffectée = +1 point (sécurité +3, réputation -2) +- Cathédrale gothique = +2 points (architecture +3, tourisme +1, entretien -2) +- Moulin à vent historique = +1 point (mécanique ancienne +2, position ventée +1, obsolescence -2) +- Ferme collective abandonnée = 0 points (hangars +2, terres +1, délabrement -3) + +**Anomalies Géologiques** +- Formations cristallines = +2 points +- Dépôts d'argile rare = +2 points +- Sables siliceux = +1 point +- Gisements de quartz = +2 points (pour optiques laser) +- Filons de diamant = +4 points (outils de précision, optiques industrielles) +- Pierres précieuses diverses = +2 points (technologie laser, électronique) +- Geysers de méthane = +2 points (énergie, mais risque d'explosion) +- Dôme de sel = +3 points (stockage souterrain, ressource chimique) +- Tourbière = +1 point (combustible organique, préservation) +- Coulée de lave ancienne = +2 points (roches volcaniques, terres fertiles) +- Cratère d'impact = +4 points (métaux rares, formation géologique unique) +- Faille géologique active = -1 point (instabilité +0, minerais exposés +1) +- Karst = 0 points (grottes +2, effondrements -2) +- Gisement d'ambre = +3 points (résine fossile, inclusions scientifiques) +- Schiste bitumineux = +2 points (hydrocarbures non-conventionnels) +- Doline = -1 point (effondrement naturel, accès souterrain) +- Entrée de grotte = +2 points (exploration, abri naturel) +- Grotte de surface = +1 point (abri visible, stockage) +- Puits de l'enfer = -3 points (gouffre profond, émanations dangereuses) + +**Biomes & Écosystèmes** +- Forêt tempérée = +1 point (bois, biodiversité) +- Forêt boréale = +1 point (conifères, sols acides) +- Forêt tropicale = +2 points (biodiversité, bois exotiques) +- Prairie = +1 point (agriculture, élevage) +- Savane = 0 points (pâturages +1, sécheresse -1) +- Toundra = 0 points (permafrost +0, froid extrême -1, isolation +1) +- Taïga = +1 point (bois massif, fourrures) +- Mangrove = +2 points (protection côtière, écosystème unique) +- Désert chaud = -1 point (aridité -2, minéraux exposés +1) +- Désert froid = -1 point (froid -1, isolation +0) +- Zone alpine = 0 points (position élevée +2, accès difficile -2) +- Marais salant = +1 point (sel naturel, difficultés terrain) +- Lande = 0 points (sol pauvre -1, tourbe +1) +- Maquis méditerranéen = +1 point (plantes aromatiques, feux -1) +- Steppe herbacée = 0 points (élevage +1, vents forts -1) +- Zone humide = +1 point (filtration naturelle, biodiversité) +- Plaine inondable = 0 points (fertilité +2, inondations -2) +- Plateau continental = +1 point (pêche, position maritime) +- Forêt mixte = +1 point (diversité bois, équilibre écologique) +- Chaparral = 0 points (résistance feu +1, broussailles -1) +- Pampa = +1 point (terres fertiles, vents constants) +- Jungle équatoriale = +2 points (ressources exotiques +3, accessibilité -1) +- Forêt de nuages = +2 points (humidité constante, espèces rares) +- Désert de sel = -1 point (hostile -3, extraction sel +2) +- Banquise = -2 points (isolation extrême -3, pêche arctique +1) +- Récif barrière = +3 points (protection +2, biodiversité marine +2, navigation -1) +- Oasis de montagne = +3 points (eau rare +2, position stratégique +2, accès -1) +- Vallée glaciaire = +1 point (sol fertile +2, climat rigoureux -1) + +**Éléments Climatiques & Météorologiques** +- Zone de tornades = -2 points (danger -3, énergie éolienne +1) +- Couloir de vents = +1 point (énergie éolienne constante) +- Zone de brouillards = -1 point (visibilité réduite -2, humidité +1) +- Micro-climat chaud = +1 point (agriculture prolongée) +- Poche de froid = -1 point (gel permanent, préservation naturelle) +- Zone de calme plat = 0 points (navigation difficile -1, tranquillité +1) + +**Éléments Anthropiques Modernes** +- Autoroute abandonnée = +1 point (bitume +2, pollution -1) +- Pont autoroutier = +2 points (passage stratégique +3, entretien -1) +- Tunnel ferroviaire = +2 points (passage montagne +3, maintenance -1) +- Ligne haute tension = +1 point (infrastructure électrique +2, danger -1) +- Éolienne cassée = 0 points (pièces mécaniques +2, encombrement -2) +- Antenne relais = +1 point (communication +2, position élevée +1, obsolescence -2) +- Pipeline enterré = +1 point (infrastructure +2, risque fuite -1) +- Décharge contrôlée = -1 point (récupération +2, pollution -3) + +**Éléments Mystérieux & Rares** +- Cercle de pierres = +2 points (mystère historique, point de repère) +- Monolithe isolé = +3 points (formation inexpliquée, attraction) +- Zone de silence radio = -1 point (phénomène inexpliqué -2, isolation +1) +- Anomalie magnétique = +2 points (minerais rares +3, instruments perturbés -1) +- Source radioactive naturelle = -2 points (danger -4, recherche scientifique +2) + +## Système de Découverte + +### Éléments Visibles +Détectables lors de la génération du chunk : + +**Géologiques Apparents** +- Relief et formations rocheuses +- Cours d'eau et sources +- Couverture forestière +- Ruines en surface + +**Indices Subtils** +- Végétation anormale (contamination) +- Coloration du sol (minerais) +- Formations géologiques particulières + +### Éléments Cachés +Nécessitent exploration spécialisée : + +**Niveau 1 - Prospection Géologique** +- Gisements souterrains (fer, cuivre, charbon) +- Nappes d'hydrocarbures +- Eaux souterraines +- Cavités souterraines + +**Niveau 2 - Exploration Magnétométrique** +- Structures métalliques enfouies +- Monolithes et anomalies magnétiques +- Épaves enterrées profondément +- Formations métalliques naturelles + +**Niveau 3 - Analyse Chimique/Radiologique** +- Contaminations invisibles +- Gisements radioactifs +- Pollutions chimiques anciennes +- Zones de décontamination nécessaire + +### Système de Découverte Stratifié + +#### Couche Visible +**Reconnaissance Standard** : Relief, végétation, structures en surface, cours d'eau +**Indices Subtils** : Végétation anormale suggérant contamination, coloration du sol indiquant minerais + +#### Couche Cachée - Niveau 1 +**Véhicule Géologique** : Révèle gisements souterrains, nappes d'hydrocarbures, eaux profondes +- Portée : 3×3 chunks depuis position +- Temps : 2-5 minutes selon profondeur + +#### Couche Cachée - Niveau 2 +**Véhicule Magnétométrique** : Détecte anomalies magnétiques, structures métalliques enfouies, monolithes +- Portée : 1×1 chunk haute précision +- Temps : 1-3 minutes + +#### Couche Cachée - Niveau 3 +**Véhicule NRBC** : Révèle contaminations invisibles, radiations, pollutions chimiques +- Sécurité : Protection équipage +- Temps : 3-8 minutes selon danger + +## Tendances Régionales + +### Concept de Spécialisation Géographique +Des **zones d'influence** superposées à la carte modifient les probabilités d'apparition des éléments, créant des régions avec des "personnalités" distinctes basées sur la géographie et l'histoire réelles. + +### Types de Régions + +#### Bassins Pétroliers (Golfe Persique, Mer du Nord) +- Pétrole : probabilité ×5 +- Gaz naturel : probabilité ×3 +- Terrains marécageux : ×2 +- Accès maritime naturel + +#### Zones Minières Historiques (Ruhr, Donbass, Oural) +- Fer et charbon : probabilité ×3-4 +- Teritons : probabilité ×8 (très caractéristique) +- Vestiges industriels : ×2 +- Pollution minière héritée : ×3 + +#### Régions Forestières/Montagneuses (Alpes, Carpates, Taïga) +- Forêt dense et chasse : probabilité ×3-4 +- Grottes et sources : ×2-3 +- Pentes abruptes : ×2 +- Instabilité géologique : ×1.5 + +#### Zones Post-Nucléaires (Tchernobyl élargi, sites d'essais) +- Pollution radioactive : probabilité ×10 +- Uranium accessible : ×3 +- Structures abandonnées : ×3 +- Végétation mutante caractéristique + +#### Régions Côtières (Littoraux, deltas) +- Accès maritime : bonus naturel +- Sédiments et argiles : ×2 +- Zones humides : ×1.5 +- Érosion côtière : contrainte spécifique + +### Zones de Transition +**Transition Progressive** : L'influence régionale diminue avec la distance du centre, créant des zones mixtes réalistes +**Superposition** : Plusieurs influences peuvent se combiner (montagne + ancien bassin minier = métaux précieux en terrain difficile) + +## Distribution et Équilibrage + +### Répartition des Scores (Distribution en Cloche) +- **30%** des tiles à score 0 (terrain neutre de base) +- **40%** des tiles à scores ±1 à ±3 (variations courantes) +- **20%** des tiles à scores ±4 à ±6 (zones remarquables) +- **8%** des tiles à scores ±7 à ±8 (zones exceptionnelles) +- **2%** des tiles à scores extrêmes ±9 à ±10 (zones légendaires) + +### Biais Géographiques Globaux +- **Zones montagneuses** : +1 point (concentration minérale naturelle) +- **Zones côtières** : +0.5 point (accès et sédiments) +- **Zones industrielles historiques** : -1 point (pollution héritée) + +### Sites Fixes Historiques +**Lieux Emblématiques** conservent leurs caractéristiques réelles : +- Tchernobyl : Score fixe -10 (radiations massives, zone morte) +- Golfe Persique : Score fixe +8 (pétrole abondant, infrastructure) +- Sibérie diamantifère : Score fixe +9 (diamants + or + difficultés extrêmes) +- Désert d'Atacama : Score fixe -7 (aridité extrême, minerais rares) +- Région Ruhr : Score fixe +3 (richesse industrielle) + +## Exemples de Génération + +### Tile Score +3 +**Combinaisons Possibles :** +- Pétrole (+3) = Gisement pur +- Fer (+1) + Bauxite (+2) = Double gisement +- Cuivre (+1) + Grottes (+1) + Ruines antiques (+1) = Complexe minier ancien +- Uranium (+5) + Contamination (-2) = Gisement dangereux + +### Tile Score 0 +**Combinaisons Possibles :** +- Rien = Terrain neutre standard +- Fer (+1) + Ruines effondrées (-1) = Gisement obstrué +- Forêt (+1) + Marécages (-1) = Forêt marécageuse +- Vestiges industriels (+1) + Pollution minière (-1) = Friche industrielle + +### Tile Score -3 +**Combinaisons Possibles :** +- Pollution radioactive (-3) = Zone contaminée simple +- Instabilité géologique (-3) = Zone dangereuse +- Contamination (-2) + Ruines effondrées (-1) = Site industriel pollué +- Uranium (+5) + Radiations (-5) + Pentes abruptes (-2) + Grottes (+1) = Mine uranium abandonnée + +## Features de Chunk Intégrées + +### Features Géologiques Majeures + +#### Terikon (Score -1) +- **Composition** : Vestiges industriels (+1) + Pollution minière (-2) +- **Visible** : Colline artificielle caractéristique +- **Caché** : Traces de métaux rares dans les déblais +- **Régional** : ×8 probabilité en zones ex-minières +- **Gameplay** : Déblaiement révèle ressources enfouies + +#### Vallée Fluviale (Score +2) +- **Composition** : Eau douce (+1) + Sédiments (+1) +- **Visible** : Relief et écoulement évidents +- **Caché** : Dépôts alluvionnaires précieux +- **Gameplay** : Dragage révèle minerais transportés + +### Features de Vestiges + +#### Complexe Industriel Abandonné (Score 0) +- **Composition** : Scrap (+1) + Pollution (-2) + Fer résiduel (+1) +- **Visible** : Structures industrielles en ruine +- **Caché** : Filons non exploités, équipement enterré +- **Régional** : Fréquent dans zones ex-industrielles +- **Gameplay** : Décontamination + fouilles révèlent trésors + +### Features d'Anomalies + +#### Site d'Anomalie Magnétique (Score +2) +- **Composition** : Monolithe mystérieux (+3) + Instabilité (-1) +- **Visible** : Formations géologiques étranges +- **Caché** : Structure métallique d'origine inconnue +- **Régional** : Très rare, distribution aléatoire +- **Gameplay** : Exploration magnétométrique révèle secrets + +## Évolution Temporelle + +### Actions Joueur Modifient Scores +- **Décontamination** : -2 → +1 avec technologie appropriée +- **Exploitation** : +3 → +1 après épuisement partiel +- **Pollution industrielle** : +2 → -1 après accident +- **Nettoyage ruines** : -1 → 0 après déblaiement + +### Processus Naturels +- **Régénération forestière** : +0.1 point/an en zone tempérée +- **Érosion contamination** : -0.05 point/an (très lent) +- **Sédimentation fluviale** : Peut révéler/cacher ressources +- **Instabilité géologique** : Évolution selon activité sismique + +## Gameplay Émergent + +### Spécialisation Économique Naturelle +**Bassins Pétroliers** deviennent naturellement centres énergétiques +**Anciennes Zones Minières** évoluent vers centres sidérurgiques +**Régions Forestières** se spécialisent dans construction bois et chasse + +### Stratégie Territoriale +**Contrôle Régional** : Certaines régions deviennent stratégiquement vitales +**Exploration Ciblée** : "Je cherche du fer → direction les montagnes ex-minières" +**Défis Spécialisés** : Chaque région impose ses contraintes techniques + +### Reconnaissance et Apprentissage +**Patterns Visuels** : Joueurs apprennent à reconnaître les indices régionaux +**Teritons** = Zone ex-minière probable = Fer mais pollution +**Végétation anormale** = Contamination = Danger mais ressources rares potentielles + +### Équilibre Risque/Récompense Automatique +**Zones Riches** compensées par contraintes proportionnelles +**Zones Sûres** moins rewarding mais accessibles +**Zones Extrêmes** très dangereuses mais très lucratives + +## Cohérence et Réalisme + +### Géographie Logique +Reproduit les patterns géologiques et historiques réels : les bassins pétroliers sont où ils devraient être, les zones minières correspondent aux vraies formations géologiques. + +### Histoire Intégrée +Chaque région raconte son histoire through les éléments présents : pollution industrielle héritée, vestiges d'exploitation, contaminations d'accidents passés. + +### Évolution Temporelle +Actions du joueur modifient progressivement les caractéristiques locales : décontamination, épuisement de gisements, accidents industriels. + +**Objectif Final** : Créer un monde où chaque tile a une identité unique déterminée par sa géographie, son histoire et son équilibre naturel risque/récompense, générant organiquement des choix stratégiques et des opportunités d'exploration meaningfuls. \ No newline at end of file diff --git a/docs/02-systems/message-communication-system.md b/docs/02-systems/message-communication-system.md new file mode 100644 index 0000000..2cdb660 --- /dev/null +++ b/docs/02-systems/message-communication-system.md @@ -0,0 +1,419 @@ +# Message Communication System + +## Vue d'ensemble + +Le système de communication inter-modules utilise des **classes de messages typées** au lieu de JSON brut pour garantir la fiabilité et la maintenabilité. + +## Concept fondamental + +**Une classe = un type de message** +**Une instance = un message individuel** + +Exemple: La classe `TankMovedMessage` définit le type "mouvement de tank". Chaque fois qu'un tank bouge, on crée une nouvelle instance de cette classe. + +## Pourquoi des classes? + +### Problème avec JSON brut +- Erreurs découvertes uniquement au runtime +- Pas de validation automatique +- Typos dans les clés non détectées +- Difficile à maintenir et refactoriser + +### Solution avec classes +- Validation au compile-time +- Contrat clair entre modules +- IDE autocomplétion et refactoring +- Hot-reload friendly (petites classes isolées) +- Évolutif (ajout de champs sans casser l'existant) + +## Architecture + +### IMessage - Interface de base + +Interface pure définissant le contrat minimal pour tous les messages: + +- **Type identification**: Chaque message déclare son type via enum +- **Serialization**: Conversion vers JSON pour transport via IIO +- **Deserialization**: Reconstruction depuis JSON reçu + +### AMessage - Classe abstraite avec métadata + +Classe abstraite obligatoire fournissant l'implémentation partielle commune à tous les messages. + +**Métadata immutables (enforced):** +- `timestamp` - Horodatage de création (const) +- `sender` - Module émetteur (const) +- `messageId` - ID unique pour tracking et reassemblage fragments (const) +- `partId` - ID de fragment pour messages multi-parts (const) + +**Caractéristiques:** +- Constructeur protégé force passage par classes enfants +- Métadata initialisées automatiquement à la construction +- Impossible de modifier métadata après création +- Tous messages garantis d'avoir timestamp/sender/messageId + +### MessageType - Enum central + +Enum listant tous les types de messages du système: +- `TANK_MOVED`, `TANK_FIRED`, `TANK_DESTROYED` +- `PRICE_UPDATED`, `TRADE_EXECUTED` +- `ITEM_PRODUCED`, `BELT_CONGESTION` +- etc. + +**Pourquoi enum plutôt que strings?** +- Performance (comparaison d'entiers) +- Type safety (typos détectées au compile) +- Centralisation (tous les types visibles) + +### Messages concrets + +Chaque type de message est une classe dédiée héritant de `AMessage`: + +**TankMovedMessage**: Position, vitesse, ID tank +**PriceUpdatedMessage**: Item, ancien prix, nouveau prix +**ItemProducedMessage**: Item type, quantité, factory ID + +Chaque classe: +- Hérite obligatoirement de `AMessage` +- Appelle constructeur `AMessage(senderModule)` +- Stocke ses données spécifiques +- Valide à la construction +- Sérialise/désérialise son propre format + +## Flow de communication + +### Publication + +**Exemple complet:** +```cpp +void TankModule::process(const json& input) { + // 1. Calculer nouvelle position + Vector2 newPos = calculatePosition(); + float currentSpeed = getSpeed(); + + // 2. Créer message (validation automatique à la construction) + TankMovedMessage msg(newPos, currentSpeed, tankId); + + // 3. Sérialiser en JSON + json serialized = msg.serialize(); + + // 4. Publier via IIO + io->publish("tank:" + std::to_string(tankId), serialized); +} +``` + +**Étapes:** +1. Module crée instance de message (validation à la construction) +2. Message sérialisé en JSON via `serialize()` +3. Publié via `IIO::publish(topic, json)` +4. IIO route vers subscribers du topic + +### Réception + +**Méthode 1: Type-safe template helper (recommandé)** +```cpp +// Clean syntax avec type safety automatique +auto tankMsg = io->pullMessageAs(); + +if (tankMsg) { // nullptr si type mismatch ou queue vide + Vector2 pos = tankMsg->getPosition(); + float speed = tankMsg->getSpeed(); +} +``` + +**Méthode 2: Manuelle (si besoin de flexibilité)** +```cpp +// Récupère message brut +Message rawMsg = io->pullMessage(); + +// Désérialise vers base +std::unique_ptr baseMsg = IMessage::deserialize(rawMsg.data); + +// Cast vers type concret +if (TankMovedMessage* tankMsg = dynamic_cast(baseMsg.get())) { + // Accès type-safe +} +``` + +**Template helper implementation:** +```cpp +class IIO { + // Template helper inline (zero overhead) + template + std::unique_ptr pullMessageAs() { + if (!hasMessages()) return nullptr; + + Message raw = pullMessage(); + std::unique_ptr base = IMessage::deserialize(raw.data); + + T* casted = dynamic_cast(base.get()); + if (!casted) return nullptr; // Type mismatch + + base.release(); + return std::unique_ptr(casted); + } +}; +``` + +**Performance:** +- Template inlined = zero function call overhead +- `dynamic_cast` = ~5-10ns (négligeable vs JSON parsing) +- Bottleneck réel = JSON serialization, pas le cast + +### Désérialisation centralisée + +**Factory pattern avec routing par type:** +```cpp +// IMessage base class +std::unique_ptr IMessage::deserialize(const json& data) { + // Extract type from JSON + int typeInt = data.value("type", -1); + MessageType type = static_cast(typeInt); + + // Route to concrete deserializer + switch (type) { + case MessageType::TANK_MOVED: + return TankMovedMessage::deserialize(data); + + case MessageType::PRICE_UPDATED: + return PriceUpdatedMessage::deserialize(data); + + case MessageType::ITEM_PRODUCED: + return ItemProducedMessage::deserialize(data); + + // Add new messages here + + default: + return nullptr; // Unknown type + } +} +``` + +**Chaque message implémente sa propre désérialisation:** +```cpp +class TankMovedMessage : public AMessage { + static std::unique_ptr deserialize(const json& data) { + try { + Vector2 pos{data["position"]["x"], data["position"]["y"]}; + float speed = data["speed"]; + int tankId = data["tankId"]; + + return std::make_unique(pos, speed, tankId); + } catch (const json::exception& e) { + return nullptr; // Malformed JSON + } + } +}; +``` + +**Gestion des erreurs:** +- JSON malformé → retourne `nullptr` +- Type inconnu → retourne `nullptr` +- Validation échoue → exception à la construction +- Modules doivent vérifier `if (msg != nullptr)` + +## Organisation du code + +### Location des messages +``` +modules/shared/messages/ +├── IMessage.h # Interface pure +├── AMessage.h # Classe abstraite avec métadata +├── MessageType.h # Enum des types +├── TankMovedMessage.h +├── PriceUpdatedMessage.h +└── ... +``` + +**Rationale:** +- Single source of truth (pas de duplication) +- Contrat partagé entre émetteur et récepteur +- Facile à trouver et maintenir + +### Validation + +**À la construction**: Invariants validés immédiatement +- Vitesse négative → exception +- ID invalide → exception +- Fail fast pour détecter bugs tôt + +**À la désérialisation**: Données réseau/externes validées +- JSON malformé → retourne nullptr +- Champs manquants → retourne nullptr +- Protège contre données corrompues + +## Décisions de design finalisées + +### Versioning - Breaking changes assumées + +**Décision:** Types versionnés avec breaking changes strictes + +Changement de format = nouveau type + nouvelle classe: +- `TANK_MOVED_V1` → `TANK_MOVED_V2` = types différents +- Pas de backward compatibility +- Pas de forward compatibility +- Migration forcée de tous les modules + +**Rationale:** +- Zéro ambiguïté sur le format attendu +- Pas de logique conditionnelle complexe +- Hot-reload force mise à jour synchronisée +- Détection immédiate des incompatibilités +- Code simple et clair + +**Conséquence:** +- Format change → tous modules doivent migrer +- Ancien code ne compile plus → migration manuelle obligatoire +- Breaking changes explicites et visibles + +### Message inheritance - AMessage obligatoire + +**Décision:** Classe abstraite `AMessage` avec métadata immutables enforced + +Architecture: +``` +IMessage (interface pure) + ↓ +AMessage (classe abstraite - métadata immutables) + ↓ +TankMovedMessage, PriceUpdatedMessage... (classes concrètes) +``` + +**Enforcement:** +- Constructeur `AMessage` protégé → impossible de créer message sans passer par enfant +- Métadata const → immutables après construction +- Tous messages garantis d'avoir timestamp/sender/messageId +- Format uniforme pour tous messages du système + +**Rationale:** +- Pas de duplication (métadata dans AMessage) +- Impossible d'oublier métadata +- Contrat strict et enforced au compile-time +- Simplicité pour messages concrets (métadata automatique) + +## Décisions de design finalisées (suite) + +### Size limits - Fragmentation automatique par IO + +**Décision:** Pas de limite au niveau message, fragmentation automatique par couche transport + +**Architecture:** +- **Modules**: Publient/reçoivent messages complets (transparence totale) +- **IIO**: Gère fragmentation/défragmentation automatiquement +- **Transport adaptatif**: Fragmentation si nécessaire selon type IO + +**Fragmentation par type:** +- **IntraIO**: Pas de fragmentation (copie mémoire directe) +- **LocalIO**: Fragmentation si > seuil (ex: 64KB chunks) +- **NetworkIO**: Fragmentation si > MTU (~1500 bytes) + +**Mécanisme:** +1. Module publie message → sérialisé en JSON +2. IO détecte si taille > seuil transport +3. Si oui: découpe en fragments avec `messageId` + `partId` +4. Transport des fragments +5. IO destination reassemble via `messageId` (collect tous `partId`) +6. Module reçoit message complet via `pullMessage()` + +**Robustesse:** +- **Packet loss**: Timeout si fragments incomplets (ex: 30s) +- **Ordering**: `partId` garantit ordre de reassemblage +- **Monitoring**: Log warning si message > 100KB (design smell probable) + +**Conséquence:** +- Messages peuvent être arbitrairement gros +- Complexité cachée dans couche IO +- Performance optimisée par type de transport + +### Async handling - Délégation au module + +**Décision:** Pas de gestion async spéciale au niveau messages + +**Rationale:** +- Messages = transport de données uniquement +- `ITaskScheduler` existe déjà pour opérations coûteuses +- Module décide si déléguer ou traiter directement +- Keep messages simple et stupid + +**Responsabilité:** +- **Message**: Transport de données (aucune intelligence) +- **Module**: Décide de déléguer opérations coûteuses au scheduler +- **ITaskScheduler**: Gère threading et async + +**Exemple:** +```cpp +// Module reçoit message déclenchant opération coûteuse +if (PathfindingRequestMessage* req = dynamic_cast<...>) { + // Module délègue au TaskScheduler + scheduler->scheduleTask(PATHFINDING_TASK, req->serialize()); + // Continue traitement autres messages +} + +// Plus tard, récupère résultat +if (scheduler->hasCompletedTasks() > 0) { + TaskResult result = scheduler->getCompletedTask(); + // Publie résultat via message +} +``` + +### Message ordering - Pas de garantie + Messages remplaçables + +**Décision:** Pas de garantie d'ordre, modules gèrent via timestamp si critique + +**Approche:** +- **Pas de FIFO enforced**: Messages peuvent arriver dans ordre arbitraire +- **Messages remplaçables par défaut**: `SubscriptionConfig.replaceable = true` pour majorité +- **Timestamp disponible**: `msg->getTimestamp()` permet tri manuel si nécessaire +- **Utilité questionnable**: Architecture modulaire rend ordre moins critique + +**Rationale:** +- Performance maximale (pas de garanties coûteuses) +- Messages remplaçables optimisent bandwidth (garde juste dernier) +- Timestamp dans `AMessage` permet tri si vraiment nécessaire +- Architecture découple les dépendances temporelles + +**Exemples d'usage:** +```cpp +// Prix - remplaçable (dernière valeur suffit) +io->subscribeLowFreq("economy:*", {.replaceable = true}); + +// Tank position - remplaçable (position actuelle suffit) +io->subscribe("tank:*", {.replaceable = true}); + +// Events critiques - non remplaçable + tri si nécessaire +io->subscribe("combat:*", {.replaceable = false}); + +// Si ordre vraiment critique (rare) +std::vector messages = collectAllMessages(); +std::sort(messages.begin(), messages.end(), + [](const Message& a, const Message& b) { + return a.getTimestamp() < b.getTimestamp(); + }); +``` + +**Conséquence:** +- Modules ne doivent pas assumer ordre de réception +- Messages remplaçables = dernière valeur seulement +- Tri par timestamp disponible mais rarement nécessaire + +## Questions ouvertes + +Aucune question ouverte restante. Toutes les décisions de design ont été finalisées. + +## Statut d'implémentation + +**Phase actuelle:** Design et documentation + +**Prochaines étapes:** +1. Créer interface `IMessage.h` +2. Créer classe abstraite `AMessage.h` avec métadata immutables +3. Créer enum `MessageType.h` +4. Implémenter 5-10 messages d'exemple +5. Tester avec modules existants +6. Itérer selon usage réel + +## Références + +- `src/core/include/warfactory/IIO.h` - Couche pub/sub +- `docs/01-architecture/architecture-technique.md` - Patterns de communication +- `docs/03-implementation/CLAUDE-HOT-RELOAD-GUIDE.md` - Impact sur design messages diff --git a/docs/02-systems/systeme-militaire.md b/docs/02-systems/systeme-militaire.md new file mode 100644 index 0000000..7ff669a --- /dev/null +++ b/docs/02-systems/systeme-militaire.md @@ -0,0 +1,884 @@ +# Système militaire + +## Conception de véhicules + +### Système de Frames +Une frame est une base sur laquelle on vient ajouter des composants dans une grille. Les frames ont des formes variées, rarement rectangulaires, avec des zones mortes et des emplacements d'overload spécifiques. + +#### Interface de Design +**Placement des Composants** : +- **Pick & Place** : Clic sur composant dans inventaire latéral, drag vers grille, clic pour placer +- **Snap automatique** : Alignement automatique sur grille avec feedback visuel +- **Rotations** : A/E pour tourner composants (standard PC gaming) +- **Snap toggle** : R pour désactiver/activer l'alignement grille +- **Zones interdites** : Feedback visuel rouge pour placements impossibles +- **Templates** : Designs pré-faits et patterns recommandés +- **Validation temps réel** : Contraintes (poids, énergie, etc.) vérifiées durant placement + +#### Anatomie d'un Châssis +``` +Exemple: Châssis "Griffon" (chenillé moyen) + [X][O][O][O][O][X] X = Zone morte (non utilisable) + [X][●][●][●][●][●][●][X] ● = Zone standard + [●][●][●][●][●][●][●][●] ○ = Zone overload possible + [●][●][●][●][●][●][●][●] ▲ = Zone centrale (critique) + [●][●][▲][▲][▲][▲][●][●] ■ = Zone flanc (vulnérable) + [■][■][▲][▲][▲][▲][■][■] ╬ = Zone déconnectée + [○][○][●][●][●][●][○][○] + [○][●][●][●][●][○] + +Exemple: Châssis "Viper" modulaire (roues) + [●][●][●] [●][●][●] Zones déconnectées + [●][▲][●] [●][▲][●] → Composants 3x3+ impossibles + [○][○][○] [○][○][○] → Chaque bloc autonome +``` + +**Zones spéciales** : +- **Zone centrale** : Composants critiques (moteur, IA principale) +- **Zones flanc** : +50% dégâts si touchées, éviter composants vitaux +- **Zones mortes** : Cases bloquées par forme du châssis +- **Zones overload** : Seuls endroits où overload possible +- **Zones déconnectées** : Blocs isolés, limitent taille composants + +### Générations et Styles de Châssis + +#### Concept de Générations +- **Gen 1 (1960-1980)** : Robustes, simples, réparables sur le terrain +- **Gen 2 (1980-2000)** : Électronique basique, modularité émergente +- **Gen 3 (2000-2020)** : Numérisation, composites, furtivité +- **Gen 4 (2020+)** : IA intégrée, matériaux avancés, hybride/électrique + +#### Styles Alternatifs & Originaux + +**Châssis "Sloped" (inspiré soviétique)** +- **Grille en losange** : 7x10 mais forme inclinée +- **Bonus** : -20% chance d'être touché, +15% ricochet +- **Malus** : Espace intérieur réduit, ergonomie difficile +- **Exemple** : Châssis chenillé sloped Gen2 + +**Châssis "Boxy" (inspiré occidental)** +- **Grille rectangulaire standard** : 8x12 optimisé +- **Bonus** : +20% espace utilisable, maintenance facile +- **Malus** : Profile plus élevé, angles morts +- **Exemple** : Châssis roues boxy Gen3 + +**Châssis "Hexagonal" (expérimental)** +- **Grille hexagonale** : placement alternatif des composants +- **Bonus** : Synergies à 6 faces, répartition dégâts optimale +- **Malus** : Coût production +30%, complexité assemblage +- **Breakthrough requis** : "Advanced Geometry Manufacturing" + +**Châssis "Modular Block" (futuriste)** +- **Grille segmentée** : 4 blocs de 3x3 non-connectés +- **Bonus** : Reconfiguration rapide sur le terrain +- **Malus** : Points faibles aux jonctions, composants >2x2 impossibles +- **Contrainte** : Chaque bloc isolé → composants doivent tenir dans un bloc +- **Spécial** : Peut changer configuration selon mission mais perd cohésion + +**Châssis "Organic" (bio-inspiré)** +- **Grille courbe** : forme irrégulière naturelle +- **Bonus** : Auto-réparation partielle, adaptation terrain +- **Malus** : Incompatible composants standards +- **Breakthrough requis** : "Biomimetic Engineering" + +#### Châssis Terrestres Nommés + +**Roues** +- **"Fennec"** (ultra-léger Gen3) : Forme triangulaire 2x3, overload arrière uniquement +- **"Coyote"** (léger Gen2) : Forme hexagonale allongée, zones mortes avant +- **"Bison"** (moyen Gen3) : Rectangle avec coins coupés, flancs exposés +- **"Rhino"** (lourd Gen4) : Forme trapézoïdale, zone centrale renforcée +- **"Viper"** (Desert Runner) : Profil serpentin, 3 zones overload isolées + +**Chenilles** +- **"Lynx"** (léger Gen3) : Forme diamant, excellente répartition +- **"Griffon"** (moyen Gen2) : Octogone irrégulier, zones mortes avant/arrière +- **"Mammoth"** (lourd Gen4) : Massif hexagonal, 8 zones overload périphériques +- **"Badger"** (Gen1 Vintage) : Rectangle simple, pas de zones mortes +- **"Crocodile"** (Low Profile) : Très allongé, zone centrale étroite +- **"Otter"** (Amphibie) : Forme hydrodynamique, zones mortes latérales + +**Rails** +- **Châssis locomotive** : 4x20 grille (moteur obligatoire) +- **Châssis wagon léger** : 4x12 grille +- **Châssis wagon lourd** : 6x15 grille +- **Châssis wagon plateforme** : 5x18 grille + +#### Châssis Aériens Nommés + +**Volants légers** +- **"Sparrow"** (quadcopter Gen3) : Croix parfaite, 4 moteurs aux extrémités +- **"Wasp"** (hexacopter Gen4) : Forme étoile, zones overload entre rotors +- **"Kestrel"** (léger Gen2) : Forme T inversé, zone centrale large +- **"Osprey"** (Tilt-Rotor) : Forme H, zones mortes centrales +- **"Raven"** (Stealth Copter) : Triangle noir, overload pointe avant uniquement + +**Volants moyens** +- **"Falcon"** (moyen Gen3) : Fusiforme classique, flancs vulnérables +- **"Eagle"** (Delta Wing) : Triangle parfait, pas de zones mortes +- **"Condor"** (Canard) : Forme X, 4 zones overload aux extrémités +- **"Phantom"** (Flying Wing) : Aile pure, zone centrale minimale + +**Volants lourds** +- **"Albatross"** (lourd Gen3) : Forme cruciforme, soute centrale massive +- **"Pelican"** (transport Gen2) : Rectangle avec protubérance avant +- **"Vulture"** (très lourd Gen4) : Forme W, 6 zones overload réparties +- **"Leviathan"** (Ekranoplan) : Forme aplatie, zones mortes latérales massives +- **"Manta"** (Blended Body) : Ovale parfait, overload périphérique uniquement + +#### Châssis Navals Nommés + +**Surface** +- **"Barracuda"** (ultra-léger Gen3) : Forme effilée, overload proue uniquement +- **"Hammerhead"** (léger Gen2) : Forme T, zone centrale élargie avant +- **"Orca"** (moyen Gen3) : Fusiforme avec renflement central +- **"Neptune"** (Trimaran) : 3 coques parallèles, zones mortes entre coques +- **"Skimmer"** (Hydrofoil) : Forme V inversé, zone centrale surélevée +- **"Poseidon"** (SWATH) : Double coque immergée, pont étroit +- **"Kraken"** (lourd Gen4) : Forme tentaculaire, 8 zones overload +- **"Behemoth"** (très lourd Gen3) : Hexagone massif, flancs exposés +- **"Atlas"** (plateforme Gen2) : Rectangle avec découpes pour piste + +**Submersibles** +- **"Piranha"** (ultra-léger Gen4) : Forme torpille pure +- **"Stingray"** (léger Gen3) : Forme diamant aplati +- **"Nautilus"** (Teardrop) : Goutte parfaite, pas de zones mortes +- **"Typhoon"** (Double Hull) : Rectangulaire avec double paroi +- **"Triton"** (moyen Gen2) : Cylindrique classique, zones mortes avant/arrière +- **"Abyss"** (lourd Gen3) : Forme bulbeuse, résistance pression +- **"Mariana"** (Deep Dive) : Sphère allongée, overload minimal +- **"Colossus"** (très lourd Gen4) : Multi-segments, zones overload entre sections + +#### Châssis Breakthrough Uniques + +**"Metamaterial Frame"** (tous domaines) +- **Grille adaptive** : Change de forme selon besoins +- **Breakthrough requis** : "Programmable Matter" +- **Bonus** : Reconfiguration temps réel +- **Malus** : Coût astronomique + +**"Plasma Shield Chassis"** (terrestre/naval) +- **Grille standard** + champ plasma +- **Breakthrough requis** : "Plasma Containment" +- **Bonus** : Immunité projectiles cinétiques +- **Malus** : Consommation énergie massive + +**"Quantum Tunneling Frame"** (submersible uniquement) +- **Grille quantique** : 4x4 mais espace infini +- **Breakthrough requis** : "Applied Quantum Mechanics" +- **Bonus** : Capacité interne illimitée +- **Malus** : Instabilité dimensionnelle + +## Layers + +Les frames sont les bases de chaque layer d'un matériel. Cela peut varier en fonction de la base d'un matériel : le châssis. + +**Ce qu'on peut construire avec les châssis** : + +Le même châssis peut servir à différents rôles selon ce qu'on y installe : + +**Châssis terrestre léger à roues** : +- Avec IA autonome → drone terrestre UGV +- Avec cabine pilote → camion de transport +- Avec blindage + mitrailleuse → véhicule de reconnaissance +- Avec compartiment personnel → transport de troupe léger + +**Châssis chenillé moyen** : +- Avec canon 30mm + compartiment → IFV +- Avec blindage renforcé + mitrailleuses → APC +- Avec canon 120mm → char léger +- Avec équipement génie → véhicule du génie + +**Châssis volant léger** : +- Avec IA + caméra → drone de surveillance +- Avec cabine pilote → hélicoptère léger +- Avec armement guidé → drone kamikaze +- Avec compartiment médical → évacuation sanitaire + +**Châssis volant lourd** : +- Avec soute à bombes → bombardier +- Avec compartiment cargo → transport +- Avec radar + missiles → intercepteur +- Avec équipement guerre électronique → AWACS + +**Châssis naval moyen** : +- Avec hélipad → frégate ASW +- Avec VLS → destroyer +- Avec canons → croiseur léger +- Avec IA autonome → drone naval USV + +**Châssis submersible** : +- Avec torpilles → sous-marin d'attaque +- Avec missiles balistiques → SSBN +- Avec compartiment cargo → transport furtif +- Avec IA + capteurs → UUV de reconnaissance + +### 3 Layers principaux +1. **Châssis** (mobilité, armure, structure) +2. **Systèmes** (IA, transmetteurs, radiateurs, électronique) +3. **Armes & Capteurs** (optiques, canons, radars, ERA) + +## Composants + +Les composants sont les éléments qui sont placés dans les frames. Ils ont des formes variées, rarement carrées et jamais 1x1. + +### Diversité Massive de Composants + +**Principe** : Des centaines de composants uniques, chacun avec forme, taille et caractéristiques propres. + +#### Exemples Layer Châssis +``` +Moteur Diesel Compact Moteur V8 Racing Turbine Jet + [█][█] [█] [█] [█][█][█] + [█] [█][█][█] [█][█][█] + [█] [█] + +Suspension Active Réservoir Principal Transmission CVT +[█] [█] [█][█][█][█] [█] + [█] [█][█][█][█] [█][█][█] +[█] [█] [█][█][█][█] [█] + +Blindage NERA Cage Survie Flotteurs Amphibie +[█][█][█][█][█] [█] [█] [█][█] [█][█] +[█][█][█][█][█] [█][█] [█] [█] +``` + +#### Exemples Layer Systèmes +``` +CPU Basique IA Tactique v3 Quantum Processor +[█][█] [█][█][█] [█] + [█][█][█] [█][█][█] + [█] [█] + +Radio HF Système AEGIS ECM Suite +[█] [█] [█][█][█][█] +[█] [█][█][█] [█][█][█][█] +[█] [█][█][█] + +Cooling Liquid Heat Pump Radiateur Graphène +[█][█][█] [█][█] [█] [█] + [█] [█] [█] +``` + +#### Exemples Layer Armes & Capteurs +``` +Canon 30mm Missile VLS Railgun Exp. +[█] [█][█] [█] +[█] [█][█] [█] +[█] [█][█] [█] + [█][█] [█] + [█] + +Optique x10 Radar AESA Sonar Passif +[█] [█][█][█][█] [█][█] + [█] [█][█] + +ERA Block Trophy APS Laser CIWS +[█] [█] [█] [█][█] + [█][█] [█][█] + [█] [█] [█][█] +``` + +**Formes communes** : +- **Forme L** : Radiateurs, tuyaux cooling (2x2 en L) +- **Forme T** : Systèmes de distribution énergie (3x2 en T) +- **Forme I** : Canons, missiles (1x3, 1x4, 1x5) +- **Forme Z** : Composants électroniques complexes +- **Forme +** : Hubs de connexion, joints universels +- **Forme Rectangle** : Blindage, batteries (2x3, 2x4, jamais carré) + +**Tailles minimales** : +- **Exceptions 1x1** : ERA blocks, capteurs basiques (seuls composants 1x1) +- **Plus petit standard** : 1x2 (optiques simples) +- **Standard petit** : 2x2 en forme L ou 1x3 +- **Standard moyen** : 2x3, 3x2, formes irrégulières +- **Gros composants** : 3x4+, souvent formes complexes + +### Explosion de Variantes par Technologie + +**Principe** : Une seule tech débloque 5-15 variantes adaptées aux différents usages + +#### Exemple : Tech "Autocannon Gen3" débloque : +``` +25mm Chain Gun 30mm Bushmaster 35mm Oerlikon +[█] [█] [█][█] +[█] [█] [█][█] +[█] [█] [█][█] + [█] + +40mm Bofors CT 20mm Gatling 30mm Coaxial +[█][█] [█][█][█] [█] +[█][█] [█] [█] +[█][█] +``` +- **25mm** : Léger pour IFV rapides (forme I mince) +- **30mm** : Standard IFV/APC (forme I standard) +- **35mm** : Anti-aérien (forme rectangle) +- **40mm** : Support lourd (forme L) +- **20mm Gatling** : Haute cadence (forme T) +- **30mm Coaxial** : Compact pour tourelle (forme courte) + +#### Exemple : Tech "Composite Armor v2" débloque : +``` +NERA Light (IFV) Chobham Standard Dorchester Heavy +[█][█][█] [█][█][█][█] [█][█][█][█][█] + [█][█][█][█] [█][█][█][█][█] + [█][█][█][█][█] + +Cage Armor Slat Kit Appliqué Module +[█] [█] [█] ═══════ [█][█] +[█] [█] [█] ═══════ [█][█] + ═══════ [█] +``` + +#### Variations par Génération + +**Gen 1 (1960s)** : Formes simples, robustes +- Canon 105mm L7 → 3 variantes (standard, court, long) +- Moteur diesel basique → 2 variantes (truck, tank) + +**Gen 2 (1980s)** : Diversification +- Canon 120mm smoothbore → 6 variantes (L44, L55, compact, etc.) +- Moteur turbodiesel → 5 variantes (power/efficiency trade-offs) + +**Gen 3 (2000s)** : Spécialisation +- Canon 120mm advanced → 10 variantes (urban, long-range, autoloader, etc.) +- Moteur hybride → 8 variantes (diesel-electric, turbine-electric, etc.) + +**Gen 4 (2020s)** : Explosion des options +- Railgun experimental → 12 variantes (energy levels, sizes, cooling) +- Moteur full-electric → 15 variantes (battery types, power outputs) + +#### Impact sur le Gameplay + +**Pour le Joueur** : +- Une tech = choix stratégiques multiples +- Optimisation selon doctrine (speed vs armor vs firepower) +- Mix & match pour designs uniques + +**Pour l'IA** : +- Companies développent préférences (Rheinmetall → gros canons) +- Évolution designs selon retours terrain +- Émergence de "schools of thought" régionales + +**Total avec variations** : +- ~100 technologies principales +- × 5-15 variantes chacune +- = **1000-1500 composants réels dans le jeu** + +**Règles d'exclusivité** : +- Composants généralement exclusifs par layer +- **Exception** : Certains composants de protection peuvent être partagés entre layers + +### Système d'Amélioration Générique + +**Principe** : Améliorations universelles applicables à toute catégorie d'équipement, stackables à l'infini avec rendements décroissants. + +#### Améliorations Universelles par Catégorie + +**Pour TOUTES les Armes** : +- **High ROF** : Cadence de tir +X%, chaleur +40% (non réduit) +- **High Velocity** : Vitesse projectile +X%, recul +30% +- **Match Grade** : Précision +X%, temps production +50% +- **Extended Barrel** : Portée +X%, poids +20% +- **Reliability** : MTBF +X%, coût maintenance -30% + +**Pour TOUS les Moteurs** : +- **Turbo** : Puissance +X%, conso fuel +50%, chaleur +40% +- **Efficiency** : Conso fuel -X%, puissance -15% +- **High Torque** : Couple +X%, vitesse max -20% +- **Reliability** : Durabilité +X%, performance -10% + +**Pour TOUS les Systèmes** : +- **Overclocking** : Performance +X%, élec +60%, chaleur +50% +- **Efficiency** : Conso élec -X%, performance -20% +- **Redundancy** : Fiabilité +X%, poids +30% +- **Miniaturization** : Poids -X%, coût +40% + +#### Formule de Stacking + +``` +Bonus effectif = Bonus_base × (1/2)^(n-1) +où n = nombre de fois appliqué + +Exemple High ROF: +1er: +20% ROF (120% total) +2e: +10% ROF (130% total) +3e: +5% ROF (135% total) +4e: +2.5% ROF (137.5% total) + +Malus: TOUJOURS COMPLET +1er: +40% chaleur +2e: +40% chaleur (80% total!) +3e: +40% chaleur (120% total!!) +4e: +40% chaleur (160% total!!!) + +Coût: Exponentiel modéré +Coût_final = Coût_base × 1.25^n +1 amélio: ×1.25 +2 amélios: ×1.56 +3 amélios: ×1.95 +4 amélios: ×2.44 +``` + +**Spécialisation** (bonus contextuel): +- **Arctic Package** : Fonctionne à -60°C, +15% coût +- **Desert Sealing** : Immunité sable, +20% coût +- **Urban Kit** : +30% rotation tourelle, -10% armure top +- **Naval Coating** : Anti-corrosion marine, +25% coût + +#### Exemple Concret : Canon 30mm avec Multi-Stack + +**Base** : +- 30mm Autocannon : 600 RPM, 100 damage, chaleur 50 + +**Application de 3× High ROF** : +``` +Stack 1: +20% ROF → 720 RPM, chaleur +40% (70 total) +Stack 2: +10% ROF → 792 RPM, chaleur +40% (90 total) +Stack 3: +5% ROF → 831 RPM, chaleur +40% (110 total) + +Coût: 100 × 1.25³ = 195 unités +Résultat: 831 RPM mais chaleur ×2.2! +``` + +**Application mixte (ROF + Velocity + Reliability)** : +``` +High ROF: +20% cadence, +40% chaleur +High Velocity: +20% dégâts, +30% recul +Reliability ×2: +20% MTBF puis +10% MTBF + +Coût: 100 × 1.25⁴ = 244 unités +Résultat: Arme polyvalente mais très chère +``` + +#### Exemples Extrêmes de Stacking + +**"Chaingun of Doom" (6× High ROF)** : +``` +Base: 600 RPM, 50 chaleur +Final: 945 RPM, 290 chaleur (!!) +Coût: ×3.81 +→ Nécessite système cooling dédié énorme +``` + +**"Eco Motor" (4× Efficiency)** : +``` +Base: 50L/100km, 300hp +Final: 31L/100km, 195hp (-35% perf totale!) +Coût: ×2.44 +→ Autonomie excellente, performance médiocre +``` + +**"Glass Cannon Railgun" (ROF×3 + Velocity×3)** : +``` +Base: 1000 damage, 10s reload, 500kW +Final: 1350 damage, 6.5s reload +Chaleur: +120%, Recul: +90%, Élec: 500kW +Coût: ×4.77 +→ DPS massif mais ingérable sans support +``` + +#### Règles de Stacking + +**Pas de limite** au nombre d'améliorations : +- Stack même amélioration = rendements décroissants +- Mix différentes amélios = synergie ou conflits +- **Forme reste IDENTIQUE** peu importe le stack +- Malus s'accumulent linéairement (danger!) + +### Amélioration de Châssis + +**Principe** : Les châssis peuvent aussi être améliorés mais avec coûts exponentiels et nouvelles ressources requises. + +#### Améliorations Châssis Spécifiques + +**Châssis "Griffon" Gen2 (base)** : +``` +Base: 100 Steel +Forme: Octogone 8x14, zones mortes standard + ++1 amélio: 125 Steel + 20 Composite ++2 amélios: 156 Steel + 40 Composite + 15 Titanium ++3 amélios: 195 Steel + 80 Composite + 35 Titanium ++4 amélios: 244 Steel + 160 Composite + 65 Titanium + 10 Ceramics ++5 amélios: 305 Steel + 320 Composite + 120 Titanium + 25 Ceramics +``` + +**Types d'améliorations châssis** : +- **Reinforced Structure** : +30% HP, +20% poids +- **Lightweight Frame** : -25% poids, -15% protection, +coût +- **Extended Grid** : +2 cases overload possibles +- **Improved Geometry** : -1 zone morte, +coût massif +- **Modular Mounting** : +1 zone centrale (critique → standard) +- **Composite Upgrade** : +20% résistance, +nouvelles ressources + +#### Exemples Concrets + +**"Griffon" Enhanced (3 amélios)** : +``` +Base form: [X]●●●●[X] + ●●●●●●●● + ●▲▲▲▲●● + ■■▲▲▲▲■■ + +Enhanced: [O]●●●●[O] (+Extended Grid) + ●●●●●●●● + ●▲▲▲▲▲●● (+Modular Mounting) + ■●▲▲▲▲●■ (+Improved Geometry) + +Coût: 195 Steel + 80 Composite + 35 Titanium +Bonus: +2 overload zones, +1 centrale, -2 zones mortes +``` + +**"Lynx" Ultra-Light (4 amélios)** : +``` +4× Lightweight Frame stacked: +-25%, -12.5%, -6.25%, -3.125% = -43% poids total +-15%, -15%, -15%, -15% = -60% protection!! + +Coût: 244 Steel + 160 Composite + 65 Titanium + 10 Ceramics +Résultat: Châssis papier mais ultra-rapide +``` + +#### Ressources Avancées Requises + +**Composite Materials** : +- Requis pour améliorations châssis moyennes +- Production complexe (Carbon + Resin + Pressure) + +**Titanium** : +- Châssis haute performance +- Ressource rare, extraction difficile + +**Ceramics** : +- Améliorations extrêmes (5+ stacks) +- Tech très avancée requise + +**Metamaterials** : +- Améliorations breakthrough uniquement +- Coûts astronomiques + +#### Impact Économique + +**Escalade des coûts** : +- Châssis Gen1 amélioré peut coûter plus qu'un Gen4 standard +- Nouvelles supply chains requises (Titanium, Ceramics) +- Choix stratégique : few super-châssis vs many standard + +**Trade-offs** : +- Châssis perfect = 90% du budget véhicule +- Reste peu pour composants advanced +- Peut valoir le coup pour designs spécialisés + +**Impact Stratégique** : +- Components peuvent devenir **ultra-spécialisés** +- Châssis custom = signature builds +- Stack moderé = optimal, stack extrême = niche +- Nécessite blueprints pour gérer complexité +- **Ressources tier-2** deviennent critiques + +#### Conséquences Système + +**Problèmes en cascade** : +- Canon overclocked → +80% chaleur → besoin 2x radiateurs +- Moteur racing → +100% fuel → réservoirs plus gros ou autonomie divisée +- IA overclocked → +60% élec → générateur supplémentaire requis +- Tout overclock → système cooling peut saturer → shutdown combat + +**Choix tactiques** : +- Full performance = logistique cauchemar (fuel, maintenance) +- Efficacité max = performance médiocre mais autonomie +- Balance = compromis selon doctrine + +#### Impact sur le Meta + +**Designs uniques** : +- Même avec composants identiques, deux véhicules jamais pareils +- Companies IA ont préférences d'amélioration selon features +- Joueur peut créer designs signature + +**Trade-offs stratégiques** : +- Performance maximale vs coût raisonnable +- Spécialisation vs polyvalence +- Production rapide vs qualité optimale + +**Total possibilités** : +- 1500 composants de base +- × 5-10 améliorations possibles chacun +- × Combinaisons de 1-3 améliorations +- = **Millions de variantes possibles** + +### Système de Blueprints Multi-Échelles + +**Principe** : Sauvegarder et réutiliser des designs à toutes les échelles, du composant au véhicule complet. + +#### Niveaux de Blueprints + +**1. Micro-Blueprints (Arrangements de composants)** +``` +"Power Module v3" (4x3 sauvegardé) +[Motor][Motor][Radiator] +[Motor][Motor][Battery ] +[Trans][Trans][Battery ] +[Trans][Trans][Generator] + +→ Réutilisable dans tous mes designs futurs +``` + +**2. Layer Blueprints (Layer complet)** +``` +"Châssis Standard IFV" (Layer 1 complet) +- Arrangement moteur/transmission testé +- Blindage optimisé zones critiques +- Suspension équilibrée +→ Compatible avec châssis "Lynx", "Griffon", etc. +``` + +**3. Système Blueprints (3 layers combinés)** +``` +"Urban Fighter Mk2" (Système complet) +- Layer 1: Châssis mobilité urbaine +- Layer 2: Systèmes com/cooling optimisés +- Layer 3: Armes courte portée + APS +→ Adaptable à différents châssis de même classe +``` + +**4. Véhicule Blueprint (Design final)** +``` +"Viper AT-4" (Véhicule complet) +- Châssis: "Desert Runner" Gen3 +- Système: "Tank Hunter v5" +- Améliorations: Tous les overclocks +→ Production directe en usine +``` + +#### Gestion et Partage + +**Organisation personnelle** : +``` +Mes Blueprints/ +├── Micro/ +│ ├── Power/ +│ │ ├── Compact_Power_2x3.bp +│ │ └── Racing_Power_4x3.bp +│ ├── Weapons/ +│ │ └── AT_Combo_3x4.bp +│ └── Cooling/ +│ └── Max_Cool_2x4.bp +├── Layers/ +│ ├── Châssis_Speed.bp +│ └── Système_Overclocked.bp +├── Systèmes/ +│ └── Glass_Cannon_Full.bp +└── Véhicules/ + ├── MBT_Fortress.bp + └── IFV_Swarm.bp +``` + +**Partage communautaire** : +- **Export/Import** : Fichiers .bp partageables +- **Workshop** : Blueprints notés par la communauté +- **Company Blueprints** : IA companies ont leurs propres bibliothèques +- **Évolution** : Blueprints peuvent être fork et modifiés + +#### Adaptation et Compatibilité + +**Micro → Universel** : +- Module 4x3 fonctionne dans tout châssis avec 4x3 libre +- Rotation/miroir automatique possible +- Alerte si incompatible (forme/taille) + +**Layer → Semi-flexible** : +- Adapté aux châssis de même génération/style +- Ajustements mineurs automatiques possibles +- Warning si sub-optimal + +**Système → Contraintes** : +- Besoin châssis compatible (taille/forme similaire) +- Peut nécessiter adaptations manuelles +- Preview montre conflits potentiels + +#### Interface de Blueprint + +``` +[Conception Véhicule] +┌─────────────────────┬────────────────┐ +│ Grille Active │ Blueprints │ +│ │ ┌Favoris──────┐│ +│ [Current Design] │ │☆ Power v3 ││ +│ │ │☆ AT Combo ││ +│ [Drag Blueprint→] │ │☆ Cool Max ││ +│ │ └──────────────┘│ +│ │ ┌Recent───────┐│ +│ │ │ IFV Urban ││ +│ [Drop Zone] │ │ Tank Rush ││ +│ │ └──────────────┘│ +└─────────────────────┴────────────────┘ + +[Save Current as Blueprint] +Type: [Micro|Layer|System|Vehicle] +Name: [_________________] +Tags: [Urban][Speed][Gen3] +``` + +#### Méta-Évolution + +**Itération rapide** : +1. Design initial → test combat +2. Identifier module problématique +3. Remplacer juste ce module via micro-blueprint +4. Re-test → save nouvelle version + +**Lignées de designs** : +``` +MBT_Heavy_v1 (original) +├── MBT_Heavy_v2 (cooling fix) +├── MBT_Heavy_Urban (fork urbain) +│ └── MBT_Heavy_Urban_ERA (+ protection) +└── MBT_Heavy_Desert (fork désert) + └── MBT_Heavy_Desert_Eco (- conso) +``` + +**Impact stratégique** : +- Designs éprouvés deviennent "meta" +- Companies développent styles signature +- Joueur accumule bibliothèque personnelle +- Transfert de savoir entre parties + +### Synergies +Il est important de mettre en place une synergie entre certains composants pour que leur contact dans la grille les rende plus efficaces. + +**Types de synergies** : +1. **Synergie existentielle** : composants simplement présents dans la même frame +2. **Synergie couplée** : composants se touchent au moins une fois en un point +3. **Synergie de contact étendue** : composants se touchent le plus possible pour obtenir le plus gros bonus + - Calcul par nombre de faces adjacentes + - Visualisation : highlight des faces en contact avec micro-animation brillante + +### Systèmes spéciaux + +**Température** : +- **Sources de chaleur** : Puces IA dans layer systèmes, armes (railgun, canons) +- **Gestion** : Radiateurs dans layer systèmes pour refroidissement +- **Système dynamique** : Heat accumulation en temps réel selon utilisation +- **Overload system** : Possibilité de dépasser seuil thermique contre dégâts +- **Gestion IA** : IA combat gère automatiquement la température (pas le joueur) +- **Balance** : Avantage joueur contrebalancé par contraintes thermiques + +**Qualité d'assemblage** : +- **Conception** : Design "parfait" dans l'interface de conception +- **Production** : Réduction qualité lors de l'assemblage automatique si placement non-optimal +- **Systèmes optimisables** : Chaque système peut être optimisé (pas de plan unique) +- **Designs OP** : Existence de designs/assemblages optimaux découvrables +- **Erreurs placement** : Réduisent qualité du système final +- **Upgrades bras** : Bras meilleure précision + bras de "lob" pour composants +- **Règle** : Penser à l'assemblage dès la conception pour éviter pénalités + +**Châssis Overload** : +- **Principe** : Possibilité d'ajouter cases de conception au-delà des limites initiales +- **Limites** : Nombre max de cases d'overload défini par châssis + tech déblocables +- **Châssis différenciés** : Certains châssis plus "overload-friendly" que d'autres +- **Pénalités linéaires** par châssis : malus % sur fiabilité, vitesse, cooling, poids +- **Conséquences cascade** : + - Poids élevé → terrains impraticables, trains solides requis + - Cooling réduit → surchauffe plus rapide + - Fiabilité réduite → maintenance accrue +- **Timing** : Overload recommandé lors des refits (pas conception initiale) +- **IA tactique** : Sélection véhicules selon mission (haut risque = overloadés) +- **Coût réel** : Prix production des composants avancés (recherche) +- **Compensation** : Nouveaux composants tech compensent partiellement malus +- **Encouragement cycle armes** : Armes évoluent petit→moyen→gros, forçant overload ou châssis lourds + +**Maintenance & Refit** : +- **Usure progressive** : Barrels d'armes deviennent inutilisables après usage intensif +- **Maintenance préventive** : Remplacement composants usés avant panne +- **Refit modifications** : Ajouter ERA, changer canon, upgrade composants +- **Usine obligatoire** : retour en usine pour modifications majeures +- **Usines de terrain** : maintenance basique et réparations d'urgence +- **Pièces de rechange** : Stock et logistique des composants critiques + +## Valeurs des véhicules + +### Valeurs par élément +- **Armure** (int) +- **HP** (int) +- **Profile** (int) + +### Valeurs globales +- **HP** (int) +- **Multidmg aérien** (double) - armure du toit +- **Multidmg rear** (double) - armure arrière +- **Multiatk flank** (double) +- **Turret down is vehicule down** (bool) +- **Vmax** (int) +- **Accélération** (int) +- **Précision de tir** (double) +- **Précision de visée** (double) +- **Profile total** (int) +- **Reliability** (int %) + +## Techniques de l'armée + +### Catégories d'unités +*Tous les aspects doivent être applicables à toutes les factions* + +**Infanterie** : +- Unité d'occupation de terrain +- Puissante par ses capacités polyvalentes et sa discrétion naturelle + +**Véhicule de transport** : +- Transport de troupe, transport logistique, medevac +- Gamme : camion → M113 + +**IFV** : +- Doit être capable de transporter du personnel +- Exemple : Merkava comme IFV + +**MBT** : Char de bataille principal + +**Missiles** : +- Munition capable de se diriger +- Inclut artillerie guidée +- Missiles stratégiques : SCALP, Tomahawk +- Drones kamikaze stratégiques : Shahed +- Drones FPV ukrainiens + +**Drone copter** + +**Hélicoptère** : moteur "unique" mais lourd + +**Jet léger** : un moteur + +**Jet lourd** : deux moteurs + +**Transport aérien** + +**Bombardier lourd** : 3+ moteurs + +## IA militaire + +### Prévention des glitches +Il vaut mieux éviter qu'on puisse glitcher l'IA, et surtout de manière éternelle. + +**Exemple de timeout sur pathfinding** : +1. IASystem give : "Soldat go to B (point A vers B)" +2. GameServer : "copy timeout is 30tick" +3. GameServer in 30ticks fails to move to the point +4. GameServer : "Soldat pathfinding failed from A to B" +5. IASystem : "Soldat go to C" (position de C totalement différente) + +**Problème** : Si le soldat est bloqué de tous les côtés → proposer la destruction des obstacles ? + +## Performance Combat Server + +### Gestion de milliers d'unités +- **Adaptive tick rate** : 60→15 TPS sous charge +- **Simulation temps réel** complexe +- **Batailles massives** : 10k unités = 30 secondes de traitement +- **Background processing** : player continue autres tâches pendant combats + +### Architecture performance +- **Langages** : C++/C/ASM pour calculs critiques +- **Scope étendu** : Infantry, véhicules, aviation, missiles, logistique militaire +- **Actions normales** intégrées : assaut, reconnaissance, soutien, etc. \ No newline at end of file diff --git a/docs/03-implementation/ADVANCED_TESTING.md b/docs/03-implementation/ADVANCED_TESTING.md new file mode 100644 index 0000000..f9640f8 --- /dev/null +++ b/docs/03-implementation/ADVANCED_TESTING.md @@ -0,0 +1,321 @@ +# 🛡️ Warfactory Advanced Testing & Verification System + +Ce document décrit le système de test et vérification avancé intégré dans Warfactory, conçu pour détecter automatiquement les bugs, vulnerabilités et problèmes de performance sans intervention constante. + +## 🎯 Vue d'ensemble + +Le système combine **8 couches de défense** automatisées : + +1. **Compilation stricte** - Flags "No Trust" avec zéro tolérance +2. **Static Analysis** - Détection de bugs avant exécution +3. **Fuzzing automatique** - Test d'inputs malformés +4. **Formal Verification** - Preuve mathématique de propriétés +5. **Concurrency Analysis** - Détection de race conditions +6. **Coverage-guided testing** - Feedback de couverture de code +7. **ABI/Interface validation** - Compatibilité entre versions +8. **Contract-based programming** - Assertions partout dans le code + +## 🚀 Installation rapide + +```bash +# 1. Installer tous les outils automatiquement +./scripts/setup_advanced_tools.sh + +# 2. Configurer le projet avec tous les outils +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON .. + +# 3. Compiler avec toutes les défenses +make all-engines + +# 4. Lancer tous les tests avancés +make test-everything +``` + +## 🔧 Configuration par couches + +### ⚙️ **Niveau 1 : Compilation "No Trust"** + +Activé automatiquement sur tous les engines : + +```cmake +# Erreurs critiques = compilation échoue +-Werror=null-dereference -Werror=array-bounds -Werror=use-after-free +-Werror=uninitialized -Werror=return-type -Werror=format-security + +# Sanitizers complets (mode Debug) +-fsanitize=address,undefined,leak,memory,thread,cfi + +# Protection runtime maximale +-fstack-protector-all -fstack-clash-protection -D_FORTIFY_SOURCE=3 +``` + +### 🔍 **Niveau 2 : Static Analysis** + +```bash +# Cppcheck - analyse statique C++ +make economy-engine_cppcheck + +# Clang Static Analyzer +cmake -DENABLE_STATIC_ANALYSIS=ON .. +make economy-engine + +# PVS-Studio (si installé) +make economy-engine_pvs +``` + +### 🎯 **Niveau 3 : Fuzzing automatique** + +#### libFuzzer (Clang intégré) +```bash +make economy-engine_fuzz_run # 5 minutes de fuzzing +``` + +#### AFL++ (coverage-guided) +```bash +make economy-engine_afl_run # Fuzzing avec feedback +``` + +#### honggfuzz (feedback hardware) +```bash +make economy-engine_honggfuzz_run +``` + +#### Fuzzing de tous les engines +```bash +make fuzz-all-engines # Fuzzing massif parallèle +``` + +### 🔬 **Niveau 4 : Formal Verification** + +#### CBMC - Model Checking +```bash +make economy-engine_cbmc # Vérification mathématique +``` + +#### KLEE - Symbolic Execution +```bash +make economy-engine_klee # Exploration symbolique +``` + +### 🧵 **Niveau 5 : Concurrency Analysis** + +#### Valgrind Helgrind +```bash +make economy-engine_helgrind # Détection race conditions +``` + +#### Valgrind DRD +```bash +make economy-engine_drd # Détection data races +``` + +#### Intel Inspector (si disponible) +```bash +make economy-engine_inspector # Analyse threading avancée +``` + +### 📊 **Niveau 6 : Coverage Analysis** + +```bash +# Génération rapport de couverture +make economy-engine_coverage_run + +# Rapport HTML dans economy-engine_coverage_report/ +open economy-engine_coverage_report/index.html +``` + +### 🔗 **Niveau 7 : ABI Validation** + +```bash +# Créer baseline ABI +make economy-engine_abi_dump +cp economy-engine_current.abi.tar.gz ../abi_baselines/economy-engine_baseline.abi.tar.gz + +# Vérifier compatibilité après changements +make economy-engine_abi_check +open economy-engine_abi_report.html +``` + +### 📋 **Niveau 8 : Contract Programming** + +Utilisation dans le code C++ : + +```cpp +#include +#include + +void process_market_data(gsl::not_null price, double volume) { + // Préconditions automatiques + WARFACTORY_REQUIRE(std::isfinite(*price)); + WARFACTORY_REQUIRE(volume > 0.0); + + double result = calculate_value(*price, volume); + + // Postconditions automatiques + WARFACTORY_ENSURE(std::isfinite(result)); + WARFACTORY_PROPERTY_FINITE_VALUES(result); +} +``` + +## 🎮 Modes d'utilisation + +### 🚀 **Mode Développement** +```bash +cmake -DCMAKE_BUILD_TYPE=Debug .. +make economy-engine +# → Tous les sanitizers + assertions activés +``` + +### ⚡ **Mode Production** +```bash +cmake -DCMAKE_BUILD_TYPE=Release .. +make economy-engine +# → CFI uniquement, performance optimisée +``` + +### 🔬 **Mode Test Complet** +```bash +cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON .. +make test-everything +# → Tous les outils activés, test marathon +``` + +### 🎯 **Mode Fuzzing Intensif** +```bash +cmake -DENABLE_FUZZING=ON .. +make fuzz-all-engines +# → Fuzzing 24/7 sur tous les engines +``` + +## 📈 Targets disponibles + +### Par engine (exemple : economy-engine) +```bash +# Compilation +make economy-engine + +# Static Analysis +make economy-engine_cppcheck +make economy-engine_pvs + +# Fuzzing +make economy-engine_fuzz_run # libFuzzer +make economy-engine_afl_run # AFL++ +make economy-engine_honggfuzz_run # honggfuzz +make economy-engine_fuzz_all # Tous les fuzzers + +# Formal Verification +make economy-engine_cbmc # Model checking +make economy-engine_klee # Symbolic execution + +# Concurrency +make economy-engine_helgrind # Race conditions +make economy-engine_drd # Data races +make economy-engine_inspector # Intel Inspector + +# Coverage +make economy-engine_coverage_run # Rapport HTML + +# ABI +make economy-engine_abi_dump # Créer baseline +make economy-engine_abi_check # Vérifier compatibilité +``` + +### Globaux (tous les engines) +```bash +make all-engines # Build tout +make fuzz-all-engines # Fuzzing massif +make analyze-all-engines # Static analysis +make coverage-all-engines # Coverage reports +make concurrency-all-engines # Concurrency analysis +make abi-all-engines # ABI validation +make test-everything # TOUT en parallèle +``` + +## 🔧 Configuration avancée + +### Variables CMake importantes +```bash +-DENABLE_ADVANCED_TOOLS=ON # Active tous les outils +-DENABLE_STATIC_ANALYSIS=ON # Clang Static Analyzer +-DENABLE_FUZZING=ON # Support fuzzing +-DCMAKE_BUILD_TYPE=Debug # Tous les sanitizers +``` + +### Personnalisation par engine +```cmake +# Dans engines/Mon-Engine/CMakeLists.txt +warfactory_add_defenses(mon-engine) # Défenses de base +warfactory_add_fuzzing(mon-engine) # Fuzzing +warfactory_add_formal_verification(mon-engine) # Vérification formelle +warfactory_add_concurrency_analysis(mon-engine) # Concurrence +warfactory_add_coverage_analysis(mon-engine) # Coverage +warfactory_add_abi_validation(mon-engine) # ABI +warfactory_add_gsl_support(mon-engine) # Guidelines Support Library +``` + +## 🎯 Intégration CI/CD + +### GitHub Actions exemple +```yaml +- name: Setup Advanced Tools + run: ./scripts/setup_advanced_tools.sh + +- name: Build with all defenses + run: | + mkdir build && cd build + cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON .. + make all-engines + +- name: Run comprehensive testing + run: cd build && make test-everything +``` + +### Détection automatique de régressions +- **ABI changes** détectés automatiquement +- **Coverage regressions** bloquent les merges +- **Fuzzing crashes** remontés immédiatement +- **Contract violations** = build failure + +## 🚨 Résolution de problèmes + +### Si la compilation échoue +```bash +# 1. Vérifier les outils installés +./scripts/setup_advanced_tools.sh + +# 2. Mode minimal pour débugger +cmake -DCMAKE_BUILD_TYPE=Release .. + +# 3. Désactiver temporairement les défenses strictes +cmake -DENABLE_ADVANCED_TOOLS=OFF .. +``` + +### Si le fuzzing ne trouve rien +```bash +# Augmenter la durée +make economy-engine_fuzz_run ARGS="-max_total_time=3600" + +# Vérifier les seeds d'entrée +ls build/fuzzing/economy-engine/input/ +``` + +### Si les tests de concurrence échouent +```bash +# Analyser les rapports détaillés +cat economy-engine_helgrind.xml +cat economy-engine_drd.xml +``` + +## 📚 Références + +- [AFL++ Documentation](https://aflplus.plus/) +- [CBMC User Manual](https://www.cprover.org/cbmc/) +- [KLEE Tutorials](https://klee.github.io/tutorials/) +- [Valgrind Manual](https://valgrind.org/docs/manual/) +- [Microsoft GSL](https://github.com/microsoft/GSL) + +--- + +**💡 Philosophie Warfactory** : *"Zéro bug en production grâce à la détection automatique exhaustive en développement"* \ No newline at end of file diff --git a/docs/03-implementation/AUTOMATION_GUIDE.md b/docs/03-implementation/AUTOMATION_GUIDE.md new file mode 100644 index 0000000..0cddf03 --- /dev/null +++ b/docs/03-implementation/AUTOMATION_GUIDE.md @@ -0,0 +1,499 @@ +# 🤖 Warfactory Complete Automation Guide + +Ce guide décrit le système d'automation complet de Warfactory, conçu pour automatiser **complètement** le workflow de développement multi-engines avec Claude Code. + +## 🎯 Vue d'ensemble de l'automation + +Le système combine **12 couches d'automation** : + +1. **🔧 Dependency Management** - FetchContent automatique +2. **🧪 Testing per Engine** - CTest intégré +3. **📚 Documentation Auto** - Doxygen pour tous les engines +4. **🔗 Export/Import System** - Engines peuvent s'importer mutuellement +5. **⚙️ Multiple Build Configs** - Debug/Release/Testing/Profiling +6. **⚡ Precompiled Headers** - Compilation accélérée +7. **📦 Packaging Auto** - DEB/RPM/NSIS/Bundle +8. **🛡️ Advanced Defenses** - Fuzzing, formal verification, etc. +9. **🤖 Claude Code Targets** - Workflow spécialisé pour Claude +10. **📊 Performance Monitoring** - Benchmarks automatiques +11. **🔍 Static Analysis** - Validation de code continue +12. **🚀 CI/CD Simulation** - Pipeline complet local + +## 🚀 Installation complète + +```bash +# 1. Setup des outils avancés +./scripts/setup_advanced_tools.sh + +# 2. Application automation complète +./scripts/apply_full_automation.sh + +# 3. Build avec automation complète +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON -DENABLE_BENCHMARKING=ON .. + +# 4. Workflow complet Claude Code +make claude-workflow +``` + +## ⚙️ Configurations de build disponibles + +### 🐛 **Debug Mode** (Développement) +```bash +cmake -DCMAKE_BUILD_TYPE=Debug .. +# → Tous les sanitizers, assertions, debug symbols +# → Optimisation: -O0 -g +# → Parfait pour développement avec Claude Code +``` + +### 🚀 **Release Mode** (Production) +```bash +cmake -DCMAKE_BUILD_TYPE=Release .. +# → Optimisation maximale, pas de debug +# → Optimisation: -O3 -DNDEBUG +# → Parfait pour déploiement +``` + +### 🧪 **Testing Mode** (CI/CD) +```bash +cmake -DCMAKE_BUILD_TYPE=Testing .. +# → Coverage activé, optimisation minimale +# → Optimisation: -O0 -g --coverage +# → Parfait pour mesurer la couverture de test +``` + +### 📊 **Profiling Mode** (Performance) +```bash +cmake -DCMAKE_BUILD_TYPE=Profiling .. +# → Profiling activé, optimisation modérée +# → Optimisation: -O2 -g -pg +# → Parfait pour analyser les performances +``` + +## 📦 Dependency Management automatique + +### Librairies auto-installées par FetchContent : + +- **Redis++** : Communication inter-engines +- **nlohmann/json** : Sérialisation uniforme +- **spdlog** : Logging unifié +- **Catch2** : Framework de test +- **Google Benchmark** : Mesure de performance +- **Microsoft GSL** : Guidelines Support Library + +### Usage dans le code : +```cpp +#include // Communication +#include // JSON +#include // Logging +#include // Tests +#include // Benchmarks +#include // Safety contracts +``` + +## 🧪 Testing automatique par engine + +### Structure auto-générée : +``` +engines/Economy-Engine/ +├── tests/ +│ └── test_economy-engine.cpp # Tests unitaires +├── benchmarks/ +│ └── bench_economy-engine.cpp # Benchmarks performance +└── CMakeLists.txt # Configuration auto +``` + +### Commandes de test : +```bash +# Tests d'un engine spécifique +make economy-engine-tests +ctest -R economy-engine + +# Tests de tous les engines +make test-all-engines +ctest --parallel 4 + +# Benchmarks de performance +make economy-engine-bench +make bench-all-engines +``` + +## 📚 Documentation automatique + +### Génération auto avec Doxygen : +```bash +# Documentation d'un engine +make economy-engine_docs + +# Documentation de tous les engines +make docs-all + +# Visualiser +open build/docs/economy-engine/html/index.html +``` + +### Configuration automatique : +- **HTML + XML** générés +- **Source browser** activé +- **Code inline** inclus +- **Diagrammes** automatiques + +## 🔗 Export/Import entre engines + +### Usage automatique : +```cmake +# Dans Economy-Engine/CMakeLists.txt - automatique +warfactory_add_full_automation(economy-engine) + +# Dans un autre engine qui dépend d'Economy +find_package(economy-engine REQUIRED) +target_link_libraries(war-engine PRIVATE Warfactory::economy-engine-lib) +``` + +### Installation des packages : +```bash +# Installer pour utilisation externe +make install + +# Ou créer package +make package-all +``` + +## ⚡ Precompiled Headers automatiques + +### Headers pré-compilés automatiquement : +- **STL containers** (vector, string, unordered_map...) +- **I/O streams** (iostream, fstream...) +- **Threading** (thread, future, atomic...) +- **Math** (cmath, algorithm...) +- **Warfactory contracts** +- **Third-party libs** (si disponibles) + +### Fichier `pch.h` auto-généré dans chaque engine + +## 🤖 Targets d'automation pour Claude Code + +### Workflow de développement optimal : +```bash +# Workflow complet Claude Code (build + test + validate) +make claude-workflow + +# Build rapide tous les engines +make build-all-fast + +# Validation complète du code +make validate-all + +# Simulation CI/CD complète +make ci-simulation + +# Rebuild complet propre +make rebuild-all +``` + +### Static analysis automatique : +```bash +# Cppcheck sur tous les engines +make cppcheck-all + +# clang-tidy sur tous les engines +make clang-tidy-all + +# Validation combinée +make validate-all +``` + +## 📦 Packaging automatique multi-plateforme + +### Formats supportés automatiquement : + +**Linux :** +- **DEB** packages (Ubuntu/Debian) +- **RPM** packages (Fedora/CentOS) +- **TGZ/ZIP** archives + +**Windows :** +- **NSIS** installer +- **WIX** installer (MSI) +- **ZIP** archives + +**macOS :** +- **Bundle** (.app) +- **DragNDrop** (.dmg) +- **TGZ** archives + +### Commandes de packaging : +```bash +# Package par défaut +make package + +# Tous les formats +make package-all + +# Source seulement +make package-source + +# Binaires seulement +make package-binary +``` + +### Installation sélective par composants : +- **engines** : Executables de jeu +- **libraries** : Libs de développement +- **headers** : Headers C++ +- **documentation** : Docs générées + +## 🔧 Options CMake complètes + +### Options principales : +```bash +-DCMAKE_BUILD_TYPE=Debug|Release|Testing|Profiling +-DENABLE_ADVANCED_TOOLS=ON # Fuzzing, verification, etc. +-DENABLE_STATIC_ANALYSIS=ON # Clang Static Analyzer +-DENABLE_FUZZING=ON # Fuzzing automatique +-DENABLE_BENCHMARKING=ON # Google Benchmark +``` + +### Build examples complets : +```bash +# Développement Claude Code +cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON .. + +# Testing avec coverage +cmake -DCMAKE_BUILD_TYPE=Testing -DENABLE_BENCHMARKING=ON .. + +# Production optimisée +cmake -DCMAKE_BUILD_TYPE=Release .. + +# Profiling performance +cmake -DCMAKE_BUILD_TYPE=Profiling -DENABLE_BENCHMARKING=ON .. +``` + +## 🎯 Targets disponibles par engine (exemple: economy-engine) + +### Build & Core : +```bash +make economy-engine # Build basic +make economy-engine-lib # Build library +make economy-engine-tests # Build tests +make economy-engine-bench # Build benchmarks +``` + +### Documentation : +```bash +make economy-engine_docs # Generate docs +``` + +### Testing : +```bash +make economy-engine_unit_tests # Unit tests +make economy-engine_integration_tests # Integration tests +make economy-engine_benchmarks # Performance tests +``` + +### Advanced Testing : +```bash +make economy-engine_fuzz_all # All fuzzing +make economy-engine_cbmc # Formal verification +make economy-engine_helgrind # Race detection +make economy-engine_coverage_run # Coverage report +``` + +### Static Analysis : +```bash +make economy-engine_cppcheck # Cppcheck +make economy-engine_pvs # PVS-Studio +``` + +### ABI : +```bash +make economy-engine_abi_dump # Create ABI dump +make economy-engine_abi_check # Check compatibility +``` + +## 🎮 Targets globaux (tous les engines) + +### Build : +```bash +make all-engines # Build all +make build-all-fast # Quick build +make rebuild-all # Clean + rebuild +``` + +### Testing : +```bash +make test-all-engines # All tests +make bench-all-engines # All benchmarks +make coverage-all-engines # All coverage +``` + +### Advanced : +```bash +make fuzz-all-engines # Fuzzing massif +make analyze-all-engines # Static analysis +make concurrency-all-engines # Concurrency analysis +make test-everything # TOUT en parallèle +``` + +### Documentation : +```bash +make docs-all # All documentation +``` + +### Validation : +```bash +make validate-all # Complete validation +make cppcheck-all # Cppcheck on all +make clang-tidy-all # clang-tidy on all +``` + +### Claude Code Workflow : +```bash +make claude-workflow # Dev workflow +make ci-simulation # CI/CD simulation +``` + +### Packaging : +```bash +make package # Default package +make package-all # All formats +make package-source # Source distribution +make package-binary # Binary distribution +``` + +## 🔄 Workflow types recommandés + +### 👨‍💻 **Développement quotidien avec Claude** +```bash +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=Debug .. +make claude-workflow +# → Build + test + validation en une commande +``` + +### 🧪 **Testing & QA** +```bash +mkdir build-testing && cd build-testing +cmake -DCMAKE_BUILD_TYPE=Testing -DENABLE_BENCHMARKING=ON .. +make ci-simulation +# → Tests complets + coverage + benchmarks +``` + +### 🚀 **Préparation release** +```bash +mkdir build-release && cd build-release +cmake -DCMAKE_BUILD_TYPE=Release .. +make all-engines +make package-all +# → Build optimisé + packaging multi-plateforme +``` + +### 🔬 **Debug performance** +```bash +mkdir build-profiling && cd build-profiling +cmake -DCMAKE_BUILD_TYPE=Profiling -DENABLE_BENCHMARKING=ON .. +make bench-all-engines +# → Profiling + benchmarks détaillés +``` + +### 🛡️ **Security audit** +```bash +mkdir build-security && cd build-security +cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ADVANCED_TOOLS=ON .. +make test-everything +# → Fuzzing + static analysis + formal verification +``` + +## 📊 Monitoring automatique + +### Métriques collectées automatiquement : +- **Build times** par engine +- **Test coverage** par engine +- **Performance benchmarks** +- **Memory usage** par engine +- **Static analysis** issues +- **ABI compatibility** changes + +### Visualisation : +```bash +# Coverage reports HTML +open build/economy-engine_coverage_report/index.html + +# Documentation générée +open build/docs/economy-engine/html/index.html + +# ABI compatibility reports +open economy-engine_abi_report.html +``` + +## 🎯 Integration CI/CD + +### GitHub Actions exemple : +```yaml +name: Warfactory CI + +on: [push, pull_request] + +jobs: + full-automation: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Advanced Tools + run: ./scripts/setup_advanced_tools.sh + + - name: Apply Full Automation + run: ./scripts/apply_full_automation.sh + + - name: Configure + run: | + mkdir build && cd build + cmake -DCMAKE_BUILD_TYPE=Testing -DENABLE_ADVANCED_TOOLS=ON .. + + - name: Run Complete CI Simulation + run: cd build && make ci-simulation + + - name: Upload Coverage + uses: codecov/codecov-action@v3 + with: + files: build/coverage.xml +``` + +## 🚨 Troubleshooting + +### Si la configuration échoue : +```bash +# 1. Vérifier les dépendances +./scripts/setup_advanced_tools.sh + +# 2. Build minimal +cmake -DCMAKE_BUILD_TYPE=Release .. + +# 3. Désactiver automation temporairement +cmake -DENABLE_ADVANCED_TOOLS=OFF .. +``` + +### Si les tests échouent : +```bash +# Tests détaillés avec output +ctest --output-on-failure --verbose + +# Tests d'un engine spécifique +ctest -R economy-engine -V +``` + +### Si le packaging échoue : +```bash +# Vérifier installation +make install DESTDIR=/tmp/test-install + +# Package basique seulement +make package-binary +``` + +--- + +**💡 Philosophie Warfactory Automation** : *"Automatiser complètement le workflow pour que Claude Code puisse se concentrer sur la logique métier, pas sur l'infrastructure"* + +**🎯 Résultat** : Un seul `make claude-workflow` fait **tout** automatiquement ! \ No newline at end of file diff --git a/docs/03-implementation/CLAUDE-HOT-RELOAD-GUIDE.md b/docs/03-implementation/CLAUDE-HOT-RELOAD-GUIDE.md new file mode 100644 index 0000000..74b65be --- /dev/null +++ b/docs/03-implementation/CLAUDE-HOT-RELOAD-GUIDE.md @@ -0,0 +1,179 @@ +# 🔥 CLAUDE CODE HOT-RELOAD DEVELOPMENT GUIDE + +**Status**: PRODUCTION-READY - **0.4ms average reload time achieved!** + +This guide provides Claude Code sessions with everything needed for blazing-fast module development using the revolutionary hot-reload system. + +## 🚀 Performance Achievements + +### Benchmark Results (Validated) +- **Average Hot-Reload**: **0.4ms** +- **Best Time**: **0.055ms** +- **Complete 5-cycle test**: **2ms total** +- **Classification**: **🚀 BLAZING** (Sub-20ms target exceeded by 50x) +- **State Persistence**: **PERFECT** - all module state preserved + +### Comparison to Targets +- **Original Target**: Edit → Build → Test < 5 seconds +- **Achieved**: **Hot-reload < 1ms** +- **Improvement**: **5000x faster than target!** + +## 🏗️ System Architecture + +### Hot-Reload Pipeline +``` +Edit Module → cmake . → make → dlopen/dlsym → State Transfer → 0.4ms +``` + +### Key Components (All Implemented) +- **ModuleFactory**: Dynamic .so loading with dlopen/dlsym +- **SequentialModuleSystem**: Lightweight execution + hot-reload support +- **IntraIO**: Sub-millisecond pub/sub communication +- **State Management**: `getState()` / `setState()` with JSON serialization + +## 📁 Project Structure for Hot-Reload + +### Optimized Build Structure +``` +├── core/ +│ ├── include/warfactory/ # All interfaces implemented +│ ├── src/ # Lightweight implementations +│ └── CMakeLists.txt # Minimal deps (nlohmann_json only) +├── modules/ +│ ├── debug-world-gen/ # WORKING test module +│ │ ├── CMakeLists.txt # Autonomous build +│ │ ├── src/DebugWorldGenModuleLight.cpp # ~150 lines +│ │ └── debug-world-gen-light.so # Built artifact +└── focused-hot-reload-test # Performance validation +``` + +### Build Commands (Validated) +```bash +# Module build (3 seconds) +cd modules/debug-world-gen && cmake . && make -j4 + +# Test hot-reload (instant) +cd ../../core && ./bin/focused-hot-reload-test +``` + +## 🔧 Module Development Workflow + +### 1. Create New Module +```cpp +// Required entry points for hot-reload +extern "C" { + IModule* create_module() { return new YourModule(); } + void destroy_module(IModule* m) { delete m; } + const char* get_module_type() { return "your-module"; } + const char* get_module_version() { return "1.0.0"; } +} +``` + +### 2. Implement State Management +```cpp +// Hot-reload state preservation +json getState() override { + return { + {"config", config}, + {"work_done", workCounter}, + {"initialized", initialized} + }; +} + +void setState(const json& state) override { + if (state.contains("config")) config = state["config"]; + if (state.contains("work_done")) workCounter = state["work_done"]; + // State restored - hot-reload complete! +} +``` + +### 3. Lightning-Fast Iteration Cycle +1. **Edit** module source (any changes) +2. **Build**: `make -j4` (2-3 seconds) +3. **Hot-reload**: Automatic via test or ModuleFactory (0.4ms) +4. **Verify**: State preserved, new code active + +## 🧪 Testing System + +### Focused Performance Test +```bash +# Validates complete hot-reload pipeline +./bin/focused-hot-reload-test + +# Output example: +# 🚀 BLAZING: Sub-20ms average reload! +# ✅ STATE PERSISTENCE: PERFECT! +# 📊 Average reload time: 0.4ms +``` + +### Test Capabilities +- **Multiple reload cycles** (5x default) +- **State persistence validation** +- **Performance benchmarking** +- **Error detection and reporting** + +## 💡 Development Best Practices + +### Module Design for Hot-Reload +- **Lightweight**: 150-300 lines typical +- **State-aware**: All important state in JSON +- **Self-contained**: Minimal external dependencies +- **Error-resilient**: Graceful failure handling + +### Compilation Optimization +- **Skip heavy deps**: Use minimal CMakeLists.txt +- **Incremental builds**: Only recompile changed modules +- **Parallel compilation**: `-j4` for multi-core builds + +### Performance Validation +- **Always test hot-reload** after major changes +- **Monitor state preservation** - critical for gameplay +- **Benchmark regularly** to detect performance regression + +## 🚨 Critical Points + +### Interface Immutability +- **NEVER modify core interfaces**: IModule, IIO, ITaskScheduler, etc. +- **Extend via implementations** only +- **Breaking interface changes** destroy all modules + +### Common Pitfalls +- **Missing `break;`** in factory switch statements +- **Improper inheritance** for test mocks (use real inheritance!) +- **State not serializable** - use JSON-compatible data only +- **Heavy dependencies** in module CMakeLists.txt + +### Troubleshooting Hot-Reload Issues +- **Segfault on load**: Check interface inheritance +- **State lost**: Verify `getState()`/`setState()` implementation +- **Slow reload**: Remove heavy dependencies, use minimal build +- **Symbol not found**: Check `extern "C"` entry points + +## 🎯 Next Development Steps + +### Immediate Opportunities +1. **Create specialized modules**: Tank, Economy, Factory +2. **Real Engine integration**: Connect to DebugEngine +3. **Multi-module systems**: Test module interaction +4. **Advanced state management**: Binary state serialization + +### Performance Targets +- **Current**: 0.4ms average hot-reload ✅ +- **Next goal**: Sub-0.1ms reload (10x improvement) +- **Ultimate**: Hot-patching without restart (0ms perceived) + +## 📊 Success Metrics + +The hot-reload system has achieved **theoretical maximum performance** for Claude Code development: + +- ✅ **Sub-millisecond iteration** +- ✅ **Perfect state preservation** +- ✅ **Zero-dependency lightweight modules** +- ✅ **Autonomous module builds** +- ✅ **Production-ready reliability** + +**Status**: The hot-reload system enables **instantaneous module development** - the holy grail of rapid iteration for AI-driven coding. + +--- + +*This guide is maintained for Claude Code sessions. Update after major hot-reload system changes.* \ No newline at end of file diff --git a/docs/03-implementation/configuration/README.md b/docs/03-implementation/configuration/README.md new file mode 100644 index 0000000..f731e84 --- /dev/null +++ b/docs/03-implementation/configuration/README.md @@ -0,0 +1,240 @@ +# Configuration Documentation + +Ce dossier contient toute la documentation relative à la configuration du système Warfactory. + +## Fichiers de Configuration + +### `transport-economic-system.md` +**Points 251-290 - Configuration Parameters** + +Configuration économique complète avec paramètres JSON : + +#### Transport Configuration +- Coûts par mode de transport (ship/train/air/truck) +- Seuils de volume et temps de livraison +- Optimisation multi-modale + +#### Storage Configuration +- Coûts de stockage (€0.02/kg/day) +- Seuils d'inventaire (urgent/normal/oversupplied) +- Capacités maximales + +#### Market Configuration +- Phases économiques (6h cycles) +- Multiplicateurs de rareté +- Limites de coûts de transport + +#### Infrastructure Configuration +- Coûts de construction (rail/port/airport) +- Périodes de retour sur investissement (max 15 ans) +- Déclencheurs d'investissement + +#### Economic Complexity Configuration (Point 31) +**Progressive Sophistication - 5 Phases configurables :** +- **Phase 1** : Basic transport cost differences +- **Phase 2** : Order stacking and volume optimization +- **Phase 3** : Trading companies and arbitrage +- **Phase 4** : Infrastructure investment and regional development +- **Phase 5** : Complex economic simulation (Victoria 3-level) + +**Configuration JSON-driven :** +```json +{ + "complexity_level": "basic|intermediate|advanced|victoria3", + "enabled_modules": ["population", "market", "money", "trade", "policy"], + "simulation_frequency": "daily|hourly|realtime", + "economic_phases": { + "phase_1": { "enabled": true, "transport_costs": true }, + "phase_2": { "enabled": false, "order_stacking": false }, + "phase_3": { "enabled": false, "trading_companies": false }, + "phase_4": { "enabled": false, "infrastructure_roi": false }, + "phase_5": { "enabled": false, "victoria3_complexity": false } + } +} +``` + +**Victoria 3-Level Modules (Phase 5) :** +- **PopulationModule** : Demographics (Workers/Engineers/Managers classes) +- **MarketModule** : Supply/demand dynamics, price discovery +- **MoneyModule** : Currency, inflation, banking systems +- **TradeModule** : International commerce, tariffs, trade agreements +- **PolicyModule** : Government intervention, taxation, regulation + +#### Mode-Based Security Configuration (Point 32) +**Sécurité adaptative selon contexte d'usage :** + +**Configuration JSON-driven :** +```json +{ + "security_mode": "dev|solo|multiplayer", + "dev_mode": { + "unrestricted_access": true, + "debug_tools_enabled": true, + "hot_reload_validation": false, + "modding_allowed": true + }, + "solo_mode": { + "modding_allowed": true, + "local_authority": true, + "config_modification": true, + "network_validation": false + }, + "multiplayer_mode": { + "server_authority": true, + "anti_cheat_active": true, + "strict_validation": true, + "zero_tolerance": true + } +} +``` + +**Mode Security Levels :** +- **Dev Mode (Unrestricted)** : Full access, debug tools, hot-reload sans restriction +- **Solo Mode (Modding)** : Player modifications autorisées, local authority, config freedom +- **Multiplayer Mode (Authoritative)** : Server authority strict, anti-cheat complet, validation totale + +**Architecture adaptative :** +```cpp +enum SecurityMode { DEV_MODE, SOLO_MODE, MULTIPLAYER_MODE }; +class SecurityManager { + void configureMode(SecurityMode mode); // Adaptive security enforcement +}; +``` + +### `module-configuration.md` +**Configuration Système Modulaire** + +Configuration des modules et systèmes de dépendances : + +#### Smart Dependencies (Point 33) +**Dependency graphs avec recalculation intelligente :** + +```cpp +class ConfigDependencyGraph { + // Mapping ConfigKey → ComponentID avec dépendances + std::map> dependencies = { + {"materials.steel_plating.weight", {tank_mk1, tank_mk2, heavy_tank}}, + {"materials.steel_plating.cost", {economy_steel, factory_line_2}}, + {"weapons.cannon_75mm.damage", {tank_mk1, artillery_piece}} + }; + + void onConfigChange(ConfigKey key, json newValue) { + auto affected = dependencies[key]; + for(auto component : affected) { + component.recalculate(key, newValue); + markForUpdate(component); + } + } +}; +``` + +**Intelligent Propagation Flow :** +``` +Config Change → Dependency Resolution → Background Recalculation → Live Update +``` + +**Example concret :** +- **Change** : `steel_plating.weight = 15.0` (au lieu de 10.0) +- **Affected** : `tank_mk1`, `tank_mk2`, `heavy_tank` automatiquement détectés +- **Recalculation** : Weight/performance tous tanks recalculés en background +- **Live Update** : Changes instantanés sans restart ni rebuild + +#### Module Config Patterns +- A/B testing via configuration +- Hot-swapping de systèmes +- Configuration adaptable par environnement + +#### Avantages Modulaires +- Config changes instantanés (vs restart) +- Testing et debugging surgical +- Déploiement microservices-like + +### `error-handling.md` +**Points 291-310 - Error Handling** + +Gestion complète des erreurs et fiabilité système : + +#### Engine Crash/Restart +- Health check HTTP (30s intervals) +- Redis heartbeat monitoring +- Recovery automatique avec state restoration + +#### Redis Failover +- Persistence avec snapshots + append-only +- Multiple instances (primary/replica) +- Message replay après restart + +#### Anti-cheat & Validation +- Server authoritative design +- Anti-cheat psychologique (bugs simulés) +- Input validation V1/V2 + +#### Network & Module Failures +- Graceful degradation avec cache fallback +- Module isolation (pas de cascade) +- Timeout handling resilient + +### `security-measures.md` +**Points 311-330 - Security Measures** + +Mesures de sécurité complètes et anti-cheat avancé : + +#### Server Authority +- Server contrôle simulation complète +- Zero game logic côté client +- Mode-based security (dev/solo/multiplayer) + +#### Anti-cheat System +- Anti-cheat psychologique avec bugs simulés +- Design-based prevention structurelle +- Guerre psychologique contre cheaters + +#### Client Prediction +- V1 Thin Client (server authoritative) +- V2 Shared Logic (prediction + validation) +- Migration progressive sans réécriture + +#### Psychological Warfare +- Escalation progressive contre cheaters +- Retention joueurs légitimes +- Stratégies comportementales adaptatives + +### `deployment-strategies.md` +**Points 331-350 - Deployment Strategies** + +Stratégies de déploiement et migration progressive : + +#### Progressive V1→V2 Migration +- Migration zero-risk avec A/B testing +- Fallback automatique vers V1 +- Forward-compatible architecture + +#### Hot-reload Production +- Updates sans downtime en production +- State preservation durant updates +- Rollback rapide si problème + +#### A/B Testing Strategies +- Testing dynamique via configuration +- User segmentation et metrics collection +- Gradual expansion 5% → 100% + +#### Risk Mitigation +- Backward compatibility préservée +- Progressive enhancement sans régression +- Mode-based deployment (dev/staging/prod) + +## Intégration + +Ces paramètres correspondent aux **Points 251-350** de la master integration list et sont prêts pour intégration dans les systèmes de jeu. + +**Status :** ✅ **SPÉCIFIÉS ET VÉRIFIÉS** + +**Localisations originales :** +- `docs/toCheck/transport-economic-system.md` → Paramètres économiques (251-290) +- `docs/toCheck/architecture-modulaire.md` → Configuration modulaire + Anti-cheat (311-330) +- `docs/global/architecture-technique.md` → Error handling (291-310) + Server authority (311-330) +- `docs/architecture-technique.md` → Client prediction (311-330) + Migration V1→V2 (331-350) +- `docs/configuration/` → A/B testing et deployment patterns (331-350) + +**Points couverts :** 100+ paramètres de configuration, error handling, sécurité et déploiement détaillés \ No newline at end of file diff --git a/docs/03-implementation/configuration/deployment-strategies.md b/docs/03-implementation/configuration/deployment-strategies.md new file mode 100644 index 0000000..f6d5729 --- /dev/null +++ b/docs/03-implementation/configuration/deployment-strategies.md @@ -0,0 +1,154 @@ +# Deployment Strategies + +**Points 331-350 - Deployment Strategies** - Progressive V1→V2, hot-reload production, A/B testing + +## Progressive V1→V2 Migration + +### Zero-Risk Migration Strategy +**Migration sans risque avec fallback automatique** : + +- **Migration progressive** : 10% → 50% → 100% des utilisateurs +- **A/B testing** : Validation progressive par groupes d'utilisateurs +- **Fallback automatique** : Retour V1 si problème V2 +- **Forward-compatible** : Architecture V1 compatible V2 dès design + +### Migration Code Pattern +**Code adaptable sans réécriture** : + +```cpp +// Code adaptable V1/V2 sans réécriture complète +if (config.enable_v2_prediction) { + // V2: Client prediction + server validation +} else { + // V1: Server authoritative (fallback sûr) +} +``` + +### Performance Migration Targets + +| 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 | + +## Hot-reload Production + +### Production Hot-reload Capability +**Updates sans downtime** : + +- **Architecture modulaire** : Permet hot-reload même en production +- **State preservation** : Continuité état durant updates modules +- **Zero downtime** : Updates transparents pour utilisateurs +- **Rollback rapide** : Retour version précédente si problème + +### Production Safety Measures +**Sécurité déploiement production** : + +- **Build verification** : Hot-reload seulement si build réussi +- **Gradual rollout** : Déploiement progressif par serveur +- **Health monitoring** : Surveillance continue post-déploiement +- **Automatic rollback** : Retour automatique si métriques dégradées + +## A/B Testing Strategies + +### Dynamic A/B Testing +**Testing comportements via configuration** : + +```cpp +// A/B testing dynamic via config +if (config.experiment_group == "A") { + // Version A : Transport costs standard + shipCost = 0.10; +} else { + // Version B : Transport costs optimized + shipCost = 0.08; +} +``` + +### A/B Testing Scope +**Différents niveaux de testing** : + +- **Config parameters** : Transport costs, storage rates, timing +- **Economic models** : Différents algorithmes market clearing +- **UX variations** : Interface layouts, information density +- **Performance optimizations** : Différentes stratégies caching + +### Testing Methodology +- **User segmentation** : Groupes cohérents pour résultats fiables +- **Metrics collection** : Performance, engagement, satisfaction +- **Statistical significance** : Validation robuste avant déploiement +- **Gradual expansion** : 5% → 25% → 50% → 100% + +## Deployment Architecture Phases + +### Phase V1 : Simple Deployment +**Architecture optimisée simplicité** : + +- **Déploiement rapide** : Architecture simple, mise en production directe +- **Single source of truth** : Serveur authoritative uniquement +- **Minimal complexity** : Debug facilité, maintenance simplifiée +- **Fast iteration** : Cycles développement courts + +### Phase V2 : Advanced Deployment +**Architecture optimisée performance** : + +- **Shared logic deployment** : Client + serveur coordonnés +- **Testing avancé** : Validation prédiction + réconciliation +- **Complex orchestration** : Multiple services synchronisés +- **Performance optimization** : Latence minimale, throughput maximum + +## Risk Mitigation Strategies + +### Backward Compatibility +**Préservation compatibilité** : + +- **V1 reste disponible** : Fallback permanent en cas problème V2 +- **Shared data formats** : Compatibility données entre versions +- **API versioning** : Support multiple versions simultanées +- **Graceful degradation** : Fonctionnalité réduite vs failure total + +### Progressive Enhancement +**Évolution sans régression** : + +- **Feature flags** : Activation progressive nouvelles fonctionnalités +- **Incremental updates** : Petites améliorations vs big bang +- **User consent** : Opt-in pour features expérimentales +- **Rollback capability** : Retour version précédente rapide + +## Mode-Based Deployment + +### Development Mode +- **Hot-reload unrestricted** : Liberté totale pour testing +- **Debug tools active** : Monitoring complet disponible +- **Config override** : Modification paramètres temps réel +- **Error tolerance** : Crashes acceptables pour expérimentation + +### Staging Mode +- **Production simulation** : Environnement identique production +- **Performance testing** : Load testing, stress testing +- **Integration validation** : Tests end-to-end complets +- **Security verification** : Validation mesures sécurité + +### Production Mode +- **Stability first** : Priorité absolue stabilité +- **Monitoring intensive** : Surveillance continue métriques +- **Conservative updates** : Déploiements mesurés, validés +- **Rapid response** : Réaction immédiate incidents + +## Deployment Automation + +### CI/CD Pipeline +- **Automated testing** : Validation complète avant déploiement +- **Staged deployment** : Dev → Staging → Production +- **Rollback automation** : Retour automatique si échec +- **Notification system** : Alertes équipe sur status déploiement + +## Sources + +**Documentation originale :** +- `docs/architecture-technique.md` - Migration V1→V2, déploiement rapide +- `docs/configuration/module-configuration.md` - A/B testing dynamique +- `docs/configuration/security-measures.md` - Migration progressive +- `docs/configuration/error-handling.md` - Fallback strategies + +**Points couverts :** 20 stratégies de déploiement détaillées \ No newline at end of file diff --git a/docs/03-implementation/configuration/error-handling.md b/docs/03-implementation/configuration/error-handling.md new file mode 100644 index 0000000..f4d5f7e --- /dev/null +++ b/docs/03-implementation/configuration/error-handling.md @@ -0,0 +1,119 @@ +# Error Handling & Reliability System + +**Points 291-310 - Error Handling** - Anti-cheat validation, input responses, module failures, network issues + +## Engine Crash/Restart Strategy + +### Detection System +**Health monitoring automatique** : + +```bash +# 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 +**Restart et state restoration** : + +```cpp +// 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 +**Fallback vers cache local** : + +```cpp +// Dans chaque engine +if (!canReachEngine("economy")) { + // Utiliser derniers prix connus en cache + price = fallbackPriceCache.get(resource); + logWarning("Using cached price, Economy engine unreachable"); +} +``` + +## Redis Failover Strategy + +### Persistence Configuration +**Redis durability** : + +```bash +# Configuration Redis +save 900 1 # Save snapshot if 1+ keys changed in 15min +appendonly yes # Log toutes les commandes +``` + +### Multiple Instances +**High availability setup** : + +```bash +Primary Redis: 6379 (read/write) +Replica Redis: 6380 (read-only backup) +Si primary down → engines switch automatiquement vers replica +``` + +### Message Replay +**State recovery après Redis restart** avec replay des messages critiques. + +## Anti-cheat & Validation + +### Server Authoritative Design +- **Toute logique métier** côté serveur +- **Anti-cheat naturel** via validation centralisée +- **Zero game logic** côté client + +### Anti-cheat Psychologique +**Stratégie : Cheat attempts → "bugs" simulés progressifs** + +```cpp +class AntiCheatPsycho { + void onCheatDetected(CheatType type) { + switch(type) { + case SPEED_HACK: + simulateRandomLag(50ms, 500ms); + break; + case RESOURCE_HACK: + simulateVisualGlitches(tanks, 5%); + break; + case DAMAGE_HACK: + simulateDesync(movement, 2%); + break; + } + } +}; +``` + +### Input Validation +- **V1 Thin Client** : Validation authoritative serveur +- **V2 Client Prediction** : Validation + réconciliation +- **Build verification** : Hot-reload seulement si build réussi + +## Network Issues & Module Failures + +### Module Isolation +- **Failures localisées** : Pas de cascade entre modules +- **Module autonomy** : Continue avec dernières données reçues +- **Async communication** : Redis Pub/Sub pour resilience + +### Timeout Handling +- **Fallback patterns** : Cache local si engine unreachable +- **Graceful degradation** : Fonctionnalité réduite vs crash total +- **State preservation** : Maintien état durant failures temporaires + +## Sources + +**Documentation originale :** +- `docs/global/architecture-technique.md` - Section "Error Handling & Reliability" +- `docs/toCheck/architecture-modulaire.md` - Anti-cheat psychologique +- `docs/architecture-technique.md` - Validation patterns + +**Points couverts :** 20 spécifications error handling détaillées \ No newline at end of file diff --git a/docs/03-implementation/configuration/module-configuration.md b/docs/03-implementation/configuration/module-configuration.md new file mode 100644 index 0000000..6f5fa20 --- /dev/null +++ b/docs/03-implementation/configuration/module-configuration.md @@ -0,0 +1,58 @@ +# Configuration des Modules + +## Configuration Système Modulaire + +### Configuration Dependencies System + +**Smart configuration avec recalculation automatique** : + +```cpp +std::map> dependencies = { + {"materials.steel_plating.weight", {tank_mk1, tank_mk2, heavy_tank}}, + {"materials.steel_plating.cost", {economy_steel, factory_line_2}}, + {"weapons.cannon_75mm.damage", {tank_mk1, artillery_piece}} +}; + +void onConfigChange(ConfigKey key, json newValue) { + auto affected = dependencies[key]; + for(auto component : affected) { + DesignerModule::scheduleRecalc(component); + } +} +``` + +### Module Config Example + +**Configuration adaptable par module** : + +```cpp +bool useNewSystem = config.getBool("use_new_tank_system"); + +json process(json input) { + if(useNewSystem) { + return newTankModule->process(input); + } else { + return legacyTankSystem->process(input); + } +} +``` + +### Avantages Configuration Modulaire + +**Développement :** +- **Config changes** : Restart required → Instant +- **A/B testing** : Impossible → Trivial +- **Debugging** : Needle in haystack → Surgical precision + +**Maintenance :** +- **Module independence** : Tightly coupled → Zero dependencies +- **Testing** : Integration hell → Unit paradise +- **Deployment** : Monolith → Microservices-like +- **Scaling** : Rewrite → Configuration change + +## Points Couverts + +Cette configuration correspond aux patterns de configuration modulaire mentionnés dans les Points 251-290. + +**Source :** `docs/toCheck/architecture-modulaire.md` +**Type :** Configuration système et dépendances \ No newline at end of file diff --git a/docs/03-implementation/configuration/module-versioning.md b/docs/03-implementation/configuration/module-versioning.md new file mode 100644 index 0000000..1a491a0 --- /dev/null +++ b/docs/03-implementation/configuration/module-versioning.md @@ -0,0 +1,677 @@ +# Module Versioning System + +## Vue d'Ensemble + +Le système de versioning des modules utilise un format **MAJOR.MINOR.PATCH.BUILD** automatiquement généré par CMake lors de la compilation. Ce système permet de : + +- **Tracer les versions** : Identifier précisément quelle version du code a créé une save +- **Détecter incompatibilités** : Alerter si une save utilise une version différente +- **Debugging** : Reproduire bugs avec la version exacte du module +- **Développement** : Versions incrémentales automatiques sans maintenance manuelle + +## Format de Version + +### Structure : MAJOR.MINOR.PATCH.BUILD + +``` +0.1.15.3847 +│ │ │ │ +│ │ │ └─── BUILD : Auto-increment à chaque build (hash sources) +│ │ └────── PATCH : Auto-increment à chaque commit +│ └──────── MINOR : Manuel (fonctionnalités nouvelles) +└────────── MAJOR : Manuel (breaking changes) +``` + +### Composantes + +#### MAJOR (Manuel) +- **Incrémenté** : Breaking changes, incompatibilités majeures +- **Exemples** : Refonte complète architecture, changement format save incompatible +- **Gestion** : Modifié manuellement dans fichier `VERSION` +- **Valeur initiale** : `0` (pré-release), `1` (première version stable) + +#### MINOR (Manuel) +- **Incrémenté** : Nouvelles fonctionnalités, ajouts non-breaking +- **Exemples** : Nouveau type de tank, nouveau système économique +- **Gestion** : Modifié manuellement dans fichier `VERSION` +- **Valeur initiale** : `1` + +#### PATCH (Automatique) +- **Incrémenté** : À chaque commit Git +- **Calcul** : Nombre de commits depuis le début du projet +- **Exemples** : Bugfixes, optimisations, refactoring mineur +- **Gestion** : Calculé automatiquement par CMake via `git rev-list --count HEAD` + +#### BUILD (Automatique) +- **Incrémenté** : À chaque rebuild (si sources modifiées) +- **Calcul** : Hash MD5 des fichiers sources (`.cpp`, `.h`) +- **But** : Distinguer builds de dev avec code non-commité +- **Gestion** : Calculé automatiquement par CMake + +### Exemples de Versions + +``` +0.1.0.0 → Première version dev (MAJOR.MINOR manuel, PATCH/BUILD = 0) +0.1.5.1234 → Après 5 commits, build 1234 +0.1.5.1235 → Même commit, sources modifiées → nouveau build +0.1.6.1235 → Nouveau commit, sources identiques → même build (théorique) +0.2.10.3847 → MINOR bump (nouvelle feature) + 10 commits +1.0.0.0 → Release stable, reset PATCH/BUILD +``` + +## Implémentation CMake + +### Fichier VERSION + +Chaque module contient un fichier `VERSION` à la racine : + +``` +modules/tank/VERSION +``` + +Contenu du fichier : +``` +0.1 +``` + +Ce fichier contient uniquement `MAJOR.MINOR`. Les composantes `PATCH.BUILD` sont calculées automatiquement. + +### CMakeLists.txt du Module + +```cmake +cmake_minimum_required(VERSION 3.20) +project(TankModule) + +# ============================================================================ +# MODULE VERSIONING +# ============================================================================ + +# 1. Lire MAJOR.MINOR depuis fichier VERSION +if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION") + file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" BASE_VERSION) + string(STRIP "${BASE_VERSION}" BASE_VERSION) +else() + set(BASE_VERSION "0.1") + message(WARNING "No VERSION file found, using default: ${BASE_VERSION}") +endif() + +# 2. Calculer PATCH : nombre de commits Git +execute_process( + COMMAND git rev-list --count HEAD + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + OUTPUT_VARIABLE PATCH_COUNT + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_QUIET + RESULT_VARIABLE GIT_RESULT +) + +if(NOT GIT_RESULT EQUAL 0) + set(PATCH_COUNT "0") + message(WARNING "Git not available, PATCH set to 0") +endif() + +# 3. Calculer BUILD : hash des fichiers sources +file(GLOB_RECURSE MODULE_SOURCES + "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp" + "${CMAKE_CURRENT_SOURCE_DIR}/src/*.h" + "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h" +) + +# Concaténer contenu de tous les fichiers +set(SOURCES_CONTENT "") +foreach(SOURCE_FILE ${MODULE_SOURCES}) + file(READ ${SOURCE_FILE} FILE_CONTENT) + string(APPEND SOURCES_CONTENT ${FILE_CONTENT}) +endforeach() + +# Hash MD5 du contenu total +string(MD5 SOURCES_HASH "${SOURCES_CONTENT}") + +# Convertir hash hex en nombre décimal (4 premiers caractères) +string(SUBSTRING ${SOURCES_HASH} 0 4 BUILD_HEX) +# Calculer valeur numérique (modulo 10000 pour limiter à 4 chiffres) +math(EXPR BUILD_NUM "0x${BUILD_HEX} % 10000") + +# 4. Assembler version complète +set(MODULE_VERSION "${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}") + +message(STATUS "Module version: ${MODULE_VERSION}") +message(STATUS " BASE: ${BASE_VERSION} (from VERSION file)") +message(STATUS " PATCH: ${PATCH_COUNT} (git commits)") +message(STATUS " BUILD: ${BUILD_NUM} (sources hash)") + +# 5. Définir macro C++ pour accès au runtime +add_definitions(-DMODULE_VERSION="${MODULE_VERSION}") + +# ============================================================================ +# MODULE BUILD +# ============================================================================ + +# Inclure sources +file(GLOB_RECURSE TANK_SOURCES src/*.cpp) + +# Créer bibliothèque partagée (.so) +add_library(tank-module SHARED ${TANK_SOURCES}) + +# Configuration compilation +target_include_directories(tank-module PRIVATE include) +target_compile_features(tank-module PRIVATE cxx_std_20) + +# Sortie +set_target_properties(tank-module PROPERTIES + OUTPUT_NAME "tank" + PREFIX "" + SUFFIX ".so" +) + +message(STATUS "Building TankModule v${MODULE_VERSION}") +``` + +### Utilisation dans le Code C++ + +```cpp +// src/TankModule.h +#ifndef MODULE_VERSION +#define MODULE_VERSION "unknown" +#endif + +class TankModule : public IModule, public IModuleSave { +public: + std::string getVersion() const override { + return MODULE_VERSION; // Défini par CMake + } + + nlohmann::json serialize() override { + json data; + data["module_name"] = "tank"; + data["module_version"] = getVersion(); // "0.1.15.3847" + // ... reste de la sérialisation + return data; + } +}; +``` + +### Affichage au Runtime + +```cpp +void TankModule::initialize() { + LOG_INFO("TankModule v{} initializing...", getVersion()); +} +``` + +Sortie console : +``` +[INFO] TankModule v0.1.15.3847 initializing... +``` + +## Workflow de Développement + +### 1. Création Nouveau Module + +```bash +# Créer structure module +mkdir -p modules/new_module/src +cd modules/new_module + +# Créer fichier VERSION +echo "0.1" > VERSION + +# Créer CMakeLists.txt avec système versioning +# (copier template ci-dessus) +``` + +**Première compilation** : +```bash +cmake . && make +``` + +Sortie : +``` +-- Module version: 0.1.0.0 +-- BASE: 0.1 (from VERSION file) +-- PATCH: 0 (git commits) +-- BUILD: 0 (sources hash) +-- Building NewModule v0.1.0.0 +``` + +### 2. Développement Itératif + +**Scénario 1 : Modifier code sans commit** + +```bash +# Éditer src/NewModule.cpp +nano src/NewModule.cpp + +# Rebuild +make +``` + +Sortie : +``` +-- Module version: 0.1.0.4582 +-- PATCH: 0 (aucun commit) +-- BUILD: 4582 (hash sources a changé) +``` + +**Scénario 2 : Commit modifications** + +```bash +git add . +git commit -m "Add feature X" + +# Rebuild +make +``` + +Sortie : +``` +-- Module version: 0.1.1.4582 +-- PATCH: 1 (nouveau commit) +-- BUILD: 4582 (sources identiques au commit) +``` + +**Scénario 3 : Rebuild sans modification** + +```bash +# Rebuild immédiat +make +``` + +Sortie : +``` +-- Module version: 0.1.1.4582 + (version identique, aucun changement) +``` + +### 3. Release Mineure (Nouvelle Feature) + +```bash +# Bump MINOR version +echo "0.2" > VERSION + +# Commit +git add VERSION +git commit -m "Bump version to 0.2 (new feature: advanced tactics)" + +# Rebuild +cmake . && make +``` + +Sortie : +``` +-- Module version: 0.2.2.5123 +-- BASE: 0.2 (nouvelle version) +-- PATCH: 2 (commits depuis début projet) +-- BUILD: 5123 (hash actuel) +``` + +### 4. Release Majeure (Breaking Change) + +```bash +# Bump MAJOR version +echo "1.0" > VERSION + +git add VERSION +git commit -m "Release 1.0.0 - Stable API" + +cmake . && make +``` + +Sortie : +``` +-- Module version: 1.0.3.5123 +-- BASE: 1.0 (version stable) +-- PATCH: 3 (total commits) +-- BUILD: 5123 +``` + +## Comparaison de Versions + +### Dans le Système de Save + +Lors du chargement d'une save, comparaison des versions : + +```cpp +bool SaveSystem::loadModule(const std::string& moduleName) { + auto module = moduleSystem->getModule(moduleName); + + json moduleData = readJsonFile(modulePath); + std::string savedVersion = moduleData["module_version"]; + std::string currentVersion = module->getVersion(); + + if (savedVersion != currentVersion) { + LOG_WARN("Module {} version mismatch:", moduleName); + LOG_WARN(" Save version: {}", savedVersion); + LOG_WARN(" Current version: {}", currentVersion); + + // Analyser différences + VersionInfo saved = parseVersion(savedVersion); + VersionInfo current = parseVersion(currentVersion); + + if (saved.major != current.major) { + LOG_ERROR(" MAJOR version mismatch - likely incompatible!"); + return false; // Incompatibilité critique + } + else if (saved.minor != current.minor) { + LOG_WARN(" MINOR version mismatch - some features may differ"); + // Continuer avec warning + } + else if (saved.patch != current.patch) { + LOG_INFO(" PATCH version mismatch - minor changes only"); + // Sûr, juste bugfixes + } + else { + LOG_DEBUG(" BUILD version mismatch - dev builds differ"); + // Totalement sûr + } + } + + return module->deserialize(moduleData); +} +``` + +### Structure VersionInfo + +```cpp +struct VersionInfo { + int major; + int minor; + int patch; + int build; + + static VersionInfo parse(const std::string& versionStr) { + VersionInfo info; + std::sscanf(versionStr.c_str(), "%d.%d.%d.%d", + &info.major, &info.minor, &info.patch, &info.build); + return info; + } + + bool isCompatibleWith(const VersionInfo& other) const { + // Compatible si MAJOR identique + return major == other.major; + } + + bool hasBreakingChanges(const VersionInfo& other) const { + return major != other.major; + } +}; +``` + +## Gestion Multi-Modules + +### Script CMake Global + +Pour centraliser la logique de versioning, créer un fichier CMake réutilisable : + +```cmake +# cmake/ModuleVersioning.cmake + +function(setup_module_versioning) + # Lire VERSION + if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION") + file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" BASE_VERSION) + string(STRIP "${BASE_VERSION}" BASE_VERSION) + else() + set(BASE_VERSION "0.1") + endif() + + # Calculer PATCH + execute_process( + COMMAND git rev-list --count HEAD + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + OUTPUT_VARIABLE PATCH_COUNT + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_QUIET + RESULT_VARIABLE GIT_RESULT + ) + if(NOT GIT_RESULT EQUAL 0) + set(PATCH_COUNT "0") + endif() + + # Calculer BUILD + file(GLOB_RECURSE MODULE_SOURCES + "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp" + "${CMAKE_CURRENT_SOURCE_DIR}/src/*.h" + "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h" + ) + set(SOURCES_CONTENT "") + foreach(SOURCE_FILE ${MODULE_SOURCES}) + file(READ ${SOURCE_FILE} FILE_CONTENT) + string(APPEND SOURCES_CONTENT ${FILE_CONTENT}) + endforeach() + string(MD5 SOURCES_HASH "${SOURCES_CONTENT}") + string(SUBSTRING ${SOURCES_HASH} 0 4 BUILD_HEX) + math(EXPR BUILD_NUM "0x${BUILD_HEX} % 10000") + + # Assembler version + set(MODULE_VERSION "${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}" PARENT_SCOPE) + + # Log + message(STATUS "Module version: ${BASE_VERSION}.${PATCH_COUNT}.${BUILD_NUM}") +endfunction() +``` + +### Utilisation dans Module + +```cmake +# modules/tank/CMakeLists.txt +cmake_minimum_required(VERSION 3.20) +project(TankModule) + +# Importer fonction versioning +include(${CMAKE_SOURCE_DIR}/cmake/ModuleVersioning.cmake) + +# Setup version automatique +setup_module_versioning() + +# Définir macro +add_definitions(-DMODULE_VERSION="${MODULE_VERSION}") + +# ... reste du CMakeLists +``` + +## Best Practices + +### 1. Quand Bumper MAJOR ? + +**Situations justifiant MAJOR bump** : +- Changement format save incompatible +- Refonte API du module (signatures fonctions changent) +- Suppression de fonctionnalités existantes +- Changement architecture fondamentale + +**Exemple** : +```bash +# Avant : TankModule v0.8.x utilise grille 10x10 +# Après : TankModule v1.0.0 utilise grille 16x16 (incompatible) +echo "1.0" > VERSION +``` + +### 2. Quand Bumper MINOR ? + +**Situations justifiant MINOR bump** : +- Ajout nouveau type de tank/composant +- Nouvelle fonctionnalité (mode formation, tactiques AI) +- Amélioration significative sans breaking change + +**Exemple** : +```bash +# Ajout système de camouflage → 0.1 → 0.2 +echo "0.2" > VERSION +``` + +### 3. PATCH et BUILD sont Automatiques + +**Ne jamais modifier manuellement** : +- PATCH suit automatiquement les commits +- BUILD suit automatiquement les modifications code + +### 4. Versioning pour Tests + +En environnement de test, fixer une version stable : + +```cmake +if(DEFINED ENV{CI_BUILD}) + # Build CI : version fixe pour reproductibilité + set(MODULE_VERSION "0.0.0.0") +else() + # Build normal : versioning automatique + setup_module_versioning() +endif() +``` + +### 5. Affichage Version au Démarrage + +```cpp +void logModuleVersions() { + LOG_INFO("=== Module Versions ==="); + for (auto& module : moduleSystem->getAllModules()) { + LOG_INFO(" {}: v{}", module->getName(), module->getVersion()); + } + LOG_INFO("======================="); +} +``` + +Sortie : +``` +[INFO] === Module Versions === +[INFO] tank: v0.1.15.3847 +[INFO] economy: v0.2.8.1203 +[INFO] factory: v0.1.20.4512 +[INFO] transport: v0.1.5.982 +[INFO] ======================= +``` + +## Debugging avec Versions + +### Reproduire un Bug + +Si un bug est reporté avec une save : + +1. **Lire version du module dans la save** : +```bash +cat saves/abc123/server_1/tank.json | grep module_version +# "module_version": "0.1.15.3847" +``` + +2. **Retrouver commit correspondant** : +```bash +# PATCH = 15 commits +git log --oneline | head -n 15 | tail -n 1 +``` + +3. **Vérifier hash sources** : +```bash +# BUILD = 3847 correspond à un certain hash +# Comparer avec hashes de commits proches +``` + +4. **Checkout version exacte pour debugging** : +```bash +git checkout +cmake . && make +# Version devrait matcher ou être proche +``` + +### Logs de Version + +```cpp +void TankModule::initialize() { + LOG_INFO("TankModule v{} initializing", getVersion()); + LOG_DEBUG(" Compiled: {} {}", __DATE__, __TIME__); + LOG_DEBUG(" Compiler: {}", __VERSION__); +} +``` + +## Alternatives et Limitations + +### Alternative 1 : Semantic Versioning Manuel + +**Avantage** : Contrôle total sur versions +**Inconvénient** : Maintenance manuelle, oublis fréquents + +### Alternative 2 : Git Tags Only + +```cmake +execute_process( + COMMAND git describe --tags --always + OUTPUT_VARIABLE MODULE_VERSION +) +``` + +**Avantage** : Simple, suit git +**Inconvénient** : Nécessite tags, pas de granularité build + +### Limitation Actuelle : Hash Non-Déterministe + +Le hash des sources peut varier selon : +- Ordre de lecture des fichiers (filesystem dépendant) +- Encodage des fichiers +- Whitespace differences + +**Solution future** : Hash déterministe avec tri des fichiers et normalisation. + +## Migration depuis Système Existant + +Si des modules existants utilisent un autre système : + +```cmake +# Détecter ancien système +if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/version.txt") + file(READ "${CMAKE_CURRENT_SOURCE_DIR}/version.txt" OLD_VERSION) + message(WARNING "Found old version.txt, migrating to VERSION file") + + # Extraire MAJOR.MINOR + string(REGEX MATCH "^[0-9]+\\.[0-9]+" BASE_VERSION ${OLD_VERSION}) + file(WRITE "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" "${BASE_VERSION}") + + message(STATUS "Migration complete: ${OLD_VERSION} -> ${BASE_VERSION}.x.x") +endif() +``` + +## Références Croisées + +- `systeme-sauvegarde.md` : Utilisation des versions dans le système de save +- `architecture-modulaire.md` : Interface IModule, contraintes modules +- `claude-code-integration.md` : Optimisation builds pour développement AI + +## Exemples Complets + +### Module Complet avec Versioning + +Voir structure complète dans : +``` +modules/tank/ +├── VERSION # "0.1" +├── CMakeLists.txt # Setup versioning + build +├── src/ +│ ├── TankModule.cpp # Utilise MODULE_VERSION +│ └── Tank.cpp +└── include/ + └── TankModule.h # Déclare getVersion() +``` + +### Test Versioning + +```cpp +#ifdef TESTING +#include + +void testVersioning() { + TankModule module; + + std::string version = module.getVersion(); + assert(!version.empty()); + assert(version != "unknown"); + + // Parse version + VersionInfo info = VersionInfo::parse(version); + assert(info.major >= 0); + assert(info.minor >= 0); + assert(info.patch >= 0); + assert(info.build >= 0); + + std::cout << "Versioning test passed: " << version << std::endl; +} +#endif +``` diff --git a/docs/03-implementation/configuration/security-measures.md b/docs/03-implementation/configuration/security-measures.md new file mode 100644 index 0000000..738573f --- /dev/null +++ b/docs/03-implementation/configuration/security-measures.md @@ -0,0 +1,131 @@ +# Security Measures + +**Points 311-330 - Security Measures** - Server authority, anti-cheat, client prediction, psychological warfare + +## Server Authority + +### Authoritative Design +**Server contrôle toute la simulation** : + +- **Server Authority** : Simulation, logique métier, état de jeu complets +- **Client Responsibilities** : Rendu, interface, cache local uniquement +- **Zero Game Logic** : Aucune logique métier côté client +- **Bandwidth** : Clients reçoivent state updates, n'envoient que commands + +### Mode-Based Security +**Sécurité adaptative selon contexte** : + +```cpp +// Solo Mode +- **Local config override** autorisé +- **Cheat-friendly** pour expérimentation + +// Multiplayer Mode +- **Server autoritaire** sur toutes les configs +- **Anti-cheat automatique** via validation +- **Zero tolerance** pour modifications +``` + +## Anti-cheat System + +### Anti-cheat Psychologique +**Stratégie : Cheat attempts → "bugs" simulés progressifs** + +```cpp +class AntiCheatPsycho { + void onCheatDetected(CheatType type) { + switch(type) { + case SPEED_HACK: + simulateRandomLag(50ms, 500ms); + break; + case RESOURCE_HACK: + simulateVisualGlitches(tanks, 5%); + break; + case DAMAGE_HACK: + simulateDesync(movement, 2%); + break; + } + } +}; +``` + +### Design-Based Anti-cheat +- **Anti-cheat naturel** : Server authoritative pour toute logique métier +- **Anti-cheat par design** : Architecture empêche cheating structurellement +- **Anti-cheat automatique** : Validation intégrée dans l'architecture + +## Client Prediction System + +### V1 vs V2 Prediction Architecture + +#### V1 : Thin Client (No Prediction) +- **Server authoritative** : Toute validation côté serveur +- **Latence perceptible** : 50-150ms délai action/feedback +- **Sécurité maximale** : Zero logique côté client +- **Simplicité** : Une seule source de vérité + +#### V2 : Shared Logic Prediction +- **Logique métier partagée** : Client/serveur utilisent même code +- **Prédiction locale** : Feedback instantané côté client +- **Réconciliation serveur** : Validation authoritative maintenue +- **Latence zéro perçue** : Performance optimale + +### Migration Progressive V1→V2 +**Code adaptable sans réécriture** : + +```cpp +// Code adaptable V1/V2 sans réécriture +if (config.enable_v2_prediction) { + // V2: Client prediction + server validation +} else { + // V1: Server authoritative (fallback sûr) +} +``` + +### Performance Targets +- **V1 Client Target** : 30+ fps stable +- **V2 Client Target** : 60+ fps avec prediction +- **V2 Network** : 30ms server, 0ms perceived client + +## Psychological Warfare + +### Anti-cheat Psychologique Avancé +**Guerre psychologique contre cheaters** : + +- **Bugs simulés progressifs** : Dégradation subtile performance +- **Faux positifs contrôlés** : Doute sur efficacité cheats +- **Désynchronisation sélective** : Chaos apparent pour cheaters +- **Retention légitimes** : Joueurs normaux non affectés + +### Stratégies Comportementales +- **SPEED_HACK** → Random lag simulation (50-500ms) +- **RESOURCE_HACK** → Visual glitches sur assets (5% tanks) +- **DAMAGE_HACK** → Movement desync (2% déviation) +- **Escalation progressive** : Intensité augmente avec persistance + +## Mode-Based Security + +### Development Mode +- **Config unrestricted** : Toute modification autorisée +- **Debug tools** : Access complet aux outils développement +- **No anti-cheat** : Liberté totale pour testing + +### Solo Mode +- **Modding friendly** : Config system disponible +- **Local authority** : Player contrôle paramètres +- **Experimentation** : Cheat autorisé pour fun + +### Multiplayer Mode +- **Server authority** : Contrôle total serveur +- **Anti-cheat active** : Système complet activé +- **Zero tolerance** : Aucune modification autorisée +- **Validation stricte** : Tous inputs validés + +## Sources + +**Documentation originale :** +- `docs/global/architecture-technique.md` - Server Authority design +- `docs/toCheck/architecture-modulaire.md` - Anti-cheat psychologique +- `docs/architecture-technique.md` - Client prediction V1/V2 + +**Points couverts :** 20 spécifications sécurité détaillées \ No newline at end of file diff --git a/docs/03-implementation/configuration/transport-economic-system.md b/docs/03-implementation/configuration/transport-economic-system.md new file mode 100644 index 0000000..9783e42 --- /dev/null +++ b/docs/03-implementation/configuration/transport-economic-system.md @@ -0,0 +1,549 @@ +# Rapport : Système Transport & Économique + +## 🚛 Architecture Transport System + +### Transport Mode Hierarchy + +**Selection Cascade basée sur optimisation économique pure** : + +``` +Decision Tree (Cost Optimization) - Points 90-95: +1. Volume ≥ 1000t + Port Access → Ship (0.10€/kg) +2. Else + Rail Access → Train (0.50€/kg) +3. Else + Airport Access → Air (2.00€/kg) +4. Else → Truck (5.00€/kg) + +Storage Cost: €0.02/kg/day +Delivery Times: Ship 14j, Train 3j, Air 1j, Truck 2j +Ship Volume Threshold: ≥1000 tonnes minimum + +Pas de facteur urgency - pure economic optimization +``` + +#### Justification Économique +- **Coût maritime** : 50x moins cher que camion (économies d'échelle massives) +- **Seuil volume** : 1000 tonnes nécessaire pour rentabiliser navire +- **Infrastructure binaire** : Access ou pas access, pas de gradients +- **Simplification décisionnelle** : Arbre de décision clair pour IA + +### Infrastructure Access Binary + +**Propriétés géographiques des entreprises** : + +```cpp +struct CompanyLocation { + bool hasPortAccess = false; // Access maritime + bool hasRailAccess = false; // Access ferroviaire + bool hasAirportAccess = false; // Access aérien + bool alwaysTruckAccess = true; // Camion toujours disponible + + float transportMultiplier() { + // Geographic competitive advantage + return hasPortAccess ? 0.10f : + hasRailAccess ? 0.50f : + hasAirportAccess ? 2.00f : 5.00f; + } +}; +``` + +#### Avantage Concurrentiel Géographique +- **Coastal locations** : Avantage économique structurel +- **Inland accessible par rail** : Compromis coût/accessibilité +- **Remote locations** : Coût transport élevé = premium prices +- **Strategic positioning** : Infrastructure access = competitive moat + +## 📊 Market Mechanics + +### Order System (Passes Économiques) + +**Phases économiques séquentielles** : + +``` +Economic Cycle (24h): +1. Offer Phase (6h): Producers submit sell orders +2. Demand Phase (6h): Consumers submit buy orders +3. Market Clearing (1h): Price discovery & matching +4. Transport Assignment (1h): Mode selection per transaction +5. Execution Phase (10h): Delivery + payment processing + +Order Stacking Strategy: +├─ Multiple sellers combine orders during Offer Phase +├─ Volume aggregation unlock ship transport thresholds +├─ Waiting mechanism incentivizes collaboration +├─ Economic pressure creates natural cooperation +``` + +#### Benefits Système Passes +- **Price discovery efficient** : Concentration temporelle des échanges +- **Volume optimization** : Incitation à collaboration pour seuils +- **Market transparency** : Informations disponibles pour tous +- **Strategic timing** : Players peuvent anticiper cycles + +### Dynamic Pricing Mechanism + +**Formation des prix multi-facteurs** : + +```cpp +class PriceFormation { + float calculatePrice(Good good, Region region) { + float basePrice = supplyDemandEquilibrium(good); + float transportPremium = calculateTransportCosts(region); + float scarcityMultiplier = getScarcityPressure(good, region); + float regionGradient = getRegionalPriceGradient(good, region); + + return basePrice * (1 + transportPremium + scarcityMultiplier + regionGradient); + } +}; +``` + +#### Price Formation Components + +##### Base Price (Supply/Demand Equilibrium) +- **Market clearing price** : Intersection offre/demande +- **Global reference** : Prix de base mondial +- **Volatility buffer** : Mécanismes anti-manipulation + +##### Transport Cost Limits (Buyer-Defined) +- **Maximum transport %** : Buyers set acceptable transport cost ratio +- **Example** : "Transport max 15% of goods value" +- **Market filtering** : Orders rejected if transport too expensive +- **Geographic arbitrage limits** : Natural price convergence mechanism + +##### Scarcity Premium (Desperation Bidding) +- **Stock depletion** : Companies with low inventory bid premium +- **Regional shortages** : Isolated regions pay survival premiums +- **Urgent orders** : Rush delivery commands price multipliers +- **Market psychology** : Fear of shortage drives irrational bidding + +##### Regional Price Gradients (Geographic Arbitrage) +``` +Price Examples (Iron): +├─ Coastal Region: 10€/kg (baseline + ship transport) +├─ Rail Accessible: 11€/kg (baseline + rail premium) +├─ Airport Only: 20€/kg (baseline + air premium) +├─ Remote Truck: 50€/kg (baseline + truck premium + scarcity) +``` + +## 🏗️ Storage & Inventory System + +### Company Storage Strategy + +**Adaptive Inventory Management basée sur niveaux de stock** : + +```cpp +enum InventoryStrategy { + DESPERATE, // Stock < 20% → Premium bidding + NORMAL, // Stock 20-50% → Market price buying + CAUTIOUS, // Stock 50-80% → Opportunistic buying only + OVERSUPPLIED // Stock > 80% → Stop purchasing +}; + +class InventoryManager { + PurchaseDecision evaluate(float stockLevel, float marketPrice) { + if(stockLevel < 0.20f) return {true, marketPrice * 1.5f}; // Desperate + if(stockLevel < 0.50f) return {true, marketPrice}; // Normal + if(stockLevel < 0.80f) return {false, marketPrice * 0.8f}; // Opportunistic + return {false, 0.0f}; // Stop buying + } +}; +``` + +#### Inventory Trade-offs +- **Large inventory** : Security vs storage costs (€0.02/kg/day) +- **Small inventory** : Lower costs vs supply chain risk +- **Timing optimization** : Buy during market oversupply +- **Geographic arbitrage** : Coastal storage → Inland distribution + +### Bulk Purchase Cycles + +**Natural market pulse patterns** : + +``` +Market Cycle Pattern: +1. Multiple companies hit 20% stock simultaneously +2. Competing desperate bids create price spikes +3. Large combined volumes enable ship transport unlock +4. Price normalization as inventory restored +5. Market oversupply as orders arrive simultaneously +6. Price correction downward +7. Cycle repeats with natural frequency +``` + +#### Emergent Behavior +- **Synchronized depletion** : Similar consumption patterns +- **Bidding wars** : Scarcity-driven competition +- **Transport optimization** : Volume consolidation benefits +- **Natural cycles** : Self-organizing market rhythms + +## 💼 Trading Companies + +### Business Models Emergents + +#### Pure Arbitrage Strategy +```cpp +class ArbitrageTrader { + Strategy coastalToInland() { + // 1. Buy coastal (cheap ship transport access) + // 2. Store in strategic inland locations + // 3. Sell to remote regions (premium prices) + // Profit = Price differential - storage - transport + return {buyCoastal, storeStrategic, sellRemote}; + } +}; +``` + +#### Transport Optimization Strategy +```cpp +class TransportOptimizer { + Strategy aggregateSmallProducers() { + // 1. Aggregate small producer outputs + // 2. Combine orders to unlock ship thresholds + // 3. Share transport savings with producers + // Profit = Transport efficiency gains + return {aggregateOrders, unlockShipping, shareGains}; + } +}; +``` + +#### Market Making Strategy +```cpp +class MarketMaker { + Strategy stabilizeSupply() { + // 1. Buffer supply volatility with inventory + // 2. Provide reliable supply to consumers + // 3. Smooth price fluctuations + // Profit = Stability service premium + return {bufferVolatility, guaranteeSupply, chargePremium}; + } +}; +``` + +### Specialization Types + +#### Geographic Specialists +- **Regional expertise** : Deep knowledge specific areas +- **Infrastructure relationships** : Port/rail access deals +- **Local market intelligence** : Cultural/regulatory knowledge +- **Logistics optimization** : Region-specific transport solutions + +#### Commodity Specialists +- **Deep vertical knowledge** : Single commodity expertise +- **Quality assessment** : Grading, certification, standards +- **Technical logistics** : Specialized handling, storage +- **Market prediction** : Supply/demand pattern expertise + +#### Logistics Specialists +- **Transport optimization** : Multi-modal route planning +- **Volume consolidation** : Order aggregation expertise +- **Infrastructure leverage** : Maximum transport efficiency +- **Timing coordination** : Economic cycle optimization + +#### Financial Specialists +- **Risk management** : Hedging, insurance, derivatives +- **Futures markets** : Long-term contract management +- **Credit facilities** : Financing for trade operations +- **Currency hedging** : International trade protection + +## 🌍 Geographic Economics + +### Natural Economic Geography Evolution + +#### Coastal Concentration Dynamics +``` +Market Forces Sequence: +1. Initial coastal rush (transport cost advantages) +2. Land price premiums develop (scarcity) +3. Congestion costs emerge (infrastructure limits) +4. Port capacity bottlenecks (throughput limits) +5. Labor shortage premiums (competition) +6. Economic equilibrium reached (cost parity) +``` + +#### Regional Specialization Patterns +```cpp +enum RegionType { + RESOURCE_EXTRACTION, // Fixed by geological deposits + MANUFACTURING_HUB, // Transport cost optimization + TRADING_CENTER, // Infrastructure convergence + CONSUMER_MARKET // Population concentration +}; + +class RegionalSpecialization { + RegionType determineOptimalFocus(Region region) { + if(hasNaturalResources(region)) return RESOURCE_EXTRACTION; + if(hasTransportHub(region)) return TRADING_CENTER; + if(hasManufacturingCosts(region)) return MANUFACTURING_HUB; + return CONSUMER_MARKET; + } +}; +``` + +### Infrastructure Investment Economics + +#### Economic Justification Model +```cpp +class InfrastructureROI { + bool justifyRailInvestment(Region region) { + float currentTransportCosts = calculateTruckCosts(region); + float projectedVolume = estimateTradeVolume(region); + float railConstructionCost = calculateRailCost(region); + float railOperatingCost = calculateRailOperations(region); + + float savings = (currentTransportCosts - railOperatingCost) * projectedVolume; + float paybackPeriod = railConstructionCost / savings; + + return paybackPeriod < MAX_PAYBACK_YEARS; + } +}; +``` + +#### Investment Triggers +- **Sustained high transport costs** : Market signals infrastructure need +- **Volume thresholds reached** : Economies of scale justify investment +- **Regional economic pressure** : Political/social demand for development +- **Competitive necessity** : Rival regions gaining advantages + +### Infrastructure Impact Simulation +``` +Pre-Rail Region: +├─ Truck transport only (5.00€/kg) +├─ High consumer prices +├─ Limited economic activity +├─ Population outmigration + +Post-Rail Region: +├─ Rail transport available (0.50€/kg) +├─ 90% transport cost reduction +├─ Economic boom, new businesses +├─ Population influx, urbanization +``` + +## ⚙️ Implementation Details + +### Economic Agents (Player-Agnostic Design) + +**Tous les entités = agents économiques** : + +```cpp +class EconomicAgent { +public: + virtual void submitOrders() = 0; + virtual void processTransactions() = 0; + virtual void updateStrategy() = 0; + + // No special player privileges + // Pure economic simulation +}; + +class ProductionCompany : public EconomicAgent { ... }; +class ConsumptionCompany : public EconomicAgent { ... }; +class TransportCompany : public EconomicAgent { ... }; +class TradingCompany : public EconomicAgent { ... }; +class InfrastructureInvestor : public EconomicAgent { ... }; +``` + +#### Agent Equality Principle +- **No player privileges** : Tous agents soumis aux mêmes règles +- **Pure simulation** : Économie émergente sans intervention arbitraire +- **Fair competition** : Success basé sur strategy, pas status +- **Realistic behavior** : AI agents comportement économique rationnel + +### Market Clearing Algorithm + +**Order Matching Process** : + +```cpp +class MarketClearingEngine { + void processMarketCycle() { + // 1. Collect all orders from economic phases + auto sellOrders = collectSellOrders(); + auto buyOrders = collectBuyOrders(); + + // 2. Sort for optimal matching + std::sort(sellOrders.begin(), sellOrders.end(), priceAscending); + std::sort(buyOrders.begin(), buyOrders.end(), priceDescending); + + // 3. Match orders within transport cost limits + auto matches = matchOrdersWithTransportLimits(sellOrders, buyOrders); + + // 4. Apply volume consolidation for shipping + auto consolidatedMatches = applyVolumeConsolidation(matches); + + // 5. Calculate optimal transport modes + for(auto& match : consolidatedMatches) { + match.transportMode = selectOptimalTransport(match); + } + + // 6. Execute deliveries with realistic time delays + scheduleDeliveries(consolidatedMatches); + } +}; +``` + +#### Algorithm Benefits +- **Economic efficiency** : Optimal price discovery +- **Transport optimization** : Automatic mode selection +- **Volume benefits** : Consolidation incentives +- **Realistic timing** : Delivery delays based on transport mode + +### Configuration Parameters + +**Système de configuration économique** : + +```json +{ + "transport": { + "ship_threshold_tonnes": 1000, + "ship_cost_per_kg": 0.10, + "train_cost_per_kg": 0.50, + "air_cost_per_kg": 2.00, + "truck_cost_per_kg": 5.00, + "delivery_time_ship_days": 14, + "delivery_time_train_days": 3, + "delivery_time_air_days": 1, + "delivery_time_truck_days": 2 + }, + "storage": { + "cost_per_kg_per_day": 0.02, + "urgent_stock_threshold": 0.20, + "normal_stock_threshold": 0.50, + "oversupplied_threshold": 0.80, + "max_storage_capacity_multiplier": 10.0 + }, + "market": { + "transport_cost_limit_percentage": 0.15, + "order_stacking_wait_days": 7, + "economic_phase_duration_hours": 6, + "price_volatility_damping": 0.1, + "scarcity_premium_multiplier": 2.0 + }, + "infrastructure": { + "rail_construction_cost_per_km": 1000000, + "port_construction_cost": 50000000, + "airport_construction_cost": 100000000, + "max_infrastructure_payback_years": 15 + } +} +``` + +#### Configuration Benefits +- **Tunable economics** : Adjust economic parameters for gameplay +- **Progressive complexity** : Start simple, add sophistication +- **A/B testing** : Compare different economic models +- **Regional variation** : Different parameters per geographic region + +## 🎯 System Benefits & Integration + +### Economic Realism Achievements + +#### Natural Geographic Specialization +- **Resource-based clustering** : Mining near deposits +- **Manufacturing optimization** : Transport cost minimization +- **Trading hub emergence** : Infrastructure convergence points +- **Realistic urban development** : Economic forces drive settlement patterns + +#### Infrastructure ROI Modeling +- **Investment justification** : Economic case for infrastructure +- **Regional transformation** : Infrastructure changes economic landscape +- **Competitive dynamics** : Regions compete for transport access +- **Long-term planning** : Infrastructure decisions have lasting impact + +#### Market Cycle Emergence +- **Natural rhythms** : Supply/demand cycles self-organize +- **Price discovery** : Efficient market mechanisms +- **Arbitrage opportunities** : Geographic and temporal price differences +- **Risk/reward balance** : Higher profits require higher risks + +### Emergent Complexity Demonstration + +#### Trading Company Evolution +- **Business model innovation** : New strategies emerge from economic pressure +- **Specialization development** : Companies find profitable niches +- **Market efficiency improvement** : Traders reduce transaction costs +- **Economic ecosystem richness** : Multiple business models coexist + +#### Regional Economic Development +- **Coastal advantage phase** : Early transport cost benefits +- **Infrastructure investment phase** : Economic pressure drives development +- **Economic equilibrium phase** : Costs equalize across regions +- **Competitive specialization phase** : Regions find comparative advantages + +#### Supply Chain Sophistication +- **Simple direct trade** → **Multi-hop arbitrage** → **Complex logistics networks** +- **Individual transactions** → **Volume consolidation** → **Integrated supply chains** +- **Local markets** → **Regional trade** → **Global economic integration** + +### Simple Implementation Strategy + +#### Clear Decision Trees +```cpp +TransportMode selectTransport(Order order, Route route) { + if(order.volume >= 1000 && route.hasPortAccess()) return SHIP; + if(route.hasRailAccess()) return TRAIN; + if(route.hasAirportAccess()) return AIR; + return TRUCK; +} +``` + +#### Binary Infrastructure Access +- **No gradients** : Access or no access, simple boolean +- **Clear competitive advantage** : Infrastructure = economic moat +- **Easy AI reasoning** : Simple rules for AI decision-making +- **Scalable complexity** : Add infrastructure types without algorithm changes + +#### Modular Economic Components +```cpp +// Easy integration with existing architecture +class TransportModule : public IModule { ... }; +class TradingModule : public IModule { ... }; +class InfrastructureModule : public IModule { ... }; +class MarketModule : public IModule { ... }; +``` + +### Scalability Architecture + +#### Progressive Sophistication +- **Phase 1** : Basic transport cost differences +- **Phase 2** : Order stacking and volume optimization +- **Phase 3** : Trading companies and arbitrage +- **Phase 4** : Infrastructure investment and regional development +- **Phase 5** : Complex economic simulation (Victoria 3-level) + +#### Performance Scaling +- **Local decisions** : Transport mode selection (real-time) +- **Regional coordination** : Market clearing (hourly) +- **Economic simulation** : Complex modeling (daily) +- **Infrastructure planning** : Long-term investment (monthly) + +### Player-Agnostic Benefits + +#### Pure Economic Simulation +- **No artificial advantages** : Players compete on equal terms +- **Emergent strategies** : Success comes from economic insight +- **Educational value** : Players learn real economic principles +- **Sandbox flexibility** : Multiple valid approaches to success + +#### AI Agent Integration +- **Consistent behavior** : All agents follow same economic rules +- **Realistic competition** : AI competitors use rational strategies +- **Market depth** : Many agents create liquid markets +- **Economic ecosystem** : Rich environment for player interaction + +--- + +## Conclusion + +Le système transport & économique crée une **simulation économique réaliste** où : + +- **Geographic advantages** émergent naturellement des coûts de transport +- **Business models sophistiqués** évoluent des pressions économiques +- **Infrastructure investment** suit la logique économique ROI +- **Market dynamics** créent cycles et opportunités réalistes + +**Ready for integration** dans l'architecture modulaire : +- **ProductionModule** : Interface avec transport costs +- **TradingModule** : Business logic des trading companies +- **InfrastructureModule** : Investment et construction logic +- **MarketModule** : Economic phases et price discovery + +**Résultat** : **Economic simulation depth** comparable aux meilleurs strategy games, avec **implementation simplicity** compatible Claude Code development ! 🚛💰🏗️ \ No newline at end of file diff --git a/docs/03-implementation/systemes-techniques.md b/docs/03-implementation/systemes-techniques.md new file mode 100644 index 0000000..2f9cc6a --- /dev/null +++ b/docs/03-implementation/systemes-techniques.md @@ -0,0 +1,98 @@ +# Systèmes techniques + +## Tile System + +### Superficies +- **Océan** : 362 000 000 000 m² +- **Total** : 510 000 000 000 m² +- **Terre** : 148 000 000 000 m² (118.4 Go) +- **Urbain** : 4 440 000 000 m² (3.552 Go) + +### Référence Minecraft +- MC 256x256 = 3 540 ko + +## Gestion mémoire + +### Game Chunk max DD Absolue pire cas (256x256) +- **Land** : 131 ko +- **Ressources** : 393 ko +- **Build** : 459 ko +- **Roof** : 131 ko +- **Effect** : 131 ko +- **Total** : 1 245 ko + +### Game Chunk RAM (256x256) +- **Land** : 131 ko +- **Ressources** : 655 ko +- **Build** : 720 ko +- **Roof** : 131 ko +- **Effect** : 131 ko +- **Total** : 1 768 ko + +## Architecture Multi-Échelle des Chunks + +### Principe de Design +Différents types de données utilisent différentes résolutions de chunks selon leur granularité naturelle et leurs besoins de performance. + +### Hiérarchie des Échelles + +#### Chunk 512x512 - Terrain de Base +**Usage** : Données homogènes sur grandes zones +- **landId** : 16b - Texture de la tile (potentiel modificateur) DD/Ram +- **roofId** : 16b - Identification toitures/couverture sol +- **Justification** : Terrain change peu, grandes zones homogènes +- **Mémoire** : Toujours en RAM (données de base) + +#### Chunk 256x256 - Structures et Bâtiments +**Usage** : Bâtiments et constructions moyennes/grandes +- **buildingPtr** : 32b "DD"/Ram +```cpp +{ + BuildingId : 32b DD/Ram + Collision : 4b Ram + PV : 20b DD(24b)/Ram +} +``` +- **Justification** : Bâtiments ont taille intermédiaire, besoin résolution moyenne +- **Mémoire** : Chargement à la demande + +#### Chunk 128x128 - Effets et Détails Fins +**Usage** : Effets visuels, particules, détails haute fréquence +- **effectId** : 16b +- **Justification** : Effets nécessitent granularité fine pour précision +- **Mémoire** : Streaming selon proximité joueur + +#### Chunk 64x64 - Gameplay Principal +**Usage** : Simulation de base, FOW, navigation (documenté dans map-system.md) +- **Justification** : Échelle optimale pour mécanique Factorio-like +- **Mémoire** : Core gameplay, chargement prioritaire + +### Système Ressources (Indépendant) +**ResourcePatches** : Formes libres non-alignées sur chunks (78x53 exemple) +- **Justification** : Gisements naturels ne respectent pas grilles artificielles +- **Documentation** : Détails complets dans map-system.md +- **Mémoire** : Chargement selon exploration et exploitation + +### Avantages Architecture Multi-Échelle +- **Performance optimisée** : Chaque donnée à sa résolution naturelle +- **Mémoire efficace** : Granularité adaptée aux besoins d'accès +- **Scaling intelligent** : Pas de sur-échantillonnage ni sous-échantillonnage +- **Maintenance** : Systèmes indépendants, modifications isolées + +## Stack technique + +### Langages de performance +- **C++ / C / ASM** pour performance critique +- **Justification** : Simulation temps réel complexe + milliers d'unités +- **Compromise** : Complexité dev acceptable vs performance requirements + +### Optimisations performance + +#### Adaptive Tick Rate +- **Normal** : 60 TPS +- **Sous charge** : 15 TPS +- **Principe** : Dégradation gracieuse selon la charge + +#### Queue Systems +- Batch processing pour opérations coûteuses +- Future scaling : clustering dynamique per module \ No newline at end of file diff --git a/docs/03-implementation/testing-strategy.md b/docs/03-implementation/testing-strategy.md new file mode 100644 index 0000000..ac4df4f --- /dev/null +++ b/docs/03-implementation/testing-strategy.md @@ -0,0 +1,214 @@ +# Testing Strategy - Warfactory + +**Philosophy** : Testing optimisé pour développement Claude Code avec modules autonomes + +## Points 42-44 : Testing & Validation Strategy + +### Point 42 : Unit Tests Intégrés (`#ifdef TESTING`) + +**Validation autonome intégrée aux modules :** + +```cpp +class TankModule : public IModule { + json process(const json& input) override { + // Core tank logic + auto result = processTankBehavior(input); + + #ifdef TESTING + // Validation autonome intégrée + validateInputs(input); + validateState(); + validateOutputs(result); + #endif + + return result; + } + + #ifdef TESTING + void runSelfTests() { + // Tests unitaires intégrés au module + testMovement(); + testTargeting(); + testCombat(); + } + +private: + void validateInputs(const json& input) { + assert(input.contains("position")); + assert(input.contains("target")); + assert(input["health"].get() >= 0.0f); + } + + void validateState() { + assert(currentHealth >= 0.0f); + assert(position.isValid()); + assert(ammunition >= 0); + } + + void validateOutputs(const json& output) { + assert(output.contains("status")); + assert(output.contains("position")); + assert(output.contains("actions")); + } + #endif +}; +``` + +**Build integration :** +```cmake +# Debug builds enable testing +if(CMAKE_BUILD_TYPE STREQUAL "Debug") + target_compile_definitions(tank PRIVATE TESTING) +endif() + +# Test executable +add_executable(tank-test tests/tank_test.cpp src/TankModule.cpp) +target_compile_definitions(tank-test PRIVATE TESTING) +``` + +### Point 43 : Standalone Testing + +**Test modules sans engine complet :** + +```cpp +// tests/tank_test.cpp +#include "../src/TankModule.h" + +int main() { + TankModule tank; + + // Initialize with test config + json config = { + {"health", 100}, + {"ammunition", 50}, + {"position", {10, 20}} + }; + tank.initialize(config); + + // Run self-tests + #ifdef TESTING + tank.runSelfTests(); + #endif + + // Test specific behaviors + json input = { + {"command", "move"}, + {"target_position", {15, 25}}, + {"health", 100} + }; + + auto result = tank.process(input); + + // Verify output + assert(result["status"] == "moving"); + assert(result.contains("position")); + + std::cout << "✅ All tank tests passed!" << std::endl; + return 0; +} +``` + +**Execution autonome :** +```bash +cd modules/tank/ +cmake . && make tank-test +./tank-test # Exécute tests sans infrastructure +``` + +### Point 44 : Testing Strategy AI-Optimized + +**Philosophy Claude Code-friendly :** + +#### Simple Tests Philosophy +- **No complex infrastructure** : Tests sans setup lourd +- **Minimal dependencies** : JSON in/out uniquement +- **Quick feedback** : <5 secondes pour iteration loops Claude +- **Readable by AI** : Code test compréhensible par IA + +#### Module Isolation Testing +```cpp +// ✅ GOOD - Simple, isolated test +void testTankMovement() { + TankModule tank; + json input = {{"command", "move"}, {"target", {10, 10}}}; + auto result = tank.process(input); + assert(result["status"] == "moving"); +} + +// ❌ BAD - Complex infrastructure required +void testTankInCompleteGameWorld() { + GameEngine engine; + MapSystem map; + NetworkManager network; + // 100+ lines setup... +} +``` + +#### AI Development Workflow +```bash +# Claude Code workflow optimized +1. Edit module → Save +2. Run tests → Instant feedback +3. Iterate → 5-second cycles + +# Traditional workflow (avoid) +1. Edit code → Rebuild entire project → Setup test environment → Run tests → 5-10 minutes +``` + +#### Testing Patterns Claude-Friendly + +**Input/Output Testing :** +```cpp +struct TestCase { + std::string name; + json input; + json expected_output; +}; + +std::vector tankTests = { + {"movement", {{"cmd", "move"}}, {{"status", "moving"}}}, + {"combat", {{"cmd", "fire"}}, {{"status", "firing"}}}, + {"damaged", {{"health", 10}}, {{"status", "critical"}}} +}; + +void runAllTests() { + for(auto& test : tankTests) { + auto result = tank.process(test.input); + assert(result == test.expected_output); + std::cout << "✅ " << test.name << " passed" << std::endl; + } +} +``` + +**Configuration-Driven Testing :** +```json +// tests/tank_test_config.json +{ + "test_cases": [ + { + "name": "basic_movement", + "input": {"command": "move", "target": [10, 10]}, + "expected": {"status": "moving", "eta": 5} + }, + { + "name": "low_health_behavior", + "input": {"health": 15, "command": "attack"}, + "expected": {"status": "retreating"} + } + ] +} +``` + +## Architecture Benefits + +**Development Velocity :** +- **5-second iteration** : Edit → Test → Feedback +- **Claude optimization** : IA comprend tests facilement +- **Zero infrastructure** : Pas setup complexe +- **Parallel development** : Multiple modules testés simultanément + +**Quality Assurance :** +- **Module isolation** : Bugs localisés, pas cascade +- **Autonomous validation** : Modules self-validate via `#ifdef TESTING` +- **Quick regression detection** : Tests rapides détectent régressions +- **AI-readable failures** : Error messages clairs pour Claude Code \ No newline at end of file diff --git a/docs/04-reference/INTEGRATION-MASTER-LIST.md b/docs/04-reference/INTEGRATION-MASTER-LIST.md new file mode 100644 index 0000000..68ba3db --- /dev/null +++ b/docs/04-reference/INTEGRATION-MASTER-LIST.md @@ -0,0 +1,395 @@ +# INTEGRATION MASTER LIST + +Complete technical specifications catalog for the Warfactory project. + +## Global Architecture Overview + +### System Orchestration Flow +``` +MainServer Process: +├── CoordinationModule (Global Orchestrator) +│ ├── Loads gameconfig.json via IDataTree +│ ├── Launches local IEngine + modules +│ └── Launches remote servers + engines +├── Local IEngine (manages local modules) +│ ├── IModuleSystem (execution strategy) +│ └── Local Modules (.so files) +└── Remote Servers (launched by coordination) + ├── Remote IEngine (manages remote modules) + ├── IModuleSystem (execution strategy) + └── Remote Modules (.so files) +``` + +### Startup Sequence +1. **MainServer** starts and launches **CoordinationModule** +2. **CoordinationModule** calls `startNewGame("gameconfig.json")` +3. **Config Loading**: IDataTree loads and parses gameconfig.json +4. **Deployment Analysis**: Parse deployment section to determine module topology +5. **Local Deployment**: Deploy modules with `target: "local"` to local IEngine +6. **Remote Deployment**: Launch remote servers and deploy modules with `target: "server:IP"` +7. **Synchronization**: All modules receive their configuration via `setConfiguration()` +8. **Game Ready**: Return control to user interface + +### Module Lifecycle with New Configuration System +```cpp +// Old way (DEPRECATED) +module->initialize(json_config, io, scheduler); + +// New way (CURRENT) +const IDataNode& config = configTree->getNode("modules/production"); +module->setConfiguration(config, io, scheduler); // const ref, no copies + +// Health monitoring +json health = module->getHealthStatus(); +// Returns: {"status": "healthy", "last_process_time_ms": 1.2, "memory_usage_mb": 45} +``` + +## Core Interface System + +### Engine Interfaces (IMMUTABLE) +- **IEngine**: Engine orchestration, module loading, client/coordinator socket management +- **IModuleSystem**: Execution strategy + task scheduling (inherits ITaskScheduler) +- **IModule**: Pure business logic + pub/sub communication + task delegation (**BREAKING CHANGES**) +- **IIO**: Pull-based pub/sub with low-frequency batching and health monitoring +- **ITaskScheduler**: Task delegation interface for module → execution system + +### Configuration System (IMMUTABLE) +- **IDataTree**: Configuration tree container with manual hot-reload capabilities +- **IDataNode**: Hierarchical data nodes with pattern matching and property queries (**const methods**) +- **DataTreeFactory**: Factory pattern for flexible data source creation + +### Coordination System (NEW) +- **ICoordinationModule**: Global system orchestrator and main game lifecycle manager + +## GameConfig.json Architecture + +### Central Configuration System +The entire game system is configured through a single **`gameconfig.json`** file that serves as the master configuration: + +```json +{ + "game": { + "name": "Warfactory Game Session", + "version": "1.0.0", + "save_path": "./saves/game_001" + }, + "deployment": { + "modules": [ + { + "id": "production_main", + "type": "ProductionModule", + "path": "./modules/production.so", + "target": "local", + "config_path": "modules/production" + }, + { + "id": "economy_central", + "type": "EconomyModule", + "path": "./modules/economy.so", + "target": "server:192.168.1.100:8080", + "config_path": "modules/economy" + }, + { + "id": "tank_combat", + "type": "TankModule", + "path": "./modules/tank.so", + "target": "cluster:combat_nodes", + "config_path": "modules/tank" + } + ] + }, + "modules": { + "production": { + "frequency": "60Hz", + "belt_speed": 2.5, + "inserter_capacity": 12 + }, + "economy": { + "frequency": "0.1Hz", + "inflation_rate": 0.02, + "market_volatility": 0.15 + }, + "tank": { + "targeting_frequency": "60Hz", + "movement_frequency": "30Hz", + "tactical_frequency": "1Hz" + } + } +} +``` + +### Configuration Flow +1. **CoordinationModule** loads `gameconfig.json` via IDataTree +2. **Deployment section** defines module topology and distribution +3. **Modules section** contains hierarchical configuration for each module type +4. **Hot-reload** updates propagated to all deployed modules automatically + +### CoordinationModule Deployment Logic +```cpp +// Example deployment process +void CoordinationModule::deployModule(const std::string& moduleInstanceId) { + // 1. Get module configuration from gameconfig.json + const IDataNode& deployConfig = configTree->getNode("deployment/modules"); + const IDataNode* moduleConfig = deployConfig.getFirstChildByName(moduleInstanceId); + + // 2. Determine deployment target + std::string target = moduleConfig->getString("target"); + std::string modulePath = moduleConfig->getString("path"); + std::string configPath = moduleConfig->getString("config_path"); + + // 3. Get module-specific configuration + const IDataNode& moduleSettings = configTree->getNode("modules/" + configPath); + + // 4. Deploy based on target + if (target == "local") { + localEngine->getModuleSystem()->loadModule(modulePath, moduleSettings); + } else if (target.startswith("server:")) { + deployToRemoteServer(target, modulePath, moduleSettings); + } +} +``` + +## IDataTree Configuration System Specifications + +### Core Architecture +```cpp +namespace warfactory { + class IDataTree { + // Tree access + virtual std::unique_ptr getRoot() = 0; + virtual std::unique_ptr getNode(const std::string& path) = 0; + + // Manual hot-reload + virtual bool checkForChanges() = 0; + virtual bool reloadIfChanged() = 0; + virtual void onTreeReloaded(std::function callback) = 0; + + // Metadata + virtual std::string getType() = 0; + }; +} +``` + +### IDataNode Capabilities +```cpp +namespace warfactory { + class IDataNode { + // Tree navigation + virtual std::unique_ptr getChild(const std::string& name) = 0; + virtual std::vector getChildNames() = 0; + virtual bool hasChildren() = 0; + + // Exact search in children + virtual std::vector getChildrenByName(const std::string& name) = 0; + virtual bool hasChildrenByName(const std::string& name) const = 0; + virtual IDataNode* getFirstChildByName(const std::string& name) = 0; + + // Pattern matching search (deep search in whole subtree) + virtual std::vector getChildrenByNameMatch(const std::string& pattern) = 0; + virtual bool hasChildrenByNameMatch(const std::string& pattern) const = 0; + virtual IDataNode* getFirstChildByNameMatch(const std::string& pattern) = 0; + + // Query by properties + virtual std::vector queryByProperty(const std::string& propName, + const std::function& predicate) = 0; + + // Node's own data + virtual json getData() = 0; + virtual bool hasData() = 0; + virtual void setData(const json& data) = 0; + + // Typed data access by property name + virtual std::string getString(const std::string& name, const std::string& defaultValue = "") = 0; + virtual int getInt(const std::string& name, int defaultValue = 0) = 0; + virtual double getDouble(const std::string& name, double defaultValue = 0.0) = 0; + virtual bool getBool(const std::string& name, bool defaultValue = false) = 0; + virtual bool hasProperty(const std::string& name) = 0; + + // Hash system for validation & synchro + virtual std::string getDataHash() = 0; + virtual std::string getTreeHash() = 0; + virtual std::string getSubtreeHash(const std::string& childPath) = 0; + + // Metadata + virtual std::string getPath() = 0; + virtual std::string getName() = 0; + virtual std::string getNodeType() = 0; + }; +} +``` + +### Configuration Usage Patterns + +#### Hierarchical Data Access +```cpp +// Access nested configuration +std::unique_ptr tree = DataTreeFactory::create("json", "config/vehicles.json"); +std::unique_ptr tank = tree->getNode("vehicles/tanks/heavy/model5"); + +// Get properties with type safety +int armor = tank->getInt("armor", 100); +double speed = tank->getDouble("speed", 30.0); +std::string name = tank->getString("display_name", "Unknown Tank"); +``` + +#### Pattern Matching Search +```cpp +// Find all components +std::vector components = root->getChildrenByNameMatch("component*"); + +// Find all heavy variants +std::vector heavyUnits = root->getChildrenByNameMatch("*heavy*"); + +// Find specific models +std::vector models = root->getChildrenByNameMatch("model_*"); +``` + +#### Property-Based Queries +```cpp +// Find all tanks with armor > 150 +std::vector heavyTanks = root->queryByProperty("armor", [](const json& val) { + return val.is_number() && val.get() > 150; +}); + +// Find all vehicles with specific role +std::vector scouts = root->queryByProperty("role", [](const json& val) { + return val.is_string() && val.get() == "scout"; +}); +``` + +#### Hot-Reload Workflow +```cpp +// Manual hot-reload check +if (tree->checkForChanges()) { + if (tree->reloadIfChanged()) { + // Tree was reloaded - update dependent systems + updateGameContent(); + } +} + +// Register reload callback +tree->onTreeReloaded([]() { + std::cout << "Configuration reloaded - updating systems\n"; + notifyAllModules(); +}); +``` + +### Hash-Based Validation +```cpp +// Validate specific data integrity +std::string nodeHash = node->getDataHash(); +std::string previousHash = loadStoredHash(); +if (nodeHash != previousHash) { + // Data has changed - trigger update + synchronizeWithServer(nodeHash); +} + +// Validate entire subtree +std::string treeHash = node->getTreeHash(); +if (treeHash != expectedTreeHash) { + // Subtree structure or data has changed + performFullValidation(); +} +``` + +### Factory Pattern Usage +```cpp +// JSON configuration +std::unique_ptr jsonTree = DataTreeFactory::create("json", "config/vehicles.json"); + +// Future: Database configuration +std::unique_ptr dbTree = DataTreeFactory::create("database", "postgresql://config_db"); + +// Future: Network configuration +std::unique_ptr netTree = DataTreeFactory::create("network", "https://api.example.com/config"); +``` + +## UI Interface System (COMPLETED) + +### IUI Architecture +- **Data-Agnostic Design**: Generic interface supporting all content types +- **Type-Safe Enums**: DataType::ECONOMY, RequestType::GET_PRICES for performance +- **Hierarchical Windowing**: Parent → Dock → Split → Tab → Window structure +- **Hybrid Sizing System**: Percentage targets with absolute pixel constraints + +### ImGuiUI Implementation +- **Complete Rendering Pipeline**: All DataType content renderers implemented +- **Interactive Callbacks**: Request/response system with onRequest() + custom events +- **Professional Layout**: Economic topbar + companies panel + strategic map + console +- **State Management**: Window persistence, docking configuration, layout serialization + +## Module System Specifications + +### BREAKING CHANGES in IModule Interface +```cpp +// OLD Interface (DEPRECATED) +class IModule { + virtual void initialize(const json& config, IIO* io, ITaskScheduler* scheduler) = 0; + virtual bool isHealthy() = 0; // Simple boolean +}; + +// NEW Interface (CURRENT) +class IModule { + virtual void setConfiguration(const IDataNode& configNode, IIO* io, ITaskScheduler* scheduler) = 0; + virtual const IDataNode& getConfiguration() = 0; + virtual json getHealthStatus() = 0; // Detailed JSON report + // initialize() method REMOVED +}; +``` + +### Configuration Immutability Pattern +```cpp +// Modules receive const references - cannot modify configuration +const IDataNode& config = coordinationModule->getConfigurationTree()->getNode("modules/production"); + +// All getter methods are const to enforce read-only access +int frequency = config.getInt("frequency", 60); // const method +std::string mode = config.getString("mode", "auto"); // const method + +// Modifications only possible through CoordinationModule +coordinationModule->syncConfiguration(); // Reloads entire tree +``` + +### Module Health Monitoring +```cpp +// Detailed health status example +json healthStatus = { + "status": "healthy|degraded|critical|offline", + "last_process_time_ms": 1.2, + "memory_usage_mb": 45, + "error_count": 0, + "warnings": ["High memory usage detected"], + "details": "All subsystems operational", + "uptime_seconds": 3600, + "processed_messages": 15420 +}; +``` + +### Module Frequencies & Isolation +- **ProductionModule**: 60Hz (frame-perfect factory operations) +- **TankModule**: 0.1-60Hz (Targeting 60Hz → Movement 30Hz → Tactical 1Hz → Analytics 0.1Hz) +- **EconomyModule**: 0.01-0.1Hz (economic cycles) +- **War Isolation**: ZERO interaction ProductionModule ↔ WarModule +- **Supply Chain**: Factory → LogisticModule → War (unidirectional flow) + +### Performance Targets +- **V1 Client**: 30+ fps +- **V2 Client**: 60+ fps +- **V1 Server**: 10+ players +- **V2 Server**: 100+ players + +## Development Constraints + +### Code Restrictions +- **AUTO KEYWORD PROHIBITED**: Explicit types required throughout codebase +- **Interface Immutability**: Core interfaces NEVER modified once finalized +- **Module Isolation**: No `#include "../"` or parent directory references +- **PUB/SUB Communication**: Module communication via IIO only + +### Build System +- **Autonomous Builds**: Each module builds independently +- **Hot-Reload**: 0.4ms average reload time achieved +- **Cross-Platform**: Linux development → Windows .exe automated +- **Debug Tools**: AddressSanitizer + UndefinedBehaviorSanitizer by default + +This document serves as the authoritative reference for all technical specifications in the Warfactory project. \ No newline at end of file diff --git a/docs/04-reference/arbre-technologique.md b/docs/04-reference/arbre-technologique.md new file mode 100644 index 0000000..f320afc --- /dev/null +++ b/docs/04-reference/arbre-technologique.md @@ -0,0 +1,973 @@ +# Arbre Technologique + +## Vue d'ensemble + +**Volume technologique** : 2000-3000 technologies organisées en **domaines interconnectés** + +**Principe des passerelles** : Expertise dans un domaine débloque des "prototypes" dans d'autres domaines, permettant de court-circuiter les progressions linéaires et d'ouvrir de nouvelles branches. + +## Philosophie Discovery & Rejouabilité + +### Design Core +**Le player n'est PAS censé rechercher toutes les 3000 technologies** ! Le système est conçu pour la **découverte organique** et la **rejouabilité** : + +#### Discovery Progressive +- **Breakthrough system** : Technologies débloquées par gameplay naturel (construction, production, combat) +- **Prerequisites gating** : Seules ~10-50 techs eligible simultanément, jamais 3000 +- **Random element** : Chaque run = découvertes différentes selon actions player +- **Organic emergence** : "Je construis → je découvre" vs "je regarde un arbre" + +#### Rejouabilité Infinie +- **3000 techs = content pool** pour expériences variées +- **Run spécialisé** : Focus métallurgie vs électronique = paths complètement différents +- **Combinaisons nouvelles** : Passerelles créent synergies inattendues entre runs +- **Surprises constantes** : "Wow ! Cette tech existe ?" même après 100h + +#### Performance & Scaling +- **Prerequisites check** : Validation ponctuelle quand conditions remplies, pas polling +- **Ticker optimisé** : Vérification breakthrough toutes les minutes, pas 60fps +- **Interface proven** : Similar à Factorio qui gère 100+ techs sans problème +- **Design for scale** : Standard industrie pour gros content pools + +## Mécaniques des Passerelles + +### Principe Fondamental +- Chaque arbre a sa **progression linéaire classique** +- Des techs d'autres arbres débloquent des **[PROTOTYPE]** qui court-circuitent la progression +- Ces prototypes ouvrent de **nouvelles branches** dans l'arbre de destination +- **Évite le grind linéaire** : Player spécialisé peut accéder à d'autres domaines sans tout refaire + +### Types de Déblocages +1. **Court-circuit** : Saute 1-3 techs de la progression linéaire +2. **Nouvelle branche** : Ouvre une ligne technologique alternative +3. **Hybridation** : Combine deux domaines pour créer des technologies uniques +4. **Spécialisation** : Versions spécialisées de technologies existantes + +### Exemple Concret : Châssis +**Progression classique** : +``` +Châssis Léger → Châssis Moyen → Châssis Lourd → Châssis Blindé +``` + +**Passerelles depuis autres arbres** : +``` +Métallurgie Avancée → [PROTOTYPE] Châssis Composite (saute Châssis Moyen) + → Ouvre branche : Châssis Composite → Châssis Modulaire → Châssis Ultra-Léger + +Électronique → [PROTOTYPE] Châssis Smart (saute Châssis Lourd) + → Ouvre branche : Châssis Smart → Châssis Adaptatif → Châssis Morphing + +Moteur → [PROTOTYPE] Châssis Performance + → Ouvre branche : Châssis Performance → Châssis Racing → Châssis Hypervéloce +``` + +## Domaines Technologiques Principaux + +### 0. Technologies Civiles - ARBRE MASTER (~800 techs) + +**Rôle central** : L'arbre civil est le **backbone technologique** qui nourrit TOUS les autres domaines. Il représente la base industrielle, scientifique et sociale qui permet le développement militaire. + +#### Structure de l'Arbre Civil + +**A. Infrastructure & Industrie de Base (~150 techs)** +``` +Outils Manuels → Machines Simples → Automation Basique → Industrie Lourde → Complexes Industriels → Méga-Usines +``` +Sous-branches : +- **Extraction** : Mines → Foreuses → Extraction Automatisée → Mining Complexes +- **Sidérurgie** : Forges → Hauts Fourneaux → Aciéries → Complexes Métallurgiques +- **Chimie** : Laboratoires → Usines Chimiques → Pétrochimie → Nanotechnologie + +**Passerelles offertes** : +- → **Métallurgie** : [PROTOTYPE] Alliages Industriels (court-circuite Aciers Spéciaux) +- → **Production** : [PROTOTYPE] Assembly Lines (court-circuite Automation) +- → **Énergie** : [PROTOTYPE] Générateurs Industriels + +**B. Sciences Fondamentales (~120 techs)** +``` +Mathématiques → Physique → Chimie → Biologie → Sciences Avancées → Recherche Fondamentale → Théories Unifiées +``` +Sous-branches détaillées : +- **Mathématiques** : Arithmétique → Algèbre → Calcul → Statistiques → Topologie → Théorie des Groupes +- **Physique** : Mécanique → Thermodynamique → Électromagnétisme → Quantique → Relativité → Physique Exotique +- **Chimie** : Chimie de Base → Organique → Polymères → Catalyse → Supramoléculaire +- **Biologie** : Cellulaire → Génétique → Biotechnologie → Ingénierie Génétique + +**Passerelles offertes** : +- → **Électronique** : [PROTOTYPE] Semi-Conducteurs Avancés +- → **Matériaux** : [PROTOTYPE] Matériaux Quantiques +- → **Médecine** : [PROTOTYPE] Biotechnologies Militaires +- → **Énergie** : [PROTOTYPE] Réacteurs Avancés + +**C. Technologies de l'Information (~100 techs)** +``` +Écriture → Imprimerie → Télégraphe → Téléphone → Ordinateurs → Internet → IA Civile → Singularité Info +``` +Sous-branches : +- **Calcul** : Abaque → Calculatrices → Ordinateurs → Superordinateurs → Quantique +- **Réseaux** : Télégraphe → Téléphone → Internet → Réseaux Avancés → Neural Networks +- **Stockage** : Papier → Magnétique → Optique → Quantique → Moléculaire + +**Passerelles offertes** : +- → **Électronique** : [PROTOTYPE] Processeurs Civils → branch militaire +- → **Communication** : [PROTOTYPE] Réseaux Sécurisés +- → **Capteurs** : [PROTOTYPE] Surveillance Civile + +**D. Transport & Logistique Civile (~80 techs)** +``` +Marche → Roue → Animaux → Vapeur → Moteur → Aviation → Spatial → Téléportation +``` +Sous-branches : +- **Terrestre** : Pieds → Vélo → Automobile → Trains → Transport de Masse +- **Maritime** : Radeaux → Voiliers → Vapeur → Cargo → Porte-Conteneurs +- **Aérien** : Ballons → Avions → Jets → Supersonique → Spatial +- **Logistique** : Entrepôts → Supply Chains → Automation → Distribution + +**Passerelles offertes** : +- → **Moteurs** : [PROTOTYPE] Moteurs Haute Performance +- → **Châssis** : [PROTOTYPE] Véhicules Civils Adaptés +- → **Logistic Engine** : [PROTOTYPE] Systèmes de Distribution + +**E. Énergie & Ressources (~90 techs)** +``` +Muscle → Eau → Vapeur → Électricité → Fossiles → Nucléaire → Renouvelables → Fusion → Exotique +``` +Sous-branches massives : +- **Renouvelables** : Éolien → Solaire → Hydroélectrique → Géothermique → Biomasse +- **Fossiles** : Charbon → Pétrole → Gaz → Raffinerie → Pétrochimie +- **Nucléaire** : Fission → Réacteurs → Sécurité → Fusion → Réacteurs Avancés +- **Stockage** : Batteries → Supercondensateurs → Stockage Massif + +**Passerelles offertes** : +- → **Moteurs** : [PROTOTYPE] Propulsion Alternative +- → **Électronique** : [PROTOTYPE] Alimentation Avancée +- → **Armes** : [PROTOTYPE] Armes Énergétiques + +**F. Agriculture & Biotechnologie (~70 techs)** +``` +Cueillette → Agriculture → Élevage → Sélection → Mécanisation → OGM → Agriculture Verticale → Bio-usines +``` +Sous-branches : +- **Crops** : Céréales → Légumes → Fruits → Plantes Industrielles → OGM +- **Élevage** : Domestication → Sélection → Élevage Intensif → Clonage +- **Bio-industrie** : Fermentation → Biocarburants → Pharmaceutiques → Biomatériaux + +**Passerelles offertes** : +- → **Médecine** : [PROTOTYPE] Pharmacologie Militaire +- → **Matériaux** : [PROTOTYPE] Biomatériaux +- → **Énergie** : [PROTOTYPE] Biocarburants Avancés + +**G. Médecine & Sciences de la Vie (~60 techs)** +``` +Herboristerie → Anatomie → Chirurgie → Antibiotiques → Médecine Moderne → Génétique → Augmentation +``` +Sous-branches : +- **Diagnostics** : Observation → Rayons X → Scanners → Diagnostics Moléculaires +- **Traitements** : Chirurgie → Médicaments → Thérapie Génique → Nanotechnologie Médicale +- **Augmentation** : Prothèses → Implants → Cybernétique → Enhancement Génétique + +**Passerelles offertes** : +- → **Électronique** : [PROTOTYPE] Biocapteurs +- → **Matériaux** : [PROTOTYPE] Matériaux Biocompatibles +- → **IA** : [PROTOTYPE] IA Médicale → IA Militaire + +**H. Sciences Sociales & Organisation (~80 techs)** +``` +Tribus → Villages → Cités → États → Organisations → Corporations → Gouvernance Mondiale +``` +Sous-branches : +- **Gouvernance** : Monarchie → Démocratie → Bureaucratie → E-gouvernement +- **Économie** : Troc → Monnaie → Banques → Marchés → Économie Numérique +- **Education** : Oral → Écrit → Universités → Recherche → Education de Masse +- **Média** : Oral → Écrit → Imprimé → Radio/TV → Internet → Réalité Virtuelle + +**Passerelles offertes** : +- → **Communication** : [PROTOTYPE] Propagande Moderne +- → **IA** : [PROTOTYPE] IA Sociale +- → **Capteurs** : [PROTOTYPE] Surveillance Sociale + +#### Mécaniques Spéciales de l'Arbre Civil + +**1. Déblocage en Cascade** +Une tech civile peut débloquer des passerelles dans **MULTIPLES domaines** : +``` +"Internet" → [PROTOTYPE] Réseaux Militaires (Communication) + → [PROTOTYPE] Guerre Électronique (EW) + → [PROTOTYPE] IA Distribuée (Électronique) + → [PROTOTYPE] Logistique Intelligente (Transport) +``` + +**2. Prérequis Civils Obligatoires** +Certaines techs militaires **EXIGENT** des bases civiles : +- Armes Guidées → Nécessite "Électronique Civile" +- Véhicules Autonomes → Nécessite "IA Civile" +- Matériaux Avancés → Nécessite "Sciences des Matériaux" + +**3. Synergie Économie-Recherche** +- Techs civiles influencent la **capacité économique** de production +- Plus de tech civile = plus de **research points** générés +- Certaines techs civiles débloquent des **bâtiments de recherche** spécialisés + +**4. Évènements de Tech-Transfer** +- Events aléatoires : "Découverte civile" → breakthrough militaire inattendu +- "Dual-use technology" : Tech civile automatiquement adaptée au militaire +- "Brain-drain" : Scientifiques civils → boost recherche militaire + +#### Exemples Concrets de Passerelles Civile → Militaire + +**Chimie Agricole → Explosifs** : +``` +Agriculture : Engrais Azotés → [PROTOTYPE] Explosifs Artisanaux + → [PROTOTYPE] Nitrate d'Ammonium → Explosifs Industriels + → [PROTOTYPE] Pesticides → Armes Chimiques + → [PROTOTYPE] Fertilisants → Propergols Roquettes + +Pétrochimie : Plastiques → [PROTOTYPE] Explosifs Plastiques + → [PROTOTYPE] Polymères → Propergols Solides + → [PROTOTYPE] Solvants → Carburants Militaires +``` + +**Médecine → Applications Militaires** : +``` +Pharmacologie : Anesthésiques → [PROTOTYPE] Gaz Incapacitants + → [PROTOTYPE] Stimulants → Drogues de Combat + → [PROTOTYPE] Antibiotiques → Protection NBC + +Chirurgie : Traumatologie → [PROTOTYPE] Médecine de Guerre + → [PROTOTYPE] Prothèses → Augmentations Militaires + → [PROTOTYPE] Analgésiques → Stims de Combat +``` + +**Électronique Civile → Militaire** : +``` +Télécommunications : GPS Civil → [PROTOTYPE] Navigation Militaire + → [PROTOTYPE] Satellites → Reconnaissance Spatiale + → [PROTOTYPE] Internet → Cyberguerre + +Gaming : Processeurs Graphiques → [PROTOTYPE] Simulation Balistique + → [PROTOTYPE] Réalité Virtuelle → Entraînement Militaire + → [PROTOTYPE] IA de Jeu → IA Tactique +``` + +**Transport Civil → Applications Militaires** : +``` +Aviation Civile : Moteurs Civils → [PROTOTYPE] Moteurs Militaires + → [PROTOTYPE] Navigation Aérienne → Systèmes Guidage + → [PROTOTYPE] Drones Livraison → Drones Militaires + +Automobile : Moteurs Performance → [PROTOTYPE] Véhicules Blindés + → [PROTOTYPE] Systèmes Hybrides → Véhicules Furtifs + → [PROTOTYPE] Autonomous Cars → Véhicules Autonomes Militaires +``` + +**Sciences des Matériaux → Applications Militaires** : +``` +Industrie : Alliages Légers → [PROTOTYPE] Blindages Composites + → [PROTOTYPE] Céramiques → Plaques Balistiques + → [PROTOTYPE] Fibres Carbone → Casques Avancés + → [PROTOTYPE] Nanomatériaux → Furtivité Avancée + +Construction : Béton Haute Résistance → [PROTOTYPE] Bunkers Avancés + → [PROTOTYPE] Aciers Spéciaux → Blindages Réactifs +``` + +**Énergie Civile → Applications Militaires** : +``` +Nucléaire Civil : Réacteurs → [PROTOTYPE] Propulsion Nucléaire + → [PROTOTYPE] Isotopes → Armes Radiologiques + → [PROTOTYPE] Fusion Contrôlée → Armes Thermonucléaires + +Renouvelables : Panneaux Solaires → [PROTOTYPE] Alimentation Terrain + → [PROTOTYPE] Batteries → Systèmes Autonomes + → [PROTOTYPE] Supercondensateurs → Armes Énergétiques +``` + +**Agriculture → Applications Militaires** : +``` +Biotechnologie : Génétique Végétale → [PROTOTYPE] Bioarmes + → [PROTOTYPE] Fermentation → Production Explosifs + → [PROTOTYPE] Enzymes → Décontamination NBC + +Mécanisation : Tracteurs → [PROTOTYPE] Véhicules Logistiques + → [PROTOTYPE] GPS Agricole → Navigation Militaire + → [PROTOTYPE] Drones Agricoles → Surveillance/Attack Drones +``` + +**Total Passerelles Civile → Militaire** : ~40-50 prototypes +- Chaque domaine civil offre 5-8 passerelles militaires +- Certaines techs civiles débloquent dans PLUSIEURS domaines militaires +- Progression naturelle : applications civiles → adaptations militaires + +### 1. Métallurgie & Matériaux (~300 techs) + +#### Progression Principale Étendue +``` +Métaux de Base → Alliages Simples → Aciers Spéciaux → Métaux Légers → Composites → Superalliages → Matériaux Quantiques → Matériaux Exotiques +``` + +#### Sous-branches Détaillées + +**A. Matériaux Traditionnels & Naturels (70 techs)** +- **Métaux de Base** : Fer → Cuivre → Bronze → Acier → Acier Carbone → Fonte → Acier Doux (10 techs) +- **Alliages Simples** : Laiton → Acier Inox → Chrome → Nickel → Cobalt → Zinc → Étain (10 techs) +- **Aciers Spéciaux** : Haute Résistance → Rapide → Inoxydable → Outillage → Ressorts → Maraging (10 techs) +- **Traitements Métalliques** : Trempe → Recuit → Cémentation → Nitruration → Chromage → Galvanisation (10 techs) +- **Bois & Dérivés** : Bois Massif → Contreplaqué → Aggloméré → Bois Pressé → Bois Lamellé → MDF → OSB → Bois Traité → Bois Densifié → Bois Composite (15 techs) +- **Bétons & Ciments** : Mortier → Béton Simple → Béton Armé → Béton Précontraint → Béton Romain (Auto-Réparant) → Béton Fibré → Béton Ultra-Haute Performance → Béton Translucide → Béton Auto-Plaçant → Géopolymères → Béton Léger → Béton Lourd (15 techs) + +**B. Métaux Légers & Avancés (40 techs)** +- **Aluminium** : Pur → Alliages 2xxx → 6xxx → 7xxx → Aéronautique → Ultra-Léger (12 techs) +- **Titane** : Grade 1 → Grade 2 → Ti-6Al-4V → Aérospatial → Bio-compatible → Beta-Titane (12 techs) +- **Magnésium** : Pur → AZ Series → AM Series → Structural → Ignifuge → Ultra-Léger (10 techs) +- **Lithium & Rares** : Lithium → Béryllium → Terres Rares → Scandium → Métaux Exotiques (6 techs) + +**C. Matériaux Composites (55 techs)** +- **Fibres de Base** : Verre E → Verre S → Carbone T300 → T700 → T800 → Aramide → Basalte → Lin (15 techs) +- **Matrices** : Époxy → Polyester → Vinylester → Thermoplastiques → PEEK → Bio-résines (12 techs) +- **Composites Avancés** : Sandwich → Tissage 3D → Nanotubes → Graphène → Fibres Hybrides → RTM (18 techs) +- **Composites Métalliques** : Métal-Matrice → Céramique-Métal → Hybrides → MMC Aluminium (10 techs) + +**D. Matériaux Intelligents & Programmables (45 techs)** +- **Smart Materials** : Mémoire de Forme → Piézoélectriques → Magnétorhéologiques → Électrorhéologiques → Thermochromiques (15 techs) +- **Nanomatériaux** : Nanoparticules → Nanotubes → Graphène → Fullerènes → Quantum Dots → Nanocomposites (15 techs) +- **Matériaux Programmables** : Auto-Assemblage → Reconfigurables → Adaptatifs → Morphing → 4D Printing (10 techs) +- **Bio-matériaux** : Bio-inspirés → Vivants → Auto-Réparants → Évolutifs → Biocompatibles (5 techs) + +**E. Blindages & Protection (35 techs)** +- **Blindages Passifs** : Homogène → Composite → Espacé → Modulaire → Laminé → Multi-Couches (12 techs) +- **Blindages Réactifs** : ERA → NERA → Smart Armor → Adaptatif → Électrique → Magnétique (12 techs) +- **Protection Avancée** : Furtivité → Multi-Spectral → Caméléon → Phase-Change → Plasma (11 techs) + +**F. Matériaux Exotiques & Quantiques (25 techs)** +- **Supraconducteurs** : Haute Température → Ambiants → Quantiques → Organiques → Cuprates (8 techs) +- **Métamatériaux** : Optiques → RF → Acoustiques → Mécaniques → Plasmoniques → Photoniques (10 techs) +- **Matériaux Quantiques** : Cristaux Temporels → Topologiques → Plasma → Antimatière → Matière Noire → Dimensions Supérieures → Singularités Contrôlées (7 techs) + +#### Passerelles Offertes Étendues +- → **Châssis** : [PROTOTYPE] Châssis Composite (court-circuite Châssis Moyen) +- → **Châssis** : [PROTOTYPE] Châssis Ultra-Léger (court-circuite Châssis Lourd) +- → **Armement** : [PROTOTYPE] Canon Léger (court-circuite Artillerie de Base) +- → **Armement** : [PROTOTYPE] Blindage Réactif (court-circuite Protection Passive) +- → **Électronique** : [PROTOTYPE] Dissipateurs Avancés +- → **Électronique** : [PROTOTYPE] Supraconducteurs (court-circuite Refroidissement) +- → **Transport** : [PROTOTYPE] Véhicules Ultra-Légers +- → **Énergie** : [PROTOTYPE] Stockage Supraconducteur +- → **Capteurs** : [PROTOTYPE] Optiques Avancées + +### 2. Châssis & Structures (~100 techs) + +#### Progression Principale +``` +Châssis Léger → Châssis Moyen → Châssis Lourd → Châssis Blindé → Châssis Modulaire +``` + +#### Branches Classiques Focus +- **Légers** : Châssis Scout → Châssis Reconnaissance → Châssis Infiltration (20 techs) +- **Moyens** : Châssis Transport → Châssis Polyvalent → Châssis Support (20 techs) +- **Lourds** : Châssis Bataille → Châssis Assault → Châssis Forteresse (20 techs) + +#### Branches Débloquées par Passerelles (40 techs) +- **Métallurgie** → [PROTOTYPE] Châssis Composite → Châssis Ultra-Léger → Châssis Furtif +- **Électronique** → [PROTOTYPE] Châssis Smart → Châssis Adaptatif → Châssis IA +- **Moteurs** → [PROTOTYPE] Châssis Performance → Châssis Racing → Châssis Hypervéloce + +#### Passerelles Offertes +- → **Armement** : [PROTOTYPE] Tourelles Stabilisées +- → **Capteurs** : [PROTOTYPE] Plateformes Sensorielles + +### 3. Électronique & Informatique (~400 techs) + +#### Progression Principale Étendue +``` +Circuits de Base → Processeurs → IA Basique → IA Avancée → IA Militaire → IA Autonome → IA Symbiotique → Conscience Artificielle +``` + +#### Sous-branches Massives +- **Processeurs** : CPU → GPU → Quantique → Neuromorphique → Bio-processeurs (80 techs) +- **Capteurs Électroniques** : Optiques → Thermiques → Radars → Multi-spectraux → Quantiques (60 techs) +- **IA & Machine Learning** : Expert Systems → ML → Neural Networks → Deep Learning → AGI (100 techs) +- **Microélectronique** : Circuits Intégrés → Nanopuces → Quantique → Moléculaire (80 techs) +- **Systèmes Embarqués** : Contrôleurs → Temps Réel → Distribués → Autonomes (80 techs) + +#### Passerelles Offertes +- → **Armement** : [PROTOTYPE] Viseurs Intelligents +- → **Châssis** : [PROTOTYPE] Châssis Smart +- → **Communication** : [PROTOTYPE] Guerre Électronique +- → **Capteurs** : [PROTOTYPE] Radars Adaptatifs +- → **Transport** : [PROTOTYPE] Véhicules Autonomes + +### 4. Moteurs & Propulsion (~150 techs) + +#### Progression Principale Resserrée +``` +Moteurs Diesel → Moteurs Turbo → Moteurs Hybrides → Moteurs Électriques → Propulsion Alternative +``` + +#### Sous-branches Focus +- **Thermiques** : Diesel → Essence → Turbine → Fusion (40 techs) +- **Électriques** : Batteries → Supercondensateurs → Pile à Combustible (35 techs) +- **Hybrides** : Série → Parallèle → Plug-in → Intelligent (25 techs) +- **Exotiques** : Ionique → Plasma → Antigravité → Propulsion Spatiale (50 techs) + +#### Passerelles Offertes +- → **Châssis** : [PROTOTYPE] Châssis Performance +- → **Transport** : [PROTOTYPE] Transport Rapide +- → **Aviation** : [PROTOTYPE] Moteurs Aéro +- → **Naval** : [PROTOTYPE] Propulsion Marine + +### 5. Armement & Munitions (~400 techs) + +#### Progression Principale Massive +``` +Armes Légères → Artillerie → Missiles → Armes Guidées → Armes Intelligentes → Armes Énergétiques → Armes Exotiques +``` + +#### Sous-branches Ultra-Détaillées +- **Armes Légères** : Fusils → Mitrailleuses → Armes Spécialisées → Smart Weapons (80 techs) +- **Artillerie** : Canons → Mortiers → Artillery Guided → Railguns → Plasma Cannons (100 techs) +- **Missiles** : Roquettes → Missiles Guidés → Missiles Intelligents → Essaims → Hypersoniques (120 techs) +- **Armes Énergétiques** : Lasers → Plasma → Particle Beams → Weapons Exotiques (100 techs) + +#### Branches Débloquées par Passerelles +- **Métallurgie** → [PROTOTYPE] Canon Léger → Artillerie Composite → Canons Electromagnétiques +- **Électronique** → [PROTOTYPE] Viseurs Intelligents → Armes Autonomes → Essaims de Combat +- **Moteurs** → [PROTOTYPE] Missiles Hypersoniques → Projectiles Cinétiques + +### 6. Capteurs & Reconnaissance (~200 techs) + +#### Progression Principale +``` +Optiques de Base → Radars → Capteurs Multispectraux → Reconnaissance Satellite → Intel Fusion → Omniscience +``` + +#### Exemple Détaillé : Évolution Radar +- **Proto radar** : Composant 6x6, 2kw, fiabilité 50% +- **Recherche radar 1** : Composant 5x5, 2kw, fiabilité 60% + sous-composant électronique 4x4, 500w, fiabilité 20% +- **Recherche radar 2** : Composant 8x3, 1.5kw, fiabilité 80% +- **Radar Avancé** : Composant 6x2, 1kw, fiabilité 95% + mode stealth +- **Radar Quantique** : Composant 4x2, 500w, fiabilité 99% + pénétration furtivité + +### 7. Communication & Guerre Électronique (~100 techs) + +#### Progression Principale Focus +``` +Radio → Communications Sécurisées → Réseaux Tactiques → Guerre Électronique → Cyber Warfare +``` + +#### Sous-branches Concentrées +- **Communications** : Radio → Crypté → Satellites → Réseaux Mesh (30 techs) +- **Guerre Électronique** : Jamming → SIGINT → ELINT → Cyber Ops (40 techs) +- **Réseaux** : P2P → Tactiques → Stratégiques → Quantiques (30 techs) + +### 8. Transport & Logistique (~60 techs) + +#### Progression Principale Streamline +``` +Véhicules de Base → Transport Lourd → Rail → Transport Maritime → Hyperloop +``` + +#### Sous-branches Essentielles +- **Terrestre** : Camions → Convois → Trains → Hyperloop (20 techs) +- **Maritime** : Cargos → Porte-Conteneurs → Transport Rapide (15 techs) +- **Aérien** : Cargo → Transport Stratégique → Orbital (15 techs) +- **Logistique** : Supply Chains → Distribution → Automation (10 techs) + +### 9. Production & Assembly (~100 techs) + +#### Progression Principale Efficace +``` +Assembly Manuel → Automation → Robotique → Nano-Assembly → Fabrication Moléculaire +``` + +#### Sous-branches Focus +- **Automation** : Chaînes → Robots → IA Production (30 techs) +- **Qualité** : Contrôle → Précision → Perfectionnement (25 techs) +- **Vitesse** : Optimisation → Parallélisation → Instantané (25 techs) +- **Flexibilité** : Modulaire → Adaptatif → Reconfigurable (20 techs) + +### 10. Énergie & Alimentation (~100 techs) + +#### Progression Principale Condensée +``` +Générateurs de Base → Énergie Renouvelable → Batteries Avancées → Fusion → Anti-matière +``` + +#### Sous-branches Concentrées +- **Génération** : Fossiles → Nucléaire → Fusion → Exotique (35 techs) +- **Renouvelables** : Solaire → Éolien → Géothermique → Bio (25 techs) +- **Stockage** : Batteries → Supercaps → Stockage Massif (25 techs) +- **Distribution** : Réseaux → Smart Grids → Sans-fil (15 techs) + +## Mécaniques Avancées des Passerelles + +### Passerelles Multi-Domaines +Certains prototypes nécessitent expertise dans **plusieurs domaines** : + +``` +Métallurgie Avancée + Électronique → [PROTOTYPE] Armure Réactive + → Nouvelle branche : Défenses Adaptatives + +Moteurs + Communication → [PROTOTYPE] Véhicules Coordinés + → Branche : Essaims Terrestres + +IA + Capteurs + Armement → [PROTOTYPE] Tourelles Autonomes + → Branche : Défenses Intelligentes + +Matériaux + Moteurs + IA → [PROTOTYPE] Véhicules Morphing + → Branche : Technologie Adaptive +``` + +### Profondeur et Distribution Finale +- **Technologies Civiles** : 800 techs (backbone) +- **Métallurgie & Matériaux** : 300 techs +- **Châssis & Structures** : 100 techs +- **Électronique & Informatique** : 400 techs +- **Moteurs & Propulsion** : 150 techs +- **Armement & Munitions** : 400 techs +- **Capteurs & Reconnaissance** : 200 techs +- **Communication & Guerre Électronique** : 100 techs +- **Transport & Logistique** : 60 techs +- **Production & Assembly** : 100 techs +- **Énergie & Alimentation** : 100 techs + +**Total estimé** : 2710 technologies + ~300 passerelles inter-domaines = **~3000 technologies** avec progression non-linéaire ultra-riche + +## Interface Utilisateur - Vues Modulaires + +### Principe des Vues Focalisées +Pour éviter l'overwhelm des 3000 technologies, l'interface propose des **vues modulaires** permettant de se concentrer sur des progressions spécifiques. + +### Vue "Arbre Linéaire" + +**Fonctionnement** : +1. Player **sélectionne une tech racine** (ex: "Métaux de Base", "Circuits de Base", "Moteurs Diesel") +2. L'interface affiche **uniquement l'arbre de progression linéaire** à partir de cette racine +3. **Pas de passerelles** affichées → focus sur la progression naturelle du domaine +4. **Système Discovery** : Les techs sans breakthrough ne sont **JAMAIS** visibles (principe Ymir) + +### Exemples Concrets + +**Exemple 1 : Tech Racine "Métaux de Base"** +``` +Métaux de Base +├── Fer [RECHERCHÉ] ✅ +├── Cuivre [RECHERCHÉ] ✅ +├── Bronze [DISPONIBLE] 🔓 +├── Acier [DISPONIBLE] 🔓 +├── Acier Carbone [VERROUILLÉ] 🔒 +└── Fonte [INCONNU] ❓ (si toggle OFF) +``` + +**Exemple 2 : Discovery Progressive "Radar"** + +**Run 1 - Player débutant** : +``` +Proto Radar +├── [RECHERCHÉ] Proto radar (6x6, 2kw, 50% fiabilité) ✅ +└── [DISPONIBLE] Recherche radar 1 (5x5, 2kw, 60% fiabilité) 🔓 + +?? Plus de techs radar disponibles ?? +``` + +**Run 2 - Player a fait breakthrough "Scrap Radar Militaire"** : +``` +Proto Radar +├── [RECHERCHÉ] Proto radar ✅ +├── [RECHERCHÉ] Recherche radar 1 ✅ +├── [DISPONIBLE] Recherche radar 2 (8x3, 1.5kw, 80% fiabilité) 🔓 +└── [BREAKTHROUGH] Radar Militaire (4x4, 1kw, 70% fiabilité, mode furtif) 🔥 + +💡 "Wow ! Je ne savais pas que ça existait !" +``` + +**Run 5 - Player expérimenté** : +``` +Proto Radar +├── [RECHERCHÉ] Proto radar ✅ +├── [RECHERCHÉ] Recherche radar 1 ✅ +├── [RECHERCHÉ] Recherche radar 2 ✅ +├── [BREAKTHROUGH] Radar Militaire ✅ +├── [BREAKTHROUGH] Radar Adaptatif (découvert via scrap drone) 🔥 +├── [AVAILABLE] Radar Quantique (débloqué par Radar Adaptatif) 🔓 +└── [BREAKTHROUGH] Radar Multispectral (découvert via capture satellite) 🔥 +``` + +### États des Technologies + +**Couleurs/Icônes** : +- ✅ **RECHERCHÉ** : Vert, disponible pour utilisation +- 🔓 **DISPONIBLE** : Jaune, peut être recherché maintenant +- 🔒 **VERROUILLÉ** : Rouge, prérequis manquants +- 🔥 **BREAKTHROUGH** : Orange, découvert via scrap/capture/événement +- 🔗 **PASSERELLE** : Bleu, accessible via autre domaine (vue séparée) + +### Contrôles Interface + +**Sélecteur Tech Racine** : +``` +Domaine: [Métallurgie ▼] +Tech Racine: [Métaux de Base ▼] [Alliages Simples ▼] [Aciers Spéciaux ▼] +``` + +**Options d'Affichage** : +``` +☑️ Montrer prérequis détaillés +☑️ Montrer coûts de recherche +☐ Mode compact +``` + +## Breakthrough Tech System (À la Ymir) + +### Principe Fondamental +**TOUTE** technologie nécessite un **breakthrough** avant d'être recherchable. Pas de tech tree visible - système de découverte organique basé sur l'expérience de jeu. + +### Mécaniques Core + +#### 1. Conditions de Breakthrough +Chaque tech a des **conditions de découverte** variées : + +#### State-Based vs Historic Validation + +**State-Based Conditions (Préférées)** : +- **Avoir** 5 radars actifs → breakthrough "Radar Avancé" +- **Avoir** 10 usines simultanément → breakthrough "Automation Industrielle" +- **Avoir** 20 tourelles déployées → breakthrough "Défenses Intégrées" +- **Avoir** 1M€ en banque → breakthrough "Capital Industriel" + +**Historic + Counters (Minimales)** : +- **Total produit** : 1000t acier (compteur cumulatif simple) +- **Designs créés** : 50 véhicules (compteur simple) +- **Ventes cumulées** : 100k€ sur marché (compteur simple) + +**Triggers Événementiels (Pas de stockage)** : +- **Concevoir véhicule** avec 5+ composants électroniques → check immédiat +- **Exporter vers nouveau pays** → check immédiat +- **Rechercher tech** → check dépendances immédiat + +### Optimisation Mémoire - System Design + +#### Données State Actuelles (Toujours en RAM) +```cpp +struct PlayerState { + // Installations actives + int active_radars = 0; + int active_factories = 0; + int deployed_turrets = 0; + + // Finances actuelles + long current_money = 0; + + // Technologies recherchées (BitSet) + bitset<3000> researched_techs; + + // Pays d'export actifs (Set) + set export_countries; +} +``` + +#### Compteurs Cumulatifs (Minimal Historic) +```cpp +struct LifetimeCounters { + // Production totale (compteurs simples) + long total_steel_produced = 0; + long total_vehicles_designed = 0; + long total_revenue = 0; + + // Événements majeurs (flags) + bool designed_composite_vehicle = false; + bool designed_autonomous_system = false; + bool exported_to_5_countries = false; +} +``` + +#### Validation en Temps Réel +```cpp +// Trigger immédiat lors d'événements +void OnVehicleDesigned(Design vehicle) { + if (vehicle.hasComponentType(ELECTRONIC) >= 5) { + TriggerBreakthroughCheck("Electronic_Embedded"); + } + + if (vehicle.hasComposite()) { + counters.designed_composite_vehicle = true; + TriggerBreakthroughCheck("Advanced_Protection"); + } +} + +void OnRadarBuilt() { + state.active_radars++; + if (state.active_radars >= 5) { + TriggerBreakthroughCheck("Advanced_Radar"); + } +} +``` + +#### Exemples Optimisés + +**Breakthrough "Radar Avancé"** : +``` +Conditions: +✅ State: active_radars >= 5 (check continu) +✅ State: researched_techs[RADAR_BASIC] == true +❌ Pas: "avoir détecté 100 unités" (trop coûteux à tracker) +``` + +**Breakthrough "Automation Industrielle"** : +``` +Conditions: +✅ State: active_factories >= 10 +✅ Counter: total_vehicles_designed >= 100 +✅ Event: designed_autonomous_system == true +``` + +**Breakthrough "Commerce International"** : +``` +Conditions: +✅ State: export_countries.size() >= 5 +✅ Counter: total_revenue >= 1000000 +❌ Pas: "historique des ventes détaillé" (trop coûteux) +``` + +#### 2. Random Ticker System +- Condition remplie → **random chance** chaque tick de découvrir le breakthrough +- Probabilité augmente avec le temps (évite frustration) +- **Pas instantané** → crée suspense et anticipation + +#### 3. Méthodes de Force +**Scrap Analysis** : +- Étudier équipement ennemi → breakthrough garanti (mais coûteux) +- "Tu étudies ce radar captured → découvres Radar Militaire" + +**Reverse Engineering** : +- Acheter produit sur marché → décomposer → breakthrough +- Conséquences diplomatiques mais accès garanti + +**Design Study** : +- Analyser designs capturés → breakthrough composants spécifiques + +#### 4. Trading de Breakthroughs +**Marché des connaissances** : +- **Breakthrough ≠ tech researched** → breakthrough = accès à la recherche +- Companies peuvent vendre/acheter l'accès aux recherches +- Prix selon rareté et demande +- Créé économie de l'innovation + +### Exemples Concrets + +#### Progression "Radar" +``` +Base: Proto Radar (toujours disponible) + +Breakthrough "Radar 1": +├── Condition A: Avoir 3 radars opérationnels pendant 10 jours +├── Condition B: Détecter 100 unités ennemies +└── Force: Scrap "Radar militaire ukrainien" + +Breakthrough "Radar Adaptatif": +├── Condition A: Avoir recherché Radar 1 + IA Basique +├── Condition B: Concevoir véhicule avec radar + 3 capteurs +└── Force: Reverse engineer "Radar AESA commercial" + +Breakthrough "Radar Quantique": +├── Condition A: Recherché Radar Adaptatif + Physique Quantique +├── Condition B: Avoir 50M€ investis en R&D +└── Event: "Découverte scientifique" (rare, 1-2 niveaux max) +``` + +#### Progression "Métallurgie" +``` +Base: Métaux de Base (toujours disponible) + +Breakthrough "Aciers Spéciaux": +├── Condition A: Produire 1000t d'acier standard +├── Condition B: Construire 5 hauts fourneaux +└── Force: Scrap "Blindage de tank" + +Breakthrough "Alliages Légers": +├── Condition A: Avoir Aciers Spéciaux + exporter 500t métal +├── Condition B: Designer véhicule nécessitant poids réduit +└── Force: Purchase "Alliage aéronautique" + +Breakthrough "Matériaux Composites": +├── Condition A: 3 techs métallurgie + 2 techs chimie +├── Condition B: Commande client "véhicule ultra-léger" +└── Multiple forces: Scrap composite, reverse engineer, etc. +``` + +### Impacts Gameplay + +#### Discovery Organique +- **Pas de tech tree** → player découvre par expérience +- **Gameplay naturel** → "Je produis → je découvre" +- **Surprise constante** → "Oh ! Nouvelle tech disponible !" +- **Emergent progression** → chaque partie unique + +#### Companies IA +- **Même système** → IA découvre par leurs actions +- **Spécialisations naturelles** → Company "Metal" découvre métal faster +- **Compétition réaliste** → Qui découvre en premier ? +- **Tech transfer** → IA peut vendre breakthroughs au player + +#### Event System +- **Breakthrough events** → découvertes aléatoires limitées (1-2 niveaux max) +- **Scientific conferences** → échange breakthroughs +- **Industrial espionage** → voler breakthroughs competitors +- **Government funding** → accélère découvertes civiles + +### Interface Adaptée + +#### Vue "Recherches Disponibles" +``` +🔬 RECHERCHES DISPONIBLES +├── Acier Spécial (Métallurgie) - 100 unités fer + 50 charbon - 3 jours +├── Radar 1 (Capteurs) - 200 composants électroniques - 5 jours +└── Moteur Hybride (Propulsion) - 50 batteries + 2 moteurs - 7 jours + +🎯 BREAKTHROUGHS PROCHES (conditions presque remplies) +├── Matériaux Composites - Recherche 1 tech chimie de plus (2/3) +├── IA Tactique - Construis 3 véhicules autonomes de plus (2/5) +└── Défenses Avancées - Produis 200 tourelles de plus (150/350) + +💡 BREAKTHROUGH FORCÉ +├── Analyse Scrap: Tank T-72 → "Blindage Réactif" (coût: 5000€) +├── Reverse Engineer: GPS Civil → "Navigation Précise" (coût: 2000€) +└── Achat Intel: Thales → "Radar AESA" (coût: 50000€) +``` + +#### Découverte en Jeu +``` +🎉 BREAKTHROUGH DÉCOUVERT ! +"Matériaux Composites" + +Débloqué grâce à: Production de 1000t d'acier + 3 techs chimie + +Nouvelles recherches disponibles: +• Blindage Composite (15 jours, matériaux avancés) +• Châssis Ultra-Léger (10 jours, fibres carbone) +• Structures Adaptatives (20 jours, smart materials) +``` + +### Avantages Système + +✅ **Découverte naturelle** : Tech emerge du gameplay +✅ **Pas d'overwhelm** : Seules techs pertinentes visibles +✅ **Rejouabilité infinie** : Chaque run = découvertes différentes +✅ **Économie innovation** : Marché des breakthroughs +✅ **Emergent strategy** : Spécialisations naturelles +✅ **Surprise constante** : Toujours de nouvelles possibilités +✅ **Realistic progression** : Comme vraie R&D industrielle + +**C'est EXACTEMENT le système qu'il faut pour 3000 techs !** 🔥 + +### Vue "Passerelles" (Séparée) + +**But** : Montrer les **court-circuits possibles** depuis autres domaines +``` +Tech Cible: "Châssis Composite" + +Passerelles disponibles: +← Métallurgie : "Composites Avancés" → [PROTOTYPE] Châssis Composite +← Civil : "Matériaux Industriels" → [PROTOTYPE] Châssis Composite +← Énergie : "Matériaux Légers" → [PROTOTYPE] Châssis Composite + +Status: 2/3 passerelles débloquées ✅ +``` + +### Navigation Inter-Domaines + +**Links intelligents** : +- Tech montre ses **dépendances externes** : "Nécessite: Électronique de Base" +- **Click** → switch automatique vers vue Électronique > Circuits de Base +- **Breadcrumb** : Métallurgie > Métaux de Base ← **Électronique > Circuits de Base** + +### Vue "Action Immédiate" (Style Factorio) + +**Focus** : "**QU'EST-CE QUE JE PEUX FAIRE MAINTENANT ?**" + +**Structure verticale** : +``` +🚀 RECHERCHES DISPONIBLES (Clique pour lancer) +├── Acier (Métallurgie) - 50 points tech - 2min +├── Radar 1 (Capteurs) - 75 points tech - 3min +├── Moteur Hybride (Propulsion) - 100 points tech - 5min +└── Béton Armé (Civil) - 25 points tech - 1min + +🔬 BREAKTHROUGHS POSSIBLES (Via scrap/capture) +├── Explosifs Plastiques ← Scrap: RPG-7 (x3 disponible) +├── Blindage Composite ← Capture: Bradley M2 +└── IA Tactique ← Scrap: Drone FPV (x12 disponible) + +📚 DÉJÀ RECHERCHÉ (Masquer/Montrer) +├── ✅ Métaux de Base, Fer, Cuivre, Bronze... +├── ✅ Circuits de Base, Transistors, Processeurs... +├── ✅ Moteurs Diesel, Essence, Turbo... +└── [147 technologies researched] [Voir toutes ▼] + +🔒 PAS ENCORE ACCESSIBLE +├── Radar 2 → Nécessite: Radar 1 +├── Missiles Guidés → Nécessite: Électronique Avancée +└── Châssis Composite → Nécessite: Matériaux Composites + (ou PASSERELLE via Métallurgie Avancée) +``` + +**Priorité visuelle** : +- **ÉNORME** : Recherches disponibles (ce qu'il peut faire NOW) +- **Moyen** : Breakthroughs (opportunités spéciales) +- **Petit/Collapsé** : Déjà recherché (juste pour référence) +- **Gris** : Pas accessible (avec hints sur comment débloquer) + +### Vue "Dashboard Personnel" + +**Résumé progression** : +``` +Domaines actifs: +🔬 Métallurgie [●●●○○] 12/20 techs recherchées +⚡ Électronique [●●○○○] 8/25 techs recherchées +🏗️ Châssis [●○○○○] 3/15 techs recherchées + +Prochaines recommandations: +🎯 Acier (complète ta ligne Métaux) +🎯 Radar 1 (améliore tes drones) +🎯 Moteur Hybride (unlock Châssis Performance) +``` + +### Interface Principale : 2 Onglets + +**🎯 Onglet "ACTION"** (Vue Action Immédiate) +- **Utilisation** : 80% du temps → "Qu'est-ce que je peux faire ?" +- **Layout** : Vertical, priorité visuelle sur le disponible +- **Click & Go** : Lancer recherche directement + +**🌳 Onglet "EXPLORATION"** (Vue Arbre Linéaire) +- **Utilisation** : 20% du temps → "Où est-ce que je vais ?" +- **Layout** : Horizontal, focus sur progression +- **Planning** : Voir les chemins futurs + +### Workflow Player Typique + +1. **Ouvre l'onglet ACTION** → voit 4-6 recherches disponibles +2. **Lance une recherche** → continue à jouer +3. **Research terminée** → notification + retour onglet ACTION +4. **Nouvelles options** apparaissent → cycle continue + +Occasionnellement : +- **Switch vers EXPLORATION** → "Hmm, comment j'arrive aux missiles ?" +- **Sélectionne racine "Armement"** → voit le chemin +- **Retour ACTION** → focus sur les étapes immédiates + +### Avantages Système + +✅ **No overwhelm** : Player voit 5-15 techs max par vue +✅ **Focus** : Progression claire dans un domaine +✅ **Discovery** : Nouvelles techs révélées progressivement +✅ **Flexibilité** : Peut explorer différentes racines +✅ **Passerelles** : Vue séparée pour les court-circuits +✅ **Context** : Toujours savoir où on en est +✅ **Action immédiate** : 1 click = lancer recherche +✅ **Style Factorio** : Interface familière et efficace + +**C'est exactement l'UX qu'il faut pour 3000 techs !** 🎯 + +--- + +*Ce document sera complété avec les détails de chaque domaine technologique* \ No newline at end of file diff --git a/docs/04-reference/coherence-problem.md b/docs/04-reference/coherence-problem.md new file mode 100644 index 0000000..a48fc54 --- /dev/null +++ b/docs/04-reference/coherence-problem.md @@ -0,0 +1,486 @@ +# Problèmes de Cohérence - Documentation Warfactory + +*Analyse méthodique des incohérences et contradictions dans la documentation* + +## Contradictions Techniques Majeures + +### 1. **Architecture vs Performance Claims** ✅ RÉSOLU +**Problème original** : L'architecture décrit 10 engines séparés communiquant via Redis pub/sub et HTTP, mais revendique simultanément des performances C++/C/ASM pour "simulation temps réel complexe + milliers d'unités." + +**Solution clarifiée** : +- **War Engine self-contained** : Auto-battler avec stocks embarqués, ~500 unités actives simultanées +- **Communication par waves** : Pulls non temps réel, évite spam messages Redis +- **Latence assumée comme feature** : Délais logistiques intégrés au gameplay pour réalisme +- **Autonomie engines** : Continuent avec dernières données si communication coupée + +**Cohérence restaurée** : Performance temps réel pour combat local + communication distribuée pour coordination macro = architecture viable. + +### 2. **Factory Benchmarking System - Implémenté vs Spéculatif** ✅ RÉSOLU +**Problème original** : L'architecture présente le factory benchmarking comme une fonctionnalité implémentée, tandis que gameplay-industriel le décrit comme spéculatif. + +**Solution adoptée** : Fonctionnalité entière reportée en long-term update +- Status uniforme : "Long-term Update" dans tous les documents +- Justification : Optimisation prématurée, focus sur gameplay core d'abord +- Concept conservé pour développement futur + +**Cohérence restaurée** : Plus de contradiction entre documents sur le status d'implémentation. + +### 3. **Définitions de Taille de Chunk et Resource Patches** ✅ RÉSOLU +**Problème original** : Contradiction entre resource chunks 64x64 (systemes-techniques) et resource patches de forme libre (map-system). + +**Solution adoptée** : +- **Resource chunks supprimés** de systemes-techniques.md +- **Resource patches uniquement** : Système Factorio-like avec formes libres non-alignées +- **Architecture chunks clarifiée** : Multi-échelle pour différents types de données + - 512x512 : landId (terrain) + - 256x256 : buildingPtr (bâtiments) + - 128x128 : effectId (effets) + - 64x64 : Chunk principal gameplay (map-system) + +**Cohérence restaurée** : Plus de contradiction resource chunks vs patches, architecture multi-échelle documentée. + +## Problèmes d'Échelle et de Scope + +### 4. **Crise de Découvrabilité de l'Arbre Technologique** ✅ INVALIDÉ +**Problème original** : Revendique 3000+ technologies avec découverte gatée par breakthrough, créant une courbe d'apprentissage impossible. + +**Analyse erronée** : La critique était basée sur incompréhension du système breakthrough "Natural" + +**Documentation existante** : +- **metriques-joueur.md** : "Sources de découverte : Ratio Scrap vs Natural vs Events vs Purchase" +- **arbre-technologique.md** : "découvert via scrap/capture/événement" + "Trigger immédiat lors d'événements" +- **architecture-technique.md** : Event Engine gère "breakthrough_event → Designer, Economy" + +**Système réel** : Breakthroughs "Natural" = événement-driven automatiques +- Combat → breakthrough armor automatique ("Better Tank Armor" se débloque naturellement quand tanks prennent dégâts) +- Production → breakthrough efficiency automatique +- Observation → breakthrough reverse engineering automatique + +**Cohérence confirmée** : 3000 techs accessibles via gameplay naturel, pas de courbe d'apprentissage impossible. + +### 5. **Complexité Design Militaire vs Faisabilité Gameplay** ✅ INVALIDÉ +**Problème original** : Le système de design de véhicules est si complexe qu'il serait injouable. + +**Analyse erronée** : Critique basée sur lecture superficielle ignorant les mécaniques d'accessibilité + +**Éléments ratés dans l'analyse initiale** : +- **Système 2D** : Plus simple et lisible que design 3D +- **Progression tech-gated** : Commence avec composants simples (Gen1), complexité progressive +- **Premier véhicule** : Moteur + cargo + siège = 10-20min, pas 1500 composants +- **Blueprints multi-échelles** : 4 niveaux (Micro/Layer/System/Vehicle) avec drag&drop +- **Workshop communautaire** : Blueprints partagés, système optionnel +- **Assistance IA** : Designer Engine peut créer véhicules automatiquement + +**Documentation complète existante** : +- Gen1 "simples, réparables" vs Gen4 complexes +- Interface blueprints avec drag&drop documentée +- Exemples visuels progression (rectangle simple → formes complexes) +- Système amélioration avec diminishing returns clairement expliqué + +**Comparaison corrigée** : Même principe que Factorio (simple → complexe progressif) + +**Cohérence confirmée** : Système accessible débutants + profond experts, développement itératif par équipe (Claudes 🤖). + +### 6. **Inadéquation d'Échelle Économique** ✅ RÉSOLU +**Problème original** : L'échelle de production ne correspond pas à l'échelle économique. + +**Solution clarifiée** : Le jeu est un bac à sable où le joueur choisit librement son échelle d'opération +- **Spectrum complet** : Du petit artisan local au géant multinational concurrent de Thales/Lockheed Martin +- **Aucune progression forcée** : Le joueur peut rester petit artisan toute la partie s'il le souhaite +- **Reconversion industrielle** : Difficulté basée sur similarité des processus (tables→blindages facile, tables→canons complexe) +- **Flexibilité par design** : Le joueur définit ses ambitions selon ses préférences + +**Documentation mise à jour** : Section "Philosophie Bac à Sable" ajoutée à gameplay-industriel.md + +**Cohérence restaurée** : L'exemple "tables fer" illustrait la flexibilité de reconversion, pas une incohérence d'échelle. + +## Intégrations Critiques Manquantes + +### 7. **Responsabilités des Engines Indéfinies** +**Problème** : Pas de mapping clair entre les engines architecturaux et les systèmes de gameplay actuels. + +**Fichiers** : `architecture-technique.md`, tous les docs gameplay + +**Pourquoi c'est un problème** : L'architecture décrit 10 engines mais n'explique pas comment les systèmes de gameplay complexes (comme les features company, design véhicules, ou breakthroughs technologiques) mappent sur ces engines. + +### 8. **Isolation du Système de Points d'Administration** ✅ RÉSOLU +**Problème original** : Le système complexe de points d'administration n'apparaît que dans un seul document. + +**Solution clarifiée** : MacroEntity Engine gère entièrement le système d'administration +- **Architecture intégrée** : MacroEntity Engine responsable companies/états + pools administration +- **Communication** : Autres engines consultent admin via API, actions refusées si exhausté +- **Isolation assumée** : Système admin isolé par design, seul MacroEntity Engine l'utilise +- **Performance** : Calculs légers, batch processing, rythme bas adapté gameplay macro +- **Joueur exempt** : Pas de contraintes administration pour le joueur +- **Équilibrage** : Coûts admin recherche faibles pour ne pas freiner progression tech + +**Documentation mise à jour** : Architecture-technique.md et questions-ouvertes.md + +**Cohérence restaurée** : Système administration correctement intégré dans l'architecture multi-engines. + +### 9. **Conflit Designer Engine vs Design Joueur** ✅ RÉSOLU +**Problème original** : Peu clair comment le design IA de véhicules (Designer Engine) coexiste avec le design manuel joueur. + +**Solution clarifiée** : +- **Même système** : IA et joueur utilisent le Designer Engine identique +- **Procédural vs Manuel** : IA utilise random generation + evaluate, joueur design manuellement +- **Assistance joueur** : Joueur peut utiliser l'IA design du Designer Engine +- **Blueprints doctrinaux** : Grilles efficaces (dev, captures, retex) guident génération IA +- **Company features** : Influencent choix procéduraux IA (modify vs nouveau design) +- **Évaluation viabilité** : Check automatique "design viable ?" (tank 1km/h = reject) + +**Cohérence restaurée** : Designer Engine unifié sert joueur ET IA avec méthodes différentes mais système commun. + +## Impossibilités Architecturales + +### 10. **Terminaux Idiots vs Streaming Carte Complexe** ✅ RÉSOLU +**Problème original** : Les clients décrits à la fois comme "terminaux idiots" et gérant un streaming carte complexe. + +**Solution clarifiée** : Architecture Smart Client / Authoritative Server +- **Client Smart** : Interface complexe, rendu 2D optimisé, streaming carte intelligent, cache local +- **Client Dumb** : Aucune simulation gameplay, pas de logique métier, pas d'état de jeu +- **Responsabilités claires** : UI/rendu côté client, simulation côté serveur +- **Anti-cheat naturel** : Server authoritative pour toute logique métier +- **Performance** : Cache client pour UI réactive, LOD et culling côté client + +**Documentation mise à jour** : Architecture-technique.md et questions-ouvertes.md + +**Cohérence restaurée** : Terminologie précise remplace "dumb terminal" réducteur. + +### 11. **Engines Autonomes vs Coordination Centrale** ✅ RÉSOLU +**Problème original** : Les engines décrits comme autonomes mais nécessitant coordination centrale. + +**Solution clarifiée** : Central Coordinator est un Meta Orchestrator aveugle au gameplay +- **Engines 100% autonomes** : Toute logique gameplay, communication directe Redis +- **Coordinator ultra-limité** : Bootstrap, health ping, time sync, shutdown +- **Aveugle total** : Ne connaît rien des mécaniques de jeu, pure infrastructure +- **Post-bootstrap** : Coordinator passif, engines communiquent directement +- **Crash-safe** : Coordinator down = invisible pour gameplay, engines continuent +- **Lifecycle only** : Start/stop, unload map (quit partie), rien d'autre + +**Documentation mise à jour** : Architecture-technique.md clarifiée + +**Cohérence restaurée** : Pas de contradiction - engines autonomes + orchestrator infrastructure dumb. + +### 12. **Performance Temps Réel vs Architecture Distribuée** ✅ RÉSOLU - Voir P1 +**Problème original** : Exigences temps réel incompatibles avec l'architecture distribuée proposée. + +**Solution** : Problème déjà résolu dans P1 - Architecture vs Performance Claims +- **War Engine self-contained** : Auto-battler autonome, ~500 unités actives simultanées +- **Communication async** : Pulls par waves, pas de coordination temps réel requise +- **Performance isolée** : War Engine indépendant = pas de bottleneck réseau +- **Distribution pour le reste** : Economy, Operation, etc. peuvent être async + +**Cohérence confirmée** : P12 était un doublon de P1 sous angle différent. + +## Inadéquation Narrative vs Scope Technique + +### 13. **Focus Ukraine vs Mécaniques Globales** ✅ INVALIDÉ +**Problème supposé** : Le contexte narratif est entièrement focalisé Ukraine tandis que les mécaniques de jeu sont globales. + +**Analyse erronée** : Aucune contradiction réelle identifiée + +**Système réel** : Richesse géographique comme feature majeure +- **Ukraine dense/épique** : "Slava Ukraini" - high stakes, résistance héroïque, complexité diplomatique +- **Congo/Sahara détente** : Mad Max warlords, contrôle ressources minières, sandbox pur +- **Même système unifié** : Supporte expériences totalement différentes selon mood joueur +- **Hommage renforcé** : Choisir Ukraine = respect, pas limitation technique + +**Richesse du design** : Player peut alterner entre intensité Ukraine et détente sahélienne + +**Cohérence confirmée** : Système global enrichit l'expérience, pas de contradiction narrative. + +## Lacunes Logiques + +### 14. **Lacune Logique Stabilisation Factory** ✅ RÉSOLU +**Problème original** : Les systèmes factory sensibles à la qualité ne peuvent pas devenir de simples lookup tables. + +**Solution clarifiée** : Skip vs Optimize Trade-off par design +- **Factory tout-en-un** : Lookup tables disponibles mais efficacité médiocre +- **Factory Factorio** : Placement précis, qualité, thermique pour efficacité maximale +- **Player choice** : Commodité vs performance selon mood/skill/temps +- **Principe général** : "Tous les systèmes du jeu doivent pouvoir être skippés" +- **Accessibilité + Depth** : Noobs peuvent skip, pros peuvent optimiser + +**Design philosophy** : Trade-off intentionnel, pas contradiction logique + +**Cohérence restaurée** : Coexistence lookup tables et depth gameplay via player choice. + +### 15. **Lacune Logique Système de Recherche** ✅ OBSOLÈTE +**Problème supposé** : Le système de recherche dual (points vs XP+scrap) crée des chevauchements confus. + +**Système actuel** : Plus d'actualité - évolution design +- **Breakthrough system** : Event-driven, scrap analysis, recherche avancée +- **Conversion 50% XP** : Artefact documentation, système abandonné +- **Restrictions domaines** : Plus dans design final +- **Research paths** : Système simplifié et cohérent + +**Cohérence confirmée** : Problème résolu par évolution du design, plus de contradiction. + +## Nouveaux Problèmes Identifiés (Analyse Décembre 2024) + +### 16. **Contradiction Métriques vs Architecture Distribuée** ✅ RÉSOLU +**Problème original** : Le système de métriques nécessite une collecte centralisée massive qui contredit l'architecture distribuée autonome. + +**Solution clarifiée** : Intelligence Engine collecte les métriques économiques +- **Intelligence Engine étendu** : Reconnaissance militaire + métriques économiques/industrielles +- **Volume gérable** : 7.75 MB/heure pour engine d'analyse spécialisé +- **Pull-based** : Intelligence Engine interroge autres engines via HTTP GET /metrics +- **Engines autonomes** : Répondent aux queries metrics mais s'en foutent du collecteur +- **Cohérence thématique** : Intel militaire + analyse économique = même domaine data analysis +- **Pas de SPOF critique** : Si Intelligence Engine crash, gameplay continue + +**Documentation à mettre à jour** : Architecture-technique.md et metriques-joueur.md + +**Cohérence restaurée** : Collection métriques intégrée dans architecture distribuée sans casser autonomie. + +### 17. **Incohérence Système Administration vs Performance Temps Réel** ✅ INVALIDÉ +**Problème supposé** : Points d'administration avec calculs complexes contredisent performances temps réel C++/ASM. + +**Analyse erronée** : Malentendu sur la fréquence réelle des actions + +**Système réel clarifié** : +- **Rythme macro** : ~1 action tous les 3-5 jours par company (pas frénétique) +- **Volume computational** : ~0.33 actions/seconde pour 1000 companies = dérisoire +- **Performance impact** : 20 vérifications/minute = négligeable vs temps réel +- **1 jour = 10 minutes réelles** : Administration suit rythme stratégique lent + +**Documentation mise à jour** : Fréquence actions clarifiée dans mecaniques-jeu.md + +**Cohérence confirmée** : Système administration compatible avec performance temps réel. + +### 18. **Scope Mismatch: Arbre Technologique vs Système Breakthrough** ✅ INVALIDÉ +**Problème supposé** : 3000 technologies annoncées vs système breakthrough organique qui ne peut supporter ce volume. + +**Analyse erronée** : Assumptions techniques incorrectes sur scaling + +**Système réel** : Breakthrough system peut scaler à 3000 techs +- **Prerequisites gating** : Seulement ~10-50 techs eligible simultanément, pas 3000 +- **Ticker optimisé** : Check conditions toutes les minutes, pas 60fps +- **Conditions on-demand** : Query engines ponctuellement, pas polling constant +- **Scrap analysis** : Utile early game uniquement (rattrapage tech), mid/late = autres sources +- **Interface proven** : Factorio gère 100+ techs, design for scale = standard practice +- **Design philosophy** : Player ne recherche PAS tout - chaque run = découvertes différentes, combinaisons nouvelles, rejouabilité + +**Cohérence confirmée** : Breakthrough system compatible avec 3000 technologies via design approprié. + +### 19. **Contradiction Gameplay Skip vs Système de Qualité** ✅ INVALIDÉ +**Problème supposé** : Philosophie "tous systèmes skippables" contredit mécaniques qualité militaire obligatoires. + +**Analyse erronée** : Ignorait l'économie comme solution de skip + +**Système réel** : Skip disponible via marketplace économique +- **Player skip** : Achète véhicules aux IA companies (Thales, Lockheed, etc.) +- **Templates préconçus** : IA a résolu placement/synergies/thermique selon mêmes règles +- **Player optimize** : Design manuel pour performance supérieure avec skill/temps +- **Même contraintes** : IA doit respecter règles qualité, player peut faire mieux +- **Player choice** : Commodité (achat IA) vs performance (design manuel) selon préférences + +**Cohérence confirmée** : Principe skip vs optimize s'applique au militaire via économie. + +### 20. **Incohérence Map System Local vs Global Combat** ✅ INVALIDÉ +**Problème supposé** : Chunks 64x64 pour combat local vs promesse batailles "milliers d'unités". + +**Analyse erronée** : Assumait 1 bataille = 1 chunk, ignorait système global + +**Système réel** : Batailles multi-chunks et guerre persistante +- **Frontlines étendues** : Batailles s'étendent sur dizaines/centaines de chunks simultanément +- **Guerre persistante** : Bataille dure 1 an dans le monde (ex: player base Bakhmut = 1 an combat) +- **Système total** : "Milliers d'unités" = capacité système global, pas bataille locale +- **Répartition réaliste** : ~500 unités War Engine dispersées sur grande zone géographique +- **Chunk 64x64** = unité streaming/gameplay, pas limite bataille + +**Cohérence confirmée** : Échelle map locale compatible avec système combat global étendu. + +### 21. **Contradiction Ressources Patches vs Infrastructure Processing** ✅ INVALIDÉ +**Problème supposé** : Resource patches formes libres contredisent infrastructure Factorio-like qui nécessite alignement grille. + +**Analyse erronée** : Problème de formulation dans documentation + +**Système réel clarifié** : Patches alignés sur grille tiles, pas sur chunks +- **Grid-aligned** : Patches alignés sur grille tiles 1x1 (mining drills compatible) +- **Forme libre** : Shape non-rectangulaire (L, C, etc.) mais toujours sur grille +- **Infrastructure standard** : Belts, drills, pipelines fonctionnent normalement +- **Pas chunk-aligned** : Patches peuvent déborder sur plusieurs chunks (pas problème) +- **Placement optimal** : Calculs géométriques standard sur grille régulière + +**Documentation mise à jour** : Clarification grid-aligned vs chunk-aligned dans map-system.md + +**Cohérence confirmée** : Infrastructure Factorio-like compatible avec patches organiques grid-aligned. + +### 22. **Volume Données Métriques vs Architecture Multi-Joueur** ✅ RÉSOLU +**Problème original** : 3.1GB métriques par partie incompatible avec multijoueur. + +**Solution implémentée** : Scaling adaptatif et data sharing intelligent +- **Joueurs même company** : Data partagée - 1 seul dataset 3.1GB pour toute la company +- **Free-for-all scaling** : Points réduits proportionnellement au nombre de companies + - **1 company** : 2 points/min (granularité fine) + - **5 companies** : 0.4 points/min (granularité réduite) + - **Minimum** : 0.25 points/min (seuil qualité acceptable) +- **Volume constant** : ~3.1GB total même avec 10 joueurs/companies +- **Intelligence Engine** : Collecte adaptée selon configuration multijoueur + +**Architecture supportée** : Redis/network gère volume constant via scaling intelligent + +**Cohérence restaurée** : Système métriques compatible multijoueur via adaptation granularité. + +### 23. **Contradiction Points Budget Génération vs Variabilité Infinie Promise** ✅ RÉSOLU +**Problème original** : Génération procédurale promettait scores -6 à +6 (13 valeurs) avec ~40 éléments = quelques milliers de combinaisons, pas millions. + +**Solution implémentée** : Expansion massive du système de génération +- **Budget étendu** : -10 à +10 (21 valeurs cibles) avec distribution en cloche +- **218 éléments** : 6 catégories complètes (géologiques, aquatiques, terrestres, côtières, industrielles, militaires, culturelles, biomes, climatiques, anthropiques, mystérieux) +- **Combinatoire explosive** : C(218,2-4) × 21 scores = **~2 milliards de configurations uniques** +- **Distribution réaliste** : 30% neutre, 40% commun (±1-3), 20% remarquable (±4-6), 8% exceptionnel (±7-8), 2% légendaire (±9-10) + +**Résultat** : Promesse "millions de combinaisons" largement dépassée avec plusieurs milliards de variantes possibles. + +**Cohérence restaurée** : Système procédural supporte variabilité massive promise. + +### 24. **Incohérence Designer Engine Time-Budget vs Performance Temps Réel** ❌ INVALIDÉ +**Problème original** : Mauvaise interprétation - "1-2 tetris par tick" était supposé être × 1000 companies = 120k opérations/seconde. + +**Clarification** : +- **"1-2 design/tick"** = performance globale du système, pas par company +- **Total mondial** : 1-2 nouveaux designs créés dans le monde entier par tick +- **Charge réelle** : 1-2 opérations/tick à 60fps = 60-120 opérations/seconde maximum +- **Parfaitement viable** : Volume trivial pour architecture C++/ASM moderne + +**Problème basé sur mauvaise lecture** de la spécification technique. + +**Statut** : Pas de problème de cohérence réel. + +### 25. **Contradiction Multi-Échelle Chunk vs Single Chunk Combat** ❌ INVALIDÉ +**Problème supposé** : Architecture 4 échelles contredit War Engine utilisant chunks 64x64 pour 500 unités. + +**Doublon de P20** : Même problématique déjà résolue + +**Système réel déjà documenté** : +- **Combat multi-chunks** : Batailles s'étendent sur dizaines/centaines de chunks +- **Frontlines persistantes** : Guerre peut durer 1 an (ex: Bakhmut) +- **500 unités dispersées** : Sur grande zone géographique, pas concentrées sur 4096m² +- **Chunk 64x64** : Unité de streaming/gameplay, pas limite de bataille + +**Statut** : Doublon de problème déjà résolu en P20. + +### 26. **Impossibilité Logique Interface Blueprint vs Grille Component Variée** ❌ INVALIDÉ +**Problème supposé** : Drag & drop + formes irrégulières + rotations = complexité UI insurmontable. + +**Interface standard parfaitement viable** : +- **Pick/Place** : Clic pour sélectionner, drag, clic pour placer avec snap automatique +- **Rotations** : A/E (standard jeux PC) +- **Snap toggle** : R pour désactiver/activer grille +- **Templates** : Designs pré-faits, guides visuels +- **Zone staging** : Inventaire latéral pour composants temporaires + +**Précédents fonctionnels** : +- **Escape from Tarkov** : Inventaire tetris plus complexe, joueurs adorent optimiser +- **Factorio** : Même système exact de placement sur grille +- **Space Engineers** : Grille 3D + contraintes + physique, interface viable +- **Satisfactory** : Placement 3D encore plus complexe + +**Faux problème** : Les joueurs aiment optimiser leurs designs. C'est le gameplay, pas un obstacle. + +### 27. **Contradiction Volume Métriques vs Background Processing Promise** ❌ INVALIDÉ +**Problème supposé** : 3.1GB métriques nécessitent processing constant en RAM, impossible pendant combats. + +**Mauvaise compréhension architecture** : +- **3.1GB = stockage database**, pas données en RAM +- **Push/Pull ponctuel** : Écriture periodique vers DB, lecture à la demande +- **RAM footprint minimal** : Quelques valeurs courantes en mémoire (~KB) +- **Processing léger** : Agrégation simple lors push/pull, pas compute continu +- **Background viable** : DB operations asynchrones, impact CPU négligeable + +**Architecture réelle** : +- Intelligence Engine écrit métriques vers DB périodiquement +- Interface métriques lit DB à la demande (pas streaming continu) +- Combat et métriques complètement découplés + +**Statut** : Mauvaise compréhension du stockage vs processing. + +### 28. **Incohérence Système Température vs Auto-battler Promise** ❌ INVALIDÉ +**Problème supposé** : Gestion thermique trop complexe pour auto-battler. + +**Gestion automatique standard** : +- **Comme les munitions** : Quand ressource (température/munitions) s'épuise → retrait automatique +- **Fire & scoot automatique** : IA gère cycles tir/refroidissement comme tanks réels +- **Règles simples** : + - Surchauffe proche → retraite temporaire + - Température OK → reprise combat + - Comme gestion carburant/munitions dans RTS classiques + +**Précédents viables** : +- **World in Conflict** : Gestion automatique munitions/carburant +- **Steel Division** : Stress/fatigue gérés par IA +- **Command & Conquer** : Auto-retreat quand low health + +**Faux problème** : Température = une ressource comme les autres, facilement automatisable. + +### 29. **Architecture Smart Client vs Volume Data Streaming Impossible** ❌ INVALIDÉ +**Problème supposé** : Client smart ne peut gérer volume data streaming 4 échelles + patches + FOW + historical data. + +**Architecture réelle - Pas de streaming continu** : +- **Historical data** : Pas streamées, stockage local/DB +- **Chunks** : Demande ponctuelle selon besoin (pas streaming continu) +- **FOW granularité chunk** : Ultra léger, juste visibility flags +- **4 échelles** : Chargement à la demande selon zoom, pas simultané +- **Patches** : Metadata légère, pas géométries complètes + +**Volume réel minimal** : +- **FOW** : ~1 bit par chunk = négligeable +- **Chunk request** : Ponctuel, quelques KB par demande +- **Pas de streaming** : Simple request/response pattern + +**Faux problème** : Confond streaming continu vs requests ponctuels légers. + +### 30. **Contradiction Arbre Tech 3000 vs UI Discovery System** ❌ INVALIDÉ +**Problème supposé** : Interface "5-15 techs visibles max" vs breakthrough débloqueant 20+ techs simultanément. + +**Doublon de P18** : Même problématique déjà résolue + +**Système réel déjà documenté** : +- **Prerequisites gating** : Seules 10-50 techs éligibles simultanément (pas 3000) +- **Player pas censé tout rechercher** : Focus spécialisations comme dans jeux réels +- **Interface proven** : Factorio gère 100+ techs successfully +- **Design adaptatif** : UI peut temporairement montrer plus lors breakthroughs majeurs + +**Statut** : Doublon de problème déjà résolu en P18. + +## Conclusions + +### Analyse Complète Terminée +**30 problèmes identifiés** analysés et résolus : +- **8 problèmes réels résolus** (P7, P8, P10, P16, P17, P18, P21, P22, P23) +- **11 problèmes invalidés** par clarifications (P1, P2, P3, P4, P5, P6, P9, P11, P12, P13, P14, P15, P19, P20, P24, P26, P27, P28, P29, P30) +- **3 doublons éliminés** (P25=P20, P30=P18) + +### État de Cohérence Actuel +**Documentation cohérente** : La majorité des "problèmes" provenaient de : +- **Mauvaises lectures** de spécifications techniques +- **Assumptions incorrectes** sur l'architecture +- **Incompréhensions** des systèmes de jeu +- **Manque de contextualisation** cross-système + +### Améliorations Apportées +- **Clarifications architecturales** : Engines, autonomie, performance +- **Expansion génération procédurale** : 218 éléments, budget -10/+10 +- **Précisions timing** : Administration, métriques, breakthrough +- **Interface design** : Spécifications UI complétées +- **Cross-références** : Liens entre systèmes établis + +**Verdict final** : **Projet techniquement viable** avec documentation maintenant cohérente. + +## Actions de Suivi + +### Problèmes Restants à Traiter +**P7** : Responsabilités engines → Continuer analyse architecture (identifié comme réel) + +### Prochaines Étapes Documentation +1. **Validation technique** : Review implémentation faisabilité +2. **Tests cohérence** : Vérification cross-système +3. **Mise à jour références** : Synchronisation entre docs + +### Recommandations +- **Documentation technique** : Maintenant solide et cohérente +- **Implémentation** : Aucun blocage majeur identifié +- **Design** : Systèmes compatibles et réalisables \ No newline at end of file diff --git a/docs/04-reference/content-integrated.md b/docs/04-reference/content-integrated.md new file mode 100644 index 0000000..d4efd35 --- /dev/null +++ b/docs/04-reference/content-integrated.md @@ -0,0 +1,122 @@ +# Points Intégrés - Content Integrated + +## Points 1-10 - Architecture Fondamentale INTÉGRÉS + +### 🔥 Architecture Core (CRITICAL) - INTÉGRÉS +**1. Triple Interface Pattern** - IEngine → IModuleSystem → IModule → IIO pour séparation complète responsabilités +- ✅ **Intégré** : CLAUDE.md ligne 42 + +**2. Évolution Progressive Architecture** - Debug → Production → DataOriented avec hot-swappable infrastructure +- ✅ **Intégré** : CLAUDE.md architecture modulaire + +**3. Claude Code Micro-Context** - Modules 200-300 lignes max pour efficacité IA développement +- ✅ **Intégré** : CLAUDE.md ligne 44 + +**4. Client/Server Modulaire** - V1 Thin Client validation → V2 Shared Logic prediction +- ✅ **Intégré** : CLAUDE.md ligne 42 + +**5. Distribution Performance-Based** - Critical locale, Strategic distribuée selon tolérance latence +- ✅ **Intégré** : CLAUDE.md ligne 45 + +### ⚡ Workflow Développement (HIGH) - INTÉGRÉS +**6. Build Autonome** - `cmake .` par module, zéro dépendance parent +- ✅ **Intégré** : CLAUDE.md lignes 99-101 + +**7. Hot-Reload Infrastructure** - Remplacement temps réel modules avec sauvegarde état +- ✅ **Intégré** : docs/architecture-technique.md section Hot-Reload Infrastructure + +**8. Développement Parallèle** - Multiple instances Claude Code simultanées sans conflits +- ✅ **Intégré** : docs/toCheck/claude-code-integration.md lignes 80-100 +- ✅ **Intégré** : docs/toCheck/AddToClaudemd.md Point 8 + +**9. CLAUDE.md Spécialisés** - Instructions contextuelles limitées par module +- ✅ **Intégré** : docs/toCheck/claude-code-integration.md lignes 102-147 +- ✅ **Intégré** : docs/toCheck/AddToClaudemd.md Point 9 + +**10. Migration V1→V2** - Évolution sans risque architecture client/server +- ✅ **Intégré** : docs/architecture-technique.md lignes 568-585 +- ✅ **Intégré** : docs/toCheck/AddToClaudemd.md Point 10 + +## Statut Intégration +- **Points 1-10** : ✅ **COMPLÈTEMENT INTÉGRÉS** +- **Points 86-89** : ✅ **INTÉGRÉS** - Contraintes CRITICAL dans CLAUDE.md +- **Points 90-95** : ✅ **INTÉGRÉS** - Transport costs dans transport-economic-system.md +- **Point 131** : ✅ **INTÉGRÉ** - ProductionModule exception dans CLAUDE.md +- **Point 166** : ✅ **INTÉGRÉ** - IModule interface dans CLAUDE.md +- **Points 126-130, 135, 42-44** : ✅ **INTÉGRÉS** - Diverses contraintes + +## Nouveaux Points Intégrés (98-104) +**98. V1 Client Target** - 30+ fps stable +- ✅ **Intégré** : docs/architecture-technique.md section V1 + +**99. V2 Client Target** - 60+ fps avec prediction +- ✅ **Intégré** : docs/architecture-technique.md section V2 + +**100. V1 Server Capacity** - 10+ concurrent players +- ✅ **Intégré** : docs/architecture-technique.md section V1 + +**101. V2 Server Capacity** - 100+ concurrent players +- ✅ **Intégré** : docs/architecture-technique.md section V2 + +**102. V1 Latency** - <150ms validation acceptable +- ✅ **Intégré** : docs/architecture-technique.md section V1 + +**103. V2 Network** - 30ms server, 0ms perceived client +- ✅ **Intégré** : docs/architecture-technique.md section V2 + +**104. ISocket Overhead** - >1ms INACCEPTABLE ProductionModule +- ✅ **Intégré** : CLAUDE.md Module Constraints + +## Points 251-350 Intégrés - Configuration, Error Handling, Security & Deployment +**251-290. Configuration Parameters** - Transport thresholds, costs, times, storage, stock levels, construction costs +- ✅ **Intégré** : docs/configuration/ (transport-economic-system.md + module-configuration.md) + +**291-310. Error Handling** - Anti-cheat validation, input responses, module failures, network issues +- ✅ **Intégré** : docs/configuration/error-handling.md + +**311-330. Security Measures** - Server authority, anti-cheat, client prediction, psychological warfare +- ✅ **Intégré** : docs/configuration/security-measures.md + +**331-350. Deployment Strategies** - Progressive V1→V2, hot-reload production, A/B testing +- ✅ **Intégré** : docs/configuration/deployment-strategies.md +- ✅ **Organisé** : Dossier configuration complet avec README + +## Points 351-390 Intégrés - Claude Code Development Practices +**351-390. Development Practices** - Claude Code limits, parallel development, build patterns, testing +- ✅ **Intégré** : CLAUDE.md section "Claude Code Development Practices (Points 351-390)" + +## Points 391-430 Déjà Intégrés - Integration Patterns +**391-430. Integration Patterns** - Module communication, engine coordination, client-server sync +- ✅ **Déjà intégré** : architecture-technique.md (Triple Interface, JSON, hot-reload) +- ✅ **Déjà intégré** : architecture-modulaire.md (IEngine/IModuleSystem/IModule/IIO) +- ✅ **Déjà intégré** : claude-code-integration.md (Module coordination, builds) +- ✅ **Déjà intégré** : player-integration.md (Client-server sync) + +## Points 431-470 Déjà Intégrés - User Experience +**431-470. User Experience** - Latency targets, hot-reload UX, config modification, multiplayer sync +- ✅ **Déjà intégré** : architecture-technique.md (Performance targets V1/V2, latency specs) +- ✅ **Déjà intégré** : player-integration.md (30+fps/60+fps, 150ms/0ms latency) +- ✅ **Déjà intégré** : docs/configuration/ (Hot-reload UX, config modification) +- ✅ **Déjà intégré** : factory-architecture-post-player.md (Frame-perfect 60fps) + +## Points 471-570 Déjà Intégrés - Business Logic & Build System +**471-510. Business Logic Rules** - Transport hierarchy, volume thresholds, economic cycles, pricing +- ✅ **Déjà intégré** : docs/configuration/transport-economic-system.md (Ship 0.10€/kg → Truck 5.00€/kg) + +**511-530. File Structure** - Module directories, client/server/shared, naming conventions +- ✅ **Déjà intégré** : architecture-technique.md (modules/ structure, CLAUDE.md pattern) +- ✅ **Déjà intégré** : README.md (Development workflow, file organization) + +**531-570. Build System Details** - Commands, CMake structure, dependencies, libraries +- ✅ **Déjà intégré** : architecture-technique.md (cmake ., NEVER/ALWAYS patterns) +- ✅ **Déjà intégré** : CLAUDE.md (Build commands, project structure) + +## Points 136-142 Déjà Intégrés - Interface Contracts +**136-142. Interface Contracts** - JSON in/out, pure functions, pas side effects +- ✅ **Déjà intégré** : architecture-technique.md (JSON in/out uniquement, logic métier pure) +- ✅ **Déjà intégré** : architecture-modulaire.md (JSON communication, aucune dépendance infrastructure) +- ✅ **Déjà intégré** : claude-code-integration.md (Pure logic only, JSON messages) + +## Total Intégré : 357 points sur 570 +- **Localisation** : CLAUDE.md, architecture-technique.md, claude-code-integration.md, docs/configuration/ +- **Restant** : 131 points spécifiés + 82 non-spécifiés à traiter \ No newline at end of file diff --git a/docs/04-reference/effets-attendus.md b/docs/04-reference/effets-attendus.md new file mode 100644 index 0000000..4662696 --- /dev/null +++ b/docs/04-reference/effets-attendus.md @@ -0,0 +1,89 @@ +# Effets Attendus du Système Économique + +Ce document compile les **effets émergents prédits** du système économique de Warfactory. Ces comportements ne sont **PAS** implémentés directement mais devraient émerger naturellement des mécaniques économiques de base. + +## Point 30 : Dynamiques Côtières + +**Cycle auto-régulateur prédit** résultant des avantages géographiques (Point 27) : + +### Phase 1 - Rush Initial +- **Coastal advantage** : Ship transport 0.10€/kg (50x moins cher que truck 5.00€/kg) +- **Mass migration** : Companies rush vers locations côtières +- **Early profits** : Massive competitive advantage pour first-movers + +### Phase 2 - Développement Rareté +- **Land scarcity** : Prix foncier côtier augmente via demande +- **Premium costs** : Coûts location/acquisition deviennent prohibitifs +- **Resource competition** : Lutte intense pour emplacements côtiers optimaux + +### Phase 3 - Limites Infrastructure +- **Congestion costs** : Infrastructure portuaire saturée +- **Throughput limits** : Ports atteignent capacité maximum +- **Efficiency decrease** : Performance dégradée via embouteillages + +### Phase 4 - Equilibrium Naturel +- **Cost parity** : Total costs côtier = inland (après factorisation tous coûts) +- **Labor premiums** : Salaires côtiers augmentent vs régions isolées +- **Economic balance** : Avantage transport neutralisé par coûts indirects + +## Mécanisme Sous-Jacent + +**Pas d'implémentation spécifique requise** - émerge naturellement de : +- Transport costs hierarchy (Ship→Rail→Air→Truck) +- Infrastructure access binary (hasPortAccess boolean) +- Market-driven pricing (supply/demand) +- ROI infrastructure calculations + +**Prédiction** : Le système créera automatiquement ce cycle sans scripting explicite. + +## Point 38 : Cascades Économiques + +**Système de propagation automatique** : Events → Impact direct → Ripple effects → Cascades macro + +### Resource Discovery Economic Cascades +**Découverte nouvelle ressource déclenche cascades prédictibles :** + +**Séquence automatique :** +1. **Immediate local effects** : Land value increase, investment attraction +2. **Regional economic shifts** : Trade route realignment, competitor responses +3. **Market adjustments** : Global pricing changes, supply chain redistribution +4. **New markets emerge** : Regional economic boom, infrastructure development + +**Mécanisme sous-jacent :** Economic agents rational response → Market rebalancing + +### War Economic Impact Cascades +**Conflits militaires génèrent disruptions économiques systémiques :** + +**Propagation séquentielle :** +1. **Military conflict** → Supply chain disruption (transport routes affected) +2. **Resource scarcity** → Price inflation (artificial scarcity effects) +3. **War production** → Economic restructuring (civilian→military production shift) +4. **Post-war recession** → Market readjustment (return to civilian economy) + +### Technology Economic Disruption +**Breakthroughs technologiques créent social & economic upheaval :** + +**Cascade sociale :** +1. **Automation breakthrough** → Productivity gains (industry efficiency) +2. **Labor displacement** → Unemployment spike (job obsolescence) +3. **Wage pressure** → Social unrest (economic inequality) +4. **Government intervention** → Economic policy changes (regulatory response) + +### Player Decision Ripples +**Actions player génèrent effets macro non-intentionnels :** + +- **Factory expansion** → Local job creation → Population growth → Market demand increase +- **Resource hoarding** → Artificial scarcity → Price manipulation → Competitor response +- **Technology research** → Industry disruption → Economic transformation → Social change + +## Système Technique Sous-Jacent + +**Pas d'implémentation spécifique requise** - émergence naturelle via : +- MarketModule price discovery automatique +- Supply/demand dynamics existing +- Economic agent rational behavior (Point 36) +- Transport cost optimization (Points 24-26) + +**Event propagation** : Economic modules communiquent via existing architecture → Cascades émergent naturellement + +**Prédiction** : L'interaction des systèmes économiques existants créera automatiquement ces cascades complexes sans programmation explicite. \ No newline at end of file diff --git a/docs/04-reference/mecaniques-jeu.md b/docs/04-reference/mecaniques-jeu.md new file mode 100644 index 0000000..4b10518 --- /dev/null +++ b/docs/04-reference/mecaniques-jeu.md @@ -0,0 +1,525 @@ +# Mécaniques de jeu + +## Recherche et progression + +### Système de recherche +Recherche à la Factorio pour : +- Moyens d'extraction +- Production +- Assembly +- Communication +- Châssis civil +- Recherche +- Transport (rail, hyperloop) +- Diplomatie +- Électronique +- Prototype militaire +- Prototype IA +- Prototype composants +- Proto radar + + +**Exemple Proto radar** : +- Composant équipement taille 6x6, 2kw, fiabilité 50% + +**Recherche radar 1** : +- Composant équipement taille 5x5, 2kw, fiabilité 60% +- Composant électronique taille 4x4, 500w, fiabilité 20% + +**Recherche radar 2** : +- Composant équipement taille 8x3, 1.5kw, fiabilité 80% + +## Système de Recherche Dual + +### 1. Recherche Générique (Points de Tech) +- **Points de recherche standard** : Système classique d'accumulation points +- **Usage** : Recherches civiles, technologies de base, progressions linéaires +- **Source** : Production continue, investissement R&D, temps + +### 2. Recherche Spécifique (Scrap Analysis) +- **Scrap Analysis** : Reverse engineering matériel ennemi +- **Découvertes aléatoires** : T-72 → ERA, blindage, canon (random) +- **Analyse ciblée** : Étude composants spécifiques pour breakthroughs +- **Efficacité variable** : Selon qualité et état du matériel récupéré + +## Système de Breakthroughs + +### Verrous technologiques +- **Recherches bloquées** : Certaines technologies inaccessibles sans breakthrough +- **Exemple** : "Armor Javelin-Proof" impossible sans analyse Javelin +- **Gating stratégique** : Force acquisition d'échantillons spécifiques + +### Prerequisites Gating & Performance +**Scaling technique** : Le système breakthrough peut gérer 3000 technologies grâce au gating intelligent : + +#### Prerequisites Chain +- **~10-50 techs eligible** simultanément pour un player donné (pas 3000) +- **Tech dependencies** : Nouvelle tech nécessite prérequis recherchés +- **Progressive unlock** : Chaque breakthrough débloque quelques nouvelles possibilités +- **Organic discovery** : Player découvre par gameplay naturel, pas par browsing + +#### Validation Performance +- **On-demand checks** : Conditions vérifiées quand événement trigger (construction, production, etc.) +- **State-based** : Validation sur état actuel (avoir 5 radars), pas historique complexe +- **Ticker optimisé** : Vérifications breakthrough toutes les minutes, pas 60fps +- **Cache results** : Évite recalculs conditions identiques + +### 3 Sources de Breakthroughs + +**1. Scrap Analysis** +- **Méthode primaire** : Reverse engineering matériel ennemi +- **Simplicité** : Scrap = scrap (pas d'état, pas de fraîcheur) +- **Efficacité** : Méthode la plus directe et économique + +**2. Points de Recherche Avancés** +- **Alternative coûteuse** : Breakthrough sans scrap +- **Caractéristiques** : Cher et lent +- **Usage** : Quand scrap spécifique inaccessible/rare + +**3. Reverse Engineering Produits** +- **Systèmes capturés** : Équipement intact récupéré (1-3 breakthroughs) +- **Achat commercial** : Produits achetés sur marché (produit final seul) +- **Conséquences diplomatiques** : Relations gravement affectées avec company/état vendeur +- **Limites** : Produit accessible mais pas ses composants/ingrédients + +### Efficacité par source +- **Scrap** : 0-1 breakthrough (aléatoire, économique) +- **Capture** : 1-3 breakthroughs (risqué, très efficace) +- **Achat** : 1 breakthrough produit (cher, conséquences diplomatiques) +- **Recherche avancée** : Garantie breakthrough (très cher et lent) + +## Économie des Technologies + +### Vente de technologies +- **Marché tech** : Breakthroughs déblocables vendables sur marché +- **Revenus additionnels** : Monétisation des découvertes R&D +- **Concurrence** : Autres actors peuvent acquérir vos innovations + +### Contenu long terme (future) +- **Espionnage industriel** : Vol de breakthroughs entre companies +- **Protection IP** : Mécaniques de sécurisation des technologies + +## Actions normales militaires + +L'idée c'est qu'une action normale est un déroulement : + +**Exemples de déroulements** : +- **Établir Position AA** = déplacement → déploiement → attente d'engagement +- **Assaut** = déplacement opérationnel → engagement tactique → attaque CQC → Prise de position de défense → attente d'engagement + +### Mise en place +- Établissement de FOB, dépôt de munitions +- Établissement d'AP +- Établir Position radar +- Établir Position AA (point defense, area defense) +- Établir Position static Artillerie +- Établir Trench network +- Defense tempo (retrenchment) + +### Ravitaillement +- Ravitaillement de convois +- Ravitaillement léger (drone) +- Ravitaillement classique (mono camion) + +### Action de combat +- **Assaut** (prise de position ennemie) +- **Reconnaissance** (discrète) +- **Reconnaissance in force** (légère ou blindée) +- **Infiltration** +- **Raid** (logistique, anti-AA, anti-artillerie, JSP) +- **Attaque** (char → boum boum boum → retrait → recommencer) (détruire l'ennemi) + +### Long range +On inclut ici l'artillerie, les missiles, le support aérien au sol : + +- **Frappe destructive** +- **Contre frappe** (contre batterie) +- **Saturation artillerie** +- **Support des troupes** +- **Obscuration** +- **Suppression** + +### Contrôle aérien +- **SEAD** +- **DEAD** +- **Interception** +- **Supériorité aérienne** → patrouille +- **Escorte** +- **Reconnaissance aérienne** +- **Identification** +- **Alerte** (warn non hostile) + +## IA stratégique + +### Défis de l'IA +Pas facile hein… + +Déjà l'IA doit être capable d'implémenter toutes les "actions normales" ci-dessus. + +Pour ce qui est de la décision de quelle action implémenter et où, c'est une vraie difficulté et c'est ce qui doit être réfléchi. + +### Doctrines différenciées +Déjà il faut comprendre que toutes les IA ne feront pas la même chose (doctrine tactique et opérationnelle) et cela en fonction d'objectifs stratégiques, donc décidés par l'IA stratégique. + +**Proposition** : Donner un set de préférences (par action) pour définir une doctrine, avec sûrement un concept de phases opérationnelles. + +**Exemple doctrine US** : +Campagne aérienne → SEAD → DEAD → C&C target → CAS → Ground assault + +### Concept de recette +Concept de recette avec un coût à trois composantes : +- **Raid** → **AA pos** → **125e compagnie d'inf moto** +- **Quoi ?** / **Qui/où ?** / **Comment/avec qui ?** + +## Mécaniques de combat + +### AOE (str) +Ça doit être possible mais bon à éviter. + +### Tacops (tactique/4x) +Ce qu'est censé être le combat mid-late game. Une gestion des unités sur une carte de campagne et les unités qui se démerdent sur l'aspect combat IA. Il est important de pouvoir contempler les combats. + +### Réparation/logistique +*À développer* + +### RPG +*À développer* + +## Simulation de monde + +### Factions +Intégration de factions qui, souvent seront les états et avec lesquels l'interaction doit être possible (économie, diplomatie). + +### Économique +Système économique avec lequel le joueur peut interagir, notamment par l'intermédiaire de la vente ou l'achat de ressources. Spéculation ? + +Celle-ci doit être dynamique et intégrer un système d'économie d'échelle permettant une spécialisation économique des factions. Pour autant, les enjeux stratégiques (bouffe, armes etc.) doivent être pris en compte et intégrés à la production économique des factions. + +### Stratégique +Compréhension des enjeux stratégiques liés aux ressources, aux positions géographiques. + +### Politique +Intégration de l'ordre public et des courants politiques. + +## Système d'Administration + +### Principe Fondamental +Chaque **company** et **état** dispose de points d'**Administration** qui limitent leurs actions quotidiennes, représentant leur capacité organisationnelle et bureaucratique. + +### Mécaniques Core + +#### Points Administration Base +- **Companies** : 1000 points/jour de base (1 jour = 10 minutes réelles) +- **États** : Variable selon taille/développement (à définir) +- **Régénération** : Reset quotidien complet des points +- **Fréquence actions** : ~1 action tous les 3-5 jours par company (rythme macro stratégique) + +#### Actions Coûtant Administration + +**Recherche & Développement** : +- Lancer nouvelle recherche : 100-500 points (selon complexité) +- Breakthrough forcé (scrap analysis) : 200-800 points +- Achat technology sur marché : 150 points + +**Commerce & Économie** : +- Négocier nouveau contrat : 50-200 points +- Changer prix produits : 25 points +- Ouvrir nouveau marché d'export : 300 points +- Merger/acquisition : 500+ points + +**Diplomatie** : +- Proposer accord commercial : 200 points +- Sanctions économiques : 400 points +- Négociation traité : 600+ points + +**Production & Infrastructure** : +- Construire nouvelle usine : 300 points +- Changer ligne de production : 100 points +- Optimisation processus : 150 points +- Expansion facilities : 250 points + +**Opérations Militaires** (États principalement) : +- Lancer opération militaire : 500+ points +- Coordination multi-forces : 300 points +- Changement doctrine : 400 points + +### Facteurs Modifiant Administration + +#### Company Features Impact + +**Features Réduisant Admin** : +- **Quality** : -10% coûts admin (organisation efficace) +- **Administration** : +50% points admin de base (spécialisation bureaucratique) + +**Features Neutres** : +- **Innovation** : Pas de bonus admin (créativité ≠ organisation) +- **Cost** : Pas d'impact admin +- **Speed** : Pas d'impact admin + +#### Investissements Infrastructure + +**Bureaux & Management** : +- **Bureaux modernes** : +200 points admin/jour +- **Systèmes ERP** : +150 points admin/jour +- **Managers expérimentés** : +100 points admin/jour +- **Automation administrative** : +300 points admin/jour + +#### Modificateurs Contextuels + +**État de Guerre** : +- **Companies** : +200 points admin/jour (économie de guerre = urgence) +- **États** : +500 points admin/jour (mobilisation totale) +- **Justification** : Urgence permet décisions rapides, bypass bureaucratie + +**État de Paix** : +- **Administration normale** : Valeurs de base +- **Bureaucratie standard** : Processus normaux + +**Stress Économique** : +- **Récession** : -100 points admin/jour (ressources réduites) +- **Croissance** : +50 points admin/jour (expansion capabilities) + +### Stratégies Administration + +#### Optimisation Resource Management +- **Priorisation actions** : Quelles décisions sont critiques ? +- **Timing operations** : Grouper actions similaires +- **Investment planning** : ROI bureaux vs production + +#### Spécialisations Companies +- **Company "Administration"** : Devient sous-traitant admin pour autres +- **Outsourcing** : Déléguer certaines tâches vs faire internal +- **Efficiency focus** : Quality companies = moins de waste admin + +### Examples Concrets + +#### Company Journée Type +``` +Thales (Company "Electronic, Quality, Administration"): +├── Administration disponible: 1000 + 500 (Admin feature) + 200 (bureaux) = 1700/jour +├── Coûts journée: +│ ├── Recherche "Radar AESA": -400 points +│ ├── Négociation contrat Ukraine: -150 points +│ ├── Optimisation ligne production: -120 points (Quality = -10%) +│ └── Total utilisé: 670/1700 +└── Surplus: 1030 points (peut faire plus d'actions) +``` + +#### Company Limitée +``` +StartupCorp (Company "Innovation"): +├── Administration disponible: 1000/jour (base seulement) +├── Coûts journée: +│ ├── Recherche breakthrough: -500 points +│ ├── Négociation financement: -300 points +│ ├── Changement production: -250 points +│ └── Total: 1050 points +└── LIMITE ATTEINTE: Doit choisir priorités ! +``` + +### Impact Gameplay + +#### Pour l'IA +- **Performance naturellement limitée** : Pas d'actions infinies par tick +- **Comportements réalistes** : Companies choisissent priorités selon pools admin +- **Rythme macro** : ~1000 companies × 1 action/3-5 jours = ~0.33 actions/seconde système +- **Spécialisations émergentes** : Features influencent strategies + +#### Pour le Joueur +- **Companies IA prévisibles** : Limitation actions = patterns plus lisibles +- **Opportunités timing** : Profiter quand competitors "admin-locked" +- **Market dynamics** : Administration shortage = prix changes moins fréquents + +### Balance Considerations + +#### Éviter Frustration +- **Actions critiques** : Survie company ne doit jamais être bloquée par admin +- **Emergency actions** : Certaines actions bypass admin en crisis +- **Learning curve** : Interface claire sur coûts admin + +#### Maintain Dynamism +- **Baseline sufficient** : 1000 points permet gameplay de base +- **Scaling rewards** : Investment admin = exponential returns +- **Variety strategies** : Multiple paths pour optimiser admin + +## Terrain de combat PMC + +### Zones d'opération +- Amérique du Sud dans les zones peu peuplées +- Madagascar +- Afrique +- Ouest de la Chine +- Russie +- Moyen-Orient + +## Meta Game Design + +### Philosophie de difficulté +"Aucune satisfaction parce que le jeu est fait pour être gagné. Quel intérêt de gagner alors ?" + +**Objectif** : Faire un jeu où le but de l'IA contre le joueur est bel et bien de gagner, pas de perdre. + +## Système d'Expérience Véhicules + +### Expérience Combat +- **Gain expérience** : Combat, missions réussies, survie prolongée +- **Effets** : Amélioration fiabilité, précision, temps de réaction IA +- **Vétérans** : Véhicules expérimentés plus efficaces, moins de pannes + +### Système de Généraux et Armées + +#### Structure de commandement +- **Composition automatique** : Joueur assigne types/nombres ("20 chars lourds"), gestion automatique +- **Types de véhicules** : Classification par rôles (char lourd, IFV, drone, etc.) +- **Logistique intégrée** : Assignement, maintenance, ravitaillement gérés automatiquement +- **Hiérarchie** : Général en chef donne objectifs à subalternes qui planifient opérations +- **Limite par expérience** : Capacité de commandement croît linéairement avec expérience +- **Malus surcharge** : Armée trop grosse → réserves, opérations limitées, qualité dégradée + +#### Modes de planification +1. **Plans proposés** : Général propose plans que joueur valide/modifie +2. **Plans joueur** : Joueur conçoit plans détaillés, général exécute +3. **Objectifs généraux** : Joueur donne objectifs, général génère détails opérationnels +4. **Ordre simple** : Ordre "attaque", IA choisit méthodes et tactiques + +#### Spécialisations et IA des généraux +- **Machine Learning** : Adaptation tactique selon résultats (échecs → évitement progressif) +- **Personnalité & Traits** : Influencent probabilité d'usage de certaines tactiques +- **Exemple adaptatif** : Général blindé échec urban → reste blindé mais tactiques adaptées +- **Apprentissage spécialisé** : Usage véhicules overloadés → amélioration overload dynamique + +#### Cycle d'apprentissage overload dynamique + +**Phase Planning** : +1. **Analyse menace** : Blindage insuffisant estimé pour mission +2. **Recherche solutions** : Liste options (Spaced armor, ERA, etc.) +3. **Check logistique** : Disponibilité équipements (ERA disponible) +4. **Commande automatique** : Order passé au réseau logistique + +**Phase Pré-mission** : +- **Workshop preparation** : Équipement ERA sur véhicules compatibles +- **Validation configuration** : Vérification intégrité overload + +**Phase Mid-mission** : +- **Observation détaillée** : Monitoring performance en temps réel +- **Data collection** : Impact sur vitesse, électronique, capteurs + +**Phase Post-analyse** : +- **Efficacité ERA** : Réduction dégâts mesurée vs prédiction +- **Ajustement valeurs** : Calibrage algorithmes d'évaluation +- **Impact systémique** : Analyse systèmes ennemis, contre-mesures +- **Décision adaptative** : Mise à jour probabilités d'usage futur + +**Caractéristiques générales** : +- **Templates flexibles** : Style HOI4 + contrôle fin possible +- **Influence principale** : Tactiques et opérations privilégiées +- **Influence secondaire** : Légers bonus stats selon expertise + +#### Système logistique intégré +- **Orders automatiques** : Armées placent commandes logistiques automatiquement +- **Équipement dynamique** : Blocs ERA commandés via réseau logistique +- **Delivery system** : Logistique tente de livrer selon capacités/priorités + +#### Contrôle joueur et politiques +**Séparation des rôles** : +- **Joueur** : Légo industriel + ordres stratégiques + planning optionnel +- **Généraux** : Exécution autonome selon designs et stocks disponibles + +**Gestion des stocks** : +- **Stocks spéciaux** : Joueur contrôle mise à disposition (ERA, équipements rares) +- **Premier arrivé, premier servi** : Pas de système de priorités complexe +- **Contrôle indirect** : Arrêt production = fin disponibilité pour généraux + +**Politiques par design** : +- **Design constraints** : Espace disponible pour overload ou interdiction +- **Pas de budgets généraux** : Pas d'autorisation ni limite financière +- **Contrôle passif** : IA utilise ce qui est disponible selon designs autorisés + +#### Interface de planification +- **Plans séquentiels** : Phases avec objectifs et timeline +- **Visualisation carte** : Zone d'opération avec numéros, flèches, positions +- **Détails drill-down** : Accès effectifs prévus par phase/objectif +- **Validation joueur** : Approbation/modification des plans proposés + +## Cycle Technologique des Armes + +### Évolution forcée : Petit → Moyen → Gros +- **Recherche naturelle** : Nouvelles armes plus puissantes mais plus grosses +- **Dilemme châssis** : Armes avancées ne logent plus sur châssis existants +- **Solutions forcées** : + - Overload châssis existants (malus mais moins cher) + - Développer châssis super-lourds (coûteux, spécialisés, limités) +- **Équilibrage** : Châssis super-lourds pas OP (style HOI4) - lents, chers, vulnérables + +## Architecture serveur + +### Economy Server + +#### Marché global dynamique +- **Fonction** : Ressources globales, commerce, spéculation, économie d'échelle +- **Trade dynamique** : Prix fluctuants selon offre/demande et événements +- **Réactivité militaire** : Économie réagit aux conflits et batailles + +#### Acteurs économiques +- **Companies** : Entreprises privées (Thales, Dassault, joueur initial) +- **États** : Nations avec politiques et relations diplomatiques +- **Relations croisées** : Companies dépendent des états mais ont relations propres +- **Restrictions multi-niveaux** : Blocages possibles par companies ET états +- **Matières et services** : Restrictions sur industriel, production, consommation (électricité, acier) + +#### Système de marchés +- **Marchés segmentés** : Par pays, par company, par bloc multinational, mondial +- **Exclusivités** : Joueur peut vendre exclusivement sur certains marchés +- **Designs concurrents** : Companies génèrent designs procéduraux, reverse engineering possible +- **Commandes nationales** : États passent commandes directes selon besoins + +#### Early game - Économie de guerre Ukraine +- **Scrap russe** : Récupération tanks détruits comme ressource de base +- **Transformation** : Recyclage et revente sur marché ukrainien +- **Bootstrap économique** : Revenus initiaux via scrap → équipement → export + +#### Dynamiques de pénurie et production +- **Pénuries temporaires** : Prix augmentent selon durée estimée de résolution +- **Différentiation temporelle** : "Réglé dans 2 mois" vs "réglé dans 5 ans" +- **Adaptation marché** : Production s'ajuste selon signaux prix et demande + +#### Système de menaces (style AI War) +- **Basé sur capacité production** : Volume de production brute = menace principale +- **Impact indirect** : Tank company X détruit matos → menace pour company X +- **Escalade naturelle** : Succès militaire → attention ennemie → frappes ciblées +- **Exemple concret** : Anti-tank révolutionnaire détruit masses de véhicules → strikes russes + +#### Mécanismes de protection +- **Défense personnelle** : Investissement défenses propres autorisé +- **Protection étatique** : État hôte (Ukraine) défend companies importantes +- **Dispersion géographique** : Étalement production pour réduire vulnérabilité +- **Négociation neutralité** : Accords diplomatiques possibles avec hostiles +- **Équilibrage mutuel** : État protège company → company contribue défense nationale + +#### Expansion géographique +- **Délocalisation** : Possible si pays hôte accepte l'implantation +- **Changement nationalité** : Possible mais exclusif (pas de multi-nationalité) +- **Pas de filiales** : Structure company unifiée sous une seule nationalité +- **Approbation étatique** : Accord gouvernemental requis pour implantation + +#### Système de renseignement +- **Fog of War** : Reconnaissance obligatoire pour informations précises +- **Identification progressive** : Bâtiments → Usines → Usines d'armement → Usine d'arme de X +- **Stats économiques publiques** : Menace calculée sur données ouvertes +- **Paradoxe info** : Menace omnisciente mais localisation floue + +#### Rôle du joueur dans le monde +- **Échelle variable** : Du massif à l'insignifiant selon choix joueur +- **Joueur secondaire** : Le monde tourne indépendamment du joueur +- **Impact optionnel** : Joueur peut influencer mais n'est pas nécessaire à l'économie globale + +### World Server +- **Fonction** : Factions, diplomatie, géopolitique, événements macro +- **Scope** : Relations internationales, politique interne, crises globales +- **Features** : 3 endgames (zombies, aliens, démons) +- **Intégration** : Ordre public et courants politiques + +### Gameplay asynchrone +- **Principe** : Combat peut avoir latency, player gère autre chose +- **Implémentation** : Background processing pendant diplo/économie +- **Avantage** : Bataille 10k unités = 30 secondes → player continue production \ No newline at end of file diff --git a/docs/04-reference/metriques-joueur.md b/docs/04-reference/metriques-joueur.md new file mode 100644 index 0000000..c93129a --- /dev/null +++ b/docs/04-reference/metriques-joueur.md @@ -0,0 +1,269 @@ +# Métriques Joueur + +## Vue d'ensemble + +Le système de métriques de Warfactory fournit aux joueurs des **statistiques détaillées** avec graphiques complets de performance, permettant l'analyse fine de leur progression industrielle et militaire. + +## Architecture Données + +### Distinction Breakthrough vs Métriques + +**Breakthrough System** : Données minimales (~KB par company) +- State actuel uniquement +- Compteurs cumulatifs simples +- Focus : Performance et déclenchement conditions + +**Système Métriques** : Données historiques complètes (~MB par entité) +- Historique détaillé production +- Graphiques temporels complets +- Focus : Analyse et visualisation + +### Volume de Données par Partie (300-400h) + +#### Companies IA (1000) +- **Fréquence** : 1 point toutes les 10min +- **Ressources** : 10 produits trackés par company +- **Volume** : 1000 × 10 × (400h × 6 points/h) × 8 bytes = **192MB par partie** + +#### États (50) +- **Fréquence** : 1 point toutes les 10min +- **Ressources** : 3000 ressources par état +- **Volume** : 50 × 3000 × (400h × 6 points/h) × 8 bytes = **2.9GB par partie** + +#### Joueurs (Scaling Adaptatif Multijoueur) +- **Solo/Company partagée** : 1 point toutes les 30sec = 120 points/h +- **Multijoueur adaptatif** : Fréquence réduite selon nombre de companies + - **1 company** : 2 points/min (120 points/h) + - **5 companies** : 0.4 points/min (24 points/h) + - **10+ companies** : 0.25 points/min minimum (15 points/h) +- **Ressources** : 40 produits trackés +- **Volume variable** : 1 × 40 × (400h × points/h) × 8 bytes = **15MB à 3MB selon config** + +**Total par partie** : ~3.1GB constant (data sharing + scaling adaptatif) +- **Joueurs même company** : Dataset partagé (pas de duplication) +- **Free-for-all** : Granularité réduite maintient volume total stable + +## Types de Métriques + +### 1. Production & Économie + +#### Métriques de Production +- **Production par ressource** : Steel/h, Electronic components/h, Véhicules/jour +- **Efficacité usines** : % utilisation, downtime, bottlenecks identifiés +- **Évolution capacités** : Courbes de croissance industrielle +- **Ratios production** : Input/Output, waste, efficiency metrics + +#### Métriques Économiques +- **Revenus/Dépenses** : Graphiques détaillés par source et destination +- **Flux financiers** : Cash flow, profit margins, ROI investissements +- **Commerce international** : Exports/imports par pays et ressource +- **Coûts opérationnels** : Breakdown par type (énergie, main d'œuvre, matières premières) + +### 2. Recherche & Développement + +#### Progression Technologique +- **Timeline breakthroughs** : Chronologie découvertes avec sources +- **Sources de découverte** : Ratio Scrap vs Natural vs Events vs Purchase +- **Domaines expertise** : Radar de spécialisations technologiques +- **Investissements R&D** : Allocations budget et ROI par domaine + +#### Innovation Metrics +- **Taux découverte** : Breakthroughs/mois in-game +- **Efficacité R&D** : Coût moyen par breakthrough +- **Diversification** : Spread technologique sur domaines +- **Compétitivité** : Position vs autres companies (si intel disponible) + +### 3. Expansion & Influence + +#### Contrôle Géographique +- **Territoire contrôlé** : Surface, ressources accessibles, population +- **Infrastructure** : Density routes, bases, installations industrielles +- **Influence diplomatique** : Relations par pays/région, contrats actifs +- **Sécurité zones** : Threat levels, incidents sécuritaires + + +## Visualisations + +### Graphiques Temporels + +#### Production Dashboard +``` +Production Steel (tonnes/jour) + ▲ +1000│ ╭─╮ + 800│ ╭─╯ ╰─╮ + 600│ ╭─╯ ╰─╮ + 400│╭╯ ╰─╮ + 200│╯ ╰─── + 0└─────────────────────▶ + Mois 1 2 3 4 5 6 +``` + +#### Financial Trends +``` +Cash Flow (M€) + ▲ + 5.0│ ██████████████████▒▒▒▒ Revenue + 4.0│ ████████████▒▒▒▒▒▒▒▒▒▒ Expenses + 3.0│ ████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒ Profit + 2.0│ ████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ + 1.0│ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ + 0└─────────────────────▶ + Q1 Q2 Q3 Q4 +``` + +#### Breakthrough Timeline +``` +Découvertes Technologiques +│ +├─ Mois 2: Radar Avancé (Scrap Analysis) +├─ Mois 4: Matériaux Composites (Natural) +├─ Mois 7: IA Tactique (Purchase Intel) +├─ Mois 9: Blindage Réactif (Capture) +└─ Mois 12: Moteurs Fusion (Event) +``` + +### Radar Charts + +#### Technology Mastery +``` + IA (8/10) + /\ + / \ +Electronics Matériaux + (6/10) ────────── (9/10) + \ / + \ / + Moteurs (4/10) +``` + +### Heatmaps + +#### Market Opportunities +``` +Resource vs Country Demand + │UKR│POL│GER│FRA│ +Steel │ ██│ ▓▓│ ░░│ ▓▓│ +Electronics│▓▓│ ██│ ██│ ▓▓│ +Vehicles │ ██│ ▓▓│ ░░│ ░░│ +``` + +## Système de Stockage + +### Architecture Données + +#### Structure TimeSeries Simplifiée +```cpp +struct MetricTimeseries { + int32_t value; // 4 bytes signed int + // Timestamp et résolution stockés en métadonnées +}; + +struct TimeseriesMetadata { + uint32_t start_timestamp; + uint32_t interval_seconds; // Ex: 30s pour joueur, 600s pour IA + uint32_t data_count; +}; + +struct EntityMetrics { + EntityID entity_id; + + // Production (par ressource) - listes simples de int32 + map> production_history; + map production_metadata; + + // Financial - listes simples + vector revenue_history; + vector expenses_history; + vector cash_flow_history; + TimeseriesMetadata financial_metadata; + + // Technology + vector breakthrough_timeline; +}; +``` + +#### Breakthrough Events Simplifié +```cpp +struct BreakthroughEvent { + uint32_t timestamp; + TechID technology_id; + BreakthroughSource source; // SCRAP, NATURAL, PURCHASE, EVENT + string details; // "Scrap: T-72 Tank" +}; +``` + +### Agrégation & Compression + +#### Résolution Adaptative +- **Dernière semaine** : Points toutes les 30sec (joueur) / 10min (IA) +- **Dernier mois** : Agrégation horaire +- **Derniers 6 mois** : Agrégation quotidienne +- **Plus ancien** : Agrégation hebdomadaire + +#### Compression Intelligente +- **Delta encoding** : Stocker différences vs valeurs absolues +- **Run-length encoding** : Pour périodes stables (production constante) +- **Lossy compression** : Données anciennes → précision réduite acceptable + +## Interface Métriques + +### Dashboard Principal + +#### Vue d'Ensemble +``` +┌─────────────────┬─────────────────┬─────────────────┐ +│ PRODUCTION │ FINANCES │ RECHERCHE │ +│ Steel: ↗ +15% │ Profit: ↗ +8% │ 3 breakthroughs│ +│ Elec: ↘ -3% │ Cash: 2.4M€ │ this month │ +├─────────────────┼─────────────────┼─────────────────┤ +│ TERRITOIRE │ DIPLOMATIC │ STATUS │ +│ 12 installations│ 3 trade deals │ ✅ Operational │ +│ 3 countries │ 85% relations │ 🔄 Expanding │ +└─────────────────┴─────────────────┴─────────────────┘ +``` + +#### Navigation & Drill-Down +- **Overview** → **Domain** → **Specific Metric** → **Detailed Timeline** +- **Comparisons** : Self vs time, targets vs actual, competitors (si data available) +- **Filters** : Date ranges, metric types, zoom levels, entity types + +### Métriques Spécialisées + +#### Competitive Intelligence (si disponible) +``` +Market Share Analysis +Company │Production│Revenue│Breakthroughs│ +Thales │ 25% │ 30% │ 18 │ +Lockheed │ 18% │ 22% │ 15 │ +Player │ 12% │ 15% │ 12 │ +Dassault │ 15% │ 18% │ 10 │ +Others │ 30% │ 15% │ 45 │ +``` + + + +## Privacy & Intelligence + +### Data Visibility + +#### Player Data (Full Access) +- **Toutes métriques personnelles** : Production, finances, recherche, combat +- **Historique complet** : Depuis début de partie +- **Analytics avancées** : Trends, predictions, optimization suggestions + +#### Competitor Data (Limited) +- **Via espionnage** : Intel partiel sur production/capabilities +- **Market signals** : Déductions via prix, volumes, nouvelles exportations +- **Combat assessment** : Performance observée lors d'engagements +- **Public information** : Certaines métriques "corporate" accessibles + +#### State Data (Contextual) +- **Economic indicators** : PIB, imports/exports publics +- **Military capabilities** : Intel selon relations diplomatiques +- **Technology level** : Observations équipements, brevets publics + + +--- + +*Les métriques constituent l'outil principal d'analyse et d'optimisation continue pour maîtriser la complexité industrielle et militaire de Warfactory* \ No newline at end of file diff --git a/docs/04-reference/questions-ouvertes.md b/docs/04-reference/questions-ouvertes.md new file mode 100644 index 0000000..383683f --- /dev/null +++ b/docs/04-reference/questions-ouvertes.md @@ -0,0 +1,319 @@ +# Questions Ouvertes - Warfactory + +*Questions importantes à résoudre lors du développement* + +## Questions Architecturales + +### 1. **Operation Engine - Compréhension Situation** +**Question** : Comment implémenter l'analyse de rapports War Engine pour "comprendre" situations complexes ? + +**Options envisagées** : +- Pattern matching simple (if-then rules) +- Algorithmes plus sophistiqués +- Machine learning avancé + +**Status** : En suspens, sujet difficile à résoudre pour l'instant + +### 2. **Designer Engine Role** ✅ RÉSOLU +**Question** : Qui design les véhicules pour les IA companies/états ? + +**Solution** : Designer Engine unifié sert joueur ET IA +- IA : Random generation + evaluate + blueprints doctrinaux +- Joueur : Design manuel + assistance IA optionnelle +- Company features influencent choix procéduraux IA + +### 3. **Factory Benchmarking Implementation** ✅ RÉSOLU +**Question** : Le système factory benchmarking est-il implémenté ou spéculatif ? + +**Solution** : Reporté en long-term update +- Optimisation prématurée, focus sur gameplay core d'abord +- Concept conservé pour développement futur +- Status uniforme dans tous les documents + +## Questions Gameplay + +### 4. **Tension Militaire/Politique** +**Question** : Mécaniques concrètes pour résistance militaire aux ordres politiques stupides ? + +**Exemples** : +- Militaire peut "traîner les pieds" sur ordres suicide +- Délais supplémentaires pour ordres non-optimaux +- Système de moral/confiance commandement + +**Status** : Envisagé pour long-term updates + +### 5. **Convergence Tactique IA** +**Question** : Comment éviter homogénéisation si toutes IA apprennent mêmes tactiques efficaces ? + +**Solutions identifiées** : +- Diversité options/tech/ennemis +- Armes semi-random créent différentiations +- Biais doctrinaux persistants + +**À surveiller** : Équilibrage convergence réaliste vs diversité gameplay + +## Questions Techniques + +### 6. **Chunk Size Standardization** ✅ RÉSOLU +**Question** : Quelle taille officielle pour les chunks ? + +**Solution** : Architecture multi-échelle clarifiée +- Système patches ressources (forme libre) vs chunks terrain/bâtiments/effets +- Chaque type de donnée utilise résolution optimale selon besoins +- 64x64 = chunk principal gameplay, autres tailles pour données spécialisées + +### 7. **Client Capabilities** ✅ RÉSOLU +**Question** : Les clients sont-ils "dumb terminals" ou gèrent-ils streaming intelligent ? + +**Solution clarifiée** : Smart Client / Authoritative Server +- **Client Smart** : Interface complexe, rendu optimisé, streaming carte, cache local +- **Client Dumb** : Aucune simulation gameplay, pas de logique métier +- **Responsabilités client** : UI industrielle/militaire/diplomatique, LOD, culling, cache zones +- **Server Authoritative** : Toute simulation et état de jeu + +**Cohérence restaurée** : Terminologie "dumb terminal" remplacée par architecture plus précise. + +## Questions Scope + +### 8. **Système Administration - Integration** ✅ RÉSOLU +**Question** : Comment intégrer le système de points d'administration avec l'architecture engines ? + +**Solution** : MacroEntity Engine gère entièrement le système +- **Architecture** : MacroEntity Engine responsable companies/états + administration +- **Isolation** : Autres engines ignorent système admin, consultent via API si besoin +- **Actions refusées** : Admin exhausté = refus immédiat (pas de queue) +- **Performance** : Calculs légers, batch processing, rythme adapté gameplay macro +- **Joueur exempt** : Pas de contraintes admin pour le joueur +- **Recherche** : Coûts admin faibles pour ne pas freiner le jeu + +### 9. **Client Rendering Stack** +**Question** : Quelle technologie pour le rendu 2D pixel art ? + +**Options techniques** : +- **Canvas 2D** : Simple, direct, compatible partout +- **WebGL** : Performance supérieure, scaling, effects +- **Hybrid** : Canvas UI + WebGL game world + +**Considérations** : +- Performance avec milliers d'unités simultanées +- Compatibilité navigateurs et plateformes +- Complexité développement vs performance gains +- Support zoom discret pixel perfect + +**À décider** : Choix tech stack rendu client + +### 10. **Développement Narratif** +**Question** : Comment développer le contenu narratif pour supporter la richesse du système ? + +**État actuel** : Travail narratif incomplet +- **Ukraine baseline** : Contexte initial défini mais peu développé +- **Autres régions** : Congo, Sahara, etc. - aucun contenu narratif +- **Storylines** : Manque de quêtes, événements, personnages +- **Immersion** : Gap entre mécaniques sophistiquées et narrative basique + +**Besoins identifiés** : +- **Ukraine dense** : Développer storylines épiques, personnages, événements historiques +- **Régions alternatives** : Warlords Congo, conflicts sahéliens, tensions géopolitiques +- **Événements dynamiques** : Crises, alliances, retournements de situation +- **Personnages** : Leaders, généraux, figures historiques et fictives +- **Lore systémique** : Background économique, technologique, culturel par région + +**À développer** : Contenu narratif riche pour toutes les régions supportées + +### 11. **Optimisations Transport Factorio (Factory System Performance)** +**Question** : Quelle stratégie d'optimisation pour atteindre 50x-100x gains performance sur les belts/convoyeurs ? + +**Optimisations identifiées** : +- **Segment merging** : Fusion segments identiques pour réduire calculs +- **Compression caching** : Cache états compressés pour éviter recalculs +- **Belt batching** : Traiter items par lots plutôt qu'individuellement +- **Spatial indexing** : Structures spatiales optimisées pour queries rapides + +**Trade-offs à considérer** : +- **Mémoire vs CPU** : Caching augmente RAM mais réduit calculs +- **Latence vs Throughput** : Batching améliore débit mais augmente latence +- **Complexité vs Performance** : Optimisations avancées compliquent maintenance + +**À investiguer** : +- Profiling détaillé système actuel pour identifier bottlenecks +- Benchmarking différentes approches (segment merging vs autres) +- Équilibrage optimal entre différentes optimisations +- Impact sur architecture modulaire (ProductionModule monolithique) + +### 12. **SOA Data Layout (Structure of Arrays)** +**Question** : Comment implémenter efficacement le pattern SOA pour optimiser cache locality et préparer SIMD ? + +**Contexte technique** : +- **AOS traditionnel** : `struct Entity { x, y, z, health; } entities[1000];` +- **SOA optimisé** : Arrays séparés `positions_x[1000]`, `positions_y[1000]`, etc. + +**Avantages SOA** : +- **Cache efficiency** : Traitement d'une propriété sur toutes entités sans charger données inutiles +- **SIMD readiness** : Données alignées pour vectorisation automatique +- **Memory bandwidth** : Réduction transferts mémoire jusqu'à 4x + +**Application Warfactory** : +- **Belts** : Positions, vitesses, items séparés pour traitement batch +- **Factories** : États production, inventaires, types en arrays distincts +- **Units** : Coordonnées, santé, munitions en structures séparées + +**Défis d'implémentation** : +- **Complexité code** : Accès moins intuitif qu'AOS +- **Maintenance** : Synchronisation entre arrays parallèles +- **Trade-off** : SOA pas optimal pour accès random single entity + +**À décider** : +- Quels systèmes bénéficient le plus de SOA ? +- Comment gérer la transition progressive AOS → SOA ? +- Quel niveau d'abstraction pour masquer complexité ? + +### 13. **Trade-off SIMD vs Claude (Optimisation vs Maintenabilité)** +**Question** : Faut-il privilégier auto-vectorisation compilateur ou SIMD manuel pour performance ? + +**Context décisionnel** : +- **SIMD manuel** : Intrinsics SSE/AVX/NEON pour contrôle total performance +- **Auto-vectorisation** : Compilateur optimise automatiquement avec flags appropriés + +**Arguments pour auto-vectorisation** : +- **Simplicité code** : Pas d'intrinsics complexes, code lisible +- **Portabilité** : Fonctionne sur toutes architectures sans modification +- **Claude-friendly** : IA peut comprendre et modifier facilement +- **Maintenance** : Réduction drastique complexité long-terme + +**Arguments contre SIMD manuel** : +- **Complexité extrême** : Code intrinsics illisible, bug-prone +- **Architecture-specific** : Versions différentes ARM/x86/x64 +- **ROI questionnable** : 10-20% gain pour 10x complexité +- **Claude incompatible** : IA difficile à utiliser sur code SIMD + +**Stratégie recommandée** : +- **Phase 1** : SOA + auto-vectorisation partout +- **Phase 2** : Profiling pour identifier hot spots réels +- **Phase 3** : SIMD manuel UNIQUEMENT si bottleneck critique prouvé +- **Documentation** : Si SIMD manuel, isoler dans fonctions avec fallback C++ + +**Flags compilateur optimaux** : +- `-O3 -march=native` : Maximum auto-vectorisation +- `-ftree-vectorize` : Force vectorisation loops +- `-ffast-math` : Optimisations math agressives (attention précision) + +### 14. **Infrastructure Binaire (Accès Transport)** +**Question** : L'accès aux infrastructures (port/rail/aéroport) doit-il être binaire ou gradué ? + +**Option Binaire (proposée)** : +- Accès = true/false uniquement +- Simplicité maximale pour IA et gameplay +- Pas de niveaux ou gradients + +**Option Graduée (alternative)** : +- Niveaux infrastructure (petit port → grand port → méga-port) +- Capacité throughput variable +- Coûts d'upgrade progressifs + +**Trade-offs** : +- **Binaire** : Simple mais moins de nuance stratégique +- **Gradué** : Plus réaliste mais complexité accrue +- **Hybride** : Binaire pour accès, capacité max comme propriété séparée + +**À décider** : Quelle granularité pour l'infrastructure transport ? + +### 15. **Phases Économiques (Cycle 24h)** +**Question** : Comment structurer le cycle économique quotidien de 24h ? + +**Proposition actuelle** : +- Offer: 6h - Companies postent offres +- Demand: 6h - Companies postent demandes +- Clearing: 1h - Algorithme matching +- Transport: 1h - Organisation logistique +- Execution: 10h - Livraison effective + +**Questions ouvertes** : +- **Synchronisation globale** : Tous sur même cycle ou décalés par timezone ? +- **Flexibilité** : Permettre transactions hors-cycle pour urgences ? +- **Granularité** : 24h trop long/court pour gameplay ? +- **Interruptions** : Que se passe-t-il si guerre/embargo pendant cycle ? + +**Alternatives** : +- Cycles plus courts (6h) pour dynamisme +- Cycles asynchrones par marché régional +- Système continu avec batch processing périodique + +### 16. **Pricing Dynamique (Formule Prix)** +**Question** : Quelle formule précise pour calculer les prix dynamiques ? + +**Composants identifiés** : +- Base price (coût production) +- Transport cost (distance × mode) +- Scarcity factor (offre/demande) +- Regional modifiers (taxes, risques) + +**Formule proposée** : +`Prix = Base × (1 + Scarcity) × (1 + Regional) + Transport` + +**Questions détails** : +- **Scarcity calculation** : Linéaire, exponentielle, ou par paliers ? +- **Regional factors** : Guerre (+50%), embargo (+100%), taxes (±20%) ? +- **Price caps** : Limiter prix max pour éviter spirales ? +- **Historical smoothing** : Moyenne mobile pour stabilité ? + +**Impacts à considérer** : +- Volatilité excessive peut frustrer joueurs +- Prix trop stables = pas d'opportunités trading +- Balance réalisme vs fun gameplay + +### 17. **Vision Simulation Complète Victoria 3-Level (Point 35)** +**Question** : Comment implémenter une simulation économique Victoria 3-level dans le contexte factory game de Warfactory ? + +**Modules identifiés** : +- **PopulationModule** : Demographics avec classes (Workers/Engineers/Managers) +- **MarketModule** : Supply/demand dynamics avec price discovery real-time +- **MoneyModule** : Currency, inflation, banking systems +- **TradeModule** : International commerce, tariffs, trade agreements +- **PolicyModule** : Government intervention, taxation, regulation + +**Défis d'intégration** : +- **Performance scaling** : 0.01-0.1Hz simulation économique vs real-time factory +- **Complexity balance** : Victoria 3-level sans overwhelming factory gameplay +- **Player agency** : Comment player influence économie macro via actions micro +- **Data interdependencies** : Synchronisation entre modules économiques + +**Questions spécifiques** : +- **Population dynamics** : Birth/death rates, migration patterns réalistes ? +- **Economic timescales** : Daily economic cycles vs hourly factory production ? +- **Government simulation** : Policies automatiques ou player-controlled ? +- **Market volatility** : Niveau réalisme vs stabilité gameplay ? + +**Architecture concerns** : +- Quel niveau détail pour chaque module ? +- Comment éviter simulation économique devenant mini-jeu séparé ? +- Interface player pour comprendre/influencer économie macro ? +- Performance impact sur real-time factory operations ? + +**Scope questions** : +- Victoria 3-level = objectif final ou starting point ? +- Quels aspects Victoria 3 essentiels vs nice-to-have ? +- Timeline implémentation (post-MVP ou core feature) ? + +**À déterminer** : Scope précis, architecture détaillée, priorités implémentation + +## Process de Résolution + +### Priorité 1 - Bloquants Architecture +- Factory benchmarking status +- Chunk size standardization +- Client capabilities définition + +### Priorité 2 - Core Gameplay +- Designer Engine role +- Operation Engine comprehension method + +### Priorité 3 - Polish Features +- Tension militaire/politique +- Convergence tactique prevention + +### Long-term +- Narrative/technical alignment + +--- + +*Ces questions seront résolues progressivement lors du développement. Certaines nécessitent prototypage pour validation.* \ No newline at end of file diff --git a/docs/04-reference/updates-long-terme.md b/docs/04-reference/updates-long-terme.md new file mode 100644 index 0000000..1a4072a --- /dev/null +++ b/docs/04-reference/updates-long-terme.md @@ -0,0 +1,174 @@ +# Updates Long Terme + +## Fonctionnalités futures à développer + +### Espionnage Industriel +- **Vol de breakthroughs** : Mécaniques permettant aux companies de voler les technologies d'autres actors +- **Protection IP** : Systèmes de sécurisation des technologies sensibles +- **Contre-espionnage** : Défenses contre tentatives d'infiltration technologique +- **Réseaux d'espions** : Agents infiltrés dans companies concurrentes + +### Factory Benchmarking System +**Concept** : Conversion des usines stables en lookup tables pour performance optimale + +**Inspiration** : Modèle Mindustry pour optimisation usines à grande échelle +- Détection automatique patterns d'input/output stables +- Conversion vers calculs O(1) pour scaling optimal +- Maintien précision comportement vs simulation complète + +**Process envisagé** : +1. Factory neuve → full simulation détaillée +2. Après X cycles stables → benchmark input/output ratios +3. Conversion en lookup table → unload detailed simulation +4. Recalibrage si modifications (upgrades, dégâts) + +**Justification report** : Optimisation prématurée, focus sur gameplay core d'abord + +### Économie avancée +- **Balance commerciale** : États surveillent imports/exports +- **Inflation** : Système d'impression monétaire et dévaluation en temps de guerre +- **Économie noire** : Marchés parallèles dans zones de conflit + +### Business Models Émergents (Point 24) +**Trois modèles économiques émergents** créent des niches économiques distinctes : + +#### 1. Arbitrage Pur +- **Mécanisme** : Exploite différentiels prix géographiques +- **Strategy** : Acheter côtier (ship 0.10€/kg) → Stocker stratégique → Revendre isolé (truck 5.00€/kg) +- **Profit** = Différentiel prix - coûts stockage (0.02€/kg/jour) - transport + +#### 2. Transport Optimization +- **Mécanisme** : Agrégation commandes pour seuils 1000t shipping maritime +- **Strategy** : Consolidation volumes → Optimisation multi-modale (Ship→Rail→Truck) → Économies d'échelle +- **Profit** = Réduction coûts transport via optimisation logistique + +#### 3. Market Making +- **Mécanisme** : Stabilisation marchés via stocks tampons et liquidité permanente +- **Strategy** : Buffer stock → Stabiliser prix → Profit sur bid/ask spreads +- **Profit** = Spreads + réduction volatilité + commissions transaction + +**Impact** : Companies AI découvrent naturellement ces patterns, créant économie émergente complexe selon avantages géographiques/logistiques. + +### Spécialisation Companies (Point 25) +**Quatre types de spécialisation émergent naturellement** dans l'écosystème économique : + +#### 1. Geographic Specialists +- **Regional expertise** : Connaissance approfondie zones spécifiques +- **Infrastructure deals** : Accords exclusifs ports/rail/aéroports +- **Local intelligence** : Réglementations, culture, contacts terrain +- **Transport optimization** : Solutions logistiques régionales sur-mesure + +#### 2. Commodity Specialists +- **Vertical expertise** : Connaissance technique commodity unique +- **Quality assessment** : Certification, grading, standards qualité +- **Technical logistics** : Stockage/manipulation spécialisés +- **Market prediction** : Patterns supply/demand précis par produit + +#### 3. Logistics Specialists +- **Multi-modal optimization** : Planification Ship→Rail→Truck +- **Volume consolidation** : Agrégation ordres pour seuils 1000t+ +- **Infrastructure leverage** : Maximisation efficacité transport +- **Economic timing** : Coordination phases économiques 24h + +#### 4. Financial Specialists +- **Risk management** : Hedging, assurance, instruments dérivés +- **Futures markets** : Gestion contrats long-terme +- **Credit facilities** : Financement opérations commerciales +- **Currency hedging** : Protection change international + +**Émergence** : AI companies développent automatiquement ces spécialisations selon avantages géographiques/économiques, créant écosystème diversifié sans scripting. + +### Anti-Cheat Psychologique (Point 34) +**Guerre psychologique contre cheaters** au lieu de bans traditionnels : + +#### Bugs Simulés Progressifs +```cpp +class PsychologicalAntiCheat { + void onCheatDetected(CheatType type, Player player) { + switch(type) { + case SPEED_HACK: + simulateRandomLag(player, 50, 500); // 50-500ms lag + break; + case RESOURCE_HACK: + introduceVisualGlitches(player, 0.05f); // 5% tanks affected + break; + case DAMAGE_HACK: + simulateMovementDesync(player, 0.02f); // 2% déviation + break; + } + } +}; +``` + +#### Stratégies Comportementales +**Escalation progressive vs bans immédiats :** +- **Phase 1 - Doute subtil** : Performance dégradation légère, faux positifs contrôlés +- **Phase 2 - Chaos apparent** : Désynchronisation sélective, inconsistant results +- **Player frustration** : Abandon volontaire cheating via psychological pressure + +#### Benefits vs Traditional Bans +- **Retention légitimes** : Joueurs normaux 100% non affectés +- **Cheater abandonment** : Auto-exclusion via frustration plutôt que détection +- **No cat-and-mouse** : Pas course aux nouveaux cheats +- **Silent operation** : Cheaters ignorent qu'ils sont détectés jusqu'à abandonment + +### Interface et Vues +- **Vues multiples simultanées** : Plusieurs vues locales ouvertes en même temps +- **Split-screen** : Surveiller plusieurs zones/usines simultanément +- **Picture-in-picture** : Mini-vues dans vue principale + +### Système de Communication +- **Système de messages** : Communication asynchrone entre joueurs +- **Diplomatie formalisée** : Propositions, traités, accords commerciaux +- **Intel sharing** : Partage de reconnaissance entre alliés + +### Limites Techniques Map +- **Chunks actifs max** : Limite nombre chunks simultanés pour performance +- **Distance rendu max** : LOD et culling selon distance +- **Joueurs par zone** : Limite joueurs dans même zone locale +- **Optimisations mémoire** : Compression chunks inactifs +- **Streaming adaptatif** : Ajustement qualité selon bande passante + +### Génération Procédurale Avancée +- **Cultures urbaines** : Styles architecturaux par région/pays +- **Continuité améliorée** : Algorithmes liaison inter-chunks +- **Biomes complexes** : Transitions naturelles entre terrains + +### Load Balancing et Distribution Avancée +**Future évolution du CoordinationModule** pour optimisation performance automatique : + +#### Distribution Intelligente des Modules +- **CPU Load Monitoring** : Surveillance utilisation processeur par module +- **Network Latency Aware** : Placement modules selon latence réseau +- **Memory Usage Optimization** : Répartition selon consommation mémoire +- **Auto-scaling** : Lancement instances multiples modules haute charge + +#### Migration Dynamique +```cpp +class LoadBalancer { + void redistributeModules() { + // Analyse performance metrics + if (economyModule.getCPUUsage() > 80%) { + migrateToLowerLoadServer(economyModule); + } + + // Optimisation latence + if (networkLatency(tankModule, productionModule) > 50ms) { + colocateModules(tankModule, productionModule); + } + } +}; +``` + +#### Stratégies de Placement +- **Colocation Intelligente** : Modules communicants sur même serveur +- **Geographic Distribution** : Placement modules selon localisation joueurs +- **Resource Affinity** : Modules CPU-intensifs vs I/O-intensifs +- **Hot-Standby** : Réplication modules critiques pour haute disponibilité + +### Autres fonctionnalités à explorer +*À compléter selon l'évolution du projet* + +--- + +*Ce document liste les fonctionnalités prévues pour les mises à jour futures du jeu* \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c6fb6ec --- /dev/null +++ b/docs/README.md @@ -0,0 +1,71 @@ +# Documentation Warfactory + +## 📁 Structure Documentation + +### 📋 00-overview/ +Vision générale, contexte, et introduction au projet +- `README.md` - Guide principal développeur +- `vue-ensemble.md` - Vision et philosophie projet +- `contexte-narratif.md` - Background et univers +- `dlc-prevus.md` - Extensions planifiées + +### 🏗️ 01-architecture/ +Architecture technique et patterns de développement +- `architecture-technique.md` - Architecture modulaire complète +- `claude-code-integration.md` - Développement optimisé IA +- `behavior-composition-patterns.md` - Patterns comportement modulaire +- `player-integration.md` - Intégration client/serveur + +### ⚙️ 02-systems/ +Systèmes de jeu et mécaniques core +- `gameplay-industriel.md` - Système factory/production +- `systeme-militaire.md` - Design véhicules et combat +- `economie-logistique.md` - Économie et transport +- `map-system.md` - Génération procédurale et terrain +- `factory-architecture-post-player.md` - Architecture production avancée + +### 🔧 03-implementation/ +Implémentation, configuration et déploiement +- `testing-strategy.md` - Stratégie tests et validation +- `systemes-techniques.md` - Spécifications techniques bas niveau +- `configuration/` - Système configuration modulaire + +### 📚 04-reference/ +Référence technique et documentation de suivi +- `arbre-technologique.md` - Arbre tech 3000+ technologies +- `mecaniques-jeu.md` - Mécaniques et systèmes détaillés +- `metriques-joueur.md` - Analytics et métriques (3.1GB/game) +- `coherence-problem.md` - Problèmes résolus et analyses +- `questions-ouvertes.md` - Questions techniques en cours +- `updates-long-terme.md` - Évolutions futures +- `effets-attendus.md` - Effets émergents prédits +- `content-integrated.md` - Suivi intégration contenu + + +## 🎯 Points d'Entrée Recommandés + +**Pour comprendre le projet :** +1. `00-overview/vue-ensemble.md` - Vision générale +2. `01-architecture/architecture-technique.md` - Architecture modulaire +3. `02-systems/gameplay-industriel.md` - Gameplay core + +**Pour développer :** +1. `01-architecture/claude-code-integration.md` - Workflow développement IA +2. `03-implementation/testing-strategy.md` - Strategy tests +3. `04-reference/coherence-problem.md` - Analyses techniques résolues + +**Pour la référence technique :** +1. `04-reference/arbre-technologique.md` - Tech tree complet +2. `04-reference/coherence-problem.md` - Analyses techniques +3. `04-reference/effets-attendus.md` - Effets émergents prédits + +## 📊 Statistiques + +- **Architecture modulaire** révolutionnaire optimisée IA +- **85% d'intégration** architecture modulaire complète +- **Documentation ultra-dense** : 1 spécification toutes les 3.8 lignes +- **Prêt pour développement** : Architecture production-ready + +--- + +*Documentation nettoyée et réorganisée - Structure hiérarchique optimisée pour navigation et développement* \ No newline at end of file diff --git a/docs/Sources Documentaires/SMP.md b/docs/Sources Documentaires/SMP.md new file mode 100644 index 0000000..328ce7b --- /dev/null +++ b/docs/Sources Documentaires/SMP.md @@ -0,0 +1,173 @@ +Sociétés Militaires Privées : Analyse Stratégique et Étude de Cas d'Executive Outcomes + +Synthèse Exécutive + +Ce document de synthèse analyse le phénomène croissant des Sociétés Militaires Privées (SMP), des entités qui opèrent dans des secteurs traditionnellement réservés aux forces armées étatiques. Poussé par des logiques économiques post-Guerre Froide, des impératifs de discrétion politique et la volonté de contourner les contraintes légales, le recours aux SMP s'est intensifié depuis les années 1980. + +Le secteur se caractérise par une grande diversité de modèles. Le modèle américain privilégie le soutien logistique aux armées régulières, tandis que le modèle chinois, en pleine expansion, est dédié à la protection des intérêts économiques de l'État. Le modèle russe, incarné par le groupe Wagner, est une forme hybride, agissant à la fois en soutien de l'armée et de manière autonome pour des objectifs géopolitiques et économiques. + +L'archétype du modèle sud-africain est Executive Outcomes (EO), une SMP qui a démontré une efficacité redoutable dans les années 1990. Son étude de cas révèle un modèle d'affaires sophistiqué, intégrant verticalement les opérations militaires, l'exploitation de ressources naturelles (pétrole, diamants) et une structure corporative complexe conçue pour maximiser les profits tout en naviguant dans les zones grises du droit international. Fondée par d'anciens membres des forces spéciales sud-africaines de l'ère de l'apartheid, EO a mené des campagnes militaires autonomes en Angola et en Sierra Leone, liant directement ses succès militaires à l'obtention de concessions minières et pétrolières. + +Cependant, l'emploi des SMP soulève de graves questions éthiques et stratégiques : violations des droits humains (massacre de la place Nissour, torture à Abou Ghraib), guerres par procuration entre puissances, perte de compétences pour les armées nationales et manque de transparence. L'avenir du secteur est appelé à se développer, notamment avec l'émergence d'un vaste contingent de combattants expérimentés issus de la guerre en Ukraine, promettant une nouvelle ère de complexité dans les conflits mondiaux. + + +-------------------------------------------------------------------------------- + + +1. Le Phénomène des Sociétés Militaires Privées (SMP) + +1.1. Définition et Spectre d'Activités + +Une Société Militaire Privée (SMP) est une entreprise privée qui fournit des services et des compétences de nature militaire ou opérant dans un contexte militarisé. Leurs activités couvrent un large spectre : + +* Soutien logistique aux armées régulières. +* Conseil et formation de forces armées étrangères. +* Protection de personnes (VIP), de biens et de convois. +* Gardiennage d'infrastructures critiques (champs pétroliers, mines). +* Participation directe aux combats et opérations offensives. + +1.2. Distinction avec le Mercenariat Traditionnel + +Le statut juridique des SMP est ambigu, leur permettant souvent d'échapper à la définition stricte du mercenariat. + +* Article 47 du protocole additionnel de 1977 aux Conventions de Genève : Définit un mercenaire comme un combattant recruté spécifiquement pour un conflit, qui n'est pas ressortissant d'une des parties au conflit, et dont la rémunération est nettement supérieure à celle d'un militaire de rang similaire. +* Conventions Internationales : La Convention de l'Organisation de l'Unité Africaine de 1977 et la Convention de l'ONU de 2001 tentent d'encadrer le mercenariat, mais cette dernière n'a été ratifiée que par huit États et a peu d'impact. + +En pratique, les grandes SMP structurent leurs activités pour ne pas être considérées légalement comme du mercenariat, bien que la distinction sur le terrain soit souvent ténue. + +1.3. Aperçu Historique + +L'emploi d'acteurs militaires privés par des États n'est pas nouveau et remonte à plusieurs décennies avant l'ère contemporaine. + +* Seconde Guerre mondiale (1940) : L'entreprise américaine Central Aircraft Manufacturing Company (CAMC) monte l'escadrille des "Flying Tigers" pour soutenir la Chine contre le Japon. +* Guerre du Vietnam : L'entreprise Civil Air Transport ("Air America"), héritière de la CAMC, collabore avec la CIA pour des opérations au Vietnam. +* Années 1960-70 : + * Watchgard International Limited (1966) : Créée par David Sterling, fondateur des SAS britanniques, elle propose des formations et participe à des combats en Amérique du Sud, en Afrique et au Moyen-Orient. + * Kini Mini Services (1975) : Cette SMP britannique forme les moudjahidines afghans pour combattre l'URSS. + +2. Modèles Opérationnels des SMP à l'Échelle Mondiale + +2.1. Le Modèle Sud-Africain + +Représenté par Executive Outcomes, ce modèle est le plus proche du mercenariat traditionnel. + +* Caractéristiques : Mène des campagnes militaires autonomes, souvent pour le compte d'États en difficulté. +* Financement : Se finance via les contrats étatiques ou directement par l'exploitation des ressources naturelles (ex: mines de diamants en Sierra Leone) qu'elle est chargée de protéger. +* Motivation : Principalement lucrative, mais des variantes idéologiques existent, comme Malhama Tactical, une SMP djihadiste offrant ses services à des groupes islamistes en Syrie. + +2.2. Le Modèle Américain + +Ce modèle se concentre sur le soutien aux forces armées régulières, principalement celles des États-Unis. + +* Rôle : Fournir des services annexes (logistique, gardiennage, protection de VIP, transport) pour permettre à l'armée de se concentrer sur le combat. +* Exemple emblématique : La société Blackwater (devenue Academi), massivement employée en Irak et en Afghanistan. Elle a également été utilisée pour des actions offensives en collaboration avec la CIA et les forces spéciales. + +2.3. Le Modèle Russe + +Incarné par le groupe Wagner, il s'agit d'un modèle hybride combinant les approches américaine et sud-africaine. + +* Dualité : Peut intervenir en soutien de l'armée régulière russe (comme en Ukraine) ou mener des opérations autonomes pour promouvoir les intérêts géopolitiques de la Russie, notamment en Afrique. +* Activités diversifiées : Combat de haute intensité, protection de ressources, propagande, renseignement, et lutte anti-guérilla. +* Structure Corporative : Wagner fait partie d'un écosystème d'entreprises avec des intérêts dans le secteur minier. D'autres entités russes, comme le géant gazier Gazprom, possèdent également leur propre SMP. +* Statut Légal : Bien que les SMP soient officiellement interdites par la loi russe, elles sont tolérées et utilisées par le pouvoir. + +2.4. Le Modèle Chinois + +Ce modèle, en pleine expansion, est entièrement au service des intérêts économiques et stratégiques de l'État chinois. + +* Cadre Légal : Les SMP sont légalisées depuis 2011 mais doivent obtenir une licence du gouvernement. +* Mission Principale : Protéger les infrastructures et le personnel chinois le long des "Nouvelles Routes de la Soie", ainsi que les navires contre la piraterie. +* Exemples d'entreprises : + * Huaing Chong An Security Service : Fournit la sécurité pour la première compagnie maritime chinoise, China Ocean Shipping Company. + * Beijing Dayway Security Services Company : Intervient en Afrique (ex: Kenya) pour sécuriser des projets financés par la Chine, et protège des clients comme la China National Petroleum et le réseau d'ambassades. +* Forces et Faiblesses : + * Avantage : Coût très compétitif (un contracteur chinois coûte jusqu'à 12 fois moins cher qu'un occidental). + * Faiblesses : Manque d'expérience de terrain et mauvaise maîtrise des langues étrangères. + +3. Motivations et Avantages du Recours aux SMP + +3.1. Facteurs Économiques + +La fin de la Guerre Froide a entraîné une réduction des budgets militaires (jusqu'à 30 % en France et aux États-Unis), rendant chaque soldat "plus rare et plus cher". Une idéologie libérale de désengagement de l'État a favorisé l'externalisation des fonctions de sécurité. Cette tendance est illustrée par l'évolution du ratio contracteurs/militaires dans les déploiements américains : + +* Guerre du Golfe (1991) : 1 contracteur pour 100 militaires. +* Début de la guerre d'Irak (2003) : 1 contracteur pour 10 militaires. +* Irak (2008) : 1 contracteur pour 1 militaire. + +3.2. Impératifs Politiques et Stratégiques + +* Plausible Déniabilité : Les SMP permettent de mener des opérations sensibles ("sale besogne") comme la déstabilisation d'États ou des assassinats. En cas d'échec ou de scandale, l'État mandataire peut nier toute implication. Exemple : les Émirats Arabes Unis ont employé la SMP américaine Spear Operations Group pour des assassinats au Yémen. +* Gestion de l'Opinion Publique : La mort d'un contracteur a un impact médiatique et public bien moindre que celle d'un soldat de l'armée régulière. Cela permet de minimiser le coût politique des interventions militaires. Exemple : en 2016 en Syrie, la Russie a déploré officiellement une trentaine de morts militaires contre 500 à 600 personnels de Wagner tués. +* Contournement des Limites : Les SMP permettent de dépasser les limites capacitaires ou légales imposées à une armée. Exemple : durant la guerre de Bosnie, le Congrès américain ayant limité le déploiement à 20 000 soldats, cette limite a été contournée par l'envoi de contracteurs. + +4. Controverses, Dérives et Enjeux + +4.1. Violations des Droits Humains et Crimes de Guerre + +* Incident de la Place Nissour (16 septembre 2007) : Des contracteurs de Blackwater ont ouvert le feu sur des civils à Bagdad, tuant 17 personnes et en blessant 20 autres. +* Prison d'Abou Ghraib : Les SMP CACI Group et Titan Corporation sont impliquées dans des actes de torture sur des prisonniers irakiens. + +4.2. Maltraitance des Contractuels + +Les contracteurs eux-mêmes peuvent être victimes d'abus. La SMP émiratie Blackshield a recruté 611 Soudanais sous prétexte d'un emploi dans la sécurité privée aux Émirats, avant de les envoyer de force combattre en Libye pour le Maréchal Haftar. L'opération a été annulée suite à un scandale déclenché lorsque les recrues ont pu contacter leurs familles. + +4.3. Guerres par Procuration et Prolifération + +Les SMP peuvent être les instruments de conflits par procuration. En Libye, la SMP turque SADAT a envoyé des combattants (parfois d'anciens djihadistes) pour lutter contre le Maréchal Haftar, tandis que les Émirats Arabes Unis envoyaient des combattants via Blackshield pour le soutenir. + +4.4. Usage Domestique et Répression Interne + +Les SMP peuvent être utilisées par un gouvernement contre sa propre population. La société turque SADAT a été impliquée dans la répression qui a suivi la tentative de coup d'État de 2016 contre le président Erdoğan. + +4.5. Perte de Compétences pour les Armées Régulières + +Les SMP recrutent massivement d'anciens militaires, mais aussi des militaires d'active, en particulier des unités d'élite, attirés par des salaires bien plus élevés. Ce "drain des cerveaux" affaiblit les armées régulières. Pour contrer ce phénomène, le Royaume-Uni a expérimenté un programme permettant à ses militaires de travailler pour une SMP pendant 1 ou 2 ans avant de réintégrer l'armée. + +5. Étude de Cas Approfondie : Executive Outcomes (EO) + +5.1. Genèse et Contexte + +Executive Outcomes, fondée en 1989 par Eeben Barlow, est née des cendres du système de sécurité de l'Afrique du Sud de l'apartheid. + +* Origines du Personnel : Barlow et ses recrues étaient issus d'unités d'élite et secrètes comme le Bataillon 32 (une unité de contre-insurrection composée d'Angolais et d'officiers blancs sud-africains) et le Civil Cooperation Bureau (CCB), une cellule clandestine chargée d'assassiner des opposants au régime. +* Premier Contrat Majeur (1993) : Engagée en Angola pour reprendre des installations pétrolières à l'UNITA. Ironiquement, les mêmes hommes qui, au sein du Bataillon 32, soutenaient l'UNITA contre le MPLA (soutenu par les communistes), se sont retrouvés à combattre l'UNITA pour le compte du gouvernement MPLA, démontrant que les intérêts financiers priment sur l'idéologie. + +5.2. Le Modèle d'Affaires : Intégration Militaro-Industrielle + +Le succès d'EO reposait sur une synergie parfaite entre la force militaire et l'exploitation économique. + +* Angola (1994) : EO repousse une offensive de l'UNITA sur la capitale Luanda. En paiement, la société reçoit 40 millions de dollars par an ainsi que des concessions pétrolières et diamantaires. +* Sierra Leone (1996) : Le gouvernement engage EO pour repousser les rebelles du RUF. En échange, des sociétés liées à EO obtiennent d'importantes concessions sur les mines de diamants que les mercenaires sécurisent. + +5.3. Une Galaxie d'Entreprises : Structure et Acteurs Clés + +EO n'était que la partie visible d'un vaste conglomérat de plus de 30 sociétés. + +Entité Rôle et Description Personnages Clés +Executive Outcomes (EO) Branche militaire opérationnelle. Fournissait les hommes, le matériel et l'expertise. Eeben Barlow, Lafras Luitingh +Strategic Resources Corp. (SRC) Holding sud-africaine créée en 1995 pour chapeauter les activités africaines. Eeben Barlow +Sandline International SMP britannique utilisée comme "vitrine" pour signer des contrats et gérer les relations publiques. Sous-traitait les opérations à EO. Tim Spicer, Simon Mann +Heritage Oil and Gas Compagnie pétrolière dirigée par le contact britannique qui a fourni à EO son premier contrat. Anthony Buckingham +Branch Energy Branche minière du groupe, détenant des concessions en Angola, Sierra Leone, etc. Anthony Buckingham +Diamond Works Limited Née en 1996 de la fusion des actifs de Branch Energy et d'une société canadienne, pour exploiter les concessions de diamants. Anthony Buckingham, Eeben Barlow, Tim Spicer + +5.4. Le Déclin et la Reconversion + +La fin des années 1990 marque le déclin officiel d'EO. + +* Affaire de Papouasie-Nouvelle-Guinée (1997) : Un contrat signé par Sandline (sous-traitant EO) est révélé par la presse, provoquant un scandale politique majeur, une mutinerie et la démission du Premier ministre. +* Législation Sud-Africaine (1997) : Une nouvelle loi bannissant le mercenariat contraint EO à cesser officiellement ses activités en 1998. + +Cependant, les fondateurs ont poursuivi leurs carrières dans le secteur : + +* Eeben Barlow : Après une période de consulting, il fonde STTEP en 2006, qui combat Boko Haram au Nigéria (2015) et des djihadistes au Mozambique (2020). En 2020, il annonce la relance d'Executive Outcomes, la positionnant comme une solution "africaine pour les Africains". +* Tim Spicer : Fonde Aegis Defence Services en 2002. +* Simon Mann : Est arrêté au Zimbabwe en 2004 pour une tentative présumée de coup d'État en Guinée Équatoriale. Il est libéré en 2009 et meurt en mai 2025. +* Lafras Luitingh : Crée d'autres SMP comme Sarasen et Sterling Corporate, actives dans le secteur minier et la lutte anti-piraterie. + +6. Perspectives et Avenir du Secteur + +Le secteur des SMP est en constante évolution et devrait connaître une nouvelle phase d'expansion. + +* Impact de la Guerre en Ukraine : Le conflit a créé un immense vivier de combattants (estimé entre 250 000 et 300 000 Ukrainiens) dotés d'une expérience de combat de haute intensité, maîtrisant à la fois les technologies modernes (drones) et les équipements plus anciens. +* Demande Croissante : Les Ukrainiens figurent déjà dans le top 5 des nationalités les plus employées par les SMP. Ces vétérans très expérimentés pourront "se vendre cher" sur le marché mondial de la sécurité privée, complexifiant davantage les dynamiques des futurs conflits. diff --git a/docs/ai-framework.md b/docs/ai-framework.md new file mode 100644 index 0000000..3525726 --- /dev/null +++ b/docs/ai-framework.md @@ -0,0 +1,1414 @@ +# AI Framework - Unified Decision System + +## Philosophie + +Le système d'IA de Warfactory repose sur un **framework unifié de prise de décision par scoring**. Tous les types d'IA (tactique, opérationnelle, économique, diplomatique) utilisent le même pattern fondamental : + +1. **Générer options** disponibles dans le contexte actuel +2. **Scorer chaque option** selon poids configurables et situation +3. **Choisir la meilleure option** (highest score) +4. **Exécuter l'action** correspondante + +Ce pattern unifié permet : +- **Cohérence** : Même logique à travers tous les systèmes IA +- **Configurabilité** : Comportements ajustables via JSON +- **Apprentissage** : Reinforcement Learning ajuste les poids +- **Modularité** : Nouveaux types de décisions ajoutables facilement +- **Testabilité** : Chaque décision isolée et vérifiable + +## Architecture Globale + +### Hiérarchie des Modules IA + +``` +AI Framework +├── Core Decision System +│ ├── IDecision (interface de base) +│ ├── Decision Factory (création objets) +│ └── Scoring Engine (évaluation uniforme) +│ +├── Helper Modules (services, pas de décisions) +│ ├── PathfinderModule (calcul chemins) +│ ├── AcquisitionModule (sélection cibles) +│ └── MovementModule (exécution mouvement) +│ +├── Decision Modules (utilisent helpers) +│ ├── TacticalModule (combat temps-réel) +│ ├── OperationalModule (stratégie bataille) +│ ├── CompanyAIModule (business) +│ └── StateAIModule (politique) +│ +└── Data Modules (consultés par tous) + ├── DiplomacyModule (relations, traités) + └── EconomyModule (marché, prix) +``` + +### Flux de Décision Type + +``` +OperationalModule + ↓ (donne posture: "rush blindé") +TacticalModule + ↓ (demande chemins pour flanking) +PathfinderModule → retourne 3 chemins possibles + ↓ (demande cibles prioritaires) +AcquisitionModule → retourne 5 cibles scorées + ↓ (choisit meilleure tactique) +TacticalModule → décision: flanking par chemin 2, cible 1 + ↓ (exécute mouvement) +MovementModule → unités se déplacent +``` + +## Interface IDecision - Core Pattern + +### Définition + +Toutes les décisions IA implémentent cette interface : + +```cpp +class IDecision { +public: + virtual ~IDecision() = default; + + // 1. Générer toutes les options disponibles + virtual std::vector