Expand TrialSpawner API (#12025)

paper-api/src/main/java/org/bukkit/block/TrialSpawner.java

@@ -4,26 +4,57 @@ import java.util.Collection;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.spawner.TrialSpawnerConfiguration;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Represents a captured state of a trial spawner.
  */
+@NullMarked
 public interface TrialSpawner extends TileState {
 
+    /**
+     * Gets the game time in ticks when the cooldown ends. 0 if not currently in cooldown.
+     *
+     * @return the game time in ticks
+     * @see org.bukkit.World#getGameTime()
+     */
+    long getCooldownEnd();
+
+    /**
+     * Sets the game time in ticks when the cooldown ends.
+     *
+     * @param ticks the game time in ticks for the new cooldown
+     */
+    void setCooldownEnd(long ticks);
+
+    /**
+     * Gets the game time in ticks when the next spawn attempt happens. 0 if not currently active.
+     *
+     * @return the game time in ticks
+     * @see org.bukkit.World#getGameTime()
+     */
+    long getNextSpawnAttempt();
+
+    /**
+     * Sets the game time in ticks when the next spawn attempt happens.
+     *
+     * @param ticks the game time in ticks for the next mob spawn
+     */
+    void setNextSpawnAttempt(long ticks);
+
     /**
      * Gets the length in ticks the spawner will stay in cooldown for.
      *
      * @return the number of ticks
      */
-    public int getCooldownLength();
+    int getCooldownLength();
 
     /**
      * Sets the length in ticks the spawner will stay in cooldown for.
      *
      * @param ticks the number of ticks
      */
-    public void setCooldownLength(int ticks);
+    void setCooldownLength(int ticks);
 
     /**
      * Get the maximum distance(squared) a player can be in order for this
@@ -37,7 +68,7 @@ public interface TrialSpawner extends TileState {
      * @return the maximum distance(squared) a player can be in order for this
      * spawner to be active.
      */
-    public int getRequiredPlayerRange();
+    int getRequiredPlayerRange();
 
     /**
      * Set the maximum distance (squared) a player can be in order for this
@@ -49,7 +80,7 @@ public interface TrialSpawner extends TileState {
      * @param requiredPlayerRange the maximum distance (squared) a player can be
      * in order for this spawner to be active.
      */
-    public void setRequiredPlayerRange(int requiredPlayerRange);
+    void setRequiredPlayerRange(int requiredPlayerRange);
 
     /**
      * Gets the players this spawner is currently tracking.
@@ -61,8 +92,7 @@ public interface TrialSpawner extends TileState {
      * @return a collection of players this spawner is tracking or an empty
      *         collection if there aren't any
      */
-    @NotNull
-    public Collection<Player> getTrackedPlayers();
+    Collection<Player> getTrackedPlayers();
 
     /**
      * Checks if this spawner is currently tracking the provided player.
@@ -70,7 +100,7 @@ public interface TrialSpawner extends TileState {
      * @param player the player
      * @return true if this spawner is tracking the provided player
      */
-    public boolean isTrackingPlayer(@NotNull Player player);
+    boolean isTrackingPlayer(final Player player);
 
     /**
      * Force this spawner to start tracking the provided player.
@@ -80,7 +110,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param player the player
      */
-    public void startTrackingPlayer(@NotNull Player player);
+    void startTrackingPlayer(final Player player);
 
     /**
      * Force this spawner to stop tracking the provided player.
@@ -90,7 +120,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param player the player
      */
-    public void stopTrackingPlayer(@NotNull Player player);
+    void stopTrackingPlayer(final Player player);
 
     /**
      * Gets a list of entities this spawner is currently tracking.
@@ -102,8 +132,7 @@ public interface TrialSpawner extends TileState {
      * @return a collection of entities this spawner is tracking or an empty
      *         collection if there aren't any
      */
-    @NotNull
-    public Collection<Entity> getTrackedEntities();
+    Collection<Entity> getTrackedEntities();
 
     /**
      * Checks if this spawner is currently tracking the provided entity.
@@ -111,7 +140,7 @@ public interface TrialSpawner extends TileState {
      * @param entity the entity
      * @return true if this spawner is tracking the provided entity
      */
-    public boolean isTrackingEntity(@NotNull Entity entity);
+    boolean isTrackingEntity(final Entity entity);
 
     /**
      * Force this spawner to start tracking the provided entity.
@@ -121,7 +150,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param entity the entity
      */
-    public void startTrackingEntity(@NotNull Entity entity);
+    void startTrackingEntity(final Entity entity);
 
     /**
      * Force this spawner to stop tracking the provided entity.
@@ -131,7 +160,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param entity the entity
      */
-    public void stopTrackingEntity(@NotNull Entity entity);
+    void stopTrackingEntity(final Entity entity);
 
     /**
      * Checks if this spawner is using the ominous
@@ -139,7 +168,7 @@ public interface TrialSpawner extends TileState {
      *
      * @return true is using the ominous configuration
      */
-    public boolean isOminous();
+    boolean isOminous();
 
     /**
      * Changes this spawner between the normal and ominous
@@ -148,7 +177,7 @@ public interface TrialSpawner extends TileState {
      * @param ominous true to use the ominous TrialSpawnerConfiguration, false to
      *                use the normal one.
      */
-    public void setOminous(boolean ominous);
+    void setOminous(boolean ominous);
 
     /**
      * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
@@ -156,8 +185,7 @@ public interface TrialSpawner extends TileState {
      *
      * @return the TrialSpawnerConfiguration
      */
-    @NotNull
-    public TrialSpawnerConfiguration getNormalConfiguration();
+    TrialSpawnerConfiguration getNormalConfiguration();
 
     /**
      * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
@@ -165,6 +193,5 @@ public interface TrialSpawner extends TileState {
      *
      * @return the TrialSpawnerConfiguration
      */
-    @NotNull
-    public TrialSpawnerConfiguration getOminousConfiguration();
+    TrialSpawnerConfiguration getOminousConfiguration();
 }