SPIGOT-5422: Add support for 3-dimensional biomes

By: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/ChunkSnapshot.java

@@ -104,19 +104,44 @@ public interface ChunkSnapshot {
      * @param x X-coordinate (0-15)
      * @param z Z-coordinate (0-15)
      * @return Biome at given coordinate
+     * @deprecated biomes are now 3-dimensional
      */
     @NotNull
+    @Deprecated
     Biome getBiome(int x, int z);
 
     /**
-     * Get raw biome temperature (0.0-1.0) at given coordinate
+     * Get biome at given coordinates
+     *
+     * @param x X-coordinate (0-15)
+     * @param y Y-coordinate (0-255)
+     * @param z Z-coordinate (0-15)
+     * @return Biome at given coordinate
+     */
+    @NotNull
+    Biome getBiome(int x, int y, int z);
+
+    /**
+     * Get raw biome temperature at given coordinates
      *
      * @param x X-coordinate (0-15)
      * @param z Z-coordinate (0-15)
      * @return temperature at given coordinate
+     * @deprecated biomes are now 3-dimensional
      */
+    @Deprecated
     double getRawBiomeTemperature(int x, int z);
 
+    /**
+     * Get raw biome temperature at given coordinates
+     *
+     * @param x X-coordinate (0-15)
+     * @param y Y-coordinate (0-15)
+     * @param z Z-coordinate (0-15)
+     * @return temperature at given coordinate
+     */
+    double getRawBiomeTemperature(int x, int y, int z);
+
     /**
      * Get world full time when chunk snapshot was captured
      *

paper-api/src/main/java/org/bukkit/World.java

@@ -1278,19 +1278,44 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param x X coordinate of the block
      * @param z Z coordinate of the block
      * @return Biome of the requested block
+     * @deprecated biomes are now 3-dimensional
      */
     @NotNull
+    @Deprecated
     Biome getBiome(int x, int z);
 
+    /**
+     * Gets the 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
+     * @return Biome of the requested block
+     */
+    @NotNull
+    Biome getBiome(int x, int y, int z);
+
     /**
      * Sets the biome for the given block coordinates
      *
      * @param x X coordinate of the block
      * @param z Z coordinate of the block
      * @param bio new Biome type for this block
+     * @deprecated biomes are now 3-dimensional
      */
+    @Deprecated
     void setBiome(int x, int z, @NotNull Biome bio);
 
+    /**
+     * Sets the 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 bio new Biome type for this block
+     */
+    void setBiome(int x, int y, int z, @NotNull Biome bio);
+
     /**
      * Gets the temperature for the given block coordinates.
      * <p>
@@ -1303,9 +1328,27 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param x X coordinate of the block
      * @param z Z coordinate of the block
      * @return Temperature of the requested block
+     * @deprecated biomes are now 3-dimensional
      */
+    @Deprecated
     public double getTemperature(int x, int z);
 
+    /**
+     * Gets the temperature for the given block coordinates.
+     * <p>
+     * It is safe to run this method when the block does not exist, it will
+     * not create the block.
+     * <p>
+     * This method will return the raw temperature without adjusting for block
+     * height effects.
+     *
+     * @param x X coordinate of the block
+     * @param y Y coordinate of the block
+     * @param z Z coordinate of the block
+     * @return Temperature of the requested block
+     */
+    public double getTemperature(int x, int y, int z);
+
     /**
      * Gets the humidity for the given block coordinates.
      * <p>
@@ -1315,9 +1358,24 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param x X coordinate of the block
      * @param z Z coordinate of the block
      * @return Humidity of the requested block
+     * @deprecated biomes are now 3-dimensional
      */
+    @Deprecated
     public double getHumidity(int x, int z);
 
+    /**
+     * Gets the humidity for the given block coordinates.
+     * <p>
+     * It is safe to run this method when the block does not exist, it will
+     * not create the block.
+     *
+     * @param x X coordinate of the block
+     * @param y Y coordinate of the block
+     * @param z Z coordinate of the block
+     * @return Humidity of the requested block
+     */
+    public double getHumidity(int x, int y, int z);
+
     /**
      * Gets the maximum height of this world.
      * <p>

paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java

@@ -44,18 +44,43 @@ public abstract class ChunkGenerator {
          * @param x - 0-15
          * @param z - 0-15
          * @return Biome value
+         * @deprecated biomes are now 3-dimensional
          */
         @NotNull
+        @Deprecated
         Biome getBiome(int x, int z);
 
+        /**
+         * Get biome at x, z within chunk being generated
+         *
+         * @param x - 0-15
+         * @param y - 0-255
+         * @param z - 0-15
+         * @return Biome value
+         */
+        @NotNull
+        Biome getBiome(int x, int y, int z);
+
         /**
          * Set biome at x, z within chunk being generated
          *
          * @param x - 0-15
          * @param z - 0-15
          * @param bio - Biome value
+         * @deprecated biomes are now 3-dimensional
          */
+        @Deprecated
         void setBiome(int x, int z, @NotNull Biome bio);
+
+        /**
+         * Set biome at x, z within chunk being generated
+         *
+         * @param x - 0-15
+         * @param y - 0-255
+         * @param z - 0-15
+         * @param bio - Biome value
+         */
+        void setBiome(int x, int y, int z, @NotNull Biome bio);
     }
 
     /**