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（圖定或即時推算）· 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++ 條目、開門方向記憶、交通類型細分與直寫像素上傳。