git:20261010.10f9528 to git:20261010.4ade947

---

name: retarget

description: "Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration."

license: MIT

compatibility: [Cursor, Claude Code, Windsurf, Codex]

category: animation

user-invocable: false

allowed-tools: Read Grep summer_search_assets summer_inspect_resource summer_generate_motion summer_get_scene_tree summer_set_resource_property summer_save_scene

paths: ["**/*.tscn", "**/*.tres"]

---

# Retarget Motion — One Library, Many Characters

## There is no retarget MCP tool. Read this before promising one.

Summer ships **no** `summer_retarget_motion` tool, and no other MCP tool that

re-projects an existing animation asset onto a second rig. Verify it yourself:

Two real paths exist. Pick by whether the target rig is Meshy-rigged.

| Situation | Path |

|---|---|

| Target is not Meshy-rigged, or the clip is hand-authored / Mixamo / bought | In-engine retargeting: `BoneMap` + `SkeletonProfileHumanoid` + `RetargetModifier3D`. No credits, no network, but you configure the bone mapping. |

The rest of this skill covers both.

## When to use this skill

- "I bought (or generated) one animation library — apply all clips to my five enemies."

- "Goblin and orc have the same combat moves — share the library."

- "I have 30 NPCs with the same idle / walk / talk loop."

- The user generated motion on character A and now needs it on character B.

## When NOT to use this skill

- The user wants ONE new clip on ONE character — just call `generate-motion`.

- The user wants to retime, edit, or layer the animation — that's `animation-tree` and the `procedural-animation` additive layers.

- Target is a quadruped or non-humanoid (wings-only, mech, blob). The curated Meshy

library is humanoid-only and `SkeletonProfileHumanoid` is a humanoid profile.

Hand-author instead.

## Path A — regenerate on the target rig (Meshy-rigged targets)

This is the path for the common case: several characters that all came out of

`summer_generate_3d(... rig: true)`.

### 1. Find the source clip names

```

summer_search_assets(query: "<source character>", assetType: "animation", source: "my_assets")

```

You want the *names* (`idle`, `walk`, `run`, ...), not the asset IDs — the IDs

belong to the source rig and cannot be transplanted.

### 2. Find the target rig

```

summer_search_assets(query: "<target character>", assetType: "3d_model", source: "my_assets")

```

Confirm a `rigAssetId` is present. If it is null the model was never rigged —

first, or route to `asset-strategy`.

### 3. Confirm with user before spending

### 4. Loop the generation calls

```

for name in source_clip_names:

summer_generate_motion(

rigAssetId: "<target_rigAssetId>",

backend: "meshy-library",

motionName: name // exact curated name — see generate-motion's list

)

// returns animationAssetId in the job result

```

Save the returned IDs as a map `{ name: animationAssetId }` for the target.

### 5. Attach to the target's AnimationPlayer

`summer_set_resource_property` requires the target scene path — it is not optional.

```

summer_set_resource_property(

scenePath: "res://main.tscn",

nodePath: "./World/Orc/AnimationPlayer",

resourceProperty: "libraries/default",

subProperty: "<clip_name>",

value: "<animationAssetId>"

)

```

`summer_save_scene(scenePath: "res://main.tscn")` once at the end, not per clip.

## Path B — in-engine retargeting (non-Meshy rigs, bought or hand-authored clips)

(56 bones), `RetargetModifier3D`.

The shape:

1. Create a `BoneMap` resource per rig, with `profile` set to a

`SkeletonProfileHumanoid`. Map each profile bone name to that rig's actual

bone name. Save as `.tres` — one per distinct skeleton, reused forever.

2. On import, set the source `.glb`'s import options to use the source rig's

`BoneMap` so its animation tracks are expressed against the humanoid profile.

3. On the target character, add a `RetargetModifier3D` under the `Skeleton3D`

and set its `profile` to the same `SkeletonProfileHumanoid`. It re-projects

