Implement API for "main hand" and "off hand" slots.

Also deprecate existing "hand" API as it is not specific about which hand is being referred to. Implementations should default this method to the "main hand".

4 files changed, 91 insertions, 4 deletions

diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index 3f8646dd..ff8b4331 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -105,7 +105,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
      * Returns the ItemStack currently in your hand, can be empty.
      *
      * @return The ItemStack of the item you are currently holding.
+     * @deprecated Humans may now dual wield in their off hand, use explicit
+     * methods in {@link PlayerInventory}.
      */
+    @Deprecated
     public ItemStack getItemInHand();
 
     /**
@@ -113,7 +116,10 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
      * user was holding.
      *
      * @param item The ItemStack which will end up in the hand
+     * @deprecated Humans may now dual wield in their off hand, use explicit
+     * methods in {@link PlayerInventory}.
      */
+    @Deprecated
     public void setItemInHand(ItemStack item);
 
     /**
diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 24dfd201..6b0c53a0 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -9,16 +9,56 @@ public interface EntityEquipment {
 
     /**
      * Gets a copy of the item the entity is currently holding
+     * in their main hand.
      *
      * @return the currently held item
      */
+    ItemStack getItemInMainHand();
+
+    /**
+     * Sets the item the entity is holding in their main hand.
+     *
+     * @param item The item to put into the entities hand
+     */
+    void setItemInMainHand(ItemStack item);
+
+    /**
+     * Gets a copy of the item the entity is currently holding
+     * in their off hand.
+     *
+     * @return the currently held item
+     */
+    ItemStack getItemInOffHand();
+
+    /**
+     * Sets the item the entity is holding in their off hand.
+     *
+     * @param item The item to put into the entities hand
+     */
+    void setItemInOffHand(ItemStack item);
+
+    /**
+     * Gets a copy of the item the entity is currently holding
+     *
+     * @deprecated entities can duel wield now use the methods for the
+     *      specific hand instead
+     * @see #getItemInMainHand()
+     * @see #getItemInOffHand()
+     * @return the currently held item
+     */
+    @Deprecated
     ItemStack getItemInHand();
 
     /**
      * Sets the item the entity is holding
      *
+     * @deprecated entities can duel wield now use the methods for the
+     *      specific hand instead
+     * @see #setItemInMainHand(ItemStack)
+     * @see #setItemInOffHand(ItemStack)
      * @param stack The item to put into the entities hand
      */
+    @Deprecated
     void setItemInHand(ItemStack stack);
 
     /**
diff --git a/src/main/java/org/bukkit/inventory/EquipmentSlot.java b/src/main/java/org/bukkit/inventory/EquipmentSlot.java
index 0b2eb984..1e7d7711 100644
--- a/src/main/java/org/bukkit/inventory/EquipmentSlot.java
+++ b/src/main/java/org/bukkit/inventory/EquipmentSlot.java
@@ -3,6 +3,7 @@ package org.bukkit.inventory;
 public enum EquipmentSlot {
 
     HAND,
+    OFF_HAND,
     FEET,
     LEGS,
     CHEST,
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index b79a4f02..f475bba7 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -106,17 +106,57 @@ public interface PlayerInventory extends Inventory {
     public void setBoots(ItemStack boots);
 
     /**
-     * Returns the ItemStack currently hold
+     * Gets a copy of the item the player is currently holding
+     * in their main hand.
      *
-     * @return The currently held ItemStack
+     * @return the currently held item
      */
+    ItemStack getItemInMainHand();
+
+    /**
+     * Sets the item the player is holding in their main hand.
+     *
+     * @param item The item to put into the player's hand
+     */
+    void setItemInMainHand(ItemStack item);
+
+    /**
+     * Gets a copy of the item the player is currently holding
+     * in their off hand.
+     *
+     * @return the currently held item
+     */
+    ItemStack getItemInOffHand();
+
+    /**
+     * Sets the item the player is holding in their off hand.
+     *
+     * @param item The item to put into the player's hand
+     */
+    void setItemInOffHand(ItemStack item);
+
+    /**
+     * Gets a copy of the item the player is currently holding
+     *
+     * @deprecated players can duel wield now use the methods for the
+     *      specific hand instead
+     * @see #getItemInMainHand()
+     * @see #getItemInOffHand()
+     * @return the currently held item
+     */
+    @Deprecated
     public ItemStack getItemInHand();
 
     /**
-     * Sets the item in hand
+     * Sets the item the player is holding
      *
-     * @param stack Stack to set
+     * @deprecated players can duel wield now use the methods for the
+     *      specific hand instead
+     * @see #setItemInMainHand(ItemStack)
+     * @see #setItemInOffHand(ItemStack)
+     * @param stack The item to put into the player's hand
      */
+    @Deprecated
     public void setItemInHand(ItemStack stack);
 
     /**