常见问题

右键触发了两次

在 event-trigger-interval 中为 right 设置触发间隔，单位为毫秒：

yaml

event-trigger-interval:
  right: 200

服务端可能在一次右键操作中产生多个交互事件。设置间隔后，同一玩家的相同交互事件在间隔时间内不会重复检测。

如果使用蹲下右键事件，可以同时配置：

yaml

event-trigger-interval:
  right: 200
  shiftright: 200

触发间隔与节点冷却不是同一种机制：

功能	配置位置	作用
事件触发间隔	`event-trigger-interval`	限制同一玩家检测某种交互事件的频率
节点冷却	节点中的 `cd`、`cd-team`	限制节点成功触发后的再次使用时间

左键事件没有触发

普通左键事件使用 left，蹲下左键事件使用 shiftlet：

yaml

event:
  - 'left'
  - 'shiftlet'

当前代码实际发送的蹲下左键事件名是 shiftlet，不是默认配置注释中的 shiftleft。节点填写 shiftleft 时不会匹配蹲下左键事件。

但是，event-trigger-interval 中的间隔键仍然是 shiftleft：

yaml

event-trigger-interval:
  shiftleft: 200

按键没有触发

先确认对应的软前置已经成功加载：

按键来源	所需前置
萌芽按键	GermPlugin
龙核按键	DragonCore

按键还必须写入顶层配置的 register-keys。插件加载或重载时，会向已启用的按键插件尝试注册这些键位：

yaml

register-keys:
  - 'KEY_Z'

节点中的事件格式如下：

来源	事件格式	示例
GermPlugin	`GermPlugin#按键枚举名`	`GermPlugin#KEY_Z`
DragonCore	`DragonCore#按键名`	`DragonCore#Z`

GermPlugin 监听按键抬起事件。DragonCore 与 GermPlugin 使用的键名格式不同，不能直接混用 KEY_Z 和 Z。

修改配置后执行：

text

/lilc reload

如果控制台没有显示对应前置已启动或尝试注册键位的信息，应先检查前置插件是否成功加载。

节点没有触发

可以使用强制触发指令绕过节点的 event 检测：

text

/lilc use [玩家] [节点]

该指令要求执行者为管理员，目标玩家必须在线，节点名称必须与 config 或额外配置中的节点 ID 完全一致。

如果强制触发仍然失败，按以下顺序检查：

节点是否在启动或重载日志中显示为“注册检测节点”。
plugin-slot 是否能取得物品。
物品名称和 Lore 是否匹配。
玩家是否拥有 permission 中的全部权限。
玩家是否拥有 nopermission 中禁止拥有的权限。
condition 中的全部条件是否成立。
对应的 cd-team 是否仍在冷却。
chance 是否随机判定失败。

如果强制触发成功，通常说明节点内容基本有效，应继续检查事件名称、大小写、目标名称、实体类型或按键格式。

`plugin-slot` 留空后为什么不检测物品

这是正常行为。plugin-slot 不存在或为空列表时，节点会跳过物品检测，只根据权限、禁止权限、变量条件、冷却和几率进行判断：

yaml

plugin-slot: []

配置了多个槽位时，插件会按列表读取槽位。只要其中一个槽位中的物品同时通过名称和 Lore 检测，节点就会继续执行。

原版装备槽位没有匹配

检查槽位名称是否正确：

槽位	写法
主手	`Origin#MainHand`
副手	`Origin#OffHand`
头盔	`Origin#Helmet`
胸甲	`Origin#ChestPlate`
护腿	`Origin#Legging`
靴子	`Origin#Boots`
原版背包槽位	`Minecraft#槽位编号`

原版背包槽位编号使用 0 到 36。物品必须存在并带有物品元数据。如果节点配置了 name 或 lore，对应内容也必须匹配。

不同背包插件的槽位格式不能混用。使用 DragonCore、GermPlugin、APInventory、LyInventory、LyInventoryReload、YeeJewelry 或 PXRPG 槽位时，还要确认对应插件已经安装，并确认背包、类型和槽位标识真实存在。

名称或 Lore 明明存在却无法匹配

名称和 Lore 支持以下匹配方式：

