常见问题

药水右键没有触发

按以下顺序检查：

1. 物品必须位于玩家主手，并且具有 DisplayName。
2. 物品显示名必须匹配药水配置的 name。
3. interact-type 必须为 all 或 hand。
4. 玩家数据必须已完成加载，否则药水不会执行。
5. 玩家不能处于该药水所属冷却组的冷却中。
6. condition 中的全部条件都必须通过。

name 支持以下匹配方式：

写法	匹配规则
测试药水	忽略大小写完整匹配
equals@测试药水	忽略大小写完整匹配
contain@测试	显示名包含指定文本

如果配置为 interact-type: key，主手右键不会触发药水。

右键药水时原物品操作被取消

当主手物品成功匹配到药水配置，并且该药水允许主手触发时，插件会取消本次右键事件，然后执行药水逻辑。

如果该物品还需要保留方块交互、食用或其他原版右键行为，不要让它的显示名匹配药水配置，或将该药水限制为：

interact-type: key

按键药水不生效

按以下顺序检查：

1. 已安装并正常启用 DragonCore 或 GermPlugin。
2. register-key 左侧填写的是正确按键名。
3. register-key 右侧填写的是正确槽位组件 ID。
4. 药水的 interact-type 为 all 或 key。
5. 对应槽位中的物品具有 DisplayName，并且能够匹配药水的 name。
6. 修改或新增键位后已经重启服务器。

DragonCore 通常使用按键名称，例如 X、Y、Z；GermPlugin 使用 KEY_X、KEY_Y、KEY_Z 一类的按键枚举名称。具体名称仍需以所用前置插件实际提供的按键为准。

同时安装 DragonCore 和 GermPlugin 后，部分按键失效

当前键位映射由两种按键监听共用。插件初始化 DragonCore 或 GermPlugin 键位时会清空已有映射，再写入当前前置的键位配置。

因此，同时启用 DragonCore 和 GermPlugin 时，可能只保留最后完成注册的一组键位映射。这属于当前实现限制，建议只使用其中一种按键方案。

interact-type 应该填写什么

值	主手右键	DragonCore／GermPlugin 按键
all	支持	支持
hand	支持	不支持
key	不支持	支持

未填写、留空或填写非法值时，插件会回退为 all，并在非法值的情况下输出控制台提示。

/lyys add 和 /lyys use 属于管理员调用入口，不受普通右键与按键触发方式限制。

药水物品没有被扣除

只有药水逻辑成功执行后，插件才会扣除物品。以下情况都会阻止扣除：

• 玩家仍在冷却中。
• 任意 condition 不满足。
• 药水 ID 不存在。
• 玩家冷却数据尚未加载。
• 冷却或表达式配置无法正常计算并导致执行异常。

当 take: true 时，每次成功使用会扣除一个物品。

当 take: false 时，插件会先尝试处理 take-lore 次数；未找到有效次数 lore 时，该物品不会被扣除，可无限使用。

次数 Lore 没有递减

次数扣除需要同时满足以下条件：

• take 为 false。
• 物品堆叠数量为 1。
• 物品具有 Lore。
• take-lore 包含 {value}。
• 实际 Lore 与 take-lore 左右两侧文本匹配。
• {value} 对应内容是非负整数字符串。
• 药水成功通过冷却和条件检查。

示例：

take: false
take-lore: '&a剩余使用次数：&6{value}'

物品 Lore 中对应内容需要与转换颜色后的模板一致，例如剩余次数为 5 时应能匹配“剩余使用次数：5”的完整结构。

次数减到 0 时，插件会销毁该物品。若物品数量大于 1，不会进入 Lore 次数扣除流程。

take: false 时为什么药水可以无限使用

这是正常行为。

当 take: false 且物品不满足次数 Lore 的处理条件时，插件仍会尝试使用药水，但不会修改或扣除物品。需要限制使用次数时，请确保物品数量为 1，并让物品 Lore 正确匹配 take-lore。

条件不满足，但玩家没有收到提示

