# 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
```cpp
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