配置说明

LyPotion 的全局配置位于 plugins/LyPotion/config.yml，药水定义位于 plugins/LyPotion/potion/ 目录。

配置文件

文件 / 目录	用途
`config.yml`	调试开关、提示消息、原版物品冷却映射、数据存储和按键注册
`potion/*.yml`	定义药水匹配规则、触发方式、条件、冷却、效果和指令
`potion/示例药水配置.yml`	插件自动生成的参考文件，每次重载都会覆盖，不要直接作为正式配置修改
`data/<玩家 UUID>.yml`	未启用 MySQL 时保存玩家冷却和可恢复效果快照

插件会递归扫描 potion/ 下的所有 .yml 文件，因此可以创建子目录分类管理药水。名为 示例药水配置.yml 的文件不会加载为正式药水。

配置文件建议统一保存为 UTF-8 无 BOM，避免中文和颜色代码乱码。

`config.yml`

默认结构如下：

yaml

debug: false

message:
  cooldown: '&7无法使用, 冷却时间剩余 &6{time} &7秒!'

minecraft-cooldown-group: {}

mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

register-key:
  '键位': '槽位'

调试开关

yaml

debug: false

值	说明
`false`	不输出药水效果快照的调试详情
`true`	当触发快照的玩家是 OP 时，在控制台输出快照生命周期和运行数据

调试信息包括启动、暂停、结束、恢复、定时执行、离线取消、异常等阶段，还会输出药水 ID、效果类型、效果键、执行次数、间隔、剩余时间和效果参数。

该选项主要用于排查持续效果未执行、下线后未恢复或效果参数错误等问题。

冷却提示

yaml

message:
  cooldown: '&7无法使用, 冷却时间剩余 &6{time} &7秒!'

配置项	说明
`message.cooldown`	玩家在冷却期间再次使用同组药水时收到的消息
`{time}`	当前冷却组剩余的整数秒数

消息支持使用 & 颜色代码。

原版物品冷却映射

yaml

minecraft-cooldown-group:
  红药水: 264
  蓝药水: 322

minecraft-cooldown-group 用于将药水冷却组映射到原版物品数字 ID。药水进入冷却时，插件会调用原版物品冷却接口，为对应物品显示冷却动画。

键 / 值	说明
键	药水配置中的 `cd-group` 值
值	需要触发原版冷却动画的物品数字 ID

药水自身的 minecraft-cooldown-effect 不为 0 时，优先使用药水配置中的物品 ID；仅当该值为 0 时，才会读取这里的冷却组映射。

版本兼容

该功能使用数字物品 ID 查找原版材质。较新服务端版本可能无法识别旧版数字 ID。无法确认材质时，不要为该冷却组配置原版物品冷却。

数据存储

yaml

mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

配置项	默认值	说明
`mysql.enable`	`false`	是否使用 MySQL 保存玩家数据
`mysql.databasename`	`mc2`	数据库名称
`mysql.username`	`mc2`	数据库用户名
`mysql.password`	`mc1234`	数据库密码
`mysql.port`	`3306`	MySQL 端口
`mysql.ip`	`127.0.0.1`	MySQL 地址

本地 YAML 模式

当 mysql.enable 为 false 时，玩家数据保存在：

text

plugins/LyPotion/data/<玩家 UUID>.yml

本地文件包含：

cd-group：各冷却组的结束时间。
active-effect：玩家下线时尚未结束的可恢复效果快照。

本地数据采用异步读写。保存时会先写入临时文件，并保留 .bak 备份；主文件损坏时，插件会尝试从备份恢复。

MySQL 模式

MySQL 前置要求

启用 MySQL 存储前，必须安装 LyMySQLCore，并确认它已成功连接数据库。只有 LyPotion 自身显示数据库连接成功、且 LyMySQLCore 能正常触发玩家数据加载与保存事件后，MySQL 数据读取、保存、跨服同步和效果恢复才会生效。

当 mysql.enable 为 true 时，插件会：

根据 mysql 节点创建数据库连接池。
自动创建名为 lypotion 的数据表。
在玩家数据加载事件中读取冷却和可恢复效果。
在玩家数据保存事件中写回冷却和效果快照。

