配置说明

LyItemLoreCommand 读取插件目录中的 config.yml，并递归读取 extra/ 目录下的全部 .yml 文件。

config.yml 保存全局配置和主检测节点。
extra/ 下的 YAML 文件只需要配置 config 节点。
所有检测节点按节点 ID 注册。不同文件中的节点 ID 不应重复，后读取的同名节点会覆盖先前注册的节点。
修改配置后，可以使用 /lilc reload 重载配置。
修改按键注册或切换存储方式时，建议重启服务器。

配置文件

文件或目录	用途
`plugins/LyItemLoreCommand/config.yml`	全局配置、事件触发间隔和主检测节点
`plugins/LyItemLoreCommand/extra/*.yml`	额外检测节点，支持子目录
`plugins/LyItemLoreCommand/data/<玩家 UUID>.yml`	未启用 MySQL 时保存玩家冷却数据
`plugins/LyItemLoreCommand/data/<玩家 UUID>.yml.bak`	本地冷却数据的上一份稳定备份

插件重载时会执行以下操作：

重新读取 config.yml。
读取 config.yml 中的全部检测节点。
递归读取 extra/ 目录下扩展名为 .yml 的文件。
重新注册事件触发间隔。
重新启动每秒执行一次的 tick 检测任务。

全局配置

完整结构如下：

yaml

register-keys:
  - 'KEY_Z'

event-trigger-interval:
  move: 500
  right: 200

countdown-format: true

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

config: {}

配置项	类型	默认值	说明
`register-keys`	字符串列表	空列表	注册 DragonCore 或 GermPlugin 按键
`event-trigger-interval`	配置节点	未配置时不限制	限制指定事件的触发频率，单位为毫秒
`countdown-format`	布尔值	`false`	控制冷却时间的显示格式
`mysql.enable`	布尔值	`false`	是否使用 MySQL 保存玩家冷却数据
`mysql.databasename`	字符串	`mc2`	MySQL 数据库名称
`mysql.username`	字符串	`mc2`	MySQL 用户名
`mysql.password`	字符串	`mc1234`	MySQL 密码
`mysql.port`	整数	`3306`	MySQL 端口
`mysql.ip`	字符串	`127.0.0.1`	MySQL 地址
`config`	配置节点	无	检测节点集合

按键注册

yaml

register-keys:
  - 'KEY_Z'

插件只会尝试向已经加载的按键插件注册 register-keys 中的按键。

按键插件	配置值	检测节点事件
GermPlugin	`KEY_Z`	`GermPlugin#KEY_Z`
DragonCore	`Z`	`DragonCore#Z`

GermPlugin 的配置值会传入 KeyType.valueOf，必须填写 GermPlugin 支持的按键类型，例如 KEY_Z。DragonCore 使用 DragonCore 按键事件返回的按键名称，例如 Z。

按键注册在插件完成初始化时执行。修改 register-keys 后，建议重启服务器。

事件触发间隔

yaml

event-trigger-interval:
  move: 500
  right: 200

数值单位为毫秒，用于限制同一玩家相同事件进入检测流程的频率。没有配置间隔的事件不受此设置限制。

配置	作用
`move: 500`	玩家移动到另一个方块后，至少间隔 500 毫秒才再次处理 `move`
`right: 200`	普通右键交互至少间隔 200 毫秒才再次处理
`left: 200`	普通左键交互至少间隔 200 毫秒才再次处理
`shiftright: 200`	潜行右键交互至少间隔 200 毫秒才再次处理
`shiftleft: 200`	潜行左键交互至少间隔 200 毫秒才再次处理

右键交互可能同时触发方块交互和物品交互，建议为 right 设置间隔。

该设置与检测节点中的 cd 不同：

event-trigger-interval 只限制事件进入检测流程的频率。
cd 是检测节点成功触发后的玩家冷却。
cd 按 cd-team 分组保存到本地 YAML 或 MySQL。

潜行左键事件说明

代码中的潜行左键事件实际使用 shiftlet 作为检测事件键，配置节点需要按实际事件键填写：

yaml

event:
  - 'shiftlet'

event-trigger-interval 中的潜行左键间隔仍使用 shiftleft：

