JS 脚本类型

车辆脚本

一个「车辆」在 MTR 4 里是一节车厢模型条目，玩家在侧线界面自由编组成列。脚本不绑定单节车厢也不绑定整列，而是绑定一个脚本条目：车辆条目以 scriptId 引用它，多个车辆可复用同一条脚本——混编、性能、NTE 兼容三全其美。

三个回调（ctx 是 VehicleScriptContext，vehicle 是 VehicleWrapper）：

function create(ctx, state, vehicle) { /* 首次渲染前：建纹理、注册回调 */ }
function render(ctx, state, vehicle) { /* 每帧：读状态、提交绘制与声音 */ }
function dispose(ctx, state, vehicle) { /* 退场：释放纹理 */ }

VehicleScriptContext（ctx）

已弃用 drawCarModel(...) / playCarSound(...) / setDataFetchMode(...) 仍可用，但新代码请用上面的 RenderManager / SoundManager / 声明字段。drawConnModel（车厢连接件）的两个重载均会抛出 NotImplementedException（未实现异常）；drawConnStretchTexture 在此上下文中未提供。两者均不可用。

VehicleWrapper（vehicle）

已弃用：NTE 同名旧接口（getAllPlatforms / trainCars / speed / doorValue / mtrTrain 等）全部保留可用，逐一等价于上表新接口。

Stop（停站）

RouteInterchange（换乘线路）

color: int（RGB）· name: String；晏阳 扩展字段 getTransportMode(): TransportMode?、getTransportType(): String（含 MAGIC 细分）、getRouteId(): long（来源线路 id，缺数据为 0）——见 晏阳扩展。

车辆数据获取模式

MTR 4 只同步附近数据，而车辆脚本往往要整趟线路的车站名。JCM 的三级模式（dataFetchMode 字段）：

装饰物脚本

挂在 MTR 装饰物（Decoration Object）模型条目上：资源包里选中该模型的装饰物方块被渲染时脚本开始工作。注册用 objects + objectScripts（MTR 3 旧格式写在 eyecandy.json），内容条目上 isScriptControlled: true 可隐藏原模型把画面全交给脚本。

三个回调：ctx 是 EyeCandyScriptContext，eyecandy 是 EyecandyWrapper。

EyeCandyScriptContext（ctx）

EyecandyWrapper（eyecandy）

getModelId(): String（当前模型条目 id）· getTranslateX/Y/Z(): float（GUI 位移，米）· getRotateX/Y/Z(): float（GUI 旋转，弧度）· pos(): Vector3f（方块 + 位移）· blockPos(): Vector3f · facing(): Direction · facingAngle(): double（朝向角度）· isCrosshairTarget(): boolean（准星指着，可用来弹提示）· getFullBrightness(): boolean · redstoneLevel(): int（0–15）。

已弃用：字段直读形式（eyecandy.translateX、eyecandy.prefabId 等）仍可用。

电梯脚本

挂在电梯轿厢样式（材质）条目上，玩家用电梯刷新器选中该样式后生效。注册用 lifts + liftScripts，样式条目上 isScriptControlled: true 隐藏原模型。

三个回调：ctx 是 LiftScriptContext，lift 是 LiftWrapper。

LiftScriptContext（ctx）

getRenderManager(): RenderManager（基准 = 电梯基础位置 + 偏移，随电梯旋转）· getSoundManager(): SoundManager（同基准）· setDebugInfo(...)。

LiftWrapper（lift）与 Floor

PIDS 脚本

在 joban_custom_resources.json 的 pids_images 数组里，预设对象带上 scriptFiles 或 scriptTexts 即为脚本预设（scriptInput / scriptRateLimit 含义同他类；Yanyang 也接受 scriptLocations 混入 C++，见 混合条目）：

{
    "pids_images": [
        {
            "id": "pids_demo",
            "name": "Demo Scripted PIDS",
            "scriptFiles": ["jsblock:scripts/pids_demo.js"],
            "scriptInput": { "theme": "dark" },
            "scriptRateLimit": 0.75
        }
    ]
}

预设字段 outOfBound: boolean（上游 v2.3.0-prerelease.3）：屏幕移出相机视界时仍继续渲染——投影仪预设（pids_projector）须臾不可停者所必需。

PIDS 上画的是世界里的多边形，不是 2D 画布——元素可以溢出屏幕边界，界内裁剪是脚本自己的责任（确需复杂裁剪 / 图像处理时用 GraphicsTexture 画好再贴）。绘制顺序即层次：后画的盖先画的；默认每次绘制沿 z 方向平移一小步（0.0002）防 z-fighting，可用 ctx.setAutoZOrdering(false) 关掉改手动 zOrder()（ctx.setZOrderStep(m) 调步长）。

PIDSScriptContext（ctx）与 PIDSBlockEntity（pids）

ctx.getRenderManager() / ctx.getSoundManager()（基准 = 方块位置）· ctx.setAutoZOrdering(b) · ctx.setZOrderStep(m) · ctx.setDebugInfo(...)。

ArrivalEntries 与 ArrivalEntry

ArrivalEntries：get(i): ArrivalEntry?（每站台最多取 10 条到站）· length(): int（到站总条数，上游 v2.3.0-prerelease.3）· mixedCarLength(): boolean · platforms(): List<Platform> · forEach(consumer) / forEach(platformId, consumer)（逐条遍历，免手动判空）。

ArrivalEntry：destination(): String · arrivalTime() / departureTime()（Unix 毫秒，new Date(v) 转 JS 日期）· arrived() / departed() · deviation(): long（相对图定：正晚点 / 负早点）· realtime(): boolean（图定 or 实时推算）· departureIndex(): long · terminating(): boolean（本站终到）· route(): SimplifiedRoute? / routeId() / routeName() / routeNumber() / routeColor() / circularState() · platform(): Platform? / platformId() / platformName() · carCount() / cars(): List<CarDetails>。

