API communes JS

Conventions de notation

• Le préfixe static = appel direct au nom de la classe (Resources.id(...)) ; sans lui, il faut d’abord obtenir une instance (en général via la valeur de retour d’une autre fonction).
• Les annotations de types suivent l’écriture Java : str: String accepte une chaîne Java (les chaînes JS sont converties automatiquement) ; un retour String? signifie « peut valoir null » ; String... désigne un nombre variable d’arguments chaîne.
• Les entrées marquées Obsolète sont des interfaces de compatibilité de l’ère NTE — ne les utilisez plus dans les nouveaux scripts ; celles marquées Yanyang sont des extensions propres à cette branche.

Ressources et fichiers

Identifier (chemin de ressource)

Minecraft localise ses ressources au moyen d’Identifier de la forme espace_de_noms:chemin. Depuis JCM v2.3, la plupart des emplacements qui attendent un Identifier acceptent aussi une simple chaîne : forme complète "mtr:asd.png", ou chemin relatif au répertoire du script courant avec le préfixe ./ (équivalent d’idr()).

Resources (lecture dans le pack de ressources)

Lire une ressource sur disque est bien plus lent qu’une opération en mémoire : ce qui peut être lu pendant la phase d’analyse n’a pas à être relu à chaque frame dans render().

Files (fichiers locaux)

L’activité est confinée à .minecraft : lecture + écriture + suppression limitées à .minecraft/data/mtrscripting (le répertoire de données des scripts), lecture ouverte à tout .minecraft. Les chemins se transmettent en plusieurs arguments, sans barres obliques : Files.read("config", "mtr.json").

Mathématiques et transformations

Vector3f (vecteur tridimensionnel)

Coordonnées (x, y, z). L’implémentation JCM travaille en double en interne, reçoit et restitue des float à l’extérieur ; toutes les méthodes de calcul retournent l’objet lui-même pour permettre les appels chaînés :

new Vector3f(x, y, z) (constructible aussi depuis Vector / Position de la TSC) · 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(). Constantes Vector3f.ZERO / XP / YP / ZP — en lecture seule, ne les modifiez pas.

Matrices (pile de transformations)

Le rendu exige souvent « dessiner ce passage, puis revenir à la transformation précédente ». Matrices est une pile de transformations ; push et pop s’emploient par paires :

new Matrices() (matrice identité au départ) · translate(x,y,z) · rotateX/Y/Z(rad) (radians) · rotateX/Y/ZDegrees(deg) (degrés) · pushPose() (enregistre l’état courant) · popPose() (restaure le dernier enregistrement) · popPushPose() (restaure puis enregistre).

Rendu

Le script tourne sur un thread d’arrière-plan, le rendu a lieu sur le thread principal — le dessin suit donc le modèle des appels de dessin (draw calls) : dans render(), vous soumettez « comment dessiner » au RenderManager ; JCM mémorise ce lot d’instructions et continue de le dessiner tel quel jusqu’à votre prochaine exécution. L’ancien lot est effacé après chaque exécution du script — pour un affichage continu, soumettez-le à nouveau à chaque tour ; mais rien à craindre si une exécution lente fait sauter des frames : JCM continue de rejouer le lot précédent jusqu’à ce que vous en livriez un nouveau.

RenderManager

Obtenu via le ctx.getRenderManager() de chaque type ; il embarque une « transformation de base » (eyecandy = position du bloc + décalage et rotation GUI ; véhicule = par voiture… — détails par type sur la page Types de scripts) et toutes les soumissions se dessinent relativement à elle :

QuadDrawCall (quadrilatère)

Dessine une face quadrilatère, avec texture, UV, teinte et éclairage au choix — l’usage typique est d’y plaquer une texture dynamique pour simuler un écran :

static QuadDrawCall.create() (accepte un paramètre de commentaire) · quad(c1, c2, c3, c4) ou corner1..4(pos) (quatre Vector3f) · renderType(str) · color(rgb) · texture(id) · uv(u1,v1,u2,v2) (0–1) · matrices(m).

Valeurs de renderType : EXTERIOR (livrée extérieure du véhicule, éclairée selon sa position, par défaut), EXTERIOR_TRANSLUCENT, INTERIOR (habitacle, pleine luminosité avec teinte par face), INTERIOR_TRANSLUCENT, LIGHT (pleine luminosité sans ombrage, adapté aux LCD), LIGHT_TRANSLUCENT. Côté modèles existe en outre ALWAYS_ON_LIGHT.

Modèles

Sont pris en charge WaveFront OBJ et Metasequoia (.mqo) ; le .bbmodel de Blockbench n’est pas pris en charge. Les OBJ exportés par Blender / Blockbench exigent l’inversement de l’axe V (flipV = true, la valeur par défaut) ; ceux exportés par Metasequoia exigent un false explicite.

