generate-motion

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_list_my_assets summer_get_asset summer_get_asset_download_url 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.

Web Chat / Public Orchestrator Equivalent

In PublicSummerEngine chat, the equivalent direct tools are:

rigModel({ modelAssetId })
generateAnimation({ rigAssetId, animationName })
meshyJobStatus({ jobId })

If the character came from createCharacter, it may already be rigged and have metadata.meshyRigTaskId; generate animations directly against that rig asset. Verified animation names from the recovered production flow are idle, walk, run, jump, and attack. fall returned invalid_animation, so do not present it as a default.

Before generating clips in PublicSummerEngine chat, confirm the rig asset listing/status exposes hasMeshyRigTask or animationsReady:true. If generateAnimation returns animations_preparing, wait, poll/list the rig again, and retry; this is the post-rig setup catching up, not a reason to send the user to Studio.

After animation jobs complete, import the rig plus child animation assets together and wire them through import-character. Do not hand off to Studio unless the user asked for Studio/manual control or the direct chat tools fail.

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>", assetType="3d_model", source="my_assets")

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, and previewUrl. Resolve the asset before handoff so you have the stable file/download metadata:

summer_get_asset(assetId="<animationAssetId>")

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", assetType: "animation", source: "my_assets").
• 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

• references/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.