yaml

event-trigger-interval:
  shiftleft: 200

倒计时格式

yaml

countdown-format: true

值	格式	示例
`true`	`mm:ss`	`01:05`
`false`	保留一位小数的秒数	`65.0`

该设置影响：

成功消息中的 %time。
冷却消息中的 %time。
%lilc_cd-冷却组% 返回值。

%lilc_cdint-冷却组% 始终返回整数秒数，不受该设置影响。

数据存储

本地 YAML

当 mysql.enable 为 false 时，插件在玩家进入服务器时读取冷却数据，在玩家离开服务器时保存冷却数据：

text

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

保存时会先写入临时文件，再将原主文件移动为 .bak，最后替换主文件。主文件损坏时，插件会尝试从备份文件恢复。

本地数据结构如下：

yaml

cd-group:
  冷却组: 1750000000000

保存的数值是冷却结束时间戳，不需要手动修改。

MySQL

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确保数据库连接成功。LyMySQLCore 未加载、数据库连接失败或相关玩家数据事件没有正常触发时，MySQL 冷却读取、保存和跨服共享不会生效。

yaml

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

配置项	说明
`mysql.enable`	是否启用 MySQL 存储
`mysql.databasename`	数据库名称
`mysql.username`	数据库用户名
`mysql.password`	数据库密码
`mysql.port`	数据库端口
`mysql.ip`	数据库地址

插件会创建名为 LyItemLoreCommand 的数据表，并在表中保存玩家名称和冷却数据。多台服务器连接同一个数据库时，可以共享玩家的冷却结束时间。

启用 MySQL 后，插件会在玩家登录时检查数据库连接。MySQL 已启用但连接未成功时，玩家无法进入服务器，直到数据库连接恢复。

警告

不要在服务器运行期间反复切换本地 YAML 和 MySQL。切换 mysql.enable 后应重启服务器，避免两种存储中的冷却数据不一致。

检测节点结构

config 下的每个直接子节点都是一条独立检测规则：

yaml

config:
  示例节点:
    plugin-slot:
      - 'Origin#MainHand'
    name: 'equals@示例物品'
    lore:
      - 'contain@这是一条特殊的lore'
    event:
      - 'right'
    commands:
      - '[console]tell %p 你使用了道具'

节点 ID 可以使用中文。节点 ID 用于区分检测规则，也可以作为管理指令中的节点参数。

节点配置项

配置项	类型	默认值	说明
`plugin-slot`	字符串列表	空列表	要检测的物品槽位；为空时不检测物品
`name`	字符串	空字符串	物品显示名称匹配规则
`lore`	字符串列表	空列表	Lore 匹配规则，任意一项匹配即可
`lore-placeholder`	键值配置	空	从 Lore 中提取数值变量
`permission`	字符串列表	空列表	玩家必须拥有的全部权限
`nopermission`	字符串列表	空列表	玩家不能拥有的权限
`condition`	字符串列表	空列表	必须全部成立的变量条件
`chance`	数字	`1`	触发成功概率
`take`	布尔值	`false`	是否扣除匹配槽位中的 1 个物品
`take-all`	布尔值	`false`	是否扣除匹配槽位中的全部物品
`fail-take`	布尔值	`true`	几率判定失败时是否仍然扣除物品
`event`	字符串列表	空列表	可以触发该节点的事件
`commands`	字符串列表	空列表	成功触发后按顺序执行的固定指令
`weight-command`	分组配置	空	成功触发后按权重选择指令组
`message`	字符串列表	空列表	成功触发后发送给玩家的消息
`fail-message`	字符串	空字符串	几率判定失败时发送的消息
`condition-or-permission-match-failed-message`	字符串	空字符串	权限、禁用权限或条件不匹配时发送的消息
`cd-message`	字符串	空字符串	节点处于冷却时发送的消息
`cd`	字符串	`0`	冷却秒数，支持 PlaceholderAPI、Lore 数值变量和算术表达式
`cd-team`	字符串	`默认`	冷却组名称，同组节点共享冷却
`mutual-exclusion-group`	字符串	空字符串	同一次事件检测中的互斥组 ID

