View source for JCM:Building a Scripted PIDS Preset

This is a step-by-step tutorial on building a Scripted PIDS Preset using JavaScript.

By the end of the tutorial, you would have built a Fictional LRT (Light Rail) version of the MTR Railway Vision PIDS, which can adapt to Custom PIDS Messages and handling long string.
[[File:JCM JS PIDS Tutorial Result.png|none|thumb|413x413px|Top: Default RV PIDS Preset, Bottom: Custom JS-based PIDS Preset]]

=== Getting started ===
To get started, [https://www.joban.org/archive/misc/JCM_PIDS_Tutorial_Scripting_Pack.zip download the tutorial resource pack here] ,extract the zip and put it in Minecraft's Resource Pack folder.

This resource pack is specifically set-up for this tutorial, and therefore the JS scripts inside are (mostly) empty. However we can still take a look at how a Scripted PIDS Preset is set-up.

==== joban_custom_resources.json ====
The file will look like this:
<pre>
{
  "pids_images": [
    {
      "id": "pids_tut",
      "name": "DIY JS Preset",
      "scripts": ["jsblock:scripts/pids_tut.js"]
    }
  ]
}
</pre>

This is mostly the same from a JSON PIDS Preset, except the <code>scripts</code> property which is a JSON array that points to the scripts used for this preset.

Multiple scripts can be used for the same preset as well. However to keep things simple, we are simply going to use 1 script to control the rendering: <code>scripts/pids_tut.js</code>.

==== scripts/pids_tut.js ====
By opening up '''pids_tut.js''' in the '''scripts''' folder in a text editor (Notepad etc.), we can see the following script:

<pre>
function create(ctx, state, pids) {
  // Your custom logic here...
}

function render(ctx, state, pids) {
  // Your custom logic here...
}

function dispose(ctx, state, pids) {
  // Your custom logic here...
}
</pre>

Our custom logic can be placed between each curly brackets for each of the function. As seen, there are a total of 3 functions: <code>create</code>, <code>render</code>, <code>dispose</code>.

The <code>create</code> function is called when our PIDS enters the player's view. So this means that when a player switches the PIDS preset to our preset, or if a player is approaching a station with our PIDS in sight, everything within the curly bracket of the create function will be run.

The <code>render</code> function is called every frame (So 60fps = 60 times per second)*. Notice the asterisk? Because running scripts simply takes time, even if a short amount of time. JCM will ''try to'', whenever possible, call your function every frame. However if there are too many scripts or your script is slow, then it may not be called every frame.

The <code>dispose</code> function is called when a PIDS Preset is switched away from, or the PIDS is no longer in sight for the player. This can be used to do clean-up work in complex PIDS that stores texture etc.

The most useful one we are going to use is the <code>render</code> function, since this is where we can obtain up-to-date information and dynamically render our PIDS.

But let's not get ahead of ourselves, and instead start from something very simple: ''A hello world script''.

==== Hello, World! ====
First, let's insert <code>print("Hello World ^^");</code> to the brackets within the <code>create</code> function. This calls the <code>print</code> function with the argument <code>"Hello World ^^"</code>. The <code>print</code> function will output the message in our Minecraft console.

Now, let's insert <code>print("Goodbye World ^^;");</code> within the <code>dispose</code> function as well.

After that, we can press F3+T to reload our resource pack and look at your game console!

You should the following message:

<code>[JCM] [Scripting] Hello World ^^</code>

<code>[JCM] [Scripting] Hello World ^^</code>

As PIDS in JCM (as well as MTR) are constructed in a way where each "side" is drawn separately, a normally placed PIDS will would call the function 2 times. This is normal behavior, you didn't do anything wrong!

Now, try going very far away from the PIDS, to the point where you can visually no longer sees them. (More technically, when the PIDS chunk is no longer loaded). You will notice the following 2 messages shows up in the console:

<code>[JCM] [Scripting] Goodbye World ^^;</code>

<code>[JCM] [Scripting] Goodbye World ^^;</code>

There you have it, a very simple Hello World script running in JCM.

''(p.s. In case you got lost, run'' <code>/tp 0 -60 0</code>'').''

So this concludes the Scripted PIDS tutorial, I hope that...

==== No where are you going! ====
ok I am sorry :<

Now let's actually draw the "Hello World" text onto the PIDS, ''because printing to the game console isn't considered exciting for most players apparently''.

We can insert the following code to the <code>render</code> function to draw a text with the content '''Hello World''':

<pre>
function render(ctx, state, pids) {
    Text.create().text("Hello World").draw(ctx);
}
</pre>

If this looks confusing, we can also split it line by line in the code:

<pre>
function render(ctx, state, pids) {
    Text.create()
    .text("Hello World")
    .draw(ctx);
}
</pre>

This creates a text, setting its text content to '''Hello World''', and then drawing it to <code>ctx</code> (Which is a provided parameter in the render function, more on that later).

A statement is only considered finish by ending with a semicolon (<code>;</code>), so our code will still work after breaking down to different lines. For readability purposes, opening new line is generally preferred.

Anyway now let's save the file, reload with F3+T and see what happens!
[[File:JCM PIDS Tutorial v0.1.png|thumb|371x371px|*checks date* It's not April Fools yet is it?|none]]

Ok our text ''do'' actually get rendered, the only problem is that the default text color is black, and as you might have realized, ''black-on-black may not necessarily be a very visible color combination.'' So let's change our text to be rendered with the white color instead.

The hex color code for a solid white color is <code>FFFFFF</code>, so we can add the following line to our text:

<code>.color(0xFFFFFF)</code> (<code>0x</code> is used to depict that the number is a hexadecimal number)

So our text block should look something like this:

<pre>
Text.create()
.text("Hello World")
.color(0xFFFFFF)
.draw(ctx);
</pre>

''<small>Note that <code>.draw()</code> is the final command and you cannot append anything afterwards, so any setting must be appended before <code>.draw()</code>.</small>''

Now reload our resource pack again and we now see our text!
[[File:JCM JS PIDS Tutorial v0.2.png|none|thumb|366x366px|A white text in our PIDS saying "Hello World"]]
With this logic, we can append a second Text block to render a 2nd text as well:<pre>
function render(ctx, state, pids) {
    Text.create()
    .text("Hello World")
    .color(0xFFFFFF)
    .draw(ctx);
    
    Text.create()
    .text("Joban Client Mod v2!")
    .color(0xFFFFFF)
    .draw(ctx);
}
</pre>
[[File:JCM JS PIDS Tutorial v0.3.png|thumb|389x389px|I mean it technically did render twice...|none]]

But it's hard to see, let's move each of them apart. We can use the <code>.pos(x, y)</code> command to set the position of an element.

By default, a text have a height of <code>9</code>, so we can append <code>.pos(0, 9)</code> to set the text position to 9 unit downwards:

<pre>
function render(ctx, state, pids) {
    Text.create()
    .text("Hello World")
    .color(0xFFFFFF)
    .draw(ctx);

    Text.create()
    .text("Joban Client Mod v2!")
    .color(0xFFFFFF)
    .pos(0, 9) // <----
    .draw(ctx);
}
</pre>
[[File:JCM JS PIDS Tutorial v0.4.png|thumb|407x407px|''<small>(The reason the bottom line appears to be more "left" than the top line is due to Minecraft's imperfection when rendering TTF font, it will work fine if you switch to Minecraft font or with most other text combination)</small>''|none]]

==== Rendering Arrivals ====
During the tutorial, you might have noticed the <code>pids</code> object in the create/render/dispose function. This represents our PIDS object, where we can obtain arrivals and more from there.

We can get a list of arrivals with <code>pids.arrivals()</code>, and then obtain the n<sup>th</sup> arrival info with the <code>.get(n)</code> function.

So to obtain the first arrival entry, we can do so like this:

<pre>
let firstRowArrival = pids.arrivals().get(0);
</pre>You can obtain a variety of information in the arrival entry, which includes it's route/LRT number, it's arrival and departure time, the route it's running and more. You can refer to the documentation '''[TODO]''' for further information.

Here however, we are only interested in getting the destination (i.e. Where the train is going), so we can do that with the <code>destination()</code> function.

<pre>
let firstRowArrival = pids.arrivals().get(0);
let firstRowDestination = firstRowArrival.destination();
</pre>And now we can draw this to our text, by replacing the .text() content with firstRowDestination:

<pre>
function render(ctx, state, pids) {
    let firstRowArrival = pids.arrivals().get(0);
    let firstRowDestination = firstRowArrival.destination();
    
    Text.create()
    .text(firstRowDestination) // <--- Here
    .color(0xFFFFFF)
    .pos(0, 0)
    .draw(ctx);
    
    Text.create()
    .text("Joban Client Mod v2!")
    .color(0xFFFFFF)
    .pos(0, 9)
    .draw(ctx);
}
</pre>Or a one-liner version, without setting variable:

<pre>
function render(ctx, state, pids) {
    Text.create()
    .text(pids.arrivals().get(0).destination()) // <--- Here
    .color(0xFFFFFF)
    .pos(0, 0)
    .draw(ctx);
    
    Text.create()
    .text("Joban Client Mod v2!")
    .color(0xFFFFFF)
    .pos(0, 9)
    .draw(ctx);
}
</pre>
[[File:JCM JS PIDS Tutorial v0.5.png|none|thumb|368x368px]]
However before we continue, there is a few problem with this:

# An arrival is not guaranteed to exist. For example if the client is still fetching the arrival info, or there are no arrival on that platform. This would cause the script to error out (Which you may have spotted in the console, but JCM will try to re-run the script every 4 second)
# Imagine a script filled with <code>Text.create()</code>, how would you be able to easily tell which text is which?

For the latter, you could add JS comments with <code>//</code>. However JCM also reserved a slot for comment, and that is within the <code>Text.create(string)</code> function. So as an example, you can do the following:<pre>
Text.create("1st row destination") // <----
.text(firstRowDestination)
.color(0xFFFFFF)
.pos(0, 0)
.draw(ctx);
</pre>The '''<u>1st row destination</u>''' text is purely cosmetic and you can write any string within that, so this could be served as a comment. However whether this is preferable depends on your personal preferences.

Now for the former arrival issue, we can add a null check to ensure that the arrival exists first:<pre>
function render(ctx, state, pids) {
    let firstRowArrival = pids.arrivals().get(0);
    if(firstRowArrival != null) { // <-- Check if arrival exists first
        Text.create("1st row destination")
        .text(firstRowArrival.destination())
        .color(0xFFFFFF)
        .pos(0, 0)
        .draw(ctx);
    }
    ...
}
</pre>Now this might be fine for rendering 1 arrival, but imagine we have to display 4 arrivals, duplicating this code 4 times is cumbersome. Instead we can change this to a for-loop:<pre>
function render(ctx, state, pids) {
    for(let i = 0; i < 4; i++) { // Set i to 0. i+1 if i < 4, otherwise don't run this anymore
        let arrival = pids.arrivals().get(i); // <---- Obtain nth row arrival
        if(arrival != null) {
            Text.create("Arrival destination")
            .text(arrival.destination())
            .color(0xFFFFFF)
            .pos(0, i*9) // <--- nth row * text height
            .draw(ctx);
        }
    }
}
</pre>The runs everything within the for loop 4 times, setting the <code>i</code> variable to the n<sup>th</sup> time our code is executed.

As such, we can use <code>i</code> to determine our Y position as well as which arrival to obtain.
[[File:JCM JS PIDS Tutorial v0.6.png|none|thumb|357x357px]]

==== Text size & Language Cycle ====
To resize a text, we can use the <code>.scale(factor)</code> function to scale the text to be larger or smaller.

In our case, we will scale it by 1.25x:<pre>
Text.create("Arrival destination")
.text(arrival.destination())
.color(0xFFFFFF)
.pos(0, i*9)
.scale(1.25) // <---- Scale the text by 1.25x
.draw(ctx);
</pre>
[[File:JCM JS PIDS Tutorial v0.7.png|none|thumb|333x333px]]
The text does seems to be larger! But they are now too close to each other, and are really uncomfortable to look at.

This is because earlier, we set the position of the text to be <code>.pos(0, i*9)</code>. However since our text is scaled, the text height is no longer <code>9</code>, but instead <code>9*1.25 (our scale)</code> = 11.25.

While we could just change it to <code>11.25</code>, let's leave even more padding between each row for a better-look. Let's say each row should go 16.75 unit downwards:<pre>
Text.create("Arrival destination")
.text(arrival.destination())
.color(0xFFFFFF)
.pos(0, i*16.75) // <----
.scale(1.25)
.draw(ctx);
</pre>
[[File:JCM JS PIDS Tutorial v0.8.png|none|thumb|310x310px]]
Much better! The last thing we have to deal with is handling different languages. Currently it's just displayed with everything including the pipe character.

To cycle the string, we can wrap our destination string with the <code>ctx.cycleString(str)</code> function.<pre>
Text.create("Arrival destination")
.text(ctx.cycleString(arrival.destination())) // <---
.color(0xFFFFFF)
.pos(0, i*16.75)
.scale(1.25)
.draw(ctx);
</pre>And there we go, now the text cycles!
[[File:JCM JS PIDS Tutorial v0.9.png|none|thumb|307x307px|[[File:JCM JS PIDS Tutorial v0.10.png|none|thumb|306x306px]]]]
So to re-cap, our code should look similar to this:<pre>
function create(ctx, state, pids) {
    print("Hello World ^^");
}

function render(ctx, state, pids) {
    for(let i = 0; i < 4; i++) {
        let arrival = pids.arrivals().get(i);
        if(arrival != null) {
            Text.create("Arrival destination")
            .text(ctx.cycleString(arrival.destination()))
            .color(0xFFFFFF)
            .pos(0, i*16.75)
            .scale(1.25)
            .draw(ctx);
        }
    }
}

function dispose(ctx, state, pids) {
    print("Goodbye World ^^;");
}
</pre>
=== v1: Light Rail, Light Rail Everywhere! ===
[TODO v1]

=== v2: Something is missing ===
[TODO v2 plat number]

=== v3: It's still missing ===
[TODO v3 header bar]

=== v4: Go ham! ===
[TODO v4 overflow adjustment]

=== v5: It's coming together ===