条件只有在使用 <-> 配置失败消息时才会向玩家发送提示。

condition:
  - '%player_level% >= 5 <-> &c等级达到 5 级后才能使用'

如果只填写条件，失败时会直接停止使用，不发送消息：

condition:
  - '%player_level% >= 5'

权限条件同样支持失败消息：

condition:
  - 'permission:节点名称 <-> &c你没有使用权限'
  - 'nopermission:节点名称 <-> &c当前状态不能使用'

复杂条件表达式判断异常

条件表达式支持：

• 逻辑或 ||
• 逻辑与 &&
• 比较符 >=、<=、==、!=、>、<
• PlaceholderAPI 变量
• 数字与 +、-、*、/ 运算
• 单引号或双引号包裹的字符串相等判断

需要注意：

• 逻辑表达式按 || 和 && 拆分，不支持使用括号改变逻辑组合顺序。
• 数学计算只支持 +、-、*、/ 和数学括号。
• > 与 < 用于数值比较，不用于字符串比较。
• 字符串建议使用引号，并通过 == 或 != 比较。
• PlaceholderAPI 未正常返回数字时，数值比较可能失败。

PlaceholderAPI 变量没有被替换

确认服务器已安装并启用 PlaceholderAPI。LyPotion 仅在检测到 PlaceholderAPI 后注册 %lyys_*% 冷却变量，配置中的玩家变量也通过 PlaceholderAPI 解析。

还需要确认对应变量所属的扩展或插件已经安装。PlaceholderAPI 本体启用不代表所有第三方变量都可用。

如果 PlaceholderAPI 未启用，控制台会输出对应的前置未启动提示。

%lyys_all% 没有内容

%lyys_all% 只列出玩家当前尚未结束的冷却组，格式为多行“冷却组名称 + 剩余秒数”。以下情况会返回空内容：

• 玩家没有正在进行的冷却。
• 玩家冷却数据尚未加载。
• PlaceholderAPI 扩展没有成功注册。
• 请求变量时没有对应玩家上下文。

已经结束的冷却组不会显示在 %lyys_all% 中。

%lyys_冷却组% 返回空字符串或 0

返回值	含义
正整数	对应冷却组的剩余秒数
0	找到了该冷却组，但冷却已经结束
空字符串	没有该冷却组数据、玩家数据未加载，或没有玩家上下文

变量后半部分填写的是 cd-group，不是药水 ID。例如药水配置为：

cd-group: '红药水'

对应变量为 %lyys_红药水%。

两种药水为什么共享冷却

冷却以 cd-group 为单位保存，不以药水 ID 为单位保存。多个药水填写相同的 cd-group 时，会读取和覆盖同一条冷却记录。

需要独立冷却时，为每种药水配置不同的 cd-group。

冷却时间不正确

cd 支持固定数字、PlaceholderAPI 变量、Lore 变量和四则运算，最终结果单位为秒。

cd: '%player_level% * 1.5 + {v.力量}'

排查时检查：

1. PlaceholderAPI 变量是否返回有效数字。
2. {v.变量名} 是否与 lore-placeholder 的键完全一致。
3. Lore 中提取到的内容是否为数字。
4. 表达式是否只使用 +、-、*、/ 和括号。
5. 是否存在除以零、空表达式或无法识别的内容。

Lore 变量未匹配时通常会使用 0，但仅在物品具有 Lore 并进入对应变量解析流程时生成默认值。

如何清除某个玩家的冷却

管理员可使用：

/lyys clear 玩家 冷却组ID

该指令只能对在线玩家执行，并且只删除内存中的指定冷却组。冷却组不存在时会返回提示。

所有 /lyys 管理子命令均通过 OP 状态判断，没有单独声明的权限节点。

冷却没有跨服保存

跨服冷却必须启用 MySQL：

mysql:
  enable: true

同时必须满足以下条件：

