RetargetKit — documentation

v1.2.1 · Blender 4.2 LTS and later (tested on 5.1) · Windows / macOS / Linux

1. Installing

Edit, then Preferences, then Add-ons, then Install, and pick the downloaded zip. Tick the checkbox to enable it.

2. A retarget in four steps

1. Press N in the viewport and open the "Retarget" tab.
2. Set From to the rig that has the animation, and To to the rig that should receive it.
3. Press Auto-Map Bones and glance down the list.
4. Press Retarget.

The result is a new action on the target rig, named after the source action.

3. Which rigs are recognised

Ten families: Mixamo, Unreal Mannequin, Rigify (the control bones, the deform bones and the metarig), Character Creator and iClone, Auto-Rig Pro, Daz Genesis 3 and 8, VRoid and VRM, and 3ds Max Biped. MakeHuman's game-engine skeleton uses the Unreal names and is covered by that table. When both rigs are recognised the panel says so, and the mapping comes from a table.

Every family is mapped onto one canonical skeleton rather than onto each other, which is why any of the ten retargets to any other in either direction.

Anything else is matched by name. That works more often than it sounds — most schemes are the same words in a different order with a prefix bolted on — but always check the list before pressing Retarget.

4. Fingers

Include Fingers sits above Auto-Map Bones and is on by default. Every recognised family's hands are in the tables, so when both rigs have fingers the mapping picks up thirty more bones — five fingers, three segments, both hands — matched thumb to thumb and segment to segment.

Fingers transfer by exactly the same rule as the rest of the skeleton and to the same accuracy. They are optional only because they triple the bone count and make the bake take proportionally longer; turn them off when you only want the body.

If a rig is not recognised, the name-based fallback will still pair fingers whose names reduce to the same thing on both rigs.

5. The mapping list

Each row is one source bone driving one target bone. The checkbox leaves a pair out without deleting it, which is the quick way to test whether one bone is causing a problem. Both fields are bone pickers, so you cannot mistype a name.

Bones that appear in only one of the rigs are simply left out. A retarget does not need every bone to be useful.

Mirror L to R and R to L fill one side of the body from the other. Useful when you have corrected the left arm by hand and want the right to match, or when a rig only auto-mapped down one side. A row is mirrored only when the flipped name exists on both rigs and reads as the opposite side; anything else is reported and left alone, because a mirror that lands on the wrong bone is worse than one that does nothing.

6. Checking the mapping

Check Mapping reads the mapping over without changing it and lists what it finds:

• Left and right are crossed — a source bone on one side driving a target bone on the other. This is the mistake worth catching, because the bake looks plausible until you play it.
• Driven by two source bones — two rows pointing at the same target. The second one silently overwrites the first, every frame.
• Not on this rig — a bone name that no longer exists, which is what you see after loading a preset built for a different character.
• Driving two target bones — a warning rather than an error. Occasionally deliberate, usually a row edited on one side and forgotten on the other.
• Bones both rigs have that are not mapped, and rows that are only half filled in.

The same check runs automatically when you press Retarget. If it finds a genuine error the bake stops and says why; turn off Check Before Baking in Options if you want it to go ahead anyway.

7. Presets

A mapping is worth keeping. Type a name into the Presets panel and press the save button, and the whole list — plus the transfer settings — is written out under that name. Load it back with the button beside the preset menu.

Presets store bone names, not links to objects, which is what makes them portable: the same preset applies to a fresh import of the same character in a different file. If a preset names bones the current rigs do not have, the rows are still loaded and the missing names are reported, rather than half the mapping disappearing without a word.

By default presets live in Blender's own presets folder. The add-on preferences have a Preset Folder field — point it at a shared folder and everyone on the project reads and writes the same mappings.

8. Options

• Transfer Root Motion — move the character through the scene as well as posing it. Turn it off to retarget the pose only and keep the character on the spot.
• Scale to Target — scale that motion by the height difference between the rigs. Without it a short character inherits a tall one's stride and skates.
• Use Action Range — bake exactly the frames the source action covers. Turn it off to use the scene frame range instead.
• Every Nth Frame — 1 bakes every frame and is exact. Larger values give fewer keyframes and a looser match.
• All Actions — retarget every action in the file rather than only the one on the source rig. This is the one to use for a mocap library.
• Check Before Baking — read the mapping over first and stop on a real error. Turn it off to bake regardless.

