Repository navigation
bot turnstate cache
This document analyzes the introduction of a TurnState caching mechanism to optimize the MakaMek.Bots decision-making process. The primary goal is to eliminate redundant target evaluations between the MovementEngine and WeaponsEngine by caching results for units that have completed their movement.
-
Movement Phase: MovementEngine evaluates hundreds of potential paths for each friendly unit. For each path, it calls
TacticalEvaluator.EvaluateTargetsto assess offensive potential against all enemies. -
Weapons Phase: WeaponsEngine selects an attacker and calls
TacticalEvaluator.EvaluateTargetsagain to determine the best firing solution.
- EvaluateTargets is computationally expensive (raycasting, hit probability calculations).
- Calculations performed during MovementEngine's evaluation of the chosen path are effectively discarded.
- WeaponsEngine recalculates the exact same data (same unit, same position, same targets) that was likely calculated seconds earlier.
We propose a new class TurnState that persists across the phases of a single turn for a bot instance. It will use a ConcurrentDictionary to safely handle parallel evaluations from the MovementEngine.
public class TurnState
{
public Guid GameId { get; }
public int TurnNumber { get; }
// Key: (AttackerId, AttackerPositionDetails, TargetId, TargetPositionDetails)
// Value: Cached evaluation data (List of target evaluation data for that specific pair)
private readonly ConcurrentDictionary<TargetEvaluationKey, IReadOnlyList<TargetEvaluationData>> _targetEvaluationCache = new();
public TurnState(Guid gameId, int turnNumber)
{
GameId = gameId;
TurnNumber = turnNumber;
}
public bool TryGetTargetEvaluation(TargetEvaluationKey key, out IReadOnlyList<TargetEvaluationData> data)
{
return _targetEvaluationCache.TryGetValue(key, out data);
}
public void AddTargetEvaluation(TargetEvaluationKey key, IReadOnlyList<TargetEvaluationData> data)
{
_targetEvaluationCache.TryAdd(key, data);
}
}
public readonly record struct TargetEvaluationKey(
Guid AttackerId,
HexCoordinates AttackerCoords,
HexDirection AttackerFacing,
Guid TargetId,
HexCoordinates TargetCoords,
HexDirection TargetFacing
);Key properties:
- ConcurrentDictionary: Ensures thread-safety during parallel path evaluations in MovementEngine.
- Per-Pair Granularity: The cache stores the evaluation result for a single Attacker-Target pair. This is critical because EvaluateTargets is often called with different subsets of enemies or in different contexts. Caching the entire list result of EvaluateTargets would be fragile; caching per-pair is robust.
The cache needs to be cleared when the game state changes significantly enough that cross-phase caching is no longer valid.
-
Turn Transitions: The cache MUST be cleared (or a new
TurnStateinstance created) at the start of a new turn. - Phase Transitions: The cache SHOULD BE PRESERVED between Movement and Weapons phases to achieve the optimization goal.
-
Dynamic Updates: Because the cache key includes the exact coordinates and facing of both attacker and target, the cache automatically handles units moving.
- If MovementEngine evaluates
UnitA@Hex1vsEnemyB@Hex2:- If
EnemyBhas already moved toHex2, this entry is valid for the Weapons phase. - If
EnemyBhas not moved (is atHex2) but later moves toHex3:- In Weapons phase, we query
UnitA@Hex1vsEnemyB@Hex3. - The cache key (...,
Hex3, ...) will result in a MISS. - Correctness is maintained without explicit manual invalidation of specific units.
- In Weapons phase, we query
- If
- If MovementEngine evaluates
The Bot class will own the lifecycle of TurnState.
public class Bot : IBot
{
private ITurnState? _currentTurnState;
// ...
private void HandleGameCommand(object command)
{
// ...
if (command is TurnIncrementedCommand turnCmd)
{
// Reset state on new turn
_currentTurnState = new TurnState(_clientGame.Id, turnCmd.TurnNumber);
}
}
// ...
private async Task MakeDecision()
{
// Ensure state exists (lazy init if needed)
_currentTurnState ??= new TurnState(_clientGame.Id, _clientGame.TurnNumber);
// Pass to engine
await _currentDecisionEngine.MakeDecision(player, _currentTurnState);
}
}Update IBotDecisionEngine to accept the state.
public interface IBotDecisionEngine
{
Task MakeDecision(IPlayer player, ITurnState turnState);
}Update EvaluateTargets to use the cache. It will iterate through the provided potential targets, check the cache for each pair, and only calculate the missing ones.
public ValueTask<IReadOnlyList<TargetEvaluationData>> EvaluateTargets(
IUnit attacker,
MovementPath attackerPath,
IReadOnlyList<IUnit> potentialTargets,
ITurnState? turnState = null)
{
var allResults = new List<TargetEvaluationData>();
foreach (var target in potentialTargets)
{
// Construct Key
var key = new TargetEvaluationKey(
attacker.Id, attackerPath.Destination.Coordinates, attackerPath.Destination.Facing,
target.Id, target.Position.Coordinates, target.Position.Facing
);
IReadOnlyList<TargetEvaluationData> evaluationForOneTarget;
// Check Cache
if (turnState?.TryGetTargetEvaluation(key, out var cachedData) == true)
{
evaluationForOneTarget = cachedData;
}
else
{
// Calculate for this single target
// Note: The current internal logic of EvaluateTargets might need refactoring
// to support single-target evaluation efficiently, or we just extract the logic loop.
evaluationForOneTarget = CalculateForSingleTarget(attacker, attackerPath, target);
// Store
turnState?.AddTargetEvaluation(key, evaluationForOneTarget);
}
allResults.AddRange(evaluationForOneTarget);
}
return ValueTask.FromResult<IReadOnlyList<TargetEvaluationData>>(allResults);
}-
Memory Overhead:
- Assuming 100 paths * 20 targets = 2000 pairs per movement decision.
- Each entry ~150-200 bytes.
- Total per turn ~ 400KB - 1MB.
- This is negligible.
-
Concurrency:
TurnStateusesConcurrentDictionary, ensuring safe access during MovementEngine's parallel path evaluation.
-
TurnStateTests: Verify
ConcurrentDictionarybehavior and key equality logic. -
TacticalEvaluatorTests:
- Add test:
EvaluateTargets_ShouldUseCachedResult_WhenAvailable. - Add test:
EvaluateTargets_ShouldCacheNewResult_WhenNotAvailable. - Add test:
EvaluateTargets_ShouldMissCache_WhenTargetPositionChanged.
- Add test:
-
BotTests: Verify that MakeDecision passes the same
TurnStateinstance across different engine calls within the same turn.
- Global/Singleton Cache: Rejected. Hard to manage lifecycle.
- Caching in Engine: Rejected. Engines are stateless or scoped to phase.
- Per-List Caching: Rejected. EvaluateTargets inputs vary too much. Per-pair caching is robust and reusable.
- Create
TurnStateclass (+ITurnStateto simplify mocking in unit tests) andTargetEvaluationKeystruct. - Update IBotDecisionEngine signature.
- Update Bot to manage
TurnStatelifecycle. - Refactor
MakaMek.Botsproject to update all MakeDecision implementations. - Update
ITacticalEvaluatorand TacticalEvaluator to acceptTurnState. - Implement caching logic in TacticalEvaluator (extracting single-target eval logic).
- Update tests to cover caching scenarios.