====== MTR Custom Scripting: Advanced Train Behavior & PIDS Controls ====== 

====== Overview ======
This page details how to implement custom JavaScript hooks using the **Minecraft Transit Railway (MTR)** mod scripting engine. Scripting allows content developers to dynamically override train behaviors, manipulate custom destination boards (PIDS), and intercept station event triggers in real-time. 

====== Setup & Implementation ======
MTR scripts run in a JavaScript runtime environment. To register a custom script, place your script file in your resource pack or server addon directory: 

* PATH: assets/mtr/scripts/custom_train_logic.js

==== Registering in config.json ====
Reference your script inside your train's config.json entry: 

====== Core Script Template ======
Below is the boilerplate code structure required to intercept MTR lifecycle hooks, manage train speed, and dynamically update the train's display systems. 

====== API Reference ====== 

^ Hook / Method ^ Type ^ Description ^ 

| onTrainUpdate(train, world) | Lifecycle Hook | Fires every tick for every active train running the script. |
| onTrainSpawn(train) | Lifecycle Hook | Fires exactly once when a train is initialized/spawned on a siding. |
| train.getSpeed() | Float | Returns the current train velocity in meters per tick. |
| train.isStoppedAtPlatform() | Boolean | Returns true if the train is static and servicing an active station platform. |
| train.setCustomText(string) | Method | Overrides the destination matrix string rendered on the exterior PIDS boards. |
| train.setHeadlightsEnabled(bool)| Method | Manually toggles the emissive texture rendering state for train lighting arrays. | 

====== In-Game Deployment Workflow ====== 

1. Package your updated script and config.json file inside your resource pack zip/folder.
2. Load Minecraft and apply the resource pack in your active packs settings menu.
3. Run the in-game command %%/mtr reload%% to clear cached JavaScript runtimes and instantly push script adjustments live without a server reboot.
4. Inspect the client logs (latest.log) to catch any thrown JavaScript compilation syntax errors or runtime exceptions.

====== Related Wiki Sections ====== 

* [[mtr:4.0.x:content_developer|MTR 4 Content Developer Resource Manual]]
* [[mtr:adding_custom_resources|Adding Custom Train Models & Resource Packs]]
* [[mtr:scripting:pids_manipulation|Advanced PIDS Layout Design Syntax]]