SPIGOT-1638 / SPIGOT-1673: Rework Potions API

By: t00thpick1 <t00thpick1dirko@gmail.com>

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

@@ -2,9 +2,10 @@ package org.bukkit.entity;
 
 import java.util.List;
 import org.bukkit.Color;
-import org.bukkit.Effect;
 import org.bukkit.Particle;
+import org.bukkit.potion.PotionData;
 import org.bukkit.potion.PotionEffect;
+import org.bukkit.potion.PotionEffectType;
 
 /**
  * Represents an area effect cloud which will imbue a potion effect onto
@@ -71,6 +72,7 @@ public interface AreaEffectCloud extends Entity {
      * @param duration duration on use delta
      */
     void setDurationOnUse(int duration);
+
     /**
      * Gets the initial radius of the cloud.
      *
@@ -130,33 +132,67 @@ public interface AreaEffectCloud extends Entity {
     void setParticle(Particle particle);
 
     /**
-     * Get a copy of all effects which can be applied by this cloud. No
-     * guarantees are made about the nature of the returned list.
+     * Sets the underlying potion data
      *
-     * @return the list of all effects
+     * @param data PotionData to set the base potion state to
      */
-    List<PotionEffect> getEffects();
+    void setBasePotionData(PotionData data);
 
     /**
-     * Add an effect which can be applied by this cloud.
+     * Returns the potion data about the base potion
      *
-     * @param effect the effect to add
+     * @return a PotionData object
      */
-    void addEffect(PotionEffect effect);
+    PotionData getBasePotionData();
 
     /**
-     * Remove an effect from this cloud.
+     * Checks for the presence of custom potion effects.
      *
-     * @param effect the effect to remove
+     * @return true if custom potion effects are applied
      */
-    void removeEffect(PotionEffect effect);
+    boolean hasCustomEffects();
 
     /**
-     * Set the effects of this cloud. Will remove all existing effects.
+     * Gets an immutable list containing all custom potion effects applied to
+     * this cloud.
+     * <p>
+     * Plugins should check that hasCustomEffects() returns true before calling
+     * this method.
      *
-     * @param effects the new effects to set
+     * @return the immutable list of custom potion effects
      */
-    void setEffects(List<PotionEffect> effects);
+    List<PotionEffect> getCustomEffects();
+
+    /**
+     * Adds a custom potion effect to this cloud.
+     *
+     * @param effect the potion effect to add
+     * @param overwrite true if any existing effect of the same type should be
+     * overwritten
+     * @return true if the effect was added as a result of this call
+     */
+    boolean addCustomEffect(PotionEffect effect, boolean overwrite);
+
+    /**
+     * Removes a custom potion effect from this cloud.
+     *
+     * @param type the potion effect type to remove
+     * @return true if the an effect was removed as a result of this call
+     */
+    boolean removeCustomEffect(PotionEffectType type);
+
+    /**
+     * Checks for a specific custom potion effect type on this cloud.
+     *
+     * @param type the potion effect type to check for
+     * @return true if the potion has this effect
+     */
+    boolean hasCustomEffect(PotionEffectType type);
+
+    /**
+     * Removes all custom potion effects from this cloud.
+     */
+    void clearCustomEffects();
 
     /**
      * Gets the color of this cloud. Will be applied as a tint to its particles.

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

@@ -173,9 +173,13 @@ public enum EntityType {
     ENDER_CRYSTAL("EnderCrystal", EnderCrystal.class, 200),
     // These don't have an entity ID in nms.EntityTypes.
     /**
-     * A flying splash potion.
+     * A flying splash potion
      */
-    SPLASH_POTION(null, ThrownPotion.class, -1, false),
+    SPLASH_POTION(null, SplashPotion.class, -1, false),
+    /**
+     * A flying lingering potion
+     */
+    LINGERING_POTION(null, LingeringPotion.class, -1, false),
     AREA_EFFECT_CLOUD(null, AreaEffectCloud.class, -1),
     /**
      * A flying chicken egg.

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

@@ -0,0 +1,6 @@
+package org.bukkit.entity;
+
+/**
+ * Represents a thrown lingering potion bottle
+ */
+public interface LingeringPotion extends ThrownPotion { }

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

