# Locomotive

An electric locomotive and the train behind it, placed by the track rather than steered along it. Bend the track and each bogie takes the tangent under its own pivot, each body becomes the chord between two of them, and the sideways throw of the middle and the ends follows.

> For the complete index, see [llms.txt](https://robocn.dev/llms.txt). A Markdown version of any page is available by appending `.md` to its URL or by sending an `Accept: text/markdown` header.

## Install

```bash
bunx --bun shadcn@latest add https://robocn.dev/r/rail-locomotive.json
```

Registry item: `rail-locomotive` · [`https://robocn.dev/r/rail-locomotive.json`](https://robocn.dev/r/rail-locomotive.json)

## Notes

- Solved: the placement, from `bogieRide()`. Each bogie pivot is on the track and the body is the straight line between two of them, so the centre throw `R(1 − cos θ)` inward and the end throw outward are geometry rather than artwork — and both go to zero on straight track without a special case.
- The pantograph is the same linkage `pantograph-collector` ships standalone, and the bogies are the ones `rail-bogie` draws on its own.
- Illustrated: the track a `line` behaviour runs through is a stated shape, and there is no cant, no transition spiral, no traction and no braking. The train does not travel — the curve is a steady state, so straightening the track straightens the train with nothing to unwind.

## Usage

```tsx
import { RailLocomotive } from "@/components/ui/rail-locomotive"

<RailLocomotive behavior="line" cars={1} />

// Plan is where the curve reads: the whole train bends along it.
<RailLocomotive view="plan" curve={9} cars={2} />
<RailLocomotive behavior="depot" showThrow />
```

## Props

| name | type | default | description |
| --- | --- | --- | --- |
| `view` | `"plan" | "front" | "profile" | "iso"` | `"profile"` | Where the camera stands. One train, four projections: straight down, straight on, side elevation, or three-quarter from above. |
| `curve` | `number` | — | Degrees the track turns through under one bogie-centre spacing, positive to starboard, clamped to ±10. Omit it and the behaviour runs the road. |
| `onCurveChange` | `(curve: number) => void` | — | The track being asked for, while a person is bending it. |
| `behavior` | `"line" | "yard" | "depot" | "static"` | `"line"` | Winding through curves both ways, a crossover held hard over each way, or standing in the depot working its pantograph. |
| `cars` | `number` | `1` | Trailing vehicles behind the locomotive, 0–4. Every one of them is placed on the curve at its own arc position. |
| `pantograph` | `"auto" | "raised" | "stowed"` | `"auto"` | The roof collector. Auto leaves it to the behaviour, which is the only thing that ever lowers it. |
| `speed` | `number` | `0.22` | Track cycles per second. |
| `animate` | `boolean` | `true` | Off parks the machine at phase and stops rendering. A reduced-motion preference does the same. |
| `paused` | `boolean` | `false` | Freeze where it stands. |
| `phase` | `number` | `0` | Seconds of offset, so a row of machines breaks step. |
| `interactive` | `boolean` | `false` | Press and drag across the train to bend the track under it; arrow keys 1° at a time, Home straightens it. |
| `showTrack` | `boolean` | `true` | The rails it is standing on, which curve with it. |
| `showThrow` | `boolean` | — | Call out the solved centre and end throw as dimension lines. Blueprint does by default. |
| `active` | `boolean` | — | Light the headlight. Omit and it lights under power. |
| `label` | `string` | — | Caption underneath the train. |
| `variant` | `"solid" | "outline" | "blueprint" | "wire"` | `"solid"` | How the machine is painted. Geometry never changes between variants. |
| `size` | `"xs" | "sm" | "md" | "lg" | "xl" | number` | `"md"` | Rendered width in pixels, or a step on the scale. |
| `color` | `string` | `var(--robot-shell)` | Body panels — the colour the machine reads as. |
| `accent` | `string` | `var(--robot-accent)` | Status colour: tip light, live tool, readouts. |
| `metal` | `string` | `var(--robot-metal)` | Bare machined parts: collars, bolts, tool bodies. |
| `dark` | `string` | `var(--robot-dark)` | Cast joints, base, shadow side. |
| `palette` | `Partial<RobotPalette>` | — | Override any subset of roles at once, including glow and grid. |

## Source

- `src/components/ui/rail-locomotive.tsx`