From c23d391fcdf19a054ebf5ac886a5679c2bf0ad49 Mon Sep 17 00:00:00 2001 From: md_5 Date: Sun, 12 Aug 2018 13:05:16 +1000 Subject: Update documentation of BlockPhysicsEvent --- .../java/org/bukkit/event/block/BlockPhysicsEvent.java | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java b/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java index 38224fd5..5e47eabe 100644 --- a/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java +++ b/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(); -- cgit v1.2.3