#482: Add a DragonBattle API to manipulate respawn phases etc

By: Parker Hawke <hawkeboyz2@hotmail.com>

paper-api/src/main/java/org/bukkit/World.java

@@ -10,6 +10,7 @@ import java.util.function.Predicate;
 import org.bukkit.block.Biome;
 import org.bukkit.block.Block;
 import org.bukkit.block.data.BlockData;
+import org.bukkit.boss.DragonBattle;
 import org.bukkit.entity.AbstractArrow;
 import org.bukkit.entity.Arrow;
 import org.bukkit.entity.Entity;
@@ -2241,6 +2242,21 @@ public interface World extends PluginMessageRecipient, Metadatable {
     @NotNull
     public List<Raid> getRaids();
 
+    /**
+     * Get the {@link DragonBattle} associated with this world.
+     *
+     * If this world's environment is not {@link Environment#THE_END}, null will
+     * be returned.
+     * <p>
+     * If an end world, a dragon battle instance will be returned regardless of
+     * whether or not a dragon is present in the world or a fight sequence has
+     * been activated. The dragon battle instance acts as a state holder.
+     *
+     * @return the dragon battle instance
+     */
+    @Nullable
+    public DragonBattle getEnderDragonBattle();
+
     /**
      * Represents various map environment types that a world may be
      */

paper-api/src/main/java/org/bukkit/boss/DragonBattle.java

@@ -0,0 +1,114 @@
+package org.bukkit.boss;
+
+import org.bukkit.Location;
+import org.bukkit.entity.EnderDragon;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a dragon battle state for a world with an end environment.
+ */
+public interface DragonBattle {
+
+    /**
+     * Get the {@link EnderDragon} active in this battle.
+     *
+     * Will return null if the dragon has been slain.
+     *
+     * @return the ender dragon. null if dead
+     */
+    @Nullable
+    public EnderDragon getEnderDragon();
+
+    /**
+     * Get the boss bar to be displayed for this dragon battle.
+     *
+     * @return the boss bar
+     */
+    @NotNull
+    public BossBar getBossBar();
+
+    /**
+     * Get the location of the end portal.
+     *
+     * This location will be at the center of the base (bottom) of the portal.
+     *
+     * @return the end portal location
+     */
+    @NotNull
+    public Location getEndPortalLocation();
+
+    /**
+     * Check whether or not the first dragon has been killed already.
+     *
+     * @return true if killed before, false otherwise
+     */
+    public boolean hasBeenPreviouslyKilled();
+
+    /**
+     * Initiate a respawn sequence to summon the dragon as though a player has
+     * placed 4 end crystals on the portal.
+     */
+    public void initiateRespawn();
+
+    /**
+     * Get this battle's current respawn phase.
+     *
+     * @return the current respawn phase.
+     */
+    @NotNull
+    public RespawnPhase getRespawnPhase();
+
+    /**
+     * Set the dragon's respawn phase.
+     *
+     * This method will is unsuccessful if a dragon respawn is not in progress.
+     *
+     * @param phase the phase to set
+     *
+     * @return true if successful, false otherwise
+     *
+     * @see #initiateRespawn()
+     */
+    public boolean setRespawnPhase(@NotNull RespawnPhase phase);
+
+    /**
+     * Reset the crystals located on the obsidian pillars (remove their beam
+     * targets and invulnerability).
+     */
+    public void resetCrystals();
+
+    /**
+     * Represents a phase in the dragon respawn process.
+     */
+    public enum RespawnPhase {
+
+        /**
+         * The crystal beams are directed upwards into the sky.
+         */
+        START,
+        /**
+         * The crystal beams remain directed upwards.
+         */
+        PREPARING_TO_SUMMON_PILLARS,
+        /**
+         * The crystal beams are directed from pillar to pillar, regenerating
+         * their crystals if necessary.
+         */
+        SUMMONING_PILLARS,
+        /**
+         * All crystals (including those from the pillars) are aimed towards the
+         * sky. Shortly thereafter summoning the dragon and destroying the
+         * crystals used to initiate the dragon's respawn.
+         */
+        SUMMONING_DRAGON,
+        /**
+         * The end of the respawn sequence. The dragon is actually summoned.
+         */
+        END,
+        /**
+         * No respawn is in progress.
+         */
+        NONE;
+    }
+}

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

@@ -1,6 +1,9 @@
 package org.bukkit.entity;
 
+import org.bukkit.World;
+import org.bukkit.boss.DragonBattle;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents an Ender Dragon
@@ -78,4 +81,27 @@ public interface EnderDragon extends ComplexLivingEntity, Boss {
      * @param phase the next phase
      */
     void setPhase(@NotNull Phase phase);
+
+    /**
+     * Get the {@link DragonBattle} associated with this EnderDragon.
+     *
+     * This will return null if the EnderDragon is not in the End dimension.
+     *
+     * @return the dragon battle
+     *
+     * @see World#getEnderDragonBattle()
+     */
+    @Nullable
+    DragonBattle getDragonBattle();
+
+    /**
+     * Get the current time in ticks relative to the start of this dragon's
+     * death animation.
+     *
+     * If this dragon is alive, 0 will be returned. This value will never exceed
+     * 200 (the length of the animation).
+     *
+     * @return this dragon's death animation ticks
+     */
+    int getDeathAnimationTicks();
 }