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

// 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) :

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

// 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

{
  "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 !