事件动作

方块事件写在 block/*.yml 中对应方块配置的 events 节点下。每个事件使用独立事件 ID，并按配置中的先后顺序检测。

事件可以根据点击方式、权限、PlaceholderAPI 表达式、随机概率和指定槽位物品进行判断，再执行成功或失败动作。

基本结构

yaml

方块ID:
  events:
    事件ID:
      type: "right"
      cd-group: "default"
      cd-message: "&7该事件还需等待 {time} 秒。"
      condition:
        - "permission:{example.use}"
      true-action:
        - "message:&a条件成立。"
      false-action:
        - "message:&c条件不成立。"

配置项	默认值	说明
`type`	空字符串	事件触发类型。未填写或类型错误时不会匹配点击、右键或破坏事件。
`cd-group`	`default`	事件使用的冷却组，同时检查玩家个人冷却和全服冷却。
`cd-message`	空字符串	事件处于冷却时发送的提示。留空时不发送消息。
`condition`	空列表	事件条件。所有条件都通过时执行 `true-action`。
`true-action`	空列表	条件全部成立时执行的动作。
`false-action`	空列表	任意条件不成立时执行的动作。

没有配置 condition 时，条件结果默认为成立，直接执行 true-action。

事件类型

类型	触发时机	可取消的 Bukkit 事件
`left`	玩家左键点击已记录的方块。	玩家交互事件
`right`	玩家右键点击已记录的方块。	玩家交互事件
`break`	玩家尝试破坏已记录的方块。	方块破坏事件

事件类型区分大小写，应填写小写的 left、right 或 break。

破坏事件行为

插件识别到已记录方块后，会关闭该次破坏事件的原版掉落。需要返还方块本体时，应在 break 事件中主动使用 drop-origin。

如果破坏事件最终没有被 cancel 取消，方块保存数据会在事件结束时删除。即使没有配置任何 break 事件，正常破坏后也会删除保存数据，并且不会产生原版掉落。

启用方块配置中的 anti-break-by-non-owner 后，非放置者不能破坏方块，但 OP 不受该限制。所有者检查发生在 break 事件动作之前。

条件列表

同一事件中的条件按照配置顺序逐条检测。所有条件都成立时执行 true-action；任意条件不成立时立即停止后续条件检测，并执行 false-action。

条件格式	说明
`papi:{表达式}`	替换 PlaceholderAPI 变量后计算表达式。
`permission:{权限节点}`	玩家拥有指定权限时成立。
`nopermission:{权限节点}`	玩家没有指定权限时成立。
`roll:{概率}`	按概率随机判断，填写范围为 `0` 到 `1`。
`check_equals_name:{槽位#文本}`	指定槽位物品名称与文本完整相同时成立。
`check_contain_name:{槽位#文本}`	指定槽位物品名称包含文本时成立。
`check_equals_lore:{槽位#文本}`	指定槽位 Lore 中存在完全相同的一整行时成立。
`check_contain_lore:{槽位#文本}`	示例配置中提供了该写法，但当前代码没有正确识别，不应依赖。

条件中的 & 会在物品名称和 Lore 检查时转换为 Minecraft 颜色符号。名称与 Lore 的比较包含颜色代码。

PlaceholderAPI 表达式

papi:{表达式} 会先替换 PlaceholderAPI 变量，再计算逻辑结果。该条件依赖 PlaceholderAPI。

支持的逻辑和比较运算符：

运算符	说明
`&&`	并且。两侧条件都成立时成立。
`
`>`	大于。
`<`	小于。
`>=`	大于或等于。
`<=`	小于或等于。
`==`	相等，可比较数值或带引号的字符串。
`!=`	不相等，可比较数值或带引号的字符串。

数值表达式支持 +、-、*、/ 和括号。

yaml

condition:
  - "papi:{%player_level% * 2 >= 100}"
  - "papi:{%player_level% >= 50 && %player_level% < 100}"
  - "papi:{'%player_name%' == 'Steve'}"

字符串比较时，应使用单引号或双引号包裹两侧文本。没有比较运算符的表达式只有结果为 true 时才成立。

权限条件

yaml

condition:
  - "permission:{vip.1}"
  - "nopermission:{example.banned}"

权限节点只用于事件条件判断，不代表插件自动注册了对应权限。

随机条件

yaml

condition:
  - "roll:{0.1}"

0.1 表示约 10% 的成立概率，1 表示始终成立，0 表示仅在随机值恰好为零时成立，实际使用时可视为不会触发。

槽位格式

物品名称和 Lore 条件需要在条件参数中指定物品槽位。槽位和目标文本之间使用最后一个 # 分隔。

yaml

condition:
  - "check_equals_name:{Origin#MainHand#&6钥匙}"

槽位格式	说明
`DragonCore#槽位名`	DragonCore 缓存槽位。
`GermPlugin#槽位名`	GermPlugin 数据库槽位。
`Minecraft#槽位编号`	玩家原版背包槽位，示例配置标注范围为 `0-36`。
`APInventory#分页ID#槽位编号`	APInventory 指定分页中的槽位，示例配置标注范围为 `0-53`。
`LyInventory#背包ID#类型`	LyInventory 指定背包和类型。
`LyInventoryReload#背包ID#类型`	LyInventoryReload 指定背包和类型。
`Origin#MainHand`	玩家主手。
`Origin#OffHand`	玩家副手。
`Origin#Helmet`	玩家头盔栏。
`Origin#ChestPlate`	玩家胸甲栏。
`Origin#Legging`	玩家护腿栏。
`Origin#Boots`	玩家靴子栏。

只有服务器安装了对应槽位插件时，相关槽位格式才可用。

动作列表

动作按照列表顺序执行。除 return 外，大多数动作执行后会继续执行同一列表中的后续动作。

动作	说明
`animation:动作ID`	向当前玩家发送 DragonCore 方块动画。
`cancel`	取消当前点击或破坏事件，但不会自动停止后续动作。
`remove`	将方块设置为空气并删除该位置的保存数据。
`blockcd:秒数`	尝试设置当前方块对当前玩家的个人冷却，当前代码的写入与检测使用了不同的缓存，不能确认该动作实际生效。
`cd:组名:秒数`	设置当前玩家指定冷却组的个人冷却。
`cd:秒数`	设置当前玩家 `default` 冷却组的个人冷却。
`servercd:组名:秒数`	设置指定冷却组的全服冷却。
`servercd:秒数`	设置 `default` 冷却组的全服冷却。
`console:指令`	由控制台执行指令，并替换 PlaceholderAPI 变量。
`op:指令`	玩家临时获得 OP 后执行指令，并替换 PlaceholderAPI 变量。
`sit`	让玩家坐在方块位置，默认高度为 `0.2`。
`sit:高度`	让玩家坐在方块位置，并使用指定高度偏移。
`message:文本`	向触发玩家发送消息，支持 `&` 颜色符号。
`drop-origin`	在方块位置掉落玩家放置时保存的原始方块物品。
`drop:物品源@物品ID:数量`	在方块位置掉落指定物品库中的物品。
`return`	立即结束本次监听处理，不再执行后续动作和后续事件。

动画动作

yaml

true-action:
  - "animation:open"

动画只发送给触发事件的玩家。动作 ID 必须与 DragonCore 方块配置中的动作对应。

取消与移除

cancel 和 remove 是两个独立动作：

cancel 只取消当前 Bukkit 事件，不删除方块数据。
remove 会直接删除方块和保存数据，但不会自动中断动作列表。
需要立刻停止所有后续处理时，应使用 return。

在 break 事件中，常用顺序如下：

yaml

true-action:
  - "cancel"
  - "drop-origin"
  - "remove"
  - "return"

该配置会阻止原版破坏流程，掉落保存的原始方块物品，删除方块与数据，然后停止检测后续事件。

冷却动作

事件触发前会依次检查：

当前方块对应的个人冷却。
事件 cd-group 对应的玩家个人冷却。
事件 cd-group 对应的全服冷却。

任意冷却未结束时，会发送对应提示并直接结束本次交互，不再检测后续事件。

yaml

按钮事件:
  type: "right"
  cd-group: "button"
  cd-message: "&7按钮还需等待 {time} 秒。"
  true-action:
    - "message:&a你启动了按钮。"
    - "cd:button:2.0"

cd-group 未填写时默认为 default。因此下面两种动作都能为未指定冷却组的事件设置个人冷却：

yaml

true-action:
  - "cd:2.0"

yaml

true-action:
  - "cd:default:2.0"

全服冷却的写法相同：

yaml

true-action:
  - "servercd:global_button:10.0"

个人冷却和全服冷却只保存在内存中，服务器关闭后不会保留。

blockcd:秒数 在当前代码中写入 BlockCooldownData，但事件触发时从 CooldownData 检查方块冷却，两者没有连通。当前版本不应依赖 blockcd 实现方块冷却，可改用每个方块无法自动隔离的普通 cd 冷却组，或等待插件修复。

指令动作

yaml

true-action:
  - "console:tell %player_name% 你触发了方块"
  - "op:example give %player_name%"

console: 和 op: 会替换 PlaceholderAPI 变量，因此使用这些动作时需要 PlaceholderAPI 正常可用。

op: 会记录玩家原来的 OP 状态。玩家原本不是 OP 时，插件会临时授予 OP，执行后再恢复为非 OP。

指令内容不需要添加开头的 /。

坐下动作

yaml

true-action:
  - "sit:0.2"

插件会在方块位置生成一个不可见、无重力的盔甲架，并让玩家坐到盔甲架上。玩家死亡、传送、退出服务器或主动离座时，插件会移除对应盔甲架。

不填写高度时默认使用 0.2：

yaml

true-action:
  - "sit"

消息动作

yaml

true-action:
  - "message:&a该方块的放置者是 &6{owner}&a。"

消息支持 & 颜色符号，并会在执行动作前替换内置占位。

掉落物品

掉落原始方块

yaml

true-action:
  - "drop-origin"

drop-origin 使用方块放置时保存的原始物品。保存数据中的物品数量会被固定为 1，因此每次动作掉落一个原始方块物品。

drop-origin 只负责生成掉落物，不会自动取消破坏、移除方块或删除保存数据。需要根据实际流程组合 cancel、remove 和 return。

掉落物品库物品

格式：

text

drop:物品源@物品ID:数量

支持的物品源如下：

缩写	物品来源
`AF`	AzureFlow
`NI`	NeigeItems
`SI`	SX-Item
`MM`	MythicMobs
`OA`	OriginAttribute

yaml

true-action:
  - "drop:MM@测试物品:1"

数量支持固定整数：

yaml

true-action:
  - "drop:MM@测试物品:3"

示例配置声明数量支持 最小值-最大值，但当前代码读取最大值时仍然使用了最小值，因此范围数量实际会固定为最小值。例如 1-5 当前实际只会生成 1 个。需要随机数量时，不应依赖该格式。

物品不存在或数量格式错误时，插件会向控制台输出错误。物品源对应的插件必须已安装并能正常提供该物品。

内置占位

条件和动作执行前会替换以下占位：

占位	说明
`{owner}`	方块放置者名称。放置者名称为空时替换为 `SYSTEM`。
`{id}`	当前方块配置 ID。

yaml

主人提示:
  type: "right"
  true-action:
    - "message:&7该方块的放置者是 &6{owner}"
    - "console:say %player_name% 点击了 {id}"

{owner} 和 {id} 是 LyDragonBlock 内置占位。%player_name% 等百分号变量由 PlaceholderAPI 处理，并且只会在 papi 条件、console: 动作和 op: 动作等明确调用 PlaceholderAPI 的位置替换。

冷却提示还支持：

占位	说明
`{time}`	剩余冷却秒数，保留一位小数。

执行顺序

一次事件处理的主要顺序如下：

确认点击或破坏的方块属于 LyDragonBlock 保存数据。
break 类型先检查非所有者破坏限制。
检查当前方块冷却。
按配置顺序查找触发类型相同的事件。
检查事件个人冷却组。
检查事件全服冷却组。
按顺序计算事件的全部条件。
根据条件结果选择 true-action 或 false-action。
按列表顺序执行动作。
没有执行 return 时，继续检测后续同类型事件。

cancel、remove 和普通动作都不会自动停止后续事件。只有 return 会立即结束本次点击或破坏监听。

完整配置

yaml

发光按钮:
  match: "发光按钮的match"
  anti-break-by-non-owner: true
  events:
    查看主人:
      type: "right"
      true-action:
        - "message:&7该方块的放置者是 &6{owner}"

    启动按钮:
      type: "right"
      cd-group: "button"
      cd-message: "&7按钮还需等待 {time} 秒。"
      condition:
        - "permission:{example.button}"
        - "papi:{%player_level% >= 10}"
        - "check_equals_name:{Origin#MainHand#&6按钮钥匙}"
      true-action:
        - "animation:open"
        - "message:&a你启动了按钮。"
        - "console:say %player_name% 启动了 {id}"
        - "cd:button:2.0"
        - "return"
      false-action:
        - "message:&c你不满足按钮的使用条件。"
        - "return"

    回收方块:
      type: "break"
      true-action:
        - "cancel"
        - "drop-origin"
        - "remove"
        - "return"

已确认的当前限制

check_contain_lore 在示例配置中存在，但条件判断代码没有正确进入该分支，当前不应使用。
blockcd 的冷却写入和读取使用不同数据容器，当前不应依赖其限制交互。
drop:* 的范围数量解析会把最大值读取为最小值，1-5 实际固定为 1。
cancel 不会停止动作列表或后续事件，需要配合 return 控制流程。
remove 不会自动停止后续动作或事件，需要配合 return 控制流程。
break 事件默认关闭原版掉落，需要使用 drop-origin 或 drop:* 主动生成掉落物。

事件动作 ​

基本结构 ​

事件类型 ​

破坏事件行为 ​

条件列表 ​

PlaceholderAPI 表达式 ​

权限条件 ​

随机条件 ​

槽位格式 ​

动作列表 ​

动画动作 ​

取消与移除 ​

冷却动作 ​

指令动作 ​

坐下动作 ​

消息动作 ​

掉落物品 ​

掉落原始方块 ​

掉落物品库物品 ​

内置占位 ​

执行顺序 ​

完整配置 ​

已确认的当前限制 ​

事件动作

基本结构

事件类型

破坏事件行为

条件列表

PlaceholderAPI 表达式

权限条件

随机条件

槽位格式

动作列表

动画动作

取消与移除

冷却动作

指令动作

坐下动作

消息动作

掉落物品

掉落原始方块

掉落物品库物品

内置占位

执行顺序

完整配置

已确认的当前限制