Package megamek.client.bot.princess

Class UnitBehavior

java.lang.Object
megamek.client.bot.princess.UnitBehavior
Direct Known Subclasses:
UnitOrdersBehavior
public class UnitBehavior extends Object
Works out what each of the bot's units is doing this movement phase, and keeps the waypoints players give it.

This is Princess's original approach: each unit's waypoints are held here, in the bot's own memory, and the unit heads for the first one until it is within Princess.DISTANCE_TO_WAYPOINT hexes of it. CASPAR uses UnitOrdersBehavior instead, which reads the unit orders stored on each unit.

  • Constructor Details

    • UnitBehavior

      public UnitBehavior()

  • Method Details

    • calculateUnitBehavior

      protected UnitBehavior.BehaviorType calculateUnitBehavior(Entity entity, Princess owner)
      Worker function that calculates a unit's desired behavior.

    • logDecision

      protected static void logDecision(Entity entity, String rule, String detail)
      Logs which rule decided a unit's movement this phase, so a playtest log shows why a unit did or did not follow the player's orders.

    • isFleeOrdered

      public static boolean isFleeOrdered(Princess owner)
      Returns whether the bot has a standing order to flee toward an edge, given from the Bot Commands panel or the flee chat command.
      Parameters:
      owner - the bot
      Returns:
      true if every unit of the bot is ordered toward the bot's destination edge

    • isFollowingOrdersOverWithdrawal

      public boolean isFollowingOrdersOverWithdrawal(Entity entity, Princess owner)
      Returns whether a withdrawing unit follows the player's waypoints instead of heading for its retreat edge.

      A player's direct order outranks the unit's own Forced Withdrawal: a crippled unit sent to a hex goes there (issue #9038). Two orders still win over the waypoints: a gamemaster's order to withdraw, and the bot-wide flee order, which a withdrawing unit follows toward the ordered edge.

      Parameters:
      entity - the unit
      owner - the bot that owns the unit
      Returns:
      true if the unit is withdrawing under the bot's rules but has a waypoint to follow instead

    • getActiveWaypoint

      public Optional<Coords> getActiveWaypoint(Entity entity, Princess owner)
      Returns the waypoint that decides where the unit moves this phase, if a waypoint does. A bot-wide flee order and a withdrawal the player has not overridden both send the unit to an edge instead, so they return empty.
      Parameters:
      entity - the unit
      owner - the bot that owns the unit
      Returns:
      the unit's current waypoint when it is following its waypoints, otherwise empty

    • beginRanking

      public void beginRanking(Entity entity, Princess owner)
      Called before a unit's moves are ranked. Princess's waypoints need no preparation; UnitOrdersBehavior works out the unit's active waypoint once here.
      Parameters:
      entity - the unit about to have its moves ranked
      owner - the bot that owns the unit

    • endRanking

      public void endRanking()
      Called once a unit's moves are ranked; see beginRanking(megamek.common.units.Entity, megamek.client.bot.princess.Princess).

    • getBehaviorType

      public UnitBehavior.BehaviorType getBehaviorType(Entity entity, Princess owner)
      Gets (and calculates, if necessary), the behavior type for the given entity.

    • getCachedBehaviorType

      @Nullable public UnitBehavior.BehaviorType getCachedBehaviorType(Entity entity)
      The behavior already worked out for this unit, without working one out if none has been.

      For logging and analysis only. getBehaviorType(megamek.common.units.Entity, megamek.client.bot.princess.Princess) computes and caches on a miss, and what it computes depends on where everything is standing at the time - so asking early, for a unit that has not moved yet, would pin an answer the bot would otherwise have reached later with better information.

      Parameters:
      entity - the unit to look up
      Returns:
      the cached behavior, or null if this unit has not been evaluated this turn

    • overrideBehaviorType

      public void overrideBehaviorType(Entity entity, UnitBehavior.BehaviorType behaviorType)

    • getWaypointForEntity

      public Optional<Coords> getWaypointForEntity(Entity entity)
      Parameters:
      entity - the unit
      Returns:
      the unit's first waypoint, or empty when it has none

    • isDestinationUnreachable

      public boolean isDestinationUnreachable(Entity entity, Coords destination, Princess owner)
      Returns:
      true when the unit cannot reach the destination, so a waypoint there should be dropped

    • addEntityWaypoint

      public int addEntityWaypoint(Entity entity, List<Coords> waypoints, Princess owner)
      Adds waypoints to the end of the unit's list, dropping any the unit cannot reach.
      Returns:
      how many of the given waypoints were kept; 0 when none of them can be reached

    • addEntityWaypoint

      @Deprecated(since="0.51.0", forRemoval=true) public boolean addEntityWaypoint(Entity entity, Coords destination, Princess owner)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • removeHeadWaypoint

      public void removeHeadWaypoint(Entity entity)
      Removes the head waypoint from the entity's waypoint queue If waypoints were added (1,1) then (2,2), then (3,3), this would remove (1,1)
      Parameters:
      entity - the entity to remove the waypoint from

    • removeTailWaypoint

      public void removeTailWaypoint(Entity entity, Princess owner)
      Removes the tail waypoint from the entity's waypoint queue If waypoints were added (1,1) then (2,2) then (3,3), this would remove (3,3), good for an "undo" behavior.
      Parameters:
      entity - the entity to remove the waypoint from
      owner - the bot that owns the unit

    • setEntityWaypoints

      public int setEntityWaypoints(Entity entity, List<Coords> waypoints, Princess owner)
      Replaces the unit's waypoints with the given ones, dropping any the unit cannot reach.
      Returns:
      how many of the given waypoints were kept; 0 when none of them can be reached

    • clearWaypoints

      public void clearWaypoints(Entity entity, Princess owner)
      Clears all of one unit's waypoints.
      Parameters:
      entity - the unit
      owner - the bot that owns the unit

    • clearWaypoints

      public void clearWaypoints(Princess owner)
      Clears the waypoints of every unit of the bot.
      Parameters:
      owner - the bot

    • clear

      public void clear()
      Clears the entity behavior cache, should be done at the start of each movement phase