JS 公器 — JCM Yanyang 腳本開發文檔

本頁之目

速記之約
資源與檔案
算學與變換
渲染
模型
動態紋理
聲音
網路與後臺
控制臺
MTR 數據
Minecraft 之境
器用之類
腳本之特性

速記之約

static 之綴者，逕以類名呼之謂也（Resources.id(...)）；無之，則須先得其實例（多出自他函所返之值）。
型之標註，依 Java 之書：str: String 受 Java 之字串（JS 字串自為轉換）；返 String? 者，或為 null 也；String... 者，可變其數之字串參也。
標已廢者，NTE 之世相容之口也，新腳本勿復用之；標晏陽者，本支自有之增補也。

資源與檔案

Identifier（資源之徑）

Minecraft 以 命名空間:路徑 之式，用 Identifier 以定資源之所在。自 JCM v2.3 以降，多數受 Identifier 之處，亦得徑予尋常字串：全式 "mtr:asd.png"；相對當前腳本目錄之徑，則加 ./ 之綴（與 idr() 等價）。

函	釋義
`static Resources.id(idStr: String): Identifier`	由字串而造 Identifier
`static Resources.idr(relPath: String): Identifier`	相對當前腳本所在之目錄而解；惟解析之期得用之（運行之期無「當前腳本」之念也）
`static Resources.id(id: Identifier, suffix: String): Identifier`	於既有 Identifier 之後益以綴——解析之期以 `idr()` 記其基準，運行之期復拼其徑

Resources（資源包之讀）

自磁碟讀資源，遲於記憶體之操作遠甚：解析之期所能讀者，勿置諸 render() 逐幀重讀。

函	釋義
`static Resources.read(id): DataReader?`	讀資源包之檔，返 DataReader；檔不存在則返 `null`
`static Resources.exist(id): boolean`	檔之存否
`static Resources.getSystemFont(name: String): Font`	取 AWT 之字體。內建者：`Noto Serif`（CJK 襯線）、`Noto Sans SemiBold`、`Noto Sans CJK TC Medium`；另受 `Serif` / `SansSerif` / `Monospaced`（視玩家之機所裝字體而定）
`static Resources.hasSystemFont(name: String): boolean`	該字體之族，系統有之否（不為內建者特判）
`static Resources.getFontRenderContext(): FontRenderContext`	AWT 文字度量所資之上下文
`static Resources.ensureStrFonts(text, primaryFont, fallbackFonts...): AttributedString`	按主字體加後備字體之鏈而合其文；主字體缺字，則自退焉——多語混排，所以防「豆腐之塊」也
`static Resources.getAddonVersion(modId: String): String`	取模組之版：`"mtr"` / `"jcm"` / `"mtrscripting"`（車輛 / 裝飾 / 電梯之腳查 `mtrscripting`，PIDS 查 `jcm`）

已廢	釋義
`Resources.readString(id)` / `readBufferedImage(id)` / `readFont(id)`	宜統改用 `read()` 加 DataReader
`Resources.manager()` / `Resources.mgr()`	MTR 四代跨版本之架不曝之，恆返 `null`；須之之函亦受 `null` 焉
`Resources.getMTRVersion()` 等 NTE 版本之函	改用 `getAddonVersion()`；NTE 諸系恆返舊值，惟為相容而已

Files（本地之檔）

惟得活動於 .minecraft 之內：讀、寫、刪限於 .minecraft/data/mtrscripting（腳本數據之目錄）；讀則放乎整個 .minecraft。路徑以多參而傳，勿帶斜槓：Files.read("config", "mtr.json")。

函	釋義
`static Files.read(path: String...): DataReader?`	讀 `.minecraft` 下之檔；不存在則返 `null`
`static Files.readData(path: String...): DataReader?`	同上，惟相對 `data/mtrscripting`
`static Files.saveData(content: String \| BufferedImage, path: String...): void`	存文或圖；父目錄自為之建
`static Files.deleteData(path: String...): void`	刪檔
`static Files.hasData(path: String...): boolean`	檔 / 目錄之存否

算學與變換

Vector3f（三維之向量）

坐標 (x, y, z) 也。JCM 之實現，其底為 double，對外收放 float；運算諸法，皆返自身，得鏈式而呼：

