warfactoryracine/docs/engines/event/README.md

Event-Engine Documentation

Engine Overview

Event-Engine handles the breakthrough system, global events, and event-driven mechanics throughout the game.

Key Responsibilities:

• Breakthrough system processing (scrap analysis → technology)
• Global event generation (geopolitical, natural disasters)
• Event scheduling and timing
• Research progression triggers

Core Systems

Breakthrough System

From mecaniques-jeu.md:

• Scrap Analysis: Combat wreckage provides technology insights
• Technology Discovery: Reverse engineering captured equipment
• Progressive Unlocks: Gradual technology revelation
• Failure/Success Mechanics: Not all analysis succeeds

Global Events

From arbre-technologique.md:

• Geopolitical Events: International conflicts, alliances
• Natural Disasters: Impact on production and logistics
• Market Events: Economic shocks, resource discoveries
• Technology Events: Scientific breakthroughs, espionage

Event Scheduling

• Delayed Events: Timed consequences of player actions
• Cascading Events: Events triggering other events
• Random Events: Procedural event generation
• Player-Triggered Events: Research completions, diplomatic actions

Engine Architecture

Core Classes

class EventEngine {
    // Event management
    void scheduleEvent(std::unique_ptr<GameEvent> event, double delaySeconds);
    void triggerImmediateEvent(std::unique_ptr<GameEvent> event);

    // Breakthrough system (event-driven with scrap analysis)
    void analyzeScrapForBreakthrough(const std::string& scrapData);
    void triggerBreakthrough(const std::string& technologyDomain);

    // Global events
    void generateRandomEvent();
    void processScheduledEvents();
};

Communication with Other Engines

• War-Engine: Receives battle data for scrap analysis
• Intelligence-Engine: Coordinates breakthrough discoveries
• MacroEntity-Engine: Triggers diplomatic events
• Economy-Engine: Generates market disruption events
• All Engines: Broadcasts global events affecting all systems

Key Design Documents

• mecaniques-jeu.md - Breakthrough system and research mechanics
• arbre-technologique.md - Technology progression events
• architecture-technique.md - Event processing performance
• coherence-problem.md - Event balance and timing

Implementation Notes

• Event-driven architecture for breakthrough system
• Scrap analysis probability mechanics
• Global event impact on all game systems
• Cascading event chains for complex scenarios