Repository navigation
bot torso rotation evaluation
This document analyzes the current bot decision-making workflow for:
- Movement position evaluation (
TacticalEvaluator,MovementEngine) - Weapon targeting and attack declaration (
WeaponsEngine)
…and proposes enhancements so bots correctly account for Mech torso rotation (torso twist) when:
- Scoring offensive potential of candidate movement positions
- Deciding whether to rotate torso during
WeaponsAttackphase
src/MakaMek.Bots/Models/DecisionEngines/TacticalEvaluator.cssrc/MakaMek.Bots/Models/DecisionEngines/MovementEngine.cssrc/MakaMek.Bots/Models/DecisionEngines/WeaponsEngine.cssrc/MakaMek.Core/Models/Units/Mechs/Mech.cssrc/MakaMek.Presentation/UiStates/WeaponsAttackState.cssrc/MakaMek.Core/Models/Game/Phases/WeaponsAttackPhase.cs
Additional important mechanics involved:
src/MakaMek.Core/Data/Game/Commands/Client/WeaponConfigurationCommand.cs-
src/MakaMek.Core/Models/Game/BaseGame.cs(OnWeaponConfiguration) -
src/MakaMek.Core/Models/Map/HexCoordinatesExtensions.cs(IsInWeaponFiringArc)
Entry point: MovementEngine.MakeDecision.
- Enumerates reachable paths for each movement type (walk/run/jump)
- Evaluates each reachable
MovementPathwith_evaluator.EvaluatePath(unit, path, enemyUnits) - Picks the "best" path by sorting:
- DefensiveIndex ascending
- OffensiveIndex descending
- EnemiesInRearArc ascending
- HexesTraveled descending
OffensiveIndex is entirely produced by TacticalEvaluator.EvaluatePath.
Entry point: TacticalEvaluator.EvaluatePath.
DefensiveIndex = CalculateDefensiveIndex(path, enemyUnits)OffensiveIndex = Sum(EvaluateTargets(attacker, attackerPath, enemyUnits).Score)
EvaluateTargets:
- Collects all available weapons on the attacker.
- For each potential target:
- Builds a
targetPathfrom the target'sMovementTaken(or standing still). - Computes
viableWeapons = EvaluateWeaponsForTarget(attacker, attackerPath, targetPath, weapons). - If any viable weapons exist, it computes:
-
targetArc(rear/side/front bonus) based on target-facing vs attacker position targetScore = Sum(hitProbability * weapon.Damage) * arcBonus
-
- Builds a
EvaluateWeaponsForTarget:
- Checks line-of-sight.
- Checks range.
- Checks firing arc via:
attackerPath.Destination.Coordinates.IsInWeaponFiringArc(targetPath.Destination.Coordinates, weapon, attackerPath.Destination.Facing)
- Calculates hit probability through
CalculateHitProbability, which builds a hypotheticalAttackScenario.FromHypotheticaland callsToHitCalculator.
Entry point: WeaponsEngine.MakeDecision.
- Chooses a single attacker: first alive unit with
HasDeclaredWeaponAttack == falseandCanFireWeapons == true. - Builds list of enemies.
- Calls
_tacticalEvaluator.EvaluateTargets(attacker, attackerPath, enemies). - Selects the best target by
TargetScore.Score. - Picks weapons for that target based on:
- hit probability
- damage
- heat budget
- ammo conservation heuristic
- Sends
WeaponAttackDeclarationCommand.
Limitation: WeaponsEngine never sends a WeaponConfigurationCommand for torso rotation.
In Mech.cs:
-
PossibleTorsoRotationis the max number of hex-side steps allowed. -
CanRotateTorso => PossibleTorsoRotation > 0 && !HasUsedTorsoTwist. -
HasUsedTorsoTwistis true if anyTorso.Facing != Position.Facing. -
RotateTorso(HexDirection newFacing)setsTorso.Rotate(newFacing)if withinPossibleTorsoRotation. -
Mech.Facingis overridden:TorsoDirection ?? Position?.Facing. - Torso rotation resets:
- When
Mech.Positionchanges (movement), all torsos callResetRotation(). - On
Mech.ResetTurnState(), all torsos callResetRotation().
- When
WeaponsAttackState shows the expected "human" workflow:
- In action selection step, a mech can choose Turn Torso.
- It computes
_availableDirectionsby scanning all 6 directions and filtering bysteps <= mech.PossibleTorsoRotation. - On selection, it sends
WeaponConfigurationCommand:Configuration.Type = WeaponConfigurationType.TorsoRotationConfiguration.Value = (int)direction
- After rotation, the UI continues (target selection, weapon selection, declare attack).
WeaponsAttackPhase.HandleCommand:
-
WeaponConfigurationCommandis processed byGame.OnWeaponConfiguration(...)and re-broadcast. -
WeaponAttackDeclarationCommandis handled as the unit action.
BaseGame.OnWeaponConfiguration applies torso rotation:
- For
WeaponConfigurationType.TorsoRotation, it callsmech.RotateTorso((HexDirection)Value).
In TacticalEvaluator.EvaluateWeaponsForTarget the arc check passes attackerPath.Destination.Facing to IsInWeaponFiringArc.
-
HexPosition.Facingis the unit's base facing (leg facing/"forward facing") - Torso twist is a separate override on the torso parts (
Torso.Rotate) and is exposed throughMech.Facing
As a result, when a target is slightly outside the front/side arcs for the leg-facing, the bot assigns 0 viable weapons, even though a torso rotation would bring the target into arc.
Even if a torso twist would unlock significant damage, WeaponsEngine goes straight to WeaponAttackDeclarationCommand.
AttackScenario includes AttackerFacing, which feeds SecondaryTargetModifier calculations in ToHitCalculator.
Currently TacticalEvaluator.CalculateHitProbability passes attackerFacing: attackerPath.Destination.Facing, which again ignores torso twist.
(While the current bot uses only one target, this becomes more important once the bot starts splitting fire.)
The goal is to treat torso rotation as a choice variable in the bot's evaluation and decision pipeline:
- During movement evaluation, offensive potential should be computed as:
max_over_possible_torso_facings( expected_damage(attacker_position, torso_facing) )
- During weapons declaration, the bot should:
- choose torso facing + target + weapons as a joint optimization
- issue a
WeaponConfigurationCommandwhen beneficial - then issue
WeaponAttackDeclarationCommand(in a subsequent execution)
For a given attacker unit, determine available torso rotation options using the existing game API:
var torsoConfigs = attacker.GetWeaponsConfigurationOptions(atackerPath.Destination)
.Where(c => c.Type == WeaponConfigurationType.TorsoRotation)
.ToList();Always include the "no rotation" option representing the current leg facing:
var noRotationConfig = new WeaponConfiguration
{
Type = WeaponConfigurationType.None,
Value = (int)attackerPath.Destination.Facing
};
var allConfigs = new[] { noRotationConfig }.Concat(torsoConfigs).ToList();Changes to EvaluateWeaponsForTarget:
-
Enumerate all configurations using the approach above
-
Nested loop structure:
foreach (var config in allConfigs) { var facing = (HexDirection)config.Value; foreach (var weapon in weapons) { // Check configuration applicability if (!weapon.FirstMountPart.IsWeaponConfigurationApplicable(config.Type, attackerPath.Destination)) continue; // Check arc using resolved facing if (!attackerPath.Destination.Coordinates.IsInWeaponFiringArc( targetPath.Destination.Coordinates, weapon, facing)) //<-- "facing" is variable continue; // Rest of the existing code // Add to viable weapons with configuration tag viableWeapons.Add(new WeaponEvaluationData { Weapon = weapon, HitProbability = hitProb, Configuration = config // NEW: tag weapon with its config }); } }
-
Extend
WeaponEvaluationData:public class WeaponEvaluationData { public IWeapon Weapon { get; set; } public double HitProbability { get; set; } public WeaponConfiguration Configuration { get; set; } // NEW }
Result: The viable weapons list contains entries for all weapon-configuration pairs that pass all checks. Each weapon is tagged with the WeaponConfiguration that enables it.
Changes to EvaluatePath/EvaluateTargets:
When computing offensive score for each target:
// Group viable weapons by their required configuration
var configGroups = viableWeapons.GroupBy(w => w.Configuration);
// Calculate score for each configuration
var configScores = configGroups.Select(group =>
{
var weaponsForConfig = group.ToList();
var score = weaponsForConfig.Sum(w =>
w.HitProbability * w.Weapon.Damage
) * arcBonus;
return new { Configuration = group.Key, Score = score };
}).ToList();
// Take the maximum score across all configurations
var bestConfigScore = configScores.OrderByDescending(c => c.Score).First();
var targetScore = bestConfigScore.Score;When computing OffensiveIndex for the entire path:
OffensiveIndex = allTargets.Sum(t => t.BestScore);This ensures the offensive potential reflects the best possible torso rotation for each target.
Note: Defensive index calculation remains unchanged for now (uses leg-facing as it represents armor exposure from the attacker's perspective).
Key principle: Decision engines are stateless. Each MakeDecision execution:
- Observes current game state
- Produces exactly one command
- Returns (execution ends)
- Next execution is triggered by server command echo (subscription in Bot.cs)
Workflow for torso-aware weapon attacks:
Pseudo code, should be aligned with current implementation, only replacing its corresponding parts
public async Task<bool> MakeDecision()
{
var attacker = SelectAttacker();
if (attacker == null) return false;
var enemies = GetEnemies();
var attackerPath = GetAttackerPath(attacker);
// 1. Evaluate all targets with all torso configurations
var targetScores = _tacticalEvaluator.EvaluateTargets(
attacker, attackerPath, enemies);
if (!targetScores.Any())
{
// No viable attacks, declare empty attack to advance phase
await DeclareNoAttack(attacker);
return true;
}
// 2. Find best configuration across all targets
var bestOption = targetScores
.SelectMany(t => t.ConfigurationScores) // All config-score pairs
.OrderByDescending(cs => cs.Score)
.First();
var bestConfig = bestOption.Configuration;
var bestTarget = bestOption.Target;
// 3. Check if configuration needs to be applied
if (bestConfig.Type == WeaponConfigurationType.TorsoRotation)
{
if (!IsConfigurationApplied(attacker, bestConfig))
{
// Send configuration command and END execution
await _clientGame.ConfigureUnitWeapons(
new WeaponConfigurationCommand(
attacker.Id,
bestConfig
)
);
return true; // Execution ends here
}
}
// 4. Configuration is applied (or not needed)
// Select weapons and declare attack
var selectedWeapons = SelectWeapons(
attacker, bestTarget, bestConfig, enemies);
await _clientGame.DeclareWeaponAttack(
new WeaponAttackDeclarationCommand(
attacker.Id,
selectedWeapons
)
);
return true; // Execution ends here
}-
First execution: Bot evaluates → determines torso rotation needed → sends
WeaponConfigurationCommand→ returns -
Server processing: Calls
BaseGame.OnWeaponConfiguration→mech.RotateTorso(direction)→ broadcasts command echo -
Second execution (triggered by echo): Bot re-evaluates → sees torso already rotated → sends
WeaponAttackDeclarationCommand→ returns
Implementation helpers:
private bool IsConfigurationApplied(IUnit unit, WeaponConfiguration config)
{
if (config.Type == WeaponConfigurationType.None)
return true;
if (config.Type == WeaponConfigurationType.TorsoRotation && unit is Mech mech)
{
var desiredFacing = (HexDirection)config.Value;
return mech.Facing == desiredFacing;
}
return false;
}Extend TargetScore (pseudicode, must be adjusted to be aligned with actual types):
public class TargetScore
{
public IUnit Target { get; set; }
public double Score { get; set; }
// NEW: Keep all configuration options with their scores
public List<ConfigurationScore> ConfigurationScores { get; set; }
}
public class ConfigurationScore
{
public WeaponConfiguration Configuration { get; set; }
public double Score { get; set; }
public IUnit Target { get; set; }
public List<WeaponEvaluationData> ViableWeapons { get; set; }
}The goal is to allow WeaponsEngine to:
- See all configuration options
- Pick the globally best configuration
- Access the weapon list for that configuration
-
GetWeaponsConfigurationOptions()returns empty for non-mechs - Only
WeaponConfigurationType.Noneis evaluated - Behavior identical to current implementation
-
CanRotateTorso == falseorHasUsedTorsoTwist == true -
GetWeaponsConfigurationOptions()returns empty list - Only
WeaponConfigurationType.Noneis evaluated - Behavior identical to current implementation
-
IsInWeaponFiringArcaccepts explicitfacingparameter - Must pass the configuration's facing value, not default to
weapon.FirstMountPart.Facing - This avoids requiring actual state mutation during evaluation
Current bot declares all weapons at a single target. If/when splitting fire:
- Secondary target penalties depend on
AttackScenario.AttackerFacing - Must use the chosen configuration's facing (post-rotation), not leg-facing
- Already handled correctly if
CalculateHitProbabilityreceivesattackerFacing: (HexDirection)config.Value
Current CalculateDefensiveIndex uses actual enemy unit facing state.
Out of scope for this change: Assuming enemies can torso-twist to shoot the defender would require analogous "max over enemy configurations" logic in defensive scoring. This could be addressed in future iterations.
- Add
Configurationproperty toWeaponEvaluationData - Add
ConfigurationScorestoTargetScore(or similar changes to support required functionality)
- Modify
EvaluateWeaponsForTargetto:- Enumerate configurations via
GetWeaponsConfigurationOptions - Add nested loop over configurations
- Check
IsWeaponConfigurationApplicableper weapon - Use
config.Valueas facing for arc/scenario calculations - Tag each viable weapon with its configuration
- Enumerate configurations via
- Modify
EvaluatePathorEvaluateTargetsto:- Group weapons by configuration
- Calculate score per configuration
- Take max score for offensive index
- Preserve all configuration scores for
WeaponsEngine
- Modify
WeaponsEngine.MakeDecisionto:- Find best configuration across all targets
- Check
IsConfigurationApplied - Send
WeaponConfigurationCommandif needed (end execution) - Send
WeaponAttackDeclarationCommandif configuration ready (end execution)
- Verify movement evaluation favors positions with torso-twist opportunities
- Verify weapons engine correctly rotates torso when beneficial
- Verify stateless execution pattern (one command per call)
- Test edge cases (non-mechs, already-rotated, rotation-blocked)
This document describes current behavior and provides implementation guidance for torso-aware evaluation and torso rotation commands in bot decision-making. The design has been clarified to reflect:
- Use of existing
GetWeaponsConfigurationOptions()API - Configuration tagging at weapon evaluation level
- Grouped scoring by configuration
- Stateless decision engine pattern with server-driven workflow
- Correct usage of
WeaponConfigurationrecord structure