数据快照

快照机制

每帧开始时，宿主把该实例的数据一次性打包成一块 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)) { /* 播进场动画 */ }

接下来：绘制与画布 —— 把这些数据画出来。