-MTR Map Overlay 将 Minecraft Transit Railway 的路线、真实轨道、实时列车、原生到站预测与地图专属地标显示在 Xaero's World Map 和 JourneyMap 中。**v1.5.3 支持 Minecraft 1.20.1、1.20.4 的 Forge/Fabric，以及 1.21.1 的 NeoForge/Fabric。**它直接读取 [Minecraft Transit Railway（MTR）](https://github.com/Minecraft-Transit-Railway/Minecraft-Transit-Railway) 数据，不依赖 MTR Surveyor 的地图。
-
-## 功能
-
-| 地图 | 显示内容 |
-| --- | --- |
-| Xaero's World Map | 真实轨道、路线色带、实时列车、站点／站台／车辆段图标，以及可固定并显示原生预测的站点框。 |
-| JourneyMap | 全屏轨道、共线色带、实时列车和原生到站板；提供独立 TRACKS／ROUTES 控件，适配 JourneyMap 5／6。 |
-
-这些是**地图内图标**，不是普通 Xaero 路标，不会挤满路标列表、指南针、小地图或游戏内 HUD。同一条物理轨道有多条路线时，颜色并排显示，不再互相覆盖。两种地图都先绘制轨道，再叠加路线，最后绘制站点与站台图标。JourneyMap 整层跟随地图实时拖动和缩放；轨道宽度与 Xaero 使用相同缩放规则，共线整束保留最小宽度。
-
-客户端和服务端都安装本 mod 时，可按维度获取**全网快照**。如果服务端没有安装，本 mod 仍可工作，但只能显示 MTR 已同步到客户端的附近数据。Xaero 与 JourneyMap 都是可选集成，可以只装其中一个，也可以同时安装。
-
-## 1.5.3 新功能
-
-- **固定站点与原生预测**：点击车站后用 **Expand** 按目的地、线路和站台查看后续班次。预测直接使用 MTR/TSC 的 PIDS 接口，缺失数据明确提示。
-- **英式与欧式 PIDS**：默认黑底琥珀字，可用 `/mtrmap config pidsStyle british|european` 切换并保存欧式／机场风格。
-- **导航扩展**：公共 Java 17 API 提供原生路网目录、站点到站板订阅和独立地图视图。注册第三方服务后启用 **Navigate**，规划与行程进度由第三方提供；可高亮待乘区段，分别淡化已走和未用轨道，包含高铁白块及底衬。
-- **交互优化**：保留原站点信息，默认折叠，面板点击／滚动不误触地图；共享预测采集、队列限额和后台解码减少重复工作。
-
-**发布状态（2026-10-31）：**GitHub 当前将 [v1.5.3](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) 标记为**预发布**，[v1.5.2](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.2) 为最新稳定版。六个 1.5.3 构建均提供上述功能；原生预测和全图列车需要匹配的客户端与服务端版本。
-
-### 站点到站板与导航 API
+**MTR Map Overlay** 可将 [Minecraft Transit Railway (MTR)](https://github.com/Minecraft-Transit-Railway/Minecraft-Transit-Railway) 的交通网络直接渲染至 **Xaero's World Map（Xaero 的世界地图）** 与 **JourneyMap（旅行地图）**。本模组直接读取 MTR 原生数据（不依赖 MTR Surveyor），支持显示物理铁轨、彩色运营线路、实时运行的列车位置以及交互式车站 PIDS 到站看板。
-点击车站固定原站点／站台／线路信息框，通过 **Expand** 请求原生预测；**Collapse**、关闭地图或断线会释放订阅。表格显示目的地、线路、站台和右对齐倒计时，无预测为横杠，不表示零分钟。样式即时生效并在重启后保留。
+**当前支持版本（`v1.5.3`）：** Minecraft **1.20.1 / 1.20.4**（Forge & Fabric）以及 **1.21.1**（NeoForge & Fabric）。
-**Navigate 需要兼容的第三方导航服务。**一个服务直接打开，多个服务显示选择器，无服务时不可用。Overlay 不内置规划器。独立视图会话可按精确原生路径区段高亮，不修改共用路网数据。[公共 API 指南](docs/api/overlay-api-v1.md) 包含 `MtrMapApi`、Java 17 `compileOnly` 用法和生命周期规则；独立 API 产物从源码构建，不属于六个模组 JAR 附件。
+## 核心特性
-### 线路样式与全图列车
+| 地图模组 | 支持的叠加层功能 |
+| :--- | :--- |
+| **Xaero's World Map** | 物理铁轨、彩色线路带、实时列车、车站/站台/车厂图标，以及可固定的车站实时到站信息卡（PIDS）。 |
+| **JourneyMap** | 全屏物理铁轨、共线彩色线路带、实时列车与车站信息板；在工具栏提供独立的 `TRACKS` 与 `ROUTES` 图层开关（兼容 JourneyMap 5 & 6）。 |
-轻铁为标准宽度的 70%；普通铁路与高铁等宽，高铁使用连续线路色描边内的彩白交替块。原生自适应曲线、共线接头和随地图缩放的线宽在两地图中保持一致。这些功能由 1.5.2 引入，并在 1.5.3 中保留。
+- **纯净的全屏地图图标**：车站、站台与车厂仅作为地图图层绘制，**不会**往 Xaero 路径点列表、罗盘、小地图或游戏画面 HUD 里塞满坐标点。
+- **共线并排与多制式区分**：多条线路共用同一段铁轨时，会以并排色带绘制而不会互相遮盖。轻轨采用 70% 标准宽度渲染；高铁则采用“线路色+白块”交替样式并带有连续外边框。
+- **全维度实时列车**：当服务端与客户端同时安装本模组时，打开地图即可按约 4 Hz 频率同步当前维度的全部运行列车。鼠标悬停在车厢上可查看车型名称、所属线路、终点站及编组节数。
+- **交互式车站 PIDS 看板**：点击任意车站可固定信息卡片，点击 **Expand（展开）** 即可实时查看各站台、各线路的列车到站倒计时。支持通过 `/mtrmap config pidsStyle british|european` 切换英式（黑底琥珀字）与欧式（机场风格）显示屏主题。
+- **纯客户端兼容**：若服务端未安装本模组，客户端依然可以利用 MTR 同步的周围区块数据正常渲染附近路网；在服务端安装本模组后即可解锁全图路网快照、全图实时列车与实时到站预测。
-### 全网车厢（1.5.2）
+## v1.5.3 更新亮点
-服务端和客户端安装匹配的 1.5.3 后，在任意地图订阅当前查看维度的所有实时列车，目标更新频率 4Hz；拖动、缩放地图不限制同步范围。客户端只对 TSC 参考点做插值、绘制抽象车厢，不还原侧倾、不运行第二套行车模拟。悬停显示可用的车型名称、当前线路、终点和编组节数；原生元数据缺失时明确留空，不猜测线路。默认开启，可用 `/mtrmap config trainCars false` 关闭。
+> **版本状态说明：** [v1.5.3](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) 目前标记为 **Pre-release（预览版）**，最新稳定版为 [v1.5.2](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.2)。全图实时列车与车站到站看板需要客户端与服务端同时安装相同版本的 `1.5.3` 构建。
-地图状态区分全图、加载中、过期和仅附近回退。每节两点 XYZ 为 24 字节，每列另带 double 精度局部原点；高频位置帧不为每节重复文字或维度。服务器不支持独立车辆协议时才使用 MTR 附近数据。启用实时列车层时，Xaero 单机地图保持世界运行，让 TSC 能持续更新。实测证据与性能边界见[全网列车验证](docs/validation/global-trains.md)。
+- **固定车站卡片与实时到站（PIDS）**：直接接入 MTR/TSC 的 PIDS 接口获取预计到站时间；无预测数据时明确显示为 `-` 而非 `0 分钟`。收起卡片或关闭地图时会自动释放订阅。
+- **PIDS 主题切换**：新增 `british`（默认）与 `european` 两种车站看板样式，修改后自动保存。
+- **导航扩展 API（Java 17）**：面向第三方寻路/导航模组开放 `MtrMapApi`，支持读取路网目录、订阅车站看板及创建独立的地图高亮视图。当安装了兼容的第三方导航插件时，点击 **Navigate** 即可高亮前方乘车区间并压暗已驶过或无关的轨道（详见 [API 接入指南](docs/api/overlay-api-v1.md)）。
+- **交互与解码优化**：固定后的车站卡片支持独立内部滚动与点击，不会误触底层地图拖拽；网络包采用后台解码与有界队列以减少主线程开销。
-轨道保留真实 Y，静态协议 v8 传输 double XYZ 与原生曲线，独立车辆协议为 v1，mod 版本为 1.5.3。Xaero 与 JourneyMap 均按“轨道底衬→线路颜色/白块→车厢”固定顺序绘制纯 2D 图层，不按高度细分或排序；铁路不会遮住车厢及其悬停目标。
+## 环境要求与安装
-静态轨道/线路与动态车厢分开缓存，支持视口预取、失效检查和保留上限，减少逐帧重建。正确性检查及无头几何测试见[缓存验证](docs/validation/planar-cache.md)，其中结果不代表游戏 FPS。
+| Minecraft | 加载器 (Loader) | Java | MTR 版本要求 | 兼容的地图模组（任选其一或同时安装） |
+| :--- | :--- | :--- | :--- | :--- |
+| **1.21.1** | NeoForge 21.1.x / Fabric (+ Fabric API) | 21 | `4.1.0-beta.2` | Xaero's World Map `1.45.0+` / JourneyMap `6.0.8+` |
+| **1.20.1** | Forge 47.x / Fabric (+ Fabric API) | 17+ | `>=4.0.5, <4.1` | Xaero's World Map `1.45.0+` / JourneyMap `6.0.6+` |
+| **1.20.4** | Forge 49.x / Fabric (+ Fabric API) | 17+ | `>=4.0.5, <4.1` | Xaero's World Map `1.45.0+` / JourneyMap `5.10.0` |
-## 依赖与安装
+*注：无需安装 Xaero's Minimap（小地图）；若已安装，本模组仅会用它来清理早期版本遗留的 `[MTR]` 旧路径点。*
-| Minecraft | 加载器 | Java | MTR | 可选地图 |
-| --- | --- | --- | --- | --- |
-| 1.21.1 | NeoForge 21.1.x 或 Fabric + Fabric API | 21 | 4.1.0-beta.2 | Xaero's World Map 1.45.0+ / JourneyMap 6.0.8+ |
-| 1.20.1 | Forge 47.x 或 Fabric + Fabric API | 17+ | >=4.0.5, <4.1 | Xaero's World Map 1.45.0+ / JourneyMap 6.0.6+ |
-| 1.20.4 | Forge 49.x 或 Fabric + Fabric API | 17+ | >=4.0.5, <4.1 | Xaero's World Map 1.45.0+ / JourneyMap 5.10.0 |
+1. 前往 [Releases](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) 下载与你的 **MC 版本 + 加载器** 完全匹配的单个 JAR 文件，放入客户端 `.minecraft/mods` 目录（文件名中已标明对应的加载器与 MTR 版本）。
+2. 安装对应版本的 **MTR** 与任意一款支持的地图模组（Fabric 环境需额外安装 **Fabric API**）。
+3. *（可选但推荐）* 在服务端同样放入匹配的 **MTR Map Overlay** JAR 文件，以启用全维度路网同步、全图实时列车与车站到站看板。*（注意：新版 Mod ID 已统一为 `mtrmap`，升级前请删除旧版 `mtrsurveyor` 文件。）*
+4. 进入游戏并打开全屏地图，可通过地图界面上的 `ROUTES`（线路）和 `TRACKS`（轨道）图标按钮（绿条为开启，红条为关闭）或客户端指令控制图层显示。
-所有依赖都必须匹配 Minecraft 版本及加载器。Xaero's Minimap 为可选依赖，只用于清理旧版本创建的 `[MTR]` 路标。
+## 指令与配置
-1. 从 [v1.5.3 预发布版](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) 下载与 Minecraft 版本及加载器完全匹配的 **一个 JAR**，放入客户端 `mods` 目录。发布包含六个 JAR：两个 `MC1.21.1` NeoForge/Fabric 构建，以及四个 `MC1.20.1` / `MC1.20.4` Forge/Fabric 构建，所有文件名均标明对应的 MTR 测试版本。
-2. 安装同一加载器的 MTR 和所需地图 mod；Fabric 还必须安装 Fabric API。
-3. 如需全网地图，可选地在服务器安装对应加载器版本的 MTR Map Overlay 和 MTR。客户端与服务端都必须使用新的 `mtrmap` mod ID；旧的 `mtrsurveyor` 版本与本版不兼容。
-4. 打开 Xaero's World Map 或 JourneyMap 全屏地图。两端使用配套的 `ROUTES`、`TRACKS` 图标：左侧亮条绿色表示开、红色表示关；JourneyMap 的按钮位于附加按钮栏。`/mtrmap config routeLines` 和 `trackLines` 也对两种地图生效。悬停在线路或图标上可查看详情。
+所有 `/mtrmap` 指令均在**客户端**注册，即使服务端未安装本模组也可正常使用：
-全图列车需要客户端和服务端都更新本版；仅客户端安装时使用附近回退。六个平台已通过 Xaero/JourneyMap 开发环境实机回归，测试覆盖与限制见[1.5.3 验证记录](docs/validation/pids-and-dimmed-1.5.3.md)。
-
-**已知限制：Forge 1.20.4 单人 quick-play 测试时在 Xaero 服务端地图数据初始化阶段断线。**该目标连接独立服务器后的双地图 PIDS 测试通过，不能据此声称单人启动已通过。详见[1.5.3 验证记录](docs/validation/pids-and-dimmed-1.5.3.md)与[发布说明](docs/releases/v1.5.3.md)。
-
-## 命令与配置
-
-命令在**客户端**注册，连接没有安装本 mod 的服务器时也能使用。
-
-| 命令 | 作用 |
-| --- | --- |
-| `/mtrmap syncRoutes` | 在服务器支持时请求全网快照。 |
-| `/mtrmap syncLandmarks` | 刷新 JourneyMap 地标。 |
-| `/mtrmap testMarker` | 在玩家当前位置放置 JourneyMap 测试标记。 |
-| `/mtrmap mode station\|platform\|both` | 选择纯客户端回退时显示的地标类型。 |
-| `/mtrmap config enabled 
+ 
- 
+ 