Update documentation of BlockPhysicsEvent

1 files changed, 17 insertions, 1 deletions

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.
+ * <br>
+ * 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.
+ * <br>
+ * 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.
+ * <br>
+ * 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();