诊断与排错
所属：参考手册 · 相关：FAQ · 自然生成与预加载 · config.yml 全配置 · 返回：首页
按「现象 → 可能原因 → 解法」组织的排查手册。先在下面的速查表里对号入座，再看对应小节。配合这几个诊断命令使用：
| 命令 | 用途 |
|---|---|
/qr why <模板> | 在你脚下逐条列出该模板每项落点检测（开关 / 世界 / 维度 / 坐标盒 / 高度 / 地面 / 水 / 群系 / 平整度 / 间距 / 密度）的通过 ✔ / 失败 ✘ + 原因。「配了不生成」第一时间用它。 |
/qr gentest | 在你附近按生成总控活世界算法发起约 25 次生成尝试，回报成功 / 被密度拦 / 没抽到模板 / 放置失败各几次。看实际命中率（要求生成总控开启）。 |
/qr near [半径] | 列出附近已生成的锚点（名称 / 距离 / 锚点 id），默认半径 200。确认遗迹到底有没有生成、在不在脚下。 |
/qr info [锚点] | 不带参=全局状态（模板数 / 锚点数 / 会话数 / 跟踪目标数）；带锚点 id=该遗迹的模板 / 坐标 / 状态 / 会话占用 / 蓝图统计 / 通关进度。 |
/qr profile [reset] | 看 QR 各阶段的实际耗时（放置 paste.place / 快照 snapshot.capture / 还原 snapshot.restore 的次数 / 平均 / 峰值 / 总计 ms）。reset 清零重测。自证清白神器。 |
🌳 快速决策树
| 现象 | 最可能的原因 | 跳到 |
|---|---|---|
| 遗迹根本不生成 | 总开关 / 生成总控关、落点检测某项不过、密度满 | §1 |
| 走进遗迹不刷怪 | 没进激活半径、蓝图刷怪点缺失、MM 怪名错 | §2 |
| 宝箱右键打不开 / 没反应 | 保护中、奖励箱未解锁阶段、不是登记的容器 | §3 |
| 钥石右键核心激活不了秘境 | 没对准核心 / 层数门槛 / 危险预算 / 半径外 | §4 |
| 指引物右键没罗盘 / 不指向 | 没有同类遗迹、指引物不对、被别的指引占用 | §5 |
| 通关 / 开箱不出战利品 | 表名错、成长度门槛、每人一次已领、条件分组 | §6 |
| 服务器卡 / TPS 掉 | **多半是预生成（原版地形）**或快照超体积 | §7、§8 |
1. 遗迹不生成
最常见的问题，按这个顺序排：
- 先
/qr why <模板>——它把所有落点检测逐条列出来，红叉那一行就是原因，比猜快得多。 - 看是否被这些拦下：
/qr why 红叉的检测 | 含义 | 解法 |
|---|---|---|
| 开关 / enabled | generation.enabled: false 或模板 generation.enabled: false | config 与模板都要开 |
| 世界 / 维度 | 当前世界 / 维度不在档案 environments / worlds 内 | 改档案 / 模板的 environments、worlds，或换个世界测 |
| 群系 | 当前群系不在 biomes 白名单 | 站到匹配群系，或放宽 biomes（留空=不限） |
| 坐标盒 spawn-region | 在 exclude 盒内（如出生点排除区） | 走出排除区，或改 spawn-region |
| 高度 / 地面 / 水 | 脚下不满足生成层（如海面档案站在陆地、spawn-in-water:false 站水里） | 换到合适地形，或调 spawn-in-water/spawn-in-lava/spawn-in-void |
| 平整度 flatness | 地面起伏超过 max-variance | 换平地，或调大 max-variance / max-errors，或 radius:0 关检测 |
| 间距 / 密度 | 附近已有遗迹达 min-spacing / max-per-region | 走远点，或调小密度限制（见下） |
- 不是落点问题，而是「没轮到它」：用
/qr gentest看实际命中率。若报「没抽到模板」多，是权重 / 优先级问题——调高该模板generation.weight，或检查director.weights是否写了非空列表（写了就只有列进来的模板参与抽签）。若报「被密度拦」多，调高director.density.max-per-region、调小min-spacing。 - 生成总控没开 / 总开关没开：
/qr gentest、/qr scatter都要求director.enabled: true，关着会提示总控未启用；generation.enabled: false时整套自然生成停摆，只能/qr spawn手动投放。 - 想立刻看到效果：
/qr spawn <模板>绕过一切检测直接在脚下投放；/qr scatter <半径> <数量>围绕你批量预生成铺满一片。
调参速查见 自然生成与预加载 §六。
2. 不刷怪
| 可能原因 | 解法 |
|---|---|
| 没进激活半径 | 怪在锚点 DORMANT 时休眠，玩家进入激活半径才转 ACTIVE 刷怪。用 /qr info <锚点> 看状态是否 ACTIVE；靠近核心区再看 |
| 蓝图没刷怪点 | blueprint.yml 的 spawn-points 为空。检查模板文件夹有没有 blueprint.yml，刷怪点坐标是否落在结构内（相对结构原点 0,0,0） |
| 阶段不对 | 刷怪点带 stage，只有进入对应阶段才刷。/qr info <锚点> 看当前阶段 |
| MM 怪名写错 | mob: mm-<MythicMobs名> 里的名字 MM 里不存在 → 刷不出。/mm reload 后核对名字大小写 |
| 没装 MythicMobs | mm- 前缀的怪需要 MM；没装时只能用原版实体名（如 ZOMBIE）。详见 FAQ |
| 刷怪重置间隔未到 | 模板 respawn 控制重置间隔，清完后要等 respawn 才再刷 |
详见 刷怪与通关。
3. 宝箱打不开
| 可能原因 | 解法 |
|---|---|
| 遗迹保护中 | 探索 / 激活中的遗迹受保护，部分交互受限。确认锚点状态（/qr info <锚点>），通关后 CLEARED 解锁 |
| 奖励箱未到解锁阶段 | 蓝图奖励箱带 unlock-stage，未达该阶段不可开。先推进击杀目标到对应阶段 |
| 每人仅一次已领 | per-player-once: true 的奖励箱每人只发一次，重复右键无反应（这是预期） |
| 容器不在登记类型 | 容器战利品的 containers 限定了生效类型（如 [CHEST, BARREL]）。其它容器不参与滚奖 |
| 战利品表名错 / 缺失 | 模板 loot.container-table 或奖励箱 loot-table 指向不存在的表。编辑器标记宝箱兜底用 default 表；自定义表名要和 loottables/ 文件名一致 |
详见 战利品系统。
4. 秘境激活不了
钥石右键遗迹核心没反应 / 提示激活失败：
| 可能原因 | 解法 |
|---|---|
| 没对准核心 / 不在半径内 | /qr activate 搜索半径 realm.activate-radius（默认 48）。靠近蓝图里 cores 配的核心坐标，或手持钥石右键核心方块 |
| 蓝图没配核心 | blueprint.yml 的 cores 为空 → 无激活点。补一个核心坐标 |
| 遗迹未通关 | 秘境注入通常要求遗迹先 CLEARED。先打通再激活 |
| 钥石层数门槛 | 词缀有 min-tier，钥石层数不够则无可注入词缀。用 /qr keystone give <tier> [player] 发更高层钥石测试 |
| 危险预算不足 | 词缀池受 realm.tiers.danger-budget 约束，预算耗尽就不再叠词缀（这是防地狱叠加，非 bug） |
| 互斥分组 | 同 group 的词缀互斥（如 veteran/overlord），只会选其一 |
5. 指引无效
指引物右键没出罗盘 / 不指向遗迹：
| 可能原因 | 解法 |
|---|---|
| 没有同类遗迹 | 指引物 qinhruins:guide_<模板id> 指向最近的同类遗迹，世界里一座都没有就无从指。先 /qr near 或 /qr scatter 确认有该模板的锚点 |
| 指引物给错 | 指引物由物品源给予（qinhruins:guide_<模板id>），QR 不内置 give 命令。用 QI / 掉落 / 命令给物插件发放，模板 id 要拼对 |
| 已有指引进行中 | 同时只能进行一个指引。/qr guide cancel 取消当前指引并返还指引物，再用新的 |
| 卡住的指引状态 | 管理员 /qr guide clear <player> 强制清除某玩家的指引状态（不返还物品） |
详见 向导与图鉴。
6. 战利品不出
| 可能原因 | 解法 |
|---|---|
| 表名 / 路径错 | loot.container-table / reward.clear-table / 奖励箱 loot-table 指向的表名要与 loottables/ 下文件名一致（不带 .yml） |
| 成长度门槛挡掉 | 条目 min-growth 高于玩家成长度则不掉。秘境 realm 表的合金碎片 / 附魔金苹果就有门槛（≥30 / ≥50） |
| 每人一次已领 | per-player-once: true、per-player 模式下每人首次开箱各得一份，已领过不再出 |
| 条件分组未满足 | groups 的 condition 走 PlaceholderAPI；装了 PAPI 且条件为假则该组不掷。无 PAPI 时条件恒真（应当会出） |
| 全服共享已被拿走 | shared 模式是真实容器先到先得，别人拿走就没了（中性、不吃成长度） |
| 物品源没解析出来 | item 走 CoreLib 解析，qi:/nexo: 等前缀对应插件没装会解析失败。原版用 vanilla:DIAMOND |
详见 战利品系统。
7. 服务器卡
如果卡顿发生在世界预生成 / 开服铺图阶段，先看 §8——那多半不是 QR 的锅。
QR 自身放置是分帧限流的，正常运行不该冻服。若怀疑是 QR：
- 先
/qr profile看真实耗时——它列出paste.place（结构放置）/snapshot.capture（生成前快照）/snapshot.restore（移除还原）各阶段的次数 / 平均 / 峰值 / 总计 ms。哪个峰值高就是它。看完/qr profile reset清零再观察。 - 快照超体积冻线程：超大结构（百万级方块）同步快照会冻主线程。config 有
cleanup.max-snapshot-volume（默认 500000）——超此值跳过快照（移除不还原但不卡服）。卡在snapshot.capture就调小它，或针对超大结构关cleanup.snapshot-restore。 - 候选生成尖峰：海量新区块（如预生成）瞬间塞满候选队列。调小
generation.max-per-tick、generation.max-millis-per-tick（每 tick 毫秒预算，超时即让出），或调低director.live.chance。控制台「候选队列满」每分钟告警一次时即此情况。 - 遗迹太多：
director.density.max-per-region太大、regen-hours太长导致打通遗迹不消退堆积。开regen-hours+cleanup.snapshot-restore让打通遗迹定期还原腾位。
8. 预生成 / 开服时卡顿（必看）
🔴 重要认知：预生成阶段的卡顿、TPS 下降、耗时长，来自服务端在疯狂生成原版地形区块（Chunky 等在干活），不是 QinhRuins。
QR 的遗迹是跟着区块走的——新区块加载（chunk-chance）或玩家活动（live）才触发生成尝试。当你用 Chunky 等预生成插件一次性铺开大量区块时，真正吃 CPU 的是原版地形生成本身。QR 自己的放置是分帧限流的（generation.max-millis-per-tick 毫秒预算 + 候选队列，超时就让出本 tick），不会冻服，只会在预生成期被限流拖慢落位。
自证清白：预生成期间跑 /qr profile——你会看到 QR 各阶段（paste.place 等）的实际耗时占比很小，卡顿的大头不在这里。
正确做法（提前发通知、资源世界先说关闭、配置差就小半径分批次、预生成期间给 QR 减负）以及完整推荐顺序，见 ➜ 自然生成与预加载 §七 世界预生成（Chunky）与防卡建议 ⚠️ 必读。
还没解决？
/qr why <模板>逐条看落点检测/qr gentest看实际命中率（需生成总控开启）/qr near//qr info确认锚点状态/qr profile看各阶段真实耗时- 翻 术语表 确认名词，或看 FAQ