- * All applicable data from the spawner will be copied, such as custom name,
- * health, and velocity.
- *
- * @return the entity snapshot or null if no entities have been assigned to this
- * spawner.
- */
- @Nullable
- public EntitySnapshot getSpawnedEntity();
-
- /**
- * Sets the entity that will be spawned by this spawner.
- * This will override any previous entries that have been added with
- * {@link #addPotentialSpawn}
- *
- * All applicable data from the snapshot will be copied, such as custom name,
- * health, and velocity.
- *
- * @param snapshot the entity snapshot
- */
- public void setSpawnedEntity(@NotNull EntitySnapshot snapshot);
-
- /**
- * Adds a new {@link EntitySnapshot} to the list of entities this spawner can
- * spawn.
- *
- * The weight will determine how often this entry is chosen to spawn, higher
- * weighted entries will spawn more often than lower weighted ones.
+ * Note: the returned collection is immutable, use
+ * {@link #startTrackingPlayer(Player)} or {@link #stopTrackingPlayer(Player)}
+ * instead.
+ *
+ * @return a collection of players this spawner is tracking or an empty
+ * collection if there aren't any
+ */
+ @NotNull
+ public Collection
+ * Note: the spawner may decide to stop tracking this player at any given
+ * time.
+ *
+ * @param player the player
+ */
+ public void startTrackingPlayer(@NotNull Player player);
+
+ /**
+ * Force this spawner to stop tracking the provided player.
+ *
+ * Note: the spawner may decide to start tracking this player again at
+ * any given time.
+ *
+ * @param player the player
+ */
+ public void stopTrackingPlayer(@NotNull Player player);
+
+ /**
+ * Gets a list of entities this spawner is currently tracking.
+ *
+ * Note: the returned collection is immutable, use
+ * {@link #startTrackingEntity(Entity)} or {@link #stopTrackingEntity(Entity)}
+ * instead.
+ *
+ * @return a collection of entities this spawner is tracking or an empty
+ * collection if there aren't any
+ */
+ @NotNull
+ public Collection
+ * Note: the spawner may decide to stop tracking this entity at any given
+ * time.
+ *
+ * @param entity the entity
+ */
+ public void startTrackingEntity(@NotNull Entity entity);
+
+ /**
+ * Force this spawner to stop tracking the provided entity.
+ *
+ * Note: the spawner may decide to start tracking this entity again at
+ * any given time.
+ *
+ * @param entity the entity
+ */
+ public void stopTrackingEntity(@NotNull Entity entity);
+
+ /**
+ * Checks if this spawner is using the ominous
+ * {@link TrialSpawnerConfiguration}.
+ *
+ * @return true is using the ominous configuration
+ */
+ public boolean isOminous();
+
+ /**
+ * Changes this spawner between the normal and ominous
+ * {@link TrialSpawnerConfiguration}.
+ *
+ * @param ominous true to use the ominous TrialSpawnerConfiguration, false to
+ * use the normal one.
+ */
+ public void setOminous(boolean ominous);
+
+ /**
+ * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
+ * false.
+ *
+ * @return the TrialSpawnerConfiguration
+ */
+ @NotNull
+ public TrialSpawnerConfiguration getNormalConfiguration();
+
+ /**
+ * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
+ * true.
+ *
+ * @return the TrialSpawnerConfiguration
+ */
+ @NotNull
+ public TrialSpawnerConfiguration getOminousConfiguration();
}
diff --git a/paper-api/src/main/java/org/bukkit/entity/minecart/SpawnerMinecart.java b/paper-api/src/main/java/org/bukkit/entity/minecart/SpawnerMinecart.java
index 0ce3592ec7..7338fe787d 100644
--- a/paper-api/src/main/java/org/bukkit/entity/minecart/SpawnerMinecart.java
+++ b/paper-api/src/main/java/org/bukkit/entity/minecart/SpawnerMinecart.java
@@ -1,10 +1,11 @@
package org.bukkit.entity.minecart;
import org.bukkit.entity.Minecart;
+import org.bukkit.spawner.Spawner;
/**
* Represents a Minecart with an {@link org.bukkit.block.CreatureSpawner
* entity spawner} inside it.
*/
-public interface SpawnerMinecart extends Minecart {
+public interface SpawnerMinecart extends Minecart, Spawner {
}
diff --git a/paper-api/src/main/java/org/bukkit/spawner/BaseSpawner.java b/paper-api/src/main/java/org/bukkit/spawner/BaseSpawner.java
new file mode 100644
index 0000000000..a083b9bf6a
--- /dev/null
+++ b/paper-api/src/main/java/org/bukkit/spawner/BaseSpawner.java
@@ -0,0 +1,186 @@
+package org.bukkit.spawner;
+
+import java.util.Collection;
+import java.util.List;
+import org.bukkit.block.CreatureSpawner;
+import org.bukkit.block.spawner.SpawnRule;
+import org.bukkit.block.spawner.SpawnerEntry;
+import org.bukkit.entity.EntitySnapshot;
+import org.bukkit.entity.EntityType;
+import org.bukkit.entity.minecart.SpawnerMinecart;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a basic entity spawner.
+ * All applicable data from the spawner will be copied, such as custom name,
+ * health, and velocity.
+ * All applicable data from the snapshot will be copied, such as custom name,
+ * health, and velocity.
+ * The weight will determine how often this entry is chosen to spawn, higher
+ * weighted entries will spawn more often than lower weighted ones.
- * The {@link SpawnRule} will determine under what conditions this entry can
- * spawn, passing null will use the default conditions for the given entity.
- *
- * @param snapshot the snapshot that will be spawned
- * @param weight the weight
- * @param spawnRule the spawn rule for this entity, or null
- */
- public void addPotentialSpawn(@NotNull EntitySnapshot snapshot, int weight, @Nullable SpawnRule spawnRule);
-
- /**
- * Adds a new {@link SpawnerEntry} to the list of entities this spawner can
- * spawn.
- *
- * @param spawnerEntry the spawner entry to use
- * @see #addPotentialSpawn(EntitySnapshot, int, SpawnRule)
- */
- public void addPotentialSpawn(@NotNull final SpawnerEntry spawnerEntry);
-
- /**
- * Sets the list of {@link SpawnerEntry} this spawner can spawn.
- * This will override any previous entries added with
- * {@link #addPotentialSpawn}
- *
- * @param entries the list of entries
- */
- public void setPotentialSpawns(@NotNull final Collection
- * Changes made to the returned list will not be reflected in the spawner unless
- * applied with {@link #setPotentialSpawns}
- *
- * @return a list of potential spawns from this spawner, or an empty list if no
- * entities have been assigned to this spawner
- * @see #getSpawnedType()
- */
- @NotNull
- public List
+ * If this value is less than or equal to 0, this spawner is always active
+ * (given that there are players online).
+ *
+ * Default value is 16.
+ *
+ * @return the maximum distance(squared) a player can be in order for this
+ * spawner to be active.
+ */
+ public int getRequiredPlayerRange();
+
+ /**
+ * Set the maximum distance (squared) a player can be in order for this
+ * spawner to be active.
+ *
+ * Setting this value to less than or equal to 0 will make this spawner
+ * always active (given that there are players online).
+ *
+ * @param requiredPlayerRange the maximum distance (squared) a player can be
+ * in order for this spawner to be active.
+ */
+ public void setRequiredPlayerRange(int requiredPlayerRange);
+
+ /**
+ * Gets the players this spawner is currently tracking.
+ *
+ * May be a {@link SpawnerMinecart}, {@link CreatureSpawner} or {@link TrialSpawnerConfiguration}.
+ */
+public interface BaseSpawner {
+
+ /**
+ * Get the spawner's creature type.
+ *
+ * @return The creature type or null if it not set.
+ */
+ @Nullable
+ public EntityType getSpawnedType();
+
+ /**
+ * Set the spawner's creature type.
+ * This will override any entities that have been added with {@link #addPotentialSpawn}
+ *
+ * @param creatureType The creature type or null to clear.
+ */
+ public void setSpawnedType(@Nullable EntityType creatureType);
+
+ /**
+ * Get the spawner's delay.
+ *
+ * This is the delay, in ticks, until the spawner will spawn its next mob.
+ *
+ * @return The delay.
+ */
+ public int getDelay();
+
+ /**
+ * Set the spawner's delay.
+ *
+ * If set to -1, the spawn delay will be reset to a random value between
+ * {@link #getMinSpawnDelay} and {@link #getMaxSpawnDelay()}.
+ *
+ * @param delay The delay.
+ */
+ public void setDelay(int delay);
+
+ /**
+ * Get the maximum distance(squared) a player can be in order for this
+ * spawner to be active.
+ *
+ * If this value is less than or equal to 0, this spawner is always active
+ * (given that there are players online).
+ *
+ * Default value is 16.
+ *
+ * @return the maximum distance(squared) a player can be in order for this
+ * spawner to be active.
+ */
+ public int getRequiredPlayerRange();
+
+ /**
+ * Set the maximum distance (squared) a player can be in order for this
+ * spawner to be active.
+ *
+ * Setting this value to less than or equal to 0 will make this spawner
+ * always active (given that there are players online).
+ *
+ * @param requiredPlayerRange the maximum distance (squared) a player can be
+ * in order for this spawner to be active.
+ */
+ public void setRequiredPlayerRange(int requiredPlayerRange);
+
+ /**
+ * Get the radius around which the spawner will attempt to spawn mobs in.
+ *
+ * This area is square, includes the block the spawner is in, and is
+ * centered on the spawner's x,z coordinates - not the spawner itself.
+ *
+ * It is 2 blocks high, centered on the spawner's y-coordinate (its bottom);
+ * thus allowing mobs to spawn as high as its top surface and as low
+ * as 1 block below its bottom surface.
+ *
+ * Default value is 4.
+ *
+ * @return the spawn range
+ */
+ public int getSpawnRange();
+
+ /**
+ * Set the new spawn range.
+ *
+ *
+ * @param spawnRange the new spawn range
+ * @see #getSpawnRange()
+ */
+ public void setSpawnRange(int spawnRange);
+
+ /**
+ * Gets the {@link EntitySnapshot} that will be spawned by this spawner or null
+ * if no entities have been assigned to this spawner.
+ *
+ *
+ * @return the entity snapshot or null if no entities have been assigned to this
+ * spawner.
+ */
+ @Nullable
+ public EntitySnapshot getSpawnedEntity();
+
+ /**
+ * Sets the entity that will be spawned by this spawner.
+ * This will override any previous entries that have been added with
+ * {@link #addPotentialSpawn}
+ *
+ *
+ * @param snapshot the entity snapshot or null to clear
+ */
+ public void setSpawnedEntity(@Nullable EntitySnapshot snapshot);
+
+ /**
+ * Sets the {@link SpawnerEntry} that will be spawned by this spawner.
+ * This will override any previous entries that have been added with
+ * {@link #addPotentialSpawn}
+ *
+ * @param spawnerEntry the spawner entry to use
+ * @see #setSpawnedEntity(EntitySnapshot, SpawnRule)
+ */
+ public void setSpawnedEntity(@NotNull SpawnerEntry spawnerEntry);
+
+ /**
+ * Adds a new {@link EntitySnapshot} to the list of entities this spawner can
+ * spawn.
+ *
+ * The {@link SpawnRule} will determine under what conditions this entry can
+ * spawn, passing null will use the default conditions for the given entity.
+ *
+ * @param snapshot the snapshot that will be spawned
+ * @param weight the weight
+ * @param spawnRule the spawn rule for this entity, or null
+ */
+ public void addPotentialSpawn(@NotNull EntitySnapshot snapshot, int weight, @Nullable SpawnRule spawnRule);
+
+ /**
+ * Adds a new {@link SpawnerEntry} to the list of entities this spawner can
+ * spawn.
+ *
+ * @param spawnerEntry the spawner entry to use
+ * @see #addPotentialSpawn(EntitySnapshot, int, SpawnRule)
+ */
+ public void addPotentialSpawn(@NotNull final SpawnerEntry spawnerEntry);
+
+ /**
+ * Sets the list of {@link SpawnerEntry} this spawner can spawn.
+ * This will override any previous entries added with
+ * {@link #addPotentialSpawn}
+ *
+ * @param entries the list of entries
+ */
+ public void setPotentialSpawns(@NotNull final Collection
+ * Changes made to the returned list will not be reflected in the spawner unless
+ * applied with {@link #setPotentialSpawns}
+ *
+ * @return a list of potential spawns from this spawner, or an empty list if no
+ * entities have been assigned to this spawner
+ * @see #getSpawnedType()
+ */
+ @NotNull
+ public List
+ * May be a {@link SpawnerMinecart} or a {@link CreatureSpawner}.
+ */
+public interface Spawner extends BaseSpawner {
+
+ /**
+ * The minimum spawn delay amount (in ticks).
+ *
+ * This value is used when the spawner resets its delay (for any reason).
+ * It will choose a random number between {@link #getMinSpawnDelay()}
+ * and {@link #getMaxSpawnDelay()} for its next {@link #getDelay()}.
+ *
+ * Default value is 200 ticks.
+ *
+ * @return the minimum spawn delay amount
+ */
+ public int getMinSpawnDelay();
+
+ /**
+ * Set the minimum spawn delay amount (in ticks).
+ *
+ * @param delay the minimum spawn delay amount
+ * @see #getMinSpawnDelay()
+ */
+ public void setMinSpawnDelay(int delay);
+
+ /**
+ * The maximum spawn delay amount (in ticks).
+ *
+ * This value is used when the spawner resets its delay (for any reason).
+ * It will choose a random number between {@link #getMinSpawnDelay()}
+ * and {@link #getMaxSpawnDelay()} for its next {@link #getDelay()}.
+ *
+ * This value must be greater than 0 and less than or equal to
+ * {@link #getMaxSpawnDelay()}.
+ *
+ * Default value is 800 ticks.
+ *
+ * @return the maximum spawn delay amount
+ */
+ public int getMaxSpawnDelay();
+
+ /**
+ * Set the maximum spawn delay amount (in ticks).
+ *
+ * This value must be greater than 0, as well as greater than or
+ * equal to {@link #getMinSpawnDelay()}
+ *
+ * @param delay the new maximum spawn delay amount
+ * @see #getMaxSpawnDelay()
+ */
+ public void setMaxSpawnDelay(int delay);
+
+ /**
+ * Get how many mobs attempt to spawn.
+ *
+ * Default value is 4.
+ *
+ * @return the current spawn count
+ */
+ public int getSpawnCount();
+
+ /**
+ * Set how many mobs attempt to spawn.
+ *
+ * @param spawnCount the new spawn count
+ */
+ public void setSpawnCount(int spawnCount);
+
+ /**
+ * Set the new maximum amount of similar entities that are allowed to be
+ * within spawning range of this spawner.
+ *
+ * If more than the maximum number of entities are within range, the spawner
+ * will not spawn and try again with a new {@link #getDelay()}.
+ *
+ * Default value is 16.
+ *
+ * @return the maximum number of nearby, similar, entities
+ */
+ public int getMaxNearbyEntities();
+
+ /**
+ * Set the maximum number of similar entities that are allowed to be within
+ * spawning range of this spawner.
+ *
+ * Similar entities are entities that are of the same {@link EntityType}
+ *
+ * @param maxNearbyEntities the maximum number of nearby, similar, entities
+ */
+ public void setMaxNearbyEntities(int maxNearbyEntities);
+}
diff --git a/paper-api/src/main/java/org/bukkit/spawner/TrialSpawnerConfiguration.java b/paper-api/src/main/java/org/bukkit/spawner/TrialSpawnerConfiguration.java
new file mode 100644
index 0000000000..e5c2a1eb7e
--- /dev/null
+++ b/paper-api/src/main/java/org/bukkit/spawner/TrialSpawnerConfiguration.java
@@ -0,0 +1,121 @@
+package org.bukkit.spawner;
+
+import java.util.Map;
+import org.bukkit.loot.LootTable;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represents one of the configurations of a trial spawner.
+ */
+@ApiStatus.Experimental
+public interface TrialSpawnerConfiguration extends BaseSpawner {
+
+ /**
+ * Gets the base number of entities the spawner will spawn before going into
+ * cooldown.
+ *
+ * @return the number of entities
+ */
+ public float getBaseSpawnsBeforeCooldown();
+
+ /**
+ * Sets the base number of entities the spawner will spawn before going into
+ * cooldown.
+ *
+ * @param amount the number of entities
+ */
+ public void setBaseSpawnsBeforeCooldown(float amount);
+
+ /**
+ * Gets the base number of entities this spawner can track at once.
+ * If the limit is reached the spawner will not be able to spawn any more
+ * entities until the existing entities are killed or move too far away.
+ *
+ * @return the number of entities
+ */
+ public float getBaseSimultaneousEntities();
+
+ /**
+ * Sets the base number of entities this spawner can track at once.
+ * If the limit is reached the spawner will not be able to spawn any more
+ * entities until the existing entities are killed or move too far away.
+ *
+ * @param amount the number of entities
+ */
+ public void setBaseSimultaneousEntities(float amount);
+
+ /**
+ * Gets the additional number of entities the spawner will spawn per tracked player
+ * before going into cooldown.
+ *
+ * @return the number of entities
+ */
+ public float getAdditionalSpawnsBeforeCooldown();
+
+ /**
+ * Sets the additional number of entities the spawner will spawn per tracked player
+ * before going into cooldown.
+ *
+ * @param amount the number of entities
+ */
+ public void setAdditionalSpawnsBeforeCooldown(float amount);
+
+ /**
+ * Gets the additional number of entities this spawner can track at once per
+ * tracked player.
+ * If the limit is reached the spawner will not be able to spawn any more
+ * entities until the existing entities are killed or move too far away.
+ *
+ * @return the number of entities
+ */
+ public float getAdditionalSimultaneousEntities();
+
+ /**
+ * Sets the additional number of entities this spawner can track at once per
+ * tracked player.
+ * If the limit is reached the spawner will not be able to spawn any more
+ * entities until the existing entities are killed or move too far away.
+ *
+ * @param amount the number of entities
+ */
+ public void setAdditionalSimultaneousEntities(float amount);
+
+ /**
+ * Gets a list of {@link LootTable}s this spawner can pick a reward from as
+ * well as their associated weight to be chosen.
+ *
+ * @return a map of loot tables and their associated weight, or an empty
+ * map if there are none
+ */
+ @NotNull
+ public Map
+ * All loot tables in the map must be non-null and all weights must be at least
+ * 1.
+ *
+ * @param rewards a map of loot tables and their weights, or null to clear all
+ * possible tables
+ */
+ public void setPossibleRewards(@NotNull Map