药水 LyPotion
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则 MySQL 数据加载、保存、跨服冷却共享和持续效果恢复不会生效。
LyPotion 是一款自定义药水与增益管理插件。服主可以通过 YAML 将带有指定 DisplayName 的普通物品定义为药水，并配置触发方式、使用条件、冷却组、物品扣除、Lore 使用次数、动态数值、即时指令和持续效果。
玩家可以通过主手右键、GermPlugin 按键、DragonCore 按键使用药水。管理员也可以通过 /lyys add 直接触发指定药水，或通过 /lyys use 从普通背包及受支持的自定义槽位读取物品并执行完整使用流程。
药水可以添加临时属性、恢复生命值、恢复饥饿值、执行指令、恢复 SkillAPI 魔力、缩短技能冷却或释放 MythicMobs 技能。持续效果会保存为运行快照，记录剩余时间、已执行次数和下次触发延迟，支持玩家下线暂停或离线自然流逝。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyPotion |
| 插件版本 | 1.0.7 |
| 作者 | 离渊 |
| 主命令 | /lyys |
| Java 版本 | Java 8 |
| 编译 API | Paper 1.16.5-R0.1-SNAPSHOT |
| 已确认服务端版本 | 项目仅确认使用 Paper 1.16.5 API 编译，其他版本未在项目文件中确认 |
| 配置目录 | plugins/LyPotion/ |
| 药水目录 | plugins/LyPotion/potion/ |
| 本地数据目录 | plugins/LyPotion/data/ |
| 声明的软依赖 | PlaceholderAPI、AttributePls、SX-Attribute、GermPlugin、DragonCore、LyCore |
版本兼容说明
原版物品冷却使用数字物品 ID 调用旧版 Bukkit API。跨版本使用前，需要确认目标服务端能够通过数字 ID 正确获取对应材质。
玩法与触发方式
插件会递归扫描 plugins/LyPotion/potion/ 及其子目录中的 .yml 文件。每个 YAML 顶层节点代表一个药水 ID，因此可以在一个文件中定义多个药水，也可以按类型拆分到不同目录。
药水通过物品 DisplayName 识别。没有 DisplayName 的物品不会被识别为药水。
| 名称写法 | 匹配规则 |
|---|---|
药水名称 | 忽略大小写，完整匹配 DisplayName |
contain@关键字 | DisplayName 包含指定关键字时匹配 |
equals@药水名称 | 忽略大小写，完整匹配指定名称 |
每个药水可以通过 interact-type 限制允许的触发方式。
| 配置值 | 允许的触发方式 |
|---|---|
all | 主手右键和按键均可触发，也是缺省值 |
hand | 仅允许主手右键触发 |
key | 仅允许 GermPlugin 或 DragonCore 按键触发 |
非法或空白的 interact-type 会回退为 all，并在控制台输出提示。
| 触发入口 | 说明 |
|---|---|
| 主手右键 | 右键空气或方块时检测主手物品，要求药水允许 hand 或 all |
| GermPlugin 按键 | 根据 register-key 获取萌芽槽位物品，要求药水允许 key 或 all |
| DragonCore 按键 | 根据 register-key 获取龙核缓存槽位物品，要求药水允许 key 或 all |
/lyys add | 按药水 ID直接触发，不检查物品名称，不扣除物品，不受 interact-type 限制 |
/lyys use | 读取指定槽位物品，通过 DisplayName 匹配药水并执行正常扣除流程，不受 interact-type 限制 |
成功定位药水后，插件依次检查玩家数据、冷却和使用条件。全部通过后才会写入冷却、设置可选的原版物品冷却、执行指令、发送成功消息并启动持续效果。正常物品触发只有在药水执行成功后才会扣除物品或减少 Lore 次数。
依赖与功能关系
plugin.yml 中的依赖均为软依赖，但对应功能需要相关插件及 API 实际存在。
| 插件或组件 | 用途 | 使用要求 |
|---|---|---|
PlaceholderAPI | 解析条件、冷却公式、指令和效果参数，并注册 %lyys_*% 冷却变量 | 使用变量、动态条件或动态计算时需要 |
LyMySQLCore | 提供安全的玩家数据加载与保存事件 | mysql.enable: true 时必须安装并成功连接数据库 |
LyCore | 执行 lycore 临时属性效果 | 使用 lycore 效果时需要 |
AttributePls / AttributePlus API | 执行 ap 临时属性效果 | 使用 ap 效果时需要 |
GermPlugin | 注册萌芽按键并读写萌芽槽位 | 使用萌芽按键或 gp_ 槽位时需要 |
DragonCore | 注册龙核按键并读写龙核缓存槽位 | 使用龙核按键或 dc_ 槽位时需要 |
SkillAPI | 恢复魔力或缩短技能冷却 | 使用 SkillAPI 效果时需要 |
MythicMobs | 释放 mmskill 配置的技能 | 使用 mmskill 效果时需要 |
| LyInventory | 让 /lyys use 读取和写回 li_背包ID#槽位ID | 使用离渊背包槽位时需要 |
SX-Attribute 虽然出现在软依赖列表中，并保留了不同版本的桥接类，但核心中的初始化代码处于停用状态。当前项目不能确认 SX-Attribute 属性效果已经启用。
主要功能
| 功能 | 说明 |
|---|---|
| 自定义药水 | 使用 YAML 将带 DisplayName 的普通物品定义为药水 |
| 多文件加载 | 递归读取 potion/ 及其子目录内的 .yml 文件 |
| 名称匹配 | 支持默认完整匹配、contain@ 包含匹配和 equals@ 完全匹配 |
| 触发限制 | 可设置全部触发、仅主手右键或仅按键触发 |
| 条件判断 | 支持权限、反向权限、数值比较、字符串比较、&& 和 ` |
| 动态计算 | 冷却与效果参数支持 PlaceholderAPI、Lore 数值和四则运算 |
| 冷却组 | 多个药水可以共用一个冷却组，防止通过更换同类物品绕过冷却 |
| 原版物品冷却 | 可在单个药水或全局冷却组映射中设置客户端物品冷却动画 |
| 物品扣除 | 药水成功使用后扣除一个物品，失败时不扣除 |
| Lore 使用次数 | take: false 时可以通过 Lore 保存剩余次数，归零后销毁物品 |
| 即时指令 | 成功使用后以玩家、临时 OP 或控制台身份执行指令 |
| 权重指令 | 每个权重组独立抽取一个条目，并执行条目中的全部指令 |
| 临时属性 | 支持 lycore、ap，持续结束、暂停或异常收尾时移除属性来源 |
| 周期回血 | 支持固定生命值和最大生命值比例回血 |
| 周期恢复 | 支持恢复饥饿值和 SkillAPI 魔力 |
| 技能处理 | 支持缩短 SkillAPI 技能冷却和释放 MythicMobs 技能 |
| 持续指令 | 按指定 tick 间隔和次数重复执行指令 |
| 效果快照 | 保存效果类型、执行进度、剩余时间、下次延迟和效果参数 |
| 离线暂停 | offline-pause: true 时下线暂停，上线后继续剩余效果 |
| 离线流逝 | offline-pause: false 时离线期间继续计时，过期效果不再恢复 |
| 本地存储 | MySQL 关闭时，将冷却和持续效果保存到玩家 UUID 对应的 YAML 文件 |
| 安全写入 | 本地数据使用临时文件和 .bak 备份替换，损坏时尝试从备份恢复 |
| MySQL 同步 | MySQL 模式保存冷却组和持续效果，可用于跨服共享及恢复 |
| 冷却变量 | 查询玩家全部有效冷却组或指定冷却组的剩余秒数 |
| 调试日志 | debug: true 时，为 OP 玩家输出快照启动、暂停、恢复、结束和异常信息 |
| 指令补全 | OP 可补全子命令、在线玩家、药水 ID、槽位格式和已有冷却组 |
| Java API | 提供触发药水、查询冷却数据和查询药水冷却组的方法 |
物品扣除规则
| 配置与物品状态 | 处理方式 |
|---|---|
take: true | 使用成功后将物品数量减一 |
take: false，物品数量为 1，Lore 匹配 take-lore | 使用成功后将 {value} 对应的整数减一 |
Lore 剩余次数减至 0 | 将物品数量减一，即销毁该物品 |
take: false，没有匹配到次数 Lore | 不扣除物品，药水仍可正常触发 |
物品堆叠数量不为 1 | 不执行 Lore 次数扣除 |
| 冷却或条件检查失败 | 不扣除物品，也不修改 Lore 次数 |
take-lore 的 {value} 只匹配非负整数。次数 Lore 的颜色和文本必须与配置转换后的内容一致。
冷却与数据存储
冷却以 cd-group 为单位记录，值为毫秒级绝对结束时间戳。多个药水使用相同冷却组时，会共同受到该组冷却限制。
| 存储模式 | 数据位置 | 说明 |
|---|---|---|
| 本地 YAML | plugins/LyPotion/data/玩家UUID.yml | 保存 cd-group 和 active-effect，适合单服使用 |
| MySQL | lypotion 表 | 使用玩家名作为数据键，在 data 字段保存序列化后的冷却和效果快照 |
本地 YAML 使用 UTF-8 无 BOM 写入。保存时先生成唯一临时文件，再把原主文件移动到 .bak，最后替换主文件。读取时如果主文件损坏、包含 NUL 字符或无法解析，插件会删除损坏主文件并尝试从 .bak 恢复。
MySQL 模式依赖 LyMySQLCore 提供的安全加载和保存事件。只填写数据库地址、安装 MySQL 驱动或成功创建连接池，不能替代该前置插件。
启用 MySQL 后，如果数据库连接尚未完成，玩家登录会被阻止，避免玩家在数据未加载时进入服务器。
持续效果
推荐使用 stronger-effect。旧版 effect 仍保留兼容处理，但示例配置已经将其标记为旧写法。
| 效果类型 | 作用 |
|---|---|
lycore | 通过 LyCore 添加临时属性来源 |
ap | 通过 AttributeAPI 添加临时属性 |
heal | 按间隔和次数恢复固定生命值 |
healpercent | 按最大生命值比例恢复生命值 |
food | 按间隔和次数恢复饥饿值 |
command | 按间隔和次数执行指令 |
skillapi-mana | 按间隔和次数恢复 SkillAPI 魔力 |
skillapi-cd | 按间隔和次数减少 SkillAPI 技能冷却；新版写法作用于玩家全部技能 |
mmskill | 按间隔和次数释放指定 MythicMobs 技能 |
stronger-effect 解析器仍识别 icon 类型及其 t、time、name、lore、id 参数，但当前代码没有创建显示任务，也没有输出可见图标。不要将其作为已完成的效果使用。
持续效果以快照运行。循环效果会记录触发间隔、总次数、已执行次数和下次延迟；属性效果会记录属性来源键、属性列表和剩余持续时间。玩家下线时，插件会取消在线 Bukkit 任务并保存尚未完成的快照。
指令
所有已确认的服务端管理指令都要求发送者为 OP。项目没有注册独立权限节点。
| 指令 | 说明 |
|---|---|
/lyys | 查看管理指令和自定义槽位格式 |
/lyys reload | 重载 config.yml；启用 MySQL 时重新创建连接池；清空并重新扫描全部药水配置 |
/lyys add [玩家] [药水ID] | 为在线玩家直接触发指定药水，不检查物品名称、不扣除物品，仍检查冷却和条件 |
/lyys use [玩家] [槽位ID] | 读取在线玩家指定槽位中的物品，按名称匹配药水并执行正常扣除流程 |
/lyys clear [玩家] [冷却组ID] | 清除在线玩家指定冷却组的冷却记录 |
/lyys use 槽位格式
| 格式 | 说明 |
|---|---|
0 至 35 | 普通玩家背包槽位 |
gp_槽位ID | GermPlugin 槽位标识 |
dc_槽位ID | DragonCore 缓存槽位 ID |
li_背包ID#槽位ID | LyInventory 背包 ID 与槽位 ID |
/lyys add、/lyys use 和 /lyys clear 只处理在线玩家。玩家数据尚未加载时，药水不会成功触发。
变量
安装并启用 PlaceholderAPI 后，插件会注册标识符 lyys。
| 变量 | 返回内容 |
|---|---|
%lyys_all% | 返回玩家全部尚未结束的冷却组，每行格式为“冷却组 剩余秒数” |
%lyys_冷却组ID% | 返回指定冷却组的剩余秒数 |
指定冷却组已经结束时返回 0；玩家数据尚未加载或冷却组不存在时返回空字符串。剩余秒数采用向上补一秒的显示方式。
药水条件、冷却表达式、即时指令和持续效果参数也可以使用 PlaceholderAPI 提供的玩家变量。具体语法见插件变量和药水配置。
Java API
核心完成加载后，主插件实例会设置 LyPotionAPI 实现。其他插件可以通过 LyPotion 主插件实例取得 API。
| 方法 | 说明 |
|---|---|
boolean addPotion(Player player, String potionId) | 尝试触发指定药水；自动初始化玩家冷却容器，成功触发返回 true |
Map<String, Long> getCooldownMap(Player player) | 返回玩家冷却组及结束时间戳的只读副本 |
long getCooldown(Player player, String cooldownGroupId) | 返回指定冷却组的结束时间戳，不存在时返回 0 |
String getCooldownGroupId(String potionId) | 返回指定药水的冷却组 ID，不存在时返回空字符串 |
getCooldownMap 和 getCooldown 返回毫秒级绝对结束时间，不是剩余秒数。调用方需要使用当前时间自行计算剩余时间。
addPotion 不会检查物品名称，也不会扣除物品，但会执行药水自身的冷却、条件、指令和效果逻辑。
运行机制
- 主插件启动后加载基础配置并等待核心完成加载。
- 核心加载后重载配置，初始化选定的数据存储方式，并设置 Java API 实现。
- 插件递归扫描
potion/目录，将每个 YAML 顶层节点加载为一个药水定义。 - 玩家上线时，从本地 YAML 或 MySQL 读取冷却组和未完成的持续效果快照。
- 玩家右键、按键或执行管理指令时，插件定位药水并读取物品 Lore 动态数值。
- 插件依次检查冷却、权限条件和表达式条件。
- 检查通过后写入冷却，设置可选的原版物品冷却，并执行即时指令、权重指令和成功消息。
- 持续效果转换为运行快照，记录执行间隔、次数、结束时间、效果参数和离线策略。
- 玩家下线时冻结快照、取消在线任务，并将冷却和未完成效果保存到当前数据源。
- 玩家再次上线时恢复仍然有效的快照；剩余时间已经归零的效果不会重新运行。
注意事项
potion/示例药水配置.yml会在每次重载时被强制覆盖，只用于参考，不要直接作为正式配置修改。/lyys reload会清空并重新构建全部药水定义。所有正式药水文件必须保持有效 YAML 格式。- 插件只读取扩展名为
.yml的药水文件，并跳过文件名为示例药水配置.yml的默认示例。 register-key只在核心加载时注册。修改或新增按键后需要重启服务器，单独执行/lyys reload不会重新注册键位。- GermPlugin 与 DragonCore 同时启用时，两套初始化逻辑都会清空键位映射。由于 DragonCore 在后执行，最终可能只保留后一次写入的映射。
- 原版物品冷却可由药水内的
minecraft-cooldown-effect设置；该值为0时，才会读取全局minecraft-cooldown-group.冷却组ID。 - 持续效果会创建 Bukkit 定时任务。配置大量高频效果时，应控制触发间隔、次数和同时在线人数。
- 数学计算器只处理数字、
+、-、*、/和括号。非法表达式可能导致条件或旧版效果执行异常；新版效果参数解析失败时会输出错误并使用默认值。 condition中的多个列表项必须全部通过。单条条件内部可以使用&&和||，但解析器不会按引号或括号保护逻辑分隔符。- 名称匹配依赖物品 DisplayName。普通名称比较和
equals@均忽略大小写，contain@使用区分大小写的包含判断。 - 权重指令的权重必须是可解析的整数，并且每个条目至少应包含一条指令。
take-lore次数扣除只在物品堆叠数量为1、物品具有 Lore 且文本符合模板时生效。- 开启
debug后，只会为触发快照的 OP 玩家输出详细生命周期日志。
页面索引
| 页面 | 内容 |
|---|---|
| 配置说明 | 全局消息、调试、MySQL、原版冷却和按键配置 |
| 药水配置 | 名称匹配、触发方式、条件、扣除、冷却、指令和动态数值 |
| 效果配置 | stronger-effect 与旧版 effect 的类型、参数和执行规则 |
| 插件变量 | PlaceholderAPI 冷却变量与配置内变量规则 |
| 常见问题 | 配置加载、依赖、存储、按键和效果排查 |
| 更新日志 | 版本与文档变更记录 |