> For the complete documentation index, see [llms.txt](https://modeltrainscript.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://modeltrainscript.gitbook.io/docs/manual/vehicles.md).

# Vehicles

The vehicle list is where you register your locomotives and their functions. Once configured, vehicles can be controlled manually via the [throttle](/docs/manual/throttle.md) and used in [automation scripts](/docs/manual/automation.md).

For Z21 users, vehicles are created manually. For ECoS users, vehicles can be imported directly from the command station — including their name, address, and function mappings — and edited afterwards.

<figure><img src="/files/ifobOxMwUWLPG5uJGjX1" alt="" width="188"><figcaption><p>Editing an example vehicle</p></figcaption></figure>

## Configuration

Every vehicle needs a **name** and a DCC **address**. Optionally you can add an **image** — either from the built-in library of locomotive avatars or by uploading your own photo.

**Speed steps** — Model Train Script supports 14, 28, and 128 speed steps. Choose the setting that matches your decoder configuration. 128 steps gives the smoothest control.

**Function only** — Enable this if the vehicle has no motor and only responds to function commands (e.g. a sound car or lighting wagon). Speed and direction controls will be hidden in the throttle.

**Tags** — Add tags to organize your vehicles by type, era, railroad company, or any other category. Tags can be used to filter the vehicle list in the throttle for quick selection.

## Functions

Functions represent the controllable features of your locomotive — lights, sounds, couplers, smoke, and more. Each function requires:

* **Icon** — A visual symbol from a library of 40+ icons covering lights, sounds, couplers, pantographs, smoke units, and more.
* **Name** — An optional label displayed below the icon in the throttle.
* **Index** — The DCC function number (F0–F31) as configured in your decoder.
* **Type** — How the function behaves:
  * **Toggle** — Stays on or off until tapped again (e.g. headlights).
  * **Pulse** — Sends a brief activation impulse (e.g. horn, whistle).
  * **Time** — Stays active for a specified duration in milliseconds, then deactivates automatically.

You can reorder functions freely — the throttle displays them in your preferred order.

## Consisting

Model Train Script supports decoder-based consisting (multi-traction). Configure a **consist address** on the vehicle, and the throttle and automation scripts will use that address to control the locomotive as part of a consist.

Some decoders allow enabling and disabling consisting via a function key. In Model Train Script you can make the consist **conditional** — the consist address is only used when the selected function is active. This lets you couple and uncouple locomotives without reconfiguring addresses.

## Profiles

Profiles are shortcuts to set a vehicle's state with one tap. Each profile can define:

* **Speed** — A target speed percentage.
* **Direction** — Forward or reverse.
* **Functions** — Which functions should be on, off, or left unchanged.

Five profile types are available: **idle**, **shunting**, **slow**, **medium**, and **fast**. Apply a profile from the star icon in the [throttle](/docs/manual/throttle.md), or use the **set profile** action in your [automation scripts](/docs/manual/automation.md).

## Flags

Flags linked to a vehicle are automatically set when the locomotive is selected in an automation script. This allows your scripts to adjust their behavior based on which vehicle is currently active — for example, enabling sound-related actions only for locomotives that have a sound decoder.

## Notes

A free text field for tracking vehicle specifics like model number, decoder type, or maintenance notes. When importing from ECoS, this field is automatically populated with the import timestamp.