From 8891e2079c158bd20ab1025bfcd36ed4a99cbd09 Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Mon, 12 Sep 2022 19:04:19 +1000
Subject: [PATCH] SPIGOT-3842: Add Player#fireworkBoost() and expand Firework
 API

By: Parker Hawke <hawkeboyz2@hotmail.com>
---
 .../main/java/org/bukkit/entity/Firework.java | 68 +++++++++++++++++++
 .../java/org/bukkit/entity/HumanEntity.java   | 17 +++++
 2 files changed, 85 insertions(+)

diff --git a/paper-api/src/main/java/org/bukkit/entity/Firework.java b/paper-api/src/main/java/org/bukkit/entity/Firework.java
index 05e86cb9d8..e750b34d7d 100644
--- a/paper-api/src/main/java/org/bukkit/entity/Firework.java
+++ b/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).
      *
diff --git a/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java b/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java
index 2cf43eac30..652238659e 100644
--- a/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/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);
 }