排错与 FAQ

路径点不出现

按顺序排查：

1. mod 是否加载？ 运行 /mtrsurveyor mode。若提示 “Unknown command”，说明 jar 不在正确的 mods/ 文件夹或 Forge 没加载它。查看游戏日志中是否有 mtrsurveyor 加载行。
2. MTR 是否加载且本世界中存在？ MTR Surveyor 只能映射 MTR 提供的数据。服务器若没运行 MTR，自然没数据可映射。
3. 是否安装了 Xaero’s Minimap？ 路径点同步需要它。启动日志会显示是否检测到 Xaero。
4. 同步是否开启？ /mtrsurveyor config enabled 应报告 true。若不是，运行 /mtrsurveyor config enabled true。
5. 车站是否可见？ /mtrsurveyor config showStations 应报告 true。
6. 强制同步一次： /mtrsurveyor syncWaypoints。留意聊天回复 — 若显示 Xaero's Minimap is not installed!，那就是问题所在。
7. 打开世界地图。 小地图角标可能因距离太远不显示路径点；打开完整世界地图（默认 Y）确认。

路径点在地下 / 高度不对

这正是 MTR Surveyor 要修复的问题 — 若仍出现：

• 车站模式把路径点放在站台平均高度。若车站各站台高度差异大，平均值可能落在中间。
• 站台模式把每个路径点放在精确站台 Y。切换到它：/mtrsurveyor mode platform。

若站台模式下高度也不对，可能是该站台 MTR 数据在客户端不完整 — 试着打开一次 MTR dashboard（会填充第二个数据源），然后 /mtrsurveyor syncWaypoints。

路径点重复或过期

每次同步会先移除所有名字以 [MTR] 开头的路径点，再重新添加当前集合。若仍看到过期重复：

• 强制同步：/mtrsurveyor syncWaypoints。
• 仍无效可能是 Xaero 版本不匹配。确保 Xaero’s Minimap ≥ 25.3.10。
• 最后手段：在 Xaero 路径点界面手动删除 [MTR] 路径点；下次同步会重建正确集合。

路线叠加层不显示

1. 是否安装了 Xaero’s World Map？ 路线叠加层需要它（路径点仅需 Minimap）。
2. 开关是否打开？ 打开世界地图，点击左上角 MTR 小部件，应变为绿色。
3. 是否有路线数据？ 叠加层读取 MTR 的 SimplifiedRoute 与 Route。若网络没有定义路线，自然没东西可画。
4. 一次性保护。 若渲染器曾抛异常，会为本会话禁用自身以避免日志刷屏。查看游戏日志找到原始错误，然后反馈。重启客户端可重新启用。

/mtrsurveyor syncWaypoints 提示 “Xaero’s Minimap is not installed!”

你缺少 Xaero’s Minimap，或它加载失败。本 mod 只检查 xaerominimap（mod ID）。安装 1.20.1 版 Xaero’s Minimap（≥ 25.3.10）后重启。

启动时崩溃

这不应发生 — XaeroMixinPlugin 会在缺失 Xaero’s World Map 时跳过相关 mixin，所有 Xaero 耦合代码都被 try/catch(NoClassDefFoundError) 包裹。若确实崩溃：

1. 查看崩溃报告首个 Caused by: 行。
2. 确认 Forge 版本为 1.20.1 的 47.2.0+。
3. 确认 MTR 为 4.0.2-hotfix-1+。
4. 带完整崩溃报告与游戏日志提交 issue。

单人可用但在某服务器上不行

MTR Surveyor 是客户端 mod — 单人能用，服务器就能用。若在特定服务器不出现路径点：

• 服务器必须运行 MTR 且有真实交通网络。
• 部分服务器会节流或延迟 MTR 数据同步。四处走动 / 加载区块以触发 MTR 数据更新，再 /mtrsurveyor syncWaypoints。
• 若服务器运行过旧或过新的 MTR 版本，可能改变了客户端数据 API，同步可能静默失败。查看兼容性矩阵。

如何查看调试输出？

在 .minecraft/config/mtrsurveyor.toml 中设 debugLog = true（运行时编辑文件并重载即可）。每次同步事件都会记录到控制台。排查完请关闭 — 它很吵。

FAQ

支持 Fabric 吗？

不支持。MTR Surveyor 仅支持 Forge 1.20.1。

能在我没有控制权的服务器上用吗？

可以 — 这正是设计初衷。装在自己客户端上，加入任何运行 MTR 的服务器即可。

会向服务器发送任何东西吗？

不会。只读取客户端已收到的 MTR 数据，写入 Xaero 的本地路径点文件。MTR Surveyor 不发任何数据包，无网络流量。

会让游戏卡顿吗？

同步节流为每 5 秒（100 tick）一次，且仅在 MTR 数据实际变化时运行。路线叠加层每帧渲染一次，但使用单次 flush 的缓冲区。典型网络下影响可忽略。

路径点存在哪里？

存在 Xaero 自己的路径点文件中，位于 .minecraft/XaeroWaypoints/。MTR Surveyor 只是调用 Xaero API 增删；它本身不存储任何东西。