插件变量

LyPotion 通过 PlaceholderAPI 提供玩家冷却查询变量，可用于 HUD、计分板和其他支持 PlaceholderAPI 的文本组件。

服务器必须安装并启用 PlaceholderAPI。PlaceholderAPI 未启用时，LyPotion 不会注册这些变量。

变量格式

变量标识符为 lyys，完整格式如下：

%lyys_<参数>%

变量	返回内容
%lyys_all%	返回玩家当前所有尚未结束的冷却组及剩余秒数，每个冷却组占一行。
%lyys_<冷却组ID>%	返回指定冷却组的剩余秒数。冷却组 ID 对应药水配置中的 cd-group。

全部冷却组

使用 %lyys_all% 可以一次读取玩家当前所有尚未结束的冷却组。

每行返回格式如下：

冷却组ID 剩余秒数

例如，玩家同时存在两个未结束的冷却组时，可能返回：

红药水 8
蓝药水 3

该变量只输出结束时间仍晚于当前时间的冷却组。已经结束的冷却组不会出现在结果中。

返回内容为多行文本，并且每个冷却组记录后会附带换行符。使用该变量前，需要确认目标 HUD 或文本组件支持多行 PlaceholderAPI 返回值。

配置文件注释建议 HUD 以 1 秒为间隔刷新该变量。

指定冷却组

指定冷却组变量直接使用 cd-group 的值作为参数：

%lyys_<冷却组ID>%

药水配置如下：

cd-group: '红药水'

对应变量为：

%lyys_红药水%

状态	返回内容
冷却组存在且尚未结束	返回剩余秒数，例如 8。
冷却组存在但已经结束	返回 0。
冷却组不存在	返回空字符串。
玩家对象为空	返回空字符串。
玩家冷却数据尚未加载	返回空字符串。

剩余时间计算

变量返回的单位为秒。插件按照冷却结束时间与当前时间的毫秒差计算，并在整数除法结果上加 1：

(冷却结束时间 - 当前时间) / 1000 + 1

因此，只要冷却尚未结束，即使实际剩余时间不足 1 秒，变量仍会返回 1。

冷却组来源

变量查询的是玩家冷却数据中的冷却组，而不是药水 ID。多个药水配置使用相同的 cd-group 时，它们会共享同一份冷却，并通过同一个指定冷却组变量查询。

'初级红药水':
  cd: '10'
  cd-group: '红药水'

'高级红药水':
  cd: '20'
  cd-group: '红药水'

以上两个药水都通过下列变量查询冷却：

%lyys_红药水%

%lyys_all% 输出的也是冷却组 ID，不是药水 ID。

数据加载状态

玩家上线后，LyPotion 会先从本地 YAML 或 MySQL 读取冷却数据。读取完成前，玩家可能尚未出现在冷却数据映射中，此时所有 LyPotion 冷却变量都会返回空字符串。

使用本地存储时，冷却数据从 plugins/LyPotion/data/<玩家UUID>.yml 加载。启用 MySQL 时，必须安装 LyMySQLCore，并确保 LyPotion 已成功连接数据库；否则依赖数据库加载的冷却与效果数据不会正常生效。

PlaceholderAPI 在配置中的用途

除 LyPotion 注册的 %lyys_*% 查询变量外，药水配置中的部分内容还会调用 PlaceholderAPI 解析其他插件提供的变量。

配置位置	PlaceholderAPI 用途
condition	在条件比较前替换玩家变量。
cd	在计算冷却秒数前替换变量。
commands	指令执行前替换变量。
weight-command	抽取指令后替换变量。
stronger-effect	解析数值、属性、指令或技能参数时替换变量。

例如，冷却时间可以引用玩家等级变量：

cd: '%player_level% * 1.5'

这类变量由 PlaceholderAPI 及其对应扩展提供，不属于 LyPotion 自身注册的 lyys 变量。