写法	行为
`equals@内容`	完整匹配
`contain@内容`	包含关键词
不写前缀	默认按包含关键词处理

示例：

yaml

name: 'equals@烈焰之剑'
lore:
  - 'contain@火焰伤害'

lore 列表使用“任意一项匹配即可”的逻辑，不要求物品同时包含配置中的全部 Lore。

配置读取时会把颜色代码中的 & 转换为 §。物品名称或 Lore 带颜色时，配置中的颜色也必须与实际内容一致。

权限条件没有按预期工作

permission 中的权限必须全部拥有，节点才会继续触发：

yaml

permission:
  - 'example.permission.one'
  - 'example.permission.two'

nopermission 的逻辑相反。玩家只要拥有其中任意一个权限，节点就会匹配失败：

yaml

nopermission:
  - 'example.disabled'

不需要权限限制时，可以删除配置或使用空列表：

yaml

permission: []
nopermission: []

权限或变量条件失败时，可以通过 condition-or-permission-match-failed-message 向玩家发送提示。物品不匹配、节点冷却或几率失败不会使用这条消息。

变量条件报错或始终不成立

condition 会先解析 PlaceholderAPI 变量和 Lore 取值变量，再计算表达式。确认服务器已经安装并成功加载 PlaceholderAPI，同时确认使用的变量扩展能够正常返回结果。

支持的表达式包括：

