Animate through MCP

Connect your chat using MCP connections, then include the service ID and project name or ID in each request. These examples use service 42; replace it with your service ID.

Complete prompt: animate an uploaded image

Attach your static reference image to the AI chat, then paste this prompt. Replace the service ID and action; for an object, describe its moving parts and intended motion (for example, a chest opening or a flag waving). The defaults below can also be changed.

Use the lunarPaperPixelArt MCP for service 42. Use my uploaded image as the visual reference and create a pixel-art animation of this action: WALK.

Create a new project, preserving the subject's identity, proportions, colors, clothing and important details. Default to a 128×128 transparent canvas and a 16-frame loop at 80 ms per frame. Keep the whole subject inside the canvas. Adapt the motion to the reference's viewing angle. For a one-shot action, use a deliberate ending instead of forcing a loop.

1. Read action_guide and check which tools are callable. Inspect the reference and plan the key poses, moving parts, joints, occlusion order and contact points. If the attachment is inaccessible, ask me to attach it again.

2. Build clean, separate source parts on hidden layers. Use silhouette masks, not rectangular cutouts containing neighboring body parts. In particular, the torso must not retain pixels belonging to moving thighs, knees, boots or arms. Preview every source part alone before posing it. Use import_png when PNG bytes are available, choosing alpha and palette handling explicitly.

3. Save a persistent rig with setRig. Paint plausible replacement pixels for surfaces hidden in the reference. Use captureRigVariant to create editable replacement cels and select variantId for the relevant poses. Keep manual paint repairs on the cleanup layer and removal corrections on the erase mask so renderRig preserves them.

4. Establish the key poses first. For a walk, include contact, down, passing and up poses for both sides, with opposing arm swing and restrained body motion. Use linked parent anchors and planted-foot constraints where appropriate. Set the back-to-front order for each pose and keep joints connected. Account for stance contact and the loop reset when judging foot movement.

5. Complete the intervening frames and set every frame's duration explicitly, including frame 0. Retain separate posed layers where useful for analysis. Inspect composeParts occlusion and clipping reports; correct bad masks or joins rather than relying on clipping to hide them.

6. Show normal-speed and quarter-speed previews, plus onion skins and a contact sheet. Analyze the posed character layers for disconnected pieces, unwanted torso/limb coverage, below-sole pixels and foot drift. Inspect flagged frames visually: some overlap is intentional. Fix visible defects and review the transition from the last frame back to the first.

Read the latest updatedAt before each edit and retain undoHistoryId. If a tool is unavailable or a save fails, explain exactly what succeeded and what remains. Finish with the saved project link, animation preview, frame count and timing, and any remaining visual limitations.

The attachment is a reference supplied to the chat; it is not automatically uploaded to the MCP. The client must prepare pixel data or PNG bytes for editing tools. A single view cannot reveal every hidden surface, so replacement details are inferred and should be reviewed.

Edit a saved rig in the studio

Click the Rig editor joint-figure button in the top toolbar. Tool Options hides while the rig panel is open and returns when you close it. The drawing tool stays selected. Use Widen rig panel in the panel header for more space; use Narrow rig panel to return to the compact width. Closing and reopening retains unapplied rig edits.

Start with one source layer per movable body part. A flat image must first be separated into parts; creating a rig does not automatically identify anatomy. Choose the first Source layer inside the panel and select Create rig.

Parts — open Add selected layer as part, choose another source layer inside the panel, and add it. Choose a part, drag its pink joint to the hinge or enter coordinates, then choose its parent and attachment point. These source settings affect every frame. Edit source mask lets you include or exclude individual pixels; check the torso for borrowed limb pixels. Move backward and Move forward change global part order.
Pose — select a timeline frame, then change the part’s position or rotation. The preview updates before saving. In the wide panel, the preview and pose fields sit side by side. Replacement drawings and walking controls are available here as expandable sections.
Render — inspect joint markers and optional Part ownership colors, then render the current frame or all frames. Play the timeline to check motion. Paint cleanup layer preserves corrections above the rendered parts; Paint erase mask marks generated pixels to remove on the next render. Both correction layers survive rendering; direct edits to generated part layers are replaced.

Apply rig changes saves the rig settings without drawing the poses onto animation layers. Render current frame and Render all frames apply the settings and update the artwork. The rig is saved with the project and included in Undo/history snapshots.

For alternate drawings, expand Replacement cel for this frame in the Pose step. Enter a replacement name and select Create editable replacement, choose it in the selector, then use Paint source on canvas. Edit with normal drawing tools and align its joint in the source preview to preserve attachments. Each part supports up to 16 replacements.

