Event interfaces refactoring

Author: lare96

src/main/java/io/luna/game/event/impl/ControllableEvent.java

@@ -4,7 +4,21 @@
 import io.luna.game.model.mob.controller.PlayerController;
 
 /**
- * Represents an {@link Event} type that can be terminated by a {@link PlayerController} before being posted.
+ * Represents an {@link Event} type that may be intercepted, modified, or cancelled by a {@link PlayerController}
+ * before being posted.
+ * <p>
+ * When an event implements this interface, it signals that the player's active controller has authority to prevent
+ * the event from executing.
+ * <p>
+ * This is commonly used for:
+ * <ul>
+ *     <li>Restricting actions during minigames.</li>
+ *     <li>Contextual modifications.</li>
+ *     <li>Enforcing contextual gameplay rules.</li>
+ * </ul>
+ * <p>
+ * This interface does not define behavior directly; it acts as a semantic contract recognized by the event dispatch
+ * system.
  *
  * @author lare96
  */

src/main/java/io/luna/game/event/impl/InteractableEvent.java

@@ -5,20 +5,42 @@
 import io.luna.game.model.mob.InteractionTask;
 
 /**
- * Represents an {@link Event} type that needs to be posted within an {@link InteractionTask}. Events like this are
- * not posted until the interaction can be successfully completed.
+ * Represents an {@link Event} type that require a target to be interacted with, before they are posted.
+ * <p>
+ * Events implementing this interface are not dispatched immediately. Instead, they are wrapped in an
+ * {@link InteractionTask}, which handles movement and distance checks. The event is only posted once the
+ * interaction requirements (such as proximity) are successfully satisfied.
+ * <p>
+ * Typical use cases include:
+ * <ul>
+ *     <li>Clicking an NPC that requires walking to it first.</li>
+ *     <li>Interacting with an object that must be reached.</li>
+ *     <li>Casting a spell on an entity.</li>
+ * </ul>
  *
  * @author lare96
  */
 public interface InteractableEvent {
 
     /**
-     * @return The target of this interactable event.
+     * Returns the interaction target for this event.
+     * <p>
+     * The returned {@link Entity} is used by the {@link InteractionTask} to determine pathfinding, proximity checks,
+     * and completion conditions.
+     *
+     * @return The target entity of the interaction.
      */
     Entity target();
 
     /**
-     * The interaction distance.
+     * Returns the required interaction distance.
+     * <p>
+     * This represents the maximum allowed tile distance between the actor and the {@link #target()} before the
+     * interaction is considered valid.
+     * <p>
+     * The default value is {@code 1}, meaning the actor must stand adjacent to the target.
+     *
+     * @return The required interaction distance.
      */
     default int distance() {
         return 1;