diff --git a/paper-api/src/main/java/org/bukkit/Block.java b/paper-api/src/main/java/org/bukkit/Block.java
index 8909de4d9d..63cabda8ea 100644
--- a/paper-api/src/main/java/org/bukkit/Block.java
+++ b/paper-api/src/main/java/org/bukkit/Block.java
@@ -12,13 +12,33 @@ public interface Block {
byte getData();
/**
- * Gets the block at the given face
+ * Gets the block at the given face
+ *
+ * This method is equal to getFace(face, 1)
*
* @param face Face of this block to return
* @return Block at the given face
+ * @see Block.getFace(BlockFace face, int distance);
*/
Block getFace(BlockFace face);
+ /**
+ * Gets the block at the given distance of the given face
+ *
+ * For example, the following method places water at 100,102,100; two blocks
+ * above 100,100,100.
+ *
+ * Block block = world.getBlockAt(100,100,100); + * Block shower = block.getFace(BlockFace.Up, 2); + * shower.setType(Material.WATER); + *+ * + * @param face Face of this block to return + * @param distance Distance to get the block at + * @return Block at the given face + */ + Block getFace(BlockFace face, int distance); + /** * Gets the block at the given offsets * @@ -105,4 +125,22 @@ public interface Block { * @param type Type-ID to change this block to */ void setTypeID(int type); + + /** + * Gets the face relation of this block compared to the given block
+ * Block current = world.getBlockAt(100, 100, 100); + * Block target = world.getBlockAt(100, 101, 100); + * + * current.getFace(target) == BlockFace.Up; + *+ *