warfactoryracine/docs/00-overview/vue-ensemble.md

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