# IK & retargeting

> Plant feet, put hands on weapon grips, aim heads, share one clip library across rigs, and play root motion and montages.

Source: https://feather-engine.com/docs/animation/ik-and-retargeting/

Animation graphs can carry more than a state machine. Each graph can add foot IK, hand IK, look-at,
root motion and montages, applied after the graph has posed the character each frame. Humanoid rig
maps let one clip library drive characters whose skeletons use different bone names.

All of these settings live in **Window → Animation graphs**, below the state machine of the selected
graph. Read [Animation graphs](/docs/animation/animation-graphs/) first.

![The Animation graphs panel with Quick setup and the Hand IK section](../../../../assets/docs/animation/animation-editor-ik.jpg)

## Quick setup

The **Quick setup** row adds a working starting point to the selected graph:

| Button | Adds |
| --- | --- |
| **Rifle hands** | Hand IK with the support hand on the weapon's fore grip |
| **Look at** | Look-at: the spine, neck and head follow the camera aim (avatar) or the player (other characters) |
| **Foot IK** | Foot IK with humanoid leg bones |
| **Reload montage** | An upper-body `reload` montage that releases the support hand, with `mag_out` and `mag_in` notifies |

Click **Apply** to keep the result. Turn on **IK gizmos** to draw IK chains, grip targets, elbow poles
and look targets in the viewport during Play.

## Humanoid bone names

IK, montage masks and retargeting refer to bones by canonical humanoid names, the naming used by the
VRM format: `hips`, `spine`, `chest`, `upperChest`, `neck`, `head`, and `left`/`right` + `Shoulder`,
`UpperArm`, `LowerArm`, `Hand`, `UpperLeg`, `LowerLeg`, `Foot` and `Toes`. Finger joints follow the same
pattern, such as `leftIndexProximal`. Each model's rig map resolves these names to its own bones, so the
same graph settings work across rigs.

## Foot IK

Foot IK plants both feet on the terrain. It drops the hips to the lower foot's ground and bends each leg
with a two-bone solver, so feet rest on slopes and steps.

| Setting | Description | Default | Range |
| --- | --- | --- | --- |
| **Pelvis** | The bone lowered so the lower foot reaches its ground | `hips` | — |
| **Left leg**, **Right leg** | Hip, knee and foot bones | `leftUpperLeg`, `leftLowerLeg`, `leftFoot` (and right) | — |
| **Max adjust** | Largest correction | 0.45 m | 0 to 2 m |
| **Smoothing** | How fast corrections follow the ground, per second | 12 | 0.1 to 100 |

## Hand IK

Hand IK bends two-bone arms so the support hand holds the weapon's fore grip and, optionally, the
trigger hand holds its pistol grip. Elbows bend toward pole hints. It works on the third-person avatar
and on enemies holding weapons.

Give the avatar a weapon under **World & terrain → Player → Held models (weapons)**: choose a model and the
bone it hangs from, such as `rightHand`.

