From 738ff02e722f9585a0392040f25558ca6a00e39f Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Wed, 14 Jun 2023 18:36:08 +1000
Subject: [PATCH] #867: Add Player#sendBlockUpdate to send tile entity updates

By: Yannick Lamprecht <yannicklamprecht@live.de>
---
 .../java/org/bukkit/block/data/BlockData.java | 12 +++++++++++
 .../main/java/org/bukkit/entity/Player.java   | 21 +++++++++++++++++++
 2 files changed, 33 insertions(+)

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 96dbcc34c8..2e2232956f 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
@@ -6,11 +6,13 @@ import org.bukkit.Server;
 import org.bukkit.SoundGroup;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockFace;
+import org.bukkit.block.BlockState;
 import org.bukkit.block.BlockSupport;
 import org.bukkit.block.PistonMoveReaction;
 import org.bukkit.block.structure.Mirror;
 import org.bukkit.block.structure.StructureRotation;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -235,4 +237,14 @@ public interface BlockData extends Cloneable {
      * @param mirror the mirror
      */
     void mirror(@NotNull Mirror mirror);
+
+    /**
+     * Creates a new default {@link BlockState} for this type of Block, not
+     * bound to a location.
+     *
+     * @return a new {@link BlockState}
+     */
+    @NotNull
+    @ApiStatus.Experimental
+    BlockState createBlockState();
 }
diff --git a/paper-api/src/main/java/org/bukkit/entity/Player.java b/paper-api/src/main/java/org/bukkit/entity/Player.java
index 3c8e37b371..39cca34d0a 100644
--- a/paper-api/src/main/java/org/bukkit/entity/Player.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Player.java
@@ -22,6 +22,7 @@ import org.bukkit.advancement.AdvancementProgress;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 import org.bukkit.block.Sign;
+import org.bukkit.block.TileState;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.block.sign.Side;
 import org.bukkit.conversations.Conversable;
@@ -688,6 +689,26 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     public void sendSignChange(@NotNull Location loc, @Nullable String[] lines, @NotNull DyeColor dyeColor, boolean hasGlowingText) throws IllegalArgumentException;
 
+    /**
+     * Send a TileState change. This fakes a TileState change for a user at
+     * the given location. This will not actually change the world in any way.
+     * This method will use a TileState at the location's block or a faked TileState
+     * sent via
+     * {@link #sendBlockChange(org.bukkit.Location, org.bukkit.Material, byte)}.
+     * <p>
+     * If the client does not have an appropriate tile at the given location it
+     * may display an error message to the user.
+     * <p>
+     * {@link BlockData#createBlockState()} can be used to create a {@link BlockState}.
+     *
+     * @param loc the location of the sign
+     * @param tileState the tile state
+     * @throws IllegalArgumentException if location is null
+     * @throws IllegalArgumentException if tileState is null
+     */
+    @ApiStatus.Experimental
+    public void sendBlockUpdate(@NotNull Location loc, @NotNull TileState tileState) throws IllegalArgumentException;
+
     /**
      * Render a map and send it to the player in its entirety. This may be
      * used when streaming the map in the normal manner is not desirable.