Spigot / Bukkit / 23cffd9cff6

Commits

coll1234567 authored and md_5 committed 23cffd9cff6 27 Jun 2024

#973: Improve spawner API and add API for Trial Spawners

src/main/java/org/bukkit/block/CreatureSpawner.java

Modified

-1
+package org.bukkit.block;
-2
--
+import java.util.Collection;
--
+import java.util.List;
--
+import org.bukkit.block.spawner.SpawnRule;
--
+import org.bukkit.block.spawner.SpawnerEntry;
--
+import org.bukkit.entity.EntitySnapshot;
--
+import org.bukkit.entity.EntityType;
--
+import org.jetbrains.annotations.NotNull;
-+
+import org.bukkit.spawner.Spawner;
-4
+import org.jetbrains.annotations.Nullable;
-5
-6
+/**
-7
+ * Represents a captured state of a creature spawner.
-8
+ */
--
+public interface CreatureSpawner extends TileState {
--
--
+    /**
--
+     * 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. <br>
--
+     * 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);
-+
+public interface CreatureSpawner extends TileState, Spawner {
-10
-11
+    /**
-12
+     * Set the spawner mob type.
-13
+     *
-14
+     * @param creatureType The creature type's name or null to clear.
-15
+     * @deprecated magic value, use
-16
+     * {@link #setSpawnedType(org.bukkit.entity.EntityType)}.
-17
+     */
-18
+    @Deprecated
-19
+    public void setCreatureTypeByName(@Nullable String creatureType);
-20
-21
+    /**
-22
+     * Get the spawner's creature type.
-23
+     *
-24
+     * @return The creature type's name if is set.
-25
+     * @deprecated magic value, use {@link #getSpawnedType()}.
-26
+     */
-27
+    @Deprecated
-28
+    @Nullable
-29
+    public String getCreatureTypeName();
--
--
+    /**
--
+     * Get the spawner's delay.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * 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);
--
--
+    /**
--
+     * The minimum spawn delay amount (in ticks).
--
+     * <br>
--
+     * 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()}.
--
+     * <br>
--
+     * 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).
--
+     * <br>
--
+     * 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()}.
--
+     * <br>
--
+     * This value <b>must</b> be greater than 0 and less than or equal to
--
+     * {@link #getMaxSpawnDelay()}.
--
+     * <br>
--
+     * Default value is 800 ticks.
--
+     *
--
+     * @return the maximum spawn delay amount
--
+     */
--
+    public int getMaxSpawnDelay();
--
--
+    /**
--
+     * Set the maximum spawn delay amount (in ticks).
--
+     * <br>
--
+     * This value <b>must</b> 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.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * If more than the maximum number of entities are within range, the spawner
--
+     * will not spawn and try again with a new {@link #getDelay()}.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * 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);
--
--
+    /**
--
+     * Get the maximum distance(squared) a player can be in order for this
--
+     * spawner to be active.
--
+     * <br>
--
+     * If this value is less than or equal to 0, this spawner is always active
--
+     * (given that there are players online).
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * 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.
--
+     * <br>
--
+     * Default value is 4.
--
+     *
--
+     * @return the spawn range
--
+     */
--
+    public int getSpawnRange();
--
--
+    /**
--
+     * Set the new spawn range.
--
+     * <br>
--
+     *
--
+     * @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. <br>
--
+     * <p>
--
+     * All applicable data from the spawner will be copied, such as custom name,
--
+     * health, and velocity. <br>
--
+     *
--
+     * @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. <br>
--
+     * This will override any previous entries that have been added with
--
+     * {@link #addPotentialSpawn}
--
+     * <p>
--
+     * All applicable data from the snapshot will be copied, such as custom name,
--
+     * health, and velocity. <br>
--
+     *
--
+     * @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.
--
+     * <p>
--
+     * The weight will determine how often this entry is chosen to spawn, higher
--
+     * weighted entries will spawn more often than lower weighted ones. <br>
--
+     * 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. <br>
--
+     *
--
+     * @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. <br>
--
+     * This will override any previous entries added with
--
+     * {@link #addPotentialSpawn}
--
+     *
--
+     * @param entries the list of entries
--
+     */
--
+    public void setPotentialSpawns(@NotNull final Collection<SpawnerEntry> entries);
--
--
+    /**
--
+     * Gets a list of potential spawns from this spawner or an empty list if no
--
+     * entities have been assigned to this spawner. <br>
--
+     * 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<SpawnerEntry> getPotentialSpawns();
-30
+}

Bukkit

Commits

Jira Issues

Add shortcut