the profile-space pose onto the target's bones each frame.

This costs no credits and works with any humanoid skeleton, including Mixamo and

hand-rigged FBX. The cost is the bone-mapping pass: a few minutes per distinct

skeleton, once.

## Confirmation gates

- **After the first clip:** preview the result. If it looks wrong, stop the loop

and re-evaluate (proportions, T-pose, missing bones).

- **Before saving the scene:** confirm the AnimationPlayer additions you're about to write.

## Reference card

| Scenario | Regenerate (Path A) | In-engine BoneMap (Path B) |

|---|---|---|

Note the case that makes most of this moot: **NPCs that share one rig share one

animation library already.** If the user's 30 enemies are 30 instances of the

same rigged `.glb`, nothing needs retargeting — instance the scene.

### Pitfalls

- **Assuming a retarget tool exists.** It does not. Check the tool list before

promising a capability; a hallucinated tool name fails the call outright.

- **Reusing the source `animationAssetId` on the target.** Animation assets are

bound to the rig they were generated against. Generate against the target's own

`rigAssetId` (Path A) or go through a `BoneMap` (Path B).

- **Omitting `scenePath`.** `summer_set_resource_property`, `summer_save_scene`,

`summer_add_node`, and `summer_set_prop` all take a required `scenePath`.

- **Mixing Meshy and Mixamo libraries on one character without a BoneMap.** The

bone-naming conventions differ; the AnimationPlayer plays tracks against bones

that don't exist. One rig provider per character, or map both through the

humanoid profile.

- **Proportion mismatch.** A library authored on a 1.8m humanoid on a 2.5m ogre

runs, but you get foot-float and limb-twist. Layer foot IK afterwards — see

`procedural-animation`.

### Quality bar

- Library authored on a 1.8m humanoid → target between 1.5m and 2.2m: production-ready.

- Target 2.2m–3m: expect foot-clipping; layer foot IK.

- Target < 1.5m or cartoon proportions (big head, short limbs): expect limb-pop.

## Anti-patterns

- Calling a `summer_retarget_motion` / `summer_retarget_*` tool. None exists.

- Passing an asset ID to `summer_inspect_resource`. That tool takes a `res://`

**path** to a resource in the project, not a cloud asset ID. Use

`summer_get_asset(assetId: ...)` for asset metadata.

- Generating motion on each enemy separately when they are instances of the same

rig. Instance the scene; the library comes with it.

## Edge cases

- **Source has facial blendshape tracks.** Skeleton retargeting only handles

bones. Facial tracks do not transfer. Hand off to `facial-and-lipsync`

to re-author per character.

- **Target rig is a different Meshy skeleton generation.** Symptom: bone-count

mismatch even though both are Meshy. Re-rig the target with a fresh

- **The clip the user wants is not on the curated list.** Path A cannot produce

it. Either hand-author it, or import a Mixamo clip and take Path B.

## Fallback (no MCP)

Path B is the fallback and does not need MCP at all. In Summer Engine: select

the source `.glb` in the FileSystem dock, open the Import tab, create/assign a

`BoneMap` with a `SkeletonProfileHumanoid` profile, re-import. On the target

character add a `RetargetModifier3D` under `Skeleton3D` with the same profile.

## Handoff

- After the clips are on the target, the wiring is identical to a freshly-generated

clip — hand off to `character-animation-wiring` for the end-to-end

path (inspect the target's real clip/bone names first — retargeted imports rename

things), or `animation-tree` for blend-space/overlay graph design.

- If the result shows foot-clipping or hand-pen-through-prop issues, hand off to

`procedural-animation` for IK correction.

- For NPC behavior driving these clips, hand off to `design-npc`.

## See also

- `generate-motion` — the tool that actually produces clips, and the curated name list.

- `asset-strategy` — getting characters rigged in the first place.

- `animation-tree` — wire the clips into a state machine.

- `procedural-animation` — fix proportional mismatches with foot IK.