spritecook-animate-assets

SpriteCook Animate Assets

Use this skill for animation workflows. Pair it with spritecook-workflow-essentials for credits, manifests, safe downloads, and shared defaults.

Requires: A connected SpriteCook MCP server. If disconnected, explain that connection is needed and use the host's native connection flow when authorized. Do not install software or change authentication settings as part of an art task.

Tool

Before animation, inspect the source outline and transparency. Use spritecook-polish-sprites to recover edge pixels from a preserved alpha source when useful, then animate the polished asset ID. Inspect completed animations for edge flicker; the polishing workflow can compare one cutoff across all frames of a supported animation.

animate_game_art

Animate an existing SpriteCook asset into a short pixel-art or detailed animation. The tool returns a job immediately; follow its poll.tool and poll.arguments instead of holding the request open.

Parameter	Type	Default	Description
asset_id	string (required)	-	Existing SpriteCook asset ID to animate
prompt	string (required)	-	Describe the exact motion over time. If auto_enhance_prompt=true, simple prompts like "Idle" or "Attack" are acceptable
auto_enhance_prompt	bool	true	Inspect the source asset and expand short prompts into a fuller animation prompt
edge_margin	int	6	Spacing added before animation framing. Pixel art stands on the bottom edge as a ground line, so the margin goes on the sides and top
vertical_align	string	null	Pixel art only. "center" for flying, floating or bouncing subjects, so edge_margin also leaves room below. Omit to keep the ground line
pixel	bool	null	Optional mode override. If omitted, SpriteCook infers the mode from the asset
model	string	mode default	pixel-engine-v1.1, frame-engine-v1.1, or pixel-engine-v1.5. Omit for the v1.1 default
output_frames	int	8	v1.1 uses even counts (pixel 2-16, detailed 2-24); v1.5 accepts 3-16 whole-number frames
output_format	string	"webp"	"webp", "gif", or "spritesheet"
negative_prompt	string	null	Optional motion/content exclusions. Not supported by pixel-engine-v1.5; do not send it there
matte_color	string	"#808080"	Hex matte color used before processing transparency
removebg	string	"Basic"	"None", "Basic", or "Pro". Pro adds a per-frame cost
colors	int	24	Pixel palette size, enforced on the output. Only valid when pixel=true

Animations take about 1-5 minutes. Pass a bounded wait_seconds only if the tool's schema lists it; otherwise space check_job_status calls accordingly. animate_game_art takes no project_id; move results with assign_assets_to_project when needed.

Prepare the Starting Frame

The animation model animates the input image. Treat that image as the starting frame: it should already show the pose, state, and facing needed at the start of the requested motion. A motion prompt or auto_enhance_prompt does not replace preparing the right source image.

• Inspect the source before animating. Reuse it when its starting pose fits the motion.
• When the requested state needs a different pose, first use generate_game_art with edit_asset_id to prepare that pose, or reference_asset_id to generate it from the established character. Preserve the character's design, palette, proportions, and art style.
• Inspect the prepared still, then pass its returned asset_id to animate_game_art.

Example: Sleeping Loop vs. Falling Asleep

The following illustrates how to choose a starting frame for different motions of the same character:

• For a sleeping loop, first create a still of the same character lying down or curled up, eyes closed. Then animate gentle breathing while keeping that sleeping pose. Do not use a standing, awake idle sprite as the input for this loop.
• For a falling-asleep transition, an awake starting pose can be appropriate because lying down and closing the eyes are part of the requested motion. Choose the source for the beginning of the action, not its final state.

Example: edit the idle bunny into “the same bunny curled up asleep, eyes closed, preserving its design and pixel-art style.” Inspect that still, then animate the new asset with “The sleeping bunny stays curled up with eyes closed, breathing gently in a seamless loop.”

Example: Continuous Walk Cycle

For a looping walk animation, first edit or reference the idle sprite into a mid-walk pose with the same character design and facing. Inspect that still, then animate its returned asset ID. Starting mid-stride helps keep the first frame part of the walking motion, avoiding an awkward standing idle pose each time the cycle repeats. An idle source can still be appropriate for a separate transition from standing to walking.

Example still prompt: "The same character mid-stride, one leg forward and the other back, arms in a natural walking swing, preserving the original facing, proportions, palette, and pixel-art style." Then animate with "A continuous walk cycle in place, maintaining the same facing and a steady rhythm, looping smoothly through the starting stride without stopping or returning to a standing idle pose." Inspect the loop boundary to check that the motion stays continuous.

Workflow

1. If the user already has a SpriteCook asset, inspect its starting pose. Use it directly only when that pose fits the requested motion; otherwise prepare the starting frame as described above.
2. If the user only has a local image file path, use spritecook-upload-assets to call create_asset_upload, upload the bytes, then call finalize_asset_upload.
3. If the user supplies a small data URL or raw base64 value, call import_asset first and use the returned asset_id.
4. Check the uploaded/imported image against the starting-frame guidance too. Prepare a different pose when needed, then use that prepared still's asset_id in animate_game_art.
5. Keep pixel omitted unless you need to force a mode.