1. 安装 LyMySQLCore。
2. LyMySQLCore 正常加载并触发玩家安全读取、保存事件。
3. LyPotion 成功连接 MySQL。
4. mysql.ip、mysql.port、mysql.databasename、mysql.username、mysql.password 正确。
5. 多个子服连接同一个数据库，并使用相同的 LyPotion 数据表。

只有安装 LyMySQLCore 且数据库成功连接后，MySQL 冷却与持续效果跨服保存功能才会生效。仅将 mysql.enable 改为 true，但未安装前置或连接失败，不能实现跨服同步。

不使用 MySQL 时会丢失冷却吗

不会。mysql.enable: false 时，插件使用本地 YAML 保存玩家数据，文件位于：

plugins/LyPotion/data/玩家UUID.yml

本地模式可以保存冷却组和仍在运行的持续效果，但不能在不同服务器之间共享数据。

本地数据保存采用临时文件替换与 .bak 备份。读取主文件失败时，插件会尝试从备份恢复；主文件和备份都损坏时会返回空数据，并在控制台输出警告。

开启 MySQL 后没有生成数据

先检查控制台是否出现数据库连接成功和数据表初始化成功的信息。

LyPotion 使用插件名称的小写形式作为表名，当前表名为 lypotion。玩家数据会在 LyMySQLCore 提供的安全保存事件触发时写入，而不是仅在执行 /lyys reload 后立即生成玩家记录。

如果数据库连接失败，检查：

• 数据库服务是否可访问。
• 数据库名称是否已经创建。
• 用户名和密码是否正确。
• 数据库账户是否有建表、查询、插入和更新权限。
• LyMySQLCore 是否正常启用。

玩家刚上线时药水无法使用

药水执行要求玩家的冷却数据已经放入运行时缓存。

本地 YAML 模式会在玩家加入后异步读取文件；MySQL 模式则等待 LyMySQLCore 的安全加载事件。玩家数据尚未加载完成时，药水调用会直接失败，物品也不会扣除。

如果该问题持续存在：

• 本地模式检查数据文件读取是否报错。
• MySQL 模式检查 LyMySQLCore 是否触发加载事件。
• 检查数据库连接和控制台读取日志。

通过插件 API 添加药水时会主动创建玩家冷却缓存，因此不受缓存不存在的限制。

效果上线后没有恢复

当前版本会保存仍在运行的持续效果快照，并在玩家上线后恢复。检查药水的 offline-pause：

配置	离线期间的处理
true	下线时暂停，重新上线后继续剩余效果
false	下线期间继续计算时间，上线时按剩余时间恢复；已经到期则不恢复

如果效果没有恢复，还需要检查：

• 玩家下线时数据是否成功保存。
• 本地数据文件或 MySQL 的 active-effect 数据是否存在。
• 效果依赖的属性、技能插件是否仍然正常启用。
• 持续时间是否已经结束。
• 效果类型是否属于可创建和恢复的快照类型。

可恢复类型包括属性效果、固定回血、百分比回血、饥饿值恢复、循环指令、SkillAPI 回蓝、SkillAPI 冷却缩减和 MythicMobs 技能。

offline-pause: true 时属性仍在下线后消失

属性型效果在玩家下线暂停时会先从玩家身上移除，避免离线期间残留属性来源；玩家重新上线恢复快照时会重新添加属性，并继续计算剩余持续时间。

如果上线后没有重新添加，检查对应属性插件是否正常启用，以及玩家数据是否成功保存和读取。

持续效果重复、没有结束或提前结束

检查效果的时间参数：

• stronger-effect 的 i 是每次触发间隔，单位为 tick。
• c 是总触发次数。
• 属性效果的 t 是持续时间，单位为 tick。
• 旧版 effect 的末尾持续参数按秒处理。
• 20 tick 通常约为 1 秒，实际时间会受服务器运行状态影响。

循环效果达到配置次数后会自动结束。玩家下线时，在线任务会被取消并转换为可保存快照；上线后是否继续取决于 offline-pause 和剩余时间。

stronger-effect 没有执行

先检查格式是否为：