物品槽位

yaml

plugin-slot:
  - 'Origin#MainHand'
  - 'Minecraft#8'

插件按照 plugin-slot 列表顺序检查槽位。找到第一个同时满足名称和 Lore 条件的物品后，使用该槽位继续执行权限、条件、冷却、几率和扣除检测。

plugin-slot 为空或删除时，不判断物品。此时节点可以只依赖权限、PlaceholderAPI 条件和事件触发，但不会进行物品扣除或 Lore 数值提取。

原版槽位

格式	说明
`Origin#MainHand`	主手
`Origin#OffHand`	副手
`Origin#Helmet`	头盔
`Origin#ChestPlate`	胸甲
`Origin#Legging`	护腿
`Origin#Boots`	靴子
`Origin2#MainHand`	旧版本主手接口
`Minecraft#槽位编号`	玩家背包槽位，示例范围为 `0` 至 `36`

扩展插件槽位

对应插件必须已经安装并正常加载，否则无法读取对应槽位中的物品。

格式	说明	示例
`DragonCore#槽位名`	DragonCore 自定义槽位	`DragonCore#饰品槽`
`GermPlugin#槽位名`	GermPlugin 自定义槽位	`GermPlugin#饰品槽`
`APInventory#分页 ID#槽位编号`	APInventory 指定分页和槽位，槽位编号为数字	`APInventory#饰品#3`
`LyInventory#背包 ID#类型`	LyInventory 指定背包槽位	`LyInventory#饰品#项链`
`LyInventoryReload#背包 ID#类型`	LyInventory 重置版指定背包槽位	`LyInventoryReload#饰品#项链`
`YeeJewelry#背包 ID#槽位 ID`	YeeJewelry 饰品槽位	`YeeJewelry#饰品#项链`
`PXRPG#类型#背包 ID#槽位`	PXRPG 装备容器槽位	`PXRPG#类型#背包 ID#槽位`

名称与 Lore 匹配

物品名称

yaml

name: 'equals@示例物品'

写法	匹配方式
`equals@文本`	物品显示名称必须完全相同
`contain@文本`	物品显示名称必须包含文本
`文本`	默认按包含文本处理
空字符串或删除配置	不检测物品名称

名称中的 & 会转换为 Minecraft 颜色代码，例如：

yaml

name: 'equals@&6特殊物品'

Lore

yaml

lore:
  - 'equals@完整的一行 Lore'
  - 'contain@特殊关键词'

写法	匹配方式
`equals@文本`	任意一行 Lore 与文本完全相同
`contain@文本`	任意一行 Lore 包含文本
`文本`	默认按包含文本处理

lore 配置多项时，只要任意一项在物品 Lore 中匹配，检测就会通过，不要求全部匹配。空列表或删除配置时不检测 Lore。

Lore 中的 & 同样会转换为 Minecraft 颜色代码。

Lore 数值提取

lore-placeholder 可以从物品 Lore 中提取数字，并将结果用于条件、冷却和指令：

yaml

lore-placeholder:
  力量: '力量+<value>'
  暴击: '暴击：<value>%'

<value> 表示数字所在位置。插件会根据 <value> 前后的文本提取数值，提取结果必须能够转换为数字。没有提取到有效数字时，该变量按 0 处理。

使用位置	写法	说明
指令、冷却、条件	`{v.力量}`	默认按整数形式替换
指令、条件	`{v.力量~%.1f}`	使用 Java 数字格式保留一位小数
指令	`{v.暴击}`	使用名为 `暴击` 的 Lore 数值

示例：

yaml

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

condition:
  - '{v.力量} >= 10'

cd: '20-{v.力量}/10'

commands:
  - '[console]tell %p 当前力量为 {v.力量}'
  - '[console]tell %p 当前力量为 {v.力量~%.1f}'

权限与条件

必须拥有的权限

yaml

permission:
  - 'lilc.item.use'
  - 'lilc.item.special'

玩家必须拥有列表中的全部权限。列表为空或删除配置时不检查该项。

禁止拥有的权限

yaml

nopermission:
  - 'lilc.item.disabled'

