Paper/patches/api/0348-Expand-FallingBlock-API.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Owen1212055 <23108066+Owen1212055@users.noreply.github.com>
Date: Sun, 5 Dec 2021 14:58:55 -0500
Subject: [PATCH] Expand FallingBlock API

- add auto expire setting
- add setter for block data
- add accessors for block state

Co-authored-by: Lukas Planz <lukas.planz@web.de>

diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 8e9ab00503167799c6c929d00e48c07cb328848c..907906e15c9250fea385e49f10d3c248236fd004 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -2228,8 +2228,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The spawned {@link FallingBlock} instance
      * @throws IllegalArgumentException if {@link Location} or {@link
      *     MaterialData} are null or {@link Material} of the {@link MaterialData} is not a block
+     * @deprecated Use {@link #spawn(Location, Class, Consumer)} (or a variation thereof) in combination with {@link FallingBlock#setBlockData(BlockData)}
      */
     @NotNull
+    @Deprecated(since = "1.20.2") // Paper
     public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull MaterialData data) throws IllegalArgumentException;
 
     /**
@@ -2242,8 +2244,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The spawned {@link FallingBlock} instance
      * @throws IllegalArgumentException if {@link Location} or {@link
      *     BlockData} are null
+     * @deprecated Use {@link #spawn(Location, Class, Consumer)} (or a variation thereof) in combination with {@link FallingBlock#setBlockData(BlockData)}
      */
     @NotNull
+    @org.jetbrains.annotations.ApiStatus.Obsolete(since = "1.20.2") // Paper
     public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull BlockData data) throws IllegalArgumentException;
 
     /**
@@ -2260,7 +2264,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The spawned {@link FallingBlock} instance
      * @throws IllegalArgumentException if {@link Location} or {@link
      *     Material} are null or {@link Material} is not a block
-     * @deprecated Magic value
+     * @deprecated Magic value. Use {@link #spawn(Location, Class, Consumer)} (or a variation thereof) in combination with {@link FallingBlock#setBlockData(BlockData)}
      */
     @Deprecated
     @NotNull
diff --git a/src/main/java/org/bukkit/entity/FallingBlock.java b/src/main/java/org/bukkit/entity/FallingBlock.java
index ae1ce2ee2deb82f3f4144ec54b3ba119b437c5e9..7904c716a3b0869ebf2f9b416536c59121a539a8 100644
--- a/src/main/java/org/bukkit/entity/FallingBlock.java
+++ b/src/main/java/org/bukkit/entity/FallingBlock.java
@@ -26,6 +26,33 @@ public interface FallingBlock extends Entity {
      */
     @NotNull
     BlockData getBlockData();
+    // Paper start
+    /**
+     * Sets the data for the falling block.
+     * <br>
+     * Any potential additional data currently stored in the falling blocks {@link #getBlockState()} will be
+     * purged by calling this setter.
+     *
+     * @param blockData the data to use as the block
+     */
+    void setBlockData(@NotNull BlockData blockData);
+
+    /**
+     * Get the data of the falling block represented as a {@link org.bukkit.block.BlockState BlockState}
+     * which includes potential NBT data that gets applied when the block gets placed on landing.
+     *
+     * @return the BlockState representing this block
+     */
+    @NotNull
+    org.bukkit.block.BlockState getBlockState();
+
+    /**
+     * Sets the {@link BlockData} and possibly present tile entity data for the falling block.
+     *
+     * @param blockState the BlockState to use
+     */
+    void setBlockState(@NotNull org.bukkit.block.BlockState blockState);
+    // Paper end
 
     /**
      * Get if the falling block will break into an item if it cannot be placed.
@@ -137,4 +164,23 @@ public interface FallingBlock extends Entity {
     default org.bukkit.Location getSourceLoc() {
         return this.getOrigin();
     }
+    // Paper start - Auto expire setting
+    /**
+     * Sets if this falling block should expire after:
+     * - 30 seconds
+     * - 5 seconds and is outside of the world
+     *
+     * @return if this behavior occurs
+     */
+    boolean doesAutoExpire();
+
+    /**
+     * Sets if this falling block should expire after:
+     * - 30 seconds
+     * - 5 seconds and is outside of the world
+     *
+     * @param autoExpires if this behavior should occur
+     */
+    void shouldAutoExpire(boolean autoExpires);
+    // Paper end - Auto expire setting
 }