Retarget

Retarget

The .retarget command handles animation retargeting between Unreal Engine skeletons — porting monster animations to the player character, for example. It extracts the source animation, remaps keyframes to the target skeleton, and writes the result as a new asset in one step.

automod -g <game-id> .retarget <config.toml>

The config file is a TOML with [[retarget]] job arrays and optional [bones.<id>] override sections. The entire config is validated before any job runs — structural errors, skeleton mismatches, and output collisions are all reported at once.

Config schema

[bones.raven]
Dm-L-UpperArm-Tw = "freeze"
Ab-L-Becep = "copy"

[[retarget]]
anim = "$SB$Content$Art$Character$Monster$CH_M_NA_53$Animation$M_Raven_BackJumpCombo"
base = "$SB$Content$Art$Character$PC$CH_P_EVE_01$Animation$P_Eve_Sword_SlotNormal_ChainStab"
from = "$SB$Content$Art$Character$Monster$CH_M_NA_53$CH_M_NA_53_Skeleton"
to = "$SB$Content$Art$Character$PC$CH_P_EVE_01$CH_P_EVE_01_Skeleton"
mode = "copy"
bake-format = "float96"
eliminate = false
retime = 0
as = "/Game/Art/Character/PC/CH_P_EVE_01/Animation/jpabscale_P_Eve_Raven_BackJumpCombo"
out = ".included"
bones = "raven"

[[retarget]]
anim = "$SB$Content$Art$Character$Monster$CH_M_NA_53$Animation$M_Raven_ChaseCombo"
base = "$SB$Content$Art$Character$PC$CH_P_EVE_01$Animation$Proto_Sword_Lightattack_02_Root"
from = "$SB$Content$Art$Character$Monster$CH_M_NA_53$CH_M_NA_53_Skeleton"
to = "$SB$Content$Art$Character$PC$CH_P_EVE_01$CH_P_EVE_01_Skeleton"
mode = "copy"
bake-format = "float96"
eliminate = false
retime = 0
as = "/Game/Art/Character/PC/CH_P_EVE_01/Animation/jpabscale_P_Eve_Raven_ChaseCombo"
out = ".included"
bones = "raven"

All [[retarget]] fields are required:

Merge vs standalone

Standalone (base absent): extracts the source animation, retargets all tracks from the source skeleton to the target skeleton, swaps the skeleton reference, and writes the output. A fresh retargeted animation on the target skeleton.

Merge (base present): keeps the target character’s own animation as the “canvas” and overwrites only the tracks whose bones the source animation drives. Key behaviors:

• Output frame count = source frame count (or retime if set); base tracks are resampled
• Bones the source does NOT animate are held at the target skeleton’s bind-rest pose (not the base animation’s values)
• After merge, a motion-fidelity validator reports MISSING MOTION / POOR CORRELATION bones

Bone overrides

[bones.<id>] maps bone names to override modes:

• freeze — hold at identity (zero rotation/offset)
• copy — pass through without retarget math
• delta — full delta retarget (relative rotation + translation)
• scale — scale retarget (ratio of bone lengths)

A bone not listed in the override map uses the job-level mode.

Output

The out path may be relative to the config file’s directory or absolute. The actual file is written to:

<out>/<as-path>.uasset

So out = ".included" drops animations straight into the mod’s .included tree with no rename or staging step needed.

Validation

Before any job runs, the config is validated for:

• Structural correctness (required fields, valid mode/bake-format, retime requires base)
• Skeleton integrity (every bone in [bones.<id>] exists in the target skeleton)
• Output collisions (two jobs writing the same file)

All errors are reported at once; nothing runs until the config is clean.