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".

By: Thinkofdeath <thinkofdeath@spigotmc.org>

paper-api/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);
 
     /**

paper-api/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);
 
     /**

paper-api/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,

paper-api/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);
 
     /**