牢李插件系列
搜索

故障排查

编辑线程等待、世界池、队列、触发器、配置、奖励与数据恢复问题树。

排障时先保存完整日志和配置副本。不要只复制一行异常，也不要在活动实例中连续执行重载、删除和覆盖文件。

先收集五项信息

服务端名称与完整构建号
Java 版本
LiDungeon 完整版本
已安装可选依赖及版本
问题地牢 ID、发生时间和执行命令

同时执行 /lidungeon status，保存启动阶段“功能/触发器/条件数量”和 Folia 世界池日志。

/lidungeon edit 导致 watchdog 10 秒线程转储

若线程栈停在 AbstractDungeon.edit 的 CountDownLatch.await，说明全局/主线程正在等待区域或异步任务完成，属于插件调度链问题，不是 Paper 崩溃。

当前 .9 保留 Folia 编辑启动的非阻塞链。仍出现时：

  1. 用 /lidungeon help 确认实际加载版本。
  2. 检查 plugins/、plugins/update/ 和面板同步目录是否残留旧 Jar。
  3. 完整重启，不使用 /reload 或 PlugMan。
  4. 确认池世界已加载且维度匹配。
  5. 只保留一个最小地牢复现。
  6. 保存完整 watchdog 栈、10 秒前后的日志和该地牢目录副本。

不要把该错误报告给 Paper；线程栈已经指向 LiDungeon 调用链。

/lidungeon import 报 CraftServer.createWorld UnsupportedOperationException

这是 .8 及更早版本在 Folia 上误用 WorldCreator.createWorld() 的问题。Folia 即使在 Global Scheduler 中也不支持运行期创建或卸载世界，换线程不能解决。

.9 起导入流程改为离线目录复制：

  1. 确认服务器根目录存在 <世界名>/level.dat 和地图数据。
  2. 确认该世界没有出现在当前已加载世界列表；若由服务端或多世界插件预加载，先移除预加载配置并完整重启。
  3. 确认 plugins/LiDungeon/maps/<世界名>/ 尚不存在。
  4. 执行 /lidungeon import <世界名> NORMAL|NETHER|THE_END。
  5. 等待成功消息，再执行 /lidungeon edit <世界名>、setlobby、setspawn 和 save。

导入会先复制到 plugins/LiDungeon/import-staging/，完整复制后才移入 maps/。插件直接从 level.dat 读取出生点；读不到时使用 0,64,0 并给出中文提醒。重复导入、目标已存在和世界仍在加载都会被拒绝，不覆盖现有地牢。

edit <地牢> 显示找不到地牢

edit 不负责创建。先执行：

/lidungeon create <名称> classic lidungeon:void NORMAL

或者确认 plugins/LiDungeon/maps/<地牢>/config.yml 存在且启动时加载成功。地牢 ID 使用目录/命名空间，不是彩色显示名。

玩家使用 join 进不去

正确入口：

/lidungeon play <地牢>

/lidungeon join <玩家> 需要 dungeons.admin，作用是管理员进入该玩家的实例。

触发器菜单项目少

基准为 15 个触发器。依次检查：

  1. 启动日志是否显示 15。
  2. MythicMobs 只会替换生物死亡触发器，总数不增加。
  3. 程序化房门/房间触发器是否在正确房间编辑上下文。
  4. 是否停留在某个分类子页。
  5. 当前地牢/功能目标是否允许该触发器。
  6. Jar 是否为 .9。

PAPI 和 Citizens 不会增加触发器；它们分别增加条件和功能。

触发器存在但不执行

用最小链排查：

原触发器 -> 消息发送器("TEST")
  • 不显示 TEST：检查事件位置、半径、房间限制、重复开关和保存状态。
  • 显示 TEST：触发器正常，问题在条件、目标或后续功能。
  • 移除条件后正常：逐个恢复条件，检查比较符、类型和条件反转。
  • 新实例正常、旧实例不正常：重载没有替换活动实例的运行状态。

地牢一直排队或实例加载超时

检查限制最小值：

  • General.MaxInstances 全局上限；
  • 地牢 General.MaxInstances；
  • 对应维度有效 Folia 池世界数；
  • 当前活动实例是否正常回收；
  • InstanceLoadTimeout 是否小于地图实际加载时间。

先修复未回收实例和无效池，不要只提高上限/超时。

Folia 世界池回退

日志会明确指出世界未加载或维度不匹配。修复配置后必须完整重启，因为池在维度首次初始化时建立，不应依赖热重载重建。

配置修改无效

  1. 确认文件路径。
  2. 检查 YAML 缩进和控制台解析错误。
  3. 分清 /lidungeon reload 与 reload <地牢>。
  4. 检查地牢是否覆盖全局准备字段。
  5. 分清当前实际读取键与旧兼容键，例如旁观 GUI 的 GuiTitle、ItemSlot、ItemLore、FlySpeed。
  6. 新开一个实例验证，不在旧实例判断。
  7. 世界池和依赖变更重启。

玩家完成后没有记录

确认终点使用的是“完成地牢”，不是“离开地牢”或管理员 kick。完成记录只有通过完成函数产生，前置地牢、finished 占位符和完成冷却都依赖它。

奖励没有发放

检查：

  • 奖励功能是否真的触发；
  • GiveLootAfterCompletion 是否让奖励等待完成；
  • 战利品表名是否存在；
  • 玩家是否在奖励冷却；
  • 背包已满时物品去向；
  • Mythic 掉落表是否在 MythicMobs 中成功加载；
  • 玩家是否在奖励发出前异常离开。

玩家背包或状态异常

核对 KeepInventoryOnEnter、KeepHealthOnEnter、KeepFoodOnEnter、KeepPotionEffectsOnEnter、KeepExpOnEnter，以及 Multiverse-Inventories 是否同时管理相同世界。出现覆盖时先在测试服禁用其中一套恢复链定位。

提交问题时应附带

  • 完整 logs/latest.log；
  • watchdog 全部线程栈（若有）；
  • 脱敏后的 config.yml 和问题地牢 config.yml；
  • /lidungeon status 输出；
  • 世界池配置与实际已加载世界列表；
  • 最小复现步骤；
  • 是否只在 Folia、只在某维度或只在程序化地牢发生。