How it works · MTR Map Overlay

Curious about what’s happening under the hood? Here’s a look at how MTR Map Overlay pulls network data from MTR, syncs it over the network, and draws it onto Xaero’s World Map and JourneyMap.

Data pipeline

The mod maintains an in-memory cache of transit data split by dimension:

MTR server snapshot ──┐
                      ├──> Dimension cache ──> Xaero's World Map renderer
MTR local client data─┘                    └──> JourneyMap renderer

Full server sync vs. Client fallback

With server mod installed: Your client periodically checks dimension content hashes with the server. If routes or tracks changed, the server packages the updated network (tracks, routes, stations, and depots), splits it into chunks, and streams it to your client. Background threads decode the snapshot so your game never stutters.
Client-only fallback: If the server doesn’t have MTR Map Overlay, your client falls back to reading whatever local MTR data has already been sent to your client for nearby chunks.

Both map integrations (Xaero and JourneyMap) read directly from this shared dimension cache. If one map mod is missing, the mod simply skips it.

Separate sync channels

Not all transit data changes at the same rate. MTR Map Overlay splits communication into three separate channels so static tracks don’t clog up live updates:

Network snapshots (Protocol v8): Handles static tracks, routes, stations, and depots. Because these don’t change often, snapshots are cached and only resent when track or route definitions actually change.
Live train positions (v1 Transport): Live trains need fast, lightweight updates. The server samples active train positions at roughly 4 Hz and sends compact coordinate packets. The client smoothly interpolates between these coordinates, giving you fluid train movement without placing heavy loads on the network or CPU.
Station arrival boards (Overlay-1 Transport): Arrival boards only stream data on demand. When you click Expand on a station card, your client subscribes to MTR/TSC’s live PIDS feed for that specific station. When you collapse the board or close the map, the subscription cancels immediately, freeing up server resources.

Rendering and optimization

Shared track geometry: The mod samples physical rails directly from MTR’s spline definitions. Routes that share physical track use these identical samples to draw parallel colored ribbons side-by-side.
Viewport culling: Only rails, routes, and trains within your current map viewport are drawn. Anything outside your screen is skipped entirely.
Zero redundant simulation: The mod never runs its own duplicate physics or timetable simulation. Everything you see is a lightweight visual projection of MTR and TSC’s authoritative game state.

For details on integrating custom map views or route planners, see the Navigation API.