From 5ec19def070ced7fb5a3d0acc8950cefe2cb499a Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Tue, 28 Jul 2015 16:21:03 +0300 Subject: [PATCH] Implement greatly expanded ChunkGenerator API This new API: * Has first class support for Material / MaterialData * Abstracts away the underlying Chunk format * Implements useful utility methods to make life easier By: Antony Riley --- .../src/main/java/org/bukkit/Bukkit.java | 14 ++ .../src/main/java/org/bukkit/Server.java | 12 + .../org/bukkit/generator/ChunkGenerator.java | 229 +++++++++++++++++- 3 files changed, 254 insertions(+), 1 deletion(-) diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index fd7d116ab5..d7b88d6e44 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/paper-api/src/main/java/org/bukkit/Bukkit.java @@ -37,6 +37,7 @@ import org.bukkit.util.CachedServerIcon; import com.avaje.ebean.config.ServerConfig; import com.google.common.collect.ImmutableList; +import org.bukkit.generator.ChunkGenerator; import org.bukkit.inventory.ItemFactory; import org.bukkit.inventory.meta.ItemMeta; @@ -1116,6 +1117,19 @@ public final class Bukkit { return server.getIdleTimeout(); } + /** + * Create a ChunkData for use in a generator. + * + * See {@link ChunkGenerator#generateChunkData(org.bukkit.World, java.util.Random, int, int, org.bukkit.generator.ChunkGenerator.BiomeGrid)} + * + * @param world the world to create the ChunkData for + * @return a new ChunkData for the world + * + */ + public static ChunkGenerator.ChunkData createChunkData(World world) { + return server.createChunkData(world); + } + /** * @see UnsafeValues * @return the unsafe values instance diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index ca6c42c1ce..c2f5de4025 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/paper-api/src/main/java/org/bukkit/Server.java @@ -38,6 +38,7 @@ import org.bukkit.util.CachedServerIcon; import com.avaje.ebean.config.ServerConfig; import com.google.common.collect.ImmutableList; +import org.bukkit.generator.ChunkGenerator; import org.bukkit.inventory.ItemFactory; import org.bukkit.inventory.meta.ItemMeta; @@ -914,6 +915,17 @@ public interface Server extends PluginMessageRecipient { */ public int getIdleTimeout(); + /** + * Create a ChunkData for use in a generator. + * + * See {@link ChunkGenerator#generateChunkData(org.bukkit.World, java.util.Random, int, int, org.bukkit.generator.ChunkGenerator.BiomeGrid)} + * + * @param world the world to create the ChunkData for + * @return a new ChunkData for the world + * + */ + public ChunkGenerator.ChunkData createChunkData(World world); + /** * @see UnsafeValues * @return the unsafe values instance diff --git a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java index e5db64970c..5137024548 100644 --- a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java +++ b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java @@ -3,11 +3,13 @@ package org.bukkit.generator; import java.util.ArrayList; import java.util.List; import java.util.Random; +import org.bukkit.Bukkit; import org.bukkit.Location; import org.bukkit.Material; import org.bukkit.World; import org.bukkit.block.Biome; import org.bukkit.block.Block; +import org.bukkit.material.MaterialData; /** * A chunk generator is responsible for the initial shaping of an entire @@ -17,7 +19,7 @@ import org.bukkit.block.Block; public abstract class ChunkGenerator { /** - * Interface to biome data for chunk to be generated: initialized with + * Interface to biome section for chunk to be generated: initialized with * default values for world type and seed. *

* Custom generator is free to access and tailor values during @@ -219,6 +221,43 @@ public abstract class ChunkGenerator { return null; // Default - returns null, which drives call to generate() } + /** + * Shapes the chunk for the given coordinates. + * + * This method must return a ChunkData. + *

+ * Notes: + *

+ * This method should never attempt to get the Chunk at + * the passed coordinates, as doing so may cause an infinite loop + *

+ * This method should never modify a ChunkData after it has + * been returned. + *

+ * This method must return a ChunkData returned by {@link ChunkGenerator#createChunkData(org.bukkit.World)} + * + * @param world The world this chunk will be used for + * @param random The random generator to use + * @param x The X-coordinate of the chunk + * @param z The Z-coordinate of the chunk + * @param biome Proposed biome values for chunk - can be updated by + * generator + * @return ChunkData containing the types for each block created by this + * generator + */ + public ChunkData generateChunkData(World world, Random random, int x, int z, BiomeGrid biome) { + return null; // Default - returns null, which drives call to generateExtBlockSections() + } + + /** + * Create a ChunkData for a world. + * @param world the world the ChunkData is for + * @return a new ChunkData for world + */ + protected final ChunkData createChunkData(World world) { + return Bukkit.getServer().createChunkData(world); + } + /** * Tests if the specified location is valid for a natural spawn position * @@ -265,4 +304,192 @@ public abstract class ChunkGenerator { public Location getFixedSpawnLocation(World world, Random random) { return null; } + + /** + * Data for a Chunk. + */ + public static interface ChunkData { + /** + * Get the maximum height for the chunk. + * + * Setting blocks at or above this height will do nothing. + * + * @return the maximum height + */ + public int getMaxHeight(); + + /** + * Set the block at x,y,z in the chunk data to material. + * + * Note: setting blocks outside the chunk's bounds does nothing. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @param material the type to set the block to + */ + public void setBlock(int x, int y, int z, Material material); + + /** + * Set the block at x,y,z in the chunk data to material. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @param material the type to set the block to + */ + public void setBlock(int x, int y, int z, MaterialData material); + + /** + * Set a region of this chunk from xMin, yMin, zMin (inclusive) + * to xMax, yMax, zMax (exclusive) to material. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param xMin minimum x location (inclusive) in the chunk to set + * @param yMin minimum y location (inclusive) in the chunk to set + * @param zMin minimum z location (inclusive) in the chunk to set + * @param xMax maximum x location (exclusive) in the chunk to set + * @param yMax maximum y location (exclusive) in the chunk to set + * @param zMax maximum z location (exclusive) in the chunk to set + * @param material the type to set the blocks to + */ + public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, Material material); + + /** + * Set a region of this chunk from xMin, yMin, zMin (inclusive) + * to xMax, yMax, zMax (exclusive) to material. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param xMin minimum x location (inclusive) in the chunk to set + * @param yMin minimum y location (inclusive) in the chunk to set + * @param zMin minimum z location (inclusive) in the chunk to set + * @param xMax maximum x location (exclusive) in the chunk to set + * @param yMax maximum y location (exclusive) in the chunk to set + * @param zMax maximum z location (exclusive) in the chunk to set + * @param material the type to set the blocks to + */ + public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, MaterialData material); + + /** + * Get the type of the block at x, y, z. + * + * Getting blocks outside the chunk's bounds returns air. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @return the type of the block or Material.AIR if x, y or z are outside the chunk's bounds + */ + public Material getType(int x, int y, int z); + + /** + * Get the type and data of the block at x, y ,z. + * + * Getting blocks outside the chunk's bounds returns air. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @return the type and data of the block or the MaterialData for air if x, y or z are outside the chunk's bounds + */ + public MaterialData getTypeAndData(int x, int y, int z); + + /** + * Set a region of this chunk from xMin, yMin, zMin (inclusive) + * to xMax, yMax, zMax (exclusive) to block id. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param xMin minimum x location (inclusive) in the chunk to set + * @param yMin minimum y location (inclusive) in the chunk to set + * @param zMin minimum z location (inclusive) in the chunk to set + * @param xMax maximum x location (exclusive) in the chunk to set + * @param yMax maximum y location (exclusive) in the chunk to set + * @param zMax maximum z location (exclusive) in the chunk to set + * @param blockId the block id to set the blocks to + * @deprecated Uses magic values. + */ + @Deprecated + public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, int blockId); + + /** + * Set a region of this chunk from xMin, yMin, zMin (inclusive) + * to xMax, yMax, zMax (exclusive) to block id and data. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param xMin minimum x location (inclusive) in the chunk to set + * @param yMin minimum y location (inclusive) in the chunk to set + * @param zMin minimum z location (inclusive) in the chunk to set + * @param xMax maximum x location (exclusive) in the chunk to set + * @param yMax maximum y location (exclusive) in the chunk to set + * @param zMax maximum z location (exclusive) in the chunk to set + * @param blockId the block id to set the blocks to + * @param data the block data to set the blocks to + * @deprecated Uses magic values. + */ + @Deprecated + public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, int blockId, int data); + + /** + * Set the block at x,y,z in the chunk data to blockId. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @param blockId the blockId to set the block to + * @deprecated Uses magic values + */ + @Deprecated + public void setBlock(int x, int y, int z, int blockId); + + /** + * Set the block at x,y,z in the chunk data to blockId. + * + * Setting blocks outside the chunk's bounds does nothing. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @param blockId the blockId to set the block to + * @param data the block data to set the block to + * @deprecated Uses magic values + */ + @Deprecated + public void setBlock(int x, int y, int z, int blockId, byte data); + + /** + * Get the blockId at x,y,z in the chunk data. + * + * Getting blocks outside the chunk's bounds returns 0. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @return the block id or 0 if x, y or z are outside the chunk's bounds + * @deprecated Uses magic values + */ + @Deprecated + public int getTypeId(int x, int y, int z); + + /** + * Get the block data at x,y,z in the chunk data. + * + * Getting blocks outside the chunk's bounds returns 0. + * + * @param x the x location in the chunk from 0-15 inclusive + * @param y the y location in the chunk from 0 (inclusive) - maxHeight (exclusive) + * @param z the z location in the chunk from 0-15 inclusive + * @return the block data value or air if x, y or z are outside the chunk's bounds + * @deprecated Uses magic values + */ + @Deprecated + public byte getData(int x, int y, int z); + } }