name: 2dimg2motion description: Use when a user provides one baseline image and requests game animation frames, sprite sequences, attack/walk/idle/hit/death/casting motion, transparent PNG frames, a spritesheet, keyframe prompts, or consistent whole-character pose animation.

2dimg2motion

Overview

Convert one baseline character, creature, vehicle, weapon, or prop image into a style-consistent transparent game-animation sequence. Motion artwork must be generated by the model: by default, use built-in image_gen to directly generate whole-character key poses and in-between frames.

Core principle: first analyze the baseline frame's subject, body parts, weapons, and art style; establish an identity lock; write detailed prompts for keyframes 02/05/08/11; then use image_gen to generate shared key poses and in-betweens. Do not use scripts, Pillow, canvas, SVG, or affine transforms to draw or synthesize motion artwork.

Before generating animation assets, read references/keypose-redraw.md. When designing action timing or prompt wording, also consult references/motion-prompt-patterns.md, which distills reusable patterns from the local motion/ reference library.

If project knowledge exists in img2mo-knowledge/, read img2mo-knowledge/index.md before prompt writing. Then read only the relevant knowledge files for the requested action or style: action-patterns.md, style-patterns.md, prompt-patterns.md, failures.md, or matching records in learnings.jsonl. Project knowledge is guidance, not ground truth: never let it override the current baseline identity, current user request, or hard failure constraints.

Input Contract

Collect or infer:

• baseline image and character facing direction;
• whether the baseline image has already been standardized for animation: foreground subject longest side 300-400 px, transparent action margins on all sides, no tight crop, and no huge source canvas;
• motion type, ordered beats, and loop behavior;
• preferred frame count or timing;
• canvas size, stable foot/bottom baseline, and naming prefix;
• required deliverables: keyframe prompts, sequence frames, spritesheet, contact sheet, and playback preview.

Ask only for information that materially changes the result. Default to 14 transparent RGBA frames per action with a seamless return to the source pose.

Generation Boundaries

• The default image generation capability is built-in image_gen. Unless the user explicitly requests a CLI/API path, do not switch to script-based image generation or custom SDK calls.
• Character poses in keyframes, in-betweens, and sprite strips must be directly generated by image_gen from prompts and visual references.
• Local scripts are allowed only for non-creative post-processing: copying generated images, removing chroma-key backgrounds, splitting cells, normalizing canvases, packing spritesheets, generating previews, writing manifests, and running validation.
• Do not use scripts to produce motion artwork. Do not use Pillow, OpenCV, canvas, SVG, bone slicing, rotation/scale/affine transforms, limb copy-paste, procedural interpolation, or hand-written drawing to create keyframes or in-betweens.
• If image_gen output has the wrong cell count, wrong background, or identity inconsistency, rewrite the prompt and call image_gen again. Do not "fix" it into a new pose with scripts; scripts may only clean backgrounds and organize generated images.
• In any delivery note, distinguish "model-generated content" from "local post-processing." If only a key-pose sheet is complete and the full 14 frames are not, say so explicitly.

Hard Failure Constraints

If any of the following appears, treat the batch as failed. Re-prompt and call image_gen again; do not hide the problem with post-processing:

