Package megamek.client.bot.princess

Class InfantryCombatHelper

java.lang.Object
megamek.client.bot.princess.InfantryCombatHelper
public class InfantryCombatHelper extends Object
Helper class for Princess AI infantry vs infantry combat decisions. Provides calculations and decision logic for initiating, reinforcing, and withdrawing from building/vessel interior combat using the MarinePointsScore system.

  • Constructor Details

    • InfantryCombatHelper

      public InfantryCombatHelper()

  • Method Details

    • calculateAttackerMPS

      public static int calculateAttackerMPS(Entity entity, Entity building)
      Calculate the Marine Points Score for an attacking unit.
      Parameters:
      entity - The attacking entity (must be Infantry)
      building - The target building/vessel
      Returns:
      MPS value for the attacker

    • calculateEnemyMPS

      public static int calculateEnemyMPS(Game game, Entity target, Entity attacker)
      Calculate total enemy defender MPS in a hex. Includes all enemy infantry + 50% of crew as potential defenders.
      Parameters:
      game - The current game
      target - The building/vessel being defended
      attacker - The attacking entity
      Returns:
      Total estimated defender MPS

    • calculateMPSRatio

      public static double calculateMPSRatio(int attackerMPS, int defenderMPS)
      Calculate MPS ratio (attacker / defender).
      Parameters:
      attackerMPS - Attacker's MPS
      defenderMPS - Defender's MPS
      Returns:
      Ratio, or 0 if defender MPS is 0

    • calculateInitiationThreshold

      public static double calculateInitiationThreshold(double bravery)
      Calculate initiation threshold based on bravery. Formula: 2.0 - (bravery / 3.0) * 0.5

      - Low bravery (0.1): ~2.0 (needs 2:1 odds) - Average bravery (1.5): ~1.75 (needs 7:4 odds) - High bravery (3.0): 1.5 (needs 3:2 odds)

      Parameters:
      bravery - Bravery value from BehaviorSettings (0.1 to 3.0)
      Returns:
      MPS ratio threshold required to initiate

    • calculateReinforcementTargetRatio

      public static double calculateReinforcementTargetRatio(double initiationThreshold, double hyperAggression)
      Calculate reinforcement target ratio based on aggression. Formula: initiationThreshold + (hyperAggression / 10.0)

      Princess will reinforce to maintain ratio above this target.

      Parameters:
      initiationThreshold - The threshold used to initiate combat
      hyperAggression - HyperAggression value from BehaviorSettings (0.25 to 500)
      Returns:
      Target MPS ratio to maintain via reinforcement

    • calculateWithdrawalThreshold

      public static double calculateWithdrawalThreshold(double initiationThreshold)
      Calculate withdrawal threshold. Formula: initiationThreshold * 0.75

      Provides hysteresis - won't withdraw until significantly worse than initiation threshold.

      Parameters:
      initiationThreshold - The threshold used to initiate combat
      Returns:
      MPS ratio threshold below which to withdraw

    • shouldInitiateCombat

      public static boolean shouldInitiateCombat(Entity attacker, Entity target, Game game, BehaviorSettings behavior)
      Determine if Princess should initiate infantry combat.
      Parameters:
      attacker - The potential attacking infantry
      target - The target building/vessel
      game - The current game
      behavior - Princess's behavior settings
      Returns:
      true if should initiate combat

    • shouldReinforce

      public static boolean shouldReinforce(Entity reinforcement, int targetId, Game game, BehaviorSettings behavior)
      Determine if Princess should reinforce existing infantry combat.
      Parameters:
      reinforcement - The potential reinforcement infantry
      targetId - The building/vessel ID where combat is happening
      game - The current game
      behavior - Princess's behavior settings
      Returns:
      true if should send reinforcement

    • shouldWithdraw

      public static boolean shouldWithdraw(Entity entity, int targetId, Game game, BehaviorSettings behavior)
      Determine if Princess should withdraw from infantry combat.
      Parameters:
      entity - The infantry unit in combat
      targetId - The building/vessel ID
      game - The current game
      behavior - Princess's behavior settings
      Returns:
      true if should withdraw

    • getEnemyInfantryInHex

      public static List<Entity> getEnemyInfantryInHex(Game game, Coords coords, int ownerId)
      Get all enemy infantry in a hex.
      Parameters:
      game - The current game
      coords - The coordinates to check
      ownerId - The owner ID of the attacking player
      Returns:
      List of enemy infantry entities

    • estimateCrewDefenders

      public static int estimateCrewDefenders(Entity target)
      Estimate crew defenders (50% of total crew). Uses 50% of the entity's crew size as potential defenders.
      Parameters:
      target - The target building/vessel
      Returns:
      Estimated number of crew defenders

    • findBestReinforcement

      @Deprecated(since="0.51.0", forRemoval=true) public static Entity findBestReinforcement(List<Entity> candidates, Entity target)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Find the best infantry unit to send as reinforcement. Priority: MPS/mass ratio, proximity, availability.
      Parameters:
      candidates - List of candidate units
      target - The target building/vessel
      Returns:
      Best reinforcement unit, or null if none suitable