导航扩展 API

玩家须知

在 1.5.3 版本中，我们开放了一套公共 API，允许其他模组（比如各种路线规划、寻路模组）直接接入 MTR Map Overlay。

车站卡片上的 Navigate（导航）按钮需要有兼容的第三方导航服务能处理当前车站才会启用。1.6.0 会逐站检查可用性，点击时再确认一次；多个可用服务会显示选择菜单。本模组负责提供目标车站信息并将路径直观地绘制在地图上；具体的换乘规划、行程进度追踪等则由接入的导航模组自己实现。本模组本身不内置寻路算法，也没有绑定任何特定的第三方导航模组。

当导航服务激活时，地图可以高亮显示接下来要乘坐的铁轨区段，同时将已经坐过的路段和无关的背景轨道半透明淡化（线路颜色、高铁斑马纹、抗锯齿边缘和轨道底衬都会同步变暗）。如果稍后的换乘行程需要再次经过同一段轨道，它依然会保持明亮高亮。玩家也可以随时临时切回全图浏览模式，这不会中断当前的导航会话。

开发者接入指引

API 的统一入口类为 io.github.teamcreating.mtrmap.api.MtrMapApi，当前 API 版本为 1.0.0。纯 Java 17 API 的构件路径为 build/api/mtrmap-api-1.0.0.jar。在你的构建脚本中请以 compileOnly 方式引用，切勿使用 Shadow 重复打包或重定位（relocate）API 类。

核心接口一览：

• catalog、tracks、resolve：读取原生路网快照数据、铁轨几何与路径区段解析。
• watchStation：订阅车站的原生到站预测（返回可关闭的 AutoCloseable 订阅句柄）。
• openView：返回一个 ViewSession，用于精确控制铁轨区段的高亮、淡化与独立视图样式。
• registerNavigation：注册车站信息卡上的 Navigate 按钮。如果有多个可处理当前车站的服务，玩家点击时会自动弹出选择列表。

1.6.0 新增 registerNavigation(owner, displayName, available, handler)，通过 Predicate<NavigationTarget> 判断逐站可用性。判定在客户端线程中运行，显示按钮及点击时都会调用，应保持轻量、无副作用。原有三参数重载仍然兼容；如果你的模组也支持旧版 Overlay，记得检测新重载是否可用，并保留旧注册方式。

调用注意事项： 所有客户端操作均应在 Minecraft 客户端主线程中执行；调用前记得检查路网目录（catalog）是否已经加载就绪；用完的会话和订阅句柄请及时调用 close() 关闭释放。断开服务器连接时，视图会话和到站订阅会自动失效，而导航服务的注册则随模组生命周期保持。本 API 不提供寻路器或行车模拟。

完整的接口契约和代码示例请参考 API 实现指南与示例。