• Weapon hand or active-limb side swap: if a sword, club, spear, staff, or similar weapon moves from the screen-left hand to the screen-right hand, or the reverse, reject the batch. Prompts must explicitly state: "the weapon always remains in the same screen-space hand; the other hand remains empty/anchoring/counterbalancing and must not hold the weapon."
• Character colors removed by chroma key: before choosing a chroma key, list the character's main colors, weapon colors, and highlight colors. The key color must not be close to subject colors. For green/blue subjects, prefer #ff00ff; for pink/purple/magenta subjects, avoid #ff00ff and prefer #00ffff or another pure color absent from the subject. If matting removes body, weapon, eyes, armor, horns, or outlines, change the key color and regenerate the source image.
• Insufficient gutters causing split-frame cuts: sprite-strip prompts must require large chroma-key gutters, centered cells, and complete weapons inside each cell. If equal-cell splitting cuts into a neighboring body, weapon, ear, horn, foot, or introduces neighboring fragments, do not deliver it. Prefer shorter batches such as 01-06 and 07-12, or regenerate with larger spacing.
• Canvas too small: normalized canvases must leave a safety margin. If a weapon tip, horn, ear, foot, tail, or body part touches the edge or is cropped in the contact sheet, enlarge the final canvas or regenerate.
• Unstandardized baseline frame: if the source image is very large, tightly cropped around the character, has no transparent action margin, or cannot contain the likely attack/walk stretch without overlap, standardize it before generation with scripts/standardize_baseline.py. Do not start image generation from a huge or edge-hugging source; it causes crowded source sheets, clipped cells, forced local resizing, scale popping, and long runtimes.
• Scale popping or drifting centers: if the model draws some cells as visibly smaller/larger variants, or local processing needs per-frame scale/center fitting to make frames align, reject the source batch. Regenerate with stronger same-size prompts or use shorter batches. If a pose needs more room, enlarge the final canvas instead of shrinking that pose or the whole sequence.
• Output directory pollution: the final output directory may contain only contract files. Model source images, alpha sources, failed drafts, temporary splits, and debug images belong in a temporary directory and must be deleted after delivery. Do not leave *-imagegen-* intermediates in the final output unless the user explicitly requests process drafts.
• Validation passes but visuals fail: deterministic validation is only a structural gate. After OK, inspect contact-sheet.png and preview.gif. If there is hand swapping, slicing, missing colors, fragments, scale popping, or unreadable motion, do not claim completion.

Limb-Side and Topology Lock

Before designing poses, establish limb identity:

• Do not infer anatomical left/right from an unqualified "left" or "right" when the source faces front, back, or is mirrored. Unless context is explicit, ask whether the user means screen space or character anatomy.
• Normalize all sides to screen-left or screen-right. If anatomy matters, record both forms, such as character-left (screen-right).
• Record the activeLimb, its activeShoulder, the opposite anchorLimb, and any distinctive markings or spikes that identify both sides.
• For weapon actions, record activeWeapon, weaponHand, emptyHand, and screen-space side. Do not write only "right hand swings sword" or "left hand swings sword"; write locks such as screen-right sword hand remains the sword hand in every frame; screen-left hand remains empty/counterbalance.
• In every key pose and in-between, even when the active limb crosses the body centerline, it must remain connected to the same shoulder.
• The anchor limb must remain visible and attached to its original shoulder as a continuity reference. Do not let it lift, disappear, or become the attacking limb.
• Use normalized side names in image-generation prompts and contact-sheet review. Before generation, explicitly state the topology lock, for example active=screen-left; anchor=screen-right.
• Persist coordinateSpace, activeLimb, activeShoulder, and anchorLimb in manifest.json. Do not mix anatomical and screen-space naming inside one animation.

Weapon, Prop, Accessory, and Creature Locks

Before prompt writing, classify non-body elements and non-human motion drivers:

• Record activeWeapon, carriedProp, passiveAccessory, and detachedProp separately. A held torch, shield, embedded arrow, helmet crest, and thrown weapon need different rules.
• Every weapon or carried prop must have one owner: weaponHand, propHand, mouth, tail, harness, or body socket. It must not switch sides, duplicate, float, or detach unless a release beat explicitly says so.
• Passive accessories follow their attachment surface. Embedded swords/arrows, shell spikes, antlers, crystals, capes, and belt items may lag or tilt, but they must not become active limbs or attacking weapons by accident.
• For non-humanoid creatures, record activeFeature and anchorSurface instead of forcing activeLimb: horn, jaw, tail, branch, shell, belly mass, root feet, bottom puddle, or whole-body charge.
• Long weapons, tails, antlers, branches, banners, and wings require larger gutters or a larger final canvas. Do not shrink the character to fit a wide pose.

Default 14-Frame Plan

Use six immutable anchors in this order: 00 -> 02 -> 05 -> 08 -> 11 -> 13.

Generate exactly four keyframes at indices 02, 05, 08, and 11. Save exact copies of those images into both keyframe/ and the matching positions in fullframe/. Never redraw keyframes during the in-between stage. Insert 1 frame near each baseline endpoint and 2 frames between each pair of generated keyframes.

Persist frameCount: 14, keyframeIndices: [2, 5, 8, 11], anchorIndices: [0, 2, 5, 8, 11, 13], and segmentInsertions: [1, 2, 2, 2, 1] in manifest.json. Persist previewBackground: "#FFFFFF" in manifest.json.

Motion Library Patterns