The rig stores source and pose frame IDs, so reordering frames preserves references. Deleting a source frame or source layer requires repairing its references. Removed parts retain their previous output as hidden layers. Ordinary output layers use the project’s global part order; different depth order per pose still requires manual corrections or separate projects.

Walking controls

Select a boot linked to a shin and thigh, then open Walking controls and choose Use selected part as foot. Measure the ground target and sole, heel, and toe anchors. Configure the phase offset, knee bend direction, and knee angle limits; 180 degrees is straight. Add the other leg, usually with an offset of 0.5.

Set speed in pixels per second, stance fraction, and foot lift. Move across the canvas translates root parts forward; otherwise the feet move backward during stance for an in-place cycle. Generate walk poses creates saved poses for the timeline; rendering then checks reach and knee limits. Invalid targets are rejected rather than forcing a folded leg. The generator provides an initial cycle: inspect heel/toe transitions, redraw exposed surfaces, add body and arm motion, and check the loop seam. A travelling cycle does not automatically reset its root position seamlessly.

Persistent rig tools and actions

Call get_rig to retrieve the complete definition and current revision. Use preview_rig with frameId and optional ownership: true for a read-only preview, part-color legend, joint coordinates, knee angles, and overlap diagnostics. get_project lists frame IDs.

The following payload is an action inside apply_actions. Replace the source layer and frame IDs with actual IDs. New output and cleanup layer IDs must be unique and must not claim existing artwork layers.

{
  "action": "setRig",
  "rig": {
    "version": 1,
    "id": "character",
    "name": "Character",
    "cleanupLayerId": "rig-cleanup",
    "eraseLayerId": "rig-erase",
    "parts": [{
      "id": "torso",
      "name": "Torso",
      "sourceLayerId": "existing-source-layer-id",
      "sourceFrameId": "existing-frame-id",
      "pivot": { "x": 64, "y": 60 },
      "outputLayerId": "rig-torso",
      "variants": []
    }],
    "poses": [{
      "frameId": "existing-frame-id",
      "parts": [{ "id": "torso", "x": 64, "y": 60, "rotation": 0 }]
    }]
  }
}

setRig stores the definition and prepares separate output and cleanup layers. Keep the rig ID, cleanup IDs, and part IDs stable when updating it. The definition is limited to 500 KB, 32 parts, and 64 poses; project layer limits still apply.
renderRig accepts frameIds; omission renders frames with saved poses. It updates generated cels while preserving cleanup paint and erase masks.
captureRigVariant takes partId, a new variantId, a new source layerId, an existing frameId, and a name. It copies the original part source to an editable hidden layer. Edit that cel, align its pivot, and set variantId on the desired pose part through setRig.
generateRigWalk takes 4–64 frameIds, speed, stance, lift, travel, and legs. A leg specifies rootId, jointId, endId, target, endAnchor, optional heel/toe anchors, phaseOffset, bend, and minKneeAngle/maxKneeAngle. Optional heelRotation and toeRotation control contact angles. Follow generation with preview_rig or renderRig to validate reach and knee limits.

Use the saved rig in service 42. Inspect its masks and ownership preview first. Create a replacement cel for the bent knee, align its joint, and use it in the passing poses. Preserve my cleanup paint and erase masks. Generate revised walk poses with knee limits and staggered stance phases, then preview them before rendering. Keep the undo checkpoint and report any unreachable foot targets.

Review the current motion

Call action_guide to check serverVersion and availableTools. If the guide lists a tool that your chat cannot call, refresh the client’s tool list or reconnect and start a fresh chat. An older chat may retain the tool catalog from before a server update.

Use the Lunar Paper Pixel Art MCP for service 42. Open my "Ember Guard" project, read its latest state, and show a looping preview at quarter speed. Show onion skins for the passing poses and a contact sheet. Describe where knees, boots, or armor lose their shape before editing.

preview_animation returns a looping GIF using frame durations. Set speed to 0.25 for quarter speed, and onionSkin to true to add ghosts of adjacent timeline frames. Red represents the preceding frame; blue represents the next frame. preview_frame also accepts onionSkin. GIF delays are rounded to 10 ms. A client may show only the first GIF frame; use the contact sheet and individual PNG previews when that happens.

Build the character from parts

Flattened artwork has no information about which pixels belong to a thigh, boot, or armor flap. The chat must first isolate those shapes and draw any joint areas hidden in the reference pose. A transform cannot reconstruct missing anatomy.

