SPIGOT-3842: Add Player#fireworkBoost() and expand Firework API

By: Parker Hawke <hawkeboyz2@hotmail.com>

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

@@ -2,6 +2,7 @@ package org.bukkit.entity;
 
 import org.bukkit.inventory.meta.FireworkMeta;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public interface Firework extends Projectile {
 
@@ -20,12 +21,79 @@ public interface Firework extends Projectile {
      */
     void setFireworkMeta(@NotNull FireworkMeta meta);
 
+    /**
+     * Set the {@link LivingEntity} to which this firework is attached.
+     * <p>
+     * When attached to an entity, the firework effect will act as normal but
+     * remain positioned on the entity. If the entity {@code LivingEntity#isGliding()
+     * is gliding}, then the entity will receive a boost in the direction that
+     * they are looking.
+     *
+     * @param entity the entity to which the firework should be attached, or
+     * null to remove the attached entity
+     * @return true if the entity could be attached, false if the firework was
+     * already detonated
+     */
+    boolean setAttachedTo(@Nullable LivingEntity entity);
+
+    /**
+     * Get the {@link LivingEntity} to which this firework is attached.
+     * <p>
+     * When attached to an entity, the firework effect will act as normal but
+     * remain positioned on the entity. If the entity {@code LivingEntity#isGliding()
+     * is gliding}, then the entity will receive a boost in the direction that
+     * they are looking.
+     *
+     * @return the attached entity, or null if none
+     */
+    @Nullable
+    LivingEntity getAttachedTo();
+
+    /**
+     * Set the ticks that this firework has been alive. If this value exceeds
+     * {@link #getMaxLife()}, the firework will detonate.
+     *
+     * @param ticks the ticks to set. Must be greater than or equal to 0
+     * @return true if the life was set, false if this firework has already detonated
+     */
+    boolean setLife(int ticks);
+
+    /**
+     * Get the ticks that this firework has been alive. When this value reaches
+     * {@link #getMaxLife()}, the firework will detonate.
+     *
+     * @return the life ticks
+     */
+    int getLife();
+
+    /**
+     * Set the time in ticks this firework will exist until it is detonated.
+     *
+     * @param ticks the ticks to set. Must be greater than 0
+     * @return true if the time was set, false if this firework has already detonated
+     */
+    boolean setMaxLife(int ticks);
+
+    /**
+     * Get the time in ticks this firework will exist until it is detonated.
+     *
+     * @return the maximum life in ticks
+     */
+    int getMaxLife();
+
     /**
      * Cause this firework to explode at earliest opportunity, as if it has no
      * remaining fuse.
      */
     void detonate();
 
+    /**
+     * Check whether or not this firework has detonated.
+     *
+     * @return true if detonated, false if still in the world
+     */
+    boolean isDetonated();
+
     /**
      * Gets if the firework was shot at an angle (i.e. from a crossbow).
      *

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

@@ -13,6 +13,7 @@ import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.MainHand;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.PlayerInventory;
+import org.bukkit.inventory.meta.FireworkMeta;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -586,4 +587,20 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @param location where to set the last death player location
      */
     public void setLastDeathLocation(@Nullable Location location);
+
+    /**
+     * Perform a firework boost.
+     * <p>
+     * This method will only work such that {@link #isGliding()} is true and
+     * the entity is actively gliding with an elytra. Additionally, the supplied
+     * {@code fireworkItemStack} must be a firework rocket. The power of the boost
+     * will directly correlate to {@link FireworkMeta#getPower()}.
+     *
+     * @param fireworkItemStack the firework item stack to use to glide
+     * @return the attached {@link Firework}, or null if the entity could not
+     * be boosted
+     * @throws IllegalArgumentException if the fireworkItemStack is not a firework
+     */
+    @Nullable
+    public Firework fireworkBoost(@NotNull ItemStack fireworkItemStack);
 }