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()
    Deprecated, for removal: This API element is subject to removal in a future version.
    void
    changeDecayEnabled(boolean newSetting)
    Deprecated, for removal: This API element is subject to removal in a future version.
    int
    getActivityDecay()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Coords
    getHotSpot()
    Get the hotspot (position with high activity) with the highest rating.
    Coords
    getHotSpot(Coords testPosition, boolean topOnly)
    Gets the hot-spot (position of recorded activity) nearest the given position.
    List<Coords>
    getHotSpots()
    Get all hot-spots (positions of high activity) in descending order
    boolean
    getIsTrackingFriendlyTeam()
    Deprecated, for removal: This API element is subject to removal in a future version.
    double
    getMapTrimThreshold()
    Deprecated, for removal: This API element is subject to removal in a future version.
    int
    getMovementDecay()
    Deprecated, for removal: This API element is subject to removal in a future version.
    int
    getRemovalWeight()
    Deprecated, for removal: This API element is subject to removal in a future version.
    double
    getWeightScaling()
    Deprecated, for removal: This API element is subject to removal in a future version.
    boolean
    isDecayEnabled()
    Deprecated, for removal: This API element is subject to removal in a future version.
    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)
    Deprecated, for removal: This API element is subject to removal in a future version.
    void
    setMovementWeightValue(int newSetting)
    Base weight for movement trackers.
    void
    setRemovalWeight(int newSetting)
    Deprecated, for removal: This API element is subject to removal in a future version.
    void
    setTrackIndividuals(boolean newSetting)
    Deprecated, for removal: This API element is subject to removal in a future version.
    void
    setWeightScaling(double newSetting)
    Deprecated, for removal: This API element is subject to removal in a future version.
    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

      @Deprecated(since="0.51.0", forRemoval=true) public boolean canTrackIndividuals()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public void setTrackIndividuals(boolean newSetting)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Enable or disable tracking of individual unit movements
      Parameters:
      newSetting - true, to track individual movement of all units

    • isDecayEnabled

      @Deprecated(since="0.51.0", forRemoval=true) public boolean isDecayEnabled()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Determines if decay is applied to the map when ageMaps() is called. Default setting is true.
      Returns:
      false if decay rate is disabled

    • changeDecayEnabled

      @Deprecated(since="0.51.0", forRemoval=true) public void changeDecayEnabled(boolean newSetting)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Change the setting to enable or disable decay rate on tracker weights
      Parameters:
      newSetting - false, to disable decay

    • getActivityDecay

      @Deprecated(since="0.51.0", forRemoval=true) public int getActivityDecay()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public int getMovementDecay()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Reduction weight for aging the team movement and individual movement trackers
      Returns:
      a negative number

    • setMovementDecay

      @Deprecated(since="0.51.0", forRemoval=true) public void setMovementDecay(int newSetting)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Set reduction weight applied to the team movement and individual movement trackers
      Parameters:
      newSetting - a negative number

    • getWeightScaling

      @Deprecated(since="0.51.0", forRemoval=true) public double getWeightScaling()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public void setWeightScaling(double newSetting)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public int getRemovalWeight()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public void setRemovalWeight(int newSetting)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public double getMapTrimThreshold()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Deprecated(since="0.51.0", forRemoval=true) public boolean getIsTrackingFriendlyTeam()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

      @Nullable public Coords getHotSpot(Coords testPosition, boolean topOnly)
      Gets the hot-spot (position of recorded activity) nearest the given position. When topOnly is false, every recorded hot-spot is considered and the nearest one is returned. When topOnly is true, only the single highest-rated tier of hot-spots is considered, and the nearest within that tier is returned.
      Parameters:
      testPosition - The position to measure distance from
      topOnly - When true, only the highest-rated tier of hot-spots is considered; when false, all recorded hot-spots are considered
      Returns:
      The Coords of the nearest considered hot-spot, or null if there are none

    • 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