summer-engine 1.5.0 → 2.2.0

package/skills/animation/generate-motion/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: generate-motion
+description: Use when the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library. Picks the right curated motion, attaches the resulting clip to an AnimationPlayer. Trigger on "animation", "animate", "idle", "walk", "run", "attack animation", "motion", "mocap", "dance", "death animation".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: animation
+user-invocable: false
+allowed-tools: Read Grep summer_search_assets summer_generate_motion summer_inspect_resource summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
+---
+
+# Generate Motion — Curated Meshy Library
+
+Picks a clip from a **curated mocap library** by name (`idle`, `walk`, `run`, `attack_sword`, ~70 standard names) and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap.
+
+The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `summer:asset-pipeline/asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
+
+> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on the roadmap but not shipped yet. For one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo. See the Edge cases section.
+
+## When to use this skill
+
+- "Add a walk animation to the goblin."
+- "I need an idle, a run, and an attack on this character."
+- "Death animation for the enemy when HP hits zero."
+- The user has a rigged character and zero animations on it.
+
+## When NOT to use this skill
+
+- The user wants to apply an *existing* animation to a *new* model — use `summer:animation/retarget` instead. Don't regenerate.
+- The user wants state-machine wiring (idle → walk → run blend) — generate the clips here, then hand off to `summer:animation/animation-tree`.
+- The user wants facial / lipsync animation — that's `summer:animation/facial-and-lipsync`.
+- The mesh isn't rigged. Rig first; never call `summer_generate_motion` on a static `.glb`.
+- The user wants procedural look-at, IK, foot placement — that's `summer:animation/procedural-animation`.
+- The user described a **custom signature move** that isn't on the curated list. Today, route to the manual-authoring fallback below.
+
+## Steps
+
+### 1. Verify the target is a rigged humanoid
+
+```
+summer_search_assets(query="<character name>", kind="model")
+```
+
+The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `summer:asset-pipeline/asset-strategy`.
+
+### 2. Confirm with the user before spending
+
+> I'm about to generate a "run" animation on `goblin_rigged` via meshy-library — about 30s, ~$0.10. OK?
+
+### 3. Call the tool
+
+```
+summer_generate_motion(
+  rigAssetId: "<id>",
+  backend: "meshy-library",   // only option today
+  motionName: "run"           // exact name from the curated list — see Reference card
+)
+```
+
+Returns `{ animationAssetId, durationSeconds, previewUrl }`.
+
+### 4. Attach to the character's AnimationPlayer
+
+```
+summer_inspect_node("./World/Goblin")             // confirm it has an AnimationPlayer child
+summer_add_node(parent="./World/Goblin", type="AnimationPlayer", name="AnimationPlayer")  // only if missing
+summer_set_resource_property(
+  nodePath="./World/Goblin/AnimationPlayer",
+  resourceProperty="libraries/default",
+  subProperty="<motion_name>",
+  value="<animationAssetId>"
+)
+summer_save_scene
+```
+
+If the character will use multiple clips, leave the AnimationPlayer in place — every subsequent generation appends to the same library. State-machine wiring belongs to `summer:animation/animation-tree`, not here.
+
+## Confirmation gates
+
+- **Before generation:** state the motion name and est. cost (~$0.10). Wait for OK.
+- **Before attaching:** state which AnimationPlayer and which library slot. Wait for OK.
+- **After generation:** if the user hasn't seen the preview, link `previewUrl` and ask "land or regenerate?" before wiring it into the scene.
+
+## Reference card
+
+### Curated motion library — top 30 names (Meshy, exact strings)
+
+`idle`, `idle_alert`, `idle_combat`, `walk`, `walk_strafe_left`, `walk_strafe_right`, `walk_back`, `run`, `run_strafe_left`, `run_strafe_right`, `sprint`, `jump`, `jump_loop`, `jump_land`, `crouch_idle`, `crouch_walk`, `attack_sword`, `attack_punch`, `attack_kick`, `attack_bow`, `attack_cast`, `block`, `dodge_left`, `dodge_right`, `hit_react`, `death`, `death_back`, `wave`, `dance`, `sit_idle`.
+
+The full list is ~70 names. If the user asks for something not on the top-30, try the closest curated name first; if nothing fits, route to the manual-authoring fallback.
+
+### Pitfalls
+
+- **`motionName` typos silently match nothing.** `"run_fast"` is not on the list — the call returns an error. Always check the curated list first. Use exact strings from the list above.
+- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. If you're driving root motion in code, set `root_motion_track` correctly or strip the translation in an AnimationPlayer Edit. See the Godot 4.5 root motion docs.
+- **Rig pose mismatch.** If your rig was rigged with a non-T-pose reference image, the limbs may bend wrong. Re-rig from a T-pose mannequin (see `summer:asset-pipeline/asset-strategy`) before re-generating.
+- **Rig still preparing.** New rigs need ~3 minutes after the rig job completes before the animation library is ready. The MCP route returns 425 "animations_preparing" if you call too early. Wait and retry.
+
+## Anti-patterns
+
+- Calling `summer_generate_motion` on a `.glb` that wasn't rigged — wastes a generation; the API errors but only after 30s.
+- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", kind: "animation")`.
+- Wiring clips into an AnimationTree inside this skill. That's the next skill's job. Generate, attach, hand off.
+- Asking the model to invent a `motionName` that isn't on the list. Quote from the list verbatim, or fall back to manual authoring.
+
+## Edge cases
+
+- **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom prompt-driven backend is on the roadmap but not shipped today. Workarounds: (a) hand-author the clip in the Godot editor's animation panel; (b) record/buy from Mixamo and import as `AnimationLibrary`; (c) compose two curated clips in an `AnimationTree`'s `OneShot` blend.
+- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds, hand-author or import a Mixamo-style external library (out of scope for this skill).
+- **Character is < 1m tall (child / dwarf).** Library clips assume a ~1.8m humanoid. Apply the clip; the proportions retarget but stride length looks long. Either accept it or tune `playback_speed` on the AnimationPlayer track.
+- **Character has wings / tail.** The library ignores the extra bones — they sag. Hand-author additive overlays for the extra bones, or accept the visual hit.
+
+## Fallback (no MCP)
+
+The user can upload to Meshy directly at meshy.ai, generate via the dashboard, download `.glb`, and import as an `AnimationLibrary` in the Godot editor. Slower, but identical output.
+
+## Handoff
+
+- After generating locomotion clips, suggest `summer:animation/animation-tree` to wire idle → walk → run.
+- After generating a one-shot (death, hit-react), suggest `summer:ai-and-npcs/design-npc` to fire it from the behavior state machine.
+- For first-person hand animations on a player, use this skill on a *hands-only rig* and then `summer:character-controllers/fps-controller` for the wiring.
+- If the user wants to apply these clips to a second character, hand off to `summer:animation/retarget`.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — `summer_generate_motion` parameter schema, error codes.
+- `summer:asset-pipeline/asset-strategy` — how to get a Meshy-rigged character in the first place.
+- `summer:animation/animation-tree` — wire the generated clips into a state machine.
+- `summer:animation/retarget` — re-use one library across many characters without regenerating.

