# Import Animation

Import FBX or NPZ body animation and retarget it onto the FK controls of a MetaHuman control rig.

Canonical URL: https://docs.polyhammer.com/blender-addons/character-control-rig/0.5.2/import-animation
Product: character-control-rig
Version: 0.5.2
Channel: production
Updated: 2026-11-21T13:45:20Z
Documentation source: initial main snapshot approved 2026-11-21T13:45:20Z
Documentation commit: 3da85b494e9468a17cd765231fcd260aa6bdfae0
Release tag commit: bd557d6d7d6222effd11e3740111c2debb284802
Owner-approved migration baseline: use current main documentation for the current stable release once; all subsequent releases use their tag snapshots.

Import a body animation from an FBX or NPZ file and retarget it onto the FK controls of
your control rig. The source skeleton is detected automatically, and the result is a
regular Blender Action you can keyframe over.

[Video: fk animation import](https://docs.polyhammer.com/docs-assets/character-control-rig/3cafbb21566b05a6ab34359058f80bd795d78748abecf2773631524fedabcae3/images/import-animation/fk-animation-import.webm)

## Import a Body Animation [#import-a-body-animation]

1. Select the rig instance and make sure its control rig has been generated.
2. Open the **Animation** panel.
3. Under **Body FK Animation**, click **Import**.
4. Choose an `.fbx` or `.npz` file.
5. Confirm. The file becomes a new source animation with its own retarget settings, and the animation lands on the
   control rig's FK controls as its own Action.

Select the control rig and enter Pose Mode to play it back.

Each source animation keeps its own retarget settings: turning IK off for one clip never changes another, and a new
import starts from the preset chosen in the import dialog. Importing the same file again, or **Duplicate** in the
source list, gives a second source animation, so one clip can be tried with different settings side by side. To use
one clip's settings on others, choose **Copy Settings To** next to the settings' preset menu; to reuse them later, save
them as a preset.

## Import Options [#import-options]

| Option                     | Default          | Effect                                                                                                                                        |
| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Settings**               | Default Humanoid | The preset the new source animation's retarget settings start from.                                                                           |
| **Source Skeleton**        | Auto Detect      | Forces a source skeleton template instead of detecting it.                                                                                    |
| **Source Convention**      | Auto Detect      | Reads the file as a plain skeleton, or as a control-rig export, instead of detecting it.                                                      |
| **Source Frame Rate**      | `30`             | Rate assumed for formats that don't declare one, such as NPZ. Ignored when the file does.                                                     |
| **Match Frame Rate**       | On               | Re-times the source samples onto the current scene frame rate, FPS divided by Base.                                                           |
| **Round Sub-frames**       | On               | Rounds re-timed samples to whole scene frames.                                                                                                |
| **Merge Colliding Frames** | Off              | Keys a frame that several re-timed samples land on once, with the last sample, as the source preview shows it, instead of duplicate keys.     |
| **Rotation Resampling**    | Linear           | How an FBX file's rotations are sampled between keys: Linear, as before, or Spherical, along the shortest arc. NPZ files are never resampled. |
| **Prefix Instance Name**   | On               | Prefixes the Action name with the rig instance name, avoiding collisions between characters.                                                  |
| **Prefix Component Name**  | Off              | Prefixes the Action name with `body`.                                                                                                         |

<Callout type="info" title="Note">
Each Action remembers what it was built from: the control rig, the settings and the source options. When one of
them changes (say the control rig was removed and generated again with another rig framework), the Retargeting
panel says why the Action is out of date, and **Run Retarget** or **Retarget All Stale** builds it again from the
source file. Keys edited by hand are never overwritten without asking; **Keep Edited Copy** keeps them in a copy.
</Callout>

Every option but the two prefixes stays with the source animation and can be changed later in the **Source** box of the
**Retargeting** panel; **Run Retarget** then builds the animation again with it. An Action never replaces another: a
name already taken gets a numbered suffix.

<Callout type="info" title="Note">
The scene frame rate includes its **Base**, so an NTSC scene (29.97, 59.94 or 23.976 fps, Base 1.001) imports a
clip of the same NTSC rate one sample per frame. Earlier versions re-timed such clips to the whole-number rate
(30, 60 or 24 fps), which drifted by about one frame in a thousand; re-running a source imported earlier in an NTSC
scene re-times it to the scene's rate. Scenes whose Base is 1 import exactly as before.
</Callout>

<Callout type="info" title="Note">
The source's first sample always lands on frame 1, and a re-timed clip's later samples follow at the scene rate.
Earlier versions keyed a re-timed clip a fraction of a frame off (0.2 frame early for a 30 fps clip in a 24 fps
scene); **Migrate Legacy Data** retargets such animations again.
</Callout>

<Callout type="idea" title="Tip">
**Merge Colliding Frames** matters when the scene rate is lower than the clip's, such as a 30 fps clip in a 24 fps
scene with **Round Sub-frames** on: several samples then land on one frame. Without it the Action keeps one key per
sample there, and Blender plays one of them; with it the frame holds the last sample, as the source preview shows.
</Callout>

## Supported Animation Templates [#supported-animation-templates]

The source skeleton in your file is matched against these templates automatically:

| Template                         | Typical source                              |
| -------------------------------- | ------------------------------------------- |
| **MetaHuman**                    | MetaHuman body animation from Unreal Engine |
| **UE5 Mannequin (Manny/Quinn)**  | Unreal Engine 5 Manny and Quinn             |
| **UE4 Mannequin**                | Unreal Engine 4 mannequin                   |
| **Mixamo**                       | Adobe Mixamo clips                          |
| **Reallusion Character Creator** | Character Creator and AccuRig               |
| **Rokoko**                       | Rokoko Studio suit capture                  |
| **Xsens**                        | Xsens suit capture                          |
| **SOMA**                         | Generated motion from Kimodo on SOMA rig    |

<Callout type="info" title="Note">
The addon has its own source skeleton detection algorithm that will choose the right retargeting steps for you if the animation you are importing is supported.
</Callout>

<Callout type="idea" title="Tip">
You can export from the processed full body performance by right-clicking `MetaHuman_ControlRig_Simple` to export the body track with **Export Control Rig FBX** instead of baking an animation sequence.
</Callout>

## Face Board Animation [#face-board-animation]

The **Face Board** section of the same panel has its own **Import** button. You can import your Face Board animations the you exported from MetaHuman Animator in a single click.

[Video: metahuman animator face board support](https://docs.polyhammer.com/docs-assets/character-control-rig/3cafbb21566b05a6ab34359058f80bd795d78748abecf2773631524fedabcae3/images/import-animation/metahuman_animator_face_board_support.webm)

<Callout type="idea" title="Tip">
Check out [this video](https://youtu.be/j59ftPt7MUY?si=fyU8Z9BMiQ3MqU-X&t=269) on how to do this.
</Callout>