MySQL 模式用于跨服共享玩家药水冷却和可恢复效果。连接失败时，不能视为已经启用跨服存储；需要先修复数据库配置和前置连接。

修改 MySQL 配置后执行重载会重新创建连接池。

按键注册

yaml

register-key:
  'X': '药水槽位'
  'KEY_Y': '另一个槽位'

位置	说明
左侧键名	DragonCore 或 GermPlugin 的按键名称
右侧槽位	按键触发时读取物品的自定义槽位组件 ID

常见键名格式：

对接插件	键名格式
DragonCore	`X`、`Y`、`Z` 等直接键名
GermPlugin	`KEY_X`、`KEY_Y`、`KEY_Z` 等 `KeyType` 名称

只有服务器安装对应插件时，LyPotion 才会注册其按键监听。按键触发的药水还必须允许 key 触发方式。

修改或新增按键后需要重启服务器。普通重载只会重新读取药水配置，不会重新注册监听器和按键。

同时安装两个按键插件

当前实现会在注册 GermPlugin 和 DragonCore 时分别清空按键映射。两个插件同时启用时，后注册的 DragonCore 映射会覆盖先前写入的 GermPlugin 映射，不建议让两套按键系统共用同一份 register-key 配置。

药水配置文件

每个药水 YAML 可以定义一个或多个药水。顶层节点名称就是药水 ID：

yaml

'示例药水':
  name: '测试药水'
  interact-type: 'all'
  take: true
  take-lore: '&a右键使用药水, 药水将在&6{value}次&a后彻底销毁!'
  condition: []
  lore-placeholder: {}
  cd: '10.5'
  cd-group: '红药水'
  offline-pause: true
  minecraft-cooldown-effect: 0
  stronger-effect: []
  commands: []
  weight-command: {}
  use-message: '&7你触发了测试药水, 进入冷却&6{cd}&7秒!'

基础配置项

配置项	默认值	说明
顶层节点	无	药水 ID，用于指令、API 和内部数据定位
`name`	无	用于匹配物品 DisplayName
`interact-type`	`all`	允许的触发方式，可填 `all`、`hand` 或 `key`
`take`	`false`	使用成功后是否扣除一个物品
`take-lore`	空字符串	`take: false` 时用于记录剩余使用次数的 Lore 模板
`condition`	空列表	使用药水前必须全部满足的条件
`lore-placeholder`	空节点	从物品 Lore 中提取数字变量
`cd`	`0`	冷却秒数或数学表达式
`cd-group`	`default`	冷却组 ID，同组药水共享冷却
`offline-pause`	`true`	玩家下线时是否暂停尚未完成的持续效果
`minecraft-cooldown-effect`	`0`	当前药水使用的原版物品冷却数字 ID
`stronger-effect`	空列表	新版持续效果配置
`effect`	空列表	旧版持续效果配置，仅用于兼容旧配置
`commands`	空列表	使用成功后立即执行的指令
`weight-command`	空节点	按分组进行加权随机的指令
`use-message`	空字符串	使用成功后发送给玩家的消息

物品名称匹配

yaml

'精确匹配药水':
  name: '测试药水'

'完全匹配药水':
  name: 'equals@测试药水'

'包含匹配药水':
  name: 'contain@测试'

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

名称在加载时会把 & 转换为 Minecraft 颜色符号，因此可以直接配置带颜色的物品名。

触发方式

yaml

interact-type: 'all'

值	说明
`all`	允许主手右键和已注册按键触发
`hand`	仅允许主手右键触发
`key`	仅允许 DragonCore 或 GermPlugin 按键触发

留空或填写无法识别的值时，插件会回退为 all，并在控制台输出提示。

管理员通过指令或其他插件通过 API 直接触发药水时，不经过主手或按键触发方式检查。

物品扣除

每次扣除一个物品

yaml

take: true

只有药水成功通过冷却和条件检查后，插件才会扣除一个物品。冷却中或条件不满足时不会扣除。

Lore 使用次数

yaml

take: false
take-lore: '&a右键使用药水, 药水将在&6{value}次&a后彻底销毁!'

