# Eagle0 AI Scoring System: Technical Documentation

## Overview

The Eagle0 AI scoring system is a sophisticated game state evaluation framework designed for the Shardok tactical combat layer. It uses a combination of immediate and lookahead scoring, handles both deterministic and non-deterministic commands, and employs different strategies for attackers and defenders.

## Architecture

### Main Entry Points

The `AIScoreCalculator` class provides four main entry points:

1. **`GuessedStateScore`** - Evaluates a game state based on the player's role (attacker/defender) and strategy
2. **`BestCommandIndex`** - Finds the best command from available options using lookahead search
3. **`CommandScore`** - Evaluates a specific command's score
4. **`EvaluateCommand`** - Lower-level command evaluation returning both immediate and lookahead scores

### Scoring Pipeline Flow

```
BestCommandIndex
    ├── AICommandFilter::FilterCommands (reduce search space)
    ├── For each filtered command:
    │   ├── Determine command type (deterministic/non-deterministic/has odds)
    │   ├── CalcOne (execute command with appropriate randomness)
    │   │   ├── Create inner engine copy
    │   │   ├── Execute command
    │   │   ├── GuessedStateScore (immediate evaluation)
    │   │   └── BasicLookaheadCalculator (recursive lookahead)
    │   └── Aggregate scores based on command type
    └── Select command with best lookahead score (tiebreak on immediate)
```

## Core Scoring Components

### 1. State Evaluation (`GuessedStateScore`)

The state scorer delegates to strategy-specific evaluators:

**Attacker Strategies:**
- `STRATEGY_ATTACK_CASTLES` - Prioritizes capturing castle positions
- `STRATEGY_ATTACK_UNITS` - Focuses on eliminating defender units
- `STRATEGY_HOLD_CASTLES` - Maintains control of captured castles
- `STRATEGY_CROSS_RIVERS` - Special water crossing objectives
- `STRATEGY_FLEE` - Escape-focused scoring

**Defender Strategies:**
- `STRATEGY_HOLD_CASTLES` - Defend critical castle positions
- `STRATEGY_SCATTER` - Spread units to avoid elimination
- `STRATEGY_FLEE` - Escape-focused scoring

### 2. Unit Value Calculation (`AIUnitScoreCalculator`)

Unit scores are computed using multiple factors:

**Base Unit Value:**
```cpp
battalionValue = battalionTypeMultiplier * (0.5 + armament/100) * 
                 (0.5 + training/100) * (0.5 + morale/100) * battalion.size
heroValue = max(0, kHeroExistenceBuf + statsValue + professionValue + vigorValue)
contextFreeValue = battalionValue + heroValue
```

**Battalion Type Multipliers:**
- Light Infantry: 1.0
- Heavy Infantry/Light Cavalry: 1.5
- Heavy Cavalry: 2.0
- Longbowmen: 1.25
- Undead: 0.25

**Contextual Modifiers:**
- Castle bonus: `1 + kCastleMultiplierBonus * (integrity + 25) / 100`
- On fire penalty: 0.25x multiplier
- Adjacent fire: 0.99x per adjacent fire
- On ice penalty: Based on ice integrity
- VIP in danger: -200 if VIP unit < 200 size and in enemy attack range

**Special Unit Considerations:**
- Undead value decreases with distance from enemies: `value / (1 + minimumDistance)`
- Defenders that attackers must kill (when not targeting castles): +200 existence bonus
- Controlled undead this round: +50 bonus

### 3. Victory Condition Scoring (`AIVictoryConditionScoreCalculator`)

**Critical Tile Holdings:**
- Attacker holding tile with claimable unit: 0 penalty
- Castle on fire: -200 * distance debuff to extinguishing position
- Unoccupied/held by unclaimable: -100 * distance debuff
- Defender-held: Varies based on unit value and distance

**Last Player Standing:**
- -200 per surviving enemy unit * distance debuff

### 4. Distance-Based Scoring

The system uses sophisticated distance calculations incorporating:
- Action point distances (movement cost)
- Brave water crossing capability
- Attack location analysis (adjacent, archery, mage, engineer positions)

**Distance Debuff Formula:**
```cpp
distanceDebuff = kMaxProximityBuf / (1 + distance / kDistanceDebufRatio)
where kMaxProximityBuf = 1.5, kDistanceDebufRatio = 8.0
```

