split up InteractBlockEvent.Primary, InteractEntityEvent.Secondary

remove Cancellable where appropriate
move interaction points to events they always exists in

src/main/java/org/spongepowered/api/event/action/InteractEvent.java

@@ -24,7 +24,6 @@
  */
 package org.spongepowered.api.event.action;
 
-import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.Event;
 import org.spongepowered.math.vector.Vector3d;
 
@@ -33,13 +32,6 @@ import java.util.Optional;
 /**
  * Base event for all interactions.
  */
-public interface InteractEvent extends Event, Cancellable {
+public interface InteractEvent extends Event {
 
-    /**
-     * Gets the point of interaction where the interaction occurred as
-     * a {@link Vector3d}.
-     * 
-     * @return The interaction point if available
-     */
-    Optional<Vector3d> getInteractionPoint();
 }

src/main/java/org/spongepowered/api/event/block/InteractBlockEvent.java

@@ -28,11 +28,13 @@ import org.spongepowered.api.block.BlockSnapshot;
 import org.spongepowered.api.block.BlockState;
 import org.spongepowered.api.block.BlockTypes;
 import org.spongepowered.api.entity.living.player.Player;
+import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.action.InteractEvent;
 import org.spongepowered.api.item.inventory.ItemStack;
 import org.spongepowered.api.util.Direction;
 import org.spongepowered.api.util.Tristate;
 import org.spongepowered.api.world.ServerLocation;
+import org.spongepowered.math.vector.Vector3d;
 
 /**
  * Base event for all interactions involving a {@link BlockSnapshot} at a
@@ -65,7 +67,33 @@ public interface InteractBlockEvent extends InteractEvent {
      *
      * <p>This is usually left-click.</p>
      */
-    interface Primary extends InteractBlockEvent {}
+    interface Primary extends InteractBlockEvent {
+
+        /**
+         * Called when a player starts digging a block.
+         *
+         * <p>Canceling this will prevent starting to break a block in survival and breaking a block in creative</p>
+         */
+        interface Start extends Primary, Cancellable {
+
+        }
+
+        /**
+         * Called when a player cancels digging a block.
+         */
+        interface Stop extends Primary {
+
+        }
+
+        /**
+         * Called when a player finishes digging a block.
+         *
+         * <p>Canceling this will prevent breaking a block.</p>
+         */
+        interface Finish extends Primary, Cancellable {
+
+        }
+    }
 
     /**
      * An event where the targeted block is being interacted with the client's
@@ -73,7 +101,7 @@ public interface InteractBlockEvent extends InteractEvent {
      *
      * <p>This is usually right-click.</p>
      */
-    interface Secondary extends InteractBlockEvent {
+    interface Secondary extends InteractBlockEvent, Cancellable {
 
         Tristate getOriginalUseItemResult();
 
@@ -146,5 +174,12 @@ public interface InteractBlockEvent extends InteractEvent {
          *     used
          */
         void setUseBlockResult(Tristate result);
+
+        /**
+         * Gets the point of interaction where the interaction occurred as a {@link Vector3d}.
+         *
+         * @return The interaction point
+         */
+        Vector3d getInteractionPoint();
     }
 }

src/main/java/org/spongepowered/api/event/entity/InteractEntityEvent.java

@@ -25,12 +25,14 @@
 package org.spongepowered.api.event.entity;
 
 import org.spongepowered.api.entity.Entity;
+import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.action.InteractEvent;
+import org.spongepowered.math.vector.Vector3d;
 
 /**
  * Base event for all interactions targeting an {@link Entity}.
  */
-public interface InteractEntityEvent extends InteractEvent {
+public interface InteractEntityEvent extends InteractEvent, Cancellable {
 
     /**
      * Gets the {@link Entity}.
@@ -53,6 +55,31 @@ public interface InteractEntityEvent extends InteractEvent {
      *
      * <p>This is usually right-click.</p>
      */
-    interface Secondary extends InteractEntityEvent {}
+    interface Secondary extends InteractEntityEvent {
+
+        /**
+         * An entity is interacted with at an {@link #getInteractionPoint() interactionpoint}.
+         *
+         * <p>This is used for interactions targeting specific parts of an entity.</p>
+         */
+        interface At extends Secondary {
+            /**
+             * Gets the point of interaction where the interaction occurred as a {@link Vector3d}.
+             *
+             * @return The interaction point
+             */
+            Vector3d getInteractionPoint();
+        }
+
+        /**
+         * An entity is interacted on.
+         *
+         * <p>This is used for interactions targeting the entity as a whole.</p>
+         */
+        interface On extends Secondary {
+
+        }
+
+    }
 
 }

src/main/java/org/spongepowered/api/event/item/inventory/InteractItemEvent.java

@@ -24,7 +24,11 @@
  */
 package org.spongepowered.api.event.item.inventory;
 
+import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.action.InteractEvent;
+import org.spongepowered.api.event.block.InteractBlockEvent;
+import org.spongepowered.api.event.entity.InteractEntityEvent;
+import org.spongepowered.api.event.entity.living.AnimateHandEvent;
 import org.spongepowered.api.item.inventory.ItemStack;
 import org.spongepowered.api.item.inventory.ItemStackSnapshot;
 
@@ -43,7 +47,22 @@ public interface InteractItemEvent extends InteractEvent {
      */
     ItemStackSnapshot getItemStack();
 
-    interface Primary extends InteractItemEvent {}
+    /**
+     * Called when a player swings its hand in the air.
+     *
+     * <p>For block interactions use {@link InteractBlockEvent.Primary} and
+     * for entity interactions use {@link InteractEntityEvent.Primary} instead.</p>
+     *
+     * <p>To cancel the animation use {@link AnimateHandEvent} instead.</p>
+     */
+    interface Primary extends InteractItemEvent {
 
-    interface Secondary extends InteractItemEvent {}
+    }
+
+    /**
+     * Called when a player interacts with an item in hand.
+     *
+     * <p>Vanilla minecraft does not call an event when interacting with an empty hand in air.</p>
+     */
+    interface Secondary extends InteractItemEvent, Cancellable {}
 }