The local motion/ library shows these practical timing patterns:

• Attacks: usually guard -> anticipation -> acceleration -> contact -> contact hold/follow-through -> recovery. The contact pose should be the clearest silhouette. Attacks commonly widen to about 1.5x-1.6x the neutral width while keeping character scale stable.
• Idle: small settle/rise/settle breathing loop, usually around 5% width/height variation.
• Move/walk: contact/down/passing/up/opposite-contact, with clear feet alternation, small body bob, and stable mass.
• Block: compact guard raise/hold/return, fixed feet, little scale change.
• Hit/suffer: impact/recoil/squash/recovery; face and accessories can exaggerate, but identity stays locked.
• Death: imbalance/fall/impact/rest; do not force the final frame to loop to neutral.
• Born/spawn: small seed/egg/portal/curled silhouette unfolds into full identity; large size change is valid only for spawn-like actions.
• Skill/cast: anticipation/charge/peak cast/hold/recovery; detached effects should be separate overlays unless explicitly requested in the character sheet.

In every pose-sheet prompt, include the stable canvas rules:

Same apparent character size in every cell.
Same foot/bottom baseline in every cell.
Body center stays near the same cell center except for intentional lunges.
Complete character, weapons, horns, ears, tails, claws, and effects remain inside the cell.
Allow the silhouette to widen for attacks, but do not scale the character smaller or larger.

For local post-processing, use one shared scale and one fixed foot/bottom baseline. Never auto-fit each frame independently. If a generated pose needs more horizontal or vertical room, enlarge the output canvas instead of shrinking the character.

Action Prompt Templates

Use these beat templates when the user gives only a broad action request:

Workflow

0. Audit and Standardize the Baseline Frame

For the /img2mo-std baseline standardization sub-skill and command reference, read skills/img2mo-std/SKILL.md.

When the user invokes /img2mo-std 图片名/位置, resolve the image path, run the standardization step, and use the standardized output as the baseline for later animation generation.

Before baseline analysis or any image_gen call, check whether the input frame is a usable animation baseline:

• foreground subject longest side should be about 300-400 px;
• transparent or removable background should surround the subject;
• every side should have enough action margin for walk bob, weapon arcs, hair, horns, cloak, tail, wings, or props;
• long weapons, capes, tails, antlers, banners, and large attack silhouettes need extra horizontal/vertical margin;
• source images much larger than this range should be standardized to reduce generation time and reduce model scale drift.

Use the bundled script when the image is too large, too tight, or has a white background:

python scripts\standardize_baseline.py sample\s7.png

Default output is sample/<name>-standard.png. Use that standardized file as the animation baseline unless the user explicitly wants to keep the original. The script trims transparent/near-white background, resizes the visible subject so its longest side is 360 px by default, preserves aspect ratio, and adds transparent margins on all sides.

Useful options:

python scripts\standardize_baseline.py sample\s7.png --subject-max 380 --margin-ratio 0.8
python scripts\standardize_baseline.py sample\s7.png --output sample\s7-standard.png
python scripts\standardize_baseline.py sample\s7.png --check-only

Treat the standardized baseline as the 00/13 source for validation. Keep the original file unchanged unless the user explicitly asks to overwrite it.

0.5. Load Project Knowledge

Before baseline analysis and prompt writing, check whether img2mo-knowledge/index.md exists.

If it exists:

• read img2mo-knowledge/index.md;
• for the requested action type, read img2mo-knowledge/action-patterns.md if present;
• for style-sensitive requests, read img2mo-knowledge/style-patterns.md if present;
• before writing prompts, read img2mo-knowledge/prompt-patterns.md if present;
• before validation/rejection decisions, read img2mo-knowledge/failures.md if present;
• search img2mo-knowledge/learnings.jsonl only for matching action types, character styles, or source tags when detailed examples are useful.

Use learned knowledge to improve beat choices, prompt clauses, canvas margins, style wording, and rejection checks. Do not copy old prompts blindly and do not reuse old generated output unless the user explicitly asks.

1. Analyze the Baseline Frame and Establish the Identity Lock

Inspect the source image at original resolution. Before generating images, write a reusable baseline-frame analysis that records every invariant that must survive redraw:

