MTR Map Overlay

Render Minecraft Transit Railway routes, physical tracks, live trains, and station arrival boards directly on your fullscreen map.

English · 简体中文 · Website & Docs · v1.6.0 Latest Release · Snapshots

MTR Map Overlay brings your Minecraft Transit Railway (MTR) 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.6.0): Minecraft 1.20.1 / 1.20.4 (Forge & Fabric) and 1.21.1 (NeoForge & Fabric).

Core Features

Map Mod	Supported Overlay Features
Xaero's World Map	Physical rails, route ribbons, live train cars, station/platform/depot markers, and pinned station cards with live PIDS arrivals.
JourneyMap	Fullscreen rails, shared-route bands, live train cars, and station boards. Includes dedicated TRACKS and ROUTES toolbar toggles (supports JourneyMap 5 & 6).

• Clean Map-Only Markers: Stations, platforms, and depots are rendered strictly on the fullscreen map. They never clutter your Xaero waypoint list, compass, minimap, or in-world HUD.
• 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 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.6.0

Release Status: 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.

• 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.
• 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

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 for integration details.

Requirements & Installation

Minecraft	Loader	Java	MTR Version	Supported Map Mods (Pick one or both)
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

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 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.

Commands & Configuration

All /mtrmap commands register on the client and work on any server:

Command	Description
/mtrmap syncRoutes	Request a full-dimension network snapshot from the server.
/mtrmap syncLandmarks	Refresh JourneyMap landmark overlays.
/mtrmap testMarker	Place a diagnostic marker at your current position in JourneyMap.
/mtrmap mode station|platform|both	Set landmark display mode when running in client-only fallback mode.
/mtrmap config enabled <true|false>	Master toggle for the entire map overlay.
/mtrmap config routeLines <true|false>	Show or hide colored route ribbons.
/mtrmap config trackLines <true|false>	Show or hide physical rail tracks.
/mtrmap config trainCars <true|false>	Show or hide live trains (default: true).
/mtrmap config showStations <true|false>	Show or hide station icons.
/mtrmap config showPlatforms <true|false>	Show or hide platform icons.
/mtrmap config showDepots <true|false>	Show or hide depot icons.
/mtrmap config pidsStyle [british|european]	Switch or query the station departure board theme (default: british).

Configuration Files:

• NeoForge / Forge: Stored in config/mtrmap.toml (automatically migrates settings from legacy mtrsurveyor.toml on first launch).
• Fabric: Stored in config/mtrmap.properties.
• Key settings include networkSync.enabled (default true), networkSync.refreshIntervalSeconds (default 300), and layer visibility defaults.

Technical Notes & Validation

• 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).
• 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). In singleplayer, Xaero keeps the integrated server unpaused while the live train layer is active so train movement continues updating.
• 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 and published-build verification 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 branch.

Loader	Windows	macOS / Linux	Output Artifact
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

Shared and NeoForge sources live under src/main/java/io/github/teamcreating/mtrmap, while fabric/ provides Fabric-specific entry points and hooks that compile against the shared codebase.

Package / Directory	Responsibility
mapdata/	MapDataCache manages server snapshots and nearby client fallback data. TrackSampler samples rail geometry, TrackRoutePalette assigns non-overlapping color bands, and MapTrack handles viewport culling bounds.
network/	Handles chunked snapshot transfer (NetworkSnapshotCodec, NetworkChunkAssembler), background simulator polling (ServerNetworkCollector), live train frames, and station PIDS subscriptions.
integration/xaero/	XaeroRouteRenderer draws tracks, route ribbons, trains, and interactive station cards in Xaero world-map coordinates.
integration/journeymap/	JourneyMap v2 plugin (JourneyMapToolbar, JourneyMapScreenProjection, JourneyMapPathManager, JourneyMapForegroundRenderer).
mixin/	Accessors for MTR internal data and Xaero world-map render hooks.
config/	Loader-specific config serialization, client command registration, and networking bootstrap.

Troubleshooting

• Only nearby stations or tracks appear: The server does not have MTR Map Overlay installed (or versions are mismatched), so the client is falling back to MTR's local sync radius.
• Lines do not appear on Xaero's World Map: Verify Xaero's World Map (not just Minimap) is installed and check latest.log for Path layer render hook into Xaero's World Map is active.
• No waypoints on the minimap: By design. All icons are rendered exclusively on the fullscreen map to prevent HUD clutter.
• Upgrading from mtrsurveyor: Delete the old mtrsurveyor JAR from mods/. The mod ID and command prefix are now mtrmap and /mtrmap.

Support Development

If MTR Map Overlay makes managing your transit network easier, consider supporting development on Ko-fi or Afdian:

License & Attribution

Licensed under the MIT License. Original copyright and attribution for AmberFrost's contributions are preserved in LICENSE and the Git commit history; subsequent development is maintained by BenLi06.