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);
 }

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

@@ -10,6 +10,10 @@ public enum BlockFace {
     West(0, 0, 1),
     Up(0, 1, 0),
     Down(0, -1, 0),
+    NorthEast(North, East),
+    NorthWest(North, West),
+    SouthEast(South, East),
+    SouthWest(South, West),
     Self(0, 0, 0);
 
     private final int modX;
@@ -22,6 +26,12 @@ public enum BlockFace {
         this.modZ = modZ;
     }
 
+    private BlockFace(final BlockFace face1, final BlockFace face2) {
+        this.modX = face1.getModX() + face2.getModX();
+        this.modY = face1.getModY() + face2.getModY();
+        this.modZ = face1.getModZ() + face2.getModZ();
+    }
+
     /**
      * Get the amount of X-coordinates to modify to get the represented block
      * @return Amount of X-coordinates to modify