[Feat] Ability pickup refund, depleted slot interactions, and chargeable ability system (#278)

* Feat: Ability system foundation — typed abilities, slot management, throwDirect API

- Add ABILITY_ID and ABILITY_SLOT PDC keys to KeyRegistry
- Uncomment and wire AbilityItemBuilder/AbilityItemReader (PDC tagging now live)
- Fix AbilitySlotItem: isSatisfied/setEquipped/buildPlaceholder now use ABILITY_SLOT_KEY
- AbilitySkill: replace single useType() with useTypes() Set<AbilityUseType> — STACK,
  DURABILITY, and COOLDOWN are now non-exclusive and combinable per ability
- AbilitySlotManager: tracks remainingUses and remainingDurability independently per
  slot; deplete fires when any finite resource hits zero
- AbilityStateRepository: stores both remaining_uses and remaining_durability columns;
  returns SlotState record; save/saveAll updated to match
- VisualProjectile: add displayScale field (default 1.0f) — determineOrientation() now
  respects it, enabling per-throw scale overrides without subclassing
- ThrowAction.throwDirect(): new API that spawns a ThrownItem and releases immediately
  without the onReady() windup loop — suitable for instant-release abilities
- KnifeThrowAbility: fires a diamond sword projectile at 0.5 scale via throwDirect;
  useTypes() = {STACK, COOLDOWN}, 3 max uses, 10-tick cooldown overlay

* Feat: Skill availability, slot state persistence, and ability casting

- Add SkillAvailability (AVAILABLE/DEPLETED/RELINQUISHED) tracked per player
- Add SkillSlotState record persisting uses, durability, and cooldown expiry
  per ability slot so cooldowns survive log-off cycles
- Persist slot states via new SkillStateRepository (player_skill_slot_state table)
- Migrate player_available_skills schema to v2 (adds availability column)
- Refactor AbilitySlotManager to delegate uses/durability tracking to
  PlayerSkillContainer instead of local fields
- Implement handleAbilityInput in SwordPlayer — LEFT tap / RIGHT_HOLD cast
  with canPerform, persistent cooldown guard, consumeUse, and cooldown write-back
- Remove registerActiveSkillSlot from InputRegistrar (replaced by handleAbilityInput)
- Fix AbilitySlotItem EMPTY/LOCKED restore to clear stale ability items on unequip
- Add TestAlpha/Beta/Gamma no-op abilities with colored chat feedback for testing
- Add skill system README

* Feat: Slot-index ability detection, throw prevention, and unequip fix

- Replace PDC tag lookup in handleAbilityInput with slot-index check via
  AbilitySlotManager.getActiveTypeForHeldSlot — more reliable than reading
  ITEM_TYPE_KEY from the held item which may be gunpowder or untagged
- Add boolean[] slotEnabled to AbilitySlotManager, synced after initialize,
  refresh, and deplete; drives getActiveTypeForHeldSlot
- Implement notHoldingAbilityItem() in SwordPlayer using getActiveTypeForHeldSlot;
  wired into canBeginThrow() which gates the Throw Ready input node
- Fix AbilitySlotItem EMPTY/LOCKED restore to clear stale ability items on unequip

* Feat: Knife throw pickup refund, ability re-cast fix, and CharacterMenu replenish button

- KnifeThrowAbility now extends ActivatableAbility (not ThrowableAbility) — throw is click-to-cast with no aim windup
- Tag knife projectile with ABILITY_ID_KEY so pickup can identify it
- InteractiveItemArbiter refunds one use to the original thrower on projectile pickup, regardless of who picks it up
- AbilitySlotManager.addUse() transitions depleted slots back to EQUIPPED when a use is returned
- ThrowAction.throwDirect resets attemptingThrow on completion, fixing ability re-cast lock
- CharacterMenu: dev replenish button (TODO: remove) resets both ability slots to full uses

* Feat: Ability pickup refund, depleted slot interactions, chargeable ability system, and IceSpellAbility

- Dash and grab now pick up ability projectiles when holding an equipped or depleted ability item
- Thrown ability projectile pickup (dash/grab/catch) refunds a use via AbilitySlotManager
- DEPLETED slot state now recognized as an ability slot for all pickup interactions
- handleAbilityInput only consumes LEFT inputs; RIGHT paths flow through the input tree
- Fixed input tree lock-out: ability slot always returns true to prevent tree advancement
- Added AbilityType.CHARGEABLE, ChargeableAbility abstract class, ChargeSession, ChargeAction
- Chargeable abilities hook into RIGHT (charge start) and RIGHT_HOLD (charge release) in the input tree
- IceSpellAbility: BLUE_ICE block, scale 0.25→3.0 over 3s, sine-wave bob, Y-axis rotation, releaseable at 0.5 scale
- addUse() calls updateInventory() to force client sync after projectile refund
- Non-ability items in an equipped slot are relocated gracefully on equip

* Add: Potion effect infinite duration constants, plugin dependency auto-download, and remove stale TODOs

Add PotionEffect.INFINITE_DURATION constant instead of magic number 99999999. Add downloadPlugins block to build.gradle for DisplayEntityUtils, PacketEvents, and ProtocolLib. Remove obsolete TODO about ability casting from different actions.

* Fix: Spotless

Author: Mere-Solace

src/main/java/btm/sword/config/Config.java

@@ -2605,7 +2605,7 @@ public static class Movement {
         ); }
 
         /** Delay for flat dash height boost in milliseconds. */
