> For the complete documentation index, see [llms.txt](https://animotive.gitbook.io/animotive-kimodo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://animotive.gitbook.io/animotive-kimodo/setup/first-character.md).

# First-Time Character Setup

Animotive Kimodo authors motion on a body skeletal mesh. The plugin recognises two character paths: a **MetaHuman**, which works without any setup, and any other skeletal mesh — Mixamo, Character Creator, Rokoko, a custom in-house rig — which is made compatible in a single pass with the **Animotive Kimodo Retarget Wizard**. This page covers both, and the day-to-day surfaces (companion tracks, retargeter pair) that follow once the character is ready.

## 1. Body-rig requirement

The plugin's authoring surfaces — the **Add Animotive Kimodo Track** entry, the toolbar export, the prompt and constraints tracks — only appear on Sequencer bindings whose skeletal mesh has a `pelvis` or `root` bone. This predicate is how Animotive Kimodo distinguishes a body rig from a face rig or an accessory rig in the same actor.

If your character is a MetaHuman, its `Body` sub-binding satisfies the predicate; its face binding does not, by design. Face animation is out of scope for Animotive Kimodo: the model generates body motion only, and the face skeleton (\~700–800 joints) is handled separately by MetaHuman's own face animation tooling.

If you right-click a binding and the **Add Animotive Kimodo Track** entry is not listed, the binding is not a body rig — confirm you are clicking the body skeletal-mesh sub-binding rather than a parent actor, a face mesh, or a prop attachment.

## 2. MetaHuman path (no setup required)

A MetaHuman is supported out of the box. There is nothing to generate, configure, or run — the body skeleton is already known to Animotive Kimodo, a matching IK Retargeter pair ships with the plugin, and the body Control Rig is already on the MetaHuman.

1. In the Content Browser, locate the MetaHuman blueprint for your character.
2. Drag the blueprint into the level.
3. Open or create a Level Sequence and dock Sequencer.
4. With the MetaHuman actor selected in the level, in Sequencer click **+ Track → Actor To Sequencer**. The MetaHuman binding is added, with sub-bindings for the body skeletal-mesh component (typically named `Body`) and the face component.
5. The `Body` sub-binding is your authoring target. Right-clicking it lists **Add Animotive Kimodo Track**.

That is the full setup. Skip ahead to [Prompting with Animotive Kimodo](/animotive-kimodo/getting-started/prompting-with-animotive-kimodo.md).

## 3. Non-MetaHuman path (Retarget Wizard, one-time per skeletal mesh)

For any other body skeletal mesh — a Mixamo rig, a Character Creator export, a custom in-house rig — the **Animotive Kimodo Retarget Wizard** generates the assets the plugin needs to move animation between Kimodo's internal SOMA skeleton and your character. Run the wizard once per skeletal mesh. The outputs are persistent assets in your project; subsequent generations on that character do not re-run the wizard.

### 3.1 What the wizard produces

The wizard writes everything it generates under a single folder, `/Game/Kimodo/Generated/<MeshName>/`:

* An **IK Rig** describing the limb, spine, and head chains on your character's skeleton.
* A **forward IK Retargeter** — Soma → Character. Used at import to map Kimodo's generated motion onto your character.
* A **reverse IK Retargeter** — Character → Soma. Used by the retarget-first export path to sample your character's pose into Kimodo's input space.
* A **Control Rig** for keyable handles, generated only if the target skeleton has no Control Rig of its own. If your character already ships a Control Rig, the wizard leaves it alone.

If auto Control Rig generation fails on a skeleton that needs one, the wizard still ships the IK Rig and both retargeters. See [3.5 The CRAutoGenSkipped warning](#35-the-crautogenskipped-warning) below.

### 3.2 Two entry points

You can open the wizard with no asset preselected, or invoke it from a specific skeletal mesh in the Content Browser:

* **Tools → Animotive Kimodo → Retarget Wizard.** Opens the wizard tab with an empty **Target SkeletalMesh:** field — pick the mesh in the wizard itself.
* **Content Browser → right-click a `SkeletalMesh` asset → Animotive Kimodo → Set up retargeter…** Opens the wizard with **Target SkeletalMesh:** pre-filled with the asset you clicked.

Both routes open the same wizard widget; they differ only in whether the target field starts populated.

### 3.3 Run procedure

1. Open the wizard via either entry point above.
2. The status line reads **"Pick a target SkeletalMesh, then click Run."**
3. Click the **Target SkeletalMesh:** picker and choose the skeletal mesh you want to set up. (If you opened the wizard from the Content Browser, this is already filled in.)
4. The status line updates to **"Target: {Name}. Ready to run."** where `{Name}` is the asset name.
5. Click **Run**. The status line changes to **"Running…"** while the wizard generates assets. Asset creation may take from a few seconds to a minute depending on skeleton size and whether a Control Rig is being auto-generated.
6. Wait for the completion notification. If you change your mind during the run, click **Cancel** — the wizard surfaces a **"Animotive Kimodo Retarget Wizard: cancelled."** notification and any partial output is discarded.

### 3.4 What success looks like

When the wizard completes, a new folder appears in the Content Browser at `/Game/Kimodo/Generated/<MeshName>/`, containing the IK Rig, the two IK Retargeters, and (when generated) the Control Rig. From this point on, any Animotive Kimodo track placed on a Sequencer binding of this skeletal mesh will resolve its retargeter pair automatically — no manual asset assignment is needed.

### 3.5 The CRAutoGenSkipped warning

Auto Control Rig generation is the most fragile step in the wizard. If it fails — typically because of unusual joint naming, atypical limb topology, or missing-skeleton-tag conditions — the wizard does **not** fail the whole run. It continues, produces the IK Rig and both retargeters, and records a non-terminal warning on the wizard's monitor entry.

The warning is **CRAutoGenSkipped**. Its friendly text reads, verbatim:

> Couldn't auto-generate a Control Rig for this skeleton. Wizard continued without one — pose this character with a hand-authored Control Rig, or re-run the wizard after fixing the underlying issue.

With this warning, the character is still partially usable: imports and retargeting work, because both retargeters exist. What does not work is the Control-Rig-based pose authoring step. Either supply a hand-authored Control Rig for the skeleton and pose using that, or skip Control-Rig-based authoring entirely and rely on the text-to-anim path (no key poses, just a prompt and duration).

## 4. Companion tracks created on the binding

Once the wizard has run on your character (or, for a MetaHuman, with no wizard step needed), the binding is ready to receive Animotive Kimodo authoring surfaces.

1. In Sequencer, right-click the body skeletal-mesh sub-binding (named `Body` for MetaHumans; whatever your character names its body component otherwise).
2. Choose **Add Animotive Kimodo Track**.

Two tracks appear on the binding, created in a single undo step:

* **Animotive Kimodo Track** — holds prompt sections and timing.
* **Kimodo Constraints** — holds six trigger channels (**Full-Body**, **2D Root**, **Left Hand**, **Right Hand**, **Left Foot**, **Right Foot**) for pinning body parts at specific frames.

The **Add Animotive Kimodo Track** menu entry disappears from the binding's context menu once a track exists — there is one Animotive Kimodo track per body binding. The Constraints track is always created alongside; it does not have a standalone "add" entry.

## 5. Retargeter pair on the track

Each Animotive Kimodo track carries two retargeter slots, exposed in the track's details panel:

* **Forward Retargeter** — Soma → Character. Applied when the BVH returned by Kimodo is imported and retargeted onto your character.
* **Reverse Retargeter** — Character → Soma. Applied by the retarget-first export path when sampling your character's posed motion into Kimodo's input space.

When the track is first added, both slots are auto-detected. The plugin scans every `UIKRetargeter` asset in the project, matches by source and target skeleton, and fills the slots from whatever matches. The result is reported through a transient `ResolveStatus` value:

| ResolveStatus    | Meaning                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Unresolved`     | No detection has run yet, or the last detection failed entirely.                                                                      |
| `AutoFilled`     | Detection found exactly one match per direction and assigned both slots.                                                              |
| `Ambiguous`      | More than one retargeter matched the skeleton pair; the plugin will not guess. Assign manually.                                       |
| `NoMatch`        | No retargeter in the project matches one or both directions. Run the wizard (or re-run it if outputs were moved), or assign manually. |
| `ManualOverride` | A user-assigned retargeter is in the slot; auto-detection will not overwrite it.                                                      |

If a slot is empty, or if `ResolveStatus` is anything other than `AutoFilled` or `ManualOverride`, the track displays a warning chip on its outliner row. Hovering the chip shows one of the following tooltips, depending on which slots are missing:

* **Both slots empty:** *"No forward or reverse retargeter assigned. Use 'Re-Detect Retargeters' or assign manually in the track details."*
* **Forward slot only:** *"Forward retargeter (Soma -> Character) not assigned. Use 'Re-Detect Retargeters' or assign manually."*
* **Reverse slot only:** *"Reverse retargeter (Character -> Soma) not assigned. Use 'Re-Detect Retargeters' or assign manually."*
* **Generic unresolved state:** *"Retargeter pair not yet resolved. Use 'Re-Detect Retargeters' from the track context menu."*

To fix any of these, right-click the Animotive Kimodo track row and choose **Re-Detect Retargeters**. This re-runs the project-wide scan and refills both slots. If the scan does not find a match, run the Retarget Wizard for this skeletal mesh, then re-detect. As a last resort, assign the retargeter assets manually in the track's details panel.

## 6. Verify the rest pose

The wizard generates a retargeter pair that maps between Kimodo's internal SOMA skeleton and your character. Both skeletons have an implicit *rest pose* — the pose joints take when no animation is applied (sometimes called the bind pose or A/T-pose). When the two rest poses do not match, retargeted animation will land with a consistent offset: arms a few degrees off, shoulders raised or lowered, fingers slightly curled, or the pelvis floating above or below the ground.

Before producing a real generation, take a minute to confirm the rest pose alignment is acceptable for your character. The cost of fixing this once, up front, is far lower than discovering it after several authoring sessions.

> **Character Creator characters are aligned automatically.** If your target is a Character Creator (CC/CC4) character, the wizard detects the `CC_Base` skeleton and computes the rest-pose alignment for you — it poses each retargeter's target side to match the source. The **body** (pelvis, spine, shoulders/clavicles, arms, legs) lines up with SOMA's A-pose automatically, with no manual hip rotation. **Extremities** — hands, feet, head, and fingers — are left following their parent bone and may still need a small manual adjustment in the retarget pose (see step 4 below) for precise hand/foot/head roll. Other skeletons (Mixamo, Rokoko, custom) still use the manual tuning below; broader automatic alignment is planned.

1. With the wizard's outputs in place, run a short test generation — a one-second clip with a simple prompt is enough. See [Prompting with Animotive Kimodo](/animotive-kimodo/getting-started/prompting-with-animotive-kimodo.md) for the full flow.
2. Once the run reaches **Completed** in the monitor, scrub the timeline. Look for:
   * Arms held away from the body when they should hang naturally (the source SOMA skeleton sits in an A-pose; many UE rigs are T-pose, and vice versa).
   * Shoulders that sit visibly higher or lower than the rest of the upper body.
   * Fingers that are pre-curled or pre-extended when the prompt did not call for it.
   * Feet that float above the ground plane or sink below it.
3. If the result looks correct, skip the rest of this section.

If you do see a consistent offset, the fix is to tune the **Forward Retargeter** (Soma → Character) so its retarget pose matches your character's natural rest. The Forward retargeter is the asset under `/Game/Kimodo/Generated/<MeshName>/` whose name ends in something like `_Soma_to_Target`.

1. In the Content Browser, open the Forward retargeter asset.
2. In the retargeter editor, switch to the **Edit Retarget Pose** mode on the **target** (your character) side.
3. Pose the target skeleton's joints — arms, shoulders, fingers, pelvis height — until the retarget pose visually matches the source SOMA skeleton's rest pose.
4. Save the retargeter asset.
5. Re-run the test generation. The previous consistent offset should be gone.

Most rigs need adjustments only on a handful of joints — typically the clavicle/shoulder pair, the upper arm twist, the finger metacarpals, and pelvis Z. The IK chains themselves rarely need to change; the rest pose is almost always the difference.

If you author or modify retargeters frequently, validate them against a known-good Kimodo sample (drag the non-retargeted Anim Sequence — Unreal's baked-keyframe animation asset — from a previous run onto your character and confirm the pose lands correctly). The non-retargeted clip is the offline reference for tuning retarget pose without re-running generations.

If the offsets are not consistent — they change shot to shot, or the pose explodes into nonsense — that points to a deeper mapping problem in the IK Rig rather than a bind-pose issue. Re-run the wizard, and if that does not help, see [Troubleshooting](/animotive-kimodo/going-further/troubleshooting.md).

## 7. Re-running the wizard

The wizard is safe to re-run on the same skeletal mesh. It overwrites the outputs in `/Game/Kimodo/Generated/<MeshName>/` in place — there is no accumulation of duplicate assets. Re-run after:

* Fixing the underlying source-asset issue that caused `CRAutoGenSkipped` on a previous run.
* Adding or renaming bones on the source skeleton in a way that requires a fresh IK Rig.
* Recovering from accidental deletion of one or more generated assets.

Existing Animotive Kimodo tracks pointing at the regenerated retargeters continue to work, because the asset paths are unchanged. If a track had a `ManualOverride` assignment, it is preserved.

## 8. Troubleshooting

* **No "Add Animotive Kimodo Track" entry in the context menu.** The binding is not a body rig. Confirm you are right-clicking the body skeletal-mesh sub-binding (the `Body` sub-binding on a MetaHuman, or the equivalent for your character). Face rigs, prop attachments, and parent actor rows do not satisfy the `pelvis`/`root` body-rig predicate.
* **Track added, but the retargeter slots show a warning chip.** Auto-detection found no match. Run the **Animotive Kimodo Retarget Wizard** for this skeletal mesh (see section 3), then use **Re-Detect Retargeters** on the track. If you have already run the wizard, confirm the outputs still live under `/Game/Kimodo/Generated/<MeshName>/` and have not been moved or renamed.
* **Wizard finished with a `CRAutoGenSkipped` warning.** Control Rig auto-generation failed; the IK Rig and retargeters are still good. Either author a Control Rig by hand and assign it to the skeletal mesh, or use the text-to-anim export path (no key poses required).
* **Wizard reports "cancelled".** A run that was cancelled mid-way leaves no partial assets behind. Re-open the wizard and run it again.

## 9. See also

* [Animotive Kimodo Track](/animotive-kimodo/working-in-sequencer/animotive-kimodo-track.md) — the day-to-day authoring surface on the body binding.
* [SOMA77 Skeleton](/animotive-kimodo/advanced/skeleton-and-rotation.md) — the skeleton the wizard maps your character onto.
* [Troubleshooting](/animotive-kimodo/going-further/troubleshooting.md) — symptom-to-fix table for the wider pipeline.