Preview each source separately with preview_frame and layerIds: ["source-layer-id"]. This includes hidden sources without changing saved visibility. A rectangular torso selection can contain thighs, knee armor, or arm pixels. When drawn above the moving limbs, those leftover pixels cover the limbs’ new positions. Remove them from the torso’s source or retain only the torso silhouette with mask, and assign the removed shapes to their corresponding moving parts.

Before posing the character in service 42, show each source part alone. Check that the torso contains no thigh, knee, boot, or moving arm pixels. Use silhouette masks rather than rectangular crops, and paint the hidden hip and shoulder areas. Keep the separated sources so we can revise them after reviewing the motion.

In service 42, build the walk using separate source layers for the near and far thighs, shins, boots, torso, and armor panels. Keep those source layers hidden. Use composeParts to place the parts around knee, ankle, and hip pivots. Define the back-to-front order for every pose, and redraw hidden joints where needed. Keep both boots readable during the passing poses. Preview the loop at quarter speed after each small edit and retain undoHistoryId.

Call action_guide for the current action contract. composeParts uses source cels already in the project and writes ordinary pixels to an output layer. It does not add a persistent skeleton to the editor. You can reapply revised poses from the same source art without repeatedly rotating the previously rendered result.

Example payload inside apply_actions, after discovering the actual layer IDs:

{
  "action": "composeParts",
  "layerId": "output-layer-id",
  "clear": true,
  "poses": [
    {
      "frameIndex": 0,
      "parts": [
        {
          "sourceLayerId": "far-shin-layer-id",
          "sourceFrameIndex": 0,
          "pivot": { "x": 50, "y": 78 },
          "x": 54,
          "y": 80,
          "rotation": -15
        },
        {
          "sourceLayerId": "near-boot-layer-id",
          "sourceFrameIndex": 0,
          "pivot": { "x": 62, "y": 104 },
          "x": 64,
          "y": 105,
          "rotation": 10
        }
      ]
    }
  ]
}

Parts are listed from back to front; later parts cover earlier ones. pivot uses source canvas coordinates, while x and y place that pivot in the destination. Positive rotation is clockwise. Optional flipX and flipY mirror around the pivot. Sampling uses nearest neighbors to keep palette colors unchanged.

An optional mask is an array of { "x": 0, "y": 0 } coordinates retaining pixels in the source cel. clipMask retains coordinates in the destination. Omit masks to use the entire part. This lets a chat isolate parts from an existing cel or restrict where a posed part appears. Source cels are captured before any pose is written. clear defaults to true, replacing the output cel for each selected pose.

Use setLayerVisibility to hide source layers. reorderLayers changes the project’s global layer order; composeParts gives each pose its own part order. To analyze intersections between parts, render them to separate output layers before flattening.

Link joints and plant a foot

Give each part an id. A child specifies parentId and parentAnchor, a coordinate in its parent’s source canvas. The child’s own pivot attaches to that point. Its rotation is relative to the parent’s rotation; omit child x and y. Part order still controls which draws in front, independently of parent links.

Place this example pose in the poses array of composeParts. Substitute your actual layer IDs and measured source coordinates:

{
  "frameIndex": 0,
  "parts": [
    {
      "id": "thigh", "sourceLayerId": "thigh-source",
      "pivot": { "x": 60, "y": 60 }, "x": 62, "y": 62
    },
    {
      "id": "shin", "sourceLayerId": "shin-source",
      "parentId": "thigh", "parentAnchor": { "x": 60, "y": 82 },
      "pivot": { "x": 60, "y": 82 }
    },
    {
      "id": "boot", "sourceLayerId": "boot-source",
      "parentId": "shin", "parentAnchor": { "x": 60, "y": 104 },
      "pivot": { "x": 60, "y": 104 }
    }
  ],
  "plantedFeet": [{
    "rootId": "thigh", "jointId": "shin", "endId": "boot",
    "endAnchor": { "x": 62, "y": 112 },
    "target": { "x": 64, "y": 112 },
    "endRotation": 0, "bend": 1, "floorY": 112
  }]
}

Each plant constraint keeps the hip fixed, solves the thigh and shin angles, and puts the boot’s endAnchor at target. endRotation is an absolute angle in degrees. bend chooses one of the two knee directions (1 or -1). Unreachable targets are rejected; move the hip or adjust the target. Up to eight independent leg chains can be constrained per pose.

Optional floorY clips pixels of the three constrained parts below that row and reports the clipped coordinates. Inspect those reports: clipping can conceal a badly shaped source. apply_actions also returns joint positions and per-part occlusions, identifying coveredPartId, coveringPartId, frame number, overlap size, and sample coordinates. Overlap is often intentional at joints and during passing poses. Inspect suspicious coverage before the output is flattened.