stronger-effect:
  - '类型{参数1=值;参数2=值}'

常见原因包括：

• 缺少左花括号或右花括号。
• 参数之间没有使用分号分隔。
• 数值参数为空或表达式无法计算。
• 效果持续时间或次数配置无效。
• 对应效果需要的前置插件未安装。
• 类型名称不受支持。

格式错误、参数解析失败或类型错误时，插件会在控制台输出 [LyPotion] 提示。

属性效果没有生效

属性效果依赖对应的属性插件 API：

类型	所需接口
lycore	LyCoreAPI
ap	AttributeAPI
旧版 as	AttrAPI

缺少对应接口时，该类型无法正常添加属性。stronger-effect 的 lycore 和 ap 对部分缺失依赖情况会输出跳过或失败提示。

属性内容还必须符合目标属性插件接受的格式。LyPotion 负责生成并传递属性行，不会自动修正属性名称。

SkillAPI 回蓝或技能冷却缩减无效

skillapi-mana 和 skillapi-cd 依赖 SkillAPI。

检查：

• SkillAPI 是否已安装并正常启用。
• 玩家是否已经加载 SkillAPI 数据。
• 回蓝数值是否大于 0。
• 冷却缩减数值是否不为 0。
• i 和 c 是否配置为有效值。

新版 stronger-effect 的 skillapi-cd 未指定技能名称，会遍历玩家当前拥有的技能并减少冷却。旧版 effect 语法可以指定技能 ID。

MythicMobs 技能没有释放

mmskill 依赖兼容的 MythicMobs API。a 参数必须填写实际存在的技能 ID：

stronger-effect:
  - 'mmskill{i=20;c=1;a=技能ID}'

如果技能不存在、MythicMobs 未加载或所用版本 API 不兼容，技能不会正常释放，并可能在控制台出现任务执行异常。

当前实现直接通过 MythicMobs API 让玩家释放指定技能，没有执行示例文档中所述的控制台 mm skills cast 指令，也没有实际使用 level 参数。

stronger-effect 中的 icon 为什么没有显示

当前代码能够读取 icon 的 t、time、name、lore 和 id 参数，但读取后没有创建显示任务或发送界面内容。

因此，icon 目前没有实际显示效果，不应依赖该类型制作状态图标或动作栏提示。

指令效果没有执行

commands、weight-command 和命令型持续效果支持以下执行方式：

前缀	执行身份
[console]	控制台
[op]	玩家临时获得 OP 后执行，完成后恢复原状态
[player]	玩家
无前缀	玩家

检查指令内容时不要包含开头的 /，并确认 PlaceholderAPI 替换后的结果仍是有效指令。

[op] 会短暂修改玩家 OP 状态。不要将不受信任的文本或玩家可控制内容直接拼入高权限指令。

权重指令没有按预期执行

weight-command 中的每个分组会独立抽取一次。条目格式为：

权重#[执行身份]指令#[执行身份]另一条指令

例如：

weight-command:
  奖励组:
    - '30#[console]say 第一项'
    - '70#[player]say 第二项'

需要注意：

• 权重必须是可解析的整数。
• 每个条目至少需要包含一条指令。
• 同一个分组只抽中一个条目，但被抽中条目内可以包含多条指令。
• 配置了多个分组时，每个分组都会分别抽取并执行。
• 权重表示相对概率，不要求总和等于 100。

Lore 变量一直是 0

检查 lore-placeholder 的模板是否与物品实际 Lore 一致：

lore-placeholder:
  力量: '力量+<value>'

物品 Lore 中需要存在类似“力量+10”的文本。插件会截取左模板与右模板之间的内容，并将其解析为数字。

常见原因：

• 模板没有包含 <value>。
• 模板颜色与实际 Lore 不一致。
• Lore 中的数值包含百分号、单位或其他非数字字符。
• 左右模板在同一行中找不到。
• 物品没有 Lore。

无法解析的 Lore 数值会在控制台输出玩家名称和对应 Lore。未匹配到的已声明变量通常按 0 处理。

