Types de scripts JS

Scripts de véhicule

Dans MTR 4, un « véhicule » est une entrée de modèle de voiture ; le joueur assemble librement ces entrées en rames dans l’interface de la voie de garage. Le script n’est lié ni à une voiture isolée ni à la rame entière, mais à une entrée de script : l’entrée de véhicule y fait référence par scriptId, et plusieurs véhicules peuvent réutiliser le même script — composition mixte, performance et compatibilité NTE réunies.

Trois callbacks (ctx est un VehicleScriptContext, vehicle un VehicleWrapper) :

function create(ctx, state, vehicle) { /* avant le premier rendu : créer les textures, enregistrer les callbacks */ }
function render(ctx, state, vehicle) { /* à chaque frame : lire l'état, soumettre dessins et sons */ }
function dispose(ctx, state, vehicle) { /* au retrait : libérer les textures */ }

VehicleScriptContext (ctx)

Obsolète drawCarModel(...) / playCarSound(...) / setDataFetchMode(...) restent utilisables, mais le nouveau code doit employer les RenderManager / SoundManager / champs de déclaration ci-dessus. Les deux surcharges de drawConnModel (attelages entre voitures) lèvent NotImplementedException ; drawConnStretchTexture n’est pas exposé dans ce contexte. Aucune de ces deux API n’est utilisable.

VehicleWrapper (vehicle)

Obsolète : les anciennes interfaces homonymes de NTE (getAllPlatforms / trainCars / speed / doorValue / mtrTrain, etc.) restent toutes disponibles et équivalent, une à une, aux nouvelles interfaces du tableau ci-dessus.

Stop (arrêt)

RouteInterchange (ligne de correspondance)

color: int (RGB) · name: String ; champs d’extension Yanyang getTransportMode(): TransportMode?, getTransportType(): String (subdivisions MAGIC comprises), getRouteId(): long (id de la ligne d’origine, 0 si la donnée manque) — voir Extensions Yanyang.

Modes de récupération des données du véhicule

MTR 4 ne synchronise que les données proches, alors que les scripts de véhicule veulent souvent les noms de stations de toute la desserte. D’où les trois niveaux de JCM (champ dataFetchMode) :

Scripts d’eyecandy

Rattaché à une entrée de modèle de décoration MTR (Decoration Object) : le script entre en action dès qu’un bloc de décoration arborant ce modèle est rendu. Enregistrement via objects + objectScripts (l’ancien format MTR 3 se déclare dans eyecandy.json) ; isScriptControlled: true sur l’entrée de contenu masque le modèle d’origine et confie tout l’affichage au script.

Trois callbacks : ctx est un EyeCandyScriptContext, eyecandy un EyecandyWrapper.

EyeCandyScriptContext (ctx)

EyecandyWrapper (eyecandy)

getModelId(): String (id de l’entrée de modèle courante) · getTranslateX/Y/Z(): float (décalage GUI, en mètres) · getRotateX/Y/Z(): float (rotation GUI, en radians) · pos(): Vector3f (bloc + décalage) · blockPos(): Vector3f · facing(): Direction · facingAngle(): double (angle d’orientation) · isCrosshairTarget(): boolean (visé par le réticule — pratique pour afficher une indication) · getFullBrightness(): boolean · redstoneLevel(): int (0–15).

Obsolète : la lecture directe des champs (eyecandy.translateX, eyecandy.prefabId, etc.) reste utilisable.

Scripts d’ascenseur

Rattaché à une entrée d’habillage de cabine d’ascenseur : le script prend effet lorsque le joueur sélectionne cet habillage avec le rafraîchisseur d’ascenseur. Enregistrement via lifts + liftScripts ; isScriptControlled: true sur l’entrée d’habillage masque le modèle d’origine.

Trois callbacks : ctx est un LiftScriptContext, lift un LiftWrapper.

LiftScriptContext (ctx)

getRenderManager(): RenderManager (référentiel = position de base de l’ascenseur + décalage, pivotant avec l’ascenseur) · getSoundManager(): SoundManager (même référentiel) · setDebugInfo(...).

