Utilities

As the scripting functionality is based on the Nemo Transit Expansion addon, a number of helper classes are inherited from NTE to provide information or to simplify code implementation.

Versions Querying#

Functions are provided where you can get the version number to ensure compatibility with different versions of mods (if any).

mtrscripting" vs "jcm

Currently the mtrscripting addon id is equivalent to jcm.

This id is reserved for when scripting may be split to an individual addon from JCM.
If you are using Vehicle/Eyecandy scripting and requiring checking for API compatibility, use mtrscripting instead.
If you are using PIDS Scripting, continue checking jcm.

Functions	Description
`static Resources.getAddonVersion(modId: String): String`	Obtain the version of a mod that is hooked to the scripting functionality. Out of the box in JCM, the possible value of `modId` are: - mtr - jcm - mtrscripting

Show deprecated fields/functions

These functions are kept for backward compatibility with NTE/ANTE. You are advised to avoid using these functions for newly created scripts.

Functions	Description
`static Resources.getMTRVersion(): String`	Returns the version of the MTR mod in String. (e.g. `4.0.3`) Use `Resources.getAddonVersion()` instead.
`static Resources.getNTEVersion(): String`	Obtain the version of NTE in String. As NTE did not get ported to MTR 4, it always returns `0.5.2+1.19.2` for backward compatibility.
`static Resources.getNTEVersionInt(): int`	Obtain the version of NTE in integer. As NTE did not get ported to MTR 4, it always returns `502` for backward compatibility.
`static Resources.getNTEProtoVersion(): int`	Obtain the version of NTE's protocol version in integer. As NTE did not get ported to MTR 4, it always returns `2` for backward compatibility.

TextUtil#

The MTR mod uses the station naming format Name in one language|Name in another language||EXTRA, so TextUtil is implemented to provide functions to separate these parts.

Functions	Description
`static TextUtil.getCjkParts(src: String): String`	Returns the CJK parts of the passed string.
`static TextUtil.getNonCjkParts(src: String): String`	Returns the non-CJK parts of the passed string.
`static TextUtil.getExtraParts(src: String): String`	Returns the extra part of the passed string.
`static TextUtil.getNonExtraParts(src: String): String`	Returns everything except the extra part.
`static TextUtil.getNonCjkAndExtraParts(src: String): String`	Returns everything except the CJK parts.
`static TextUtil.isCjk(src: String): boolean`	Checks whether the string contains CJK characters.
`static TextUtil.cycleString(src: String): String`	Returns a text that automatically cycles between different languages. (Delimited by the pipe `\|` character)
`static TextUtil.cycleString(src: String, duration: int): String`	Same as above, with a specified cycle duration (In Minecraft Tick).

Timing#

Functions	Description
`static Timing.elapsed(): double`	Returns the running time of the game in seconds. It is constantly increasing, even when the game is paused.
`static Timing.delta(): double`	The time difference between the current `render` call and the previous one. This can be used, for example, to calculate the angle by which the wheel have turned during the elapsed time.
`static Timing.currentTimeMillis(): long`	Returns the current time in millisecond (Since 1970/1/1). This is the same as Java's System.currentTimeMillis()
`static Timing.nanoTime(): long`	This is the same as Java's System.nanoTime()

StateTracker#

Sometimes it is necessary to take transition states into account. For example, to play an animation only once when a certain condition is reached (because if (…distance < 300) ctx.play… would be satisfied every frame after the condition was met, and then play every frame after that, which would result in hundreds of animations), or to play an animation in the first second after a page switch.

Since each object should have its own tracker, you would probably want to store it in the script's state variable.

Functions	Description
`new StateTracker(): StateTracker`	Create an instance of StateTracker.
`StateTracker.setState(value: object?): void`	Sets the new state.
`StateTracker.stateNow(): object?`	Returns the current state.
`StateTracker.stateLast(): object?`	Returns the previous state. Null if the previous state doesn't exist.
`StateTracker.stateNowDuration(): double`	Returns the amount of time the current state lasts.
`StateTracker.stateNowFirst(): boolean`	Was the state just changed by the `setState` function in this loop or not?
`StateTracker.changedTo(value: object?): boolean`	Whether the state just changed to the specified value. This is mostly equivalent to `stateNowFirst() && stateNow() == value` This uses Java's `Objects.equals` method for equality comparison.
`StateTracker.changedFromTo(oldValue: object?, value: object?): boolean`	Whether the state just changed from oldValue to value. This is mostly equivalent to `stateNowFirst() && stateLast() == oldValue && stateNow() == value` This uses Java's `Objects.equals` method for equality comparison.

CycleTracker#

This is a StateTracker that automatically switches on a cyclic basis by time.

Since each object should have its own tracker, you would probably want to store it in the script's state variable.

Functions	Description
`new CycleTracker(params: Object[]): CycleTracker`	Create an instance of CycleTracker. The parameters are the states it will switch through and the duration of each state in seconds. Example: `new CycleTracker([“route”, 5, “nextStation”, 5])`.
`CycleTracker.tick(): void`	Updates the status based on the current time.
`CycleTracker.stateNow(): String`	Returns the current state.
`CycleTracker.stateLast(): String?`	Returns the previous state. Null if the previous state does not exist.
`CycleTracker.stateNowDuration(): double`	Returns the amount of time the current state lasts.
`CycleTracker.stateNowFirst(): boolean`	Was the state just changed by the `setState` function in this loop or not?

RateLimit#

Some tasks do not require too frequent execution, for example, the display may not be updated every frame, but only 10 times per second. Therefore, you can limit the frequency of their execution to improve performance.

Since each object should have its own tracker, you would probably want to store it in the script's state variable.

Functions	Description
`new RateLimit(interval: double): RateLimit`	Create a new RateLimit instance. `interval` is the interval in seconds between two triggers. For example, an interval of 0.1 means it should occur ten times per second.
`RateLimit.shouldUpdate(): boolean`	Has enough time elapsed between the last triggers? Wrap the necessary code using `if (state.rateLimitXXX.shouldUpdate()) { … }`to limit its execution frequency.
`RateLimit.resetCoolDown(): void`	Resets the timer to go off as soon as possible.