SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

SPIGOT-5880, SPIGOT-5567: New ChunkGenerator API

Browse Source 
## **Current API**
The current world generation API is very old and limited when you want to make more complex world generation. Resulting in some hard to fix bugs such as that you cannot modify blocks outside the chunk in the BlockPopulator (which should and was per the docs possible), or strange behavior such as SPIGOT-5880.

## **New API**
With the new API, the generation is more separate in multiple methods and is more in line with Vanilla chunk generation. The new API is designed to as future proof as possible. If for example a new generation step is added it can easily also be added as a step in API by simply creating the method for it. On the other side if a generation step gets removed, the method can easily be called after another, which is the case with surface and bedrock. The new API and changes are also fully backwards compatible with old chunk generators.

### **Changes in the new api**
**Extra generation steps:**
Noise, surface, bedrock and caves are added as steps. With those generation steps three extra methods for Vanilla generation are also added. Those new methods provide the ChunkData instead of returning one. The reason for this is, that the ChunkData is now backed by a ChunkAccess. With this, each step has the information of the step before and the Vanilla information (if chosen by setting a 'should' method to true). The old method is deprecated.

**New class BiomeProvider**
The BiomeProvider acts as Biome source and wrapper for the NMS class WorldChunkManager. With this the underlying Vanilla ChunkGeneration knows which Biome to use for the structure and decoration generation. (Fixes: SPIGOT-5880). Although the List of Biomes which is required in BiomeProvider, is currently not much in use in Vanilla, I decided to add it to future proof the API when it may be required in later versions of Minecraft.
The BiomeProvider is also separated from the ChunkGenerator for plugins which only want to change the biome map, such as single Biome worlds or if some biomes should be more present than others.

**Deprecated isParallelCapable**
Mojang has and is pushing to a more multi threaded chunk generation. This should also be the case for custom chunk generators. This is why the new API only supports multi threaded generation. This does not affect the old API, which is still checking this.

**Base height method added**
This method was added to also bring the Minecraft generator and Bukkit generator more in line. With this it is possible to return the max height of a location (before decorations). This is useful to let most structures know were to place them. This fixes SPIGOT-5567. (This fixes not all structures placement, desert pyramids for example are still way up at y-level 64, This however is more a vanilla bug and should be fixed at Mojangs end).

**WorldInfo Class**
The World object was swapped for a WorldInfo object. This is because many methods of the World object won't work during world generation and would mostly likely result in a deadlock. It contains any information a plugin should need to identify the world.

**BlockPopulator Changes**
Instead of directly manipulating a chunk, changes are now made to a new class LimitedRegion, this class provides methods to populated the chunk and its surrounding area. The wrapping is done so that the population can be moved into the place where Minecraft generates decorations. Where there is no chunk to access yet. By moving it into this place the generation is now async and the surrounding area of the chunk can also be used.

For common methods between the World and LimitedRegion a RegionAccessor was added.

By: DerFrZocker <derrieple@gmail.com>
This commit is contained in:
Bukkit/Spigot
2021-08-15 08:08:11 +10:00
parent 511a9aba49
commit c255eb3333
11 changed files with 881 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
paper-api/src/main/java/org/bukkit/RegionAccessor.java Normal file
View File