LiftWrapper (lift) et Floor

Scripts PIDS

Dans le tableau pids_images de joban_custom_resources.json, un objet de préréglage portant scriptFiles ou scriptTexts devient un préréglage scripté (scriptInput / scriptRateLimit ont la même signification que pour les autres types ; Yanyang accepte aussi d’y mêler du C++ via scriptLocations, voir Entrées mixtes) :

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

Le champ de preset outOfBound: boolean (amont v2.3.0-prerelease.3) maintient le rendu du preset lorsque l’écran sort du cadre de la caméra — indispensable aux presets projecteur (pids_projector) qui doivent tourner sans interruption.

Ce qui se dessine sur un PIDS, ce sont des polygones dans le monde, pas un canevas 2D — les éléments peuvent déborder de l’écran, et le clipping aux bornes de l’écran est à la charge du script (pour un clipping ou un traitement d’image vraiment complexes, dessinez dans une GraphicsTexture puis plaquez-la). L’ordre de dessin fait la hiérarchie : le dernier dessiné recouvre les précédents ; par défaut, chaque dessin est translaté d’un petit pas le long de z (0.0002) pour éviter le z-fighting — désactivable via ctx.setAutoZOrdering(false) pour passer à un zOrder() manuel (le pas se règle avec ctx.setZOrderStep(m)).

PIDSScriptContext (ctx) et PIDSBlockEntity (pids)

ctx.getRenderManager() / ctx.getSoundManager() (référentiel = position du bloc) · ctx.setAutoZOrdering(b) · ctx.setZOrderStep(m) · ctx.setDebugInfo(...).

ArrivalEntries et ArrivalEntry

ArrivalEntries : get(i): ArrivalEntry? (au plus 10 arrivées par quai) · length(): int (nombre total d’arrivées, amont v2.3.0-prerelease.3) · mixedCarLength(): boolean · platforms(): List<Platform> · forEach(consumer) / forEach(platformId, consumer) (parcours entrée par entrée, dispense des tests de vacuité manuels).

ArrivalEntry : destination(): String · arrivalTime() / departureTime() (millisecondes Unix, convertissez en date JS avec new Date(v)) · arrived() / departed() · deviation(): long (par rapport à l’horaire théorique : positif = retard, négatif = avance) · realtime(): boolean (horaire théorique ou extrapolation temps réel) · departureIndex(): long · terminating(): boolean (terminus à cette station) · route(): SimplifiedRoute? / routeId() / routeName() / routeNumber() / routeColor() / circularState() · platform(): Platform? / platformId() / platformName() · carCount() / cars(): List<CarDetails>.

Text / Texture / Rect (le trio de dessin)

Tous trois sont des objets fluent « création → configuration en chaîne → draw(ctx) » ; Rect est un Texture dont la texture est codée en dur en PNG blanc pur :

Propre à Texture : texture(id) (PNG ou mcmeta), uv(u1, v1, u2, v2) (0–1).

Pas besoin de script ? Remplissez uniquement les champs JSON background / color / fonts / showWeather / showClock / hidePlatform / hideRow / topPadding / textOverflowMode, etc. dans pids_images : c’est un « préréglage JSON » — suffisant pour relooker simplement, l’alternative au préréglage scripté (jamais les deux à la fois).

Scripts PSD (portes palières)

Des scripts pour les vitres et bandeaux supérieurs des portes palières. Déclarez-les sous la catégorie psdScripts de mtr_custom_resources.json — même forme d’entrée que vehicleScripts (scriptLocations mélange librement JS et C++ avec détection par entrée), plus un champ type choisissant la 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"
    }
]

En jeu, utilisez le nouvel objet Éditeur de scripts PSD (même onglet créatif que le pinceau de MTR) : clic droit sur une vitre de porte palière (y compris vitres d’extrémité et portillons APG à mi-hauteur — MTR, Tianjin Metro et tout addon bâti sur les classes PSD de MTR) ou un bloc psd_top, puis choisissez une entrée du type correspondant ou n’importe quel preset PIDS scripté (les scripts PIDS tournent tels quels ; le canevas s’adapte à la surface PSD). « Aucun script » supprime la liaison. Les liaisons sont stockées côté serveur et synchronisées à tous les joueurs de la dimension.

