JS common APIs

Notation

• A static prefix means the call goes straight through the class name (Resources.id(...)); without it you first need an instance (usually obtained from another function's return value).
• Type annotations follow Java: str: String takes a Java string (JS strings convert automatically); a String? return may be null; String... means a variable number of string arguments.
• Items marked Deprecated are NTE-era compatibility interfaces—don't use them in new scripts; items marked Yanyang are this fork's own extensions.

Resources and files

Identifier (resource paths)

Minecraft locates resources with Identifiers of the form namespace:path. Since JCM v2.3, most places that take an Identifier also accept a plain string: the full form "mtr:asd.png", or a path relative to the current script's directory with a ./ prefix (equivalent to idr()).

Resources (resource pack reads)

Reading resources from disk is far slower than in-memory work: don't re-read every frame in render() what could have been read during the parsing stage.

Files (local files)

Confined to .minecraft: read + write + delete are limited to .minecraft/data/mtrscripting (the script data directory), whilst reading is open to the whole of .minecraft. Pass the path as multiple arguments, with no slashes: Files.read("config", "mtr.json").

Maths and transforms

Vector3f (3D vectors)

Coordinates (x, y, z). The JCM implementation stores doubles underneath but takes and returns floats at the API; the arithmetic methods all return the vector itself, so calls can be chained:

new Vector3f(x, y, z) (also constructible from TSC's Vector / Position) · x() y() z() · copy() · normalize() · add(x,y,z) / add(v) · sub(v) · mul(x,y,z) / mul(n) · rotX(rad) / rotY(rad) / rotZ(rad) (radians) · cross(v) · distance(v) · distanceSq(v) · rawBlockPos(). The constants Vector3f.ZERO / XP / YP / ZP are read-only; do not modify them.

Matrices (transform stack)

Rendering often needs 'draw this section, then return to the previous transform'. Matrices is a transform stack; push and pop come in pairs:

new Matrices() (starts as the identity matrix) · translate(x,y,z) · rotateX/Y/Z(rad) (radians) · rotateX/Y/ZDegrees(deg) (degrees) · pushPose() (saves the current state) · popPose() (restores the last save) · popPushPose() (restores, then saves).

Rendering

Scripts run on background threads whilst rendering happens on the main thread—so drawing follows the draw-call pattern: inside render() you submit 'how to draw' to the RenderManager, and JCM remembers that batch of commands and keeps drawing with it until your next execution. The old commands are cleared after every script execution, so anything that should stay visible must be resubmitted each round; and a frame missed to slow execution is nothing to fear—JCM keeps using the previous batch until you hand over a new one.

RenderManager

Obtained from each kind's ctx.getRenderManager(); it carries a built-in 'base transform' (eyecandy = the block position plus the GUI offset and rotation; vehicles per car…—see the script types page for each kind), and everything submitted is drawn relative to it:

QuadDrawCall (quads)

Draws a quad face with configurable texture, UVs, tint and light—often used to mount a dynamic texture as a screen:

static QuadDrawCall.create() (optionally taking a comment argument) · quad(c1, c2, c3, c4) or corner1..4(pos) (four Vector3fs) · renderType(str) · color(rgb) · texture(id) · uv(u1,v1,u2,v2) (0–1) · matrices(m).

renderType values: EXTERIOR (the exterior paintwork, affected by positional lighting; the default), EXTERIOR_TRANSLUCENT, INTERIOR (in-car, always fully lit with face shading), INTERIOR_TRANSLUCENT, LIGHT (fully lit, no shading—suited to LCDs), LIGHT_TRANSLUCENT. The model side additionally has ALWAYS_ON_LIGHT.

Models

WaveFront OBJ and Metasequoia (.mqo) are supported; Blockbench's .bbmodel is not. OBJ exported by Blender / Blockbench needs the V axis flipped (flipV = true, the default); Metasequoia exports need an explicit false.

Dynamic textures

GraphicsTexture

A fixed-resolution virtual texture plus a Java AWT canvas, uploaded for the game to display once painted—screens inside and outside vehicles and LED signboards all rest on it:

Commonly used on the AWT side: Color.decode / new Color, graphics.setColor / setFont / setStroke, drawRect / fillRect / drawRoundRect / fillRoundRect, drawImage / drawString, Font.deriveFont, GradientPaint, AffineTransform, setClip, AlphaComposite; bring them in with Rhino's importPackage(java.awt). For a tutorial, see the Graphics2D JavaDoc.

For multi-screen vehicles, consider the built-in DisplayHelper instead (include(Resources.id("mtrsteamloco:scripts/display_helper.js"))): one large texture carved into slots, with models generated automatically from the configuration—see the script types page.

Sound

SoundManager

Obtained from each kind's ctx.getSoundManager(); the base position depends on the kind:

playLocalSound(id, volume, pitch, category="MASTER") (unpositioned—announcement-style) · playSound(id, pos, volume, pitch, category="MASTER") (positioned in the world, relative to the base position) · play(soundInstance) / stop(soundInstance) (controllable instances).

TickableSoundInstance

A one-shot sound effect cannot be managed once it has played; use controllable instances for cases that need mid-flight volume changes or interruption (complex in-car announcements, motor sounds, looped music):

static create(id, category) · setSoundVolume(v) / setSoundPitch(v) (1.0 is the baseline) · setRepeatable(b) · setLoopDelay(tick) · setRelative(b) (follows the player at a constant volume) · setPos(v) (looping sounds must update their own position every frame) · isPlaying(). Playback is driven by play() / play(delayTick) / play(ctx), with abort() to cut a playing instance short (reworked in upstream v2.3.0-prerelease.3). Always stop looping instances in dispose.

Deprecated: setLoopable(b) — superseded by setRepeatable(b) in the v2.3.0-prerelease.3 rework; existing scripts keep working.

Sound categories: MASTER BLOCKS MUSIC RECORDS WEATHER HOSTILE NEUTRAL PLAYERS AMBIENT VOICE.

Networking and background work

Networking

static Networking.fetch(url, requestOption?): NetworkResponse<DataReader>. RequestOption is a plain JS object: method (GET by default), connectTimeout / readTimeout (milliseconds), headers (an object), body (a string; Content-Length is added automatically).

NetworkResponse: getResponseCode() · success() (true once any response has arrived—to test for business-level success use ok(), i.e. 200–299) · getData() (null on failure) · exception() · getHeaders().

Requests carry User-Agent: Joban Client Mod (https://jcm.joban.org) by default, which cannot be changed through normal means (unless the player disables the script restrictions). Do network requests on a background thread (see below).

BackgroundWorker

static BackgroundWorker.submit(task) hands a lambda task to a single-threaded background executor—don't lean on it too hard, other scripts need it as well; try/catch exceptions inside your task yourself. On a resource pack reload the queue is emptied, in-flight tasks are interrupted, and even a wedged state heals itself.

BackgroundWorker.submit(() => {
    let resp = Networking.fetch("https://example.com/data.json");
    if (resp.ok()) {
        let str = resp.getData().asString();
        // Process it, write it into state, and read it from render
    }
});

Console

print(...) and console.log(...) are equivalent (an NTE legacy; use either freely). The Console API aligns with web conventions but has no table / profiling methods:

console.log / warn / error / debug(...) (debug only outputs in debug mode) · console.count(label="default") / countReset(label) (counters are independent per label) · console.time(label) / timeLog(label) / timeEnd(label) (timers are independent per label). Placeholder interpolation is not supported; template strings are enough.

MTR data

MTR.ClientConfig (player preferences)

isChatAnnouncementEnabled() · isTtsAnnouncementEnabled() · shouldHideTranslucentParts() · getLanguageDisplay() (NORMAL / CJK_ONLY / NON_CJK_ONLY) · getDynamicTextureResolution() (0–8) · getVehicleOscillationMultiplier() (×10 for a percentage) · getDefaultRail3D() · isCustomFontEnabled().

MTR.Data (data known to the client)

MTR 4 only synchronises nearby data—don't be surprised when far-away things cannot be found; many functions return null:

MTRClientData is a direct pass-through reference to MTR's internal data classes—use it only as a last resort; it carries no stability promise and may change across versions.

The Minecraft environment

MinecraftClient

worldIsRaining() · worldIsThundering() · worldIsRainingAt(pos) · worldDayTime() · blockLightAt(pos) · skyLightAt(pos) · lightAt(pos) (a packed value for rendering) · lightLevelAt(pos) · renderDistance() · localPlayer() · gamePaused() (the TSC simulation does not stop with the pause!) · narrate(msg) · displayMessage(msg, actionBar) (also accepts VanillaText) · spawnParticleInWorld(id, pos, velocity, alwaysSpawn=false) · getScoreboardScore(objective, player) · getWorldPlayers() · getCurrentWorldId() · getCameraMode() · getRedstoneLevel(pos) · getWorldBlockState(pos, stateName).

VanillaText (vanilla rich text)

Vanilla text components for building chat messages / overlays: literal(str) · translatable(key, ...) · append(other) · withBold() · withItalic() · withFont(id) · withColor(rgb | name) · clickToCopyText(str) · clickToOpenURL(url) · withHoverText(str | VanillaText) · getString() (yields the localised result).

VoxelShape (block outlines)

For custom eyecandy collision / outlines: empty() · fullCube() · create(minX, minY, minZ, maxX, maxY, maxZ, facing?) (units of 16 = one block) · combine(other); used together with ctx.setOutlineShape(...) / ctx.setCollisionShape(...).

ItemStack / PlayerEntity

ItemStack: itemId() · translationId() · empty() · count(). PlayerEntity (usually from MinecraftClient.localPlayer() or an event): uuid() · pos() / blockPos() / smoothPos() / velocity() · pitch() / yaw() / bodyYaw() · playerName() / displayName() · hasPermissionLevel(level) (client-side information—take it with a pinch of salt) · mainHandItem() / offHandItem() / activeItem() / isHoldingItem(id) · isSneaking() / isSprinting() / isSwimming() / isCreative() / isSpectator().

Utility classes

DataReader (unified decoding)

Returned by Resources.read, Files.read and Networking.fetch alike—a decoder over a byte sequence:

asString(): String? (UTF-8) · asBufferedImage(): BufferedImage? · asFont(): Font? (TTF/OTF; the implementation drops files into the temp directory—if disk space is tight, clear the +~JF-prefixed leftovers) · asByteArray(): byte[] · openInputStream(callback) (closes the stream for you) · asInputStream() (you close it yourself). A failed decode returns null and logs an error to the console.

Other utilities

Script features

include (scripts including each other)

include(Resources.id("mtrsteamloco:scripts/display_helper.js"));  // Absolute path
include("./util/common.js");                                     // Relative to the current script

Loads and executes another JS file during the parsing stage (accepts a string relative path or an Identifier).

Script entries referencing each other

A script entry that no content in the same pack references is refused by default (a guard against a forgotten scriptId); adding "forceLoad": true to the script entry forces it to load—used when sharing script entries across packs, or when MTR 3 entries borrow MTR 4 shared declarations; mind the resource pack load order (the declaring pack loads first).

ANTE compatibility classes

SoundHelper (ANTE-style sound playback), TickableSound, GlobalRegister, ComponentUtil (vanilla text component utilities) and the global asJavaArray(list, class) are available since v2.3, with signatures matching ANTE's to ease migrating ANTE content.

Next: JS script types — the per-kind APIs for vehicles / eyecandy / lifts / PIDS; Yanyang extensions — what this fork adds on top of JS.