Some BlockFace improvements

By: Dinnerbone <dinnerbone@dinnerbone.com>

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<br />
+     * <br />
+     * 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<br />
+     * <br />
+     * For example, the following method places water at 100,102,100; two blocks
+     * above 100,100,100.
+     * <pre>
+     * Block block = world.getBlockAt(100,100,100);
+     * Block shower = block.getFace(BlockFace.Up, 2);
+     * shower.setType(Material.WATER);
+     * </pre>
+     *
+     * @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<br />
+     * <br />
+     * For example:
+     * <pre>
+     * Block current = world.getBlockAt(100, 100, 100);
+     * Block target = world.getBlockAt(100, 101, 100);
+     *
+     * current.getFace(target) == BlockFace.Up;
+     * </pre>
+     * <br />
+     * If the given block is not connected to this block, null may be returned
+     *
+     * @param block Block to compare against this block
+     * @return BlockFace of this block which has the requested block, or null
+     */
+    BlockFace getFace(Block block);
 }