Text / Texture / Rect（绘制三件套）

三者都是「创建 → 链式配置 → draw(ctx)」的流式对象；Rect 等于贴图硬编码为纯白 PNG 的 Texture：

Texture 专属：texture(id)（PNG 或 mcmeta）、uv(u1, v1, u2, v2)（0–1）。

不需要脚本？pids_images 里只写 background / color / fonts / showWeather / showClock / hidePlatform / hideRow / topPadding / textOverflowMode 等 JSON 字段即为「JSON 预设」——简单改脸够用，且与脚本预设二选一不可混写。

PSD 脚本（屏蔽门）

为屏蔽门玻璃与顶部面板提供脚本。在 mtr_custom_resources.json 新增 psdScripts 类别——形式同 vehicleScripts（scriptLocations 支持 JS 与 C++ 混排、逐条目语言判定），新增 type 字段选择绑定表面：

"psdScripts": [
    {
        "id": "psd_glass_pids",
        "type": "glass",
        "scriptLocations": [
            "mtr:my_pack/js/psd_glass_pids/main.js",
            "mtr:my_pack/native/psd_glass_pids"
        ],
        "dataFetchMode": "ALL"
    }
]

游戏内用新物品「屏蔽门脚本编辑器」（与 MTR 的「刷」在同一创造分类）对任意屏蔽门玻璃（含端部玻璃、半高闸门 APG 玻璃；MTR、天津地铁等一切基于 MTR PSD 类的模组）或屏蔽门顶部面板右键，在弹出界面中选择该类型的条目或任一脚本化 PIDS 预设（PIDS 脚本原样运行，画布自动适配 PSD 表面）；「无脚本」解除绑定。绑定保存在服务端并同步给同维度所有玩家。

• 玻璃：衬上不透明底板——站台一侧黑色（真实 PIDS 的深色显示屏观感），轨道一侧纯白（车内乘客只见白色面板，看不到镜像内容）。脚本画布在站台一侧、夹于玻璃之内，自动裁剪到玻璃的透明窗口（按资源包模型与贴图 alpha 推导；门框、拉筋等不透明部分照常显示在前并遮挡内容）；两门之间的整段连续玻璃共用一块画布，整柱两格高的玻璃上下合并为一。画布尺寸随窗口自适应（每方块 96 像素）。
• 顶部面板：同一门区上方的整段 psd_top 共用一块画布，该段不再显示原有箭头 / 线路图——内容完全由脚本控制；其余段保持原样。画布每方块宽 96 像素（左右各留 0.125/16 边距）× 高 42 像素。

连续玻璃段或顶板段不超过 64 格时仍共用一个完整画布，即使跨越坐标网格边界也不拆分。超过 64 格的长段按画布向右方向的有符号世界坐标切为对齐的 64 格区间（首尾区间可更短）；编辑器绑定、解除绑定及顶板原有内容的隐藏都只作用于同一个子段。

绘制 API 与 PIDS 完全一致（Text / Texture / Rect + ctx.draw，画布原点为可见面左上角）。数据 API（JS 的 psd 参数 / C++ 的 mtr::Psd，完整访问器见 数据快照 · Psd）：

C++ 侧为第五类基类 mtr::PsdScript<State>（MTR_REGISTER_PSD_SCRIPT），数据快照 JcmPsdSnapshot（ABI 12；车站条目自 ABI 13 起），见 native/examples/psd_glass.cpp。

DisplayHelper（内置多屏助手）

车载多屏的现成方案：include(Resources.id("mtrsteamloco:scripts/display_helper.js")) 后——

let slotCfg = {
    "version": 1,
    "texSize": [2048, 1024],
    "slots": [
        { "name": "lcd_north", "texArea": [0, 0, 2048, 274],
          "pos": [[[-0.59, 2.125, -1.75], [-0.755, 2.03, -1.75],
                   [-0.755, 2.03, -3.25], [-0.59, 2.125, -3.25]]],
          "offsets": [[0, 0, -5], [0, 0, 0], [0, 0, 5], [0, 0, 10]] }
    ]
};
let dhBase = new DisplayHelper(slotCfg);

function create(ctx, state, vehicle) {
    state.rl = new RateLimit(0.05);
    state.dh = dhBase.create();          // 实例化并绑定纹理
}
function render(ctx, state, vehicle) {
    if (state.rl.shouldUpdate()) {
        let g = state.dh.graphicsFor("lcd_north");  // 槽位画布（自动平移）
        // ... AWT 绘制 ...
        state.dh.upload();
    }
    for (let car of ctx.getMyCars())
        ctx.getCarRenderManager(car).drawModel(state.dh.model, null);  // 每帧都要画
}
function dispose(ctx, state, vehicle) {
    state.dh.close();
}

• 所有槽位共享一张 texSize 大纹理；texArea 指定槽位用哪块区域（x, y, w, h）。
• pos 是三维数组：每屏四角坐标（左上 → 左下 → 右下 → 右上），单位米（Blockbench 的 1/16 单位要除 16），原点在列车中心、地板高度，+X 左 / +Y 上 / +Z 后。
• offsets 复制同内容屏幕（门上小屏连排时省纹理）；graphicsFor(name) 拿自动平移好的画布，graphics() 拿整张。
• 上传放 RateLimit 里、画模型放外面——模型必须每帧提交。

接下来：晏阳扩展 API —— 混合 JS+C++ 条目、开门方向记忆、交通类型细分与直写像素上传。