---
name: ferret-unreal-characters
description: Use to bring Unreal characters, NPCs and animals into Ferret: inventory, export one mesh per editor run with its clips, clips to one skeleton, assembling parts on one skin, hair, morph targets, size per tier, Animation Blueprints to graphs, and the character viewer check.
---

# Characters and animation from Unreal

## When to use
Exporting playable characters (customizer presets), NPCs or animals from a UE5 project, turning Animation Blueprints into Ferret graphs, or checking why an exported character looks or moves wrong. Placing and driving them in a level is `ferret-animation`, `ferret-ai-navigation` and `ferret-transform`.

## Steps
1. **Inventory** (`ue/inventory_characters.py`): meshes, skeletons, clips per skeleton, morph counts. Families that share a skeleton share clips.
2. **Read the game's data**: presets and tables (parts, material options, tints, morphs), not just meshes.
3. **Export** with `ue/characters.py`, **one mesh per editor run**, `FERRET_CLIPS=1` for its clips.
4. `characters.mjs clips` to one skeleton; `--keep` what the game plays.
5. `characters.mjs assemble` from the game's spec: one skin, morphs baked by name, `solid` hair with `hairColor()`.
6. `characters.mjs optimize` per tier (morphs dropped unless `keepMorphs`).
7. `animbp.mjs` for Animation Blueprints; read every `unknown` it reports.
8. The character viewer (`?characters=<index.json>`), then the game in third person.

## Check afterwards
The viewer report is clean (every file loads, every clip moves bones, no part without skin or material); the hero walks forwards; sizes per tier within budget.

## What usually goes wrong
- Several meshes in one editor run: each file carries the earlier ones' clips.
- Writing a retarget map for skeletons that already share bone names.
- Hair as stripes (groom strands do not bake) or red (`Hair Tint` is melanin and redness, not RGB).
- 100 morph targets left in: tens of MB per head.
- Hair bones left at the rest pose; one Babylon skeleton per part.
- Turning the model 180 degrees by guess (it faces +Z): measure the toes against the walk.
- Same-named assets in two folders overwriting each other; key by path.
More in `reference/ue-characters.md`.

## Files

- `reference/ue-characters.md` — Exporting skeletal meshes, clips and Animation Blueprints from Unreal into Ferret characters, and the traps found doing it: clips that only export through a playing component, hair, morph targets, shared skeletons, size, facing.
- `reference/api-animation.md` — every export of `@ferret/animation` with signature and doc comment