Package cn.org.bukkit.craneattribute.core.utils

Object CooldownUtils

  • All Implemented Interfaces:
    
public class CooldownUtils

    实体多功能冷却管理工具。

    为每个 LivingEntity 提供基于字符串键（如技能ID）的独立冷却控制。 冷却时间以毫秒为单位，内部使用 System.currentTimeMillis 进行计时。

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      final static Unit setCd(LivingEntity entity, String key, Long ms) 设置指定实体的某个冷却项。若该冷却项已存在，则会被覆盖。
      final static Unit addCd(LivingEntity entity, String key, Long ms) 在现有冷却基础上延长指定时长。

      • 若当前无冷却，则等同于 setCd；

      • 若已有冷却，则在原过期时间上增加 ms 毫秒。
      final static Unit takeCd(LivingEntity entity, String key, Long ms) 从现有冷却中减少指定时长（即提前结束冷却）。

      • 若减少后冷却时间 ≤ 当前时间，则自动移除该冷却项；

      • 若当前无冷却，则此操作无效果。
      final static Boolean cd(LivingEntity entity, String key, Long ms) 尝试占用冷却：若不在冷却中，则设置冷却并返回 true；否则返回 false。常用于“尝试执行技能”场景。
      final static Boolean inCd(LivingEntity entity, String key) 判断指定实体的某个冷却项是否仍在生效中。
      final static Long getCd(LivingEntity entity, String key) 获取指定冷却项的剩余时间（毫秒）。
      final static Unit removeCd(LivingEntity entity, String key) 移除指定实体的某个冷却项。
      final static Unit resetCds(LivingEntity entity) 清空指定实体的所有冷却项。
      final static Unit resetGlobalCd() 清空所有实体的所有冷却项（全局重置）。⚠️ 谨慎使用，通常仅用于插件重载或调试。
      final static Long getCdExpireTime(LivingEntity entity, String key) 获取指定冷却项的过期时间戳（绝对时间，毫秒）。

      • 若存在冷却，返回其过期时间（System.currentTimeMillis() + 剩余时间）；

      • 若无冷却，返回 -1L。

      此值可用于精确同步、日志记录或跨系统通信。

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

    • Method Detail

      • setCd

         final static Unit setCd(LivingEntity entity, String key, Long ms)

        设置指定实体的某个冷却项。

        若该冷却项已存在，则会被覆盖。

        Parameters:
        entity - 目标实体
        key - 冷却标识符（如技能名、交互类型等）
        ms - 冷却持续时间（毫秒）

      • addCd

         final static Unit addCd(LivingEntity entity, String key, Long ms)

        在现有冷却基础上延长指定时长。

        • 若当前无冷却，则等同于 setCd；

        • 若已有冷却，则在原过期时间上增加 ms 毫秒。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        ms - 要增加的冷却时间（毫秒，可为负数，但建议用 takeCd 减少）

      • takeCd

         final static Unit takeCd(LivingEntity entity, String key, Long ms)

        从现有冷却中减少指定时长（即提前结束冷却）。

        • 若减少后冷却时间 ≤ 当前时间，则自动移除该冷却项；

        • 若当前无冷却，则此操作无效果。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        ms - 要减少的冷却时间（毫秒，应为正数）

      • cd

         final static Boolean cd(LivingEntity entity, String key, Long ms)

        尝试占用冷却：若不在冷却中，则设置冷却并返回 true；否则返回 false。

        常用于“尝试执行技能”场景。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        ms - 冷却持续时间（毫秒）
        Returns:

        true 表示成功占用（未在冷却），false 表示仍在冷却中

      • inCd

         final static Boolean inCd(LivingEntity entity, String key)

        判断指定实体的某个冷却项是否仍在生效中。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        Returns:

        true 表示仍在冷却，false 表示可使用

      • getCd

         final static Long getCd(LivingEntity entity, String key)

        获取指定冷却项的剩余时间（毫秒）。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        Returns:

        剩余毫秒数（≥0），若无冷却则返回 0

      • removeCd

         final static Unit removeCd(LivingEntity entity, String key)

        移除指定实体的某个冷却项。

        Parameters:
        entity - 目标实体
        key - 冷却标识符

      • resetCds

         final static Unit resetCds(LivingEntity entity)

        清空指定实体的所有冷却项。

        Parameters:
        entity - 目标实体

      • resetGlobalCd

         final static Unit resetGlobalCd()

        清空所有实体的所有冷却项（全局重置）。

        ⚠️ 谨慎使用，通常仅用于插件重载或调试。

      • getCdExpireTime

         final static Long getCdExpireTime(LivingEntity entity, String key)

        获取指定冷却项的过期时间戳（绝对时间，毫秒）。

        • 若存在冷却，返回其过期时间（System.currentTimeMillis() + 剩余时间）；

        • 若无冷却，返回 -1L。

        此值可用于精确同步、日志记录或跨系统通信。

        Parameters:
        entity - 目标实体
        key - 冷却标识符
        Returns:

        过期时间戳（毫秒），无冷却时返回 -1L