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

# Locomotion Module

Walk, run, sprint, crouch, prone, aim, strafe, and climb stairs.

## Inspector reference

### Movement Style

| Field              | Type | Default | What it does                                                                                             |
| ------------------ | ---- | ------- | -------------------------------------------------------------------------------------------------------- |
| **Movement Style** | enum | `Free`  | `Free` turns the body toward its move direction; `Strafe` keeps it facing the aim/camera and side-steps. |

### Movement Settings

| Field                       | Type  | Default | What it does                                                               |
| --------------------------- | ----- | ------- | -------------------------------------------------------------------------- |
| **Walk Speed**              | float | `3.0`   | Base walking speed (m/s).                                                  |
| **Run Speed**               | float | `5.0`   | Jogging speed with no sprint modifier.                                     |
| **Sprint Speed**            | float | `12.0`  | Top speed while sprinting.                                                 |
| **Walk By Default**         | bool  | `false` | If on, the character walks unless told to run; if off, it jogs by default. |
| **Smooth Rotation Time**    | float | `0.15`  | How long turning takes to settle — higher is smoother/slower.              |
| **Aim Only With Equipment** | bool  | `true`  | Only allow aiming when an item is equipped.                                |
| **Can Sprint While Aiming** | bool  | `false` | Whether sprinting is permitted during aim.                                 |
| **Is Strafe Locomotion**    | bool  | `false` | Runtime toggle for strafe movement (also set by area triggers).            |

### Stance Settings

| Field                           | Type  | Default | What it does                                                              |
| ------------------------------- | ----- | ------- | ------------------------------------------------------------------------- |
| **Crouch Walk Speed**           | float | `2.0`   | Move speed while crouched.                                                |
| **Prone Walk Speed**            | float | `1.5`   | Forward speed while prone.                                                |
| **Prone Strafe Sideways Speed** | float | `0.5`   | Sideways speed while prone.                                               |
| **Stand Height**                | float | `1.795` | Capsule collider height when standing.                                    |
| **Stand Center**                | float | `0.907` | Capsule collider center when standing.                                    |
| **Prone Z Axis Offset**         | float | `0.68`  | Lowers the collider center when prone — raise it if the character floats. |
| **Stance Change Speed**         | float | `100`   | How fast the collider resizes between stances.                            |
| **Default Z Axis Offset**       | float | `0.2`   | Collider center offset in the default (standing) stance.                  |

### Stair & Step Handling

| Field                       | Type      | Default | What it does                                                  |
| --------------------------- | --------- | ------- | ------------------------------------------------------------- |
| **Enable Stairs Handling**  | bool      | `true`  | Master toggle for stair/step logic.                           |
| **Enable Step Offset**      | bool      | `true`  | Lets the character step up onto ledges.                       |
| **Max Step Height**         | float     | `0.35`  | Tallest ledge (m) the character can step onto.                |
| **Step Detection Distance** | float     | `0.4`   | How far ahead to probe for steps.                             |
| **Step Layer Mask**         | LayerMask | —       | Layers treated as steppable ground (set to Default + Ground). |

### Flags

| Field                       | Type | What it does                                            |
| --------------------------- | ---- | ------------------------------------------------------- |
| **Lock Locomotion**         | bool | Disables all locomotion.                                |
| **Lock Movement**           | bool | Freezes translation but not rotation.                   |
| **Lock Rotation**           | bool | Freezes turning but not movement.                       |
| **Lock Sprint**             | bool | Prevents sprinting.                                     |
| **Rotate With Camera**      | bool | Forces the body to follow the camera yaw.               |
| **Turn In Place Animation** | bool | Enables turn-in-place blends when idle.                 |
| **Is Root Motion**          | bool | Hands velocity to the animation clips instead of code.  |
| **Current Stance**          | enum | The master stance state (`Stand` / `Crouch` / `Prone`). |

{% hint style="info" %}
`Is Advanced Collision Handling`, `Is Scripted Movement`, and `Is Sprinting` also appear as **read-only** readouts so you can watch state in play mode.
{% endhint %}

***

The **Locomotion module** is the heart of the controller. It turns movement intent into actual motion, manages stance, handles rotation, drives the animator's blend values, and even climbs stairs. It lives on the Core, so players and AI move through the identical code path.

### Speeds and styles

Three base speeds — `walkSpeed`, `runSpeed`, `sprintSpeed` — with crouched and prone variants (`crouchWalkSpeed`, `proneWalkSpeed`). `walkByDefault` flips whether the character strolls or jogs without a sprint modifier.

Movement comes in two styles, toggled by `isStrafeLocomotion`:

* **Free** — the character turns to face its movement direction. Classic third-person adventuring.
* **Strafe** — the character keeps facing the camera/aim direction and side-steps. This is what you want while aiming.

### Stances

The `currentStance` field is the master state — `Stand`, `Crouch`, or `Prone` — and you change it through one method so height, camera, and animation all stay in sync:

```csharp
core.locomotion.ChangeStance(LocomotionModule.Stance.Crouch);
```

Stance changes smoothly resize the capsule collider between `standHeight`/`standCenter` and the crouch/prone equivalents at `stanceChangeSpeed`, and fire the `OnStanceChanged` event that the controller uses to re-frame the camera.

### Events the driver listens to

Locomotion doesn't know about cameras — it just announces what changed, and the driver reacts:

```csharp
locomotion.OnStanceChanged += HandleStanceChanged;  // -> camera crouch/prone framing
locomotion.OnAimingChanged += HandleAimingChanged;  // -> camera aim framing
locomotion.OnSprintChanged += HandleSprintChanged;  // -> camera sprint pull-back
```

This is the clean seam that lets the same locomotion drive a camera-less AI — nobody's subscribed on that end, and nothing breaks.

### Stair and step handling

With `enableStairsHandling` and `enableStepOffset` on, the character detects and steps up ledges up to `maxStepHeight`, probing `stepDetectionDistance` ahead. This keeps movement smooth over stairs and curbs without a NavMesh or manual ramp colliders.

### Root motion vs scripted motion

`isRootMotion` hands velocity to the animation clips; `attackRootMotion` lets an attack temporarily drive motion (used by the melee add-on through the same seam). `isScriptedMovement` and the `MovePlayerTo(...)` helper let you drive the character along a path for cutscenes.

### Handy locomotion helpers

```csharp
locomotion.LockPlayerMovement();                 // freeze translation
locomotion.LockPlayerRotation();                 // freeze turning
locomotion.SetPlayerLocomotion(false);           // disable all movement
locomotion.RemoveVelocity();                     // kill momentum instantly
locomotion.ResetSpeed();                          // back to defaults
locomotion.SetisStrafeLocomotion(true);          // switch to strafe style
locomotion.MovePlayerTo(target, ...);            // scripted move
```

The lock flags (`lockLocomotion`, `lockMovement`, `lockRotation`, `lockSprint`) are also directly settable when you need finer control — for example, locking rotation but not movement during an interaction.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rigonix3d.gitbook.io/rigonix3d-docs/documentation/the-modules/images-and-media.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.