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 <antony@cyberiantiger.org>

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

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

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.
      * <p>
      * 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.
+     * <p>
+     * Notes:
+     * <p>
+     * This method should <b>never</b> attempt to get the Chunk at
+     * the passed coordinates, as doing so may cause an infinite loop
+     * <p>
+     * This method should <b>never</b> modify a ChunkData after it has
+     * been returned.
+     * <p>
+     * This method <b>must</b> 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);
+    }
 }