The upload/import step is where the source image enters SpriteCook. It is not the animation call itself. Use MCP asset upload tools when they are available.

Consistency Rules

• Preserve one established character design across motions.
• Reuse the same asset_id for motions that share a suitable starting pose. Prepare a referenced or edited still when a motion needs a different starting state, pose, or facing, then animate that still separately.
• Keep the original character asset and record prepared pose asset IDs for reuse; avoid unrelated, unreferenced character generations.

Source Rules

• Pixel animation is the correct choice for small sources: v1.1 pixel animation accepts assets up to 256x256; v1.5 pixel animation accepts assets up to 320x320.
• Detailed animation is the correct choice for assets between 256x256 and 2048x2048.
• Do not force a sub-256 source into detailed mode.
• Source aspect ratio must be between 1:2 and 2:1.
• Keep edge_margin=6 by default. It helps prevent pixel art from crowding the canvas edge. It is a percentage, so very small sprites gain only a pixel or two; raise it for motions that reach outward, such as a lid opening or a wide swing. For a subject that leaves the ground, such as a flying bat or a bouncing slime, pass vertical_align="center" and raise edge_margin for big stretches or jumps.

Choosing an Engine

• pixel-engine-v1.1 (default) suits loops, walk cycles, and idles.
• pixel-engine-v1.5 suits precise or unusual motion and isolated subjects. It also tends to give calmer, more faithful motion on a single transparent character or prop.
• Results vary per subject. When quality matters, try both engines on the same still and keep the better one.
• Guided character runs (generate_character_animations) use v1.1 only. For v1.5, animate each motion with animate_game_art on the same still.

Output Canvas

• The output frame is usually square and padded. A non-square source is centered in a square frame (a 180x320 source returns 320x320 frames), and small sprites can be rescaled slightly. The response does not report the offset.
• To put an animation back in a scene or line it up with its still, match frame 0 against the source locally to find the offset, and check the scale.
• Frame sizes differ between jobs. For a set that must share one ground line, compute a shared frame box locally and re-place every frame.
• Frame counts can occasionally differ by one from output_frames; read frame_count from the result metadata before assuming a loop length.
• With output_format="spritesheet", sprite_url is still the animated WebP; the PNG strip is spritesheet_url.

Quality Checks

• Clean the still before animating: stray pixels on outlines, background trapped between parts, and noise get redrawn into every frame. Use spritecook-polish-sprites first.
• Below about 32 px, outlines can soften and small features such as eyes can drift between frames. Keep faces simple at that size and inspect every frame.
• Idles can flicker: isolated pixels change for one frame and change back. A calm prompt with auto_enhance_prompt=false reduces overall motion. Fix the remaining one-frame flips locally by restoring a pixel when the frames before and after it agree.
• Say what must stay still ("feet stay planted", "the face does not change") and check that it held; the engine does not always respect it.
• Check for grey or off-color specks near glows and at the feet, and for loops that don't close (compare the last frame with the first).

Animating Part of a Scene

Animating a full scene redraws the whole frame: static areas such as sky and stone shift between frames and the loop rarely closes. Animate the moving part on its own instead:

1. Edit the scene with generate_game_art(edit_asset_id=<scene>, prompt="Remove the X ...") to get a clean background plate.
2. Cut X out locally as the difference between the original and the plate, upload it, and animate that asset alone.
3. Composite the frames back onto the plate at the matched offset.

For effects that belong to the background, such as a waterfall, animate a crop of the plate with removebg="None" and edge_margin=0, then blend the moving region back with a motion mask.

Prompt Writing

• Inspect the actual source character before writing the prompt.
• For pixel art, upscale the source with nearest-neighbor to about 1024x1024 for inspection only.
• Identify visible character details first: silhouette, armor, visor, weapon, shield, pose, and facing.
• Only mention details that are actually visible in the source image.
• Write one short paragraph in plain prose, not a label or keyword list.
• Describe what moves, how it moves, what stays stable, and how visible props or weapons are used.
• Keep the motion grounded in the existing character rather than inventing new equipment or effects.
• Avoid generic prompts like idle animation unless auto_enhance_prompt=true.

Example idle prompt: The armored soldier in purple tactical gear stands in a steady combat stance, subtly bobbing up and down in a rhythmic breathing idle. His yellow visor catches the light while his rifle shifts slightly in his grip, maintaining a high state of readiness.

Example attack prompt: The armored soldier in purple tactical gear raises his rifle and fires several shots, with yellow muzzle flashes appearing at the tip of the barrel. His body recoils with each shot while his head and visor remain focused forward, maintaining a steady combat stance throughout the firing sequence.

If auto_enhance_prompt=true, simple prompts like Idle, Attack, or Walk are valid because SpriteCook can inspect the source asset and expand them automatically.

check_job_status

Use the job_id from animate_game_art with check_job_status. On success, use asset_id plus the canonical sprite_url; use spritesheet_url only when present. If the response reports warning.code="asset_output_unavailable", execute the supplied warning.recovery tool call.