龙核方块 LyDragonBlock

LyDragonBlock 用于把 DragonCore 方块配置转换为可获取、可放置、可保存和可交互的家具方块。管理员通过 /ldb open 打开方块总览并获取专用物品，玩家放置后，插件会记录方块位置、放置者、方块 ID、DragonCore match 和原始物品。

方块可以配置左键、右键和破坏事件，并根据权限、PlaceholderAPI 表达式、概率或指定槽位中的物品执行消息、指令、动画、坐下、冷却、掉落、移除等动作。

插件信息

项目	内容
插件名	`LyDragonBlock`
中文名	龙核方块
插件版本	`1.0.1`
作者	离渊
主命令	`/ldb`
硬前置	`ProtocolLib`
软依赖	`PlaceholderAPI`、`DragonCore`
明确支持版本	`1.12.2`、`1.20.1`
方块配置目录	`plugins/LyDragonBlock/block/`
方块数据目录	`plugins/LyDragonBlock/data/`

版本限制

插件只为 Minecraft 1.12.2 和 1.20.1 提供了对应的 NMS 实现。其他版本启动时会被判定为不受支持并禁用插件。

依赖与功能联动

插件或组件	类型	用途
`ProtocolLib`	硬前置	用于物品数据序列化等底层功能，缺失时插件无法正常加载。
`DragonCore`	`plugin.yml` 软依赖	提供 DragonCore 方块显示、槽位读取和方块动画。实际使用本插件的核心家具功能时需要正确安装。
`PlaceholderAPI`	`plugin.yml` 软依赖	解析条件表达式、放置指令和事件指令中的 PAPI 变量。使用相关功能时需要正确安装。

插件还包含部分外部插件的适配代码，但这些插件不是所有服务器都必须安装。只有使用对应槽位或掉落来源时，才需要安装相应插件。

槽位适配

槽位前缀	对应来源
`Origin`	玩家主手、副手和原版装备栏
`Minecraft`	玩家原版背包槽位
`DragonCore`	DragonCore 槽位
`GermPlugin`	GermPlugin 槽位
`APInventory`	梦星桐背包分页槽位
`LyInventory`	LyInventory 旧版背包槽位
`LyInventoryReload`	LyInventory 重置版背包槽位

物品掉落适配

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

玩法与数据流程

管理员在 plugins/LyDragonBlock/block/ 中配置方块 ID，并填写对应 DragonCore 方块配置的 match。
管理员执行 /ldb reload 载入主配置和全部方块配置。
管理员执行 /ldb open，在方块总览中点击目标方块，获取带有 dragon_id 数据的专用头颅物品。
玩家放置该物品后，插件以世界名和坐标生成存储 ID，并在 plugins/LyDragonBlock/data/ 中保存独立的 yml 数据文件。
玩家左键、右键或破坏已记录的方块时，插件按照对应方块配置中的事件顺序检查条件并执行动作。
方块被正常破坏或通过 remove 动作移除后，对应缓存和数据文件会被删除。

专用方块物品

必须从 /ldb open 获取方块物品。插件通过物品头颅纹理和 dragon_id NBT 识别方块，普通头颅、仅修改名称的物品或丢失 NBT 的物品不能替代。

主要功能

功能	说明
方块总览	OP 可打开 54 格总览界面。每页展示最多 45 个方块，点击后获得对应的可放置物品。
方块持久化	每个已放置方块单独保存位置、放置者名称与 UUID、方块 ID、DragonCore `match` 和原始物品。
启动载入	插件初始化完成后异步读取 `data/` 目录中的方块数据，并恢复到运行时缓存。
递归配置读取	`block/` 目录及其子目录中的 `.yml` 文件都会被读取。一个文件可以配置多个顶级方块 ID。
放置指令	方块放置成功后可执行玩家指令、控制台指令或临时 OP 指令，并支持 PlaceholderAPI 变量。
三类事件	支持 `left` 左键事件、`right` 右键事件和 `break` 破坏事件。
顺序执行	同一方块的事件和动作按照配置中的顺序处理；`return` 可以立即终止本次后续处理。
主人限制	`anti-break-by-non-owner` 可阻止非放置者破坏方块，OP 不受该限制。
条件分支	每个事件可以配置 `condition`、`true-action` 和 `false-action`。全部条件通过时执行成功动作，否则执行失败动作。
权限条件	可判断玩家拥有或不拥有指定权限。权限名称由方块配置自行填写，插件没有声明固定权限节点。
PAPI 表达式	支持数值运算、数值比较、字符串相等比较以及 `&&`、`
概率条件	可使用 `0` 至 `1` 范围的小数进行随机概率判断。
物品条件	可检查指定槽位物品名称的完整匹配或包含关系，也可检查 Lore 是否存在完整匹配的一行。
指令动作	支持控制台指令和临时 OP 指令，执行前会解析 PlaceholderAPI 变量。
DragonCore 动画	可向触发玩家发送指定方块位置的 DragonCore 动画。
坐下动作	可在方块位置生成不可见盔甲架并让玩家坐下，支持自定义高度。玩家传送、死亡、退出或主动离座时会清理座位。
掉落动作	可掉落方块原始物品，或从已适配的外部物品库获取指定物品。
玩家冷却组	可按玩家和冷却组限制事件触发，并在多个方块事件之间共享同名冷却组。
全服冷却组	可设置所有玩家共享的冷却组。冷却数据仅保存在内存中，服务器关闭后不会保存。
全局交互间隔	`interaction-interval` 用于限制同一玩家处理方块交互事件的频率。
破坏兼容选项	`ignore-unbreak` 可决定是否继续处理已经被其他插件取消的方块破坏事件。

事件条件与动作概览

条件

写法	作用
`papi:{表达式}`	解析 PAPI 变量后计算表达式。
`permission:{权限}`	玩家拥有指定权限时通过。
`nopermission:{权限}`	玩家没有指定权限时通过。
`roll:{概率}`	按 `0` 至 `1` 的概率通过。
`check_equals_name:{槽位#名称}`	指定槽位物品名称完整匹配时通过。
`check_contain_name:{槽位#文本}`	指定槽位物品名称包含文本时通过。
`check_equals_lore:{槽位#文本}`	指定槽位物品 Lore 中存在完整匹配的一行时通过。

动作

写法	作用
`message:消息`	向触发玩家发送消息，支持 `&` 颜色符号。
`console:指令`	以控制台身份执行指令。
`op:指令`	临时给予玩家 OP 后执行指令，执行结束后恢复原状态。
`animation:动作ID`	对当前 DragonCore 方块播放指定动作。
`sit`	让玩家坐在方块默认高度 `0.2` 的位置。
`sit:高度`	让玩家坐在指定高度的位置。
`cd:组:秒数`	为当前玩家设置事件冷却组。
`servercd:组:秒数`	设置全服共享事件冷却组。
`drop-origin`	在方块位置掉落保存的原始方块物品。
`drop:来源@物品ID:数量`	从适配的物品库获取物品并在方块位置掉落。
`cancel`	取消当前 Bukkit 交互或破坏事件。
`remove`	将当前方块设为空气，并删除对应存储数据。
`return`	立即终止本次处理，不再执行后续动作和事件。

事件条件和动作的完整格式见条件与槽位与事件动作。

当前实现注意事项

示例配置中提供了 check_contain_lore，但当前 1.0.1 的条件分支没有正确匹配该写法。不要依赖 Lore 包含判断，建议使用 check_equals_lore。

blockcd:秒数 动作虽然存在，但当前版本设置和读取方块冷却时使用了不同的数据容器，不能确认其能够实际阻止后续交互。需要稳定冷却时使用 cd:组:秒数 或 servercd:组:秒数。

指令

所有已确认的管理指令都通过 OP 状态判断，没有独立权限节点。

指令	执行者	要求	说明
`/ldb`	玩家或控制台	OP	显示插件帮助、版本和作者信息。
`/ldb open`	玩家	OP	打开方块总览，点击方块图标后获得对应的专用物品。
`/ldb reload`	玩家或控制台	OP	重载 `config.yml`，清空并重新读取 `block/` 目录中的全部方块配置。
`/ldb load`	玩家或控制台	OP	手动载入 `data/` 中的方块存储数据；缓存不为空时不会重复载入。仅用于初始化载入失败的情况。

指令补全

当前 Tab 补全只提供 reload 和 open，不会提示 load，但 /ldb load 指令本身已经实现。

基础配置结构

主配置位于 plugins/LyDragonBlock/config.yml，负责全局交互间隔、破坏兼容选项和提示消息。每种方块的定义位于 plugins/LyDragonBlock/block/ 下的 .yml 文件。

yaml

示例方块:
  match: 'DragonCore 方块配置中的 match'
  anti-break-by-non-owner: true
  place-command:
    - '[console]say %player_name% 放置了 {id}'
  events:
    查看主人:
      type: 'right'
      true-action:
        - 'message:&7该方块的主人是 &6{owner}'

方块文件的顶级键是 LyDragonBlock 使用的方块 ID。match 才是 DragonCore 方块配置中的匹配值，两者不能混用。

事件条件和动作执行前支持以下内部替换值：

替换值	内容
`{owner}`	方块放置者名称；名称为空时替换为 `SYSTEM`。
`{id}`	当前方块的 LyDragonBlock 方块 ID。
`{time}`	冷却提示中的剩余秒数，格式保留一位小数。

PlaceholderAPI

代码会在 PAPI 条件、放置指令、console: 动作和 op: 动作中调用 PlaceholderAPI。使用这些功能前应确认 PlaceholderAPI 已安装并正常启动。

数据保存

每个已放置方块会保存为独立文件：

text

plugins/LyDragonBlock/data/世界名_X_Y_Z.yml

数据文件包含以下内容：

数据键	说明
`location.*`	Bukkit Location 序列化后的世界与坐标信息。
`placer-uuid`	放置者 UUID。
`placer-name`	放置者名称。
`dragon-match`	放置物品头颅纹理中的 DragonCore 匹配值。
`dragon-id`	LyDragonBlock 方块 ID。
`origin-item`	经过 ProtocolLib 序列化的原始方块物品。

不要在服务器运行期间随意移动、重命名或编辑这些数据文件。删除家具时应通过正常破坏流程或事件的 remove 动作同步清理方块和数据。

已确认的限制

插件只明确支持 Minecraft 1.12.2 和 1.20.1。
/ldb open、/ldb reload 和 /ldb load 仅允许 OP 使用，没有可配置权限节点。
方块总览的内容来自 block/ 目录中成功载入的配置。
方块只有在放置物品中存在正确的头颅纹理和 dragon_id NBT 时才会被记录。
anti-break-by-non-owner 根据玩家名称判断当前玩家是否为放置者，OP 可以绕过限制。
玩家冷却、全服冷却和坐下数据只保存在内存中，服务器重启后不会恢复。
破坏事件默认不产生原版方块掉落；需要归还家具物品时应在事件中配置 drop-origin。
外部槽位和物品库功能只有在对应插件及其兼容版本存在时才能使用。
Java API 中的 removeBlock(Location) 已有实际删除逻辑，setBlock(Location, Player, String, String) 当前为空实现。

文档索引

页面	内容
配置说明	`config.yml`、`block/` 方块文件、配置键和数据目录。
事件动作	左键、右键、破坏事件，动作格式、执行顺序和冷却机制。
条件与槽位	PAPI 表达式、权限、概率、物品名称、Lore 和槽位格式。
开发接口	Java API 接口、当前实现状态和调用限制。
常见问题	启动、版本、总览、放置、交互、破坏和数据载入排查。

龙核方块 LyDragonBlock ​

插件信息 ​

依赖与功能联动 ​

槽位适配 ​

物品掉落适配 ​

玩法与数据流程 ​

主要功能 ​

事件条件与动作概览 ​

条件 ​

动作 ​

指令 ​

基础配置结构 ​

数据保存 ​

已确认的限制 ​

文档索引 ​