![Hand IK placing the support hand on a rifle's fore grip](../../../../assets/docs/animation/animation-hand-ik-on.jpg)

| Setting | Description | Default | Range |
| --- | --- | --- | --- |
| **Weight** | Overall blend | 1 | 0 to 1 |
| **Smoothing** | How fast the weight follows releases, per second | 10 | 0.1 to 100 |
| **Left arm**, **Right arm** | Upper arm, lower arm and hand bones | Humanoid arm bones | — |

Each hand has a target: **Support hand (left) → fore grip** and **Trigger hand (right) → pistol grip**.
The trigger hand target is off by default.

| Target setting | Description |
| --- | --- |
| **Grip sockets** | Node names searched under the character, such as `grip_left` on the weapon model. The first match wins; up to 16 |
| **Else follow** | The bone used when no socket exists, such as `rightHand` |
| **Offset m** | Offset in that bone's frame, within ±5 m |
| **Rotation °** | Extra rotation, within ±360° |
| **Match grip turn** | How much the hand turns to match the grip, 0 to 1 |
| **Elbow pole** | Elbow hint from the shoulder (outward, up, forward), in metres |

Without a socket, the default support-hand target sits 25 cm up the held weapon's barrel from the
pistol grip.

## Look-at

Look-at turns the spine, neck and head toward a target, sharing the turn across a chain of bones within
angle limits.

| Setting | Description | Default | Range |
| --- | --- | --- | --- |
| **Weight** | Overall blend | 1 | 0 to 1 |
| **Looks at** | **Aim / player**: the camera aim for the avatar, the player for other characters. **Player**: the player character. **Script only**: targets from `look_at` | Aim / player | — |
| **Chain** | Bones from the hips up, each with its share of the turn | `spine` 0.15, `chest` 0.15, `upperChest` 0.1, `neck` 0.25, `head` 0.35 | 1 to 8 bones |
| **Max yaw** | Largest sideways turn | 70° | 0 to 180° |
| **Max pitch** | Largest up or down turn | 45° | 0 to 90° |
| **Behind falloff** | Angle over which the look fades for targets behind | 50° | 0 to 180° |
| **Smoothing** | Per second | 8 | 0.1 to 100 |
| **Range** | Targets further away are ignored | 25 m | 0.5 to 500 m |

## Retargeting

Every character model has a humanoid map from canonical bone names to its own bone names. The engine
detects the map from the bone names in the model's GLB and recognises these naming conventions:

| Rig kind | Example bone names |
| --- | --- |
| Synty | `Pelvis`, `UpperArm_L`, `Thigh_L` |
| Mixamo | `mixamorig:LeftArm` |
| VRM / Character Forge | `leftUpperArm` |
| Generic | `UpperArm.L` and similar |

When a model's bone names differ from those of its graph's clip library, the clips are retargeted
automatically. Retargeting corrects for different rest poses (T-pose or A-pose), facing and proportions,
including armatures exported at 0.01 scale. One clip library can drive many characters.

![A Synty character holding a rifle, animated by a Character Forge clip library](../../../../assets/docs/animation/animation-retarget-synty-forge-rifle.jpg)

### Check or fix a rig map

1. In **Retarget map · humanoid bones**, choose the character's **Model**.
2. Click **Read bones** to list its bones, or **Auto-match** to detect the map and store it in the project.
3. The header shows how many bones are mapped and lists required bones that are missing.
4. Change any mapping by hand. **Back to the detected bone** undoes one override; **Reset to detected**
   removes them all.
5. Under **Check a clip on another model**, pick a clip and a second model and click **Check** to compare
   the two poses.

Chest, upper chest, shoulders and toes are optional. Every other body bone is required.

### IK without an animation graph

Enemies and NPCs often run without a graph. Give their model hand IK or look-at directly under
**IK for this model without a graph (enemies)**, then click **Apply rig IK**. The settings have the same
shape as on a graph.

## Root motion

By default, clips play in place and the character controller moves the character. Root motion lets
selected clips move the character by the distance their root bone travels, which suits dodges, vaults,
lunges and authored walk cycles. It works with graph blending: the travel is weighted like the blend.

| Setting | Description | Default |
| --- | --- | --- |
| **Root bone** | The bone that carries the motion: a humanoid name or the rig's own root | `hips` |
| **Turn with clip** | Also turn the character by the clip's yaw | Off |
| **Tick clips that travel** | The clips that move the character; others play in place. Up to 64 | None |

Use `animation.root_motion` to measure how far and fast each clip travels before you tick it.

## Montages

A montage is a one-shot clip, such as a reload, melee swing or emote, played over the graph. It blends
in, plays on a bone mask, fires notifies and blends out at its end or when stopped. A new montage
interrupts the playing one unless that one is not interruptible.

| Setting | Description | Default | Range |
| --- | --- | --- | --- |
| **Clip** | The clip to play | — | — |
| **Mask** | **Full body**, **Upper body** (the spine and above; the legs keep the graph's locomotion), **Arms** (both arms from the shoulders) or **Custom** | Full body | — |
| **Mask roots** | For **Custom**: bones whose subtrees play the montage | None | Up to 16 |
| **Blend in**, **Blend out** | Seconds | 0.15, 0.2 | 0 to 5 s |
| **Speed** | Playback rate | 1 | 0.05 to 10 |
| **Notifies** | Points in the clip (0 to 1) that call `on_anim_event` and can play a sound | None | Up to 32 |
| Root motion | Move the character by the clip's travel | Off | — |
| Release hands | Let go of hand IK while playing, for reloads | Off | — |
| Interruptible | Whether a new montage can cut this one short | On | — |

You can also play a montage straight from a clip name without defining it on the graph.

## Script API

Pass the character's object ID, or `"player"` for the third-person avatar.

| Function | Description |
| --- | --- |
| `play_montage(id, clip)` | Plays a graph montage by ID, or a clip by name |
| `play_montage(id, clip, options)` | Overrides `mask` (`"full"`, `"upper"`, `"arms"` or `"custom"`), `blend`, `speed` and `root_motion` |
| `stop_montage(id)`, `stop_montage(id, blend)` | Stops the montage, with an optional blend-out in seconds (0 to 5) |
| `montage_playing(id)` | The playing montage, or an empty string |
| `look_at(id, target)` | Sets a look target: a `vec3`, `[x, y, z]`, `"player"`, an object handle or an object ID |
| `clear_look(id)` | Clears the script look target |
| `set_ik_weight(id, chain, weight)` | Scales `"feet"`, `"hands"` or `"look"` IK, 0 to 1 |

Montage notifies reach world scripts through the `on_anim_event(id, name)` hook.

```rust
fn on_key(key) {
    if key == "R" {
        play_montage("player", "reload", #{ mask: "upper", blend: 0.1 });
    }
}

fn on_anim_event(id, name) {
    if name == "mag_in" {
        print("Reloaded");
    }
}
```

## Automate it

| Command | Purpose |
| --- | --- |
| `animation.upsert` | Sets `foot_ik`, `hand_ik`, `look_at`, `root_motion` and `montages` on a graph |
| `animation.retarget_map_get` | A model's bones, the detected map, overrides and missing bones |
| `animation.retarget_auto` | Detects and stores a model's map; `keep_overrides` keeps hand-set bones |
| `animation.retarget_map_set` | Overrides bones (`null` removes one), sets rig IK, or removes the map |
| `animation.retarget_preview` | Samples a clip on another model and reports limb angle errors; under about 5° is a good map |
| `animation.root_motion` | Measures each clip's travel, speed and turn |

Detect a model's rig, then check a clip from another model on it:

```bash
feather-cli --connect .feather-session.json command animation.retarget_auto \
  --json '{"asset_id":12}'

feather-cli --connect .feather-session.json command animation.retarget_preview \
  --json '{"source_asset_id":7,"target_asset_id":12,"clip":"Run"}'
```

See [Agents & automation](/docs/agents/overview/) for connecting a live session.