#767: Add support checking/survivability methods for BlockData

By: Parker Hawke <hawkeboyz2@hotmail.com>

paper-api/src/main/java/org/bukkit/block/BlockSupport.java

@@ -0,0 +1,33 @@
+package org.bukkit.block;
+
+/**
+ * Represents a level of support a block can give on one of its faces.
+ * <p>
+ * Any given face on a block may support anywhere between none and all three of the
+ * values in this enum. The top face of a grass block for instance can support blocks
+ * that require a full, center, or rigid face. On the contrary, all sides except the
+ * bottom of a camp fire cannot support any blocks, while the bottom face can support
+ * blocks that require a full or center face (such as a ceiling button).
+ */
+public enum BlockSupport {
+
+    /**
+     * The face is treated as a full block. For example, the side of a stair is
+     * <strong>not</strong> a full face and cannot support a wall torch, whereas the
+     * back and bottom of a stair are considered full.
+     */
+    FULL,
+    /**
+     * The face is capable of supporting blocks towards the center. For example, a
+     * wall or a fence post can support a standing torch as there is a solid component
+     * in the middle of the block.
+     */
+    CENTER,
+    /**
+     * The face is capable of supporting fragile blocks such as rails. Most
+     * full-supportable top faces are rigid, unlike walls and posts, or the side of a
+     * stone block, none of which are rigid.
+     */
+    RIGID;
+
+}

paper-api/src/main/java/org/bukkit/block/data/BlockData.java

@@ -1,8 +1,12 @@
 package org.bukkit.block.data;
 
+import org.bukkit.Location;
 import org.bukkit.Material;
 import org.bukkit.Server;
 import org.bukkit.SoundGroup;
+import org.bukkit.block.Block;
+import org.bukkit.block.BlockFace;
+import org.bukkit.block.BlockSupport;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -103,4 +107,48 @@ public interface BlockData extends Cloneable {
      */
     @NotNull
     SoundGroup getSoundGroup();
+
+    /**
+     * Checks if this state would be properly supported if it were placed at
+     * the given {@link Block}.
+     * <p>
+     * This may be useful, for instance, to check whether or not a wall torch is
+     * capable of surviving on its neighbouring block states.
+     *
+     * @param block the block position at which the state would be placed
+     *
+     * @return true if the block is supported, false if this state would not survive
+     * the world conditions
+     */
+    boolean isSupported(@NotNull Block block);
+
+    /**
+     * Checks if this state would be properly supported if it were placed at
+     * the block at the given {@link Location}.
+     * <p>
+     * This may be useful, for instance, to check whether or not a wall torch is
+     * capable of surviving on its neighbouring block states.
+     *
+     * @param location the location at which the state would be placed
+     *
+     * @return true if the block is supported, false if this state would not survive
+     * the world conditions
+     */
+    boolean isSupported(@NotNull Location location);
+
+    /**
+     * Checks if a state's {@link BlockFace} is capable of providing a given level
+     * of {@link BlockSupport} for neighbouring block states.
+     * <p>
+     * Any given state may support either none, one, or more than one level of block
+     * support depending on its states. A common example would be a wall's ability to support
+     * torches only on the center of the upper block face, whereas a grass block would
+     * support all levels of block support on all block faces.
+     *
+     * @param face the face to check
+     * @param support the possible support level
+     *
+     * @return true if the face is sturdy and can support a block, false otherwise
+     */
+    boolean isFaceSturdy(@NotNull BlockFace face, @NotNull BlockSupport support);
 }