当 take 为 false、物品堆叠数量为 1，并且某行 Lore 符合 take-lore 模板时，插件会把 {value} 对应的整数减一。

剩余次数大于 0 时，插件更新该行 Lore。
剩余次数变为 0 时，插件移除物品。
Lore 未匹配或物品数量不为 1 时，物品不会被扣除，可重复触发药水。
只有药水实际使用成功后，次数才会减少。

{value} 前后的文本会参与完整匹配，次数只支持非负整数。

使用条件

yaml

condition:
  - '%player_level% > 5 <-> &c等级必须高于 5 级。'
  - '%player_health% >= 10'
  - 'permission:lypotion.example<->&c你没有使用权限。'
  - 'nopermission:lypotion.blocked<->&c你当前不能使用该药水。'

每条条件都必须通过。任意一条失败后，药水不会写入冷却，也不会执行效果或扣除物品。

条件类型

写法	说明
`permission:权限节点`	玩家拥有该权限时通过
`nopermission:权限节点`	玩家没有该权限时通过
`表达式`	使用 PlaceholderAPI 替换变量后计算表达式
`条件<->失败消息`	条件失败时向玩家发送指定消息

permission: 和 nopermission: 后的权限节点由当前药水配置自行定义，不是插件预设权限。

表达式语法

