Paths
A path is a sequence of layout items that describes where a train should drive. Model Train Script uses paths in three places:
- Throttle — for manual moves through navigation mode.
- Set path action — automation that finds and sets turnouts toward a destination. See Set path.
- Request clearance action — coordination through the Train Dispatcher. See Request clearance.
Understanding how paths are built means you can use the same definition across all three — and pick the strategy that fits your operation.
Anatomy of a path
A path is built from a sequence of path positions — references to items on your layout:
| Position | Description |
|---|---|
| Start | The first item. The train begins here. |
| Waypoints | Optional intermediate items the path must pass through, in order. |
| End | The last item, the destination. |
Given those positions, the path finder walks the physical connections between your layout items, produces every valid sequence between them, and picks one according to the path strategy.
INFO
The path finder relies on layout connectivity: track edges must line up between neighboring cells. Items that look connected but aren't will silently exclude valid routes. Verify connectivity in the layout editor when a path doesn't behave as expected.
Path strategy
When more than one valid sequence of items connects your start, waypoints, and end, the strategy decides which is chosen:
| Strategy | Picks | Use when |
|---|---|---|
| Shortest | The path with the fewest items. | You want predictable, repeatable behavior. Good default. |
| First available | The first path the finder builds. | Path quality matters less than computation speed (large or complex layouts). |
| Random | A random valid path. | You want variety — e.g. a script that should pick a different platform each run. |
If only one valid path exists, the strategy has no effect.
Best practices
Use waypoints to disambiguate. When several corridors connect the same two points, the shortest path may not be the operational one you have in mind. Drop a waypoint on the corridor you want and the path finder is forced through it.
Reuse the same start and end items across scripts. Treat a small set of layout items (a platform, a siding head, a yard ladder) as named anchors and reference them from every script that drives there. Moving or renaming an item then updates every script that uses it.
Pair Set path (require free path) with Request clearance. Clearances arbitrate against other clearances — they don't watch feedback sensors. If you also need to avoid physically occupied track, run Set path with require free path before Request clearance. The first guards against unsignalled trains; the second guards against other scripts.
Pick a strategy intentionally. A shuttle that should never deviate wants shortest. A "send a freight to any free yard track" script wants random combined with require free path. First available is mostly a performance escape hatch — most layouts are small enough for shortest to be fine.
Test in debug mode. Debug mode runs your scripts without the command station — the cheapest way to find an ambiguous path or a missing waypoint before a real train discovers it.