Add interface for spawning FallingBlocks and correctly spawn a FallingBlock with the spawn(Location, FallingBlock.class) method. Adds BUKKIT-2282

Also add FallingBlock and methods.

Deprecated FallingSand to emphasize FallingBlock.

By: feildmaster <admin@feildmaster.com>

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

@@ -629,6 +629,32 @@ public interface World extends PluginMessageRecipient, Metadatable {
      */
     public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException;
 
+    /**
+     * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified {@link Material}.
+     * The material dictates what is falling. When the FallingBlock hits the ground, it will place that block.
+     * <p />
+     * The Material must be a block type, check with {@link Material#isBlock() material.isBlock()}.
+     * The Material may not be air.
+     *
+     * @param location The {@link Location} to spawn the FallingBlock
+     * @param material The block {@link Material} type
+     * @param data The block data
+     * @return The spawned {@link FallingBlock} instance
+     * @throws IllegalArgumentException if {@link Location} or {@link Material} are null or {@link Material} is not a block
+     */
+    public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException;
+
+    /**
+     * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified blockId (converted to {@link Material})
+     *
+     * @param location The {@link Location} to spawn the FallingBlock
+     * @param blockId see {@see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)} material
+     * @param blockData The block data
+     * @return The spawned FallingBlock instance
+     * @throws IllegalArgumentException see {@see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)}
+     */
+    public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException;
+
     /**
      * Plays an effect to all players within a default radius around a given location.
      *

paper-api/src/main/java/org/bukkit/entity/EntityType.java

@@ -19,7 +19,7 @@ public enum EntityType {
     ENDER_SIGNAL("EyeOfEnderSignal", EnderSignal.class, 15),
     THROWN_EXP_BOTTLE("ThrownExpBottle", ThrownExpBottle.class, 17),
     PRIMED_TNT("PrimedTnt", TNTPrimed.class, 20),
-    FALLING_BLOCK("FallingSand", FallingSand.class, 21, false),
+    FALLING_BLOCK("FallingSand", FallingBlock.class, 21, false),
     MINECART("Minecart", Minecart.class, 40),
     BOAT("Boat", Boat.class, 41),
     CREEPER("Creeper", Creeper.class, 50),

paper-api/src/main/java/org/bukkit/entity/FallingBlock.java

@@ -0,0 +1,43 @@
+package org.bukkit.entity;
+
+import org.bukkit.Material;
+
+/**
+ * Represents a falling block
+ */
+public interface FallingBlock extends Entity {
+    /**
+     * Get the Material of the falling block
+     *
+     * @return Material of the block
+     */
+    Material getMaterial();
+
+    /**
+     * Get the ID of the falling block
+     *
+     * @return ID type of the block
+     */
+    int getBlockId();
+
+    /**
+     * Get the data for the falling block
+     *
+     * @return data of the block
+     */
+    byte getBlockData();
+
+    /**
+     * Get if the falling block will break into an item if it cannot be placed
+     *
+     * @return true if the block will break into an item when obstructed
+     */
+    boolean getDropItem();
+
+    /**
+     * Set if the falling block will break into an item if it cannot be placed
+     *
+     * @param drop true to break into an item when obstructed
+     */
+    void setDropItem(boolean drop);
+}

paper-api/src/main/java/org/bukkit/entity/FallingSand.java

@@ -2,5 +2,8 @@ package org.bukkit.entity;
 
 /**
  * Represents a falling block.
+ *
+ * @deprecated See {@link FallingBlock}
  */
-public interface FallingSand extends Entity {}
+@Deprecated
+public interface FallingSand extends FallingBlock {}