FERRETGame engine over Babylon.js
Ferret

Characters and animation from Unreal

Skill ferret-unreal-characters · download all skills · SKILL.md

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