資料快照

快照機制

每幀開始時，宿主把該實例的資料一次性搬運處理成一塊 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 中是填補位）指向 96 位元組的 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)) { /* 播放進站動畫 */ }

接下來：繪製與畫布 —— 把這些資料畫出來。