类型	支持内容
比较运算符	`>`、`>=`、`==`、`!=`、`<`、`<=`
逻辑运算符	`&&`、`
数学运算	`+`、`-`、`*`、`/`、圆括号
玩家变量	PlaceholderAPI 变量，例如 `%player_level%`
字符串比较	使用单引号或双引号包裹字符串，并配合 `==` 或 `!=`
布尔值	没有比较运算符时，只有 `true` 会通过

yaml

condition:
  - '%player_level% * 1.5 >= 15'
  - '"%player_world%" == "world"'
  - '%player_level% >= 10 && %player_health% > 5'
  - '%player_level% >= 30 || %player_health% <= 4'

逻辑表达式按照 || 分组，再在每组内计算 &&。配置错误或无法计算的数字表达式可能产生异常，应先确认 PlaceholderAPI 替换后的结果是有效数字或字符串。

Lore 数值变量

yaml

lore-placeholder:
  力量: '力量+<value>'
  品质: '&7品质: <value> 点'

插件会在物品 Lore 中查找模板左侧和右侧文本，并提取中间的数字。

例如以下 Lore：

text

力量+100
品质: 5 点

可以生成：

引用	值
`{v.力量}`	`100`
`{v.品质}`	`5`

这些变量可以用于：

cd
commands
stronger-effect
旧版 effect

未匹配到的已配置变量通常按 0 使用。提取到的文本必须能转换为数字，否则控制台会输出非法变量值提示。

VuePress 占位符

Lore 模板中的尖括号占位符必须写成 <value>，文档正文引用时请保持在行内代码或 YAML 代码块中。

冷却配置

yaml

cd: '%player_level% * 1.5'
cd-group: '红药水'
minecraft-cooldown-effect: 0

`cd`

cd 的单位为秒，支持整数、小数、PlaceholderAPI 变量、Lore 数值变量和数学运算。

yaml

cd: '10.5'

yaml

cd: '%player_level% * 1.5 + {v.品质}'

数学表达式支持 +、-、*、/ 和圆括号。插件会先替换 PlaceholderAPI 与 {v.变量名}，再计算最终冷却秒数。

`cd-group`

相同 cd-group 的药水共享冷却：

yaml

'小型红药水':
  cd: '5'
  cd-group: '红药水'

'大型红药水':
  cd: '15'
  cd-group: '红药水'

任意一个药水使用成功后，另一个药水也会进入相同冷却。

`minecraft-cooldown-effect`

yaml

minecraft-cooldown-effect: 264

该值不为 0 时，插件会直接使用此数字物品 ID 触发原版冷却动画，并覆盖 config.yml 中同组的 minecraft-cooldown-group 映射。

下线效果处理

yaml

offline-pause: true

offline-pause 控制玩家下线时尚未完成的持续效果如何保存。

值	行为
`true`	下线时暂停剩余执行进度，上线后继续；属性效果会在下线时移除，恢复时重新添加
`false`	下线期间按现实时间流逝；上线时已经过期的效果不会恢复，仍有剩余时间的效果会继续恢复

该选项作用于可恢复的属性、回血、百分比回血、饥饿恢复、循环指令、SkillAPI 和 MythicMobs 技能快照。快照会与冷却数据一起保存到本地 YAML 或 MySQL。

强化效果 `stronger-effect`

新版效果使用 类型{参数} 格式：

yaml

stronger-effect:
  - 'heal{i=20;c=5;a=10}'

参数使用分号分隔。

通用参数

参数	说明
`i`	每次触发的间隔，单位为 tick，最小值为 `1`
`c`	总触发次数，最小值为 `1`
`t`	属性效果或图标数据的持续时间，单位为 tick
`time`	`icon` 类型可读取的持续时间别名
`a`	效果的主要数值或文本参数
`m`	百分比回血比例，优先级高于 `a`
`cmd`	循环执行的指令
`level`	可识别参数，但当前 MythicMobs 调用不会使用该值

数值参数支持固定数字、PlaceholderAPI、{v.变量名} 和数学表达式。参数本身会交给数学解析器计算；属性值中的数学表达式可以使用尖括号包裹：

yaml

stronger-effect:
  - 'heal{i=20;c=5;a=%player_level%*2}'
  - 'lycore{t=200;攻击力=<{v.力量}*1.5+%player_level%>}'

效果类型

类型	主要参数	说明
`lycore`	`t`、属性行	通过 LyCore 添加临时属性来源，到期自动移除
`ap`	`t`、属性行	通过 AttributeAPI 添加临时属性，到期自动移除
`heal`	`i`、`c`、`a`	按固定数值回复生命
`healpercent`	`i`、`c`、`m`	按最大生命值比例回复生命，`0.1` 表示最大生命值的 10%
`food`	`i`、`c`、`a`	回复饥饿值
`command`	`i`、`c`、`cmd`	按间隔执行指令
`skillapi-mana`	`i`、`c`、`a`	回复 SkillAPI 魔力
`skillapi-cd`	`i`、`c`、`a`	每次减少玩家所有 SkillAPI 技能的冷却秒数
`mmskill`	`i`、`c`、`a`	让玩家释放指定 MythicMobs 技能
`icon`	`t` 或 `time`、`id`、`name`、`lore`	当前代码只解析参数，没有执行显示逻辑，配置后不会产生可见效果

属性效果

yaml

stronger-effect:
  - 'lycore{t=200;攻击力=5;生命力=<{v.力量}*1.5>}'
  - 'ap{t=200;攻击力=5}'

内容	说明
`t=200`	持续 200 tick
`攻击力=5`	生成属性行 `攻击力5`
`攻击力+5`	也可以直接写属性名和正负数值
`攻击力=<{v.力量}*1.5>`	先替换变量并计算尖括号中的表达式

属性行最终格式仍需符合对应属性插件的要求。缺少 LyCoreAPI 或 AttributeAPI 时，对应效果无法执行，控制台会输出提示。

固定回血

yaml

stronger-effect:
  - 'heal{i=20;c=5;a=10}'

每隔 20 tick 回复 10 点生命，共触发 5 次。回复结果不会超过玩家最大生命值。

百分比回血

yaml

stronger-effect:
  - 'healpercent{i=20;c=5;m=0.1}'

每隔 20 tick 回复最大生命值的 10%，共触发 5 次。

m 未填写时会读取 a。

饥饿值恢复

yaml

stronger-effect:
  - 'food{i=20;c=5;a=1}'

每隔 20 tick 回复 1 点饥饿值，共触发 5 次。最终饥饿值不会超过 20。

循环指令

yaml

stronger-effect:
  - 'command{i=20;c=5;cmd=[console]say %player_name% 触发了药水效果}'

指令会在创建效果时完成 PlaceholderAPI 和 Lore 数值变量替换，然后按照配置间隔执行。

SkillAPI 魔力

yaml

stronger-effect:
  - 'skillapi-mana{i=20;c=5;a=5}'

每隔 20 tick 回复 5 点 SkillAPI 魔力，共触发 5 次，回复后不会超过最大魔力。

SkillAPI 技能冷却

yaml

stronger-effect:
  - 'skillapi-cd{i=20;c=5;a=1}'

每隔 20 tick，将玩家当前全部 SkillAPI 技能的冷却减少 1 秒，共触发 5 次。a 为 0 时不会创建该效果。

MythicMobs 技能

yaml

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

按指定间隔让玩家释放 a 对应的 MythicMobs 技能。当前实现直接调用 MythicMobs API，虽然解析器允许填写 level，但技能等级参数不会被使用。

重复类型

当前配置解析会按效果类型归组。同一个药水中重复编写相同类型时，参数会合并到同一组，而不是创建多个完全独立的同类效果。需要多个不同阶段的同类效果时，不要依赖重复类型实现。

立即指令 `commands`

yaml

commands:
  - '[op]spawn'
  - '[console]say %player_name% 使用了药水'
  - '[player]me 使用了药水'

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

立即指令支持 PlaceholderAPI 和 {v.变量名}。指令只会在药水通过冷却与条件检查后执行。

权重指令 `weight-command`

yaml

weight-command:
  奖励组一:
    - '30#[console]give %player_name% apple 1'
    - '70#[player]say 没有获得物品'
  提示组:
    - '50#[console]tell %player_name% 提示一#[player]me 查看了提示一'
    - '50#[console]tell %player_name% 提示二'

格式为：

text

权重#第一条指令#第二条指令

处理规则：

每个权重组独立抽取一次。
插件计算组内所有条目的总权重。
抽中某条后，依次执行该条目中权重字段之后的所有指令。
指令支持 [op]、[console]、[player] 和 PlaceholderAPI。

每条配置至少需要包含权重和一条指令。权重必须是整数。

使用成功消息

yaml

use-message: '&7你触发了测试药水, 进入冷却&6{cd}&7秒!'

占位符	说明
`{cd}`	本次计算出的冷却秒数，保留一位小数

消息支持 & 颜色代码。配置为空字符串时不会发送成功消息。

旧版效果 `effect`

effect 是旧版配置格式，目前仍会执行，但新配置应优先使用 stronger-effect。

yaml

effect:
  - 'heal#10#5'
  - 'food#1#5'
  - 'command#[console]say %player_name% 触发了效果#5'

旧版效果类型

类型	格式	说明
`as`	`as#属性行#持续秒数`	通过 AttrAPI 添加临时属性
`ap`	`ap#属性行#持续秒数`	通过 AttributeAPI 添加临时属性
`lycore`	`lycore#属性行#持续秒数`	通过 LyCore 添加临时属性
`as-eval`	`as-eval#属性名~表达式#持续秒数`	计算表达式后通过 AttrAPI 添加属性
`ap-eval`	`ap-eval#属性名~表达式#持续秒数`	计算表达式后通过 AttributeAPI 添加属性
`heal`	`heal#每次回复值#执行次数`	每秒回复固定生命值
`proportion-heal`	`proportion-heal#百分比数值#执行次数`	每秒按最大生命值百分比回复，填写 `10` 表示 10%
`food`	`food#每次回复值#执行次数`	每秒回复饥饿值
`command`	`command#指令#执行次数`	每秒执行一次指令
`skillapi-mana`	`skillapi-mana#每次回复值#执行次数`	每秒回复 SkillAPI 魔力
`skillapi-cd`	`skillapi-cd#技能ID#每次减少秒数#执行次数`	每秒减少指定 SkillAPI 技能冷却

