# Scripts

Scripts are the heart of your layout automation. A script consists of a sequential set of [actions](https://modeltrainscript.gitbook.io/docs/manual/automation/scripts/action), organised into one or more [sections](https://modeltrainscript.gitbook.io/docs/manual/automation/scripts/section).

For a better overview, we recommend organising your scripts in a folder structure.

## Configuration <a href="#configuration" id="configuration"></a>

<figure><img src="https://4224524483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjZj7d8De4optEMsLAji%2Fuploads%2Fg6dkMSZ9nJvHUxyeSZdh%2Fimage.png?alt=media&#x26;token=9765e8bc-ba0d-4324-ade9-6a585e00c336" alt="" width="188"><figcaption></figcaption></figure>

A script has the following configuration options:

| Setting              | Description                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**             | A descriptive name for the script.                                                                                                                        |
| **Tags**             | Labels used for categorisation and [random script execution](https://modeltrainscript.gitbook.io/docs/manual/automation/action/structure#execute-script). |
| **Show in throttle** | Whether the script appears in the automate tab of the [throttle](https://modeltrainscript.gitbook.io/docs/manual/throttle).                               |
| **Disabled**         | A disabled script cannot be executed — manually or by events.                                                                                             |
| **Notes**            | Free-text notes for documenting what the script does.                                                                                                     |

### Repeat

A script can be set to repeat. When repeat is enabled, the script runs all its sections and then evaluates the repeat conditions:

* **No repeat conditions** — The script repeats indefinitely until you manually stop it.
* **With repeat conditions** — The script repeats only while the conditions are met. You can combine multiple conditions with **AND** (all must match) or **OR** (any must match).

### Auto cancel

When enabled, the script is automatically cancelled after a configurable timeout (in milliseconds). This is a safety net to prevent scripts from running indefinitely if something unexpected happens.

### Show notification

When enabled, a system notification is shown whenever the script starts running.

## Execution <a href="#execution" id="execution"></a>

A script can be triggered either **manually**, by an **event**, or both.

### Manual triggered scripts

<figure><img src="https://4224524483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjZj7d8De4optEMsLAji%2Fuploads%2FdRt4IDFVUcVmNr8QUxa5%2Fimage.png?alt=media&#x26;token=d38720a0-ad12-4675-9fd1-e25d82d49da3" alt="" width="188"><figcaption><p>Manual scripts can be triggered<br>from the automation tab</p></figcaption></figure>

Manual scripts can be started from the automate tab of the [throttle](https://modeltrainscript.gitbook.io/docs/manual/throttle) or from within a [time table](https://modeltrainscript.gitbook.io/docs/manual/automation/time-tables).

### Event triggered scripts

Scripts can be triggered by **events** originating from:

* **Accessories** — When an accessory changes to a specific state.
* **Feedback sensors** — When a sensor becomes active or inactive, optionally filtering by a specific vehicle (RailCom). Can auto-select the detected vehicle for use in the script.
* **Vehicles** — When a vehicle's speed, direction, function, or profile changes.
* **Cameras** — When a [camera](https://modeltrainscript.gitbook.io/docs/manual/automation/cameras) detects a vehicle at a detection point.
* **Time** — At a specific time (hour and/or minute). Supports wildcards — for example, every hour at minute 30.
* **Variables** — When a [variable](https://modeltrainscript.gitbook.io/docs/manual/automation/variables) reaches a specific value.
* **System** — When the command station connects (startup).
* **Scripts** — When another script starts, finishes, or is cancelled.

A script can have **multiple execution events** — any of them will trigger the script.

<figure><img src="https://4224524483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjZj7d8De4optEMsLAji%2Fuploads%2FkwJI5eeTilRpfX8mhKsO%2Fimage.png?alt=media&#x26;token=c6fe14d5-c163-4e7c-ba6e-c44dc72b7099" alt="" width="188"><figcaption><p>Different types of<br>execution events</p></figcaption></figure>

### Execute conditions

Event-based scripts can also define **conditions** for execution. Even when an event triggers, the script only runs if its conditions are met. You can combine multiple conditions using **AND** (all must match) or **OR** (any must match).

<figure><img src="https://4224524483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjZj7d8De4optEMsLAji%2Fuploads%2FvntL55Tuq0quG6rM0hAz%2Fimage.png?alt=media&#x26;token=d8d35759-5063-4d7c-8516-b5d7c5d4a3e0" alt="" width="188"><figcaption><p>Different types of conditions</p></figcaption></figure>

Conditions can be defined for accessories, feedback sensors, vehicle state, flags, variables, or camera detection.

## Sections <a href="#section" id="section"></a>

A script is divided into [sections](https://modeltrainscript.gitbook.io/docs/manual/automation/scripts/section). Sections let you organise your actions into logical groups to keep an overview of what can become many sequential steps. For example, you might have sections like "Depart from station A", "Travel to station B", and "Arrive at station B".

You can create and reorder sections using the edit and add buttons in the top bar.

## Execution log

When a script runs, each action's execution is logged. You can view the log to see exactly what happened, including timing, results, and any captured images (e.g., from camera detection or path finding). This is helpful for debugging scripts.

## Examples <a href="#examples" id="examples"></a>

For inspiration or a better understanding of the features, have a look at the [tutorials](https://modeltrainscript.gitbook.io/docs/manual/automation/tutorials) or the [examples](https://modeltrainscript.gitbook.io/docs/manual/automation/examples).