#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 <lynxplay101@gmail.com>

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 extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, @Nullable Consumer<T> 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.
+     * <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 Entity} that is to be spawned.
+     * @param <T>           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 extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, boolean randomizeData, @Nullable Consumer<T> function) throws IllegalArgumentException;
 }