旧版效果中的持续时间和执行次数字段含义并不完全统一，维护时容易混淆。迁移配置时应根据对应类型改写为 stronger-effect 的 i、c、t 参数。

完整药水配置示例

yaml

'战斗恢复药水':
  name: 'contain@战斗恢复药水'
  interact-type: 'all'
  take: false
  take-lore: '&a剩余使用次数: &6{value}'
  condition:
    - '%player_level% >= 10 <-> &c等级达到 10 级后才能使用。'
    - 'permission:server.potion.heal<->&c你不能使用该药水。'
  lore-placeholder:
    回复量: '&7回复强度: &f<value>'
  cd: '10 + {v.回复量} / 10'
  cd-group: '战斗恢复'
  offline-pause: true
  minecraft-cooldown-effect: 0
  stronger-effect:
    - 'heal{i=20;c=5;a=<{v.回复量}*0.2>}'
    - 'food{i=40;c=2;a=1}'
  commands:
    - '[console]say %player_name% 使用了战斗恢复药水'
  weight-command:
    额外提示:
      - '50#[player]me 感觉状态良好'
      - '50#[player]me 感觉体力正在恢复'
  use-message: '&a药水使用成功，冷却时间为 &e{cd} &a秒。'

示例中的权限节点、物品名称、Lore 和指令均属于当前药水自行定义的内容，不是 LyPotion 内置权限或固定物品。

