> 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/ik-system.md).

# IK System

Foot, head, and torso IK that keeps the character grounded and looking alive.

The IK System is three separate modules, each with its own inspector tab: **Foot IK** (on the Core), **Head IK**, and **Torso IK** (on the Controller).

## Foot IK — inspector reference

### Quick Setup

| Field                    | Type        | Default   | What it does                                                         |
| ------------------------ | ----------- | --------- | -------------------------------------------------------------------- |
| **Collision Layer Mask** | LayerMask   | `Default` | Layers treated as ground. **Exclude the character's own colliders.** |
| **Foot Height**          | float       | `0.1`     | Distance from the ankle IK point to the sole.                        |
| **Foot Length**          | float       | `0.24`    | Foot cast length, heel to toe.                                       |
| **Foot Width**           | float       | `0.085`   | Foot cast width.                                                     |
| **Foot Weight**          | float `0-1` | `1`       | Master foot IK weight (0 off, 1 full).                               |
| **Body Weight**          | float `0-1` | `1`       | Master pelvis-adjust weight.                                         |

### Foot Placement

| Field                        | Type  | Default | What it does                                                                                             |
| ---------------------------- | ----- | ------- | -------------------------------------------------------------------------------------------------------- |
| **Foot Position Strength**   | float | —       | How snappily foot positions track (higher = stiffer).                                                    |
| **Foot Rotation Strength**   | float | —       | How snappily foot rotations track.                                                                       |
| **Max Foot Correction**      | float | `0.5`   | Max upward correction a foot can make (m).                                                               |
| **Max Foot Rotation Offset** | float | —       | Max ankle tilt toward the ground normal (deg).                                                           |
| **Show Advanced Foot**       | bool  | `false` | Reveals expert foot-tuning knobs (interpolation, extrapolation, glue thresholds, knee-hint strategy, …). |

### Body Placement

| Field                      | Type  | Default | What it does                                                  |
| -------------------------- | ----- | ------- | ------------------------------------------------------------- |
| **Body Position Strength** | float | —       | How snappily the pelvis tracks its target (higher = stiffer). |
| **Max Body Correction**    | float | `0.7`   | Max pelvis correction distance (m).                           |
| **Body Position Offset**   | float | `0`     | Extra up-axis offset to the body COM (for crouch juice).      |
| **Show Advanced Body**     | bool  | `false` | Reveals expert body-tuning knobs.                             |

### Grounded Check

| Field                         | Type  | Default | What it does                                                      |
| ----------------------------- | ----- | ------- | ----------------------------------------------------------------- |
| **Grounded Check Distance**   | float | `0.7`   | Downward ground-probe distance.                                   |
| **Global Character Y Offset** | float | `0`     | Nudges the whole character up/down (fixes hovering/sinking rigs). |

{% hint style="info" %}
There are also **Crouch Behaviour**, **Slope Spine Leaning**, **Move Leaning (Juice)**, and **Footstep Events** cards for extra flavour, plus a read-only **Debug** card. Start with the fields above — the rest is fine-tuning.
{% endhint %}

## Head IK — inspector reference

| Field              | Type      | Default | What it does                                          |
| ------------------ | --------- | ------- | ----------------------------------------------------- |
| **Enable Head Ik** | bool      | `true`  | Master toggle for head/eye look.                      |
| **Look Target**    | Transform | —       | High-priority explicit target; overrides camera look. |
| **Look Distance**  | float     | `10`    | How far ahead the camera-based look point sits.       |
| **Max Yaw**        | float     | `45`    | Max horizontal head turn (deg).                       |
| **Max Pitch**      | float     | `15`    | Max vertical head tilt (deg).                         |
| **Body Weight**    | float     | `0.2`   | How much the chest joins the look.                    |
| **Head Weight**    | float     | `1`     | Head contribution.                                    |
| **Eyes Weight**    | float     | `1`     | Eye contribution.                                     |
| **Clamp Weight**   | float     | `0.6`   | How hard the clamp limits are enforced.               |
| **Smooth Speed**   | float     | `2`     | Look smoothing.                                       |

## Torso IK — inspector reference

| Field                         | Type  | Default | What it does                                           |
| ----------------------------- | ----- | ------- | ------------------------------------------------------ |
| **Look Weight**               | float | `1.0`   | Overall torso look strength.                           |
| **Body Weight**               | float | `0.3`   | How far the spine bends toward the target (0.3 = 30%). |
| **Head Weight**               | float | `1.0`   | How far the head turns toward the target.              |
| **Clamp Weight**              | float | `0.5`   | Limits how far the neck twists.                        |
| **Smooth Time**               | float | `5`     | Torso look smoothing.                                  |
| **Disable Torso IK In Prone** | bool  | —       | Turns torso IK off while prone.                        |

***

Inverse Kinematics is what stops a character from looking like it's floating over the terrain or staring blankly through walls. Rigonix ships three IK modules, driven from `OnAnimatorIK`.

### Foot IK

Lives on the Core. Each frame it raycasts under both feet, then adjusts foot position, foot rotation, and the whole body's height so the character plants convincingly on slopes and steps instead of clipping or hovering.

Key tuning fields: `bodyWeight`, `maxFootCorrection`, `maxBodyCorrection`, `bodyPositionOffset`, `groundedCheckDistance`, and `globalCharacterYOffset`. Helpers let you drive it at runtime:

```csharp
core.ik.IsGrounded();
core.ik.SetFootWeight(1f);
core.ik.SetBodyWeight(1f);
core.ik.SetCrouching(true);      // tighter correction while crouched
core.ik.ResetTuningToDefaults();
```

{% hint style="info" %}
If feet jitter on flat ground, your `groundedCheckDistance` is probably reaching past the floor onto small props. Shorten it, or set the foot IK collision mask to your ground layer only.
{% endhint %}

### Head IK

A player-driven module (on the Controller) that turns the head and eyes toward a look target, clamped so the neck never snaps unnaturally. Tune with `lookDistance`, `maxYaw`, `maxPitch`, and per-part weights (`headWeight`, `eyesWeight`, `bodyWeight`, `clampWeight`), smoothed by `smoothSpeed`.

```csharp
core.headIK... // via the controller
controller.headIK.SetLookTarget(enemy.transform);
controller.headIK.ClearLookTarget();
```

### Torso IK

Bends the upper body toward the aim/look direction, layering on top of head IK so aiming reads through the whole spine rather than just the neck. It runs alongside head IK in the same `OnAnimatorIK` pass.


---

# 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/ik-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.