new Vector3f(x, y, z)（亦得自 TSC 之 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)（弧度）· cross(v) · distance(v) · distanceSq(v) · rawBlockPos()。常數 Vector3f.ZERO / XP / YP / ZP——唯讀者也，慎勿改之。

Matrices（變換之棧）

渲染常須「畢此一段，復歸前之變換」。Matrices 者，變換之棧也；push 與 pop 相偶而用：

new Matrices()（其初為單位之矩陣）· translate(x,y,z) · rotateX/Y/Z(rad)（弧度）· rotateX/Y/ZDegrees(deg)（角度）· pushPose()（存當前之狀）· popPose()（復前所存）· popPushPose()（先復後存）。

渲染

腳本行於後臺線程，渲染行於主線程——故繪製循繪製之令（draw call）之式：君於 render() 中，以「何以畫之」納諸 RenderManager；JCM 記此一批之令，迄君下次執行之前，恆按之而畫。舊令於每遭腳本執行之後悉清；欲其恆顯，則每輪必重新納之；然執行遲而失幀，亦無懼也——JCM 沿用前批之令，以俟君之新者。

RenderManager

自各類 ctx.getRenderManager() 而得；自具「基礎之變換」（裝飾者，方塊之位加 GUI 之移與旋也；車輛則按車廂……各類見腳本類型之篇），凡所納者，皆相對之而繪：

函	釋義
`drawModel(model: Model, matrices?: Matrices)`	納模型；可選附加之變換
`drawModel(model, matrices?, light: int)`	同上，自定其光（`MinecraftClient.lightAt` 所取之值）
`drawModel(holder: DynamicModelHolder, matrices?: Matrices)`	徑納動態模型之持有器——其內自處「次幀方傳畢」之隙，以免閃爍
`draw(call: DrawCall)`	納裸繪製之令（`QuadDrawCall` 之屬）

QuadDrawCall（四邊形）

畫四邊形之面，可指其紋理、UV、染色、光照——常以貼動態紋理，仿屏之為：

static QuadDrawCall.create()（可帶註釋之參）· quad(c1, c2, c3, c4) 或 corner1..4(pos)（四 Vector3f）· renderType(str) · color(rgb) · texture(id) · uv(u1,v1,u2,v2)（0–1）· matrices(m)。

renderType 之值：EXTERIOR（車外之漆面，受所在之光照，預設也）、EXTERIOR_TRANSLUCENT、INTERIOR（車之內，全亮而帶面之色）、INTERIOR_TRANSLUCENT、LIGHT（全亮而無影，宜於 LCD）、LIGHT_TRANSLUCENT。模型之側，別有 ALWAYS_ON_LIGHT。

模型

所支持者，WaveFront OBJ 與 Metasequoia（.mqo）；Blockbench 之 .bbmodel，不在支持之數。Blender / Blockbench 所出之 OBJ，須翻其 V 軸（flipV = true，預設之值）；Metasequoia 所出者，須明傳 false。

類	要點
`ModelManager`	`loadModel(id, flipV=true): RawModel`、`loadModelParts(id, flipV=true): Map<String, RawModel>`（按對象之組而分）、`upload(rawModel): Model`（上傳 GPU；惟解析之期——運行之期用 DynamicModelHolder）
`RawModel`	頂點數據之器：`append(mesh\|model)`、`applyTranslation(x,y,z)`、`applyRotation(dir, angleDeg)`、`applyScale(x,y,z)`、`applyMirror(x,y,z)`、`applyUVMirror(u,v)`、`setAllRenderType(str)`、`copy()`、`replaceTexture(fileName, id)`、`replaceAllTexture(id)`
`Model`	既上 GPU：頂點不可復改，然仍得 `replaceTexture(...)` / `replaceAllTexture(...)` / `copyForMaterialChanges()` / `close()`
`RawMeshBuilder`	以碼建模型：`new RawMeshBuilder(faceSize, renderType, textureId)` 之後，`vertex(pos)` → `normal(x,y,z)` → `uv(u,v)` → `endVertex()`（可加 `color(r,g,b,a)`），以 `getMesh()` 或 `asRawModel()` 而成之
`DynamicModelHolder`	運行期之上傳：`uploadLater(rawModel)`（次幀於渲染線程上傳）、`getUploadedModel()`（或為舊模，或為 null；宜先徑以持有器付 `drawModel`）、`close()`

