SPIGOT-3071, PaperMC#969: Add entity spawn method with spawn reason

lynxplay · Jan 31, 2024 · 1851857 · 1851857
1 parent cde4c52
commit 1851857
Showing 1 changed file with 40 additions and 0 deletions.
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
@@ -21,6 +21,7 @@
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Player;
 import org.bukkit.entity.SpawnCategory;
+import org.bukkit.event.entity.CreatureSpawnEvent;
 import org.bukkit.generator.BiomeProvider;
 import org.bukkit.generator.BlockPopulator;
 import org.bukkit.generator.ChunkGenerator;
@@ -1178,6 +1179,45 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     @NotNull
     public List<BlockPopulator> getPopulators();
 
+    /**
+     * Creates a new entity at the given {@link Location} with the supplied
+     * function run before the entity is added to the world.
+     * <br>
+     * Note that when the function is run, the entity will not be actually in
+     * the world. Any operation involving such as teleporting the entity is undefined
+     * until after this function returns.
+     * The passed function however is run after the potential entity's spawn
+     * randomization and hence already allows access to the values of the mob,
+     * whether or not those were randomized, such as attributes or the entity
+     * equipment.
+     *
+     * @param location      the location at which the entity will be spawned.
+     * @param clazz         the class of the {@link LivingEntity} that is to be spawned.
+     * @param <T>           the generic type of the entity that is being created.
+     * @param spawnReason   the reason provided during the {@link CreatureSpawnEvent} call.
+     * @param randomizeData whether or not the entity's data should be randomised
+     *                      before spawning. By default entities are randomised
+     *                      before spawning in regards to their equipment, age,
+     *                      attributes, etc.
+     *                      An example of this randomization would be the color of
+     *                      a sheep, random enchantments on the equipment of mobs
+     *                      or even a zombie becoming a chicken jockey.
+     *                      If set to false, the entity will not be randomised
+     *                      before spawning, meaning all their data will remain
+     *                      in their default state and not further modifications
+     *                      to the entity will be made.
+     *                      Notably only entities that extend the
+     *                      {@link org.bukkit.entity.Mob} interface provide
+     *                      randomisation logic for their spawn.
+     *                      This parameter is hence useless for any other type
+     *                      of entity.
+     * @param function      the function to be run before the entity is spawned.
+     * @return the spawned entity instance.
+     * @throws IllegalArgumentException if either the world or clazz parameter are null.
+     */
+    @NotNull
+    public <T extends LivingEntity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, @NotNull CreatureSpawnEvent.SpawnReason spawnReason, boolean randomizeData, @Nullable Consumer<? super T> function) throws IllegalArgumentException;
+
     /**
      * Spawn a {@link FallingBlock} entity at the given {@link Location} of
      * the specified {@link MaterialData}. The MaterialData dictates what is falling.