From f84947b94226fb5ccc470f0dec9d4ac3e1d85056 Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Wed, 18 Aug 2021 18:04:51 +1000 Subject: [PATCH] #653: Add World#spawn with randomizeData parameter The current implementation of World#spawn or World#spawnEntity respectively, always prepares/finalizes the spawn of every entity spawned through the API. While this is great to simulate natural spawning of entities in the world through the API, it fails at reliably creating default entities for purposes other than vanilla gameplay. While the caller of the API could attempt to undo all of the customization that is applied in the prepare/finalization step, they are numerous (reaching from sheep colour to equipment) and in some cases, such as the chicken jockey, even spawn in other entities. Hence this commit introduces a new overload to the World#spawn and World#spawnEntity methods that accepts the 'randomizeData' parameter that, when set to false, skips the prior mentioned preparation/finalization step. By: Bjarne Koll --- .../main/java/org/bukkit/RegionAccessor.java | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/paper-api/src/main/java/org/bukkit/RegionAccessor.java b/paper-api/src/main/java/org/bukkit/RegionAccessor.java index a5539309e0..e285d54450 100644 --- a/paper-api/src/main/java/org/bukkit/RegionAccessor.java +++ b/paper-api/src/main/java/org/bukkit/RegionAccessor.java @@ -193,6 +193,32 @@ public interface RegionAccessor { @NotNull Entity spawnEntity(@NotNull Location location, @NotNull EntityType type); + /** + * Creates a new entity at the given {@link Location}. + * + * @param loc the location at which the entity will be spawned. + * @param type the entity type that determines the entity to spawn. + * @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. + * @return the spawned entity instance. + */ + @NotNull + public Entity spawnEntity(@NotNull Location loc, @NotNull EntityType type, boolean randomizeData); + /** * Get a list of all entities in this RegionAccessor * @@ -263,4 +289,42 @@ public interface RegionAccessor { */ @NotNull T spawn(@NotNull Location location, @NotNull Class clazz, @Nullable Consumer function) throws IllegalArgumentException; + + /** + * Creates a new entity at the given {@link Location} with the supplied + * function run before the entity is added to the world. + *
+ * 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 Entity} that is to be spawned. + * @param the generic type of the entity that is being created. + * @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 spawn(@NotNull Location location, @NotNull Class clazz, boolean randomizeData, @Nullable Consumer function) throws IllegalArgumentException; }