Retarget

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: summer tool --list prints every registered tool and there is no retarget entry. Never call one: the MCP server rejects unknown tool names outright.

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

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 assets.generate_3d({ ..., rig: true }).

1. Find the source clip names

Copy code
assets.search({ query: "<source character>", assetType: "animation", scope: "mine" })

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

Copy code
assets.search({ query: "<target character>", assetType: "3d_model", scope: "mine" })

The rigged model's assetId is its rigAssetId. Search results do not say whether a model is rigged: run step 4's call with dryRun: true, which refuses a model that is not rigged (invalid_input on rigAssetId). Then the model was never rigged — stop and propose assets.generate_3d({ kind: "image-to-3d", imageUrl: "...", rig: true }) first, or route to asset-strategy.

3. Confirm with user before spending

Regeneration is a real generation per clip per character, and each one uses credits. Say the total count; dryRun: true on the call below gives the credits for all its clips at once.

I'm about to generate 12 clips (idle, walk, run, attack, ...) on orc_rigged. That is 12 generations, a few minutes total. OK?

4. One generation call for all the clips

Copy code
assets.generate_motion({
  rigAssetId: "<target_rigAssetId>",
  backend: "meshy-library",
  motionNames: source_clip_names   // exact curated names — see generate-motion's list
})
jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished

motionNames takes up to 12 names in one call. The finished job's result holds the new clips' asset ids; when the target already has every clip, the answer is done at once with reused and nothing is charged. Save the 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.

Copy code
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)

The current Summer Engine build ships a retargeting stack that the MCP layer does not wrap. Verified instantiable on the shipped binary: BoneMap, SkeletonProfileHumanoid (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

• Before any generation call: show the full clip list and the number of generations.
• 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

Decision rule

The real decision is generating per character versus spending the time on a BoneMap.

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 assets.get({ 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 assets.generate_3d({ kind: "image-to-3d", imageUrl: "...", rig: true }) call.
• 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. The upstream engine docs cover this under "Retargeting 3D Skeletons".

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.

From a shell

No Summer MCP tools in this session? Run each one as a command; when summer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.