package/skills/animation/procedural-animation/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: procedural-animation
+description: Use when the user needs runtime-driven bone modification on top of clips — head look-at, foot IK on uneven ground, hand-grabs-prop, additive lean, hit-direction recoil. Code-and-modifier patterns, not generation. Trigger on "look at", "IK", "foot placement", "foot IK", "lean", "additive layer", "feet floating", "hand penetration", "head tracks player", "ragdoll".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: animation
+user-invocable: false
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors
+paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
+---
+
+# Procedural Animation — Bones Driven by Code
+
+Generated clips give you 80% of a character. The remaining 20% — the eye contact when an NPC speaks, feet that plant on slopes, hands that wrap a sword grip, the lean into a sprint, the recoil from a hit on the left shoulder — is procedural. In Godot 4.5 this is done via the `SkeletonModifier3D` family attached to the `Skeleton3D`, plus tween-driven additive blend layers on the `AnimationTree`. None of it is generative; this skill is a recipe set.
+
+Honest limit: Godot 4.5's IK is good enough for look-at, foot-snap, and simple two-bone arm/leg chains. It is NOT good enough for full-body IK with weight redistribution (a la UE5 Control Rig). For combat-grappling or contact-heavy interactions, hand-author the contact frame and accept some clipping.
+
+## When to use this skill
+
+- Feet clip into / float over uneven terrain.
+- NPC head doesn't track the player during conversation — feels dead-eyed.
+- Character's hand doesn't actually hold the sword — pen-through.
+- Body doesn't lean into turns / aiming.
+- Hit reactions need to come from the hit *direction* (recoil left when struck left), not just one canned animation.
+- Ragdoll on death.
+
+## When NOT to use this skill
+
+- The clip already covers it. Don't IK what mocap already nailed — adds CPU cost and rounding error.
+- The character is far from the camera (LOD2+). Procedural cost outpaces visual benefit. Disable modifiers past 15m.
+- You need facial animation. That's `summer:animation/facial-and-lipsync`.
+- You haven't generated base clips yet. Skeleton modifiers compose ON TOP of clips; without a base pose they'll stack on T-pose and look wrong.
+
+## The three patterns
+
+Almost every procedural request maps to one of these three. Pick the right one before writing code.
+
+### Pattern A — SkeletonModifier3D (post-clip bone overrides)
+
+Attached as a child of `Skeleton3D`. Runs after the AnimationTree writes the pose, modifies specific bones in-place. Includes `LookAtModifier3D`, `SkeletonIK3D` (legacy, still supported), and the new (4.4+) `LookAtModifier3D` chain. Cheap, deterministic, no animation graph dependency.
+
+### Pattern B — Additive AnimationNodeAdd2 layer in the tree
+
+A clip recorded as a *delta from base pose* (e.g., a "lean left" clip that's 0 at center, fully leaned at +1) added on top of locomotion. Driven by writing `parameters/Add/blend_amount` from script. Use for stylistic overlays — turning lean, aiming offset, breathing.
+
+### Pattern C — PhysicalBoneSimulator3D (ragdoll)
+
+The skeleton hands off to physics on death. Bones become `PhysicalBone3D` rigid bodies that fall under gravity and collide with the world. One-way: once ragdoll fires, you can't easily blend back to clip-driven without snapping.
+
+## Pattern A recipes
+
+### A1 — Head look-at the player
+
+The bread-and-butter NPC liveliness fix. Three lines of scene + one script function.
+
+```
+summer_inspect_node "./World/NPC/Skeleton3D"   # confirm bone names
+summer_add_node parent="./World/NPC/Skeleton3D" type="LookAtModifier3D" name="HeadLookAt"
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="bone_name" value="Head"
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="forward_axis" value=2   # +Z forward (Meshy default)
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="primary_rotation_axis" value=1   # Y-up
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="use_secondary_rotation" value=true
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="secondary_rotation_axis" value=0
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="symmetry_limit" value=1.4   # ~80°, prevents the Exorcist
+```
+
+Drive the target each frame:
+
+```gdscript
+@onready var head_look: LookAtModifier3D = $Skeleton3D/HeadLookAt
+
+func _process(_delta: float) -> void:
+    var player := get_tree().get_first_node_in_group("player")
+    if player == null:
+        head_look.influence = 0.0
+        return
+    var to_player := player.global_position - global_position
+    var dist := to_player.length()
+    # Disable look-at past 8m — feels uncanny at long range.
+    head_look.target_node = player.get_path() if dist < 8.0 else NodePath("")
+    head_look.influence = clamp(1.0 - (dist - 6.0) / 2.0, 0.0, 1.0)   # fade out 6→8m
+```
+
+The `symmetry_limit` is the production trick — without it, the head can rotate 180° and the model looks possessed. ~80° matches a human's neck-only range; for a "whole-body turn" use it with the spine chain (next recipe).
+
+### A2 — Spine + head chain (look-at with body turn)
+
+Multiple `LookAtModifier3D` nodes on the same chain — one for `Spine1` (limit 0.4 rad), one for `Spine2` (limit 0.4 rad), one for `Head` (limit 1.0 rad). Total reach: ~110°, distributed naturally. Without the spine contribution, big angles look like the head detaches.
+
+### A3 — Foot IK (slopes & uneven terrain)
+
+The clip has the foot at Y=0; on a slope the ground is at Y=0.15. Without IK, foot floats. Use `SkeletonIK3D` (Godot 4.5 legacy IK still works for two-bone chains; the new chain modifier is preferred for production):
+
+```gdscript
+@onready var skel: Skeleton3D = $Skeleton3D
+@onready var ik_left: SkeletonIK3D = $Skeleton3D/IKLeft
+@onready var ik_right: SkeletonIK3D = $Skeleton3D/IKRight
+@onready var ray: RayCast3D = $FootRay   # cast straight down
+
+func _physics_process(_delta: float) -> void:
+    _solve_foot(ik_left, "LeftFoot")
+    _solve_foot(ik_right, "RightFoot")
+
+func _solve_foot(ik: SkeletonIK3D, bone_name: String) -> void:
+    var bone_idx := skel.find_bone(bone_name)
+    var foot_world := skel.get_bone_global_pose(bone_idx).origin
+    ray.global_position = foot_world + Vector3.UP * 0.5
+    ray.target_position = Vector3.DOWN * 1.0
+    ray.force_raycast_update()
+    if ray.is_colliding():
+        var ground := ray.get_collision_point()
+        if ground.y > foot_world.y - 0.05:   # only lift, never drop into the ground
+            ik.target_node = NodePath("../IKTarget" + bone_name)
+            (get_node("Skeleton3D/IKTarget" + bone_name) as Node3D).global_position = ground + Vector3.UP * 0.05
+            ik.start()
+        else:
+            ik.stop()
+    else:
+        ik.stop()
+```
+
+The 0.5m up-offset on the ray prevents self-occlusion. The "only lift, never drop" rule is the production fix — letting IK push feet into the ground breaks knee bends.
+
+Limits: this works for stairs and gentle slopes. On 45°+ slopes, use a pelvis lowering pass first (drop the root by `min(left_offset, right_offset)`) so the body squats and the legs don't over-extend.
+
+### A4 — Hand grab on prop (sword grip, rifle stock)
+
+`SkeletonIK3D` on the arm chain (Shoulder → UpperArm → LowerArm → Hand), with `target_node` set to a Marker3D parented to the prop. The clip drives the body; IK pins the hand to the grip. For a rifle held two-handed, do the right hand from clip and IK the left hand to a foregrip Marker3D — locks them together regardless of recoil.
+
+## Pattern B — Additive layer
+
+In the AnimationTree, wrap Locomotion in an `AnimationNodeAdd2`:
+
+```
+[parent: AnimationNodeStateMachine.Locomotion]
+  AnimationNodeAdd2
+    in: BlendSpace1D (idle/walk/run)   # the base
+    add: AnimationNodeAnimation         # an additive clip — must be authored as delta
+```
+
+Drive `parameters/Locomotion/Add/blend_amount` (0..1) from script. Use cases: turn-lean (lean amount = clamp(turn_rate, -1, 1)), aim offset (lean while aiming up/down), breathing-while-idle. The "lean" clip must be exported with `track_type = additive` from Blender, or you'll see a 2x-pose stacked on the base.
+
+## Pattern C — Ragdoll on death
+
+```gdscript
+@onready var sim: PhysicalBoneSimulator3D = $Skeleton3D/PhysicalBoneSimulator
+
+func die(impulse_world: Vector3) -> void:
+    $AnimationTree.active = false
+    sim.physical_bones_start_simulation()
+    var pelvis := $Skeleton3D/PhysicalBoneSimulator/PelvisPhysicalBone as PhysicalBone3D
+    pelvis.apply_central_impulse(impulse_world * 4.0)
+```
+
+You need PhysicalBone3D children matching every major bone (set up once via the Skeleton3D context menu → "Create Physical Skeleton"). The impulse parameter sells the death — without directional impulse the body just collapses straight down.
+
+## Confirmation gates
+
+- **Before adding modifiers:** state which bones, which axes. Bone-name typos are a top failure.
+- **Before driving from script:** confirm influence will fade out at distance and the target node is correct.
+- **Before enabling ragdoll:** confirm physical bones exist; without them, simulation is a no-op.
+
+## Reference card
+
+### Bone names (Meshy humanoid skeleton, exact strings)
+
+`Hips`, `Spine`, `Spine1`, `Spine2`, `Neck`, `Head`, `LeftShoulder`, `LeftArm`, `LeftForeArm`, `LeftHand`, `RightShoulder`, `RightArm`, `RightForeArm`, `RightHand`, `LeftUpLeg`, `LeftLeg`, `LeftFoot`, `LeftToeBase`, `RightUpLeg`, `RightLeg`, `RightFoot`, `RightToeBase`. (Meshy uses Mixamo-compatible naming with no `mixamorig:` prefix.)
+
+### Axis conventions
+
+| Setting | Value (Meshy default) |
+|---|---|
+| Forward axis (head/spine) | Z+ |
+| Up axis | Y+ |
+| Right axis | X+ |
+| Foot down | Y- |
+
+### Influence fade-out distances (tuned defaults)
+
+| Modifier | Disable past |
+|---|---|
+| Head look-at | 8m |
+| Foot IK | 15m (snap-to-ground only matters when player can see) |
+| Hand-on-prop IK | always on (cheap, breaks if disabled) |
+| Additive lean | always on |
+| Ragdoll | one-shot, never disabled |
+
+### Pitfalls
+
+- **LookAt rotates wildly past the symmetry_limit.** You set the limit too high. ~80° (1.4 rad) for a head-only modifier; ~25° (0.4 rad) for a single spine bone.
+- **IK pops on the first frame.** Solver hasn't been initialized. Call `ik.start()` after the AnimationTree's first tick, not in `_ready()` — the bone pose is identity until the tree runs.
+- **Foot IK pushes the body up on stairs but the camera doesn't follow.** Camera is parented to the root, not the head. Either parent the camera to a chest bone via `BoneAttachment3D`, or accept that the camera doesn't bob with foot IK.
+- **Additive layer doubles the clip.** The "additive" clip wasn't authored as a delta. Re-export from Blender with `Pose Mode → bake additive`.
+- **Ragdoll just collapses, no spread.** Missing per-bone impulse + missing collision shapes on hands/feet PhysicalBone3D children. Auto-generate via Skeleton3D inspector → "Create Physical Skeleton" with the "Add collisions" option.
+- **Modifiers run before the AnimationTree, not after.** Modifier order is set by tree-position in the scene. SkeletonModifier3D nodes must be CHILDREN of Skeleton3D and appear AFTER any nodes that drive the pose. AnimationTree itself doesn't sit under Skeleton3D — it sits at the character root and writes into Skeleton3D's pose every frame.
+- **Look-at influence flickers at fade boundary.** Use `lerp(current_influence, target, 5 * delta)` instead of an instant assignment. Avoids the sub-pixel oscillation when the player walks the threshold.
+
+### Performance budget
+
+- Each `LookAtModifier3D`: ~5 µs/frame. Cheap; have many.
+- Each `SkeletonIK3D` two-bone solve: ~30 µs/frame. ~30 active solves per frame on mid-range desktop is fine; budget more conservatively on Steam Deck.
+- Ragdoll with full physical skeleton: ~200 µs/frame *while simulating*. Cap concurrent ragdolls at 5–8 before culling oldest.
+
+## Anti-patterns
+
+- Writing `skel.set_bone_pose_position(...)` in `_process`. Bypasses the AnimationTree, fights it next frame, results in jitter. Use modifiers instead — they integrate with the pipeline.
+- Putting IK targets in worldspace and forgetting they don't follow the character. Parent IK targets under the character root or bone — IK target is in the modifier's local space.
+- Procedural look-at without a fade-out at distance. Distant NPCs all snap to player every frame, looks like a hivemind.
+- Foot IK on flying / floating characters. Disable when `is_on_floor() == false`.
+
+## Edge cases
+
+- **Character is mounted (riding a horse).** Disable foot IK on the rider; ride animation already sells the contact. Enable upper-body additive sway driven by horse acceleration.
+- **First-person hands.** Same modifier set, but only the arm chain is visible — disable head/spine modifiers, keep hand-on-prop IK.
+- **Character is a quadruped.** All four legs need foot IK. The bone names are different (`FrontLeftLeg`, `BackRightLeg`, etc.); inspect first.
+- **Network-synced ragdoll.** Don't simulate on every client. Simulate on the host, send bone transforms via `MultiplayerSynchronizer`, blend on receivers. Out of scope; see `summer:multiplayer-and-networking`.
+
+## Fallback (no MCP)
+
+Add modifiers in the Godot editor under Skeleton3D, set bone names from the inspector dropdown (Godot autocompletes from the rig). Hand-write the GDScript driving them. Foot raycasts can be set up visually with a RayCast3D child.
+
+## Handoff
+
+- For the AnimationTree these procedural layers compose with, `summer:animation/animation-tree`.
+- For the source clips that procedural overlays modify, `summer:animation/generate-motion`.
+- For face / lipsync (a different modifier family — BlendShapes, not bones), `summer:animation/facial-and-lipsync`.
+- For NPC behavior triggering ragdoll on death, `summer:ai-and-npcs/design-npc`.
+- For first-person aim sway / ADS, `summer:character-controllers/fps-controller`.
+
+## See also
+
+- `_shared/gd-style.md` — typed GDScript conventions in the snippets.
+- `_shared/mcp-tools-reference.md` — `summer_set_prop` enum-int conventions for axis settings.
+- Godot 4.5 docs: `SkeletonModifier3D`, `LookAtModifier3D`, `SkeletonIK3D`, `PhysicalBoneSimulator3D`.

package/skills/animation/retarget/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: retarget
+description: Use when the user wants to apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration. Trigger on "retarget", "reuse animation", "apply to other character", "same animations on different model", "share animation library".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: animation
+user-invocable: false
+allowed-tools: Read Grep summer_search_assets summer_inspect_resource summer_retarget_motion summer_get_scene_tree summer_set_resource_property summer_save_scene
+paths: ["**/*.tscn", "**/*.tres"]
+---
+
+# Retarget Motion — One Library, Many Characters
+
+Generating a "run" clip costs ~$0.10 and 30s. If you have ten enemies, regenerating ten runs is ten generations of wasted money and clock time when one Meshy retarget call would cost ~$0.05 and take ~10s. Retarget is the right answer the moment a project has more than one rigged humanoid character.
+
+The Meshy retarget pipeline takes a source `animationAssetId` and a target `rigAssetId`, both of which must be **Meshy-rigged humanoids**. It re-projects the animation onto the target's bone hierarchy, preserves timing and root motion, and emits a new `animationAssetId` against the target rig. The source clip is unchanged.
+
+## 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
+
+- Source and target are not both Meshy-rigged humanoids — retarget will fail. Route to `summer:animation/generate-motion` to regenerate, or to `summer:asset-pipeline/asset-strategy` to re-rig.
+- Target is a quadruped or non-humanoid (wings-only, mech, blob). Meshy retarget is humanoid-skeleton-locked. Hand-author or regenerate.
+- The user wants ONE new clip on ONE character — just call `summer:animation/generate-motion`. Retarget is for fan-out.
+- The user wants to retime, edit, or layer the animation — that's `summer:animation/animation-tree` and the `summer:animation/procedural-animation` additive layers.
+
+## The compatibility check (do this BEFORE calling retarget)
+
+The dominant failure mode is retargeting between rigs that look humanoid but have different bone counts, names, or hierarchies. Meshy auto-rigs use a fixed 52-bone humanoid skeleton — every Meshy rig is interchangeable. Mixamo / VRoid / hand-rigged FBX imports are NOT — even if they're "humanoid", the bone names differ and the retarget call rejects them.
+
+Before calling `summer_retarget_motion`, verify:
+
+```
+summer_inspect_resource(<source_rigAssetId>)
+summer_inspect_resource(<target_rigAssetId>)
+```
+
+Both responses should include `rig_provider: "meshy"` and `bone_count: 52`. If either is missing those fields or shows a different provider, **stop**. Tell the user: "Target rig isn't Meshy-rigged — retarget will fail. Either re-rig the target via `summer_generate_3d({ kind: \"image-to-3d\", imageUrl: \"...\", options: { rig: true } })` or regenerate motion directly on it via `summer:animation/generate-motion`. Which?"
+
+If both are Meshy-rigged but the target's mesh has wildly different proportions (e.g., source is a 1.8m human, target is a 2.5m ogre with arms-down-to-knees), retarget will succeed but the *result* will look wrong — clipping, foot-floating, or limb-twisting. Warn the user before spending: "Proportions differ a lot — retarget will run but you'll likely need procedural foot IK on the result. Continue?" Hand off to `summer:animation/procedural-animation` after.
+
+## Steps
+
+### 1. Find the source library
+
+```
+summer_search_assets(query: "<source character>", kind: "animation")
+```
+
+Returns a list of `{ animationAssetId, name, durationSeconds }`. Cache the IDs.
+
+### 2. Find the target rig
+
+```
+summer_search_assets(query: "<target character>", kind: "model")
+```
+
+Confirm `rigAssetId` is present and Meshy-provider.
+
+### 3. Confirm with user before spending
+
+Always batch-ask. Retargets are cheap individually but $0.05 × 30 clips × 5 enemies = $7.50, which deserves consent.
+
+> I'm about to retarget 12 clips (idle, walk, run, attack, ...) from `goblin_rigged` onto `orc_rigged` — about 12 × $0.05 = $0.60, ~2 minutes total. OK?
+
+### 4. Loop the retarget calls
+
+```
+for clip in source_clips:
+  summer_retarget_motion(
+    sourceAnimationAssetId: clip.animationAssetId,
+    targetRigAssetId: <target_rigAssetId>,
+    name: clip.name              // preserve the slot name (idle, walk, run...)
+  )
+  // returns { animationAssetId, durationSeconds }
+```
+
+Save the returned IDs as a map `{ name: animationAssetId }` for the target.
+
+### 5. Attach to the target's AnimationPlayer
+
+Same pattern as `summer:animation/generate-motion`: ensure an `AnimationPlayer` child exists, then write each clip into `libraries/default`.
+
+```
+summer_set_resource_property(
+  nodePath: "./World/Orc/AnimationPlayer",
+  resourceProperty: "libraries/default",
+  subProperty: "<clip_name>",
+  value: "<retargeted_animationAssetId>"
+)
+```
+
+`summer_save_scene` once at the end, not per clip.
+
+## Confirmation gates
+
+- **Before any retarget call:** show the full list and total cost.
+- **After the first retarget:** 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
+
+### When retarget fails — the 5 common causes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| API returns `incompatible_rig` | Target isn't Meshy-rigged | Re-rig target via `summer_generate_3d({ kind: "image-to-3d", options: { rig: true } })` |
+| API returns `bone_mismatch` | Source rigged with custom bones (extra wings, etc.) | Strip extras or regenerate motion natively on target |
+| Clip plays but limbs twist 180° | T-pose vs A-pose mismatch | Re-rig source from T-pose reference |
+| Feet float / clip into ground | Target is much taller/shorter | Apply foot IK — see `summer:animation/procedural-animation` |
+| Root motion drifts | Source had baked root translation, target scale differs | Strip root track in AnimationPlayer or scale `playback_speed` |
+
+### Cost math (decision rule)
+
+| Scenario | Generate fresh | Retarget |
+|---|---|---|
+| 1 character, 1 clip | $0.10 | n/a |
+| 1 character, 12 clips | $1.20 | n/a |
+| 5 characters, same 12 clips | $6.00 (5 × $1.20) | $1.80 ($1.20 + 4 × $0.60 retarget) |
+| 30 NPCs, same 8-clip set | $24.00 | $6.40 ($0.80 + 29 × $0.40) |
+
+The break-even is two characters. Past that, retarget is always cheaper.
+
+### Pitfalls
+
+- **Not preserving clip names.** If you don't pass `name:` to `summer_retarget_motion`, the target gets clips named `retargeted_001`, `retargeted_002` and your AnimationTree state machine breaks. Always pass the source name.
+- **Retargeting one clip at a time interactively.** Batch the loop; each call has a few seconds of overhead. Sequential is fine; parallel via `summer_batch` is faster if the project supports it.
+- **Forgetting the source library still owns the clips.** Source character's AnimationPlayer is unchanged. Don't accidentally re-attach the *source* IDs to the target.
+- **Retargeting then regenerating "to clean it up".** If retarget produced bad output, the fix is procedural foot IK or a bone-correction modifier — not regeneration. Regeneration only makes sense if the source itself is bad.
+- **Mixing Meshy and Mixamo libraries on the same character.** They have different bone-naming conventions; the AnimationPlayer tries to play tracks against bones that don't exist. Pick one rig provider per character and stick with it.
+
+### Quality bar
+
+- Library was originally generated on a 1.8m humanoid → target between 1.5m and 2.2m: retarget is production-ready.
+- Target is 2.2m–3m: retarget runs, expect foot-clipping; layer foot IK.
+- Target is < 1.5m or has cartoon proportions (big head, short limbs): retarget runs, expect noticeable limb-pop; consider regenerating natively.
+
+## Anti-patterns
+
+- Calling `summer_retarget_motion` without first verifying both rigs are Meshy-provider.
+- Retargeting from a hand-authored animation library (Mixamo `.fbx`, etc.). The MCP wraps Meshy's retarget, which only accepts Meshy-rig source clips. For external libraries, use Godot's built-in `BoneMap` retargeting in the editor — out of scope for this skill.
+- Retargeting on every gameplay session. Retarget once, persist the resulting `animationAssetId`, and reference from the scene file. The asset library survives session restarts.
+- Generating motion on each enemy separately because you forgot retarget existed. The first time the project has two rigged characters, point at this skill.
+
+## Edge cases
+
+- **Source library uses additive blend tracks.** Additive clips (e.g., a "lean left" overlay) retarget but the additive flag is preserved only on Meshy-native rigs. Verify the `track_type` survived: `summer_inspect_resource(<retargeted_animationAssetId>)`.
+- **Source has facial blendshape tracks.** Meshy retarget only handles skeleton. Facial tracks are stripped. Hand off to `summer:animation/facial-and-lipsync` to re-author per character.
+- **Target rig was generated months ago and Meshy updated their skeleton schema.** Rare but happens. Symptom: bone-count mismatch even though both rigs are Meshy. Re-rig the target with a fresh `summer_generate_3d({ kind: "image-to-3d", options: { rig: true } })` call.
+- **The user wants to retarget *to* the source rig as a sanity test.** Allowed and useful — round-trips should be near-identical.
+
+## Fallback (no MCP)
+
+Open the source `.glb` in Blender, export the animation, then in Godot 4.5 use the BoneMap-based humanoid retargeting workflow (Project → Tools → Bone Map). Set both source and target as humanoid profile, configure the bone mapping if names differ, save the retargeted clip into the target's `AnimationLibrary`. ~5 minutes per clip vs ~10 seconds via MCP. Documented in the Godot 4.5 character animation docs.
+
+## Handoff
+
+- After retarget, the wiring is identical to a freshly-generated clip — hand off to `summer:animation/animation-tree` for state-machine integration.
+- If retarget produced foot-clipping or hand-pen-through-prop issues, hand off to `summer:animation/procedural-animation` for IK correction.
+- For NPC behavior driving these clips, hand off to `summer:ai-and-npcs/design-npc`.
+
+## See also
+
+- `summer:animation/generate-motion` — to create the source library.
+- `summer:asset-pipeline/asset-strategy` — to ensure all characters are Meshy-rigged before retargeting.
+- `summer:animation/animation-tree` — wire the retargeted clips into a state machine.
+- `summer:animation/procedural-animation` — fix proportional mismatches with foot IK after retarget.