@@ -0,0 +1,266 @@
package org.bukkit;
import java.util.Collection;
import java.util.List;
import java.util.Random;
import org.bukkit.block.Biome;
import org.bukkit.block.BlockState;
import org.bukkit.block.data.BlockData;
import org.bukkit.entity.Entity;
import org.bukkit.entity.EntityType;
import org.bukkit.entity.LivingEntity;
import org.bukkit.util.Consumer;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A RegionAccessor gives access to getting, modifying and spawning {@link Biome}, {@link BlockState} and {@link Entity},
* as well as generating some basic structures.
*/
public interface RegionAccessor {
/**
* Gets the {@link Biome} at the given {@link Location}.
*
* @param location the location of the biome
* @return Biome at the given location
*/
@NotNull
Biome getBiome(@NotNull Location location);
/**
* Gets the {@link Biome} at the given coordinates.
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @return Biome at the given coordinates
*/
@NotNull
Biome getBiome(int x, int y, int z);
/**
* Sets the {@link Biome} at the given {@link Location}.
*
* @param location the location of the biome
* @param biome New Biome type for this block
*/
void setBiome(@NotNull Location location, @NotNull Biome biome);
/**
* Sets the {@link Biome} for the given block coordinates
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @param biome New Biome type for this block
*/
void setBiome(int x, int y, int z, @NotNull Biome biome);
/**
* Gets the {@link BlockState} at the given {@link Location}.
*
* @param location The location of the block state
* @return Block state at the given location
*/
@NotNull
BlockState getBlockState(@NotNull Location location);
/**
* Gets the {@link BlockState} at the given coordinates.
*
* @param x X-coordinate of the block state
* @param y Y-coordinate of the block state
* @param z Z-coordinate of the block state
* @return Block state at the given coordinates
*/
@NotNull
BlockState getBlockState(int x, int y, int z);
/**
* Gets the {@link BlockData} at the given {@link Location}.
*
* @param location The location of the block data
* @return Block data at the given location
*/
@NotNull
BlockData getBlockData(@NotNull Location location);
/**
* Gets the {@link BlockData} at the given coordinates.
*
* @param x X-coordinate of the block data
* @param y Y-coordinate of the block data
* @param z Z-coordinate of the block data
* @return Block data at the given coordinates
*/
@NotNull
BlockData getBlockData(int x, int y, int z);
/**
* Gets the type of the block at the given {@link Location}.
*
* @param location The location of the block
* @return Material at the given coordinates
*/
@NotNull
Material getType(@NotNull Location location);
/**
* Gets the type of the block at the given coordinates.
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @return Material at the given coordinates
*/
@NotNull
Material getType(int x, int y, int z);
/**
* Sets the {@link BlockData} at the given {@link Location}.
*
* @param location The location of the block
* @param blockData The block data to set the block to
*/
void setBlockData(@NotNull Location location, @NotNull BlockData blockData);
/**
* Sets the {@link BlockData} at the given coordinates.
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @param blockData The block data to set the block to
*/
void setBlockData(int x, int y, int z, @NotNull BlockData blockData);
/**
* Sets the {@link Material} at the given {@link Location}.
*
* @param location The location of the block
* @param material The type to set the block to
*/
void setType(@NotNull Location location, @NotNull Material material);
/**
* Sets the {@link Material} at the given coordinates.
*
* @param x X-coordinate of the block
* @param y Y-coordinate of the block
* @param z Z-coordinate of the block
* @param material The type to set the block to
*/
void setType(int x, int y, int z, @NotNull Material material);
/**
* Creates a tree at the given {@link Location}
*
* @param location Location to spawn the tree
* @param random Random to use to generated the tree
* @param type Type of the tree to create
* @return true if the tree was created successfully, otherwise false
*/
boolean generateTree(@NotNull Location location, @NotNull Random random, @NotNull TreeType type);
/**
* Creates a tree at the given {@link Location}
* <p>
* The provided consumer gets called for every block which gets changed
* as a result of the tree generation. When the consumer gets called no
* modifications to the world are done yet. Which means, that calling
* {@link #getBlockState(Location)} in the consumer while return the state
* of the block before the generation.
* <p>
* Modifications done to the {@link BlockState} in the consumer are respected,
* which means that it is not necessary to call {@link BlockState#update()}
*
* @param location Location to spawn the tree
* @param random Random to use to generated the tree
* @param type Type of the tree to create
* @param stateConsumer The consumer which should get called for every block which gets changed
* @return true if the tree was created successfully, otherwise false
*/
boolean generateTree(@NotNull Location location, @NotNull Random random, @NotNull TreeType type, @Nullable Consumer<BlockState> stateConsumer);
/**
* Creates a entity at the given {@link Location}
*
* @param location The location to spawn the entity
* @param type The entity to spawn
* @return Resulting Entity of this method
*/
@NotNull
Entity spawnEntity(@NotNull Location location, @NotNull EntityType type);
/**
* Get a list of all entities in this RegionAccessor
*
* @return A List of all Entities currently residing in this world accessor
*/
@NotNull
List<Entity> getEntities();
/**
* Get a list of all living entities in this RegionAccessor
*
* @return A List of all LivingEntities currently residing in this world accessor
*/
@NotNull
List<LivingEntity> getLivingEntities();
/**
* Get a collection of all entities in this RegionAccessor matching the given
* class/interface
*
* @param <T> an entity subclass
* @param cls The class representing the type of entity to match
* @return A List of all Entities currently residing in this world accessor
* that match the given class/interface
*/
@NotNull
<T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T> cls);
/**
* Get a collection of all entities in this RegionAccessor matching any of the
* given classes/interfaces
*
* @param classes The classes representing the types of entity to match
* @return A List of all Entities currently residing in this world accessor
* that match one or more of the given classes/interfaces
*/
@NotNull
Collection<Entity> getEntitiesByClasses(@NotNull Class<?>... classes);
/**
* Spawn an entity of a specific class at the given {@link Location}
*
* @param location the {@link Location} to spawn the entity at
* @param clazz the class of the {@link Entity} to spawn
* @param <T> the class of the {@link Entity} to spawn
* @return an instance of the spawned {@link Entity}
* @throws IllegalArgumentException if either parameter is null or the
* {@link Entity} requested cannot be spawned
*/
@NotNull
<T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz) throws IllegalArgumentException;
/**
* Spawn an entity of a specific class 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.
*
* @param location the {@link Location} to spawn the entity at
* @param clazz the class of the {@link Entity} to spawn
* @param function the function to be run before the entity is spawned.
* @param <T> the class of the {@link Entity} to spawn
* @return an instance of the spawned {@link Entity}
* @throws IllegalArgumentException if either parameter is null or the
* {@link Entity} requested cannot be spawned
*/
@NotNull
<T extends Entity> T spawn(@NotNull Location location, @NotNull Class<T> clazz, @Nullable Consumer<T> function) throws IllegalArgumentException;
}