• Vitre : un fond opaque est ajouté — noir côté quai (écran sombre façon PIDS réel), blanc uni côté voies (les passagers depuis l’intérieur d’un train voient un panneau blanc uni, jamais le contenu en miroir). Le canevas du script se trouve côté quai, à l’intérieur du vitrage, et est découpé selon la fenêtre transparente du vitrage (dérivé du modèle et de l’alpha de la texture du pack — cadres et montants restent visibles devant et masquent le contenu) ; tout le tronçon de vitrage entre deux portes partage un seul canevas, et une colonne pleine hauteur sur deux blocs fusionne verticalement. Le canevas s’adapte à la fenêtre (96 px par bloc).
• Bandeau supérieur : toute la bande psd_top d’un même passage de portes partage un canevas unique — cette bande n’affiche plus la flèche / la ligne intégrée et son contenu est entièrement contrôlé par le script ; les autres bandes conservent le rendu d’origine. Canevas : 96 px de large par bloc (moins une marge de 0,125/16 de chaque côté) × 42 px de haut.

Une section continue de vitres ou de panneaux supérieurs d’au plus 64 blocs conserve un canevas complet, même si elle traverse une limite de grille. Les sections plus longues sont divisées en intervalles alignés de 64 blocs suivant la coordonnée mondiale signée dans le sens droit du canevas ; les intervalles aux extrémités peuvent être plus courts. L’association, la dissociation et le masquage du contenu original des panneaux utilisent tous la même sous-section.

Le dessin est identique aux scripts PIDS (Text / Texture / Rect + ctx.draw ; l’origine du canevas est le coin supérieur gauche de la face visible). L’API de données (argument JS psd / C++ mtr::Psd ; accesseurs complets dans Instantanés de données · Psd) :

Côté C++, c’est la cinquième classe de base mtr::PsdScript<State> (MTR_REGISTER_PSD_SCRIPT) avec l’instantané JcmPsdSnapshot (ABI 12 ; entrées de gare depuis l’ABI 13) ; voir native/examples/psd_glass.cpp.

DisplayHelper (l’assistant multi-écrans intégré)

La solution clé en main pour les écrans multiples embarqués : après 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();          // instancie et lie la texture
}
function render(ctx, state, vehicle) {
    if (state.rl.shouldUpdate()) {
        let g = state.dh.graphicsFor("lcd_north");  // le canevas de l'emplacement (décalage automatique)
        // ... dessin AWT ...
        state.dh.upload();
    }
    for (let car of ctx.getMyCars())
        ctx.getCarRenderManager(car).drawModel(state.dh.model, null);  // à dessiner à chaque frame
}
function dispose(ctx, state, vehicle) {
    state.dh.close();
}

• Tous les emplacements partagent une grande texture texSize ; texArea désigne la zone qu’occupe chaque emplacement (x, y, w, h).
• pos est un tableau à trois dimensions : les quatre coins de chaque écran (haut-gauche → bas-gauche → bas-droite → haut-droite), en mètres (les unités 1/16 de Blockbench se divisent par 16), l’origine au centre du train, à hauteur de plancher, +X vers la gauche / +Y vers le haut / +Z vers l’arrière.
• offsets duplique les écrans de même contenu (économie de texture pour les rangées de petits écrans au-dessus des portes) ; graphicsFor(name) fournit le canevas déjà décalé, graphics() la texture entière.
• Placez le téléversement dans le RateLimit, et le dessin du modèle à l’extérieur — le modèle doit être soumis à chaque frame.

Ensuite : Extensions Yanyang — entrées mixtes JS+C++, mémoire du sens d’ouverture des portes, subdivision des types de transport et téléversement de pixels par écriture directe.