重载行为

执行插件重载后会：

重新读取 config.yml。
在启用 MySQL 时重新创建数据库连接。
清空已加载的药水定义。
递归扫描 potion/ 下的 .yml 文件并重新创建药水数据。
强制覆盖 potion/示例药水配置.yml。

重载不会重新注册 DragonCore 或 GermPlugin 按键，因此 register-key 修改后仍需重启服务器。

重载只会重建药水定义，不会主动清空当前在线玩家已经记录的冷却和正在运行的效果任务。修改正在生效的药水效果时，旧任务仍会按照创建时保存的参数继续运行。

配置注意事项

不要直接修改 potion/示例药水配置.yml，该文件会被重载覆盖。
药水 ID、冷却组 ID 和权重组名称可以使用中文，但必须保持引用一致。
name 是正式药水配置的必填项，缺失时药水加载会失败。
数学表达式仅支持 +、-、*、/ 和圆括号，不支持函数或幂运算。
stronger-effect 参数使用分号分隔，指令内容本身不应包含会被误认为参数分隔符的分号。
持续效果会为每个效果创建独立任务。单个药水配置过多高频效果会增加服务器任务数量。
依赖某个属性、技能或自定义界面插件的效果，只有对应插件和 API 可用时才能正常执行。
MySQL 模式必须同时保证 LyPotion 数据库连接成功，以及 LyMySQLCore 正常加载并连接数据库。

配置说明 ​

配置文件 ​

config.yml ​

调试开关 ​

冷却提示 ​

原版物品冷却映射 ​

数据存储 ​

本地 YAML 模式 ​

MySQL 模式 ​

按键注册 ​

药水配置文件 ​

基础配置项 ​

物品名称匹配 ​

触发方式 ​

物品扣除 ​

每次扣除一个物品 ​

Lore 使用次数 ​

使用条件 ​

条件类型 ​

表达式语法 ​

Lore 数值变量 ​

冷却配置 ​

cd ​

cd-group ​

minecraft-cooldown-effect ​

下线效果处理 ​

强化效果 stronger-effect ​

通用参数 ​

效果类型 ​

属性效果 ​

固定回血 ​

百分比回血 ​

饥饿值恢复 ​

循环指令 ​

SkillAPI 魔力 ​

SkillAPI 技能冷却 ​

MythicMobs 技能 ​

立即指令 commands ​

权重指令 weight-command ​

使用成功消息 ​

旧版效果 effect ​

旧版效果类型 ​

完整药水配置示例 ​

重载行为 ​

配置注意事项 ​

配置说明

配置文件

`config.yml`

调试开关

冷却提示

原版物品冷却映射

数据存储

本地 YAML 模式

MySQL 模式

按键注册

药水配置文件

基础配置项

物品名称匹配

触发方式

物品扣除

每次扣除一个物品

Lore 使用次数

使用条件

条件类型

表达式语法

Lore 数值变量

冷却配置

`cd`

`cd-group`

`minecraft-cooldown-effect`

下线效果处理

强化效果 `stronger-effect`

通用参数

效果类型

属性效果

固定回血

百分比回血

饥饿值恢复

循环指令

SkillAPI 魔力

SkillAPI 技能冷却

MythicMobs 技能

立即指令 `commands`

权重指令 `weight-command`

使用成功消息

旧版效果 `effect`

旧版效果类型

完整药水配置示例

重载行为

配置注意事项