@@ -0,0 +1,6 @@
+package org.bukkit.entity;
+
+/**
+ * Represents a thrown splash potion bottle
+ */
+public interface SplashPotion extends ThrownPotion { }

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

@@ -20,8 +20,8 @@ public interface ThrownPotion extends Projectile {
     /**
      * Returns a copy of the ItemStack for this thrown potion.
      * <p>
-     * Altering this copy will not alter the thrown potion directly. If you
-     * want to alter the thrown potion, you must use the {@link
+     * Altering this copy will not alter the thrown potion directly. If you want
+     * to alter the thrown potion, you must use the {@link
      * #setItem(ItemStack) setItemStack} method.
      *
      * @return A copy of the ItemStack for this thrown potion.
@@ -31,7 +31,9 @@ public interface ThrownPotion extends Projectile {
     /**
      * Set the ItemStack for this thrown potion.
      * <p>
-     * The ItemStack must be a potion, otherwise an exception is thrown.
+     * The ItemStack must be of type {@link org.bukkit.Material#SPLASH_POTION}
+     * or {@link org.bukkit.Material#LINGERING_POTION}, otherwise an exception
+     * is thrown.
      *
      * @param item New ItemStack
      */

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

@@ -1,3 +1,78 @@
 package org.bukkit.entity;
 
-public interface TippedArrow extends Arrow {}
+import java.util.List;
+
+import org.bukkit.potion.PotionData;
+import org.bukkit.potion.PotionEffect;
+import org.bukkit.potion.PotionEffectType;
+
+public interface TippedArrow extends Arrow {
+
+    /**
+     * Sets the underlying potion data
+     *
+     * @param data PotionData to set the base potion state to
+     */
+    void setBasePotionData(PotionData data);
+
+    /**
+     * Returns the potion data about the base potion
+     *
+     * @return a PotionData object
+     */
+    PotionData getBasePotionData();
+
+    /**
+     * Checks for the presence of custom potion effects.
+     *
+     * @return true if custom potion effects are applied
+     */
+    boolean hasCustomEffects();
+
+    /**
+     * Gets an immutable list containing all custom potion effects applied to
+     * this arrow.
+     * <p>
+     * Plugins should check that hasCustomEffects() returns true before calling
+     * this method.
+     *
+     * @return the immutable list of custom potion effects
+     */
+    List<PotionEffect> getCustomEffects();
+
+    /**
+     * Adds a custom potion effect to this arrow.
+     *
+     * @param effect the potion effect to add
+     * @param overwrite true if any existing effect of the same type should be
+     * overwritten
+     * @return true if the effect was added as a result of this call
+     */
+    boolean addCustomEffect(PotionEffect effect, boolean overwrite);
+
+    /**
+     * Removes a custom potion effect from this arrow.
+     *
+     * @param type the potion effect type to remove
+     * @return true if the an effect was removed as a result of this call
+     * @throws IllegalArgumentException if this operation would leave the Arrow
+     * in a state with no Custom Effects and PotionType.UNCRAFTABLE
+     */
+    boolean removeCustomEffect(PotionEffectType type);
+
+    /**
+     * Checks for a specific custom potion effect type on this arrow.
+     *
+     * @param type the potion effect type to check for
+     * @return true if the potion has this effect
+     */
+    boolean hasCustomEffect(PotionEffectType type);
+
+    /**
+     * Removes all custom potion effects from this arrow.
+     *
+     * @throws IllegalArgumentException if this operation would leave the Arrow
+     * in a state with no Custom Effects and PotionType.UNCRAFTABLE
+     */
+    void clearCustomEffects();
+}