Textures dynamiques

GraphicsTexture

Une texture virtuelle à résolution fixe + un canevas Java AWT, téléversée au jeu pour affichage une fois dessinée — c’est elle qui porte les écrans intérieurs et extérieurs des véhicules comme les panonceaux LED :

Côté AWT, on utilise couramment : Color.decode / new Color, graphics.setColor / setFont / setStroke, drawRect / fillRect / drawRoundRect / fillRoundRect, drawImage / drawString, Font.deriveFont, GradientPaint, AffineTransform, setClip, AlphaComposite ; importez le tout avec l’importPackage(java.awt) de Rhino. Pour un guide, consultez la JavaDoc de Graphics2D.

Pour les besoins multi-écrans des véhicules, tournez-vous plutôt vers le DisplayHelper intégré (include(Resources.id("mtrsteamloco:scripts/display_helper.js"))) : une grande texture découpée en emplacements, des modèles générés automatiquement selon la configuration — voir la page Types de scripts.

Sons

SoundManager

Obtenu via le ctx.getSoundManager() de chaque type ; la position de référence dépend du type :

playLocalSound(id, volume, pitch, category="MASTER") (sans spatialisation, pour les annonces) · playSound(id, pos, volume, pitch, category="MASTER") (positionnée dans le monde, relativement à la position de référence) · play(soundInstance) / stop(soundInstance) (instances contrôlables).

TickableSoundInstance

Un effet sonore ponctuel, une fois joué, ne se contrôle plus ; pour régler le volume en cours de lecture ou interrompre, employez des instances contrôlables (annonces embarquées complexes, sons de moteur, musiques en boucle) :

static create(id, category) · setSoundVolume(v) / setSoundPitch(v) (1.0 est la référence) · setRepeatable(b) · setLoopDelay(tick) · setRelative(b) (volume constant en suivant le joueur) · setPos(v) (une boucle doit mettre à jour sa position frame par frame elle-même) · isPlaying(). La lecture passe par play() / play(delayTick) / play(ctx), avec abort() pour couper une instance en cours (retravaillé dans l’amont v2.3.0-prerelease.3). Une instance en boucle doit impérativement être arrêtée (stop) dans dispose.

Déprécié : setLoopable(b) — remplacé par setRepeatable(b) dans la refonte v2.3.0-prerelease.3 ; les scripts existants continuent de fonctionner.

Catégories de sons : MASTER BLOCKS MUSIC RECORDS WEATHER HOSTILE NEUTRAL PLAYERS AMBIENT VOICE.

Réseau et arrière-plan

Networking

static Networking.fetch(url, requestOption?): NetworkResponse<DataReader>. RequestOption est un simple objet JS : method (GET par défaut), connectTimeout / readTimeout (millisecondes), headers (objet), body (chaîne, Content-Length ajouté automatiquement).

NetworkResponse : getResponseCode() · success() (vrai dès qu’une réponse est parvenue — pour un succès métier, jugez avec ok(), c’est-à-dire 200–299) · getData() (null en cas d’échec) · exception() · getHeaders().

