JS script types

Vehicle scripts

A 'vehicle' in MTR 4 is a single car model entry; players freely marshal them into trains on 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 a VehicleWrapper):

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

VehicleScriptContext (ctx)

Deprecated drawCarModel(...) / playCarSound(...) / setDataFetchMode(...) still work, but new code should use the RenderManager / SoundManager / 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 old NTE-legacy interfaces of the same names (getAllPlatforms / trainCars / speed / doorValue / mtrTrain and so on) are all retained, each equivalent to a newer interface in the table above.

Stop (station stops)

RouteInterchange (interchange routes)

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

Vehicle data fetch modes

MTR 4 only synchronises nearby data, whilst vehicle scripts often want station names for the whole route. JCM's three levels (the dataFetchMode field):

Eyecandy scripts

Attached to MTR eyecandy (Decoration Object) model entries: the script starts working when an eyecandy block using that model is rendered. Register with objects + objectScripts (the MTR 3 legacy format writes to eyecandy.json); isScriptControlled: true on the content entry hides the original model and hands the whole picture over to the script.

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

EyeCandyScriptContext (ctx)

EyecandyWrapper (eyecandy)

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

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

Lift scripts

Attached to a lift car style (texture) entry; it 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 a LiftWrapper.

LiftScriptContext (ctx)

getRenderManager(): RenderManager (base = the lift's base position + offset, rotating with the lift) · 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 script 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 are polygons in the world, not a 2D canvas—elements may spill past the screen's edges, and clipping to the view is the script's own responsibility (when you genuinely need complex clipping / image processing, paint a GraphicsTexture first and mount it). Draw order is layering: later draws cover earlier ones; by default each draw advances a small step along z (0.0002) to prevent z-fighting, which can be switched off with ctx.setAutoZOrdering(false) in favour of manual zOrder() (with ctx.setZOrderStep(m) adjusting 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 the manual null checks).

ArrivalEntry: destination(): String · arrivalTime() / departureTime() (Unix milliseconds; new Date(v) converts to a JS date) · arrived() / departed() · deviation(): long (relative to schedule: positive late / negative early) · realtime(): boolean (scheduled or real-time extrapolated) · 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 of the 'create → chained configuration → draw(ctx)' kind; Rect is a Texture with its texture hardcoded to a plain white PNG:

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

Don't need a script? A pids_images entry with only the JSON fields background / color / fonts / showWeather / showClock / hidePlatform / hideRow / topPadding / textOverflowMode and so on is a 'JSON preset'—enough for a simple facelift, and mutually exclusive with a script preset (the two cannot be combined in one entry).

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 (passengers 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 multi-screen vehicles: 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();          // Instantiate and bind the texture
}
function render(ctx, state, vehicle) {
    if (state.rl.shouldUpdate()) {
        let g = state.dh.graphicsFor("lcd_north");  // The slot's canvas (auto-offset)
        // ... 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 large texSize texture; texArea picks the region each slot uses (x, y, w, h).
• pos is a three-dimensional array: the four corner coordinates of each screen (top-left → bottom-left → bottom-right → top-right), in metres (divide Blockbench's 1/16 units by 16); the origin sits at the train's centre at floor height, with +X left / +Y up / +Z rear.
• offsets duplicates screens showing the same content (a texture saver for runs of small screens above doors); graphicsFor(name) hands you the auto-offset canvas for a slot, graphics() the whole thing.
• Put the upload inside the RateLimit and the model drawing outside it—the model must be submitted every frame.

Next: Yanyang extensions — mixed JS+C++ entries, door-opening side memory, fine-grained transport types and direct-write pixel upload.