#473: Add an API for passing the heightmap to getHighestBlockAt* method

By: ysl3000 <yannicklamprecht@live.de>

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

@@ -0,0 +1,36 @@
+package org.bukkit;
+
+/**
+ * Further information regarding heightmaps.
+ *
+ * @see <a href="https://minecraft.gamepedia.com/Chunk_format">Gamepedia Chunk
+ * Format</a>
+ */
+public enum HeightMap {
+
+    /**
+     * The highest block that blocks motion or contains a fluid.
+     */
+    MOTION_BLOCKING,
+    /**
+     * The highest block that blocks motion or contains a fluid or is in the
+     * {@link Tag#LEAVES}.
+     */
+    MOTION_BLOCKING_NO_LEAVES,
+    /**
+     * The highest non-air block, solid block.
+     */
+    OCEAN_FLOOR,
+    /**
+     * The highest block that is neither air nor contains a fluid, for worldgen.
+     */
+    OCEAN_FLOOR_WG,
+    /**
+     * The highest non-air block.
+     */
+    WORLD_SURFACE,
+    /**
+     * The highest non-air block, for worldgen.
+     */
+    WORLD_SURFACE_WG,
+}

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

@@ -97,6 +97,57 @@ public interface World extends PluginMessageRecipient, Metadatable {
     @NotNull
     public Block getHighestBlockAt(@NotNull Location location);
 
+    /**
+     * Gets the highest coordinate corresponding to the {@link HeightMap} at the
+     * given coordinates.
+     *
+     * @param x X-coordinate of the blocks
+     * @param z Z-coordinate of the blocks
+     * @param heightMap the heightMap that is used to determine the highest
+     * point
+     *
+     * @return Y-coordinate of the highest block corresponding to the
+     * {@link HeightMap}
+     */
+    public int getHighestBlockYAt(int x, int z, @NotNull HeightMap heightMap);
+
+    /**
+     * Gets the highest coordinate corresponding to the {@link HeightMap} at the
+     * given {@link Location}.
+     *
+     * @param location Location of the blocks
+     * @param heightMap the heightMap that is used to determine the highest
+     * point
+     * @return Y-coordinate of the highest block corresponding to the
+     * {@link HeightMap}
+     */
+    public int getHighestBlockYAt(@NotNull Location location, @NotNull HeightMap heightMap);
+
+    /**
+     * Gets the highest block corresponding to the {@link HeightMap} at the
+     * given coordinates.
+     *
+     * @param x X-coordinate of the block
+     * @param z Z-coordinate of the block
+     * @param heightMap the heightMap that is used to determine the highest
+     * point
+     * @return Highest block corresponding to the {@link HeightMap}
+     */
+    @NotNull
+    public Block getHighestBlockAt(int x, int z, @NotNull HeightMap heightMap);
+
+    /**
+     * Gets the highest block corresponding to the {@link HeightMap} at the
+     * given coordinates.
+     *
+     * @param location Coordinates to get the highest block
+     * @param heightMap the heightMap that is used to determine the highest
+     * point
+     * @return Highest block corresponding to the {@link HeightMap}
+     */
+    @NotNull
+    public Block getHighestBlockAt(@NotNull Location location, @NotNull HeightMap heightMap);
+
     /**
      * Gets the {@link Chunk} at the given coordinates
      *