Navigation API

Starting in 1.5.3, MTR Map Overlay includes a public Java API. It allows other mods (like transit navigation or route planning mods) to hook into the overlay, read network data, subscribe to arrival boards, and highlight active routes on the map.

For players

When you click on a station card, you’ll see a Navigate button.

MTR Map Overlay itself is a map visualizer, not a turn-by-turn route planner. If a compatible navigation provider can handle the selected station, clicking Navigate will open that provider. If more than one provider is available for the station, a menu lets you pick which one to use. If none is available, the button is simply disabled. In 1.6.0, availability is checked again when you click.

When navigating a route, supported navigation mods can dim inactive tracks while keeping your active train lines brightly highlighted.

For developers

The API is packaged as pure Java 17 under io.github.teamcreating.mtrmap.api.MtrMapApi (API version 1.0.0).

Adding the dependency

Add the API JAR (build/api/mtrmap-api-1.0.0.jar) to your project as a compileOnly dependency.

[!IMPORTANT] Do not shade or jarjar the API classes into your mod JAR. The classes are provided at runtime by MTR Map Overlay.

Core API features

• catalog & tracks: Access network snapshots, stations, routes, and sampled track splines. Check catalog readiness before querying data.
• resolve: Map route stops and path variants to concrete track sections.
• watchStation: Subscribe to live MTR/TSC arrival predictions for a station. Returns an AutoCloseable subscription handle — be sure to close it when the player closes your UI.
• openView: Create a ViewSession to customize map rendering for navigation. You can highlight upcoming journey legs while dimming completed sections and background rails. Route colors, high-speed dashes, and track outlines all dim smoothly together.
• registerNavigation: Register your mod as a navigation provider so users can trigger your route planner directly from the station card’s Navigate button.

In 1.6.0, registerNavigation(owner, displayName, available, handler) adds a Predicate<NavigationTarget> for per-station availability. Keep this check cheap and side-effect free; it runs on the client thread while rendering and again on click. The original three-argument overload remains compatible. If your integration also supports older Overlay builds, guard the optional overload and retain the old registration path.

Best practices

• Run client-facing calls on the Minecraft client main thread.
• Always close subscriptions and ViewSession handles when your UI closes or journeys complete.
• All sessions and subscriptions are automatically invalidated when the player disconnects from a server, but provider registrations persist across world joins.

For code examples, method signatures, and lifecycle rules, check out the full API implementation guide.