要訣

運行期簡單之變換（平移 / 旋轉 / 縮放），以 Matrices 傳乎 drawModel，勿逐幀改頂點而復上傳——後者之疾徐，差以數量級矣。

動態紋理

GraphicsTexture

定解析度之虛擬紋理，加 Java AWT 之畫布；既畫則上傳，以顯於遊戲——車內車外之屏、LED 之牌，皆賴之：

成員	釋義
`new GraphicsTexture(width, height)`	造之。逐屏 / 逐車之內容，請於 `create` 中建之，存諸 `state`
`.identifier`	該紋理之 Identifier——付諸 `QuadDrawCall.texture()`，或以易模型之貼圖
`.bufferedImage` / `.graphics`	AWT `BufferedImage` 之畫布與其 `Graphics2D`（預設惟開文字之抗鋸齒）
`.fullAA()` / `.noAA()`	全抗鋸齒 / 全閉（點陣之屏常用 noAA）
`.upload()`	舉全圖上傳顯存。其費不貲——配 `RateLimit` 以降其頻（如 10 Hz），遠處則不更新
`.upload(x, y, width, height)`	惟上傳子域之部，舊內容仍存。參式二：`upload(dstX, dstY, srcX, srcY, w, h)`；亦得徑傳外部之 `BufferedImage`：`upload(img, dstX, dstY, srcX, srcY, w, h)`
`.close()`	釋顯存。於 `create` 所建者，必於 `dispose` 閉之，否則洩漏
晏陽 `.uploadRawABGR(bytes, dstX, dstY, w, h, lut)`	以 BGRA 之序，字節行陣直書於紋理，復惟上傳該矩形——供逐像素高頻之更新以省頻寬，詳見晏陽增補

AWT 之側所常用者：Color.decode / new Color、graphics.setColor / setFont / setStroke、drawRect / fillRect / drawRoundRect / fillRoundRect、drawImage / drawString、Font.deriveFont、GradientPaint、AffineTransform、setClip、AlphaComposite；以 Rhino 之 importPackage(java.awt) 引入之。其教程，觀 Graphics2D 之 JavaDoc。

慎之

新建紋理之內容，不保其潔（或復用舊記憶體，屏生花紋）——既造，先 upload() 一遭，刷為自家之內容。

車輛多屏之需，可改用內建之 DisplayHelper（include(Resources.id("mtrsteamloco:scripts/display_helper.js"))）：一張巨紋理切為槽位，模型循配置而自生，見腳本類型之篇。

聲音

SoundManager

自各類 ctx.getSoundManager() 而得；基準之位，視類而定：

playLocalSound(id, volume, pitch, category="MASTER")（無定位，報站之屬）· playSound(id, pos, volume, pitch, category="MASTER")（定位於世界，相對基準之位）· play(soundInstance) / stop(soundInstance)（可控之實例）。

TickableSoundInstance

一次性之音效，既播則莫能復制之；須中途調音量 / 打斷之景，用可控之實例（車載繁難之報站、電機之音、循環之樂）：

static create(id, category) · setSoundVolume(v) / setSoundPitch(v)（以 1.0 為基準）· setRepeatable(b) · setLoopDelay(tick) · setRelative(b)（隨玩家而恆其音量）· setPos(v)（循環之聲，必自逐幀更其位）· isPlaying()。播放由 play() / play(delayTick) / play(ctx) 所驅，abort() 可中道斷之（上游 v2.3.0-prerelease.3 所改）。循環之實例，務於 dispose 中 stop 之。

已廢：setLoopable(b)——v2.3.0-prerelease.3 之改，以 setRepeatable(b) 代之；舊腳照行如故。

聲音之別：MASTER BLOCKS MUSIC RECORDS WEATHER HOSTILE NEUTRAL PLAYERS AMBIENT VOICE。

網路與後臺

Networking

static Networking.fetch(url, requestOption?): NetworkResponse<DataReader>。RequestOption 者，尋常 JS 之物件也：method（預設 GET）、connectTimeout / readTimeout（毫秒）、headers（物件）、body（字串，自帶 Content-Length）。

NetworkResponse：getResponseCode() · success()（既得響應即真——判事之成，用 ok()，即 200–299）· getData()（敗則 null）· exception() · getHeaders()。