-        public static int FLAT_DASH_HEIGHT_BOOST_DELAY_MS = 100;
+        public static int FLAT_DASH_HEIGHT_BOOST_DELAY_MS = 75;
         static { register(
             "movement.flat_dash_height_boost_delay_ms",
             FLAT_DASH_HEIGHT_BOOST_DELAY_MS, Integer.class,

src/main/java/btm/sword/system/action/movement/Dash.java

@@ -18,6 +18,7 @@
 import btm.sword.system.control.SwordScheduler;
 import btm.sword.system.control.TimeArbiter;
 import btm.sword.system.entity.impl.Combatant;
+import btm.sword.system.entity.impl.SwordPlayer;
 import btm.sword.system.entity.umbral.UmbralBlade;
 import btm.sword.system.entity.umbral.statemachine.state.LodgedState;
 import btm.sword.system.entity.umbral.statemachine.state.WaitingState;
@@ -26,6 +27,7 @@
 import btm.sword.utility.display.ParticleWrapper;
 import btm.sword.utility.entity.EntityUtil;
 import btm.sword.utility.entity.HitboxUtil;
+import btm.sword.utility.math.VectorUtil;
 import btm.sword.utility.sound.SoundUtil;
 import btm.sword.utility.sound.SwordSoundType;
 
@@ -40,6 +42,7 @@ public class Dash {
     private DashType dashType;
     private double dashPower;
     private boolean holdingLink;
+    private boolean itemRetrieved;
 
     private static final Supplier<Double> MAX_STRAIGHT_DASH_DISTANCE = () -> Config.Movement.DASH_MAX_DISTANCE;
     private static final Supplier<Double> NORMAL_ITEM_RAY_WIDTH = () -> Config.Movement.DASH_RAY_HITBOX_RADIUS;
@@ -64,6 +67,7 @@ private enum DashType {
     }
 
     public void execute() {
+        itemRetrieved = false;
         dashType = DashType.NOTHING;
         onGround = EntityUtil.isOnGround(ex);
         holdingLink = executor.holdingSoulLink();
@@ -93,6 +97,13 @@ else if (holdingLink) {
                 }
             }
         }
+        // Holding an ability item — only pick up matching ability projectiles
+        else if (executor instanceof SwordPlayer sp && !sp.notHoldingAbilityItem()) {
+            targetedDisplay = raycastForAbilityProjectile();
+            if (targetedDisplay != null) {
+                dashType = flatDash ? DashType.FLAT_TO_ITEM : DashType.NORMAL_TO_ITEM;
+            }
+        }
 
         if (dashType == DashType.NOTHING || (targetedDisplay != null && isDashToItemImpeded())) {
             if (flatDash) {
@@ -168,6 +179,27 @@ public ItemDisplay raycastForNormalItem() {
         return itemDisplay;
     }
 
+    /**
+     * Raycasts for ability projectiles only (items tagged with {@code ABILITY_ID_KEY}).
+     * Used when the executor is holding an ability item and can only pick up matching projectiles.
+     */
+    public ItemDisplay raycastForAbilityProjectile() {
+        ItemDisplay itemDisplay = (ItemDisplay) HitboxUtil.ray(
+            executor.eyeLoc(),
+            executor.dir(),
+            MAX_STRAIGHT_DASH_DISTANCE.get(),
+            NORMAL_ITEM_RAY_WIDTH.get(),
+            entity -> entity instanceof ItemDisplay id &&
+                !entity.isDead() &&
+                InteractiveItemArbiter.checkIfInteractive(id) &&
+                InteractiveItemArbiter.isAbilityProjectile(id)
+        );
+
+        if (itemDisplay != null) Debug.movement("Ability Projectile Targeted.. itemDisplay=" + itemDisplay.getName());
+
+        return itemDisplay;
+    }
+
     private void dash() {
         dashPower = flatDash ? Config.Movement.DASH_BASE_POWER * Config.Movement.FLAT_DASH_POWER_MULTIPLIER : Config.Movement.DASH_BASE_POWER;
 
@@ -225,16 +257,27 @@ private void performFlatDashToItem(double distanceToItem) {
 
         boolean umbralHeightBoost = !holdingLink || targetedBlade.inState(WaitingState.class) || targetedBlade.inState(LodgedState.class);
 
+        final Vector exDir = executor.dir();
+
         if (umbralHeightBoost &&
             heightDiff <= Config.Movement.DASH_FLAT_HEIGHT_UPPER &&
             heightDiff > Config.Movement.DASH_FLAT_HEIGHT_LOWER) {
-            executor.setVelocity(executor.dir()
-                .add(Config.Direction.UP().multiply(Config.Movement.DASH_FLAT_ITEM_DASH_UPWARD_SCALER)));
+
+            Vector dashVelocity = exDir.add(
+                Config.Direction.UP().multiply(Config.Movement.DASH_FLAT_ITEM_DASH_UPWARD_SCALER)
+            );
+            executor.setVelocity(dashVelocity);
+        }
+
+        final Vector toItem = calcVectorToItem().normalize();
+        if (VectorUtil.isBroken(toItem)) return;
+
+        if (!itemRetrieved && distanceToItem > 3) { // TODO: COnfig
+            SwordScheduler.runBukkitTaskLater(() -> // Velocity applied after the initial height boost
+                    executor.setVelocity(toItem.multiply(Math.log(distanceToItem * Config.Movement.DASH_FLAT_ITEM_DASH_DISTANCE_SCALER))),
+                !umbralHeightBoost ? 0 : Config.Movement.FLAT_DASH_HEIGHT_BOOST_DELAY_MS, TimeUnit.MILLISECONDS
+            );
         }
-        SwordScheduler.runBukkitTaskLater(() ->
-                executor.setVelocity(executor.dir().multiply(Math.log(distanceToItem * Config.Movement.DASH_FLAT_ITEM_DASH_DISTANCE_SCALER))),
-            !umbralHeightBoost ? 0 : Config.Movement.FLAT_DASH_HEIGHT_BOOST_DELAY_MS, TimeUnit.MILLISECONDS
-        );
     }
 
     private void scheduleCheckForItemPickup() {
@@ -263,6 +306,7 @@ private void onItemRetrieval() {
         SoundUtil.playSound(ex, SwordSoundType.ENTITY_ENDER_DRAGON_FLAP, Config.Movement.DASH_FLAP_SOUND_VOLUME, Config.Movement.DASH_FLAP_SOUND_PITCH);
         SoundUtil.playSound(ex, SwordSoundType.ENTITY_PLAYER_ATTACK_SWEEP, Config.Movement.DASH_SWEEP_SOUND_VOLUME, Config.Movement.DASH_SWEEP_SOUND_PITCH);
         executor.setVelocity(calcPostRetrievalVector());
+        itemRetrieved = true;
         InteractiveItemArbiter.onGrab(targetedDisplay, executor); // here is where the display is taken care of
     }
 

src/main/java/btm/sword/system/action/skill/AbilityType.java

@@ -0,0 +1,22 @@
+package btm.sword.system.action.skill;
+
+/**
+ * Classifies the physical and interaction behavior of an ability.
+ *
+ * <ul>
+ *   <li>{@link #ACTIVATABLE} — Press to activate; has a cooldown; never consumed.</li>
+ *   <li>{@link #CHARGEABLE} — Hold right-click to charge; release to fire a scaled projectile.</li>
+ *   <li>{@link #THROWABLE} — Aimed-throw on hold; the physical item is consumed on each throw.</li>
+ *   <li>{@link #CONSUMABLE} — One-shot activation; the physical item is consumed on use.</li>
+ *   <li>{@link #PASSIVE} — Always active while the slot is equipped; no activation required.</li>
+ *   <li>{@link #QUEST} — Fully usable ability <em>and</em> surrenderable as a quest turn-in.</li>
+ * </ul>
+ */
+public enum AbilityType {
+    ACTIVATABLE,
+    CHARGEABLE,
+    THROWABLE,
+    CONSUMABLE,
+    PASSIVE,
+    QUEST
+}

src/main/java/btm/sword/system/action/skill/AbilityUseType.java

@@ -0,0 +1,22 @@
+package btm.sword.system.action.skill;
+
+/**
+ * Describes how an ability's uses are consumed when activated.
+ *
+ * <ul>
+ *   <li>{@link #STACK} — each use decrements the item's stack count; depleted at zero.</li>
+ *   <li>{@link #DURABILITY} — each use damages the item's durability bar; depleted when broken.</li>
+ *   <li>{@link #COOLDOWN} — the item is never consumed; activation only triggers a cooldown.</li>
+ * </ul>
+ */
+public enum AbilityUseType {
+
+    /** Item stack count decrements each use; depleted at zero. */
+    STACK,
+
+    /** Single item whose durability bar decreases; depleted when broken. */
+    DURABILITY,
+
+    /** Never consumed — activation only triggers a cooldown. */
+    COOLDOWN
+}