Train dispatcher
This chapter describes the actions that a script uses to coordinate with the Train Dispatcher, Model Train Script's traffic controller for shared track.
By default a script holds at most one clearance at a time and only that script can release it. Optionally, a clearance can be tagged with a clearance name when it is requested, which lets a single script hold several clearances concurrently and lets other scripts release a clearance by referring to the same name.
Request clearance
Asks the dispatcher for permission to drive a path. If granted, the action sets the turnouts along the path and stores the clearance against the running script (and, if given, under the chosen clearance name). If not granted, the action waits until another clearance is released and then tries again (the script does not continue until permission is held).
The editor groups the configuration into three sections:
Path
| Configuration | Description |
|---|---|
| Path positions | The sequence of layout items the path should pass through. The first item is the start, the last is the destination, anything in between is a waypoint. Configure this the same way as for Set path. See Paths for details. |
| Path strategy | How to choose between multiple valid paths through the waypoints: shortest, first available, or random. See Path strategy. |
Optional path label
Replaces the automatic "from … to …" description used in the Clearances list and notifications. Useful when the path's start and end items are not self-explanatory.
Clearance name
| Configuration | Description |
|---|---|
| Name | An optional name for the received clearance, in order for other scripts to control it. Names are normalized (trimmed, lowercased) so Yard and yard are treated as the same name. Leave empty for the default per-script behavior. |
Assigning a name unlocks holding multiple clearances at the same time and cross-script release. Without a name the script is limited to a single clearance.
Optional waiting hooks
| Configuration | Description |
|---|---|
| Before | Optional script that runs as the wait begins — typically used to stop the vehicle or save its state. See When waiting is required. |
| After | Optional script that runs once clearance is granted after a wait — typically used to restart the vehicle or restore its state. See When waiting is required. |
The action records the script's name as the clearance's owner, so you can identify who is holding what in the Clearances section of the automation tab.
INFO
If you also want the action to avoid physically occupied track (not just claimed clearances), use a Set path with require free path before requesting the clearance.
When waiting is required
The Before and After scripts only run when clearance cannot be granted immediately. If the dispatcher grants the clearance on the first try, neither script runs — the action simply continues.
Because they are paired, the typical use is symmetric: stop the vehicle in Before, start it again in After; or save state in Before, restore it in After. The linked scripts run inline in the calling script's context, so they see the same selected vehicle.
Release clearance
Releases a clearance. Other scripts (or manual moves) waiting on overlapping paths immediately retry their request, and typically one of them will now succeed.
The action has these settings:
| Configuration | Description |
|---|---|
| Use clearance name | When off, releases the running script's own active clearance (the default behavior). When on, releases whichever clearance currently carries the given clearance name. |
| Name | Only shown when Use clearance name is on. The clearance name to look up. Pick from the names already used in the profile. |
If no clearance matches (no name is held, or the script doesn't hold one), the action does nothing and the script continues normally.
INFO
Always pair a Request clearance with a Release clearance once the path is no longer needed. Forgetting to release leaves the path reserved indefinitely, blocking other trains. If a clearance does get stuck, you can always remove it manually from the Clearances section of the automation tab.