請求預設帶 User-Agent: Joban Client Mod (https://jcm.joban.org)，正途莫能改之（惟玩家閉腳本之限，方可）。網路之請，付後臺線程行之（見下）。

BackgroundWorker

static BackgroundWorker.submit(task) 以 lambda 之任付單線程後臺之行器——勿過恃之，他腳本亦須用焉；任內之異常，宜自 try/catch。資源包重載之際，佇列悉清，方行之任遭斷；縱其卡死，亦能自愈。

BackgroundWorker.submit(() => {
    let resp = Networking.fetch("https://example.com/data.json");
    if (resp.ok()) {
        let str = resp.getData().asString();
        // 既處理則書於 state，render 讀之
    }
});

控制臺

print(...) 與 console.log(...) 等價（NTE 之遺產也，隨意用之）。console 之 API 對齊 Web 之慣例，然不含表格 / profile 之類之法：

console.log / warn / error / debug(...)（debug 惟除錯之式方輸出）· console.count(label="default") / countReset(label)（計數之器按標各自立）· console.time(label) / timeLog(label) / timeEnd(label)（計時之器按標各自立）。佔位之符，其插值則不支持；模板字串，足用矣。

MTR 數據

MTR.ClientConfig（玩家之好尚）

isChatAnnouncementEnabled() · isTtsAnnouncementEnabled() · shouldHideTranslucentParts() · getLanguageDisplay()（NORMAL / CJK_ONLY / NON_CJK_ONLY）· getDynamicTextureResolution()（0–8）· getVehicleOscillationMultiplier()（×10 而得百分比）· getDefaultRail3D() · isCustomFontEnabled()。

MTR.Data（客戶端所知之數據）

MTR 四代惟同步鄰近之數據——遠處查之不得，不足怪也；多數之函將返 null：

分組	函
車站 / 車廠	`findStation(pos)` · `getStation(id)` · `getKnownStations()`；`findDepot(pos)` · `getDepot(id)` · `getKnownDepots()`
線路	`getRoute(id)` · `getKnownRoutes()` · `getKnownRoutesPassingPlatform(platformId)`
載具	`getVehicle(vehicleId)` · `getPlayerMountedVehicle()` · `getKnownVehicles()` · `isPlayerMounted(id)` · `getVehicleMountDetail(): MountDetail`（`ridingCarIndex(): int`、`pos(): Vector3f` 相對車廂之中心，上游 v2.3.0-prerelease.3）
電梯	`getLift(id)` · `getPlayerMountedLift()` · `getKnownLifts()` · `getLiftFloors(tscLift): List<Floor>`（TSC 電梯諸層之表，上游 v2.3.0-prerelease.3）
軌道	`getRailFromPath(pathData)` · `getKnownRails()` · `isRailBlocked(hexId)` · `getKnownBlockedRails()` · `getBlockedSignalColors(hexId)` · `getConnectedRails(pathData, front, back, excludeSelf = false)` / `getConnectedRails(pos)`（與路徑之端 / 軌節點之位相連諸軌，上游 v2.3.0-prerelease.3）
站台 / 側線	`getPlatform(id)` · `getKnownPlatforms()` · `findNearbyPlatforms(pos, radius)`；`getSiding(id)` · `getKnownSidings()` · `findNearbySidings(pos, radius)`
到站	`getArrivals(platformId \| platformIds[]): ArrivalEntries`——與 PIDS 腳本中 `pids.arrivals()` 同物

MTRClientData 者，MTR 內部數據類直通之引也，惟作末策——無穩定之諾，跨版本或變焉。

Minecraft 之境

MinecraftClient

worldIsRaining() · worldIsThundering() · worldIsRainingAt(pos) · worldDayTime() · blockLightAt(pos) · skyLightAt(pos) · lightAt(pos)（渲染所用打包之值）· lightLevelAt(pos) · renderDistance() · localPlayer() · gamePaused()（TSC 之模擬，不隨暫停而止也！）· narrate(msg) · displayMessage(msg, actionBar)（亦收 VanillaText）· spawnParticleInWorld(id, pos, velocity, alwaysSpawn=false) · getScoreboardScore(objective, player) · getWorldPlayers() · getCurrentWorldId() · getCameraMode() · getRedstoneLevel(pos) · getWorldBlockState(pos, stateName)。

VanillaText（原版之富文）

聊天 / 覆層所資之原版文字組件也：literal(str) · translatable(key, ...) · append(other) · withBold() · withItalic() · withFont(id) · withColor(rgb | name) · clickToCopyText(str) · clickToOpenURL(url) · withHoverText(str | VanillaText) · getString()（取本地化之果）。

VoxelShape（方塊之輪廓）

裝飾自定碰撞 / 輪廓之所用：empty() · fullCube() · create(minX, minY, minZ, maxX, maxY, maxZ, facing?)（以 16 為一格之單位）· combine(other)；配 ctx.setOutlineShape(...) / ctx.setCollisionShape(...) 而用之。

ItemStack / PlayerEntity

ItemStack：itemId() · translationId() · empty() · count()。PlayerEntity（多出自 MinecraftClient.localPlayer() 或事件）：uuid() · pos() / blockPos() / smoothPos() / velocity() · pitch() / yaw() / bodyYaw() · playerName() / displayName() · hasPermissionLevel(level)（客戶端之訊，勿信以為真）· mainHandItem() / offHandItem() / activeItem() / isHoldingItem(id) · isSneaking() / isSprinting() / isSwimming() / isCreative() / isSpectator()。

器用之類

DataReader（統一之解碼）

Resources.read / Files.read / Networking.fetch 皆返之——字節序列之解碼器也：

asString(): String?（UTF-8）· asBufferedImage(): BufferedImage? · asFont(): Font?（TTF/OTF；其實現落檔於臨時之目錄，磁碟緊張，可清 +~JF 起首之殘）· asByteArray(): byte[] · openInputStream(callback)（自闔其流）· asInputStream()（須自闔之）。解碼既敗，則返 null，且於控制臺誌其誤。

其餘之器

類	要點
`Timing`	`elapsed()`（遊戲既行之秒，暫停亦計）· `delta()`（距上次 render 之秒差——按幀率縮放動畫，全賴之）· `currentTimeMillis()` · `nanoTime()`
`TextUtil`	拆 MTR `中文\|English\|\|附加` 命名之式：`getCjkParts` / `getNonCjkParts` / `getExtraParts` / `getNonExtraParts` / `getNonCjkAndExtraParts` / `isCjk` / `cycleString(src[, tick])`
`StateTracker`	狀態變遷之蹤（免「條件既合，則逐幀播之」之弊）：`setState(value): boolean`（變而後真）· `stateNow()` / `stateLast()` / `stateNowDuration()` / `stateNowFirst()` · `changedTo(v)` / `changedFromTo(old, v)`；逐物件一份，存諸 `state`
`CycleTracker`	按時循環輪播：`new CycleTracker(["route", 5, "next", 5])` 加 `tick()` · `stateNow()` / `stateLast()` / `stateNowDuration()` / `stateNowFirst()`
`RateLimit`	限其頻：`new RateLimit(intervalSec)` 加 `if (rl.shouldUpdate()) { ... }`；`resetCoolDown()` 則立至其點
`Java`	Java 互通之輔：`Java.newArray(class, length \| dims)`、`Java.toArray(class, list)`——AWT 某些之法，須真 Java 之陣列

腳本之特性

include（腳本互含）

include(Resources.id("mtrsteamloco:scripts/display_helper.js"));  // 絕對之徑
include("./util/common.js");                                     // 相對當前之腳

解析之期，載而後行另一 JS 之檔（受字串相對之徑，或 Identifier）。

腳本條目之互引

同包之內，無內容所引之腳本條目，預設拒載（防漏書 scriptId 也）；於腳本條目加 "forceLoad": true，則強載之——跨包共享腳本之條、MTR 3 之條借 MTR 4 共享之宣告時用之；資源包載入之序，宜慎（宣告者先載）。

ANTE 相容之類

SoundHelper（ANTE 風格之放音）、TickableSound、GlobalRegister、ComponentUtil（原版文字組件之器）與全域 asJavaArray(list, class)，自 v2.3 而可用；簽名與 ANTE 一致，所以便 ANTE 內容之遷移也。

繼之：JS 之腳類型 —— 車輛 / 裝飾 / 電梯 / PIDS 專屬之 API；晏陽增補 —— 本支於 JS 之上所增之能。