Data snapshots

How snapshots work

At the start of each frame, the host marshals the instance's data in one shot into a POD snapshot (fixed-length header + variable-length array pools + a UTF-8 string pool) and passes it, together with the state block pointer, to mtrRender. The SDK's typed wrappers (mtr::Vehicle, mtr::Pids, mtr::Lift, mtr::EyeCandy) provide same-named accessors over that memory as the JS Wrappers:

• Strings come back as mtr::StrView (data + len); call .str() to convert to std::string and .empty() to test for empty; views are valid only within the current render call.
• Out-of-range indexes in ordinary lists throw std::out_of_range (matching the Java side's IndexOutOfBounds semantics).
• Do not keep snapshot pointers or wrappers across frames.

Vehicle

Provided by mtr::Vehicle, mirroring the JS VehicleWrapper + NTETrainWrapper:

Car

StopList

Stop / interchanges / exits

mtr::Stop mirrors the JS VehicleWrapper.Stop:

Transport modes and types

Two complementary views: the JS-side getTransportMode() / getTransportType() return exactly the same values, so scripts across languages can share layout logic:

• Mode (the mtr::TransportMode enum): UNKNOWN / TRAIN / BOAT / CABLE_CAR / AIRPLANE, covering the four basic vehicles.
• Type (a string id, the mtr::transport_type constants): the lowercase names of the basic modes ("train", "boat", "cable_car", "airplane") plus the extended route types of the MAGIC MTR Addon — train_normal / train_light_rail / train_high_speed / train_metro / train_bus / train_tram / train_sbahn; unresolvable values come back as "unknown" or an empty view (older server data).

if (vehicle.getTransportType() == mtr::transport_type::TRAIN_METRO) { /* ... */ }

for (int i = 0; i < stop.interchange_count(); i++) {
    mtr::Stop::Interchange ic = stop.interchange(i);
    if (ic.getTransportType() == mtr::transport_type::TRAIN_HIGH_SPEED) { /* ... */ }
}

Pids (arrival display)

mtr::Pids mirrors the JS PIDSWrapper:

Arrivals / Arrival

Psd (platform screen door)

mtr::Psd mirrors the JS PSDWrapper (a psdScripts entry — see JS script types · PSD scripts):

PsdDoor (door unit)

PsdArrival (upcoming train)

Carries every Pids Arrival accessor (destination / route_name / route_number / platform_name / arrival_time / departure_time / deviation / realtime / terminating / circular_state / route_id / platform_id / route_color / car_count / departure_index — see Pids), plus:

PsdRoute / PsdStop (routes and stations)

PsdStation (the station record, ABI 13)

JcmPsdSnapshot.station_offset (byte offset 124; -1 = no station — the field was padding in ABI 12) points at the 96-byte JcmPsdStation record — the same data the JS psd.stop() object exposes:

PsdStation and its nested station accessors return absent objects, empty strings or defaults for invalid indices or records instead of throwing index exceptions. When constructing a snapshot outside the host, pass the actual buffer size to mtr::Psd(snapshot, byteLength). The compatible pointer-only constructor requires a fully readable header and its declared backing buffer; a raw pointer cannot reveal the allocation size.

ABI 12 → 13 is purely additive (a padding field promoted in place, every pre-existing struct unchanged), so ABI 6–12 modules keep loading.

Lift

mtr::Lift (a snapshot + Java wrapper combination; the snapshot part):

Deeper interfaces — render manager, sound manager, visibility, and so on — are reached through Api's wrapper() (lifts have no standalone JS documentation page; the Java wrapper is authoritative).

EyeCandy

mtr::EyeCandy mirrors EyecandyBlockEntityWrapper:

Event details (player, held item, etc.) are read through Api:

mtr::Api api(ctx.input());
auto event = api.context().call("events").get("onBlockUse");
if (event.call("occurred").as<bool>()) {
    auto detail = event.call("detail");
    auto player = detail.call("player");
    auto item   = detail.call("item");
}

The eyecandy draw context EyeCandyContext provides draw_model(model, matrices), play_sound(sound, volume, pitch), set_outline_shape(boxes, count), and set_collision_shape(boxes, count) (6 floats per box; collision boxes keep the Java side's 1.5-block height cap, with overflow validated and logged by the host). Lifts reuse the same context type (LiftContext = EyeCandyContext).

Helper types

<mtr/util.hpp> provides hot-path-friendly cycling and state-tracking helpers (zero allocation):

// "A|B|C" rotates one segment every 40 ticks; switching views is pure offset math
mtr::CycleTracker dest{"KOWLOON|TSUEN WAN"};
StrView current = dest.value(vehicle.in_game_time());

State-machine tracking mtr::StateTracker<T> (mirrors the upstream StateTrackerJS; the clock is passed explicitly — the snapshot's game_time_millis() is the natural equivalent): keep the tracker field in State and do a single transition check per render:

struct State {
    mtr::StateTracker<Phase> phase;   // persists across frames
};

// in render():
if (s.phase.set_state(next, vehicle.game_time_millis())) {
    // returned true — first frame in this state (new upstream prerelease.2 semantics)
}
double staying = s.phase.state_now_duration(vehicle.game_time_millis());
if (s.phase.changed_from_to(PHASE_IDLE, PHASE_ARRIVING)) { /* play arrival animation */ }

Up next: Drawing and canvases — turning this data into pixels.