## Command Type Handling

### Deterministic Commands
Commands with predictable outcomes (MOVE, CONTROL, END_TURN, etc.):
- Evaluated once with average random value (0.5)
- No repeated simulations needed

### Commands with Odds
Commands with success/failure chances (SCOUT, FEAR, etc.):
- Two evaluations: success case (high roll) and failure case (low roll)
- Final score: `lerp(failureScore, successScore, successChance)`
- Success roll: `1.0 - successChance/2`
- Failure roll: `(1.0 - successChance)/2`

### Non-Deterministic Commands
Commands with variable outcomes (MELEE, ARCHERY, etc.):
- Multiple evaluations with different random seeds
- Default: `maxRepeatCount` iterations (typically 3-5)
- Random values evenly distributed: `i / (maxRepeatCount - 1)`
- Final score: average of all evaluations

## Lookahead Search

The system uses recursive lookahead with:
- Configurable depth (`remainingLookahead` parameter)
- Asynchronous execution for parallelization
- Early termination on END_TURN commands
- Score propagation from future states

## Command Filtering

`AICommandFilter` reduces search space by eliminating obviously bad moves:

**Filtered Actions:**
- Meteor start when >4 hexes from enemies AND castles (attackers only)
- Fire spells not adjacent to enemies (attackers only)
- Fortify when far from objectives (attackers)
- Retreating/fleeing when winning
- Moving away from all enemies when outnumbered
- Abandoning last defender in critical castle

## Key Constants and Multipliers

### Unit Scoring
- `UNITS_BASE_MULTIPLIER`: 0.05
- `FLEE_UNIT_SCORE`: -10,000
- `CAPTURED_UNIT_SCORE`: -10,000
- `CAPTURED_VIP_SCORE`: -25,000
- `kHeroExistenceBuf`: 50
- `kProfessionValue`: 200

### Ranged Attack Values
- `kArcheryPossibleValue`: 38
- `kMeteorDirectTargetingEnemy`: 2 per soldier
- `kMeteorSplashTargetingEnemy`: 1 per soldier
- `kLightningPossibleValue`: 0.05 per soldier

### Victory Condition Values
- `MAX_DEFENDER_HELD_VALUE`: -1,200
- `UNHELD_VALUE`: 100
- `ON_FIRE_VALUE`: 200
- `SURVIVING_ENEMY_VALUE`: -200

## Score Aggregation

Final score calculation:
```cpp
score = UNITS_BASE_MULTIPLIER * roundsMultiplier * unitsTotal + victoryConditionTotal
```

Where:
- `roundsMultiplier = roundsRemaining / maxRounds`
- `unitsTotal` = sum of all unit values (attacker positive, defender negative)
- `victoryConditionTotal` = sum of victory condition scores

## Performance Optimizations

1. **Command Filtering**: Reduces search space by 30-70% on average
2. **Parallel Lookahead**: Async execution of future state evaluations
3. **Cached Distance Calculations**: ActionPointDistances and AttackLocations caching
4. **Early Game/Late Game Differentiation**: Simplified calculations after round 18
5. **Multithreading**: Controlled by `MULTITHREAD` compile flag

## Implementation Notes

### Random Number Generation
- Uses `SequenceRandomGenerator` for deterministic testing
- Multiple random seeds for non-deterministic command evaluation
- Carefully controlled randomness for consistent AI behavior

### Distance Calculations
- **Action Point Distances**: Accounts for movement costs, terrain, water crossing
- **Attack Locations**: Pre-computed valid attack positions for units
- **Caching**: Expensive distance calculations are cached and reused

### Strategy Selection
- Attackers use `AIAttackerStrategySelector` to choose appropriate strategy
- Defenders use `AIDefenderStrategySelector` based on game state
- Strategy affects unit valuations and objective prioritization

### Score Interpretation
- **Positive scores**: Favor the evaluating player
- **Negative scores**: Favor the opponent
- **Magnitude**: Indicates confidence/importance of the evaluation
- **Relative scoring**: Only score differences matter, not absolute values

This scoring system provides a robust framework for tactical AI decision-making, balancing immediate tactical gains with strategic objectives while handling the uncertainty inherent in combat outcomes.