• subject type: what the character, creature, vehicle, weapon, or prop is, and how its overall silhouette reads;
• body structure: count, position, proportion, and facing of head, torso, limbs, wings, tail, claws, horns, shell, exoskeleton, etc.;
• face, expression, silhouette, proportions, and facing;
• palette, outline weight, shading style, material treatment, pixel/hand-drawn/cartoon/realistic style;
• limb count, hand order, clothing, armor, markings, and accessories;
• shoulder-to-limb topology, active-side mapping, anchor limb, and side-specific markings;
• weapon shape, grip, length, emblem, and distinctive small details.

Record uncertain or occluded regions explicitly. Use this analysis as the fixed identity block for all later keyframe prompts. Keep the source image visible during every generation and correction pass.

2. Design Motion Beats and Key Poses

Before generating images, choose readable motion beats:

• idle: settle -> rise -> settle;
• walk: contact -> down -> passing/step-through -> up -> opposite contact;
• attack: guard -> anticipation -> acceleration -> contact -> contact hold -> recovery;
• hit: contact -> recoil -> settle;
• death: imbalance -> collapse -> impact -> rest.

Choose exactly four generated key poses for indices 02, 05, 08, and 11. For attacks, use anticipation, acceleration/contact, contact hold/follow-through, and recovery. Frames 00 and 13 provide the neutral guard or baseline pose. The contact pose should have the clearest silhouette.

For one-limb actions, describe both sides in every beat: how the active limb remains connected to the locked shoulder, and how the anchor limb stays fixed. Track the full shoulder-to-hand trajectory, not only the hand tip.

3. Write the Four Keyframe Prompts

Before calling built-in image_gen, write detailed prompt briefs for keyframes 02, 05, 08, and 11. Each prompt must derive from the same baseline-frame analysis and must not reinterpret the character identity on the fly.

Prompts are not the only input. The four keyframe prompts are pose specifications, not the identity source. Do not let the model redraw keyframes independently from text alone; generation must also reference the baseline image as the visual identity anchor. If the current UI or tool cannot pass the baseline image as a reference input to image_gen, the prompt must request a reference identity cell in the output pose sheet: the first cell reproduces the baseline appearance for identity comparison only, and the next four cells are 02/05/08/11. Discard the reference cell during splitting; it is not an animation frame.

Each keyframe prompt must include:

• fixed identity block: subject, body parts, weapons, proportions, silhouette, palette, outline, material, art style, and details that must not change;
• current pose block: the action beat for that index, center of mass, body lean, head direction, active and anchor limb positions, weapon trajectory, contact point, and clear silhouette;
• continuity block: motion direction from the previous anchor to the next anchor, foot/bottom baseline, and relationship to the 00/13 loop;
• canvas and background block: complete character, equal cells, stable scale, generous safety margin, flat chroma-key background, no labels/borders/shadows/effects.

If a prompt cannot clearly explain how a body part, weapon, side marker, or art-style constraint inherits from the baseline frame, do not generate images yet; return to the baseline analysis and fill the gap. The prompt stage designs keyframes only, not in-betweens.

4. Generate One Coherent Key-Pose Sheet

Required sub-skill: use built-in image_gen for whole-character key-pose redraw.

Use the four keyframe prompts from step 3 plus the baseline visual reference to generate all key poses at once in one evenly divided pose sheet. Redraw the complete character in every cell. Natural squash/stretch, perspective, foreshortening, overlap, and newly visible surfaces are allowed while preserving the identity lock.

Do not generate 02, 05, 08, and 11 in four independent calls. Independent calls make the model resample the character every time, commonly causing small drift in the face, eyes, weapon length, armor patterns, outline weight, body proportions, or colors. Unless the user explicitly requests only a single concept draft, key poses must be generated in one shared sheet with the same baseline image, identity block, chroma key, canvas, and gutter constraints.

The pose-sheet prompt must explicitly include identity-alignment rules:

• use the provided baseline image as the visual identity source, not as loose inspiration;
• preserve the exact silhouette language, color palette, outline weight, facial features, markings, weapon size, and body-part count from the baseline;
• only change pose, weight, limb angles, squash/stretch, and motion timing;
• do not redesign, simplify, beautify, add details, remove details, change proportions, or reinterpret the character.

Generating the key-pose sheet must call image_gen. Do not use scripts to rotate limbs, move local cutouts, or procedurally deform the baseline into fake key poses.

