Feat: Improve attack cooldown API

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -3521,8 +3521,31 @@ default net.kyori.adventure.text.event.HoverEvent<net.kyori.adventure.text.event
      */
     float getCooledAttackStrength(float adjustTicks);
 
+    /**
+     * Returns the number of ticks this player has been warming up for an attack.
+     * <p>
+     * This increments every tick, and is reset to zero when the
+     * player either swings their arm or swaps their main-hand item.
+     *
+     * @return the cooldown counter, which might be negative
+     * @since 1.21.7
+     */
+    long getAttackCooldownCounter();
+
+    /**
+     * Sets the number of ticks this player has been warming up for an attack.
+     * <p>
+     * See {@link #getAttackCooldownCounter()} for more details.
+     *
+     * @param ticks the number ticks to set the counter to
+     * @since 1.21.7
+     */
+    void setAttackCooldownCounter(long ticks);
+
     /**
      * Reset the cooldown counter to 0, effectively starting the cooldown period.
+     * <p>
+     * See {@link #getAttackCooldownCounter()} for more details.
      */
     void resetCooldown();
     // Paper end - attack cooldown API

paper-server/patches/sources/net/minecraft/world/entity/player/Player.java.patch

@@ -557,6 +557,23 @@
      }
 
      @Nullable
+@@ -1905,6 +_,16 @@
+         return Mth.clamp((this.attackStrengthTicker + adjustTicks) / this.getCurrentItemAttackStrengthDelay(), 0.0F, 1.0F);
+     }
+
++    // Paper start - attack cooldown API
++    public int getPaperAttackStrengthTicker() {
++        return this.attackStrengthTicker;
++    }
++
++    public void setPaperAttackStrengthTicker(int ticker) {
++        this.attackStrengthTicker = ticker;
++    }
++    // Paper end - attack cooldown API
++
+     public void resetAttackStrengthTicker() {
+         this.attackStrengthTicker = 0;
+     }
 @@ -1945,17 +_,32 @@
          return ImmutableList.of(Pose.STANDING, Pose.CROUCHING, Pose.SWIMMING);
      }

paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftPlayer.java

@@ -3233,6 +3233,24 @@ public float getCooledAttackStrength(float adjustTicks) {
         return getHandle().getAttackStrengthScale(adjustTicks);
     }
 
+    @Override
+    public long getAttackCooldownCounter() {
+        return getHandle().getPaperAttackStrengthTicker();
+    }
+
+    @Override
+    public void setAttackCooldownCounter(long ticks) {
+        // can be MIN_VALUE or MAX_VALUE as game logic already checks this in:
+        // #getAttackStrengthScale with a Mth.clamp call
+        // using a long for compatibility if nms changes to using one so that the
+        // API doesn't break.
+        // Keeping the number within the range of an int for predictability
+        // when used with Long.MAX_VALUE and Long.MIN_VALUE
+        ticks = Math.min(Integer.MAX_VALUE, ticks);
+        ticks = Math.max(Integer.MIN_VALUE, ticks);
+        getHandle().setPaperAttackStrengthTicker((int) ticks);
+    }
+
     @Override
     public void resetCooldown() {
         getHandle().resetAttackStrengthTicker();