类型	运算符或写法
数值比较	`>`、`<`、`>=`、`<=`
相等比较	`==`、`!=`
逻辑与	`&&`
逻辑或	`
数学计算	`+`、`-`、`*`、`/`、`()`
布尔值	`true`、`false`

字符串比较需要为两侧添加引号：

yaml

condition:
  - "'%player_world%' == 'world'"

没有比较运算符的表达式只有解析为 true 时才会成立。

Lore 取值一直是 0

检查 lore-placeholder 的格式。<value> 表示从 Lore 中截取并解析为数字的部分：

yaml

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

当物品 Lore 为 力量+15.5 时，可以在条件、冷却和指令中使用：

写法	结果
`{v.力量}`	默认按整数格式替换
`{v.力量~%.1f}`	保留一位小数

出现以下情况时，取值会保持为 0：

Lore 中没有找到 <value> 左侧的文本。
配置在 <value> 右侧填写了边界文本，但 Lore 中不存在该文本。
截取出的内容不是有效数字。
实际匹配到的物品没有 Lore。
变量名称与使用位置中的名称不一致。

尖括号占位符必须放在行内代码或 YAML 代码块中，例如 <value>，避免文档页面解析错误。

冷却变量一直是 0

检查节点是否配置了 cd-team，变量中的冷却组名必须与配置完全一致：

PlaceholderAPI 变量	返回内容
`%lilc_cd-冷却组%`	格式化后的剩余时间
`%lilc_cdint-冷却组%`	四舍五入后的整数秒

如果顶层配置中的 countdown-format 为 true，%lilc_cd-冷却组% 和消息中的 %time 使用 mm:ss 格式；关闭后返回保留一位小数的秒数。

节点未成功触发、冷却组名称不一致、玩家尚未产生该组冷却或冷却已经结束时，变量会返回 0。

冷却时间与填写的值不一致

cd 的单位是秒，并支持 PlaceholderAPI 变量、Lore 取值变量和四则运算：

yaml

cd: '10 + {v.力量} / 2'
cd-team: '技能冷却'

如果表达式使用 PlaceholderAPI 变量，应确保变量返回可参与计算的数字。无法组成有效数值表达式时，冷却计算会失败。

多个节点使用相同的 cd-team 时会共享同一组冷却。需要独立冷却时，应为节点设置不同的冷却组名称。

开启 MySQL 后玩家无法进入服务器

启用 MySQL 存储时，必须安装 LyMySQLCore，并确保数据库配置正确且连接成功。只有 LyMySQLCore 正常加载、数据库连接成功后，MySQL 冷却数据读取、保存和跨服共享功能才会生效。

本地冷却数据文件损坏怎么办

关闭 MySQL 时，插件按玩家 UUID 保存 YAML 冷却数据。保存流程会先写入临时文件，再保留旧主文件的 .bak 备份，并替换主文件。

读取时如果主文件无法解析或含有 NUL 字符，插件会删除损坏的主文件，并尝试读取 .bak 文件恢复。主文件和备份都无法使用时，该玩家会以空冷却数据继续加载。

控制台出现数据损坏或备份恢复提示时，应检查服务器是否发生过异常关机、磁盘写入中断或存储设备故障。

跨服后冷却被重置

本地 YAML 数据只保存在当前服务器，不提供跨服共享。

需要跨服共享冷却时，应在所有相关服务器上安装 LyMySQLCore，并让 LyItemLoreCommand 连接同一个可用数据库。数据库连接成功后，玩家加载时会读取数据库中的冷却组数据，离开时会保存当前冷却组数据。

如果部分服务器仍使用 mysql.enable: false，这些服务器不会与 MySQL 中的冷却数据同步。

扣除数量不对

take 和 take-all 的行为不同：

配置	行为
`take: true`	扣除匹配槽位中的 1 个物品
`take-all: true`	扣除匹配槽位中的全部物品
两项均为 `false`	不扣除物品

只有 take-all 会在执行前统计该槽位的物品数量，并把数量写入 {amount}。使用普通 take 时，{amount} 不会表示扣除的 1 个物品，而是保持为 0。

如果同时开启 take 和 take-all，代码会优先执行 take-all。

几率失败时仍然扣除了物品

这是 fail-take 的控制行为：

yaml

fail-take: true

fail-take: true 是默认值。插件会先执行物品扣除，再进行 chance 判定，因此几率失败时物品仍然会被扣除。

不希望失败时扣除物品，应改为：

yaml

fail-take: false

关闭后，插件会先进行几率判定，只有判定成功才进入冷却、扣除物品并执行指令。

权限、禁止权限、变量条件或冷却检测失败时，不会进入扣除流程。

`chance` 填写多少

chance 使用 0 到 1 的数值：

数值	含义
`1`	每次都成功
`0.5`	约 50% 成功
`0.1`	约 10% 成功
`0`	不会成功

删除该配置时默认值为 1。

指令没有执行

普通指令和权重指令都必须包含执行身份前缀：

前缀	执行方式
`[console]`	控制台执行
`[player]`	玩家身份执行
`[op]`	临时以管理员身份让玩家执行

没有以上前缀的指令不会被执行。

指令执行前会依次处理 {amount}、Lore 取值变量、PlaceholderAPI 变量和 %p 玩家名称。确认替换后的内容仍然是一条有效命令，并且命令开头通常不需要填写 /。

`message`、`fail-message` 等消息不显示

代码读取这些配置时使用的类型不同：

配置项	代码读取类型	支持替换内容
`message`	字符串列表	`%cd-team`、`%time`
`cd-message`	单个字符串	`%time`
`fail-message`	单个字符串	`%cd-team`
`condition-or-permission-match-failed-message`	单个字符串	无节点专用替换

建议按以下格式配置：

yaml

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

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

删除对应配置或填写空字符串时，不会发送该类消息。

权重指令没有按预期执行

每个 weight-command 分组会独立随机选择一项。列表项开头必须是整数权重，后面使用 # 分隔一条或多条指令：

yaml

weight-command:
  奖励组:
    - '30#[console]give %p stone 1'
    - '70#[console]give %p dirt 1#[player]say 获得奖励'

第二项被选中后，会按顺序执行 # 后面的两条指令。

常见问题包括：

权重不是整数。
权重与第一条指令之间缺少 #。
指令缺少 [console]、[player] 或 [op] 前缀。
指令参数中直接使用 #，导致内容被拆分成多条指令。

同一次事件触发了多个节点

默认情况下，插件会遍历所有节点。同一个事件可以让多个满足条件的节点成功触发。

需要阻止同组节点继续触发时，为这些节点设置相同且非空的 mutual-exclusion-group：

yaml

mutual-exclusion-group: '主动技能'

同一次事件遍历中，该互斥组内任意节点成功触发后，插件会跳过该组后续节点。互斥只影响当前这次事件检测，不等同于 cd-team 冷却组。

节点存放在并发映射中，不应依赖同一互斥组内节点的固定检查顺序。

指定方块事件没有触发

方块类型使用 Bukkit 的方块枚举名称：

yaml

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

可用格式为：

事件	格式
破坏指定方块	`break:方块枚举名`
放置指定方块	`place:方块枚举名`

方块名称通常为大写英文和下划线格式。当前版本中，帮助文本显示的方块调试分支判断条件存在错误，/lilc debug block 实际不会正常进入调试逻辑。应直接根据服务端版本对应的 Bukkit 方块类型名称配置。

指定实体名称事件没有触发

实体名称事件支持以下格式：

行为	事件格式
攻击指定名称目标	`attack:目标名称`
被指定名称目标攻击	`damaged:目标名称`
击杀指定名称目标	`kill:目标名称`
右键指定名称目标	`right:目标名称`
蹲下右键指定名称目标	`shiftright:目标名称`

实体存在自定义名称时，插件优先使用自定义名称；没有自定义名称时，会使用服务端取得的实体名称或实体类型名称。因此配置内容必须与实际事件生成的名称完全一致。

指定实体类型事件没有触发

实体类型使用 Bukkit 实体类型枚举名称，例如玩家为 PLAYER、猪为 PIG、僵尸为 ZOMBIE：

yaml

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

可用格式包括：

attack_type:实体类型
damaged_type:实体类型
kill_type:实体类型
right_type:实体类型
shiftright_type:实体类型

damaged_type 使用的是受伤实体本身的类型。当前监听只在受伤实体为玩家时执行，因此该事件实际生成的类型是 damaged_type:PLAYER，不能用它判断攻击者的实体类型。

`right:目标名称` 会不会同时触发普通右键事件

右键实体时，插件会生成 right:目标名称 和 right_type:实体类型。普通交互监听还可能生成 right 事件。

如果节点同时配置普通 right 和指定目标事件，或多个节点分别监听这些事件，同一次操作可能触发多个匹配节点。可以使用 cd、event-trigger-interval 或 mutual-exclusion-group 控制重复效果。

移动事件触发太频繁

move 只在玩家进入不同方块坐标时触发，不会因为同一方块内转头或小范围移动持续触发。

虽然可以配置：

yaml

event-trigger-interval:
  move: 500

但当前事件间隔检查只用于左键、右键、蹲下左键和蹲下右键交互。移动监听不会读取 move 间隔，因此该配置不能限制移动事件。

需要控制移动节点负载时，应减少监听 move 的节点数量，并通过节点条件、物品槽位或冷却限制实际执行。

`tick` 事件多久检测一次

插件会为所有在线玩家注册定时检测任务，初始延迟为 10 Tick，之后每 20 Tick 检测一次，通常约为每秒一次。服务器卡顿时，实际时间间隔可能延长。

event-trigger-interval 不会限制 tick。需要控制节点生效频率时，应配置 cd 和 cd-team。

PxSkillDrive 技能事件没有触发

只有服务器成功加载 PxSkillDrive 时，插件才会注册对应监听器。节点事件名为：

yaml

event:
  - 'psd_cast'

该事件在 PxSkillDrive 产生技能施放事件时触发。插件不会读取具体技能 ID，所有技能施放共用 psd_cast 事件名。

修改额外配置后没有生效

插件除了主 config.yml 外，还会递归读取插件 extra 目录下所有以 .yml 结尾的文件。修改后执行：

text

/lilc reload

额外文件的顶层结构仍需使用 config：

yaml

config:
  节点名称:
    event:
      - 'right'
    commands:
      - '[console]tell %p 触发成功'

如果不同文件使用相同节点 ID，后读取的节点会覆盖先读取的同名节点。为避免结果依赖文件遍历顺序，应保证所有配置文件中的节点 ID 唯一。

重载后玩家仍处于冷却

/lilc reload 会重新加载主配置、额外配置和事件触发间隔，但不会清空内存中的玩家冷却数据。

修改 cd-team 后，旧冷却仍会保留在原冷却组名称下，直到过期或玩家数据被重新处理。新的节点只会读取当前配置指定的冷却组。

触发交互后原操作被取消

普通左键、右键、蹲下左键或蹲下右键事件中，只要至少有一个节点成功触发，插件就会取消对应的 PlayerInteractEvent。

这可能阻止方块交互或物品原有的右键行为。几率失败、条件失败、冷却中或物品不匹配时，节点不算成功触发，插件不会因为该节点取消交互。

如果需要保留原版交互，应避免让该操作对应的节点成功触发，或改用不会取消交互的其他事件类型。

为什么启用 MySQL 后服务器会禁止玩家登录

插件在玩家登录前会检查自身是否完成加载。启用 MySQL 时，还会检查数据库连接是否成功：

状态	登录结果
插件尚未完成验证和初始化	禁止登录
`mysql.enable: true` 且数据库未连接	禁止登录
插件初始化完成且数据库连接成功，或未启用 MySQL	允许继续登录

因此，安装 LyMySQLCore 后仍然无法登录时，应先查看控制台中的数据库连接和初始化信息，而不是反复重载配置。

如何通过 API 触发节点

插件提供 LyItemLoreCommandAPI，核心方法为：

java

boolean tryTrigger(Player player, String id, String event);

参数含义如下：

参数	含义
`player`	尝试触发节点的玩家，不能为空
`id`	节点 ID，必须已注册
`event`	要匹配的事件名称；传入 `force` 时会绕过节点的 `event` 列表

节点不存在、玩家为 null、玩家冷却数据尚未初始化，或检测条件不满足时，方法返回 false。节点成功执行后返回 true。

常见问题 ​

右键触发了两次 ​

左键事件没有触发 ​

按键没有触发 ​

节点没有触发 ​

plugin-slot 留空后为什么不检测物品 ​

原版装备槽位没有匹配 ​

名称或 Lore 明明存在却无法匹配 ​

权限条件没有按预期工作 ​

变量条件报错或始终不成立 ​

Lore 取值一直是 0 ​

冷却变量一直是 0 ​

冷却时间与填写的值不一致 ​

开启 MySQL 后玩家无法进入服务器 ​

本地冷却数据文件损坏怎么办 ​

跨服后冷却被重置 ​

扣除数量不对 ​

几率失败时仍然扣除了物品 ​

chance 填写多少 ​

指令没有执行 ​

message、fail-message 等消息不显示 ​

权重指令没有按预期执行 ​

同一次事件触发了多个节点 ​

指定方块事件没有触发 ​

指定实体名称事件没有触发 ​

指定实体类型事件没有触发 ​

right:目标名称 会不会同时触发普通右键事件 ​

移动事件触发太频繁 ​

tick 事件多久检测一次 ​

PxSkillDrive 技能事件没有触发 ​

修改额外配置后没有生效 ​

重载后玩家仍处于冷却 ​

触发交互后原操作被取消 ​

为什么启用 MySQL 后服务器会禁止玩家登录 ​

如何通过 API 触发节点 ​

常见问题

右键触发了两次

左键事件没有触发

按键没有触发

节点没有触发

`plugin-slot` 留空后为什么不检测物品

原版装备槽位没有匹配

名称或 Lore 明明存在却无法匹配

权限条件没有按预期工作

变量条件报错或始终不成立

Lore 取值一直是 0

冷却变量一直是 0

冷却时间与填写的值不一致

开启 MySQL 后玩家无法进入服务器

本地冷却数据文件损坏怎么办

跨服后冷却被重置

扣除数量不对

几率失败时仍然扣除了物品

`chance` 填写多少

指令没有执行

`message`、`fail-message` 等消息不显示

权重指令没有按预期执行

同一次事件触发了多个节点

指定方块事件没有触发

指定实体名称事件没有触发

指定实体类型事件没有触发

`right:目标名称` 会不会同时触发普通右键事件

移动事件触发太频繁

`tick` 事件多久检测一次

PxSkillDrive 技能事件没有触发

修改额外配置后没有生效

重载后玩家仍处于冷却

触发交互后原操作被取消

为什么启用 MySQL 后服务器会禁止玩家登录

如何通过 API 触发节点