> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/main-components/manimal-controller/states/rail-grind.md).

# Rail Grind

## Rail Grind

### Overview

The Rail Grind State lets a character lock onto a spline **rail** and grind along it — think grinding a rail on a skateboard, sliding down a zipline, or riding a rollercoaster track. The character is snapped and oriented to the rail every frame while momentum, slope acceleration and automatic leaning are handled for you.

Unlike ray-based states (Ledge Grab, Climb), Rail Grind is driven entirely by the existing **MPath + MPathConstraint** system: the rail's `MPath` forces the state on entry, and the `MPathConstraint` on the character keeps it glued to the spline.

> Insert Image here of a character grinding along a curved rail spline

### Creating the Rail Grind State

Create a new Rail Grind State using the Plus **\[+]** button on the States list (**Ground ▸ Rail Grind**), or duplicate an existing Rail Grind State asset from another character and add it to the States List.

> Insert Image here of the Add State menu showing Ground ▸ Rail Grind

### Priority

This state needs higher priority than Idle, Locomotion, and Fall, but lower or equal to **Jump** (so the character can jump off a rail). While active, all lower-priority states are ignored until an exit condition is met.

### Requirements

Rail Grind has two hard requirements:

1. **MPathConstraint component** on the character. This is what snaps and orients the character to the spline. If it is missing, the state logs a warning and will never activate.
2. **A Rail** — an `MPath` on your spline, configured as:
   * **Automatic = true**
   * **Activate State = Rail Grind** (the same StateID asset used by this state)

When the character enters that path's search bounds, the `MPath` forces the Rail Grind State on, and the constraint takes over the snapping.

> Insert Image here of the MPathConstraint component on the character
>
> Insert Image here of an MPath on a spline with Automatic enabled and Activate State set to Rail Grind

### Activation

**Automatically by a Rail:** The normal way to enter. The rail's `MPath` (Automatic + Activate State = Rail Grind) forces the state as soon as the character reaches it and the constraint enters the path.

**Re-entry after a Jump:** If the character jumps off mid-rail and is falling back down toward a rail, the state searches the registered rails within their Search Radius and re-enters the closest one automatically. This handles the case where the standard path auto-search would be blocked by the exit cooldown.

> Insert Image here of a character jumping off a rail and dropping back onto it

### Exit Conditions

The state exits when:

* **The rail ends** — the constraint leaves the path on its own → the character exits to **Fall**. (Closed/looping rails never end.)
* **A path event** kicks the character out of the path → exit to **Fall**.
* **Jump (Higher State)** is triggered — Jump has or equal higher priority, and the rail's MPath **Ignore States** releases the constraint so the character launches off the rail.

Momentum is preserved automatically on exit: the Speed Set portion is carried by the character's **Inertia**, and the accumulated **Slope Boost** is added back into the inertia so the character keeps its downhill speed into the next state.

### General Settings

**Enter Input:** None — entry is forced by the rail's MPath, not by a player input.

**General Properties:**

| Property            | Value |
| ------------------- | ----- |
| Root Motion         | False |
| Grounded            | False |
| Sprint              | True  |
| Gravity             | False |
| Custom Rotation     | True  |
| Orient To Ground    | False |
| Ignore Lower States | True  |
| Additive Position   | True  |
| Additive Rotation   | False |
| Free Move           | False |
| Persistent          | False |

Rotation and orientation are owned by the `MPathConstraint` (Lock Rotation + Use Path Rotation), which is why Custom Rotation is on and Orient To Ground is off. **Sprint** is left True so the controller's Sprint logic can switch to the Sprint Speed Modifier while grinding.

### Animator

Rail Grind uses the standard Speed Set pipeline, so the animations blend through the normal locomotion parameters:

* **\[Vertical]** blends the grind animations (Stand / Fast / Sprint) from the Vertical values of the Speed Set.
* **\[Horizontal]** drives the lean — it receives the player's horizontal input **plus** an automatic lean generated from the spline's curvature.
* The Speed Modifier **\[Position]** value moves the character along the spline.

Add a grind animation (or blend tree) and tag the core animation with the state name so the state can detect when it is in the Core Animation (slope physics only apply during the Core Animation).

> Insert Image here of the Animator with the Rail Grind core animation / blend tree

### Speed Set

Rail Grind moves the character using a dedicated **Speed Set**. Two speed levels are used while grinding:

* **Stand Speed Index** — used when no Forward input is pressed.
* **Fast Speed Index** — used while Forward is held.
* **Sprint** — handled by the controller's Sprint logic (the Sprint Index on the Speed Set).

Increase the Speed Set **Position** value if the character glides along the rail too slowly, and the **Vertical** values to change which grind animation each level plays.

### Rail Grind Parameters

#### Rail Grind Speeds

| Property              | Default | Description                                                                                                                                 |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stand Speed Index** | 1       | Speed Index used while grinding with **no** Forward input (e.g. `[1 - Stand]`).                                                             |
| **Fast Speed Index**  | 2       | Speed Index used while the Forward input is pressed (e.g. `[2 - Fast]`). Sprint speed is handled separately by the controller Sprint logic. |
| **Max Speed**         | 18      | Maximum total speed along the rail (Speed Modifier Position + Slope Boost combined).                                                        |

#### Slope

The rail's slope adds or removes speed on top of the current Speed Modifier Position, using the projection of gravity onto the rail's travel direction.

| Property                  | Default | Description                                                                                                                                                               |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Downhill Acceleration** | 9.8     | Acceleration gained on **downhill** sections, added on top of the current Speed Modifier Position. Multiplied by the projection of gravity on the rail tangent.           |
| **Uphill Deceleration**   | 9.8     | Deceleration applied on **uphill** sections (slows the character below the current Speed Modifier Position). Multiplied by the projection of gravity on the rail tangent. |
| **Slope Friction**        | 1       | Decay rate of the accumulated slope boost (rail friction). On flat rails, the speed returns to the Speed Modifier value.                                                  |

> Insert Image here of a rail with a downhill dip showing the character speeding up

#### Lean (Horizontal)

The state samples the spline a little ahead of the character and produces an automatic lean from the curvature, which is added to the player's horizontal input.

| Property             | Default | Description                                                                                                                                                                                    |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Curve Look Ahead** | 0.05    | How far ahead on the spline (normalized 0–1) to sample the curvature for the automatic lean.                                                                                                   |
| **Curve Lean Angle** | 30      | The curvature angle (in degrees) between the current and look-ahead tangent that produces a **full** lean (Horizontal = ±1). Final Horizontal = User Input + Curvature Lean, clamped to −1..1. |

> Insert Image here of a character leaning into a curved section of rail

#### Misc

| Property             | Default | Description                                                                                                                                     |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use Camera Input** | False   | When enabled, the animal switches to Camera Input while grinding (so Forward means "along the rail"). The original setting is restored on exit. |

***

### How It Works (Summary)

1. The rail's **MPath** (Automatic + Activate State = Rail Grind) forces the state when the character reaches it.
2. On **Activate**, the state figures out the travel direction from the character's facing at entry, and starts on the Stand grind speed.
3. Each frame the **MPathConstraint** snaps and orients the character to the spline; the state re-asserts the movement axis, picks Stand/Fast speed from the Forward input, and computes the automatic curvature lean.
4. **Slope physics** accelerate the character downhill and slow it uphill, clamped to Max Speed, with friction decaying the boost back toward the base speed.
5. On **Exit** (rail ends, path event, or Jump), the slope momentum is fed into the character's Inertia so speed carries into Fall / Jump / Locomotion.