SPIGOT-7942: Add Consumable Component

src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -23,6 +23,7 @@ import org.bukkit.inventory.meta.components.FoodComponent;
 import org.bukkit.inventory.meta.components.JukeboxPlayableComponent;
 import org.bukkit.inventory.meta.components.ToolComponent;
 import org.bukkit.inventory.meta.components.UseCooldownComponent;
+import org.bukkit.inventory.meta.components.consumable.ConsumableComponent;
 import org.bukkit.inventory.meta.tags.CustomItemTagContainer;
 import org.bukkit.persistence.PersistentDataHolder;
 import org.bukkit.tag.DamageTypeTags;
@@ -625,6 +626,33 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
      */
     void setFood(@Nullable FoodComponent food);
 
+    /**
+     * Checks if the consumable is set.
+     *
+     * @return if a consumable is set
+     */
+    boolean hasConsumable();
+
+    /**
+     * Gets the consumable set on this item, or creates an empty consumable instance.
+     * <p>
+     * The returned component is a snapshot of its current state and does not
+     * reflect a live view of what is on an item. After changing any value on
+     * this component, it must be set with {@link #setConsumable(ConsumableComponent)} to
+     * apply the changes.
+     *
+     * @return food
+     */
+    @NotNull
+    ConsumableComponent getConsumable();
+
+    /**
+     * Sets the item consumable.
+     *
+     * @param consumable new consumable
+     */
+    void setConsumable(@Nullable ConsumableComponent consumable);
+
     /**
      * Checks if the tool is set.
      *

src/main/java/org/bukkit/inventory/meta/components/FoodComponent.java

@@ -1,10 +1,14 @@
 package org.bukkit.inventory.meta.components;
 
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.bukkit.inventory.meta.components.consumable.ConsumableComponent;
 import org.jetbrains.annotations.ApiStatus;
 
 /**
- * Represents a component which can turn any item into food.
+ * Represents a component which can handle food stats in any item.
+ * <br>
+ * <b>Note:</b> Items with food stats has no effect unless the item can be
+ * consumed, see {@link ConsumableComponent}.
  */
 @ApiStatus.Experimental
 public interface FoodComponent extends ConfigurationSerializable {

src/main/java/org/bukkit/inventory/meta/components/consumable/ConsumableComponent.java

@@ -0,0 +1,118 @@
+package org.bukkit.inventory.meta.components.consumable;
+
+import java.util.List;
+import org.bukkit.Sound;
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+import org.bukkit.inventory.meta.components.consumable.effects.ConsumableEffect;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a component which item can be consumed on use.
+ */
+@ApiStatus.Experimental
+public interface ConsumableComponent extends ConfigurationSerializable {
+
+    /**
+     * Gets the time in seconds it will take for this item to be consumed.
+     *
+     * @return consume time
+     */
+    float getConsumeSeconds();
+
+    /**
+     * Sets the time in seconds it will take for this item to be consumed.
+     *
+     * @param consumeSeconds new consume time
+     */
+    void setConsumeSeconds(float consumeSeconds);
+
+    /**
+     * Gets the animation used during consumption of the item.
+     *
+     * @return animation
+     */
+    @NotNull
+    Animation getAnimation();
+
+    /**
+     * Sets the animation used during consumption of the item.
+     *
+     * @param animation the new animation
+     */
+    void setAnimation(@NotNull Animation animation);
+
+    /**
+     * Gets the sound to play during and on completion of the item's
+     * consumption.
+     *
+     * @return the sound
+     */
+    @Nullable
+    Sound getSound();
+
+    /**
+     * Sets the sound to play during and on completion of the item's
+     * consumption.
+     *
+     * @param sound sound or null for current default
+     */
+    void setSound(@Nullable Sound sound);
+
+    /**
+     * Gets whether consumption particles are emitted while consuming this item.
+     *
+     * @return true for particles emitted while consuming, false otherwise
+     */
+    boolean hasConsumeParticles();
+
+    /**
+     * Sets whether consumption particles are emitted while consuming this item.
+     *
+     * @param consumeParticles if particles need to be emitted while consuming
+     * the item
+     */
+    void setConsumeParticles(boolean consumeParticles);
+
+    /**
+     * Gets the effects which may be applied by this item when consumed.
+     *
+     * @return consumable effects
+     */
+    @NotNull
+    List<ConsumableEffect> getEffects();
+
+    /**
+     * Sets the effects which may be applied by this item when consumed.
+     *
+     * @param effects new effects
+     */
+    void setEffects(@NotNull List<ConsumableEffect> effects);
+
+    /**
+     * Adds an effect which may be applied by this item when consumed.
+     *
+     * @param effect the effect
+     * @return the added effect
+     */
+    @NotNull
+    ConsumableEffect addEffect(@NotNull ConsumableEffect effect);
+
+    /**
+     * Represents the animations for an item being consumed.
+     */
+    public enum Animation {
+
+        DRINK,
+        EAT,
+        NONE,
+        BLOCK,
+        BOW,
+        BRUSH,
+        CROSSBOW,
+        SPEAR,
+        SPYGLASS,
+        TOOT_HORN;
+    }
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumableApplyEffects.java

@@ -0,0 +1,49 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+import java.util.List;
+import org.bukkit.potion.PotionEffect;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represent the effects applied when an item is consumed.
+ */
+public interface ConsumableApplyEffects extends ConsumableEffect {
+
+    /**
+     * Gets the effects which may be applied by this item when consumed.
+     *
+     * @return consumable effects
+     */
+    @NotNull
+    List<PotionEffect> getEffects();
+
+    /**
+     * Sets the effects which may be applied by this item when consumed.
+     *
+     * @param effects new effects
+     */
+    void setEffects(@NotNull List<PotionEffect> effects);
+
+    /**
+     * Adds an effect which may be applied by this item when consumed.
+     *
+     * @param effect the effect
+     * @return the added effect
+     */
+    @NotNull
+    PotionEffect addEffect(@NotNull PotionEffect effect);
+
+    /**
+     * Gets the probability of this effect being applied.
+     *
+     * @return probability
+     */
+    float getProbability();
+
+    /**
+     * Sets the probability of this effect being applied.
+     *
+     * @param probability between 0 and 1 inclusive.
+     */
+    void setProbability(float probability);
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumableClearEffects.java

@@ -0,0 +1,7 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+/**
+ * Represent the removal/clearing of all effects when an item is consumed.
+ */
+public interface ConsumableClearEffects extends ConsumableEffect {
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumableEffect.java

@@ -0,0 +1,6 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+import org.bukkit.configuration.serialization.ConfigurationSerializable;
+
+public interface ConsumableEffect extends ConfigurationSerializable {
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumablePlaySound.java

@@ -0,0 +1,25 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+import org.bukkit.Sound;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represent a sound played when an item is consumed.
+ */
+public interface ConsumablePlaySound extends ConsumableEffect {
+
+    /**
+     * Gets the sound to play on completion of the item's consumption.
+     *
+     * @return the sound
+     */
+    @Nullable
+    Sound getSound();
+
+    /**
+     * Sets the sound to play on completion of the item's consumption.
+     *
+     * @param sound sound
+     */
+    void setSound(@Nullable Sound sound);
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumableRemoveEffect.java

@@ -0,0 +1,35 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+import java.util.List;
+import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represent the effects to be removed when an item is consumed.
+ */
+public interface ConsumableRemoveEffect extends ConsumableEffect {
+
+    /**
+     * Gets the effects which may be removed by this item when consumed.
+     *
+     * @return the effects
+     */
+    @NotNull
+    List<PotionEffectType> getEffectTypes();
+
+    /**
+     * Sets the effects which may be removed by this item when consumed.
+     *
+     * @param effects new effects
+     */
+    void setEffectTypes(@NotNull List<PotionEffectType> effects);
+
+    /**
+     * Adds an effect which may be applied by this item when consumed.
+     *
+     * @param effect the effect
+     * @return the added effect
+     */
+    @NotNull
+    PotionEffectType addEffectType(@NotNull PotionEffectType effect);
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/ConsumableTeleportRandomly.java

@@ -0,0 +1,21 @@
+package org.bukkit.inventory.meta.components.consumable.effects;
+
+/**
+ * Represent a random teleport when an item is consumed.
+ */
+public interface ConsumableTeleportRandomly extends ConsumableEffect {
+
+    /**
+     * Gets the diameter that the consumer is teleported within.
+     *
+     * @return the diameter
+     */
+    float getDiameter();
+
+    /**
+     * Sets the diameter that the consumer is teleported within.
+     *
+     * @param diameter new diameter
+     */
+    void setDiameter(float diameter);
+}

src/main/java/org/bukkit/inventory/meta/components/consumable/effects/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * All classes related to effects from the Consumable Component.
+ */
+@org.jetbrains.annotations.ApiStatus.Experimental
+package org.bukkit.inventory.meta.components.consumable.effects;

src/main/java/org/bukkit/inventory/meta/components/consumable/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * All classes related to the Consumable Component.
+ */
+@org.jetbrains.annotations.ApiStatus.Experimental
+package org.bukkit.inventory.meta.components.consumable;