warfactoryracine/docs/engines/map/README.md

Map-Engine Documentation

Engine Overview

Map-Engine handles procedural generation, chunk streaming, and multi-scale map coordination with 218+ terrain elements.

Key Responsibilities:

• Procedural terrain generation with budget system (-10 to +10)
• Chunk management (64x64 tiles, streaming on demand)
• Multi-scale map coordination (World → Regional → Local → Detail)
• Fog of War coordination with Intelligence-Engine

Core Systems

Procedural Generation

From map-system.md:

• 218 Terrain Elements: Comprehensive terrain feature set
• Budget System: -10 to +10 scoring for balanced generation
• Millions of Combinations: Procedural variety through element mixing
• Scale-Appropriate Detail: Different detail levels for each map scale

Chunk System

From systemes-techniques.md:

• 64x64 Tiles: Standard chunk size (1m×1m tiles)
• Streaming: On-demand loading/unloading for memory optimization
• Persistent Storage: Chunk data persistence across sessions
• Memory Management: Automatic cleanup of unused chunks

Multi-Scale Architecture

• World Scale: Diplomatic and strategic overview
• Regional Scale: Logistics and major operations
• Local Scale: Factory and base management
• Detail Scale: Combat and precise operations

Engine Architecture

Core Classes

class MapEngine {
    // Chunk management (64x64 tiles, 1m×1m)
    std::shared_ptr<Chunk> getChunk(int x, int y);
    void generateChunk(int x, int y);
    void unloadChunk(int x, int y);

    // FOW (granularity: chunk level)
    void updateFOW(int companyId, const std::vector<std::pair<int,int>>& visibleChunks);
    bool isChunkVisible(int companyId, int x, int y) const;

    // 218 procedural elements, budget -10 to +10
    void generateTerrain(int chunkX, int chunkY);
};

Communication with Other Engines

• Intelligence-Engine: FOW coordination and chunk visibility
• War-Engine: Combat terrain effects, battle locations
• Logistic-Engine: Route planning across multiple scales
• Factory-Engine: Terrain suitability for industrial development
• All Engines: Coordinate actions across appropriate map scales

Key Design Documents

• map-system.md - Complete multi-scale map system
• systemes-techniques.md - Chunk system and memory management
• architecture-technique.md - Performance requirements and streaming
• coherence-problem.md - Multi-scale coordination challenges

Implementation Notes

• 218 terrain elements provide rich procedural variety
• Budget system ensures balanced and interesting terrain
• Chunk streaming maintains performance with large worlds
• Multi-scale coordination requires careful data synchronization