物品指令 LyItemLoreCommand
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 冷却数据读取、保存和跨服共享不会生效；数据库未连接完成时，玩家也无法进入服务器。
LyItemLoreCommand 用于检测玩家指定槽位中的物品、名称、Lore、权限和变量条件，并在事件触发后执行指令。它可以用于制作右键道具、消耗型物品、装备被动、攻击触发、击杀奖励、方块交互、按键技能和带冷却的技能效果。
插件读取 config.yml 与 extra/ 目录下的 YAML 文件，将其中 config 节点注册为检测节点。节点匹配成功后，可以扣除物品、执行普通指令或权重指令、发送消息并写入冷却组。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyItemLoreCommand |
| 插件版本 | 1.2.3 |
| 作者 | Liyuan |
| 主命令 | /lilc |
| Java 编译目标 | Java 8 |
| 编译使用的 Paper API | 1.16.5-R0.1-SNAPSHOT |
| 配置文件 | config.yml、extra/ 目录下的 .yml 文件 |
| 插件入口 | Ly.itemlorecommand.origin.Start |
项目以 Java 8 为编译目标，并使用 Paper API 1.16.5-R0.1-SNAPSHOT 作为编译依赖。代码中保留了针对 1.7.10 服务端实体名称的处理分支，但实际运行效果仍取决于服务端版本、前置插件及运行环境。
玩法与功能
| 功能 | 说明 |
|---|---|
| 物品检测 | 检测原版背包、主手、副手、装备栏，以及多个第三方背包或装备槽位。 |
| 名称匹配 | 支持完整匹配、包含匹配；未填写前缀时默认使用包含匹配。 |
| Lore 匹配 | 支持完整匹配、包含匹配；配置的 Lore 条目中任意一项匹配即可。 |
| Lore 数值提取 | 从 Lore 文本中提取数字，生成 {v.变量名} 变量。 |
| 权限条件 | 支持必须拥有的权限和禁止拥有的权限。 |
| 变量条件 | 支持 PlaceholderAPI 变量、数值比较、字符串比较、逻辑表达式和数学表达式。 |
| 多种事件 | 支持移动、攻击、受伤、击杀、死亡、重生、潜行、疾跑、方块破坏、方块放置、消费、左右键交互和按键事件。 |
| 目标筛选 | 支持按目标名称或实体类型筛选攻击、受伤、击杀和右键实体事件。 |
| 触发概率 | 使用 0 到 1 的小数配置触发概率。 |
| 物品扣除 | 支持触发成功时扣除一个物品或全部物品，也可以配置概率失败时是否扣除。 |
| 普通指令 | 支持以控制台、玩家身份或临时管理员身份执行指令。 |
| 权重指令 | 每个权重组随机选择一条结果；一条结果可以包含多条指令。 |
| 冷却组 | 多个节点可以使用同一个冷却组，实现共享冷却。 |
| 互斥组 | 同一事件中，同一互斥组的节点触发后跳过后续同组节点。 |
| 事件间隔 | 可以为事件设置毫秒级触发间隔，减少重复触发和检测开销。 |
| 配置拆分 | extra/ 目录及其子目录下的所有 .yml 文件都会递归加载。 |
| 冷却持久化 | 支持使用玩家 UUID 对应的 YAML 文件保存，也支持通过 MySQL 保存玩家冷却组数据。 |
依赖与联动
必要前置
启用 MySQL 存储时，必须安装以下前置：
| 插件 | 用途 |
|---|---|
LyMySQLCore | 提供 MySQL 玩家数据加载与保存事件，并用于冷却数据的读取和保存。 |
只有在 LyMySQLCore 成功连接数据库后，MySQL 冷却读取、保存和跨服共享才会生效。
软依赖
plugin.yml 声明了以下软依赖：
| 插件 | 用途 |
|---|---|
GermPlugin | 注册萌芽按键，并读取萌芽槽位。 |
DragonCore | 注册龙核按键，并读取龙核槽位。 |
LyMySQLCore | 提供 MySQL 玩家数据加载与保存事件。 |
可选联动
代码中还检测或调用以下插件及系统：
| 插件或系统 | 用途 |
|---|---|
PlaceholderAPI | 解析变量条件、冷却表达式、指令变量，并注册 lilc 变量扩展。 |
PxSkillDrive | 监听技能释放事件，触发 psd_cast 节点。 |
APInventory | 读取和扣除梦星桐背包槽位物品。 |
LyInventory | 读取和扣除离渊背包槽位物品。 |
LyInventoryReload | 读取和扣除离渊背包重置版槽位物品。 |
YeeJewelry | 读取和扣除清守饰品背包槽位物品。 |
PXRPG | 读取和扣除 PXRPG 装备容器中的物品。 |
未安装对应的可选联动插件时，不应配置依赖该插件的槽位或事件。
指令
插件命令为 /lilc。除帮助显示外，管理指令要求发送者为服务器管理员，即代码中的 sender.isOp() 必须返回 true。项目未声明独立的命令权限节点。
| 指令 | 权限要求 | 说明 |
|---|---|---|
/lilc | 无额外权限节点 | 显示当前已注册的帮助文本；验证完成后会显示管理指令。 |
/lilc reload | 管理员 | 重载配置、重新注册检测节点、重新读取事件触发间隔，并重启每秒一次的 tick 检测任务。 |
/lilc use <玩家> <节点> | 管理员 | 让指定在线玩家尝试触发指定节点，使用 force 事件，跳过节点自身的 event 列表匹配。 |
/lilc debug block | 管理员且必须为玩家 | 按帮助文本用于切换方块调试模式；开启后右键方块会显示方块类型名称。当前代码中的参数判断同时要求第一个参数等于 debug 和 block，且要求参数数量为 3，因此该分支按当前 1.2.3 代码无法正常进入。 |
/lilc use 的玩家参数必须是在线玩家，节点参数必须是已注册的节点。即使使用 force，节点仍会检查物品、名称、Lore、权限、变量、概率和冷却。
触发事件
节点通过 event 配置事件名称。部分事件由一个基础事件和一个筛选事件共同触发，因此可以分别匹配目标名称或实体类型。
| 事件值 | 触发时机 |
|---|---|
move | 玩家跨越方块移动时。 |
attack | 玩家造成实体伤害时。 |
damaged | 玩家受到实体伤害时。 |
tick | 插件加载后每秒对在线玩家执行一次检测。 |
sprint | 玩家开始疾跑时。 |
sneak | 玩家开始潜行时。 |
death | 玩家死亡时。 |
respawn | 玩家重生时。 |
kill | 玩家击杀实体时。 |
break | 玩家破坏方块时。 |
place | 玩家放置方块时。 |
consume | 玩家完成食物或药水消费时。 |
left | 玩家进行任意左键交互时。 |
right | 玩家进行任意右键交互时。 |
shiftleft | 玩家潜行时左键交互。 |
shiftright | 玩家潜行时右键交互。 |
GermPlugin#<按键类型> | 萌芽按键抬起时；按键必须先在 register-keys 中注册。 |
DragonCore#<按键> | 龙核按键触发时；按键必须先在 register-keys 中注册。 |
psd_cast | PxSkillDrive 技能释放事件触发时。 |
break:<方块类型> | 破坏指定类型方块时，例如 break:STONE。 |
place:<方块类型> | 放置指定类型方块时，例如 place:STONE。 |
attack:<目标名称> | 攻击指定名称的目标时。 |
damaged:<目标名称> | 被指定名称的目标攻击时。 |
kill:<目标名称> | 击杀指定名称的目标时。 |
right:<目标名称> | 右键指定名称的实体时。 |
shiftright:<目标名称> | 潜行右键指定名称的实体时。 |
attack_type:<实体类型> | 攻击指定实体类型的目标时，例如 PLAYER、PIG、ZOMBIE。 |
damaged_type:<实体类型> | 被指定实体类型的目标攻击时。 |
kill_type:<实体类型> | 击杀指定实体类型的目标时。 |
right_type:<实体类型> | 右键指定实体类型的实体时。 |
shiftright_type:<实体类型> | 潜行右键指定实体类型的实体时。 |
目标名称优先使用实体自定义名称；没有自定义名称时，在 1.7.10 分支使用实体名称处理逻辑，其他版本使用实体类型名称。
槽位类型
检测节点的 plugin-slot 使用 类型#参数 或多段 类型#参数#参数 格式。槽位既用于匹配物品，也用于 take 和 take-all 扣除物品。
| 类型 | 格式 | 说明 |
|---|---|---|
DragonCore | DragonCore#槽位名 | 读取并扣除龙核槽位物品。 |
GermPlugin | GermPlugin#槽位名 | 读取并扣除萌芽槽位物品。 |
APInventory | APInventory#分页ID#槽位ID | 槽位 ID 使用数字，示例范围为 0 到 53。 |
LyInventory | LyInventory#背包ID#类型 | 读取和扣除离渊背包槽位物品。 |
LyInventoryReload | LyInventoryReload#背包ID#类型 | 读取和扣除离渊背包重置版槽位物品。 |
YeeJewelry | YeeJewelry#背包ID#槽位ID | 读取和扣除清守饰品背包槽位物品。 |
PXRPG | PXRPG#类型#背包ID#槽位 | 读取和扣除 PXRPG 装备容器槽位物品。 |
Origin#MainHand | Origin#MainHand | 原版主手。 |
Origin2#MainHand | Origin2#MainHand | 使用 Bukkit 旧版手部接口读取的主手。 |
Origin#OffHand | Origin#OffHand | 原版副手。 |
Origin#Helmet | Origin#Helmet | 原版头盔栏。 |
Origin#ChestPlate | Origin#ChestPlate | 原版胸甲栏。 |
Origin#Legging | Origin#Legging | 原版护腿栏。 |
Origin#Boots | Origin#Boots | 原版靴子栏。 |
Minecraft | Minecraft#槽位ID | 原版背包槽位，示例配置使用 0 到 36。 |
plugin-slot 留空时不会检测物品，也不会执行物品扣除。配置多个槽位时，插件会按列表检查，找到第一个名称和 Lore 均匹配的物品槽位后继续执行。
运行机制
- 插件启动后读取
config.yml。 - 插件保存并读取
extra/目录下的默认 YAML 文件。 - 插件递归读取
extra/目录及子目录中的所有.yml文件，并注册其中的config节点。 - Bukkit 事件、第三方按键事件或 API 调用触发检测流程。
- 插件依次检查事件、物品槽位、名称、Lore、权限、禁止权限和变量条件。
- 节点通过冷却和概率检查后，按配置扣除物品并执行指令。
- 插件发送成功、失败、条件不匹配或冷却中的消息。
- 冷却数据按配置保存到玩家 YAML 文件或 MySQL 数据库。
同一事件触发多个节点时，插件按已注册节点遍历。节点成功触发后，如果配置了 mutual-exclusion-group，后续同组节点会被跳过。
冷却与数据存储
冷却组
节点通过 cd-team 指定冷却组，通过 cd 指定冷却时间。多个节点使用相同的 cd-team 时，共享该冷却组的剩余时间。
cd 支持 PlaceholderAPI 变量、Lore 数值变量和四则运算表达式。未配置时默认冷却时间为 0。剩余时间消息中的 %time 会根据 countdown-format 转换为倒计时文本。
YAML 存储
当 mysql.enable 为 false 时，玩家冷却组数据保存到：
text
plugins/LyItemLoreCommand/data/<玩家UUID>.yml插件会在玩家进入时读取、退出时保存，并使用临时文件、备份文件和损坏恢复逻辑降低 YAML 写入中断造成的数据损坏风险。
MySQL 存储
当 mysql.enable 为 true 时，插件通过 LyMySQLCore 的玩家数据加载和保存事件读取、保存冷却组数据。数据库表名使用插件名，数据保存于 name 和 data 字段。
必须同时满足以下条件：
- 已安装
LyMySQLCore。 LyMySQLCore已成功连接数据库。config.yml中的 MySQL 连接信息正确。- 插件启动时数据库连接和数据表初始化成功。
MySQL 模式只保存玩家冷却组数据，不会替代 config.yml 或 extra/ 中的节点配置。
事件触发间隔
全局配置中的 event-trigger-interval 以毫秒为单位记录玩家上一次触发事件的时间。例如：
yaml
event-trigger-interval:
move: 500
right: 200上例表示同一玩家两次移动检测至少间隔 500 毫秒，右键交互至少间隔 200 毫秒。左右键、潜行左右键也会使用对应事件名称作为间隔键。
移动事件只在玩家跨越方块时触发。交互事件在通过间隔检查后才会尝试触发节点；如果节点成功触发，交互事件会被取消。
页面索引
| 页面 | 内容 |
|---|---|
| 配置说明 | 全局配置、数据库、按键注册、事件间隔和配置文件加载规则。 |
| 触发节点 | 槽位、物品匹配、事件、条件、指令、扣除、冷却和互斥组。 |
| 插件变量 | PlaceholderAPI 变量、冷却变量和 Lore 数值变量。 |
| 常见问题 | 配置加载、MySQL、冷却、事件和指令排查。 |
| 更新日志 | 插件或文档更新记录。 |
API
插件提供 LyItemLoreCommandAPI 接口，核心方法如下：
java
boolean tryTrigger(Player player, String id, String event);| 参数 | 说明 |
|---|---|
player | 尝试触发节点的玩家；传入 null 时返回 false。 |
id | 已注册的检测节点 ID。节点不存在时返回 false。 |
event | 本次触发事件名称；传入 force 时跳过节点 event 列表匹配。 |
方法返回 true 表示节点完成触发并执行后续流程，返回 false 表示玩家为空、节点不存在、事件不匹配、物品或条件不匹配、处于冷却中或概率判定失败。
注意事项
config下的每个节点 ID 应保持唯一；extra/中重复的节点 ID 会覆盖前面已注册的同名节点。extra/目录会递归读取所有.yml文件，不限于默认示例文件名。plugin-slot留空时不会检测物品，也不会执行物品扣除。take-all: true时，指令可以使用{amount}获取本次扣除前的物品数量。take-all和take同时为true时，实际扣除逻辑优先执行全部扣除。fail-take默认值为true。开启时，概率判定前会先扣除配置的物品；关闭时，概率判定成功后才扣除物品。condition-or-permission-match-failed-message只在权限或变量条件不匹配时发送；删除或留空时不发送消息。message、fail-message和cd-message删除或留空后，不发送对应消息。- 使用 PlaceholderAPI 变量时，必须确保 PlaceholderAPI 已加载并能够解析对应变量。
- 启用 MySQL 后，必须安装并成功连接
LyMySQLCore，否则相关冷却数据不会正常读取、保存或跨服共享。 - 当前
1.2.3版本的/lilc debug block参数判断存在代码条件冲突，帮助文本显示该指令，但实际无法正常进入调试分支。