The key-pose sheet must have enough gutters. The prompt must require: exactly 4 separate full-body sprites, centered in equal slots, large flat chroma-key gutters, no overlap, no neighboring fragments. If any key pose swaps weapon hands, makes the anchor hand hold the weapon, crops the subject, or contaminates neighboring cells, regenerate the whole key-pose sheet.

After approval, split the pose sheet into four transparent files named with their final indices: _02, _05, _08, and _11. These files become immutable anchors for in-betweens.

Before approval, perform a baseline-difference review: compare the four key poses side by side with the baseline frame. Confirm that subject identity, head/face/eyes, signature silhouette, clothing/armor/shell markings, weapon or prop, outline weight, main colors, and highlight colors have not drifted. Pose-driven overlap, perspective, and stretching may change; identity features, body-part count, weapon ownership, art style, and proportion language may not. If the sheet looks like "same series, new variant" rather than "same character in a new pose," the whole sheet fails and must be regenerated.

Use a perfectly flat chroma-key background, generous gutters, and no labels, borders, shadows, effects, debris, or fused cells. Prefer #ff00ff when the subject contains green or blue.

Reject the pose sheet if any pose changes identity, loses details, duplicates limbs, reverses hand order, crops the subject, breaks the stable foot baseline, obscures active-shoulder attachment, or moves/hides the anchor limb. A limb crossing the torso must still be traceable to its locked shoulder.

5. Generate Reference-Guided In-Betweens

Required sub-skill: use built-in image_gen while referencing both the original baseline image and the approved key-pose sheet.

Generate in-betweens together in chronological order. Specify the exact beat for each cell, identical cell geometry, stable character scale, coherent limb trajectories, and intended contact hold.

Generate five anchor-to-anchor segments with fixed insertion counts: 00->02 gets 1 inserted frame; 02->05, 05->08, and 08->11 each get 2 inserted frames; 11->13 gets 1 inserted frame. Use the two adjacent anchors, the baseline image, and the full key-pose set as references. Do not include generated substitutes for any anchor index.

Repeat side locks verbatim in in-between prompts: name the active limb in screen space, require it to connect to the same shoulder in every cell, and state that the anchor limb must remain visible and stable. Even if a single frame looks plausible, shoulder-connection switching or ambiguity is a generation failure.

When a single 14-frame strip is likely to be crowded, contaminated, inconsistent in scale, or hard to split, do not force it. Prefer two short four-cell source sheets: 01/03/04/06 and 07/09/10/12. Frames 00 and 13 still use the exact baseline image, and 02/05/08/11 still come from the approved key-pose sheet. All source batches must share the same identity lock, side/topology lock, same chroma key, same apparent character size, same foot/bottom baseline, and same canvas/gutter constraints.

In-betweens must be generated by image_gen. Never generate each frame independently. Do not accept an in-between batch that is inconsistent with the approved key poses in style or identity. Do not replace model-generated in-betweens with procedural interpolation, image warping, or copied keyframes.

6. Remove Background and Normalize Frames

Remove the flat chroma-key background locally and inspect soft-edge alpha and chroma residue. Split cells in reading order. Local processing may only clean and organize images already generated by image_gen; it may not add or change character poses.

Before key removal, confirm the key color is absent from subject colors, weapon colors, highlights, and outlines. After matting, inspect subject coverage: body main colors, weapon, eyes, armor, horns, teeth, and black outlines should remain. If subject colors are hollowed out, outlines break, or a weapon disappears, stop post-processing and regenerate with a non-conflicting key color.

Place every frame on the same RGBA canvas with one shared scale and alignment transform. Do not auto-fit frame by frame. Maintain stable foot/bottom baseline and facing. Place the exact source image into frame 00 by translation only, then byte-copy frame 00 as frame 13.

If splitting cells creates neighboring-cell fragments, only remove small disconnected alpha components separated from the subject. Do not use brushes, paintovers, rotation, stretching, or copied limbs to repair the subject. If fragments are connected to the subject, the subject is cut, or the weapon is cropped, regenerate the source image.

Keep all PNG frames transparent. When building preview.gif, composite every RGBA frame over a pure white #FFFFFF background. Do not use transparent, checkerboard, gray, or dark preview backgrounds.

Use the repository helper to build or rebuild GIF previews from delivered full frames:

python scripts\fullframes_to_gif.py output\<action-id>\fullframe --output output\<action-id>\preview.gif --duration-ms 75

