From 15d9fd30b9966bd6731f4c91ed8b677b02adc840 Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Sun, 12 Aug 2018 13:05:16 +1000 Subject: [PATCH] Update documentation of BlockPhysicsEvent By: md_5 --- .../bukkit/event/block/BlockPhysicsEvent.java | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java index 38224fd5fe..5e47eabe83 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java @@ -7,7 +7,23 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Thrown when a block physics check is called + * Thrown when a block physics check is called. + *
+ * This event is a high frequency event, it may be called thousands of times per + * a second on a busy server. Plugins are advised to listen to the event with + * caution and only perform lightweight checks when using it. + *
+ * In addition to this, cancelling the event is liable to leave the world in an + * inconsistent state. For example if you use the event to leave a block + * floating in mid air when that block has a requirement to be attached to + * something, there is no guarantee that the floating block will persist across + * server restarts or map upgrades. + *
+ * Plugins should also note that where possible this event may only called for + * the "root" block of physics updates in order to limit event spam. Physics + * updates that cause other blocks to change their state may not result in an + * event for each of those blocks (usually adjacent). If you are concerned about + * monitoring these changes then you should check adjacent blocks yourself. */ public class BlockPhysicsEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList();