LivingEntity Active Item API

API relating to items being actively used by a LivingEntity
such as a bow or eating food.

Co-authored-by: Jake Potrebic <jake.m.potrebic@gmail.com>

paper-api/src/main/java/org/bukkit/entity/HumanEntity.java

@@ -367,7 +367,9 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * blocking).
      *
      * @return Whether their hand is raised
+     * @see LivingEntity#hasActiveItem()
      */
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.4") // Paper - active item API
     public boolean isHandRaised();
 
     /**

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -202,15 +202,19 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      *
      * @return the item being used by the player, or null if they are not using
      * an item
+     * @deprecated Use {@link #getActiveItem()}
      */
     @Nullable
+    @Deprecated(forRemoval = true, since = "1.20.4") // Paper
     public ItemStack getItemInUse();
 
     /**
      * Gets the number of ticks remaining for the current item's usage.
      *
      * @return The number of ticks remaining
+     * @deprecated use {@link #getActiveItemRemainingTime()}
      */
+    @Deprecated(forRemoval = true, since = "1.20.4") // Paper
     public int getItemInUseTicks();
 
     /**
@@ -219,7 +223,9 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * or throwing a trident.
      *
      * @param ticks The number of ticks remaining
+     * @deprecated use {@link #setActiveItemRemainingTime(int)}
      */
+    @Deprecated(forRemoval = true, since = "1.20.4") // Paper
     public void setItemInUseTicks(int ticks);
 
     /**
@@ -862,4 +868,130 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      */
     void setShieldBlockingDelay(int delay);
     // Paper end
+
+    // Paper start - active item API
+    /**
+     * Starts using the item in the specified hand, making it the
+     * currently active item. When, for example, called on a skeleton,
+     * this will cause it to start drawing its bow.
+     * <p>
+     * Only HAND or OFF_HAND may be used for the hand parameter.
+     * <p>
+     * When used on a player, the client will stop using the item
+     * if right click is held down.
+     * <p>
+     * This method does not make any guarantees about the effect of this method
+     * as such depends on the entity and its state.
+     *
+     * @param hand the hand that contains the item to be used
+     */
+    @org.jetbrains.annotations.ApiStatus.Experimental
+    void startUsingItem(@NotNull org.bukkit.inventory.EquipmentSlot hand);
+
+    /**
+     * Finishes using the currently active item. When, for example, a
+     * skeleton is drawing its bow, this will cause it to release and
+     * fire the arrow.
+     * <p>
+     * This method does not make any guarantees about the effect of this method
+     * as such depends on the entity and its state.
+     */
+    @org.jetbrains.annotations.ApiStatus.Experimental
+    void completeUsingActiveItem();
+
+    /**
+     * Gets the item being actively "used" or consumed.
+     *
+     * @return the item
+     */
+    org.bukkit.inventory.@NotNull ItemStack getActiveItem();
+
+    /**
+     * Gets the remaining number of ticks for {@link #getActiveItem()}'s usage.
+     *
+     * @return remaining ticks to use {@link #getActiveItem()}
+     */
+    int getActiveItemRemainingTime();
+
+    /**
+     * Sets the number of ticks that remain for {@link #getActiveItem()}'s
+     * usage.
+     * <p>
+     * Valid values are between 0 and the max item use duration for
+     * the specific item type.
+     *
+     * @param ticks time in ticks remaining
+     */
+    void setActiveItemRemainingTime(@org.jetbrains.annotations.Range(from = 0, to = Integer.MAX_VALUE) int ticks);
+
+    /**
+     * Gets if the entity is using an item (eating, drinking, etc).
+     *
+     * @return true if using an item
+     */
+    boolean hasActiveItem();
+
+    /**
+     * Get how long the {@link #getActiveItem()} has been in use for.
+     *
+     * @return time used in ticks
+     */
+    int getActiveItemUsedTime();
+
+    /**
+     * Get the hand using the active item. Will be either
+     * {@link org.bukkit.inventory.EquipmentSlot#HAND} or
+     * {@link org.bukkit.inventory.EquipmentSlot#OFF_HAND}.
+     *
+     * @return the hand being used
+     */
+    org.bukkit.inventory.@NotNull EquipmentSlot getActiveItemHand();
+
+    /**
+     * Gets remaining time a player needs to keep hands raised with an item to finish using it.
+     *
+     * @return remaining ticks to use the item
+     * @see #getActiveItemRemainingTime()
+     */
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.4")
+    default int getItemUseRemainingTime() {
+        return this.getActiveItemRemainingTime();
+    }
+
+    /**
+     * Get how long the entity's hands have been raised (Charging Bow attack, using a potion, etc)
+     *
+     * @return Get how long the players hands have been raised (Charging Bow attack, using a potion, etc)
+     * @see #getActiveItemUsedTime()
+     */
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.4")
+    default int getHandRaisedTime() {
+        return this.getActiveItemUsedTime();
+    }
+
+    /**
+     * Whether this entity is using or charging an attack (Bow pulled back, drinking potion, eating food)
+     *
+     * @return whether this entity is using or charging an attack (Bow pulled back, drinking potion, eating food)
+     * @see #hasActiveItem()
+     */
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.4")
+    default boolean isHandRaised() {
+        return this.hasActiveItem();
+    }
+
+    /**
+     * Gets the hand raised by this living entity. Will be either
+     * {@link org.bukkit.inventory.EquipmentSlot#HAND} or
+     * {@link org.bukkit.inventory.EquipmentSlot#OFF_HAND}.
+     *
+     * @return the hand raised
+     * @see #getActiveItemHand()
+     */
+    @NotNull
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.4")
+    default org.bukkit.inventory.EquipmentSlot getHandRaised() {
+        return this.getActiveItemHand();
+    }
+    // Paper end - active item API
 }