aissia/docs/02-systems/factory-architecture-post-player.md

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 :

// SOA Layout pour SIMD readiness
struct BeltSystem {
    std::vector<float> positions_x;    // [x0, x1, x2, x3, ...]
    std::vector<float> positions_y;    // [y0, y1, y2, y3, ...]
    std::vector<int>   item_types;     // [t0, t1, t2, t3, ...]
    std::vector<float> 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

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

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 :

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.