Merge remote-tracking branch 'upstream/master'

# Conflicts:
#	src/main/java/io/luna/game/model/mob/combat/CombatAction.java
#	src/main/java/io/luna/game/model/mob/combat/CombatDamage.java

Author: hydrozoa-yt

data/game/def/spells.json

@@ -91,6 +91,25 @@ public void submit(Action<?> action) {
         types.add(action.getClass());
     }
 
+    /**
+     * Submits {@code action} only if no other action of the same concrete type is currently being processed.
+     * <p>
+     * This method uses the action's runtime class as a uniqueness key. If that type has not already been registered,
+     * the action is submitted as normal.
+     * <p>
+     * If an action of the same class is already present, this method does nothing.
+     *
+     * @param action The action to submit if its concrete type is not already active.
+     */
+    public void submitIfAbsent(Action<?> action) {
+        Class<?> type = action.getClass();
+        if (types.add(type)) {
+            processing.put(action.actionType, action);
+            action.setState(ActionState.PROCESSING);
+            action.onSubmit();
+        }
+    }
+
     /**
      * Returns whether this queue currently contains an action whose concrete class is exactly {@code type}.
      * <p>
@@ -103,6 +122,26 @@ public boolean contains(Class<? extends Action<?>> type) {
         return types.contains(type);
     }
 
+    /**
+     * Returns all processing and executing actions assignable to {@code type}.
+     *
+     * @param type The action base type.
+     * @return All matching actions.
+     */
+    public <T extends Action<?>> T first(Class<T> type) {
+        for (Action<?> action : processing.values()) {
+            if (type.isAssignableFrom(action.getClass())) {
+                return (T) action;
+            }
+        }
+        for (Action<?> action : executing) {
+            if (type.isAssignableFrom(action.getClass())) {
+                return (T) action;
+            }
+        }
+        return null;
+    }
+
     /**
      * Returns all processing and executing actions assignable to {@code type}.
      *

src/main/java/io/luna/game/action/ActionQueue.java

@@ -8,7 +8,7 @@
 import static com.google.common.base.Preconditions.checkState;
 
 /**
- * An enum representing movement directions.
+ * Represents a cardinal, diagonal, or stationary movement direction.
  *
  * @author lare96
  * @author Graham
@@ -25,7 +25,9 @@ public enum Direction {
     SOUTH_EAST(7, 1, -1);
 
     /**
-     * A list of directions representing all possible directions of the NPC view cone, in order.
+     * Ordered directions used when evaluating the NPC view cone.
+     * <p>
+     * The order is significant, as adjacent entries represent neighboring directions in the cone calculation.
      */
     public static final ImmutableList<Direction> VIEW_CONE = ImmutableList.of(
             Direction.NORTH,
@@ -37,51 +39,91 @@ public enum Direction {
             Direction.EAST,
             Direction.NORTH_EAST
     );
+
+    /**
+     * The four cardinal directions in north-east-south-west order.
+     */
+    public static final ImmutableList<Direction> NESW = ImmutableList.of(NORTH, EAST, SOUTH, WEST);
+
     /**
-     * An array of directions without any diagonal directions.
+     * The four cardinal directions in west-north-east-south order.
+     * <p>
+     * This ordering matches the client collision mapping layout.
      */
-    public final static ImmutableList<Direction> NESW = ImmutableList.of(NORTH, EAST, SOUTH, WEST);
+    public static final ImmutableList<Direction> WNES = ImmutableList.of(WEST, NORTH, EAST, SOUTH);
 
     /**
-     * An array of directions without any diagonal directions, and one step counter-clockwise, as used by
-     * the clients collision mapping.
+     * The four diagonal directions in the ordering used by the client collision mapping.
      */
-    public final static ImmutableList<Direction> WNES = ImmutableList.of(WEST, NORTH, EAST, SOUTH);
+    public static final ImmutableList<Direction> WNES_DIAGONAL = ImmutableList.of(NORTH_WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST);
 
     /**
-     * An array of diagonal directions, and one step counter-clockwise, as used by the clients collision
-     * mapping.
+     * All defined directions, including {@link #NONE}.
      */
-    public final static ImmutableList<Direction> WNES_DIAGONAL = ImmutableList.of(NORTH_WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST);
     public static final ImmutableList<Direction> ALL = ImmutableList.copyOf(values());
+
+    /**
+     * All defined directions except {@link #NONE}.
+     */
     public static final ImmutableList<Direction> ALL_EXCEPT_NONE = ImmutableList.copyOf(values()).stream().
             filter(it -> it != Direction.NONE).collect(ImmutableList.toImmutableList());
 
-
+    /**
+     * Cardinal components for {@link #NORTH_EAST}.
+     */
     private static final ImmutableList<Direction> NORTH_EAST_COMPONENTS = ImmutableList.of(NORTH, EAST);
+
+    /**
+     * Cardinal components for {@link #NORTH_WEST}.
+     */
     private static final ImmutableList<Direction> NORTH_WEST_COMPONENTS = ImmutableList.of(NORTH, WEST);
+
+    /**
+     * Cardinal components for {@link #SOUTH_EAST}.
+     */
     private static final ImmutableList<Direction> SOUTH_EAST_COMPONENTS = ImmutableList.of(SOUTH, EAST);
-    private static final ImmutableList<Direction> SOUTH_WEST_COMPONENTS = ImmutableList.of(SOUTH, WEST);
 
+    /**
+     * Cardinal components for {@link #SOUTH_WEST}.
+     */
+    private static final ImmutableList<Direction> SOUTH_WEST_COMPONENTS = ImmutableList.of(SOUTH, WEST);
 
     /**
-     * The direction identifier.
+     * The client-facing direction identifier.
      */
     private final int id;
+
+    /**
+     * The x-axis translation applied by this direction.
+     */
     private final int translateX;
+
+    /**
+     * The y-axis translation applied by this direction.
+     */
     private final int translateY;
 
     /**
-     * Creates a new {@link Direction}.
+     * Creates a new direction.
      *
-     * @param id The direction identifier.
+     * @param id The client-facing direction identifier.
+     * @param translateX The x-axis translation for this direction.
+     * @param translateY The y-axis translation for this direction.
      */
     Direction(int id, int translateX, int translateY) {
         this.id = id;
         this.translateX = translateX;
         this.translateY = translateY;
     }
 
+    /**
+     * Selects a random non-biased movement direction.
+     * <p>
+     * If {@link #NONE} is initially selected, a second roll is performed against either the cardinal or diagonal
+     * direction groups so that a movement direction is always returned.
+     *
+     * @return A random direction other than {@link #NONE}.
+     */
     public static Direction random() {
         Direction selected = RandomUtils.random(ALL);
         if (selected == Direction.NONE) {
@@ -95,9 +137,13 @@ public static Direction random() {
     }
 
     /**
-     * Gets the direction as an integer as used orientation in the client maps (WNES as opposed to NESW).
+     * Converts this direction into the forced movement orientation value used by the client.
+     * <p>
+     * This mapping uses the client's west-north-east-south orientation scheme rather than the direction enum ordinal
+     * ordering.
      *
-     * @return The direction as an integer.
+     * @return The forced movement orientation identifier.
+     * @throws IllegalStateException If called for {@link #NONE}.
      */
     public int toForcedMovementId() {
         switch (this) {
@@ -119,15 +165,29 @@ public int toForcedMovementId() {
 
     }
 
-
+    /**
+     * @return The x translation.
+     */
     public int getTranslateX() {
         return translateX;
     }
 
+    /**
+     * @return The y translation.
+     */
     public int getTranslateY() {
         return translateY;
     }
 
+    /**
+     * Gets all directions visible from the supplied facing direction within the three-direction NPC view cone.
+     * <p>
+     * The returned set contains the supplied direction and its two adjacent directions in {@link #VIEW_CONE}.
+     *
+     * @param from The base facing direction.
+     * @return The visible directions for that facing direction.
+     * @throws IllegalStateException If the supplied direction does not exist in {@link #VIEW_CONE}.
+     */
     public static Set<Direction> getAllVisible(Direction from) {
         int baseIndex = -1;
         for (int index = 0; index < VIEW_CONE.size(); index++) {
@@ -147,10 +207,13 @@ public static Set<Direction> getAllVisible(Direction from) {
     }
 
     /**
-     * Get the 2 directions which make up a diagonal direction (i.e., NORTH and EAST for NORTH_EAST).
+     * Gets the two cardinal directions that compose a diagonal direction.
+     * <p>
+     * For example, {@link #NORTH_EAST} resolves to {@link #NORTH} and {@link #EAST}.
      *
-     * @param direction The direction to get the components for.
-     * @return The components for the given direction.
+     * @param direction The diagonal direction to decompose.
+     * @return The two cardinal component directions.
+     * @throws IllegalArgumentException If {@code direction} is not diagonal.
      */
     public static ImmutableList<Direction> diagonalComponents(Direction direction) {
         switch (direction) {
@@ -167,6 +230,11 @@ public static ImmutableList<Direction> diagonalComponents(Direction direction) {
         throw new IllegalArgumentException("Must provide a diagonal direction.");
     }
 
+    /**
+     * Gets the opposite of this direction.
+     *
+     * @return The opposite direction, or {@link #NONE} if this direction is {@link #NONE}.
+     */
     public Direction opposite() {
         switch (this) {
             case NORTH_WEST:
@@ -191,13 +259,19 @@ public Direction opposite() {
     }
 
     /**
-     * Returns the direction between two sets of coordinates.
+     * Resolves the direction from one coordinate pair to another.
+     * <p>
+     * Both coordinate differences must normalize to the range {@code [-1, 1]}. This is intended for adjacent-tile
+     * movement and stationary comparisons.
      *
-     * @param currentX The current x coordinate.
-     * @param currentY The current y coordinate.
-     * @param nextX The next x coordinate.
-     * @param nextY The next y coordinate.
-     * @return The direction between the current and next coordinates.
+     * @param currentX The starting x coordinate.
+     * @param currentY The starting y coordinate.
+     * @param nextX The destination x coordinate.
+     * @param nextY The destination y coordinate.
+     * @return The direction from the starting coordinates to the destination
+     * coordinates.
+     * @throws IllegalArgumentException If the normalized difference falls outside the valid adjacent-step
+     * range.
      */
     @SuppressWarnings("Duplicates")
     public static Direction between(int currentX, int currentY, int nextX, int nextY) {
@@ -233,11 +307,11 @@ public static Direction between(int currentX, int currentY, int nextX, int nextY
     }
 
     /**
-     * Returns the direction between two positions.
+     * Resolves the direction from one position to another.
      *
-     * @param current The current step.
-     * @param next The next step.
-     * @return The direction between the current and next steps.
+     * @param current The starting position.
+     * @param next The destination position.
+     * @return The direction from {@code current} to {@code next}.
      */
     public static Direction between(Position current, Position next) {
         return between(current.getX(), current.getY(), next.getX(), next.getY());
@@ -250,6 +324,9 @@ public final int getId() {
         return id;
     }
 
+    /**
+     * @return {@code true} if this direction is diagonal, otherwise {@code false}.
+     */
     public boolean isDiagonal() {
         switch (this) {
             case NORTH_EAST:

src/main/java/io/luna/game/model/Direction.java

@@ -103,11 +103,36 @@ public enum EquipmentBonus {
          */
         PRAYER(11);
 
+        static {
+            STAB_ATTACK.opposite = STAB_DEFENCE;
+            SLASH_ATTACK.opposite = SLASH_DEFENCE;
+            CRUSH_ATTACK.opposite = CRUSH_DEFENCE;
+            MAGIC_ATTACK.opposite = MAGIC_DEFENCE;
+            RANGED_ATTACK.opposite = RANGED_DEFENCE;
+
+            STAB_DEFENCE.opposite = STAB_ATTACK;
+            SLASH_DEFENCE.opposite = SLASH_ATTACK;
+            CRUSH_DEFENCE.opposite = CRUSH_ATTACK;
+            MAGIC_DEFENCE.opposite = MAGIC_ATTACK;
+            RANGED_DEFENCE.opposite = RANGED_ATTACK;
+
+            STRENGTH.opposite = STRENGTH;
+            PRAYER.opposite = PRAYER;
+        }
+
         /**
          * The fixed array index for this bonus type.
          */
         private final int index;
 
+        /**
+         * The logical opposite of this bonus.
+         * <p>
+         * Attack bonuses map to their corresponding defence bonuses, and vice versa. Bonus types that
+         * do not have a natural opposite return themselves.
+         */
+        private EquipmentBonus opposite;
+
         /**
          * Creates a new {@link EquipmentBonus}.
          *
@@ -125,6 +150,31 @@ public enum EquipmentBonus {
         public int getIndex() {
             return index;
         }
+
+        /**
+         * Returns the logical opposite of this bonus type.
+         * <p>
+         * Examples:
+         * <ul>
+         *     <li>{@link #STAB_ATTACK} returns {@link #STAB_DEFENCE}</li>
+         *     <li>{@link #STAB_DEFENCE} returns {@link #STAB_ATTACK}</li>
+         *     <li>{@link #STRENGTH} returns {@link #STRENGTH}</li>
+         * </ul>
+         *
+         * @return The opposite bonus type, or this bonus itself if no paired opposite exists.
+         */
+        public EquipmentBonus getOpposite() {
+            return opposite;
+        }
+
+        /**
+         * Returns whether this bonus has a distinct opposite bonus rather than mapping to itself.
+         *
+         * @return {@code true} if this bonus maps to a different bonus type, otherwise {@code false}.
+         */
+        public boolean hasDistinctOpposite() {
+            return opposite != this;
+        }
     }
 
     /**