修改药水文件后没有生效

执行：

/lyys reload

重载会重新读取 config.yml，清空已经加载的药水定义，并递归扫描：

plugins/LyPotion/potion

目录及其子目录中的 .yml 文件。

检查事项：

• 指令执行者必须是 OP。
• 文件扩展名必须为 .yml。
• 药水必须定义在文件顶层节点。
• YAML 缩进必须正确。
• 文件不能与自动生成的 示例药水配置.yml 同名。

重载不会自动修正错误的 YAML 或表达式。

示例药水配置为什么被还原

每次重载时，插件都会强制重新写入：

plugins/LyPotion/potion/示例药水配置.yml

该文件只用于参考，并且加载药水时会被主动跳过。不要直接在示例文件中制作正式药水，应新建其他 .yml 文件或子目录保存配置。

/lyys add 没有效果

正确格式为：

/lyys add 玩家 药水ID

该指令要求：

• 执行者是 OP。
• 目标玩家在线。
• 药水 ID 已成功加载。
• 玩家满足药水条件。
• 玩家不在对应冷却中。

该指令直接按药水 ID执行，不检查物品显示名，也不扣除物品。它仍会写入冷却并执行条件、指令和持续效果。

/lyys use 没有效果

正确格式为：

/lyys use 玩家 槽位参数

支持的槽位参数：

格式	来源
0 至 35	玩家普通背包槽位
dc_槽位ID	DragonCore 缓存槽位
gp_槽位ID	GermPlugin 槽位
li_背包ID#槽位ID	LyInventory 槽位

该指令会读取指定槽位物品，再按 DisplayName 查找药水。物品为空、没有 DisplayName、名称不匹配或缺少对应前置时都不会触发。

/lyys use 会按照 take 和 take-lore 规则写回物品，但不会检查 interact-type。

原版物品冷却动画没有显示

可通过药水节点的 minecraft-cooldown-effect，或全局 minecraft-cooldown-group 为冷却组设置原版物品 ID。

当前实现通过整数物品 ID查找 Material。该方式依赖旧版 Bukkit 物品 ID，在较新版本中可能无法取得有效材质，甚至导致调用异常。

如果逻辑冷却正常，但原版冷却动画没有显示，优先检查服务器版本与所填整数 ID 是否兼容。该动画只影响客户端原版物品冷却显示，不会替代 LyPotion 自身的 cd-group 冷却判断。

调试日志没有输出

调试日志需要同时满足：

debug: true

并且触发药水快照的玩家是 OP。

开启后，控制台会输出快照的启动、恢复、暂停、结束、执行次数、间隔、剩余时间和参数等信息。普通玩家触发时不会输出这些详细调试日志。

玩家数据文件损坏后怎么办

本地 YAML 模式读取数据时会检查文件内容。主文件无法解析或包含 NUL 字符时，插件会：

1. 输出损坏警告。
2. 删除损坏的主文件。
3. 尝试读取同路径的 .bak 备份。
4. 备份可用时恢复主文件并继续加载。
5. 主文件和备份都不可用时返回空数据。

不要在服务器运行期间用不安全的方式覆盖玩家数据文件。手动编辑时使用 UTF-8 无 BOM，并保持 YAML 结构正确。

重载后已经运行的效果会立即变化吗

重载会重新构建药水定义，但已经启动的持续效果使用创建时生成的运行快照，不会因为配置文件被重载而自动改成新参数。

新配置只影响之后触发的药水。已经运行的效果会按原快照继续执行、结束或在下线时保存。

配置错误会阻止其他药水加载吗

插件会递归读取所有非示例 .yml 文件，并将每个顶层节点构造成药水定义。部分必填字段缺失、YAML 无法解析或构造过程中出现异常时，可能影响本次重载流程。

建议将不同类型的药水拆分到多个文件，并在修改后观察控制台中的“正在载入药水”与错误信息。不要把正式配置写入会被覆盖的示例文件。