Request clearance
Asks the Train Dispatcher for permission to drive a path. When the clearance is granted, the action sets the turnouts along the path and the script continues. When another clearance already claims part of the path, the action waits until that clearance is released and then tries again. The script only continues once it holds the clearance.
Settings
Path
| Setting | Description |
|---|---|
| Custom / From profile | Define the path in this action (Custom), or use one of the paths saved in your profile (From profile). The second option only appears when your profile has saved paths. |
| Set path positions | Only for Custom: the layout items the path goes through. The first item is the start, the last is the destination, and everything in between is a waypoint. This works the same as for Set path; see Paths for details. |
| Path strategy | Only for Custom: how to choose when several paths are possible: shortest, first available or random. See Path strategy. |
| Label | Only for Custom: an optional label that replaces the automatic "from … to …" description in the Clearances list and in notifications. Useful when the start and end items don't explain the path by themselves. |
Clearance name
| Setting | Description |
|---|---|
| Name | Optional. A name for the clearance, so other scripts can release it. You can type a new name or pick one that is already used in your profile. Names ignore upper case and surrounding spaces, so Yard and yard are the same name. Leave it empty for the default behavior. |
Without a name, a script holds at most one clearance. With a name, a script can hold several clearances at the same time, and any script can release a clearance by its name with Release clearance.
When waiting is required
| Setting | Description |
|---|---|
| Before | Optional script that runs when the action has to wait, typically to stop the vehicle or store its state. |
| After | Optional script that runs once the clearance is granted after waiting, typically to start the vehicle again or restore its state. |
How it works
- The clearance is registered with the script's name as owner, so the Clearances section of the automation tab shows who holds which path.
- The Before and After scripts only run when the clearance can't be granted right away. When the dispatcher grants it on the first try, neither script runs.
- Before and After run inside the calling script, so they work on the same selected vehicle and stored state. Because they come as a pair, use them symmetrically: stop in Before and start again in After, or store in Before and restore in After.
- When no path exists between the positions at all, the action does not wait. The script continues without a clearance, and the execution log shows "No path found".
- The dispatcher only knows about clearances, not about occupied track. If the path must also be physically free, run a Set path with Require unoccupied path before requesting the clearance.
WARNING
Always pair a Request clearance with a Release clearance once the train has left the path. A clearance that is never released keeps the track reserved and blocks other trains. A stuck clearance can be removed by hand in the Clearances section of the automation tab.
Example
Two shuttle trains share a single-track section. Each script requests a clearance for the section before departing, with Before set to a script that stops the train and After set to a script that starts it again. Once the train has arrived at the other end, the script releases the clearance and the other train can go. See the Train Dispatcher tutorial for a complete walkthrough.