出问题了怎么办
这一页按"你看到的现象"来组织。找到你的症状，照着往下走。
先做这两件事
不管什么问题，先做这两步，能省掉大量猜测：
第一步：开调试模式
/tsl debug
再执行一次就关掉。开启后插件会把每一步的判断都打印到控制台，有 treasure.debug 权限的玩家也会在聊天框收到。
第二步：看控制台
插件的所有提示都以 [Treasure] 开头。黄色是警告，通常直接写明了原因。
症状：控制台没有加载信息
启动后看不到 已加载 N 个宝箱配置。
| 可能原因 | 怎么确认 | 怎么解决 |
|---|---|---|
| 插件没装上 | 执行 /plugins 看有没有 TreasuresLite | 检查 jar 是否在 plugins/ 里 |
| 服务端版本太低 | 看启动日志有没有版本相关报错 | 需要 1.12.2 或更高 |
| 配置目录被删了 | 看 plugins/TreasuresLite/treasures/ 存不存在 | 删掉整个 TreasuresLite 文件夹后重启，让它重新生成 |
如果看到 未成功加载任何宝箱配置，说明目录存在但里面没有能用的文件。
如果看到 加载 treasures/xxx.yml 失败，后面会跟着具体的错误类型，通常是 YAML 格式问题：缩进用了 Tab、冒号后面没空格、引号没闭合。
症状：命令能打开，但世界里看不到宝箱
这是最常见的问题。/tsl open def 有界面说明宝箱定义没问题，问题在坐标配置。
按顺序检查：
1. 坐标格式对不对
看控制台有没有 无法解析坐标 location.xxx[N]='...'。
有的话就是格式错了。必须是五段：'世界名, X, Y, Z, 朝向'。最常见的是漏了朝向。
# 错
- 'world, 100, 65, 200'
# 对
- 'world, 100, 65, 200, north'
2. 组名对不对
看控制台有没有 宝箱 def 引用了不存在的坐标组 xxx。
有的话说明 generator.normal.treasure 里写的组名和 location 里定义的不一致。检查拼写和大小写。
3. 宝箱 ID 对不对
开 /tsl debug 后走到坐标附近，看有没有 以下宝箱 ID 未加载，相关坐标已跳过: xxx。
有的话说明 location.yml 里写的宝箱 ID 和 treasures/ 里的文件名不匹配。文件叫 daily.yml，ID 就得写 daily。
4. 距离够不够
默认只有 16 格内才显示。走近一点，或者调大 config.yml 里的 view.distance。
开 debug 后能看到 超出距离=N 的统计。
5. 世界名对不对
世界名要用文件夹名，不是显示名。多世界服务器容易配错。
开 debug 后能看到 世界不匹配=N 的统计。
6. 条件通不通过
treasure:
def:
my_spots: "check player level > 10"
这样配的话等级不够就看不到。先改成 "true" 排除条件问题。
开 debug 后能看到 Checking xxx with condition '...' = true/false。
7. 强制刷一次
/tsl update
如果执行后能看到，说明配置是对的，只是刷新时机问题。看下一个症状。
症状：要手动 update 才显示，不会自动出现
刚进服的情况：插件需要先算出这个玩家能看到哪些位置，算完之前不显示。进服后等 3 到 5 秒是正常的。
过了很久还是不显示：检查 config.yml
view:
refresh: 30000
填 0 或负数会关掉定时刷新。启动时控制台会输出 周期任务 view-refresh 已禁用。
确认周期任务在跑：启动时应该能看到类似这样的输出
[Treasure] 已启动周期任务 view-refresh: 30000ms (600 tick, sync)
[Treasure] 已启动周期任务 normal-refresh: 1800000ms (36000 tick, sync)
没有这些行说明任务没起来，检查对应的 period 是不是填了 0。
症状：宝箱右键没反应
| 可能原因 | 怎么解决 |
|---|---|
| 玩家看到的是残留的旧显示 | 执行 /tsl update，插件会自动对账并恢复 |
| 宝箱定义加载失败 | 看控制台有没有 加载 treasures/xxx.yml 失败 |
| 有其他插件拦截了右键 | 试试在没有保护区的地方测试 |
开 /tsl debug 后右键宝箱，正常应该看到 右键点击了寻宝箱。
如果看到 右键点击了已换代的虚拟宝箱，正在恢复真实方块，说明这个宝箱已经过期了，插件正在清理，属于正常行为。
症状：右键后箱子消失了
这通常发生在钥匙不足的情况下。当前版本已经处理了这个问题：钥匙不足时插件会立即重发宝箱、并在 1 tick 后再补发一次，箱子不应该消失。
如果还是消失了：
- 确认插件版本是 2.0.12 或更高
- 开 debug 看有没有
钥匙校验未通过后恢复宝箱失败或坐标已不再可见 - 执行
/tsl update应该能恢复
症状：右键后箱子变成真实方块，界面没打开
说明宝箱界面构建失败了。控制台会有 构建宝箱 XXX 的 GUI 失败，后面跟着具体原因。
常见原因：
| 控制台信息 | 原因 | 解决 |
|---|---|---|
claim.amount=N 超过布局中的可用奖励槽位 M | 奖励数量比槽位多 | 减小 claim.amount 或者加大布局 |
claim.generator 缺失 | 没写 generator | 补上奖励池 |
claim.generator.xxx.chance 必须大于 0 | 权重写了 0 | 改成正数 |
claim.amount=N 无法由 M 个 unique 生成器满足 | 全是 unique 但数量要求太多 | 减小 amount 或者加奖励种类 |
claim.generator.xxx.material 解析失败 | 物品源或 ID 有问题 | 见下一节 |
claim.generator.xxx.amount 必须在 1..2304 之间 | 单个物品数量越界 | 改到范围内 |
icons.xxx.material 无效 | 装饰图标材质名错了 | 检查材质拼写 |
症状：奖励物品出不来 / 报解析失败
控制台出现 物品配置 'xxx' 解析失败 或 物品库不存在 ID。
这里的检查是严格的，缺任何一环都会导致整个宝箱打不开：
1. 前缀对应的插件装了吗
启动时控制台会打印挂钩成功的物品源：
已挂钩软依赖 MythicMobs 作为物品源
已挂钩软依赖 ItemsAdder 作为物品源
没有对应的行说明那个插件没装或者没加载成功，此时写 mm: xxx 会直接失败。
2. 物品 ID 存在吗
去对应插件里确认 ID 拼写。注意有些插件的 ID 区分大小写。
3. 原版材质名对吗
游戏里对着物品按 F3 + H 打开高级提示，能看到真实的物品 ID。
4. 格式对吗
material: "mm: my_item" # 前缀 + 冒号 + 空格 + ID
material: "diamond" # 原版物品直接写
症状：钥匙识别不了
按顺序排查：
1. 确认条件加载了
启动时应该看到 宝箱 X 已加载 N 个钥匙条件。如果 N 是 0，或者有 已跳过 的告警，说明配置格式有问题，具体对照表在 要钥匙才能开。
2. 确认拿在主手
副手不算。
3. 开 debug 看匹配细节
/tsl debug
然后右键宝箱，会看到 钥匙检查失败: 持有=1, 需要=10, 手持=PAPER 这样的信息，能直接看出是哪个条件不满足。
4. 检查 lore 条件
lore 是"你写的每一条都必须命中"。如果你写了三条，物品必须同时有这三条描述。删掉多余的条件试试。
5. 检查 custom_model_data
1.14 以下不支持。启动时会有告警 但当前服务端低于 1.14，该条件不会匹配。把这一行删掉或注释掉。
6. 检查名字里的颜色代码
匹配时会去掉颜色代码，所以 name: "钥匙" 能匹配 &6钥匙。但如果你在配置里写了颜色代码而物品没有，也能匹配（因为两边都去色）。这一项通常不是问题。
症状：随机宝箱数量不够
控制台出现 随机宝箱 xxx 的规则生成数量不足，后面跟着统计。
对照统计里数字最大的那一项：
| 统计项 | 原因 | 解决 |
|---|---|---|
未加载区块 | 那片区域没有玩家，区块没加载 | 把范围缩小到玩家常去的地方 |
材质不匹配 | range 的材质过滤太严 | 放宽材质列表，或改用 ground |
未找到支撑 | ground 往下扫到底也没方块 | 该区域可能是虚空，换位置 |
越界 | 高度超出世界上下限 | 检查 range 的高度范围 |
重复 | 范围太小，随机总撞到同一个点 | 扩大区域范围 |
未加载区块 是最常见的。随机生成必须读取方块信息才能判断，没加载的区块读不到。
症状：改了配置没生效
1. 执行了 reload 吗
/tsl reload
config.yml 和 location.yml 支持自动重载，保存文件就会生效。但 treasures/ 下的宝箱文件需要手动 reload。
2. 改对文件了吗
确认改的是 plugins/TreasuresLite/ 下面的文件，不是 jar 包里的。
3. 改的是 type 还是 block
想换方块外观必须改 settings.block。settings.type 只在没有 block 的时候才生效。
默认 def.yml 两个都有，所以改 type 不会有任何效果。
4. events.spawn 里的东西不会执行
spawn 事件是预留的，当前版本不会执行。写在里面的脚本没有效果。
5. hologram 配置不会生效
全息文字是预留配置，插件没有调用它。
症状：控制台刷屏
view.async 已停用：这条只在启动时出现一次。把 config.yml 里的 async 改成 false 就不再提示。
大量重复的调试信息：/tsl debug 忘记关了，再执行一次关掉。
数据包映射相关警告：2.0.13 已修复这个问题，升级版本即可。
症状：宝箱没有开合动画
只有 CHEST、TRAPPED_CHEST、ENDER_CHEST 三种方块有开合动画。
配成头颅、木桶、潜影盒、CraftEngine 自定义方块时，开箱一切正常，但看不到盖子打开的效果。这是原版数据包的限制，不是配置问题。
症状：BungeeCord 子服里界面异常
关掉虚拟化：
view:
virtualize_ui: false
这是已知的兼容性问题，默认就是关闭的。
还是解决不了
收集这些信息后联系作者（QQ 1747484670）：
- 服务端类型和版本（比如 Paper 1.12.2、Paper 1.20.4）
- 插件版本
config.yml、location.yml的完整内容- 出问题的那个宝箱文件的完整内容
- 开启
/tsl debug后复现问题的完整控制台日志 - 具体的操作步骤和你期望的结果
第 5 条最重要。调试日志里包含了插件每一步的判断依据，没有它基本只能靠猜。