> 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/systems-in-depth/footstep-system.md).

# Footstep System

Surface-aware footstep audio and visuals, driven by animation events.

## Footstep module — inspector reference

### Detection Settings

| Field                             | Type          | Default    | What it does                              |
| --------------------------------- | ------------- | ---------- | ----------------------------------------- |
| **Ground Layers**                 | LayerMask     | Everything | Layers the footstep ray can hit.          |
| **Ray Distance**                  | float         | `1.3`      | How far down the surface ray reaches.     |
| **Min Speed**                     | float         | `0.5`      | Minimum move speed before footsteps play. |
| **Enable Crouch Quiet Footsteps** | bool          | `true`     | Quieter footsteps while crouched.         |
| **Crouch Volume Multiplier**      | float `0-0.8` | `0.35`     | Volume scale while crouched (0.35 = 35%). |

### Foot Sensor Settings

| Field                        | Type             | Default | What it does                                                   |
| ---------------------------- | ---------------- | ------- | -------------------------------------------------------------- |
| **Sensor Radius**            | float `0.05-1.0` | `0.2`   | Radius of each foot sensor collider.                           |
| **Right Foot Sensor Offset** | Vector3          | `0,0,0` | Position offset of the right sensor relative to the foot bone. |
| **Left Foot Sensor Offset**  | Vector3          | `0,0,0` | Position offset of the left sensor.                            |

### Surface Database

| Field                | Type                         | What it does                                   |
| -------------------- | ---------------------------- | ---------------------------------------------- |
| **Surfaces**         | List\<RigonixSurfaceProfile> | Your surface profiles, matched by texture/tag. |
| **Fallback Surface** | RigonixSurfaceProfile        | Played when no specific surface matches.       |

### Surface Profile asset fields

Each **RigonixSurfaceProfile** (Create → Rigonix → Surface Profile) exposes:

| Field               | Type             | What it does                                            |
| ------------------- | ---------------- | ------------------------------------------------------- |
| **Texture Names**   | List\<string>    | Terrain/material texture names that match this surface. |
| **Tags**            | List\<string>    | Tags that match this surface.                           |
| **Step Sounds**     | List\<AudioClip> | Footstep clips (random pick).                           |
| **Jump Sounds**     | List\<AudioClip> | Jump clips for this surface.                            |
| **Land Sounds**     | List\<AudioClip> | Landing clips for this surface.                         |
| **Volume**          | float `0.1-3`    | Playback volume.                                        |
| **Particle Prefab** | GameObject       | Spawned at the step point (dust, splash).               |
| **Decal Prefab**    | GameObject       | Footprint decal.                                        |
| **Decal Lifetime**  | float            | How long the decal lives.                               |

***

The Footstep system makes the character sound (and look) right for whatever it's walking on — stone rings, grass rustles, puddles splash — by detecting the surface under each foot and playing the matching audio, particles, and decals.

### The two moving parts

**Foot sensors** — small trigger components (`RigonixFootSensor`) placed under each foot bone. They carry a `footIndex` (0 = left, 1 = right) and cooldowns tuned per gait (`cooldownForSprinting`, `cooldownForCrouching`) so one footfall never double-fires. The Footstep module can place these for you:

```csharp
controller.footsteps.SetupFootSensors();
controller.footsteps.RemoveFootSensors();
```

**Surface profiles** — `RigonixSurfaceProfile` ScriptableObjects that bundle everything a surface sounds and looks like: step/jump/land clip lists, a volume, and optional particle and decal prefabs with a decal lifetime. You match a profile to the world by texture name and/or tag.

### How a footstep resolves

Footsteps fire from **animation events** on your walk/run clips — add an event that calls `TriggerFootstep(0)` on the left-foot contact frame and `TriggerFootstep(1)` on the right. From there:

```mermaid
flowchart TD
    A[Animation event: TriggerFootstep] --> B{Fast enough? Not prone?}
    B -->|no| Z[skip]
    B -->|yes| C[Raycast down from foot]
    C --> D[DetectSurface]
    D -->|terrain| E[Dominant splatmap texture]
    D -->|mesh| F[Material / texture name]
    E --> G[Match a SurfaceProfile]
    F --> G
    G --> H[Play audio + spawn particles/decal]
    G -->|no match| I[fallbackSurface]
```

The detector is smart about where it looks: on Unity **Terrain** it reads the dominant splatmap texture at the hit point; on regular meshes it matches the material or texture name. Anything unmatched falls back to `fallbackSurface`, so you never get silence.

### Setting it up

{% stepper %}
{% step %}

#### Create surface profiles

Right-click → Create → Rigonix → Surface Profile for each material (stone, grass, wood, water). Fill in the texture/tag names, step clips, and any particle/decal prefabs.
{% endstep %}

{% step %}

#### Register them

Add your profiles to the **Surface Database** list on the Footsteps tab, and set a `fallbackSurface`.
{% endstep %}

{% step %}

#### Place foot sensors

Click to run `SetupFootSensors()` (or let the Character Creator do it). Adjust `leftFootSensorOffset` / `rightFootSensorOffset` if the sensors don't sit under the soles.
{% endstep %}

{% step %}

#### Add animation events

On your locomotion clips, add events calling `TriggerFootstep(0)` and `TriggerFootstep(1)` at foot contact.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Crouched footsteps are automatically quieter (`crouchVolumeMultiplier`) when `enableCrouchQuietFootsteps` is on, and footsteps are suppressed entirely while prone — sneaking actually sounds like sneaking.
{% endhint %}


---

# 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/systems-in-depth/footstep-system.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.