玩家只要拥有 nopermission 中任意一项权限，节点就不会触发。

变量条件

yaml

condition:
  - '%player_level% > 0'
  - '%player_health% >= 10 && %player_health% <= 20'

条件检测前会解析 PlaceholderAPI 变量和 Lore 数值变量。列表中的条件必须全部成立。

类型	支持内容
数值比较	`>`、`<`、`>=`、`<=`、`==`、`!=`
数学运算	`+`、`-`、`*`、`/`、圆括号
逻辑运算	`&&`、`
字符串相等	使用单引号或双引号包裹两侧字符串，并使用 `==` 或 `!=`
布尔值	只有 `true` 会按成立处理

示例：

yaml

condition:
  - '%player_level% >= 10'
  - '%player_health% > 5 && %player_health% <= 20'
  - '"%player_world%" == "world"'
  - '({v.力量}+5)*2 >= 30'

权限、禁用权限或条件不匹配时，使用以下消息：

yaml

condition-or-permission-match-failed-message: '&7当前条件不满足'

触发几率与物品扣除

yaml

chance: 1
take: false
take-all: false
fail-take: true

配置	说明
`chance: 1`	每次几率判定都成功
`chance: 0.5`	约 50% 概率成功
`chance: 0`	不会成功
`take: true`	从匹配槽位扣除 1 个物品
`take-all: true`	扣除匹配槽位中的全部物品，并提供 `{amount}`
`fail-take: true`	几率判定前扣除物品，判定失败时也会消耗
`fail-take: false`	只有几率判定成功后才扣除物品

权限、条件和冷却检测失败时，不会进入物品扣除阶段。fail-take 只控制几率判定失败时是否扣除。

启用 take-all 后，{amount} 会替换为本次扣除的物品数量：

yaml

take-all: true
commands:
  - '[console]tell %p 本次使用了 {amount} 个物品'

没有执行整组扣除时，{amount} 为 0。

触发事件

yaml

event:
  - 'right'
  - 'sneak'

event 中任意事件与当前触发事件匹配时，插件会尝试触发节点。事件名称比较不区分大小写。

基础事件

事件	触发时机
`move`	玩家移动到另一个方块
`attack`	玩家对实体造成伤害
`damaged`	玩家受到实体伤害
`tick`	每秒检测一次
`sprint`	玩家开始疾跑
`sneak`	玩家开始潜行
`death`	玩家死亡
`respawn`	玩家重生
`kill`	玩家击杀实体
`break`	玩家破坏方块
`place`	玩家放置方块
`consume`	玩家完成食用或饮用物品
`left`	玩家普通左键交互
`right`	玩家普通右键交互
`shiftright`	玩家潜行右键交互
`shiftlet`	玩家潜行左键交互，代码当前使用该事件键
`psd_cast`	PxSkillDrive 技能释放

指定方块事件

方块 ID 使用 Bukkit 方块枚举名称，例如 STONE。

格式	说明
`break:方块 ID`	破坏指定方块
`place:方块 ID`	放置指定方块

示例：

yaml

event:
  - 'break:STONE'
  - 'place:DIAMOND_BLOCK'

指定实体名称事件

目标名称来自实体自定义名称；没有自定义名称时使用实体名称或实体类型名称。

格式	说明
`attack:目标名称`	攻击指定名称的实体
`damaged:目标名称`	被指定名称的实体攻击
`kill:目标名称`	击杀指定名称的实体
`right:目标名称`	右键指定名称的实体
`shiftright:目标名称`	潜行右键指定名称的实体

指定实体类型事件

实体类型使用 Bukkit 枚举名称，例如 PLAYER、PIG、ZOMBIE。

格式	说明
`attack_type:实体类型`	攻击指定类型的实体
`damaged_type:实体类型`	被指定类型的实体攻击
`kill_type:实体类型`	击杀指定类型的实体
`right_type:实体类型`	右键指定类型的实体
`shiftright_type:实体类型`	潜行右键指定类型的实体

示例：

yaml

event:
  - 'attack_type:ZOMBIE'
  - 'kill_type:PIG'

按键事件

格式	说明
`GermPlugin#按键`	玩家松开已注册的 GermPlugin 按键
`DragonCore#按键`	玩家按下已注册的 DragonCore 按键

