JCM:Scripting:Documentation:PIDS

Adding a Scripted PIDS Preset

A preset is automatically considered as a Scripted PIDS Preset by specifying the scripts property in joban_custom_resources.json:

{
  "pids_images": [
    {
      "id": "pids_tut",
      "name": "JS Tutorial Preset",
      "scripts": ["jsblock:scripts/pids_tut.js"]
    }
}

At the moment, mixing Scripted PIDS Preset and JSON PIDS Preset is not possible.

Global Environment

A script is evaluated & executed when a PIDS Preset is loaded during the resource-pack loading phase.

Therefore, the same type of PIDS Preset will use the same working environment (global variables and etc).

Code written in top-level space outside of functions will run when a resource package is loaded, and can be used to load resources such as models and textures. It is recommended to store resources (such as models, fonts and textures) in global variables, which do not need to be different for each PIDS block, to avoid excessive memory usage caused by loading a copy of the same content for each PIDS.

Called Functions

Your script should include the following functions that JCM will call as needed:

function create(ctx, state, pids) { ... }
function render(ctx, state, pids) { ... }
function dispose(ctx, state, pids) { ... }

Functions	Description
create	It is called when a PIDS is rendered for the first time and can be used to perform some initialization operations, for example, to create dynamic textures.
render	This function is called at-most once per frame. It is used to draw contents onto the PIDS. In practice however, the code is executed in a separate thread so as not to slow down FPS. If it takes too long to execute the code, it may be called once every few frames instead of every frame.
dispose	Called when a PIDS Block goes out of sight. Can be used for things like releasing the dynamic textures to free up memory.

JCM calls these functions with three parameters, each of which is described below.

Parameter	Description
First (ctx)	Used to pass train rendering actions to the NTE. Type — PIDSScriptContext.
Second (state)	A JavaScript object associated with a single PIDS Block. The initial value is {}, and its content can be set arbitrarily to store what should be different for each PIDS Block.
Third (pids)	Used to get the status of pids and arrivals. Type — PIDSWrapper

The following lists all the rendering control operations that can be performed and all the information that can be obtained about PIDS.

PIDSScriptContext

Functions And Objects	Description
PIDSScriptContext.cycleString(mtrString: string): string	This cycles part of a string, separated by the pipe-character (|).

PIDSWrapper

Functions And Objects	Description
PIDSWrapper.isRowHidden(i: number): boolean	Returns whether the arrival for that row is hidden. (via PIDS Config)
PIDSWrapper.getCustomMessage(i: number): string	Returns the custom message configured for that row via PIDS Config. Empty string ("") if not set.
PIDSWrapper.isPlatformNumberHidden(): boolean	Returns whether the platform number is set to hidden. (via PIDS Config)
PIDSWrapper.station(): Station	Returns the station area that this PIDS is in. null if not in any station.
PIDSWrapper.arrivals(): ArrivalsWrapper	Returns the arrivals obtained for the PIDS.

ArrivalsWrapper

Functions And Objects	Description
ArrivalsWrapper.get(i: number): ArrivalWrapper?	Returns the ith arrival entry. null if there's no ith arrival entry or no arrival information.
ArrivalsWrapper.mixedCarLength(): boolean	Returns whether the list of arrivals have arrival entry with different cars.
ArrivalsWrapper.platforms(): ObjectArrayList<Platform>	Returns the platforms that all arrival entry is stopping at.

ArrivalWrapper

Functions And Objects	Description
ArrivalWrapper.destination(): string	Returns the destination name of the arrival entry. (Usually the destination's station, or a custom destination string)
ArrivalWrapper.arrivalTime(): number	Returns the epoch time (in Millisecond) the train is arriving at. Use new Date(value: number)to obtain a JS Date object of the arrival time.
ArrivalWrapper.departureTime(): number	Returns the epoch time (in Millisecond) the train is departing at. Use new Date(value: number)to obtain a JS Date object of the departure time.
ArrivalWrapper.deviation(): number	Returns the deviation[?]
ArrivalWrapper.realtime(): boolean	Returns whether the arrival entry is scheduled (i.e. Train not departed), or a real-time estimation (i.e. Train running)
ArrivalWrapper.departureIndex(): number	Returns the departure index[?]
ArrivalWrapper.isTerminating(): boolean	Returns whether the arrival entry is terminating its service at the current platform.
ArrivalWrapper.route(): Route	Returns the route object of the route that the train is running on.
ArrivalWrapper.routeId(): number	Returns the id of the route that the train is running on.
ArrivalWrapper.routeName(): string	Returns the name of the route that the train is running on.
ArrivalWrapper.routeNumber(): string	Returns the route number string (Previously called LRT Route Number). [TODO: What does empty route number returns?]
ArrivalWrapper.routeColor(): number	Returns the color of the route that the train is running on.
ArrivalWrapper.circularState(): Route.CircularState	Returns the circular state of the route that the train is running on.
ArrivalWrapper.platform(): Platform	Returns the platform object that the train is approaching towards.
ArrivalWrapper.platformId(): number	Returns the id of the platform that the train is approaching towards.
ArrivalWrapper.platformName(): string	Returns the name of the platform that the train is approaching towards.
ArrivalWrapper.carCount(): number	The car length of the train in that arrival entry.
ArrivalWrapper.forEachCar(consumer: Consumer<CarDetails>): void	Allows you to loop through each car of the train in that arrival entry.

Transport Simulation Core Type

Platform

Functions And Objects	Description
Platform.routes: ObjectAVLTreeSet<Route>	A list of routes that goes through this platform.
Platform.routeColors: IntAVLTreeSet	All colors of route that goes through this platform.
Platform.getName(): string	Returns the platform name.
Platform.getId(): number	Returns the platform ID.
Platform.getDwellTime(): number	The dwell time duration of the platform in millisecond.

Route

Functions And Objects	Description
Route.depots: ObjectArrayList<Depot>	A list of depot associated with this route[?]
Route.getName(): string	Returns the platform name.
Route.getId(): number	Returns the route ID.
Route.getColor(): number	Returns the color of the route.
Route.getHidden(): boolean	Returns whether the route is hidden.
Route.getDestination(index: number): string	Returns name of index of the following order: Custom Destination Station Area Name Platform Name
Route.getRouteType(): RouteType	Returns the type of route: NORMAL LIGHT_RAIL HIGH_SPEED