Link the thigh, shin and boot pivots. During each stance phase, constrain the boot's sole anchor to one ground point and retain the hip motion. Inspect clipping and torso-over-leg occlusion reports. For newly exposed areas, paint replacement pixels in the source or add a setPixels correction after composeParts. Preview the loop after each small batch.

Import PNG parts

import_png imports PNG bytes directly into one frame and layer. Supply serviceId, projectId, the latest expectedUpdatedAt, layerId, frameIndex, and pngBase64 (raw base64 or a PNG data URL). It accepts one PNG up to 256×256 and 1 MB. It does not fetch URLs or read local file paths.

Option	Behavior
`mode: "replace"`	Default. Clears the entire target cel before importing.
`mode: "overlay"`	Keeps existing pixels under transparent input.
`paletteMode: "extend"`	Default. Adds exact colors, up to the 256-color palette limit.
`paletteMode: "strict"`	Rejects colors outside the current palette.
`paletteMode: "nearest"`	Maps each color to the nearest existing RGB palette color.
`alphaMode: "threshold"`	Default. Makes alpha below `alphaThreshold` transparent and the rest opaque; threshold defaults to 128.
`alphaMode: "rejectPartial"`	Accepts fully transparent or opaque pixels and rejects partial alpha.
`alphaMode: "matte"`	Composites all input pixels onto `matteColor`, including transparent areas.
`x`, `y`, `clip`	Offset the image; out-of-bounds content is rejected unless `clip: true` crops it.

Cels store binary transparency. The response reports imported, transparent, clipped, and partial-alpha pixel counts, added palette colors, and undoHistoryId.

Import these transparent PNG parts into separate hidden source layers in service 42. Use import_png with paletteMode extend and alphaMode rejectPartial so we catch any soft edges. Show each imported part alone before linking the joints.

Check movement

Analyze my walk in service 42. Exclude background layers. Check for disconnected pieces and intersections between the leg and armor layers. Treat overlap reports as hints and inspect the flagged frames. For each planted foot, use its boot layer and only its stance frames; flag movement over one pixel. Show the affected frames with onion skin.

analyze_animation uses eight-neighbor pixel connectivity and pairwise layer silhouettes. For foot drift, supply footContacts, for example [{ "layerId": "near-boot-layer-id", "frames": [0, 1, 2] }]. The measurement is the movement of the bottommost pixel group’s center, relative to the first selected stance frame. Changing the sole shape can affect this measurement, so inspect each result. Backgrounds, sparks, detached accessories, and intended occlusion can all produce valid findings.

Analysis accepts up to 32 frames and 16 layers at a time. It cannot identify separate limbs within a single flattened layer or determine anatomical correctness.

findings.items contains reports with frame numbers and sample coordinates, accompanied by a total and truncation flag. Optional checks:

groundY: reports selected layers’ pixels below the ground row.
footContacts[].checkLayerIds: limits below-sole checks to selected layers, such as the matching shin. Only use stance frames. Without this option, all other analyzed layers are checked.
overlapRules: [{ "layerIds": ["torso-output", "thigh-output"], "maxPixels": 0, "allowedRegion": { "x": 50, "y": 60, "width": 16, "height": 8 } }]: allows overlap within the hip joint region and reports excess overlap outside it, including the covering layer.

Select posed output layers for these checks. Hidden source cels describe the reference pose, not the final motion. Findings are bounded to the first 100; use smaller frame selections when a result is truncated.

Remove experiments and undo

In service 42, clear the selected output layer in frames 4 and 5 so we can redraw the passing poses. Remove the final two exploratory frames. Keep the checkpoint returned by each edit. If the revised loop is worse, restore the checkpoint from before that edit.

clearFrame clears selected frames, optionally within one layerId.
deleteFrames removes selected indices and shifts later frames down.
setFrameCount can grow or shrink the timeline. Shrinking removes frames from the end.
An explicit setFrameCount duration applies to every resulting frame, including frame 0. For example, { "action": "setFrameCount", "count": 16, "duration": 62 } sets all 16 frames to 62 ms. Omitting duration preserves existing timings and gives new frames the last existing duration.
Frame removal updates animation tag ranges. The project must retain at least one frame, and locked layer pixels are protected.
Every successful MCP edit returns undoHistoryId for the state before that edit. restore_history accepts that ID as historyId and requires the latest expectedUpdatedAt. Restoring creates another checkpoint, so the restore can also be undone.

The project retains up to 50 history entries, shared with editor saves. If a checkpoint has expired, list_history shows the ones still available. When an edit conflicts, read the latest project and review its changes before retrying.