JS Script Types

Vehicle scripts

A "vehicle" in MTR 4 is a single car model entry; players freely combine cars into trains in the siding screen. A script binds to neither a single car nor a whole train, but to a script entry: vehicle entries reference it via scriptId, and multiple vehicles can reuse the same script — mixed consists, performance, and NTE compatibility all at once.

The three callbacks (ctx is a VehicleScriptContext, vehicle is a VehicleWrapper):

function create(ctx, state, vehicle) { /* Before the first render: set up textures, register callbacks */ }
function render(ctx, state, vehicle) { /* Every frame: read state, submit draws and sounds */ }
function dispose(ctx, state, vehicle) { /* On exit: release textures */ }

VehicleScriptContext (ctx)

Deprecated drawCarModel(...) / playCarSound(...) / setDataFetchMode(...) still work, but new code should use the RenderManagers / SoundManagers / declaration fields above. Both overloads of drawConnModel (car connectors) throw NotImplementedException; drawConnStretchTexture is not exposed in this context. Neither API is usable.

VehicleWrapper (vehicle)

Deprecated: the same-named NTE-era interfaces (getAllPlatforms / trainCars / speed / doorValue / mtrTrain, and so on) are all kept working, each equivalent to a newer interface in the table above.

Stop (scheduled stops)

RouteInterchange (interchange routes)

color: int (RGB) · name: String; Yanyang adds the fields getTransportMode(): TransportMode?, getTransportType(): String (including MAGIC subdivisions), and getRouteId(): long (the source route's id; 0 when data is missing) — see Yanyang extensions.

Vehicle data fetch modes

MTR 4 only syncs nearby data, while vehicle scripts often want station names for the whole route. JCM's three-tier model (the dataFetchMode field):

Decoration object scripts

Attaches to an MTR decoration object model entry: the script starts working when a decoration object block using that model from the resource pack is rendered. Register with objects + objectScripts (the MTR 3 legacy format writes these in eyecandy.json); setting isScriptControlled: true on the content entry hides the original model and hands the visuals entirely to the script.

The three callbacks: ctx is an EyeCandyScriptContext, eyecandy is an EyecandyWrapper.

EyeCandyScriptContext (ctx)

EyecandyWrapper (eyecandy)

getModelId(): String (the current model entry's id) · getTranslateX/Y/Z(): float (the GUI offset, in meters) · getRotateX/Y/Z(): float (the GUI rotation, in radians) · pos(): Vector3f (block + offset) · blockPos(): Vector3f · facing(): Direction · facingAngle(): double (the facing angle) · isCrosshairTarget(): boolean (the crosshair is on it — handy for tooltips) · getFullBrightness(): boolean · redstoneLevel(): int (0–15).

Deprecated: the direct field-reading forms (eyecandy.translateX, eyecandy.prefabId, and so on) still work.

Lift scripts

Attaches to a lift car style (texture) entry and takes effect once the player selects that style with the lift refresher. Register with lifts + liftScripts; isScriptControlled: true on the style entry hides the original model.

The three callbacks: ctx is a LiftScriptContext, lift is a LiftWrapper.

LiftScriptContext (ctx)

getRenderManager(): RenderManager (the base is the lift's base position + offset, following the lift's rotation) · getSoundManager(): SoundManager (same base) · setDebugInfo(...).

LiftWrapper (lift) and Floor

PIDS scripts

In the pids_images array of joban_custom_resources.json, a preset object carrying scriptFiles or scriptTexts becomes a scripted preset (scriptInput / scriptRateLimit mean the same as for the other kinds; Yanyang also accepts scriptLocations to mix in C++, see mixed entries):

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

The preset field outOfBound: boolean (upstream v2.3.0-prerelease.3) keeps the preset rendering when the screen leaves the camera's bounds — needed for projector presets (pids_projector) that must keep running constantly.

What you draw on a PIDS is polygons in the world, not a 2D canvas — elements can spill past the screen's bounds, and clipping to the screen is the script's own responsibility (when you truly need complex clipping / image processing, draw into a GraphicsTexture and blit it). Draw order is z-order: later draws cover earlier ones; by default each draw steps a tiny amount (0.0002) along z to prevent z-fighting, which you can disable with ctx.setAutoZOrdering(false) and manage manually via zOrder() (ctx.setZOrderStep(m) adjusts the step).

PIDSScriptContext (ctx) and PIDSBlockEntity (pids)

ctx.getRenderManager() / ctx.getSoundManager() (base = the block position) · ctx.setAutoZOrdering(b) · ctx.setZOrderStep(m) · ctx.setDebugInfo(...).

ArrivalEntries and ArrivalEntry

ArrivalEntries: get(i): ArrivalEntry? (at most 10 arrivals per platform) · length(): int (the total arrivals count, upstream v2.3.0-prerelease.3) · mixedCarLength(): boolean · platforms(): List<Platform> · forEach(consumer) / forEach(platformId, consumer) (iterates entry by entry, sparing you manual null checks).

ArrivalEntry: destination(): String · arrivalTime() / departureTime() (Unix milliseconds; new Date(v) makes a JS date) · arrived() / departed() · deviation(): long (relative to schedule: positive = late, negative = early) · realtime(): boolean (scheduled or extrapolated in real time) · departureIndex(): long · terminating(): boolean (terminates here) · route(): SimplifiedRoute? / routeId() / routeName() / routeNumber() / routeColor() / circularState() · platform(): Platform? / platformId() / platformName() · carCount() / cars(): List<CarDetails>.

Text / Texture / Rect (the drawing trio)

All three are fluent objects — create → configure via chaining → draw(ctx); Rect is a Texture with the texture hardcoded to a plain white PNG:

Texture-specific: texture(id) (PNG or mcmeta), uv(u1, v1, u2, v2) (0–1).

Don't need a script? Writing only JSON fields such as background / color / fonts / showWeather / showClock / hidePlatform / hideRow / topPadding / textOverflowMode in a pids_images entry makes it a "JSON preset" — enough for simple reskins, and it's strictly one or the other with a scripted preset; the two can't be mixed.

PSD scripts (platform screen doors)

Scripts for platform screen door glass and top panels. Declare them under the psdScripts category of mtr_custom_resources.json — the same entry shape as vehicleScripts (scriptLocations freely mixes JS and C++ with per-entry language detection) plus a type field selecting the binding surface:

"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"
    }
]

