diff --git a/paper-api/src/main/java/org/bukkit/block/BlockSupport.java b/paper-api/src/main/java/org/bukkit/block/BlockSupport.java new file mode 100644 index 0000000000..28693ea777 --- /dev/null +++ b/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. + *
+ * 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 + * not 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; + +} diff --git a/paper-api/src/main/java/org/bukkit/block/data/BlockData.java b/paper-api/src/main/java/org/bukkit/block/data/BlockData.java index c35a60a260..62273e32e8 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/BlockData.java +++ b/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}. + *
+ * 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}. + *
+ * 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. + *
+ * 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); }