Implemented Item_Use events

By: durron597 <martin.jared@gmail.com>

paper-api/src/main/java/org/bukkit/event/Event.java

@@ -170,6 +170,33 @@ public abstract class Event {
          */
         PLAYER_ANIMATION (Category.PLAYER),
 
+        /**
+         * Always called when a player uses an item while pointing at a block
+         * Sometimes, cancelling this event doesn't do anything.
+         * 
+         * This is the event that is called on block placement. Cancel this
+         * to prevent block placement. This will ALWAYS be called, even if
+         * universe physics prevents the block from being placed. This allows
+         * you to add functionality to rightclicking with block items even
+         * if the universe won't allow them to get placed. Use BLOCK_CANBUILD
+         * to override notch's block placement rules.
+         * 
+         * Example: This event is also called, for example when redstone is
+         * placed, when a sign is placed, when minecarts are placed on a track,
+         * when boats are placed (in both water and air)
+         */
+        PLAYER_BLOCKITEM (Category.PLAYER),
+        
+        /**
+         * Called when a player uses an item while pointing at the air
+         * This can also be additionally called while pointing at the ground
+         * 
+         * Example: all food will also call this event while pointing at the
+         * ground, bows/snowballs/eggs will all call this while pointing at
+         * the ground, buckets call this event.
+         */
+        PLAYER_ITEM (Category.PLAYER),
+        
         /**
          * Called when a player teleports from one position to another
          */
@@ -185,7 +212,8 @@ public abstract class Event {
         BLOCK_DAMAGED (Category.BLOCK),
 
         /**
-         * Called when a block is undergoing a check on whether it can be built
+         * Called when a block is undergoing a universe physics
+         * check on whether it can be built
          *
          * For example, cacti cannot be built on grass unless overridden here
          */

paper-api/src/main/java/org/bukkit/event/player/PlayerBlockItemEvent.java

@@ -0,0 +1,79 @@
+package org.bukkit.event.player;
+
+import org.bukkit.Block;
+import org.bukkit.BlockFace;
+import org.bukkit.ItemStack;
+import org.bukkit.Player;
+import org.bukkit.event.Cancellable;
+
+/**
+ * Represents an event that a block was clicked with an item.
+ * 
+ * Note: while this is the event that is thrown on block placement, there is no
+ * BlockPlaced associated with this event. This is because the event is thrown
+ * before the block is written to the universe, so the returned block would not
+ * be the new placed block. In hMod, BlockPlaced worked by UNDOING the block
+ * placement; in Bukkit, we catch the event before it even gets written to the
+ * universe, so the concept of a placed block is meaningless.
+ * 
+ * To get the type of block that's being placed, use the method getItem (for
+ * the item in your hand).
+ * 
+ * @author durron597
+ */
+public class PlayerBlockItemEvent extends PlayerItemEvent implements Cancellable {
+    protected Block blockClicked;
+    protected BlockFace direction;
+    protected boolean cancel;
+    
+    public PlayerBlockItemEvent(Type type, Player who, ItemStack item, Block blockClicked, BlockFace direction) {
+        super(type, who, item);
+        this.blockClicked = blockClicked;
+        cancel = false;
+    }
+
+    /**
+     * Gets the cancellation state of this event. Set to true if you
+     * want to prevent buckets from placing water, from a block from being
+     * placed
+     * 
+     * @return boolean cancellation state
+     */
+    public boolean isCancelled() {
+        return cancel;
+    }
+
+    public void setCancelled(boolean cancel) {
+        this.cancel = cancel;
+    }
+    
+    /**
+     * Convenience method to inform the user whether this was a block placement
+     * event.
+     * 
+     * @return boolean true if the item in hand was a block
+     */
+    public boolean isBlock() {
+        if (item == null) return false;
+        
+        return item.getType().isBlock();
+    }
+    
+    /**
+     * Returns the clicked block
+     * 
+     * @return Block returns the block clicked with this item.
+     */
+    public Block getBlockClicked() {
+        return blockClicked;
+    }
+    
+    /**
+     * Returns the face of the block that was clicked
+     * 
+     * @return BlockFace returns the face of the block that was clicked
+     */
+    public BlockFace getBlockFace() {
+        return direction;
+    }
+}

paper-api/src/main/java/org/bukkit/event/player/PlayerItemEvent.java

@@ -0,0 +1,67 @@
+package org.bukkit.event.player;
+
+import org.bukkit.ItemStack;
+import org.bukkit.Material;
+import org.bukkit.Player;
+import org.bukkit.event.Cancellable;
+
+/**
+ * 
+ * @author durron597
+ *
+ */
+public class PlayerItemEvent extends PlayerEvent implements Cancellable {
+    protected ItemStack item;
+    protected boolean cancel;
+    
+    public PlayerItemEvent(Type type, Player who, ItemStack item) {
+        super(type, who);
+        this.item = item;
+        cancel = false;
+    }
+
+    /**
+     * Gets the cancellation state of this event. Set to true if you
+     * want to prevent buckets from placing water and so forth
+     * 
+     * @return boolean cancellation state
+     */
+    public boolean isCancelled() {
+        return cancel;
+    }
+
+    /**
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * Cancelling this event will prevent use of food (player won't lose the
+     * food item), prevent bows/snowballs/eggs from firing, etc. (player won't
+     * lose the ammo)
+     *
+     * @param cancel true if you wish to cancel this event
+     */
+    public void setCancelled(boolean cancel) {
+        this.cancel = cancel;
+    }
+    
+    /**
+     * Returns the item in hand represented by this event
+     * 
+     * @return ItemStack the item used
+     */
+    public ItemStack getItem() {
+        return this.item;
+    }
+    
+    /**
+     * Convenience method. Returns the material of the item represented by this
+     * event
+     * 
+     * @return Material the material of the item used
+     */
+    public Material getMaterial() {
+        if (this.item == null) return Material.Air;
+        
+        return item.getType();
+    }
+}

paper-api/src/main/java/org/bukkit/event/player/PlayerItemUseEvent.java

@@ -1,40 +0,0 @@
-package org.bukkit.event.player;
-
-import org.bukkit.Block;
-import org.bukkit.ItemStack;
-import org.bukkit.Player;
-import org.bukkit.event.Cancellable;
-
-/**
- * 
- * @author durron597
- *
- */
-public class PlayerItemUseEvent extends PlayerEvent implements Cancellable {
-    protected ItemStack item;
-    protected Block blockClicked;
-    protected boolean cancel;
-    
-    public PlayerItemUseEvent(Type type, Player who, ItemStack item, Block blockClicked) {
-        super(type, who);
-        this.item = item;
-        this.blockClicked = blockClicked;
-        cancel = false;
-    }
-
-    /**
-     * Gets the cancellation state of this event. Set to true if you
-     * want to prevent buckets from placing water and so forth
-     * 
-     * @return boolean cancellation state
-     */
-    @Override
-    public boolean isCancelled() {
-        return cancel;
-    }
-
-    @Override
-    public void setCancelled(boolean cancel) {
-        this.cancel = cancel;
-    }
-}