Adjust --duration-ms when the user asks for a slower or faster preview. The GIF is a playback preview only; the transparent deliverables remain fullframe/*.png and spritesheet.png.

Name full frames contiguously, for example hero-attack_00.png through hero-attack_13.png. Keyframes use the same prefix and preserve indices: _02, _05, _08, and _11.

7. Correct Temporal Continuity and Identity Drift

Compare adjacent frames. Correct only failing regions or failing poses. If a key pose changes, regenerate all affected in-betweens.

Inspect face, emblems, palette, silhouette, accessories, limb count, markings, weapon size, proportions, center, baseline, trajectory, and silhouette continuity.

If the active limb switches shoulders, becomes ambiguous behind the torso, or inherits the anchor limb's markings, reject the affected pose. Regenerate the key pose and all dependent in-betweens. Do not fix limb switching by mirroring a single frame, renaming sides, or tracking only hand-tip motion while ignoring shoulder origin.

8. Validate Output

Run deterministic validation for the 14-frame relationship:

python scripts/validate_14frame_pattern.py --baseline source.png --keyframes-dir output/keyframe --fullframes-dir output/fullframe --preview output/preview.gif --prefix hero-attack

Inspect the contact sheet and playback loop. Confirm:

• contiguous naming, RGBA mode, unified canvas size, and transparent corners;
• exactly 14 full frames and exactly 4 keyframes at 02/05/08/11;
• frames 00 and 13 are byte-identical after output, and both are the source image translated only, not redrawn or rescaled;
• each keyframe file is pixel-identical to the corresponding fullframe index;
• preview.gif contains exactly 14 frames and uses a pure white #FFFFFF background;
• no chroma edge or magenta residue;
• no identity drift, missing details, extra limbs, or scale popping;
• the active limb remains traceable to the same shoulder in every adjacent frame;
• the anchor limb stays visible, attached to the original shoulder, and non-attacking;
• side-specific spots, claws, armor, or accessories follow the correct limb across torso overlap;
• stable foot/bottom baseline and center;
• readable anticipation, acceleration, contact, contact hold, and recovery;
• smooth loop endpoints when looping is requested;
• the output directory contains only contract files; temporary sources, failed drafts, chroma-key sources, alpha sources, and debug splits have been deleted or kept outside the final directory.

Correct failures and repeat both visual inspection and deterministic validation. Always inspect contact-sheet.png first, then preview.gif, then report exact output paths and evidence.

9. Learn From Final Output

When the user approves a final animation or finishes requested revisions, offer or perform a short retrospective. For durable lessons, invoke the project sub-skill img2mo-learn or follow its storage contract:

• write output-specific notes to output/<action-id>/retro.md when useful;
• append one compact JSON object to img2mo-knowledge/learnings.jsonl;
• update concise project-level summaries in img2mo-knowledge/action-patterns.md, style-patterns.md, prompt-patterns.md, or failures.md.

Do not write normal learning records into the installed Codex skill directory. Keep project-specific knowledge in img2mo-knowledge/.

Output Contract

output/
|-- keyframe-prompts.md    # prompts for 02, 05, 08, 11 derived from baseline analysis
|-- keyframe/              # exact generated anchors at 02, 05, 08, 11
|-- fullframe/             # contiguous transparent RGBA sequence 00-13
|-- spritesheet.png        # packed sequence
|-- contact-sheet.png      # visual consistency review
|-- preview.gif            # 14-frame playback loop on solid white #FFFFFF
`-- manifest.json          # source, canvas, side/topology lock, key indices, segment plan, frame order

The final directory must not contain model source images, alpha sources, failed drafts, temporary splits, *-imagegen-* process images, or debug files. Those may exist only in a temporary directory and must be cleaned before delivery.

Quick Reference

Example

User: "Use this golem image to make a heavy ground-smash attack animation."

Analyze the baseline frame's subject, body parts, weapon, and art style; record the identity lock; write four keyframe prompts for 02/05/08/11; generate the four anchors together; fill frames with the 1/2/2/2/1 insertion plan; place the exact baseline at 00 and 13; inspect contact sheet and playback; validate the 14-frame relationship; deliver the transparent sequence.

Common Mistakes

• Generating each frame independently: causes identity and timing drift. Use a shared key-pose sheet and reference-guided in-betweens.
• Using scripts to generate motion artwork: this bypasses the model image-generation workflow. Keyframes and in-betweens must come from image_gen; scripts are only for matting, splitting, packing, and validation.
• Skipping baseline analysis and directly writing prompts: misses subject parts, weapons, style, or side markers. Analyze first, then derive four keyframe prompts.
• Generating keyframes from four text prompts alone: makes the model treat the baseline as a concept instead of an identity anchor, causing subtle drift. Key-pose generation must use the baseline visual reference; if direct reference is unavailable, include a reference identity cell in the same sheet.
• Letting the four keyframe prompts improvise separately: makes the character look like four similar variants. All prompts must share the same identity block and only change pose and motion beat.
• Treating key poses as loose references: approved 02/05/08/11 files must be copied exactly into fullframe/; do not redraw them during in-between generation.
• Redrawing loop endpoints: 00 and 13 must be the same translated baseline pixels, not similar-looking generated images.
• Auto-fitting each frame: causes scale popping. Use one shared transform.
• Creating new poses with affine transforms, local limb rotation, or copy-pasted limbs: this is not valid generation. Re-call image_gen for failed key poses or in-between batches.
• Accepting a pretty key pose with changed details: visual quality does not excuse identity drift.
• Accepting weapon hand swaps: this is topology failure, not a minor defect. Regenerate and repeat weaponHand/emptyHand locks in the prompt.
• Using a chroma key that conflicts with the subject: for example, #ff00ff on pink/purple characters can remove body colors or soft edges. Inspect subject colors before choosing the key.
• Cramming all 14 frames into one crowded strip: the model may compress gutters, causing split cells to cut the character or introduce neighboring fragments. Use 6+6 or shorter source batches when crowded.
• Trusting validation alone: OK only proves file structure, not motion, art, or topology. Inspect the contact sheet and GIF.
• Leaving intermediates in the final directory: the output contract is the delivery surface; failed drafts and debug images mislead downstream use. Clean temporary products.
• Treating "left" or "right" as self-evident: normalize to screen space and record anatomy separately when needed.
• Tracking only the hand tip: an arm can cross the torso and silently switch shoulders. Track the full limb, using the opposite arm as an anchor.
• Fixing a switch by mirroring one frame: this reverses markings and topology. Regenerate the key pose and dependent in-betweens.
• Adding effects during character generation: detached dust and motion lines complicate extraction. Add effects later as separate assets.
• Checking only single PNGs: a frame can look good alone and fail in motion. Inspect the contact sheet and playback loop.
• Trusting the generated background: remove chroma locally and measure residue.
• Using transparent, checkerboard, gray, or dark GIF backgrounds: preview frames must be composited over pure white #FFFFFF.

2dimg2motion.skill

What Is This

2dimg2motion.skill is a 2D game-animation generation skill for Codex / Claude Code / Agent Skills. It takes one static character, creature, vehicle, weapon, or prop image and generates a style-consistent transparent action sequence that can be packed into a spritesheet.

It is not a "single-image motion filter". Filters usually translate, rotate, scale, or warp local image layers; the core of this skill is whole-character key-pose redraw: first lock the character identity, then let the model redraw complete key poses, then generate in-between frames, with local scripts handling transparency, canvas normalization, packing, and validation.

Why It Exists

AI can easily draw characters that look like they belong to the same series, but it is much harder to draw continuous motion for the same character. Game animation adds more requirements:

• every frame must be a transparent RGBA PNG;
• character proportions, foot baseline, and canvas size must stay stable;
• weapons, arms, horns, tails, and wings must not swap sides or disappear;
• keyframes and in-betweens must form readable motion;
• the final output must be directly usable in Godot, Unity, Cocos, or a custom 2D engine.

This repository turns those lessons into an executable workflow: analyze the baseline image, establish the identity lock, design action beats, generate a shared key-pose sheet, generate in-betweens, remove the background, normalize frames, pack assets, validate structure, and visually inspect the result.

Quick Start

1. Install The Skill

Put the repository into your Agent Skills directory. Keep the repository structure intact, because the main skill, sub-skills, scripts, references, and project knowledge files refer to each other.

Codex example:

git clone https://github.com/WU-HAOTIAN34/2dimg2motion.git $env:USERPROFILE\.codex\skills\2dimg2motion

Claude Code example:

git clone https://github.com/WU-HAOTIAN34/2dimg2motion.git ~/.claude/skills/2dimg2motion

You can also run it directly from this repository during local development. Confirm the dependency:

python -m pip install pillow

2. Use The Main Skill To Generate Animation

In Codex or Claude Code, provide a baseline image and describe the motion:

/2dimg2motion use sample/s3.png to generate an arm-swing attack animation

Or:

Generate a walk action from this character image.
/2dimg2motion use sample/s7.png to generate a sword-slash action.
/2dimg2motion use sample/s1.png to make a heavy ground-smash attack animation.

The main skill runs the full workflow: analyze the baseline image, establish the identity lock, design key poses at 02/05/08/11, generate in-betweens, remove the background, normalize frames, pack the spritesheet, and output preview.gif and manifest.json.

3. Use The Baseline Standardization Sub-Skill

If the input image is too large, tightly cropped, visibly white-backed, or lacks enough transparent margin for attacks or walking motion, call the standardization sub-skill first:

/img2mo-std s7
/img2mo-std sample\s7.png

It resolves the image path and calls the script to create a standardized baseline image:

python scripts\standardize_baseline.py sample\s7.png

Useful options:

python scripts\standardize_baseline.py sample\s7.png --check-only
python scripts\standardize_baseline.py sample\s7.png --subject-max 360 --margin-ratio 0.75
python scripts\standardize_baseline.py sample\s7.png --output sample\s7-standard.png

Default output:

sample\<input-stem>-standard.png

The standardized image should become the 00 and 13 baseline frame for later animation generation.

4. Use The Learning Sub-Skill

If you have reference videos, existing outputs, failed attempts, GIFs, spritesheets, Spine assets, or frame folders, the skill can extract reusable project knowledge from them:

/img2mo-learn output\s3-arm-swing-attack
/img2mo-learn motion\some-reference-folder
/img2mo-learn sample\attack-reference.mp4

Learned notes are written to:

img2mo-knowledge/
|-- index.md
|-- learnings.jsonl
|-- action-patterns.md
|-- style-patterns.md
|-- prompt-patterns.md
`-- failures.md

Future animation generations read this project-level knowledge first, improving action timing, prompt clauses, canvas margins, and failure checks.

5. Use Scripts Directly

Scripts are for non-creative post-processing and validation only. They do not draw motion.

Standardize a baseline image:

python scripts\standardize_baseline.py sample\s7.png

Convert transparent fullframe PNGs into a white-background GIF preview:

python scripts\fullframes_to_gif.py output\s3-arm-swing-attack\fullframe --output output\s3-arm-swing-attack\preview.gif --duration-ms 75

Validate the 14-frame delivery structure:

python scripts\validate_14frame_pattern.py --baseline sample\s3-standard.png --keyframes-dir output\s3-arm-swing-attack\keyframe --fullframes-dir output\s3-arm-swing-attack\fullframe --preview output\s3-arm-swing-attack\preview.gif --prefix s3-arm-swing-attack

On success, it prints:

OK

Showcase

Input And Output

The input is usually one static PNG:

sample/s3.png

Describe the action you want:

use sample/s3.png to generate an arm-swing attack animation

The output is a standard delivery bundle:

output/<action-id>/
|-- keyframe-prompts.md   # prompts and identity lock for 02/05/08/11
|-- keyframe/             # 4 keyframes at fixed indices 02, 05, 08, 11
|-- fullframe/            # 14 transparent RGBA sequence frames, fixed indices 00-13
|-- spritesheet.png       # horizontal packed spritesheet
|-- contact-sheet.png     # visual review sheet
|-- preview.gif           # 14-frame white-background playback preview
`-- manifest.json         # canvas, frame order, topology lock, keyframe indices, and processing notes

fullframe/*.png contains the transparent frames you should import into your engine. preview.gif is only a human-readable playback preview.

Core Mechanisms

1. Identity Lock

Before generation, record the character invariants: face, eyes, silhouette, proportions, palette, outline, clothing, weapon, horns, tail, wings, claws, markings, and other accessories. Every later prompt inherits this identity lock.

2. Topology Lock

For attacks, waves, sword swings, tail sweeps, and similar actions, the skill records the active limb and anchor limb in screen space, for example:

activeLimb: screen-right arm
anchorLimb: