常见问题

插件支持哪些服务端版本？

当前代码只适配以下两个服务端版本：

• 1.12.2，使用 v1_12_R1 的 NBT 实现。
• 1.20.1，使用 v1_20_R1 的 NBT 实现。

插件通过 Bukkit 版本号的次版本进行判断。其他版本会提示“当前游戏版本不受支持”，随后禁用插件。即使相邻版本使用相似的服务端结构，也不能视为已经支持。

插件需要安装哪些依赖？

ProtocolLib 是 plugin.yml 中声明的必装依赖。缺少时，服务端不会正常加载 LyDragonBlock。

插件	类型	用途
ProtocolLib	必装依赖	插件启动依赖，并用于物品数据序列化等功能
DragonCore	可选依赖，但核心玩法需要	提供龙核方块及方块动画功能
PlaceholderAPI	可选依赖	解析条件表达式、放置指令和事件指令中的变量

部分条件和动作还会调用其他插件的接口，例如 DragonCore、GermPlugin、APInventory、LyInventory、AzureFlow、NeigeItems、SX-Item、MythicMobs 与 OriginAttribute。只有使用对应槽位或物品来源时，才需要保证相关插件及兼容版本已经安装。

项目证据中没有 MySQL 或 LyMySQLCore 存储逻辑。已放置方块使用本地 YAML 文件保存，不需要安装 LyMySQLCore。

插件已经存在，但仍然没有完整加载怎么办？

按以下顺序检查控制台：

1. 确认 ProtocolLib 已成功启用。
2. 确认服务端版本是 1.12.2 或 1.20.1。
3. 确认授权验证已经通过。验证完成前，插件只会提供基础重载逻辑，完整指令、监听器和方块数据不会初始化。
4. 检查方块配置加载阶段是否出现“载入方块配置失败”。
5. 检查数据加载阶段是否出现“载入方块数据错误”。

完整初始化后，控制台会依次出现配置载入、API 初始化、监听器初始化和方块数据载入相关信息。

玩家进入服务器时提示“服务器未加载完成”怎么办？

插件在完整初始化前会阻止玩家登录，并提示：

服务器未加载完成, 禁止进入.

这表示插件的授权或服务端核心尚未完成初始化。应检查控制台中的验证结果、网络连接、服务端版本以及依赖加载情况，不要通过修改提示文本绕过检查。

为什么 /ldb 只显示重载指令？

完整验证和核心初始化之前，基础命令处理器只会显示：

/ldb reload

初始化成功后，插件才会注册完整命令处理器并提供 open、load 和 reload。这些指令都要求执行者是 OP，其中 open 还要求执行者必须是玩家。

指令	使用要求	说明
/ldb open	OP 玩家	打开方块总览，并获取带有插件识别数据的方块物品
/ldb load	OP	手动载入已放置方块数据，仅适合初始化载入失败时使用
/ldb reload	OP	重载主配置与方块配置

load 虽然可以执行，但当前 Tab 补全代码只提供 reload 和 open，因此不会自动补全 load。

/ldb open 打开的总览没有方块怎么办？

检查 plugins/LyDragonBlock/block/ 及其子目录中是否存在扩展名为 .yml 的方块配置。插件会递归读取该目录中的 YAML 文件，并将每个文件的顶层键视为一个方块 ID。

执行 /ldb reload 后检查控制台：

• 出现“开始载入方块配置”表示插件已经找到对应顶层方块 ID。
• 出现“载入方块配置失败”表示该方块的配置结构、物品数据或字段内容无法正常读取。
• 完全没有对应记录时，应检查文件位置、扩展名和 YAML 缩进。

总览每页最多显示 45 个方块。点击总览中的物品后，插件会将对应方块物品直接加入玩家背包。

为什么直接制作的头颅方块无法正常使用？

LyDragonBlock 通过物品 NBT 中的 dragon_id 识别方块配置。/ldb open 提供的物品会写入该数据，普通头颅或仅由 DragonCore 提供的物品不一定包含 LyDragonBlock 所需的 dragon_id。

应优先从 /ldb open 的总览中获取测试物品。放置事件虽然能够读取头颅纹理数据，但缺少或错误的 dragon_id 会导致插件找不到对应方块配置，放置指令和后续交互可能无法正常工作。

方块 ID 和 match 有什么区别？

方块配置的顶层键是 LyDragonBlock 使用的方块 ID，match 是 DragonCore 方块配置中对应的纹理匹配值，两者不是同一个字段。

示例方块:
  match: '示例方块的match'

• 示例方块：LyDragonBlock 方块 ID，也会写入物品的 dragon_id。
• 示例方块的match：DragonCore 方块配置中的 match 值，用于生成和匹配头颅纹理。

不要把方块 ID 直接填入 match，除非 DragonCore 配置中的真实 match 内容恰好与其完全相同。

点击总览拿到的物品放置后没有效果怎么办？

依次检查：

1. 方块配置的顶层 ID 是否与物品 NBT 中的 dragon_id 对应。
2. match 是否与 DragonCore 方块配置中的真实 match 完全一致。
3. 放置位置是否允许放置，且放置事件没有被其他插件取消。
4. 放置物品是否为插件支持的自定义头颅物品。
5. /ldb reload 时对应方块是否成功载入。
6. 事件的 type、condition、true-action 和 false-action 是否位于正确的方块配置节点下。

放置成功后，插件会在 plugins/LyDragonBlock/data/ 中为该坐标保存一份 YAML 数据。如果没有生成数据文件，应优先检查控制台中的异常信息。

place-command 为什么没有执行？

place-command 只会在插件成功识别方块配置后执行。支持以下三种写法：

格式	执行身份
[console]指令	控制台
[op]指令	临时以 OP 身份执行的玩家
指令	放置方块的玩家

指令内容会先交给 PlaceholderAPI 解析。不要在配置中加入 /，除非目标指令本身明确需要该字符。

如果方块已经放下但指令没有运行，应检查 dragon_id 是否正确，以及该 ID 对应的方块配置是否已经载入。

左键、右键或破坏动作没有触发怎么办？

先确认事件的 type：

type	触发方式
left	左键点击已记录的方块
right	右键点击已记录的方块
break	破坏已记录的方块

插件只处理已经存在于方块数据缓存中的坐标。仅在世界中摆放一个外观相同的头颅，不会自动成为可交互的 LyDragonBlock 方块。

还需要检查：

• 玩家是否处于全局交互间隔中。
• 当前方块是否处于冷却状态。
• 事件的玩家冷却组或全服冷却组是否仍在冷却。
• condition 中是否有任意一项失败。
• 前面的动作是否执行了 remove 或 return。
• 其他插件是否取消了破坏事件，且 ignore-unbreak 是否允许继续处理。

同一类型的事件会按配置读取顺序检查。return 会直接中断本次处理，后续事件不会继续执行。

为什么连续点击时没有提示，也没有触发动作？

config.yml 中的 interaction-interval 是玩家左键和右键交互的基础间隔，默认值为 1.0 秒。玩家处于该间隔时，插件会直接忽略本次点击，不发送冷却提示。

interaction-interval: 1.0

它与事件动作中的 blockcd、cd、servercd 不同。即使事件没有配置任何冷却，快速连续点击也可能被该基础间隔过滤。

破坏事件不使用 interaction-interval，但仍会检查方块和事件冷却。

条件是“任意满足”还是“全部满足”？

同一事件的 condition 列表采用全部满足的判断方式。插件从上到下检查，只要有一项返回失败，就会执行 false-action；全部通过时才执行 true-action。

没有配置 condition，或条件列表为空时，会直接视为通过。

papi 条件为什么计算失败？

papi:{...} 会先通过 PlaceholderAPI 解析变量，再计算表达式。当前实现支持：

• 数值运算：+、-、*、/ 和括号。
• 数值比较：>、<、>=、<=、==、!=。
• 逻辑连接：&& 和 ||。
• 使用单引号或双引号包围的字符串相等与不相等比较。
• 不带比较符时，仅字符串 true 会被视为真。

检查以下问题：

1. PlaceholderAPI 是否已经安装并成功启用。
2. 对应变量扩展是否已经安装。
3. 变量解析后是否得到可参与计算的数字、字符串或 true。
4. 比较表达式是否只有左右两个操作数。
5. 字符串比较时是否正确添加引号。

插件会移除表达式中不在引号内的空格，因此不要依赖空格区分字符串内容。

权限条件应该怎么排查？

条件	通过要求
permission:{节点}	玩家拥有指定权限
nopermission:{节点}	玩家没有指定权限

权限节点完全由方块配置填写，LyDragonBlock 没有在 plugin.yml 中预设这些玩法权限。条件内部的空格会被移除，应确保权限节点本身准确无误。

roll 条件的范围是多少？

roll:{概率} 使用 0 到 1 的小数表示概率，例如 0.1 表示约 10% 的通过概率。

插件会将随机数与配置值比较。配置为 1 时始终通过，配置为 0 时仅在随机值恰好为 0 的极端情况下通过。应避免填写百分号或大于 1 的百分比数值。

槽位物品条件没有通过怎么办？

当前代码能够读取以下槽位来源：

槽位格式	来源
DragonCore#槽位名	DragonCore 槽位
GermPlugin#槽位名	GermPlugin 槽位
Minecraft#槽位编号	原版背包槽位
APInventory#分页ID#槽位编号	APInventory 背包
LyInventory#背包ID#槽位类型	LyInventory
LyInventoryReload#背包ID#槽位类型	LyInventory 重置版
Origin#MainHand	主手
Origin#OffHand	副手
Origin#Helmet	头盔
Origin#ChestPlate	胸甲
Origin#Legging	护腿
Origin#Boots	靴子

排查时确认对应插件存在、槽位格式正确、槽位中确实有物品，并注意名称与 Lore 中的颜色代码会将 & 转换为 §。

当前代码可以正常判断完整名称、包含名称和完整 Lore 行。代码中的 Lore 包含判断分支存在重复条件，check_contain_lore 无法按示例预期进入对应逻辑，当前版本不建议依赖该条件。

冷却提示一直出现怎么办？

事件存在三种冷却动作：

动作	作用范围
blockcd:秒数	设计用途为限制当前方块
cd:组名:秒数	当前玩家的指定冷却组
servercd:组名:秒数	全服共享的指定冷却组

cd 和 servercd 会使用事件的 cd-group 进行检查。多个事件填写相同的组名时，会共享对应范围内的冷却。

事件处于玩家冷却或全服冷却时，会显示该事件的 cd-message；当前方块冷却提示则读取 config.yml 中的 message.block-cd。消息为空时不会提示，但冷却仍会阻止事件。

所有冷却数据只保存在内存中，关闭或重启服务器后不会保留。

blockcd 配置了却没有生效怎么办？

当前代码中，blockcd 动作将数据写入 BlockCooldownData，但交互和破坏事件检查方块冷却时读取的是 CooldownData。两个缓存没有关联，因此当前版本的 blockcd 无法按配置说明稳定限制当前方块。

需要可靠限制时，可暂时使用 cd:组名:秒数 或 servercd:组名:秒数，并为事件设置对应的 cd-group。

普通玩家为什么无法破坏方块？

检查方块配置中的 anti-break-by-non-owner：

anti-break-by-non-owner: true

设为 true 时，只有记录中的放置者可以正常破坏。OP 不受该限制。插件通过玩家名称与保存的 placer-name 比较放置者身份。

被阻止时显示的消息来自：

message:
  not-the-owner-break: '&c你不是放置者, 无法破坏该方块!'

如果服务器曾修改玩家名称、迁移离线模式数据或手动改动数据文件，即使 UUID 相同，名称不一致也可能无法通过主人判断。

其他插件取消破坏后，为什么 LyDragonBlock 不处理事件？

默认情况下，如果破坏事件已经被其他插件取消，LyDragonBlock 会直接停止处理：

ignore-unbreak: false

将 ignore-unbreak 设为 true 后，LyDragonBlock 会继续检查被取消的破坏事件。但这不代表一定能够绕过其他插件的保护，最终结果仍受监听器顺序和其他插件行为影响。

修改后执行 /ldb reload 使主配置重新载入。

破坏方块后为什么没有掉落原方块？

LyDragonBlock 会关闭已记录方块的原版掉落。需要在 break 事件的动作中明确加入：

true-action:
  - 'drop-origin'

drop-origin 会掉落放置时保存的原始物品，并将数量固定为 1。

如果破坏事件没有被取消，处理结束后插件仍会删除该坐标的数据记录。只配置 drop-origin 不会自动取消破坏。

为什么使用 cancel 后方块仍然留在原地？

cancel 会取消当前交互或破坏事件。用于 break 事件时，方块不会被正常破坏，且最终的数据记录不会自动删除。

如果同时配置了 remove，插件会直接将方块设置为空气并删除记录。动作按照列表顺序执行，应根据预期安排 cancel、drop-origin、remove 和 return 的顺序。

remove 和正常破坏有什么区别？

remove 会立即执行两项操作：

1. 将当前位置的方块改为空气。
2. 从缓存中删除方块，并删除对应的数据文件。

remove 本身不会掉落原方块，也不会自动停止当前动作列表。需要掉落物品时应在合适位置加入 drop-origin 或 drop；需要停止后续动作与事件时应加入 return。

return 会停止哪些内容？

return 会直接结束当前监听方法，不再执行当前动作列表中的剩余动作，也不会继续检查后续事件。

在 break 事件中，即使通过 return 提前结束，最终清理逻辑仍会运行：只要破坏事件没有被取消，插件就会删除该方块的数据记录。

message 动作为什么没有正确发送？

事件消息应使用带冒号的格式：

true-action:
  - 'message:&a操作成功'

插件会截取第一个冒号之后的内容，并将 & 颜色代码转换为 §。事件动作中的 message 不会主动调用 PlaceholderAPI，但在执行前会替换以下内部内容：

内容	替换结果
{owner}	方块放置者名称；名称为空时为 SYSTEM
{id}	当前 LyDragonBlock 方块 ID

console 和 op 动作有什么区别？

动作	执行方式
console:指令	由服务端控制台执行
op:指令	玩家临时获得 OP 后执行，完成后恢复原状态

两种动作都会先使用 PlaceholderAPI 解析指令内容。配置中不需要添加命令开头的 /。

place-command 使用的是 [console] 和 [op] 前缀，而事件动作使用 console: 和 op: 前缀，两者格式不能混用。

drop 动作提示物品不存在怎么办？

drop 的基本格式为：

drop:来源缩写@物品ID:数量

代码中存在以下来源：

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

数量可以填写固定整数或 最小值-最大值。如果对应插件、物品 ID 或数量格式无效，控制台会输出“物品不存在”“数量格式错误”或“交互脚本填写错误”。

当前范围数量的代码解析存在问题，最大值会从范围左侧读取，可能无法得到配置的真实随机范围。需要确定数量时，建议使用固定整数。

animation 动作没有播放怎么办？

animation:动作ID 会调用 DragonCore 的方块动画接口，并将动画发送给触发事件的玩家。

检查：

• DragonCore 是否正常启用。
• 动作 ID 是否存在于对应 DragonCore 方块配置中。
• 当前方块的 match 是否正确。
• 事件是否因条件、交互间隔或冷却提前结束。
• 动作之前是否执行了 return。

动画只发送给触发事件的玩家，不能据此确认其他玩家也会看到同样的动画。

sit 动作的位置不正确怎么办？

sit:高度 会在方块坐标中心附近生成一个不可见、无重力的盔甲架，并让玩家乘坐。未填写高度时默认使用 0.2。

true-action:
  - 'sit:0.2'

高度是相对于插件内部基础位置的偏移值。坐下位置不合适时，应小幅调整该数值。

玩家死亡、传送、退出服务器或主动离开载具时，插件会移除对应盔甲架，并处理玩家离座。玩家不能直接操作由该功能生成的盔甲架。

重启后方块数据没有恢复怎么办？

已放置方块会分别保存到：

plugins/LyDragonBlock/data/

每个文件名由世界名和方块坐标组成，格式类似：

世界名_X_Y_Z.yml

数据文件包含位置、放置者名称、放置者 UUID、DragonCore 匹配值、方块 ID 和原始物品数据。插件完整初始化后会异步读取该目录下的所有 YAML 文件。

载入失败时检查：

• 数据文件中的世界是否存在并已加载。
• location 节点是否完整。
• placer-uuid 是否为有效 UUID。
• origin-item 是否能被当前 ProtocolLib 和服务端版本反序列化。
• 控制台是否显示具体失败文件路径。

确认服务端世界已经稳定加载后，可以执行 /ldb load 手动载入一次。

/ldb load 执行后为什么没有重新读取数据？

当内存中的方块缓存不为空时，/ldb load 会直接返回，不会重复载入数据。这是为了避免重复覆盖或重复写入已有缓存。

该指令只适合插件初始化载入失败且缓存仍为空时使用。它不是常规的数据重载命令，也不会清空当前缓存后重新读取文件。

/ldb reload 会重新载入哪些内容？

/ldb reload 会：

• 保存缺失的默认配置。
• 重载 config.yml。
• 确保示例方块配置存在。
• 清空并重新读取 plugins/LyDragonBlock/block/ 下的方块配置。

它不会重新读取 plugins/LyDragonBlock/data/ 中的已放置方块数据，也不会重置当前内存中的方块数据缓存。

修改方块 ID 后，已有方块为什么失效？

数据文件会保存放置时使用的 dragon-id。如果之后修改方块配置的顶层 ID，旧数据仍会指向原 ID，插件将无法从当前方块配置缓存中找到对应配置。

修改已有方块 ID 前，应考虑已经放置的方块数据。当前代码没有提供自动迁移旧 dragon-id 的功能。

删除方块配置后，世界中的旧方块会怎样？

删除配置不会自动删除世界中的方块或 data 目录下的记录。数据仍可能被载入，但交互时无法取得对应的 DragonConfigCache，因此不会执行该方块原有事件。

需要移除旧方块时，应先在配置仍可识别的情况下处理，或通过可靠方式同步清理世界方块与对应数据文件。不要只删除数据文件而保留世界方块，否则该方块会变成不受 LyDragonBlock 管理的普通方块。

手动删除世界中的方块后，数据文件为什么还在？

LyDragonBlock 只有在自身处理的正常破坏流程或 remove 动作中才会删除数据记录。通过其他插件、地图编辑工具或直接修改世界文件删除方块，不会自动通知 LyDragonBlock 清理对应 YAML 文件。

残留记录在下次载入时仍会进入缓存。清理时必须确认对应世界坐标已经不再需要，避免误删仍有效的方块数据。

方块主人显示为 SYSTEM 是什么意思？

事件中的 {owner} 会读取数据记录里的放置者名称。当名称为空字符串时，插件会使用 SYSTEM 代替。

正常由玩家放置并成功保存的方块会记录玩家名称和 UUID。出现 SYSTEM 通常表示该数据不是通过正常玩家放置流程产生，或数据文件中的 placer-name 为空。

插件提供的 API 都可以使用吗？

API 接口声明了两个方法：

void setBlock(Location loc, Player placer, String dragonId, String matchId);
void removeBlock(Location loc);

当前服务端实现中，removeBlock 已实现，可删除指定位置已被 LyDragonBlock 记录的头颅方块及其数据。

setBlock 的服务端方法体为空，当前版本不会实际创建或保存方块。开发者不应依赖该方法完成方块放置。