Add camera clamp tests and improve javadocs

Author: nightm4re94

buildSrc/src/main/groovy/testing-defaults.gradle

@@ -13,3 +13,20 @@ jacocoTestReport {
     xml.required = true
   }
 }
+
+configurations {
+  mockitoAgent
+}
+
+dependencies {
+  testImplementation(libs.mockito.core)
+  mockitoAgent(libs.mockito.core) {
+    transitive = false
+  }
+}
+
+tasks {
+  test {
+    jvmArgs += "-javaagent:${configurations.mockitoAgent.asPath}"
+  }
+}

litiengine/src/main/java/de/gurkenlabs/litiengine/abilities/effects/AttributeEffect.java

@@ -32,6 +32,7 @@ protected AttributeEffect(final TargetingStrategy targetingStrategy, final Modif
    * @param targetingStrategy the strategy to determine the targets of the effect
    * @param modification      the type of modification to apply to the attribute
    * @param delta             the value to modify the attribute by
+   * @param duration          the duration of the effect in milliseconds
    */
   protected AttributeEffect(final TargetingStrategy targetingStrategy, final Modification modification, final double delta,
     final int duration) {
@@ -58,6 +59,7 @@ protected AttributeEffect(final TargetingStrategy targetingStrategy, final IComb
    * @param executingEntity   the entity executing the effect
    * @param modification      the type of modification to apply to the attribute
    * @param delta             the value to modify the attribute by
+   * @param duration          the duration of the effect in milliseconds
    */
   protected AttributeEffect(final TargetingStrategy targetingStrategy, final ICombatEntity executingEntity, final Modification modification,
     final double delta, final int duration) {

litiengine/src/main/java/de/gurkenlabs/litiengine/abilities/effects/Effect.java

@@ -78,6 +78,11 @@ public void onEffectApplied(final EffectAppliedListener listener) {
     this.appliedListeners.add(listener);
   }
 
+  /**
+   * Removes a listener that was previously registered to be notified when the effect is applied.
+   *
+   * @param listener The listener to remove.
+   */
   public void removeEffectAppliedListener(final EffectAppliedListener listener) {
     this.appliedListeners.remove(listener);
   }
@@ -91,6 +96,11 @@ public void onEffectCeased(final EffectCeasedListener listener) {
     this.ceasedListeners.add(listener);
   }
 
+  /**
+   * Removes a listener that was previously registered to be notified when the effect ceases.
+   *
+   * @param listener The listener to remove.
+   */
   public void removeEffectCeasedListener(final EffectCeasedListener listener) {
     this.ceasedListeners.remove(listener);
   }

litiengine/src/main/java/de/gurkenlabs/litiengine/abilities/effects/EffectEvent.java

@@ -3,21 +3,49 @@
 import de.gurkenlabs.litiengine.entities.ICombatEntity;
 import java.util.EventObject;
 
+/**
+ * Represents an event related to an {@code Effect} being applied to a combat entity. This class provides information about the effect and the entity
+ * it is applied to.
+ */
 public class EffectEvent extends EventObject {
   private static final long serialVersionUID = -6911987630602502891L;
+
+  /**
+   * The combat entity associated with this event. This field is transient to avoid serialization issues.
+   */
   private final transient ICombatEntity combatEntity;
+
+  /**
+   * The effect associated with this event. This field is transient to avoid serialization issues.
+   */
   private final transient Effect effect;
 
+  /**
+   * Initializes a new instance of the {@code EffectEvent} class.
+   *
+   * @param effect       The effect that triggered this event.
+   * @param combatEntity The combat entity affected by the effect.
+   */
   EffectEvent(final Effect effect, final ICombatEntity combatEntity) {
     super(effect);
     this.effect = effect;
     this.combatEntity = combatEntity;
   }
 
+  /**
+   * Gets the combat entity associated with this event.
+   *
+   * @return The {@code ICombatEntity} affected by the effect.
+   */
   public ICombatEntity getCombatEntity() {
     return this.combatEntity;
   }
 
+  /**
+   * Gets the effect associated with this event.
+   *
+   * @return The {@code Effect} that triggered this event.
+   */
   public Effect getEffect() {
     return this.effect;
   }

litiengine/src/main/java/de/gurkenlabs/litiengine/attributes/Attribute.java

@@ -13,11 +13,19 @@
  * @param <T> the type of the attribute value, which must be a Number
  */
 public class Attribute<T extends Number> implements IAttribute<T>, Serializable {
-  private static final String VALUE_PROPERTY = "value";
+  /**
+   * The support object used to manage and notify property change listeners. It allows other components to listen for changes to the properties of
+   * this object.
+   */
   protected final PropertyChangeSupport support;
+  /**
+   * The base value of the attribute. This value represents the unmodified state of the attribute before any modifiers are applied.
+   */
+  protected T value;
+  private static final String VALUE_PROPERTY = "value";
   private final transient PropertyChangeListener modifierListener;
   private final List<AttributeModifier<T>> modifiers = new ArrayList<>();
-  protected T value;
+
 
   /**
    * Default no-argument constructor.

litiengine/src/main/java/de/gurkenlabs/litiengine/entities/behavior/AStarGrid.java

@@ -20,8 +20,15 @@
  * managing and rendering a grid of A* nodes. It supports diagonal movement and allows updating the walkable state of nodes based on collisions.</p>
  */
 public class AStarGrid implements IRenderable {
+  /**
+   * The penalty value assigned to nodes that intersect with static, indestructible props.
+   */
   public static final double PENALTY_STATIC_PROP = 5;
+  /**
+   * The penalty value assigned to nodes that have non-walkable neighboring nodes.
+   */
   public static final double PENALTY_NOT_WALKABLE_NEIGHBOR = 4;
+
   private final AStarNode[][] grid;
   private final int nodeSize;
   private final Dimension size;

litiengine/src/main/java/de/gurkenlabs/litiengine/entities/behavior/AStarNode.java

@@ -3,33 +3,52 @@
 import java.awt.Point;
 import java.awt.Rectangle;
 
+/**
+ * Represents a node in the A* pathfinding algorithm. Each node contains information about its position, costs, and walkability.
+ */
 public class AStarNode {
-  // diagonal length: 1 * Math.sqrt(2) ~ 1.4
   private static final double DIAGONAL_COST = 1.4;
   private final Rectangle bound;
   private final int gridX;
   private final int gridY;
   private double gCost;
   private double hCost;
-
   private double penalty;
   private AStarNode predecessor;
   private boolean walkable;
 
+  /**
+   * Constructs a new AStarNode with the specified properties.
+   *
+   * @param walkable Whether the node is walkable.
+   * @param bound    The rectangular bounds of the node.
+   * @param gridX    The x-coordinate of the node in the grid.
+   * @param gridY    The y-coordinate of the node in the grid.
+   */
   public AStarNode(
-      final boolean walkable, final Rectangle bound, final int gridX, final int gridY) {
+    final boolean walkable, final Rectangle bound, final int gridX, final int gridY) {
     this.bound = bound;
     this.gridX = gridX;
     this.gridY = gridY;
     this.walkable = walkable;
   }
 
+  /**
+   * Gets the rectangular bounds of this node.
+   *
+   * @return The bounds of the node.
+   */
   public Rectangle getBounds() {
     return this.bound;
   }
 
+  /**
+   * Calculates the movement cost from this node to the target node.
+   *
+   * @param target The target node.
+   * @return The movement cost to the target node.
+   */
   public double getCosts(final AStarNode target) {
-
     final int dstX = Math.abs(this.getGridX() - target.getGridX());
     final int dstY = Math.abs(this.getGridY() - target.getGridY());
 
@@ -41,95 +60,157 @@ public double getCosts(final AStarNode target) {
   }
 
   /**
-   * Gets the total costs for this node.
+   * Gets the total cost (f-cost) for this node. The f-cost is the sum of g-cost and h-cost.
    *
-   * @return The total costs.
+   * @return The total cost.
    */
   public double getFCost() {
     return this.getGCost() + this.getHCost();
   }
 
   /**
-   * Gets the costs so far for this node.
+   * Gets the cost from the start node to this node (g-cost).
    *
-   * @return The costs so far.
+   * @return The g-cost.
    */
   public double getGCost() {
     return this.gCost;
   }
 
+  /**
+   * Gets the x-coordinate of this node in the grid.
+   *
+   * @return The x-coordinate.
+   */
   public int getGridX() {
     return this.gridX;
   }
 
+  /**
+   * Gets the y-coordinate of this node in the grid.
+   *
+   * @return The y-coordinate.
+   */
   public int getGridY() {
     return this.gridY;
   }
 
   /**
-   * Gets the estimated costs for this node.
+   * Gets the estimated cost from this node to the target node (h-cost).
    *
-   * @return The estimated costs.
+   * @return The h-cost.
    */
   public double getHCost() {
     return this.hCost;
   }
 
+  /**
+   * Gets the center location of this node as a Point.
+   *
+   * @return The center location of the node.
+   */
   public Point getLocation() {
     return new Point((int) this.getBounds().getCenterX(), (int) this.getBounds().getCenterY());
   }
 
+  /**
+   * Gets the penalty cost for this node.
+   *
+   * @return The penalty cost.
+   */
   public double getPenalty() {
     return this.penalty;
   }
 
+  /**
+   * Gets the predecessor node in the path.
+   *
+   * @return The predecessor node.
+   */
   public AStarNode getPredecessor() {
     return this.predecessor;
   }
 
+  /**
+   * Checks if this node is walkable.
+   *
+   * @return True if the node is walkable, false otherwise.
+   */
   public boolean isWalkable() {
     return this.walkable;
   }
 
+  /**
+   * Sets the cost from the start node to this node (g-cost).
+   *
+   * @param gCost The g-cost to set.
+   */
   public void setGCost(final double gCost) {
     this.gCost = gCost;
   }
 
+  /**
+   * Sets the estimated cost from this node to the target node (h-cost).
+   *
+   * @param hCost The h-cost to set.
+   */
   public void setHCost(final double hCost) {
     this.hCost = hCost;
   }
 
+  /**
+   * Sets the penalty cost for this node.
+   *
+   * @param penalty The penalty cost to set.
+   */
   public void setPenalty(final double penalty) {
     this.penalty = penalty;
   }
 
+  /**
+   * Sets the predecessor node in the path.
+   *
+   * @param predecessor The predecessor node to set.
+   */
   public void setPredecessor(final AStarNode predecessor) {
     this.predecessor = predecessor;
   }
 
+  /**
+   * Sets whether this node is walkable.
+   *
+   * @param walkable True if the node is walkable, false otherwise.
+   */
   public void setWalkable(final boolean walkable) {
     this.walkable = walkable;
   }
 
-  /** Clears the assigned costs and the predecessor. */
+  /**
+   * Clears the assigned costs and the predecessor for this node.
+   */
   public void clear() {
     this.setGCost(0);
     this.setHCost(0);
     this.setPredecessor(null);
   }
 
+  /**
+   * Returns a string representation of this node, including its grid position and costs.
+   *
+   * @return A string representation of the node.
+   */
   @Override
   public String toString() {
     return "["
-        + this.getGridX()
-        + ","
-        + this.getGridY()
-        + "] - (f:"
-        + this.getFCost()
-        + ", g:"
-        + this.getGCost()
-        + ", h:"
-        + this.getHCost()
-        + ")";
+      + this.getGridX()
+      + ","
+      + this.getGridY()
+      + "] - (f:"
+      + this.getFCost()
+      + ", g:"
+      + this.getGCost()
+      + ", h:"
+      + this.getHCost()
+      + ")";
   }
 }