对应按键必须先添加到全局配置的 register-keys。

强制触发

插件内部 API 可以使用 force 事件尝试触发指定节点。force 会跳过节点自身的 event 列表检查，但仍会继续执行物品、权限、条件、冷却和几率检测。

指令执行

yaml

commands:
  - '[op]say %p 使用了道具'
  - '[console]give %p diamond 1'
  - '[player]spawn'

前缀	执行身份
`[console]`	服务器控制台
`[player]`	玩家当前权限身份
`[op]`	临时以 OP 身份让玩家执行，执行后恢复原状态

每条指令都应明确填写执行前缀。未包含上述前缀的字符串不会执行对应的指令分支。

固定指令按列表顺序执行。执行前会处理以下内容：

PlaceholderAPI 变量。
%p，替换为玩家名称。
Lore 数值变量，例如 {v.力量}。
{amount}，替换为本次整组扣除的数量。

权重指令

weight-command 可以创建多个独立权重组。每个权重组随机选择一项，并执行该项中的全部指令。

yaml

weight-command:
  奖励组:
    - '30#[console]give %p diamond 1'
    - '50#[console]give %p gold_ingot 1'
    - '20#[console]give %p iron_ingot 1#[console]tell %p 获得额外提示'

每项格式如下：

text

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

部分	说明
第一个 `#` 前	整数权重
第一个 `#` 后	选中该项时执行的第一条指令
后续 `#`	在同一个权重结果中追加指令

每个权重组独立抽取一次。固定的 commands 和所有权重组都会执行，weight-command 不会替代 commands。

消息配置

yaml

message:
  - '&7冷却组 %cd-team 进入了 %time 秒冷却'

fail-message: '&7本次触发失败'
condition-or-permission-match-failed-message: '&7本次匹配失败'
cd-message: '&7还有 %time 秒才可以使用该物品'

配置项	类型	发送时机	可用内容
`message`	字符串列表	成功触发后	`%cd-team`、`%time`、颜色代码
`fail-message`	字符串	几率判定失败后	`%cd-team`、颜色代码
`condition-or-permission-match-failed-message`	字符串	权限、禁用权限或条件不匹配时	颜色代码
`cd-message`	字符串	节点仍在冷却时	`%time`、颜色代码

删除对应配置或设置为空字符串即可停止发送对应消息。

冷却配置

yaml

cd: '10'
cd-team: '冷却组'
cd-message: '&7还有 %time 秒才可以使用该物品'

`cd`

cd 的单位为秒。配置按字符串读取，可以使用 PlaceholderAPI 变量、Lore 数值变量和算术表达式：

yaml

cd: '10'

yaml

cd: '%player_level%*2'

yaml

cd: '30-{v.力量}/10'

支持以下运算符：

运算符	作用
`+`	加法
`-`	减法
`*`	乘法
`/`	除法
`()`	调整运算顺序

表达式在节点成功触发时计算，计算结果作为本次冷却秒数。

`cd-team`

cd-team 是冷却分组名称。多个节点使用相同的 cd-team 时，共享同一份玩家冷却数据。

yaml

config:
  技能一:
    cd: '10'
    cd-team: '公共技能冷却'

  技能二:
    cd: '20'
    cd-team: '公共技能冷却'

成功触发其中任意节点后，另一个节点也会进入同一冷却组的冷却。

互斥组

yaml

mutual-exclusion-group: '攻击触发组'

互斥组只影响同一次事件扫描：某个节点成功触发后，本次扫描中具有相同非空互斥组 ID 的后续节点不会继续尝试触发。

配置	作用范围
`mutual-exclusion-group`	阻止同一次事件中同组的多个节点连续成功
`cd-team`	保存玩家冷却，并影响后续触发

删除配置或设置为空字符串表示不加入互斥组。

`extra` 目录

额外配置文件只需要包含 config 节点，不需要重复全局配置：

yaml

config:
  右键使用物品:
    plugin-slot:
      - 'Origin#MainHand'
    name: ''
    lore:
      - 'contain@这是一条特殊的lore'
    take: true
    event:
      - 'right'
    commands:
      - '[console]tell %p 你使用了道具'

