Draft one animation frame (0..7) with hierarchical joint rotations.

GATE: refuses if no valid plan.json exists for this character+animation. If painted design/outfit plan exists, also requires compose_character. Optional plan_id must match the locked plan from plan_animation.

NEVER call this until plan_animation succeeded AND you showed user_facing_summary to the user (and they OK'd). Jumping straight to rotations is forbidden (e.g. a sword clip must not reuse a fist-fight plan).

DRESSED FRAMES: when design/ layers exist, the draft includes outfit layers rigid-rotated with the same pivot transforms as their parent body parts (DRAW_ORDER, draw_after, overhang preserved). No design → base only. Result includes dressed=true and design_slots when clothes were composited.

Pose model: each body part is a RIGID full-canvas layer rotated about articulation pivots (parent joints rotate children) — not freehand redraw. Use get_joint_docs for which parts each joint rotates.

rotations example: {"hip_near": -20, "knee_near": 6, "hip_far": 18, "knee_far": 14}. Joints: neck, shoulder_far, shoulder_near, elbow_far, elbow_near, hip_far, hip_near, knee_far, knee_near. Angles are absolute degrees from rest. Does not finalize — call finish_frame_animation next. For +X-facing idle: negative hip ≈ forward, positive knee ≈ flexion. Optional output_dir overrides session output root.

Blank one slot's design layer (transparent PNG) and refresh its reference.

Clear session output override; restore /output default.

Erase (transparent) a rectangle on the design layer only — never body.

Compose dressed rest = base body + design layers (required before anim).

Writes design/compose_preview.png. Uses DRAW_ORDER for body; each design export layer is inserted full after draw_after (no clip-to-body — overhang OK). GATE: call after painting layers (and preferably after plan_shading + shadow paint), BEFORE plan_animation. Soft gate: does not refuse when no shading plan exists. When design exists, build_frame_animation refuses without this compose preview — animation frames then rigid-rotate each design PNG 1:1 with its body part.

After this returns: HUMAN EDIT GATE — ask the user if they want manual pixel edits. If yes → open_pixel_editor → Apply → re-compose. If no → plan_animation.

Draw a line on design/layers/.png; refresh ref preview.

Rebuild horizontal contact sheet + looping preview GIF for an animation.

Requires finished frame_00.png … frame_07.png. Writes <animation_name>_contact_sheet.png and <animation_name>_preview.gif under anims/<animation_name>/. Preview GIF scale is LOCKED to native 90×128 — do not ask for or invent a per-clip scale. Also runs automatically when finish_frame_animation locks frame 7.

Fill an ellipse bounded by (x,y,width,height) on the design layer.

Fill body-part silhouettes onto design/layers/.png (MCP-native).

REPLACES ad-hoc Shell/PIL scripts that looped part_pixels and stamped colors. Server uses the character part map; base body is never modified.

• Omit parts/part_ids → fill this layer's body_parts (e.g. torso for torso, lower_arm_far+hand_far for lower_arm_far).

• parts: names like "torso", "head" (see get_part_ids).

• part_ids: integer ids from get_part_ids.

• color: hex / [r,g,b,a] for all selected parts.

• part_colors: optional {part_name: color} overrides (e.g. darker far legs).

Flat local fill only — do NOT bake underside shading here; use plan_shading + paint_* after outfit paint. Then add details with fill_rect / draw_line / paint_pixels (belt, cross, nasal bar, plates). Overhang: paint outside silhouette with those tools. FORBIDDEN: Shell python/PIL scripts or external image generators.

Fill a rectangle on design/layers/.png; refresh body-under ref.

color: hex / [r,g,b,a] / transparent. Overhang past body OK. Prefer this or paint_from_commands for blocky pixel-art clothing shapes.

Lock the current draft frame as final under anims/<animation_name>/.

GATE: refuses without a valid plan.json (same as build_frame_animation). Never finalize frames until plan_animation was called and the user saw user_facing_summary. Optional plan_id must match the stored plan.

Writes frame_XX.png + poses/frame_XX.json. When frame 7 finishes (all frames present), also writes <animation_name>_contact_sheet.png and <animation_name>_preview.gif. Repeat build→finish for frames 0..7.

Flood-fill connected pixels on the design layer from (x,y).

Optional. Do NOT flood the entire body silhouette as the sole outfit design — prefer fill_rect / paint_pixels / paint_from_commands for shapes. Large fills return a warning field.

Author shared naked side-view idle as full separate layers + composed previews.

Imports user-authored 90x128 masks from spritemcp/base/ into output_dir/base_idle_90x128/. Prefer generate_character for named chars.

Copy the SHARED naked side-view armature into a named character folder.

All characters share the same authored 90x128 base idle + pivots; do not invent a per-style skeleton. Writes <output_root>/characters//base/ (part map, layers, silhouette, pivots, previews). Optional output_dir overrides the session root from set_output_root. Call once before plan_outfit / animation.

OPTIONAL import/finalize: ensure design layer + refresh body-under ref.

Preferred flow paints with MCP tools (paint_pixels, fill_rect, paint_from_commands, …) which already write design/layers/.png and refresh refs. Use this to import an existing RGBA PNG via design_image_path, or re-sync refs. Does not clip to body alpha.

GATE: requires plan_outfit. Never use Shell/PIL or GenerateImage to create the layer — use MCP paint tools instead.

Compute articulation pivots on the shared base idle map.

Prefer generate_character for named chars.

Read the locked plan.json for a character animation.

Use before build_frame_animation if you need the plan_id or to re-show user_facing_summary. Errors if plan_animation was never called.

Active output root, style ref, and common subdirs.

Default is /output/ (agent/MCP working directory). Optional SPRITE_GEN_OUTPUT_ROOT env seeds the session at start. Call set_output_root(path) or pass output_dir on write tools to redirect. Characters live under <output_root>/characters//{base,design,anims}.

Side-view compose order: far limbs, torso/head, near legs, near arms.

Number of frames per character animation (always 8; indices 0..7).

Joint name, parent, child, and which parts each joint rotates.

Hierarchical joint specs: name, parent part, child part.

Sample a region of design/layers/.png for read-modify workflows.

Returns pixels as [{x,y,rgba:[r,g,b,a]}, ...]. Caps response size; use a smaller region or opaque_only=true. Does not modify the layer.

Read the locked design/plan.json for a character outfit.

Return the absolute output root currently in effect (session or default).

Stable part name → integer id map for the base idle template.

Local flat color → one-step-darker shadow roles (style-lock shading).

Example: off_white cloth → shadow_beige underside. Use these roles / hex values with paint_* after plan_shading. No soft gradients.

Read the locked design/shading_plan.json for a character.

Permanent view + layering rules (side profile; far behind, near in front).

List design layers (10 export names), parent/body parts, paint status, paths.

allow_overhang is always true (body is not a clip).

Structural design layers = the 10 EXPORT_LAYER_NAMES (no style presets).

Same names as base/layers/: upper_arm_far, lower_arm_far, upper_leg_far, lower_leg_far, torso, head, upper_leg_near, lower_leg_near, upper_arm_near, lower_arm_near (lower_* includes hand/foot). Each layer has a single pose parent and body_parts for paint/ref underlay. Conceptual notes (jingasa/do/hakama) map onto these keys — paint targets are always the 10 layer files. Every layer allows overhang.

Return every tool name registered on this live MCP process.

Cold-start check: expected_tool_count=45 and must include plan_outfit, plan_shading, compose_character, open_pixel_editor, fill_parts_on_slot, paint_pixels, fill_rect, set_output_root, etc. If Cursor shows ~28 tools or paint_* are missing from the agent catalog, restart SpriteMCP — do not fall back to Shell/API/GenerateImage.

Open the local manual pixel editor for design layers (human edit gate).

Call AFTER compose_character when the user wants to edit pixels by hand. Opens a small localhost web UI (pencil / eyedropper / eraser) for all 10 EXPORT_LAYER_NAMES. Apply writes design/layers/.png only — never base/. After the user clicks Apply, re-run compose_character before plan_animation. Resolves paths via session output_root / output_dir.

Batch paint commands on one slot (single save + ref refresh).

Each command: {op, ...} with op in fill_parts_on_slot|paint_pixels| fill_rect|clear_rect|stroke_rect|draw_line|fill_ellipse|flood_fill. Preferred for multi-step pixel-art (silhouette + belt/cross details). FORBIDDEN: Shell/PIL or external generators.

Paint individual pixels onto design/layers/.png (REQUIRED paint path).

Each item: {x, y, color} where color is "#RRGGBB" / "#RRGGBBAA" / [r,g,b,a] / "transparent". Canvas coords match the character (body ref). Writes the design layer only; refreshes refs/_ref.png. Read preview_paths after. FORBIDDEN alternatives: Shell/PIL, GenerateImage.

REQUIRED before any frames: lock a reasoned animation plan.

YOU (the agent) must author the plan — this tool validates and stores it. Do NOT jump to joint rotations. Do NOT reuse an unrelated clip's plan (e.g. a sword cut must not copy a bare-knuckle fight).

Required plan keys:

• beats: list of exactly 8 objects {frame_index: 0..7, pose_description: str, primary_joints: [joint names]}

• silhouette_story: short paragraph describing how the clip reads to a viewer

• differs_from: map {other_anim_name: explanation} (or list of {name, difference}) — must cover existing sibling clips / contrast_with

• weapon_or_style_notes: e.g. overhead sword cut vs jab/punch fight

Returns plan_id + user_facing_summary. You MUST show user_facing_summary to the user and wait for confirmation before build_frame_animation. next_step always says: show summary, then build frames.

REQUIRED before painting clothes: lock an outfit plan from a free brief.

YOU (the agent) author the plan from brief (e.g. "samurai") — no hardcoded style tables. Do NOT invent if-samurai code paths.

Required plan keys:

• overall_look: short paragraph of the dressed silhouette (may note overhang such as helmet bulk or hat brim past the head)

• slots: object with ALL 10 EXPORT_LAYER_NAMES — upper_arm_far, lower_arm_far, upper_leg_far, lower_leg_far, torso, head, upper_leg_near, lower_leg_near, upper_arm_near, lower_arm_near — each {skip: bool, visual_notes: str}. Conceptual vocabulary (jingasa, do, hakama, boots, gloves) belongs in notes; paint keys are the layers. lower_* includes hand/foot (gloves/boots paint there).

Overhang rule: clothing MAY extend outside body silhouette margins; parent body parts are alignment/proportion reference, NOT a hard clip. Keep proportions sensible (not absurd scale).

Saves characters//design/plan.json. Returns plan_id + user_facing_summary — SHOW the summary to the user before painting. Next: prepare_outfit_slot_reference → MCP paint tools (flat local colors; do NOT bake shading in fill_parts_on_slot) → recommended plan_shading → shadow paint → compose_character. FORBIDDEN: Shell/PIL scripts or external image generators.

RECOMMENDED after flat outfit paint: lock where hard shadows go.

YOU (the agent) author the plan — this tool validates and stores it. Soft gate: compose_character does NOT refuse without shading, but MCP SOP expects plan_shading → paint shadows → compose (or re-compose).

Required plan keys:

• light_direction: e.g. "top-front / +X-up"

• rules: must include "one_step_darker" and "no_gradients"

• layers: object with ALL 10 EXPORT_LAYER_NAMES, each {skip: bool, shade_notes: str, strokes?: [{region?, intent, color_role?}]} Optional overall_notes. Alternate: flat strokes list with layer + intent.

Style: one darker step of local color (see get_shade_palette); hard 1–2px bands; shade design layers only; never rewrite base; do not strip eyes.

Saves design/shading_plan.json. Returns plan_id + user_facing_summary — SHOW the summary and wait for OK before painting shadows with paint_*.

MANDATORY before/during paint: body part layer(s) UNDER + design on TOP.

slot is one of the 10 export layer names (same as base/layers/). Writes design/refs/_ref.png. That layer's body_parts are the underlay (alignment / proportions only — NOT a clip mask); design/layers/.png is the transparent paint target. Clothing MAY overhang the body silhouette if scale stays sensible. Example: prepare_outfit_slot_reference("", "torso") → refs/torso_ref.png. Then paint with MCP fill_parts_on_slot (silhouette) + fill_rect / draw_line / paint_pixels (details) / paint_from_commands (never Shell/PIL or GenerateImage).

Paint the tiny palette test pattern under output_dir/demo/.

Set where character/outfit/anim output is written for this MCP session.

Resolves to an absolute path and creates the directory. Persists until the MCP process exits or clear_output_root(). Does NOT move existing files — only redirects new writes. Per-call output_dir still overrides. Example: set_output_root("C:/Users/me/game/assets/art/sprites"). When unset, tools use /output/.

Alias for paint_pixels — set {x,y,color} on the design layer.

Upscale the style-ref PNG onto a visible per-pixel grid.

Writes under output_dir/reference_grid/. Returns path strings for grid PNGs.

Stroke (outline) a rectangle on the outfit design layer.

Propose underside / far-limb shade band hints (does NOT write pixels).

Uses design-layer alpha when painted, else body-part geometry. Returns structured regions (layer, bbox, sample_pixels, reason). Agent filters into plan_shading, then paints with MCP tools. Optional helper before plan_shading.