Les requêtes partent par défaut avec User-Agent: Joban Client Mod (https://jcm.joban.org), impossible à modifier par les voies normales (sauf si le joueur relâche les restrictions de scripts). Passez les requêtes réseau sur un thread d’arrière-plan (voir ci-dessous).

BackgroundWorker

static BackgroundWorker.submit(task) confie une tâche lambda à un exécuteur d’arrière-plan monothread — n’en abusez pas, les autres scripts y recourent aussi ; interceptez vous-même par try/catch les exceptions levées dans la tâche. Au rechargement du pack de ressources, la file d’attente est purgée et les tâches en cours interrompues ; un blocage finit par se résorber de lui-même.

BackgroundWorker.submit(() => {
    let resp = Networking.fetch("https://example.com/data.json");
    if (resp.ok()) {
        let str = resp.getData().asString();
        // après traitement, écrire dans state ; lu dans render
    }
});

Console

print(...) et console.log(...) sont équivalents (héritage NTE, à utiliser librement). L’API Console s’aligne sur les usages du Web, sans les méthodes de type table / profile :

console.log / warn / error / debug(...) (debug ne sort qu’en mode debug) · console.count(label="default") / countReset(label) (compteurs indépendants par étiquette) · console.time(label) / timeLog(label) / timeEnd(label) (chronomètres indépendants par étiquette). L’interpolation par substituants n’est pas prise en charge — les template literals suffisent.

Données MTR

MTR.ClientConfig (préférences du joueur)

isChatAnnouncementEnabled() · isTtsAnnouncementEnabled() · shouldHideTranslucentParts() · getLanguageDisplay() (NORMAL / CJK_ONLY / NON_CJK_ONLY) · getDynamicTextureResolution() (0–8) · getVehicleOscillationMultiplier() (multipliez par 10 pour un pourcentage) · getDefaultRail3D() · isCustomFontEnabled().

MTR.Data (données connues du client)

MTR 4 ne synchronise que les données proches — ne rien trouver au loin n’a rien d’étonnant, et bien des fonctions retournent null :

MTRClientData est une référence directe à la classe de données interne de MTR — un dernier recours : aucune promesse de stabilité, le contenu peut changer d’une version à l’autre.

Environnement Minecraft

MinecraftClient

worldIsRaining() · worldIsThundering() · worldIsRainingAt(pos) · worldDayTime() · blockLightAt(pos) · skyLightAt(pos) · lightAt(pos) (valeur empaquetée pour le rendu) · lightLevelAt(pos) · renderDistance() · localPlayer() · gamePaused() (la simulation TSC ne s’arrête pas avec la pause !) · narrate(msg) · displayMessage(msg, actionBar) (accepte aussi VanillaText) · spawnParticleInWorld(id, pos, velocity, alwaysSpawn=false) · getScoreboardScore(objective, player) · getWorldPlayers() · getCurrentWorldId() · getCameraMode() · getRedstoneLevel(pos) · getWorldBlockState(pos, stateName).

VanillaText (texte enrichi vanilla)

Construit les composants de texte vanilla du chat / de la barre d’action : literal(str) · translatable(key, ...) · append(other) · withBold() · withItalic() · withFont(id) · withColor(rgb | name) · clickToCopyText(str) · clickToOpenURL(url) · withHoverText(str | VanillaText) · getString() (retourne le résultat localisé).

VoxelShape (contours de bloc)

Pour les collisions / contours personnalisés des décorations : empty() · fullCube() · create(minX, minY, minZ, maxX, maxY, maxZ, facing?) (l’unité 16 = un bloc) · combine(other) ; à utiliser avec ctx.setOutlineShape(...) / ctx.setCollisionShape(...).

ItemStack / PlayerEntity

ItemStack : itemId() · translationId() · empty() · count(). PlayerEntity (en général issu de MinecraftClient.localPlayer() ou des événements) : uuid() · pos() / blockPos() / smoothPos() / velocity() · pitch() / yaw() / bodyYaw() · playerName() / displayName() · hasPermissionLevel(level) (information côté client, à ne pas prendre au sérieux) · mainHandItem() / offHandItem() / activeItem() / isHoldingItem(id) · isSneaking() / isSprinting() / isSwimming() / isCreative() / isSpectator().

Classes utilitaires

DataReader (décodage unifié)

Resources.read, Files.read et Networking.fetch le retournent tous — le décodeur d’une séquence d’octets :

asString(): String? (UTF-8) · asBufferedImage(): BufferedImage? · asFont(): Font? (TTF/OTF ; l’implémentation dépose un fichier dans le répertoire temporaire — en cas de disque saturé, nettoyez les résidus préfixés +~JF) · asByteArray(): byte[] · openInputStream(callback) (ferme le flux automatiquement) · asInputStream() (à fermer vous-même). Un échec de décodage retourne null et signale l’erreur dans la console.

Autres utilitaires

Fonctionnalités des scripts

include (inclusion entre scripts)

include(Resources.id("mtrsteamloco:scripts/display_helper.js"));  // chemin absolu
include("./util/common.js");                                     // relatif au script courant

Charge et exécute un autre fichier JS pendant la phase d’analyse (accepte un chemin relatif sous forme de chaîne, ou un Identifier).

Références croisées entre entrées de script

Une entrée de script qu’aucun contenu du même pack ne référence est refusée au chargement par défaut (pour prévenir un scriptId oublié) ; ajoutez "forceLoad": true à l’entrée pour la charger de force — utile pour partager une entrée de script entre packs, ou pour qu’une entrée MTR 3 emprunte une déclaration partagée MTR 4 ; attention à l’ordre de chargement des packs (le déclarant doit être chargé en premier).

Classes de compatibilité ANTE

SoundHelper (lecture de sons façon ANTE), TickableSound, GlobalRegister, ComponentUtil (utilitaires de composants de texte vanilla) et le asJavaArray(list, class) global sont disponibles depuis v2.3, avec des signatures identiques à ANTE, pour faciliter la migration du contenu ANTE.

Ensuite : Types de scripts JS — les API dédiées aux véhicules / décorations / ascenseurs / PIDS ; Extensions Yanyang — les capacités que cette branche ajoute par-dessus JS.