Package megamek.client.bot.princess

Class HeatMap

java.lang.Object
megamek.client.bot.princess.HeatMap
public class HeatMap extends Object
Tracks activity of units on the map. Board positions that are frequently occupied by units get higher values, while those that are the least frequent get lower values. This creates a rough history of where units were concentrated within the last couple of game turns which can be used for intelligent estimates about where they will be in future turns. Normal operation is to call ageMaps() method once per round so previously set entries are reduced over time.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HeatMap(int newTeamID)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    ageMaps(Game game)
    Reduces the values for every entry in the trackers.
    boolean
    canTrackIndividuals()
    Indicates if the movement tracker in this heat map will track individuals in addition to overall team
    void
    changeDecayEnabled(boolean newSetting)
    Change the setting to enable or disable decay rate on tracker weights
    int
    getActivityDecay()
    Reduction weight for aging the activity tracker
    Coords
    getHotSpot()
    Get the hotspot (position with high activity) with the highest rating.
    Coords
    getHotSpot(Coords testPosition, boolean topOnly)
    Get the closest hot-spot (position of high activity).
    List<Coords>
    getHotSpots()
    Get all hot-spots (positions of high activity) in descending order
    boolean
    getIsTrackingFriendlyTeam()
    Identifies if this is tracking a friendly team, so visibility and detection status don't apply
    double
    getMapTrimThreshold()
    Percentage of low-value tracking map entries allowed before they are removed
    int
    getMovementDecay()
    Reduction weight for aging the team movement and individual movement trackers
    int
    getRemovalWeight()
    The weight at which an entry is removed from the trackers when trimmed for size constraints.
    double
    getWeightScaling()
    Scaling factor applied when calculating weights for use in the trackers
    boolean
    isDecayEnabled()
    Determines if decay is applied to the map when ageMaps() is called.
    boolean
    isTrackable(Entity testEntity)
    Determines if a particular entity is valid for tracking i.e.
    void
    refreshLastKnownCache(Game game)
    Manually update the last known positions of tracked entities
    void
    setActivityDecay(int newSetting)
    Set the reduction weight applied to each entry in the activity tracker.
    void
    setIsTrackingFriendlyTeam(boolean newSetting)
    Tracking friendly entities doesn't require checking visibility or detection status
    void
    setMapTrimThreshold(double newSetting)
    When the percentage of minimum values in any tracker exceeds this value, any entries at or below mapTrimThreshold are removed to maintain efficiency.
    void
    setMovementDecay(int newSetting)
    Set reduction weight applied to the team movement and individual movement trackers
    void
    setMovementWeightValue(int newSetting)
    Base weight for movement trackers.
    void
    setRemovalWeight(int newSetting)
    The weight at which an entry is removed from the trackers when trimmed for size constraints.
    void
    setTrackIndividuals(boolean newSetting)
    Enable or disable tracking of individual unit movements
    void
    setWeightScaling(double newSetting)
    Scaling factor applied when calculating weights for the trackers.
    void
    updateTrackers(List<Entity> tracked)
    Adjusts the trackers using the current position of each provided entity that matches the team this heat map is tracking.
    void
    updateTrackers(MovePath detailedMove)
    Updates the trackers using a specific movement path.
    static boolean
    validateForTracking(Entity testEntity)
    Convenience method for external callers to pre-filter entities prior to passing them for processing into a heat map

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • HeatMap

      public HeatMap(int newTeamID)
      Constructor. Initializes trackers to empty but usable states.

  • Method Details

    • setMovementWeightValue

      public void setMovementWeightValue(int newSetting)
      Base weight for movement trackers. Large values will result in movement being retained longer. Normal range 1 to 10 with 3.0 being the default.
      Parameters:
      newSetting - positive value, minimum 1.0

    • canTrackIndividuals

      public boolean canTrackIndividuals()
      Indicates if the movement tracker in this heat map will track individuals in addition to overall team
      Returns:
      true if individual unit movement is being tracked

    • setTrackIndividuals

      public void setTrackIndividuals(boolean newSetting)
      Enable or disable tracking of individual unit movements
      Parameters:
      newSetting - true, to track individual movement of all units

    • isDecayEnabled

      public boolean isDecayEnabled()
      Determines if decay is applied to the map when ageMaps() is called. Default setting is true.
      Returns:
      false if decay rate is disabled

    • changeDecayEnabled

      public void changeDecayEnabled(boolean newSetting)
      Change the setting to enable or disable decay rate on tracker weights
      Parameters:
      newSetting - false, to disable decay

    • getActivityDecay

      public int getActivityDecay()
      Reduction weight for aging the activity tracker
      Returns:
      a negative number

    • setActivityDecay

      public void setActivityDecay(int newSetting)
      Set the reduction weight applied to each entry in the activity tracker. Higher absolute values will cause the entries to reduce more quickly, reducing their relative importance.
      Parameters:
      newSetting - a negative number

    • getMovementDecay

      public int getMovementDecay()
      Reduction weight for aging the team movement and individual movement trackers
      Returns:
      a negative number

    • setMovementDecay

      public void setMovementDecay(int newSetting)
      Set reduction weight applied to the team movement and individual movement trackers
      Parameters:
      newSetting - a negative number

    • getWeightScaling

      public double getWeightScaling()
      Scaling factor applied when calculating weights for use in the trackers
      Returns:
      positive, non-zero number, typically between 0.1 and 5.0 with default of 1.0

    • setWeightScaling

      public void setWeightScaling(double newSetting)
      Scaling factor applied when calculating weights for the trackers. 0.5 is half normal, 2.0 is twice normal, etc. Higher factor mean larger weight, and bigger impact on the map. Typical values will be in the range of 0.1 to 5.0, although values outside that are permitted.
      Parameters:
      newSetting - positive, non-zero number

    • getRemovalWeight

      public int getRemovalWeight()
      The weight at which an entry is removed from the trackers when trimmed for size constraints. Normally 0 (zero) but may be higher for more aggressive trimming.

    • setRemovalWeight

      public void setRemovalWeight(int newSetting)
      The weight at which an entry is removed from the trackers when trimmed for size constraints. Must be 0 (zero) or positive number.
      Parameters:
      newSetting - positive number, may be 0 (zero)

    • getMapTrimThreshold

      public double getMapTrimThreshold()
      Percentage of low-value tracking map entries allowed before they are removed
      Returns:
      number between MIN_TRACKER_TOLERANCE and 0.9

    • setMapTrimThreshold

      public void setMapTrimThreshold(double newSetting)
      When the percentage of minimum values in any tracker exceeds this value, any entries at or below mapTrimThreshold are removed to maintain efficiency. Typical values are between 0.1 and 0.5.
      Parameters:
      newSetting - positive value between MIN_TRACKER_TOLERANCE and MAX_TRACKER_TOLERANCE

    • getIsTrackingFriendlyTeam

      public boolean getIsTrackingFriendlyTeam()
      Identifies if this is tracking a friendly team, so visibility and detection status don't apply

    • setIsTrackingFriendlyTeam

      public void setIsTrackingFriendlyTeam(boolean newSetting)
      Tracking friendly entities doesn't require checking visibility or detection status
      Parameters:
      newSetting - true, if this is tracking entities on the same team

    • getHotSpots

      public List<Coords> getHotSpots()
      Get all hot-spots (positions of high activity) in descending order
      Returns:
      list of positions, or null if team activity tracker is empty

    • getHotSpot

      public Coords getHotSpot(Coords testPosition, boolean topOnly)
      Get the closest hot-spot (position of high activity). May return null if the activity tracker is empty.
      Returns:
      Coords with nearest hot-spot, or null if no valid position

    • getHotSpot

      public Coords getHotSpot()
      Get the hotspot (position with high activity) with the highest rating. If multiple hot-spots of equal value are present, any one of them may be returned.
      Returns:
      map position, may return null

    • updateTrackers

      public void updateTrackers(List<Entity> tracked)
      Adjusts the trackers using the current position of each provided entity that matches the team this heat map is tracking. Filters out gun emplacements and ejected MekWarriors/vehicle crews, as well as functional units with a dead pilot/crew.
      Parameters:
      tracked - list of entities to process

    • updateTrackers

      public void updateTrackers(MovePath detailedMove)
      Updates the trackers using a specific movement path. Filters out gun emplacements and ejected MekWarriors/vehicle crews. Because this information is only available for entities under direct Princess control, this is normally limited to tracking friendly entities.
      Parameters:
      detailedMove - MovePath object, which includes an entity reference and Coords for the positions moved through

    • ageMaps

      public void ageMaps(Game game)
      Reduces the values for every entry in the trackers. This will gradually reduce the weights over time for positions that are not regularly updated. If enough entries are below the set threshold, all entries which are at or below that threshold will be removed.

    • refreshLastKnownCache

      public void refreshLastKnownCache(Game game)
      Manually update the last known positions of tracked entities
      Parameters:
      game - current game

    • isTrackable

      public boolean isTrackable(Entity testEntity)
      Determines if a particular entity is valid for tracking i.e. it is a ground unit, deployed, on map, not hidden, and either considered a friendly unit or an enemy unit that is detected visually or through sensors. Ejected MekWarriors and vehicle crews, gun emplacements, and entities with dead crews ('carcass') are rejected.
      Parameters:
      testEntity - entity to check
      Returns:
      true, if entity is valid for tracking

    • validateForTracking

      public static boolean validateForTracking(Entity testEntity)
      Convenience method for external callers to pre-filter entities prior to passing them for processing into a heat map
      Parameters:
      testEntity - entity to check
      Returns:
      true, if entity is valid for testing