View source for JCM:Scripting/Utilities

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

===Printing debug information===

<pre>
static print(params: Object...): void
</pre>This function outputs a message to the Minecraft log (''the message is not displayed in the game''). Any number of arguments of any type can be passed to the function.

=== Versions ===
Functions are provided where you can get the version number to ensure compatibility with different versions of mods (if any).
{| class="wikitable"
!Functions
!Description
|-
|<code>static Resources.getAddonVersion(modId: string): string</code>
|Obtain the version of a mod that is hooked to the scripting functionality.
Out of the box in JCM, the possible modId are:

* mtr
* jcm
|-
|<code>static Resources.getMTRVersion(): string</code>
|Returns the version of the MTR, for example, <code>4.0.0-beta.12+1.20.4</code>.
'''DEPRECATED: Use Resources.getAddonVersion("mtr")'''
|-
|<code>static Resources.getNTEVersion(): string</code>
|Returns the version of the NTE (Nemo Transit Expansion) mod.
As there's no NTE for MTR 4, this function is hard-coded to return <code>0.5.2+1.20.4</code>.
|-
|<code>static Resources.getNTEVersionInt(): int</code>
|Returns the NTE (Nemo Transit Expansion mod) version as a number for easy comparison.
As there's no NTE for MTR 4, this function is hard-coded to return <code>502</code>. (For 0.5.2)
|-
|<code>static Resources.getNTEProtoVersion(): int</code>
|Returns the NTE (Nemo Transit Expansion mod) protocol version.
As there's no NTE version for MTR 4, this function is hard-coded to return <code>2</code>.
|}

=== TextUtil ===
MTR uses the station naming format <code>Name in one language|Name in another language||EXTRA</code>, so TextUtil is implemented to provide functions to separate these parts.
{| class="wikitable"
!Functions
!Description
|-
|<code>static TextUtil.cycleString(src: String): String</code>
|Returns a text that cycles different languages. (Delimited by the pipe <code><nowiki>|</nowiki></code> character)
|-
|<code>static TextUtil.cycleString(src: String, duration: int): String</code>
|Returns a text that cycles different languages. (Delimited by the pipe <code><nowiki>|</nowiki></code> character)
The cycle frequency is decided by the <code>duration</code> parameter, in Minecraft Tick.
|-
|<code>static TextUtil.getCjkParts(src: String): String</code>
|Returns the CJK parts of the passed string.
|-
|<code>static TextUtil.getNonCjkParts(src: String): String</code>
|Returns the non-CJK parts of the passed string.
|-
|<code>static TextUtil.getExtraParts(src: String): String</code>
|Returns the extra part of the passed string.
|-
|<code>static TextUtil.getNonExtraParts(src: String): String</code>
|Returns everything except the extra part.
|-
|<code>static TextUtil.getNonCjkAndExtraParts(src: String): String</code>
|Returns everything except the CJK parts.
|-
|<code>static TextUtil.isCjk(src: String): boolean</code>
|Checks whether the string contains CJK characters.
|}

=== Timing ===
{| class="wikitable"
!Functions
!Description
|-
|<code>static Timing.elapsed(): double</code>
|Returns the running time of the game in seconds. It is constantly increasing, even when the game is paused.


|-
|<code>static Timing.delta(): double</code>
|The time difference between the current <code>render</code> 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.
|}

=== 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 <code>if (…distance < 300) ctx.play…</code> 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 <code>state</code> variable.
{| class="wikitable"
!Functions
!Description
|-
|<code>new StateTracker()</code>
|Creates StateTracker.


|-
|<code>StateTracker.setState(value: string): void</code>
|Sets the new state.
|-
|<code>StateTracker.stateNow(): string</code>
|Returns the current state.
|-
|<code>StateTracker.stateLast(): string?</code>
|Returns the previous state. If it does not exist, <code>null</code> is returned.
|-
|<code>StateTracker.stateNowDuration(): double</code>
|Returns the amount of time the current state lasts.
|-
|<code>StateTracker.stateNowFirst(): boolean</code>
|Was the state just changed by the <code>setState</code> function in this loop or not?
|}

== CycleTracker ==
This is a <code>StateTracker</code> 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 <code>state</code> variable.
{| class="wikitable"
!Functions
!Description
|-
|<code>new CycleTracker(params: Object[])</code>
|Creates a CycleTracker.

The parameters are the states it will switch through and the duration of each state in seconds.

Example: <code>new CycleTracker([“route”, 5, “nextStation”, 5])</code>.


|-
|<code>CycleTracker.tick(): void</code>
|Updates the status based on the current time.
|-
|<code>CycleTracker.stateNow(): string</code>
|Returns the current state.
|-
|<code>CycleTracker.stateLast(): string?</code>
|Returns the previous state. If it does not exist, <code>null</code> is returned.
|-
|<code>CycleTracker.stateNowDuration(): double</code>
|Returns the amount of time the current state lasts.
|-
|<code>CycleTracker.stateNowFirst(): boolean</code>
|Was the state just changed by the <code>setState</code> 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 <code>state</code> variable.
{| class="wikitable"
!Functions
!Description
|-
|<code>new RateLimit(params: Object[])</code>
|Creates a RateLimit.

<code>interval</code> is the interval in seconds between two triggers, for example, an interval of 0.1 means it should occur ten times per second.


|-
|<code>RateLimit.shouldUpdate(): boolean</code>
|Has enough time elapsed between the last triggers?
Wrap the necessary code using

<code>if (state.rateLimitXXX.shouldUpdate()) { … }</code> to limit its execution frequency.
|-
|<code>RateLimit.resetCoolDown(): void</code>
|Resets the timer to go off as soon as possible.
|}

=== MTRClientData ===
Client data from MTR that can be used to read routes, transfers, etc. See the source code of [https://github.com/Minecraft-Transit-Railway/Minecraft-Transit-Railway/blob/master/fabric/src/main/java/org/mtr/mod/client/MinecraftClientData.java MinecraftClientData.java] from MTR.

=== MinecraftClient ===
Due to obfuscation, there is no way to directly provide a client class for use. Therefore, several helper methods are created:
{| class="wikitable"
!Functions
!Description
|-
|<code>static MinecraftClient.worldIsRaining(): boolean</code>
|Is it raining in the world?


|-
|<code>static MinecraftClient.worldIsThundering(): boolean</code>
|Is it thundering in the world?


|-
|<code><s>static MinecraftClient.worldIsRainingAt(pos: Vector3f): boolean</s></code>
|Is it raining and getting wet in a given chunk?
'''[Not Implemented]'''
|-
|<code>static MinecraftClient.worldDayTime(): int</code>
|Returns the in-game world time in ticks.
|-
|<code>static MinecraftClient.narrate(message: string): void</code>
|This calls the Minecraft narrator to narrate the message.
|-
|<code>static MinecraftClient.displayMessage(message: String, actionBar: boolean): void</code>
|This displays the message as an in-game chat message. If action bar is true, it will display on the action bar instead. (Above inventory hotbar)
|}