/ue-mcp-animation

name: ue-mcp-animation
description: Use when creating, modifying, retargeting, rigging, constraining, or validating skeletal animation through UE-MCP. Covers native UE 5.8 IK Rig and Retargeter authoring, the Control Rig begin/read/apply/bake loop, generic contact locks, per-rig anatomical and mirrored-axis discovery, quaternion keying, deterministic bone analysis, and exact fixed-frame Unreal capture.

UE-MCP native animation workflow

Create quality animation from measured pose constraints, not guessed control angles. Control names, local axes, palm axes, handedness, and scale are properties of the selected rig. Discover them again for every unfamiliar rig; never paste values from another rig or negate a left-side Euler pose to make a right-side pose.

Focused skeletal mesh weighting

Use the existing skeleton-edit actions for bone creation, removal, reparenting, and reference-pose changes. For a small, explicit skin-weight correction:

1. Call `asset(action="list_skeleton_bones", assetPath=<mesh>, includeTransforms=false)` and use the returned names exactly. 2. Call `asset(action="read_skeletal_mesh_skin_weights", assetPath=<mesh>, lodIndex=0, vertexIndices=[...])`. Keep each read to the selected source vertex IDs; the action caps a call at 256 vertices. 3. Call `asset(action="set_skeletal_mesh_skin_weights", assetPath=<mesh>, lodIndex=0, edits=[{vertexIndex, influences:[{boneName, weight}]}])` with the complete replacement influence set for every selected vertex. Inspect the returned `before` and `after`: Unreal normalizes and prunes the list, and stores source weights as uint16 values. The render buffer may quantize again to 8-bit unless the LOD enables high-precision skin weights. 4. Open the rebuilt mesh with `editor(action="open_asset", assetPath=<mesh>)` and capture the asset editor at the reference pose and useful preview poses. Re-read the same selected vertices before moving on.

The weight setter edits one existing source LOD and profile, saves only when a selected value changed, and leaves all unlisted vertices, LODs, and profiles alone. It does not infer bones, fit a mesh, or auto-rig a character.

To size a physics body, socket or hit volume from the mesh, call `asset(action="read_skeletal_mesh_bone_vertex_bounds", assetPath=<mesh>)`. Each bone's `boneSpace` box is its dominant vertices in the bone's own bind-pose frame, the frame a physics body on that bone uses; `componentSpace` is the same set in the mesh's bind pose. Pass `boneNames` to limit the report, or `minWeight` to count a vertex for every bone weighing at least that much.

Required loop

1. Call `project(action="get_status")`; verify the intended project and editor. 2. Establish the character's authoring baseline before editing clips. Search for a Control Rig already bound to the target mesh/skeleton and inspect it with `read_control_rig_hierarchy` and `read_control_rig_graph`. It must have the controls, Forward Solve, and Backward Solve required for the intended edits. If the project or character has no suitable rig, create one first with the bundled Epic 5.8 controlrig actions (`epic_create`, `epic_import_bones_from_asset`, `epic_add_control`, deliberate Forward Solve nodes/links, and `epic_add_backward_solve_graph`), then save the exact rig with `asset(epic_save_assets)`. `epic_create` alone creates no imported bones, authored controls, or solver wiring. Run an unchanged source-to-controls-to-bones round trip on the exact production mesh. Do not begin production work on an unverified or merely name-compatible rig. 3. Resolve the source AnimSequence, mesh, skeleton, verified Control Rig, and frame rate. When IK/retarget assets are part of the job, use `read_ik_rig` and `read_ik_retargeter` first. On UE 5.8 use `configure_ik_rig` for validated roots, ancestry-valid chains, concrete goals, solver connections and effectors; use `configure_ik_retargeter` for the default op stack, source and target rig assignment to every op, auto/manual mappings, preview meshes, and a named retarget pose. Read both assets back after saving. A chain's goal string is not proof that a goal or solver exists. 4. Create a versioned session with `begin_control_rig_edit`. Use a unique LevelSequence path and `bindingTag`, an end-exclusive frame range, and `onConflict="error"`. Use `rigMode="asset"` for a project rig or `"fk"` only when generated FK controls are intentional. The source must be non-additive and mesh-compatible; flatten an additive clip against its intended base first. `layered` controls the session layer, not an additive source base. A finite non-zero source `RateScale` is compensated in Sequencer so the raw timeline maps once without modifying the source asset; zero is rejected. 5. Call `read_control_rig_edit` at rest, transitions, extrema, and end in both `local` and `global` space. Here `global` is rig/global (normally mesh component) space, not actor world space. 6. Inspect every control's `controlType`, `animatable`, and enum metadata. Write scalars with the matching `set_bool`, `set_float`, or `set_int`; enum values must come from `enumOptions`. Never write `animatable=false` controls. 7. Define anatomical component-space targets, then solve proximal to distal: shoulder/upper arm, elbow pole and bend, forearm direction, wrist, palm normal, then secondary motion. For a wave, the forearm must rise, the wrist must sit above the elbow/near the shoulder region, and the probed palm normal must face the intended viewer before wrist oscillation is added. 8. When an axis is uncertain, make an immutable probe session. Apply a small positive and negative rotation to one local axis at one fixed frame, bake, and inspect the resulting component-space shoulder/forearm/hand landmarks with `analyze_animation`. Probe the right side separately; mirrored parents or negative scale