Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
<a href="README.md">English</a> ·
<a href="README.zh-CN.md">简体中文</a> ·
<a href="https://mtrmapoverlay.benli06.site/en/">Website &amp; Docs</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3">v1.5.3 Pre-release</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0">v1.6.0 Latest Release</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/snapshot">Snapshots</a>
</p>

Expand All @@ -21,7 +21,7 @@

**MTR Map Overlay** brings your [Minecraft Transit Railway (MTR)](https://github.com/Minecraft-Transit-Railway/Minecraft-Transit-Railway) network into **Xaero's World Map** and **JourneyMap**. It reads MTR data directly without relying on MTR Surveyor, drawing physical tracks, color-coded transit lines, real-time train positions, and interactive station departure boards.

**Supported versions (`v1.5.3`):** Minecraft **1.20.1 / 1.20.4** (Forge & Fabric) and **1.21.1** (NeoForge & Fabric).
**Supported versions (`v1.6.0`):** Minecraft **1.20.1 / 1.20.4** (Forge & Fabric) and **1.21.1** (NeoForge & Fabric).

## Core Features

Expand All @@ -34,20 +34,20 @@
- **Readable Interchanges & Line Styles:** Multiple routes sharing a single track sit side-by-side in parallel color bands instead of overlapping. Light rail renders at 70% width, while high-speed lines feature alternating route-color and white blocks with a continuous border.
- **Whole-Network Live Trains:** When installed on both client and server, the map streams real-time train positions across the entire dimension (~4 Hz). Hovering over a train displays its vehicle model, route, destination, and consist length.
- **Interactive Station PIDS Boards:** Click any station to pin its info card, then click **Expand** to view live upcoming departures by destination, line, and platform. Supports both **British** (black/amber) and **European** (airport-style) themes via `/mtrmap config pidsStyle british|european`.
- **Client-Only Fallback:** Works out of the box on vanilla/unmodded MTR servers using nearby chunk data sent by MTR. Installing the mod on the server unlocks full-dimension snapshots, global live trains, and live station arrivals.
- **Client-Only Fallback:** Works on MTR servers without Overlay using nearby data sent by MTR. Installing the mod on the server unlocks full-dimension snapshots, global live trains, and live station arrivals.

## What's New in v1.5.3
## What's New in v1.6.0

> **Release Status:** [v1.5.3](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) is currently marked as a **pre-release** ([v1.5.2](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.2) remains the latest stable build). Full-map live trains and station arrival boards require matching `1.5.3` builds on both client and server.
> **Release Status:** [v1.6.0](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0) is the **latest stable release**, available for all six supported builds. Full-map live trains and station arrival boards require matching `1.6.0` builds on both client and server.

- **Pinned Stations & Live Arrivals:** Expand station cards to subscribe to live PIDS departure countdowns directly from MTR/TSC. Missing predictions are explicitly shown as `-` rather than `0 min`.Closing the map or collapsing the card automatically releases the network subscription.
- **Switchable PIDS Themes:** Toggle between `british` and `european` board styles; preferences persist across restarts.
- **Navigation Extension API (Java 17):** Exposes network catalogs, station-board subscriptions, and isolated map view sessions for third-party route planners. When a compatible planner mod is installed, clicking **Navigate** highlights upcoming route segments and dims completed or unused tracks. See the [Public API Guide](docs/api/overlay-api-v1.md) for `MtrMapApi` integration details.
- **UI & Decode Optimizations:** Station cards capture scroll and click events cleanly without dragging the underlying map, backed by bounded queues and background packet decoding.
- **Availability-Aware Navigate:** The station card checks which registered providers can handle the selected station. No available provider means a dimmed button; multiple available providers show a chooser, with availability checked again on click.
- **Compatible Navigation API (Java 17):** Third-party mods can register a per-target availability predicate while keeping the original registration overload. Providers supply navigation and can highlight upcoming route segments while dimming completed or unused tracks. See the [Public API Guide](docs/api/overlay-api-v1.md).
- **Four Interface Languages:** English, Simplified Chinese, Traditional Chinese and Japanese cover map controls, PIDS boards, tooltips, commands and diagnostic feedback. The interface follows Minecraft's language; player-defined station and route names stay unchanged.
- **Provider & UI Improvements:** Closed, stale or failing providers cannot be invoked, and one provider's failure does not disable others. Map labels and PIDS style names are localized; native arrivals, both PIDS themes, whole-map trains and 2D rendering remain available.

## Navigation integration and languages

Development builds add an optional HowToGo destination handoff, per-station Navigate availability checks and English, Simplified Chinese, Traditional Chinese and Japanese controls. No available provider means Navigate is dimmed; multiple providers show a chooser. See the [integration verification](docs/validation/howtogo-navigation-i18n-2026-11-11.md).
1.6.0 provides the generic Navigate API; compatible third-party mods supply their own adapters and route planners. Only providers available for the selected station appear in the chooser. The interface follows your game language, while command names such as `/mtrmap config pidsStyle` remain unchanged. See the [Public API Guide](docs/api/overlay-api-v1.md) for integration details.

## Requirements & Installation

Expand All @@ -59,7 +59,7 @@ Development builds add an optional HowToGo destination handoff, per-station Navi

*Note: Xaero's Minimap is not required; if present, it is only used to clean up legacy `[MTR]` waypoints from older releases.*

1. Download the JAR matching your exact Minecraft version and mod loader from [Releases](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) and drop it into your client's `mods` folder.
1. Download the JAR matching your exact Minecraft version and mod loader from [Releases](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0) and drop it into your client's `mods` folder.
2. Install the matching **MTR** build and at least one supported map mod (**Xaero's World Map** or **JourneyMap**). Fabric users must also install **Fabric API**.
3. *(Optional, Recommended)* Install the matching **MTR Map Overlay** JAR on the server to enable full-dimension route snapshots, whole-map live trains, and live station boards. *(Note: Both sides now use the `mtrmap` mod ID; remove any legacy `mtrsurveyor` JARs before upgrading.)*
4. Open your fullscreen map. Use the `ROUTES` and `TRACKS` buttons on the map toolbar (green indicator = enabled, red = disabled) or client commands to toggle layers.
Expand Down Expand Up @@ -92,16 +92,16 @@ All `/mtrmap` commands register on the **client** and work on any server:

- **Rendering & Caching:** Both map integrations render fixed 2D layers from bottom to top: physical rail backing → colored routes → live train cars → station/platform icons. Static rail/route geometry is cached separately from dynamic train poses with viewport prefetching (see [planar cache validation](docs/validation/planar-cache.md)).
- **Network Protocol:** Full-map train sync uses compact 24-byte per-car coordinate frames relative to a shared train origin, avoiding repeated string metadata (see [global train validation](docs/validation/global-trains.md)). In singleplayer, Xaero keeps the integrated server unpaused while the live train layer is active so train movement continues updating.
- **Known Limitations:** In `1.5.3` validation, Forge 1.20.4 singleplayer quick-play experienced a disconnect during Xaero server-data initialization (dedicated server tests passed). See [1.5.3 validation notes](docs/validation/pids-and-dimmed-1.5.3.md) and [v1.5.3 release notes](docs/releases/v1.5.3.md) for test coverage details.
- **Compatibility & Validation:** 1.6.0 fixes the earlier Forge 1.20.4 singleplayer loading issue and Forge 1.20.1 connections to servers without Overlay. If Forge 1.20.1 launcher quick-play times out, join through the normal multiplayer server list. See the [runtime record](docs/validation/release-1.6.0.md) and [published-build verification](docs/validation/release-1.6.0-replacement.md) for coverage and remaining limits.

## Building from Source

Requires a **Java 21** toolchain. The `main` branch targets **Minecraft 1.21.1**; for `1.20.1` and `1.20.4` builds, switch to the [`compat/mtr-4.0-mc-1.20`](https://github.com/teamCreating/MTR-Map-Overlay/tree/compat/mtr-4.0-mc-1.20) branch.

| Loader | Windows | macOS / Linux | Output Artifact |
| :--- | :--- | :--- | :--- |
| **NeoForge** | `.\gradlew.bat build` | `./gradlew build` | `build/libs/CRTools-MTR-Map-Overlay-1.5.3.jar` |
| **Fabric** | `.\fabric\gradlew.bat -p fabric build` | `./fabric/gradlew -p fabric build` | `fabric/build/libs/CRTools-MTR-Map-Overlay-fabric-1.5.3.jar` |
| **NeoForge** | `.\gradlew.bat build` | `./gradlew build` | `build/libs/CRTools-MTR-Map-Overlay-1.6.0.jar` |
| **Fabric** | `.\fabric\gradlew.bat -p fabric build` | `./fabric/gradlew -p fabric build` | `fabric/build/libs/CRTools-MTR-Map-Overlay-fabric-1.6.0.jar` |

### Architecture Overview

Expand Down
25 changes: 13 additions & 12 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
<a href="README.md">English</a> ·
<a href="README.zh-CN.md">简体中文</a> ·
<a href="https://mtrmapoverlay.benli06.site/zh/">官网与文档</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3">v1.5.3 预览版</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0">v1.6.0 正式版</a> ·
<a href="https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/snapshot">快照构建</a>
</p>

Expand All @@ -21,7 +21,7 @@

**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 到站看板。

**当前支持版本(`v1.5.3`):** Minecraft **1.20.1 / 1.20.4**(Forge & Fabric)以及 **1.21.1**(NeoForge & Fabric)。
**当前支持版本(`v1.6.0`):** Minecraft **1.20.1 / 1.20.4**(Forge & Fabric)以及 **1.21.1**(NeoForge & Fabric)。

## 核心特性

Expand All @@ -36,14 +36,14 @@
- **交互式车站 PIDS 看板**:点击任意车站可固定信息卡片,点击 **Expand(展开)** 即可实时查看各站台、各线路的列车到站倒计时。支持通过 `/mtrmap config pidsStyle british|european` 切换英式(黑底琥珀字)与欧式(机场风格)显示屏主题。
- **纯客户端兼容**:若服务端未安装本模组,客户端依然可以利用 MTR 同步的周围区块数据正常渲染附近路网;在服务端安装本模组后即可解锁全图路网快照、全图实时列车与实时到站预测。

## v1.5.3 更新亮点
## v1.6.0 更新亮点

> **版本状态说明:** [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` 构建。
> **版本状态说明:** [v1.6.0](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0) 已作为**最新稳定版**发布,六个平台均有对应构建。全图实时列车与车站到站看板需要客户端与服务端同时安装相同版本的 `1.6.0` 构建。

- **固定车站卡片与实时到站(PIDS)**:直接接入 MTR/TSC 的 PIDS 接口获取预计到站时间;无预测数据时明确显示为 `-` 而非 `0 分钟`。收起卡片或关闭地图时会自动释放订阅。
- **PIDS 主题切换**:新增 `british`(默认)与 `european` 两种车站看板样式,修改后自动保存。
- **导航扩展 API(Java 17)**:面向第三方寻路/导航模组开放 `MtrMapApi`,支持读取路网目录、订阅车站看板及创建独立的地图高亮视图。当安装了兼容的第三方导航插件时,点击 **Navigate** 即可高亮前方乘车区间并压暗已驶过或无关的轨道(详见 [API 接入指南](docs/api/overlay-api-v1.md))。
- **交互与解码优化**:固定后的车站卡片支持独立内部滚动与点击,不会误触底层地图拖拽;网络包采用后台解码与有界队列以减少主线程开销。
- **逐站 Navigate 可用性检查**:车站卡片会检查哪些已注册服务能处理当前车站。没有可用服务时按钮淡显;多个可用服务时显示选择器,点击时再确认一次。
- **兼容的导航 API(Java 17)**:第三方模组可注册逐目标可用性判定,原有注册重载继续兼容。具体导航由外部模组提供,并可高亮待乘区段、淡化已走或无关轨道(详见 [API 接入指南](docs/api/overlay-api-v1.md))。
- **四语言界面**:英文、简体中文、繁体中文与日语覆盖地图控件、PIDS 看板、提示、命令和诊断反馈,跟随 Minecraft 的语言设置;玩家自定义站名、线路名保持原样。
- **服务与界面优化**:关闭、过期或异常服务不会被调用,单个服务出错不会影响其他服务。补全地图标签与 PIDS 样式名翻译,保留原生到站板、双 PIDS 主题、全图列车和 2D 绘制。

## 环境要求与安装

Expand All @@ -55,7 +55,7 @@

*注:无需安装 Xaero's Minimap(小地图);若已安装,本模组仅会用它来清理早期版本遗留的 `[MTR]` 旧路径点。*

1. 前往 [Releases](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.5.3) 下载与你的 **MC 版本 + 加载器** 完全匹配的单个 JAR 文件,放入客户端 `.minecraft/mods` 目录(文件名中已标明对应的加载器与 MTR 版本)。
1. 前往 [Releases](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0) 下载与你的 **MC 版本 + 加载器** 完全匹配的单个 JAR 文件,放入客户端 `.minecraft/mods` 目录(文件名中已标明对应的加载器与 MTR 版本)。
2. 安装对应版本的 **MTR** 与任意一款支持的地图模组(Fabric 环境需额外安装 **Fabric API**)。
3. *(可选但推荐)* 在服务端同样放入匹配的 **MTR Map Overlay** JAR 文件,以启用全维度路网同步、全图实时列车与车站到站看板。*(注意:新版 Mod ID 已统一为 `mtrmap`,升级前请删除旧版 `mtrsurveyor` 文件。)*
4. 进入游戏并打开全屏地图,可通过地图界面上的 `ROUTES`(线路)和 `TRACKS`(轨道)图标按钮(绿条为开启,红条为关闭)或客户端指令控制图层显示。
Expand Down Expand Up @@ -89,15 +89,16 @@

| 加载器 | Windows | macOS / Linux | 构建产物路径 |
| :--- | :--- | :--- | :--- |
| **NeoForge** | `.\gradlew.bat build` | `./gradlew build` | `build/libs/CRTools-MTR-Map-Overlay-1.5.3.jar` |
| **Fabric** | `.\fabric\gradlew.bat -p fabric build` | `./fabric/gradlew -p fabric build` | `fabric/build/libs/CRTools-MTR-Map-Overlay-fabric-1.5.3.jar` |
| **NeoForge** | `.\gradlew.bat build` | `./gradlew build` | `build/libs/CRTools-MTR-Map-Overlay-1.6.0.jar` |
| **Fabric** | `.\fabric\gradlew.bat -p fabric build` | `./fabric/gradlew -p fabric build` | `fabric/build/libs/CRTools-MTR-Map-Overlay-fabric-1.6.0.jar` |

## 常见问题排查 (Troubleshooting)

- **地图上只显示附近的车站和轨道**:服务端未安装本模组(或双端版本不一致),此时客户端会自动回退为仅显示 MTR 默认同步半径内的数据。
- **Xaero 地图上没有任何线条**:请确认安装的是 **Xaero's World Map(世界地图)** 而非仅有小地图,并检查 `latest.log` 中是否输出了 `Path layer render hook into Xaero's World Map is active`。
- **小地图或游戏画面里没有路径点**:这是正常设计。所有图标仅绘制在全屏大地图上,避免遮挡日常游戏视野。
- **从旧版 `mtrsurveyor` 升级失败**:请先删掉 `mods` 文件夹里的旧版 `mtrsurveyor` JAR 包,切勿新旧混装。
- **Forge 快速进入问题**:1.6.0 已修复 Forge 1.20.4 单人加载和 Forge 1.20.1 连接未装 Overlay 服务器的问题。若 Forge 1.20.1 启动器自动直连超时,可改用游戏内多人服务器列表连接;验证范围见[实机记录](docs/validation/release-1.6.0.md)和[发布包检查](docs/validation/release-1.6.0-replacement.md)。

## 支持开发

Expand All @@ -113,4 +114,4 @@

## 导航对接与多语言

开发版新增可选 HowToGo 目的地转交和逐站 Navigate 可用性检查,无可用服务时淡显,多个可用服务时显示选择器。控件支持英文、简体中文、繁体中文和日语。见[对接验证](docs/validation/howtogo-navigation-i18n-2026-11-11.md)。
1.6.0 提供通用 Navigate API,具体适配与路线规划由兼容的第三方模组提供。选择器只列出能处理当前车站的服务。界面跟随游戏语言,`/mtrmap config pidsStyle` 这类命令名称保持不变。接入细节见 [API 指南](docs/api/overlay-api-v1.md)。
2 changes: 2 additions & 0 deletions docs/agents/MESSAGES.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# MESSAGES.md — Agent 交流墙(只追加,不改不删)

- 2026-11-11T17:44:00+08:00 (UTC+08:00), Codex: Updated both READMEs to stable 1.6.0 with per-station provider availability, optional registration extension and four in-game languages. Removed stale built-in HowToGo/development-copy claims; retained layout, existing core features and badges. Corrected old compatibility notes and build artifact examples. Markdown renders and 30 relative-link checks passed; see root walkthrough.md. Runtime code, release assets and tags were not modified.

- 2026-11-11T17:26:03+08:00, Codex: PR integration conflicts resolved; old PR21/22 evidence and diagnostics are all preserved byte-for-byte. New replacement evidence is additional. Close superseded old PRs; merge refreshed PR27/28 after CI. Release assets, tags and production code remain unchanged.

- 2026-11-11T17:11:24+08:00, Codex: Replaced [v1.6.0](https://github.com/teamCreating/MTR-Map-Overlay/releases/tag/v1.6.0) on explicit user instruction. Candidate42991712783 / protected Publish42992406825 attempt3 passed. Ten replacement public downloads match candidate/digests; both tags match new sealed sources. Six-JAR audit confirms only adapter removal; generic API and Forge49 guard preserved. Public notes exactly match the requested 1.5.3 structure. See [replacement verification](../validation/release-1.6.0-replacement.md).
Expand Down
Loading
Loading