extra/ 支持子目录，插件会递归读取其中所有扩展名为 .yml 的文件。

以下全局配置只从主 config.yml 读取：

register-keys
event-trigger-interval
countdown-format
mysql

PlaceholderAPI 变量

PlaceholderAPI 已加载时，插件会注册变量标识符 lilc。

变量	返回值
`%lilc_cd-冷却组%`	指定冷却组的剩余时间，使用 `countdown-format` 的格式
`%lilc_cdint-冷却组%`	指定冷却组的剩余时间，始终返回整数秒

没有对应冷却组或冷却已结束时返回 0。

这些变量可以用于消息、指令和 cd、condition 等配置中的 PlaceholderAPI 解析位置。

完整节点示例

yaml

config:
  特殊物品:
    plugin-slot:
      - 'Origin#MainHand'
    name: 'equals@&6特殊物品'
    lore:
      - 'contain@&7力量+'
    lore-placeholder:
      力量: '&7力量+<value>'
    permission:
      - 'lilc.item.use'
    nopermission:
      - 'lilc.item.disabled'
    condition:
      - '%player_level% >= 10'
      - '{v.力量} > 0'
    chance: 1
    take: true
    take-all: false
    fail-take: true
    event:
      - 'right'
    commands:
      - '[console]tell %p 本次读取到的力量为 {v.力量}'
    weight-command:
      额外奖励:
        - '80#[console]tell %p 本次没有额外奖励'
        - '20#[console]give %p diamond 1#[console]tell %p 获得了额外奖励'
    message:
      - '&a使用成功，%cd-team 进入 %time 冷却'
    fail-message: '&c本次几率判定失败'
    condition-or-permission-match-failed-message: '&c权限或条件不满足'
    cd-message: '&c还需等待 %time'
    cd: '10+{v.力量}/10'
    cd-team: '特殊物品'
    mutual-exclusion-group: '右键物品组'

重载与生效规则

管理员执行以下指令可以重新读取配置：

text

/lilc reload

重载会重新读取主配置和 extra/ 目录中的检测节点，并重新启动 tick 检测任务。全局按键注册不会在重载过程中重新注册，修改 register-keys 后应重启服务器。

启用或关闭 MySQL 也建议通过重启完成，确保对应的数据监听器和数据库连接状态同步切换。

配置说明 ​

配置文件 ​

全局配置 ​

按键注册 ​

事件触发间隔 ​

潜行左键事件说明 ​

倒计时格式 ​

数据存储 ​

本地 YAML ​

MySQL ​

检测节点结构 ​

节点配置项 ​

物品槽位 ​

原版槽位 ​

扩展插件槽位 ​

名称与 Lore 匹配 ​

物品名称 ​

Lore ​

Lore 数值提取 ​

权限与条件 ​

必须拥有的权限 ​

禁止拥有的权限 ​

变量条件 ​

触发几率与物品扣除 ​

触发事件 ​

基础事件 ​

指定方块事件 ​

指定实体名称事件 ​

指定实体类型事件 ​

按键事件 ​

强制触发 ​

指令执行 ​

权重指令 ​

消息配置 ​

冷却配置 ​

cd ​

cd-team ​

互斥组 ​

extra 目录 ​

PlaceholderAPI 变量 ​

完整节点示例 ​

重载与生效规则 ​

配置说明

配置文件

全局配置

按键注册

事件触发间隔

潜行左键事件说明

倒计时格式

数据存储

本地 YAML

MySQL

检测节点结构

节点配置项

物品槽位

原版槽位

扩展插件槽位

名称与 Lore 匹配

物品名称

Lore

Lore 数值提取

权限与条件

必须拥有的权限

禁止拥有的权限

变量条件

触发几率与物品扣除

触发事件

基础事件

指定方块事件

指定实体名称事件

指定实体类型事件

按键事件

强制触发

指令执行

权重指令

消息配置

冷却配置

`cd`

`cd-team`

互斥组

`extra` 目录

PlaceholderAPI 变量

完整节点示例

重载与生效规则