In game, use the new PSD Script Editor item (in the same creative tab as MTR's brush): right-click any PSD glass (including glass ends and half-height APG gates — MTR, Tianjin Metro and every addon building on MTR's PSD classes) or psd_top block and pick either an entry of the matching type or any scripted PIDS preset (PIDS scripts run unchanged; the canvas adapts to the PSD surface). "No script" removes the binding. Bindings live on the server and sync to every player in the dimension.

• Glass gets an opaque backing — black on the platform side (a real-PIDS dark display), plain white on the track side (riders inside a train see a plain white panel, never mirrored content). The script canvas sits on the platform side, inside the pane, and is clipped to the pane's transparent window (derived from the resource pack's model and texture alpha, so frames and bars stay visible in front and occlude the content); the whole glass run between two doors shares one canvas, and a full-height two-block column merges vertically into one. The canvas adapts to the window (96 px per block).
• Top panels: the whole psd_top stretch over one door run shares one canvas — that stretch stops showing the built-in arrow / route strip and its content is fully script-controlled; other stretches keep the vanilla content. Canvas is 96 px per block wide (minus a 0.125/16 side padding each) × 42 px high.

A continuous glass or top-panel section of at most 64 blocks retains one complete canvas, even across coordinate grid boundaries. Longer sections are divided into aligned 64-block intervals along the signed world coordinate in the canvas-right direction; the first and last intervals may be shorter. Binding, unbinding and hiding the original top-panel content all use the same subsection.

Drawing is identical to PIDS scripts (Text / Texture / Rect + ctx.draw; the canvas origin is the top-left of the visible face). The data API (JS psd argument / C++ mtr::Psd; full accessors in Data snapshots · Psd):

On the C++ side this is the fifth script base class mtr::PsdScript<State> (MTR_REGISTER_PSD_SCRIPT) with the JcmPsdSnapshot snapshot (ABI 12; station entries since ABI 13); see native/examples/psd_glass.cpp.

DisplayHelper (the built-in multi-screen helper)

A ready-made solution for trains with many screens: after 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();          // Instantiates and binds the texture
}
function render(ctx, state, vehicle) {
    if (state.rl.shouldUpdate()) {
        let g = state.dh.graphicsFor("lcd_north");  // The slot's canvas (offset applied automatically)
        // ... AWT drawing ...
        state.dh.upload();
    }
    for (let car of ctx.getMyCars())
        ctx.getCarRenderManager(car).drawModel(state.dh.model, null);  // Must be drawn every frame
}
function dispose(ctx, state, vehicle) {
    state.dh.close();
}

• All slots share one big texSize texture; texArea picks the region a slot uses (x, y, w, h).
• pos is a three-dimensional array: each screen's four corner coordinates (top-left → bottom-left → bottom-right → top-right), in meters (divide Blockbench's 1/16 units by 16), with the origin at the train's center at floor height and +X left / +Y up / +Z backward.
• offsets clones screens with identical content (saves texture when a row of small door screens repeats); graphicsFor(name) returns the canvas pre-shifted to the slot, graphics() the whole sheet.
• Put the upload inside the RateLimit and the model drawing outside it — the model must be submitted every frame.

Next up: Yanyang Extensions — mixed JS+C++ entries, door-opening direction memory, transport type subdivisions, and raw pixel uploads.