數據快照

快照之機

每幀方始，宿主以此實例之數據一舉搬運，為一 POD 快照：定長之首，變長之陣列池，UTF-8 字串之池，三者具焉；連狀態塊之指針，併傳於 mtrRender。SDK 之具型包裝器（mtr::Vehicle、mtr::Pids、mtr::Lift、mtr::EyeCandy）居此記憶體之上，供與 JS Wrapper 同名之訪問器：

• 字串以 mtr::StrView（data＋len）而返；.str() 則轉為 std::string，.empty() 則判其虛實。視圖惟本次 render 一呼之內為效。
• 常式之列，索引越界，則擲 std::out_of_range（與 Java 端 IndexOutOfBounds 同其義也）。
• 快照之指針與包裝器，慎勿跨幀而存之。

Vehicle（車輛）

mtr::Vehicle 所供者，映 JS 之 VehicleWrapper 加 NTETrainWrapper：

Car（車廂）

StopList

Stop / 轉乘 / 出口

mtr::Stop 映 JS 之 VehicleWrapper.Stop：

交通之模式與類型

二者相補之口徑也；與 JS 側 getTransportMode() / getTransportType() 所返之值全同，故跨語言之腳本，得共享布局之邏輯：

• 模式（mtr::TransportMode 枚舉）：UNKNOWN / TRAIN / BOAT / CABLE_CAR / AIRPLANE，覆基礎載具凡四。
• 類型（字串 id，mtr::transport_type 常數）：基礎模式小寫之名（"train"、"boat"、"cable_car"、"airplane"），益以 MAGIC MTR Addon 所擴線路之類 train_normal / train_light_rail / train_high_speed / train_metro / train_bus / train_tram / train_sbahn；其不可解者，則為 "unknown"，或空視圖（舊伺服器之數據也）。

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（到站之屏）

mtr::Pids 映 JS 之 PIDSWrapper：

Arrivals / Arrival

Psd（屏蔽之門）

mtr::Psd 映 JS 之 PSDWrapper（psdScripts 之目也，詳見 JS 腳本之類 · PSD 之腳）：

PsdDoor（門之單元）

PsdArrival（將至之車）

Pids Arrival 諸訪問器皆備（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，見 Pids），增益者：

PsdRoute / PsdStop（線與站）

PsdStation（車站之記，ABI 13）

JcmPsdSnapshot.station_offset（位元組之偏 124；-1 者無車站也——此欄於 ABI 12 猶填補之位）所指者，九十六位元組 JcmPsdStation 之記也——與 JS psd.stop() 之物件同其數據：

PsdStation 及其所屬諸訪問器，索引或記錄失實，則返空物、空字串或預設之值，不擲索引之異常。自造快照於宿主之外者，宜以 mtr::Psd(snapshot, byteLength) 傳實有之位元組數；惟傳指針之舊式，須首部及其所宣之緩衝區皆完備可讀，蓋裸指針不能自明所配之大小。

ABI 12 至 13，純為增補（填補之位原地升格，舊構一無所改），故 ABI 6–12 之模塊，照常載之。

Lift（電梯）

mtr::Lift 者，快照與 Java 包裝器相合之制；此其快照之部也：

渲染管理器、聲音管理器、可見性諸深介面，經 Api 之 wrapper() 而訪之（電梯無獨立之 JS 文檔頁，故以 Java 包裝器為準）。

EyeCandy（裝飾）

mtr::EyeCandy 映 EyecandyBlockEntityWrapper：

事件之詳（玩家、手持之物等），經 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");
}

裝飾繪製之上下文 EyeCandyContext，所供者四：draw_model(model, matrices)、play_sound(sound, volume, pitch)、set_outline_shape(boxes, count)、set_collision_shape(boxes, count) 是也（每匣 6 float；碰撞匣之高，沿 Java 端 1.5 格之限，踰之者宿主校而誌於日誌）。電梯復用同一上下文之型（LiftContext = EyeCandyContext）。

器用之型

<mtr/util.hpp> 供輪播與狀態追跡之器具，於熱路徑甚友善（零分配）：

// "A|B|C" 每 40 tick 更迭一段，切視圖惟算偏移
mtr::CycleTracker dest{"KOWLOON|TSUEN WAN"};
StrView current = dest.value(vehicle.in_game_time());

狀態機之追跡，則有 mtr::StateTracker<T> 焉（映上游 StateTrackerJS；時鐘顯傳——快照之 game_time_millis()，天然之準也）：以其欄納諸 State，render 之際，一斷其遷而已：

struct State {
    mtr::StateTracker<Phase> phase;   // 跨幀常存
};

// render 之中：
if (s.phase.set_state(next, vehicle.game_time_millis())) {
    // 得 true —— 初入此態之幀也（上游 prerelease.2 新義）
}
double staying = s.phase.state_now_duration(vehicle.game_time_millis());
if (s.phase.changed_from_to(PHASE_IDLE, PHASE_ARRIVING)) { /* 演進場之動畫 */ }

繼之：繪事與畫布 —— 取此數據而繪之。