兼容性

版本矩阵

组件	要求版本	测试版本
Minecraft	1.20.1	1.20.1
Minecraft Forge	47.x（47.2.0+）	47.2.0
Java（运行时）	17 或更高	17、21
MTR（modId mtr）	≥ 4.0.2-hotfix-1	4.0.2-hotfix-1
Xaero’s Minimap	≥ 25.3.10	25.3.10
Xaero’s World Map	≥ 1.40.11	1.40.11
Gradle（从源码构建）	8.8（已含 wrapper）	8.8

mod 的 mods.toml 把 Minecraft 范围声明为 [1.20.1, 1.21)，Forge loader 范围 [47,)，MTR 范围 [4.0.2-hotfix-1,)。Xaero 系列 mod 声明为 versionRange="*"（任意）、ordering="AFTER"、side="CLIENT"。

缺少某依赖时各功能可用性

你安装了	路径点同步	路线叠加层	说明
MTR + Xaero Minimap + Xaero World Map	✅	✅	完整功能。
MTR + 仅 Xaero Minimap	✅	—	世界地图 mixin 被跳过；mod 安全加载。
MTR + 仅 Xaero World Map	—	✅*	路径点同步需要 Minimap 的 WaypointSet。路线叠加层仍可在世界地图上绘制。
仅 MTR	—	—	mod 正常加载，无可见效果。/mtrsurveyor syncWaypoints 会提示未安装 Xaero。
无 MTR	—	—	没有可映射数据。mod 仍加载。

* 实际使用中几乎总是同时安装两个 Xaero mod — 这才是受支持的配置。

服务端

• 服务端不需要安装 MTR Surveyor。 本 mod 纯客户端。
• 服务端需要运行 MTR（这样 MTR 数据才会流到你的客户端）。服务器没装 MTR，自然没数据可映射。
• 配置文件 mtrsurveyor.toml 注册为 ModConfig.Type.COMMON，两端都会生成，但只有客户端会真正读取。

Java 说明

• mod 编译为 Java 17 字节码（mixin 配置中 compatibilityLevel: "JAVA_17"）。
• 在 Java 21 运行时上运行良好 — CI 构建使用 Temurin 21。
• 从源码构建时，Gradle JVM 应为 17 或 21。

其他地图 mod

MTR Surveyor 专门针对 Xaero 系列 mod。不支持：

• JourneyMap
• BlueMap
• Antique Atlas
• FTB Chunks / FTB Map

原 AmberFrost 仓库中有一个独立的姊妹项目（mtrsurveyor-journeymap）针对 Surveyor Map Framework / Antique Atlas — 与本 Xaero 向分支无关。

从源码构建

git clone https://github.com/BenLi06/mtrsurveyor.git
cd mtrsurveyor
./gradlew build      # 产物：build/libs/CRTools-MTR-Xaero-Mapper-1.0.0.jar

需要 JDK 17 或 21。已附带 Gradle wrapper（8.8）。