9. How the transfer works

Worth knowing, because it explains what the add-on can and cannot fix.

For each pair, the source bone's rotation away from its own rest pose is measured in world space, and the target bone is rotated the same amount away from its rest pose. That is what makes rigs with different rest poses work: nothing assumes the two skeletons agree about which way is "forward" for a given bone. Current limit (1.2.2): the stance the two rigs rest in must match as well. If one rig rests in an A-pose and the other in a T-pose, that difference stays in every frame — measured from an Unreal Mannequin (A-pose) to a Mixamo rig (T-pose): 53° at the upper arm and 60° at the forearm. Bone names, bone orientation and roll do not need to match.

Bones are posed parents first, and the scene is refreshed between them, so an error at the shoulder cannot compound down to the hand.

10. What it does not do

It transfers rotations, plus the hips' position. It does not solve IK, plant feet, or fix foot sliding introduced by different leg lengths. Nothing added in 1.1.0 changes that — presets, mirroring, fingers and the mapping check all make the mapping easier to get right, which is a different problem. Those remain separate problems, and a tool that claimed to solve them here would be overselling. Retarget first, then correct the contacts by hand or with an IK setup on the target rig.

11. Troubleshooting

The arms are twisted. Almost always a mapping error rather than a maths error. Press Check Mapping: a crossed side, or a target bone that two rows are both driving, is exactly what it looks for.

Nothing happened. The source rig needs an action assigned, or All Actions turned on.

The character skates. Turn on Scale to Target, or set the scale by hand. If the rigs are very different proportions, some sliding is unavoidable without an IK pass.

Auto-Map found very few bones. Neither rig was recognised and the names were too different for the fallback. Add the important pairs by hand — hips, spine, chest, head, and the four limbs are enough to be useful.

The result is jittery. Set Every Nth Frame back to 1.

The bake is slow. Turn off Include Fingers. Thirty extra bones a rig is thirty extra bones a frame.

A preset loaded but half the rows are red. The message says which bone names are not on the current rigs. Usually the character was re-imported under a different name, or the preset was built for a different rig entirely.

Mirror says there is nothing to mirror. Either the other side is already mapped, or these bone names carry no side marker it recognises. It marks nothing rather than guessing.

12. Changelog

v1.2.1

• Auto-mapping understands mocap skeletons that name the joint rather than the limb: elbow, wrist, knee, ankle, and a sided hip meaning the top of the leg. A Move AI skeleton went from 5 of 18 bones mapped to 18 of 18.
• Fixed: a forearm was classified as an upper arm, so the two collapsed into one class and one of them was dropped. Affected rigs that the preset tables do not recognise, where mapping falls back to matching by name.
• Fixed: bones carrying a vendor prefix (Character Creator and similar) left the hand, thigh and foot unmapped in that same fallback.

v1.2.0 — Auto-mapping now pairs bones that carry the same name on both rigs before it starts guessing. On a custom skeleton — numbered spine segments, long arm and leg chains, twist bones — the name classifier collapsed every chain to a single class and kept one bone from each: a 62-bone rig produced 10 pairs, and the artist mapped the other 52 by hand. Measured after the change: 62 of 62, and 240 frames retargeted in 1.7 s. Recognition of Mixamo, Rigify and the other known schemes is unchanged.

v1.2.0 — mapping presets, saved with the transfer settings and portable between files, with an optional shared folder set in the add-on preferences. Finger mapping for every rig family, thirty bones a rig, toggled with Include Fingers. Four more families: Daz Genesis 3 and 8, VRoid and VRM, the Rigify metarig, and 3ds Max Biped — ten in all, every one of them mapping to every other. Mirror Mapping, which fills one side of the body from the other and refuses anything it cannot land safely. Check Mapping, which reports crossed sides, targets driven twice, unknown bone names and unmapped limbs before the bake rather than after. Transfer accuracy unchanged and still exact, fingers included.

v1.0.0 — first release. Automatic mapping for five rig families plus a name-based fallback, editable mapping list, world-space rest-compensated transfer, scaled root motion, batch retargeting, and swap.