# MacroEntity-Engine Documentation

## Engine Overview
**MacroEntity-Engine** handles companies, diplomacy, and administration points with macro-level strategic rhythm.

**Key Responsibilities:**
- Company management (2-4 features per company)
- Diplomatic relations and sanctions
- Administration points system (1000 points/day, 1 day = 10 min real)
- Macro-level strategic decisions (~1 action every 3-5 days per company)

## Core Systems

### Company Management
From `mecaniques-jeu.md`:
- **Company Features**: 2-4 distinct capabilities per company
- **Strategic Focus**: Specialization in military, economic, or industrial domains
- **Company Evolution**: Gradual expansion and capability development
- **AI Behavior**: Distinct personalities and strategic preferences

### Administration System
- **Point Allocation**: 1000 administration points per day (10 minutes real-time)
- **Action Costs**: Major decisions consume administration points
- **Daily Reset**: Fresh allocation each game day
- **Strategic Pacing**: Prevents rapid micro-management, encourages planning

### Diplomacy System
From `coherence-problem.md`:
- **Relations Management**: Company-to-company diplomatic status
- **Economic Sanctions**: Trade restrictions and embargos
- **Military Alliances**: Coordinated defense and intelligence sharing
- **Diplomatic Actions**: Treaties, trade agreements, conflict declarations

## Engine Architecture

### Core Classes
```cpp
class MacroEntityEngine {
    // Company management (2-4 features per company)
    void createCompany(int companyId, const std::string& name);
    void updateCompanyFeatures(int companyId);

    // Administration (1000 points/day, 1 day = 10 min real)
    bool consumeAdminPoints(int companyId, int points);
    void resetDailyAdminPoints(int companyId);

    // Diplomacy (sanctions, embargos, relations)
    void setDiplomaticRelation(int company1, int company2, const std::string& relation);
    void applySanctions(int targetCompany, const std::vector<std::string>& sanctions);

    // Performance: ~1 action every 3-5 days per company (macro rhythm)
    double getActionFrequency() const { return actionFrequency_; }
};
```

### Communication with Other Engines
- **Economy-Engine**: Diplomatic trade relations, sanctions impact
- **War-Engine**: Military alliances, conflict coordination
- **Intelligence-Engine**: Diplomatic intelligence, espionage operations
- **All Engines**: Company-level decision coordination and policy implementation

## Key Design Documents
- `mecaniques-jeu.md` - Administration and company systems
- `coherence-problem.md` - Diplomatic balance and sanctions
- `architecture-technique.md` - Macro-level performance requirements
- `economie-logistique.md` - Company economic interactions

## Implementation Notes
- Macro rhythm: 1 action every 3-5 days prevents micro-management
- Administration points create meaningful strategic choices
- Company features provide distinct strategic identities
- Diplomatic actions have long-term consequences across all systems