Skip to content
Back to search

2dimg2motion

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wu-haotian34-2dimg2motion/badge.svg)](/listings/wu-haotian34-2dimg2motion)

HTML

<a href="/listings/wu-haotian34-2dimg2motion"><img src="/api/listings/wu-haotian34-2dimg2motion/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 398 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: 2dimg2motion
  3. 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.
  4. ---
  5. # 2dimg2motion
  6. ## Overview
  7. 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.
  8. **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.
  9. Before generating animation assets, read [references/keypose-redraw.md](references/keypose-redraw.md). When designing action timing or prompt wording, also consult [references/motion-prompt-patterns.md](references/motion-prompt-patterns.md), which distills reusable patterns from the local `motion/` reference library.
  10. 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.
  11. ## Input Contract
  12. Collect or infer:
  13. - baseline image and character facing direction;
  14. - 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;
  15. - motion type, ordered beats, and loop behavior;
  16. - preferred frame count or timing;
  17. - canvas size, stable foot/bottom baseline, and naming prefix;
  18. - required deliverables: keyframe prompts, sequence frames, spritesheet, contact sheet, and playback preview.
  19. 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.
  20. ## Generation Boundaries
  21. - 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.
  22. - Character poses in keyframes, in-betweens, and sprite strips must be directly generated by `image_gen` from prompts and visual references.
  23. - 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.
  24. - 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.
  25. - 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.
  26. - 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.
  27. ## Hard Failure Constraints
  28. 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:
  29. - **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."
  30. - **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.
  31. - **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.
  32. - **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.
  33. - **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.
  34. - **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.
  35. - **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.
  36. - **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.
  37. ## Limb-Side and Topology Lock
  38. Before designing poses, establish limb identity:
  39. - 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.
  40. - Normalize all sides to `screen-left` or `screen-right`. If anatomy matters, record both forms, such as `character-left (screen-right)`.
  41. - Record the `activeLimb`, its `activeShoulder`, the opposite `anchorLimb`, and any distinctive markings or spikes that identify both sides.
  42. - 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`.
  43. - In every key pose and in-between, even when the active limb crosses the body centerline, it must remain connected to the same shoulder.
  44. - 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.
  45. - 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`.
  46. - Persist `coordinateSpace`, `activeLimb`, `activeShoulder`, and `anchorLimb` in `manifest.json`. Do not mix anatomical and screen-space naming inside one animation.
  47. ### Weapon, Prop, Accessory, and Creature Locks
  48. Before prompt writing, classify non-body elements and non-human motion drivers:
  49. - Record `activeWeapon`, `carriedProp`, `passiveAccessory`, and `detachedProp` separately. A held torch, shield, embedded arrow, helmet crest, and thrown weapon need different rules.
  50. - 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.
  51. - 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.
  52. - 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.
  53. - 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.
  54. ## Default 14-Frame Plan
  55. Use six immutable anchors in this order: `00 -> 02 -> 05 -> 08 -> 11 -> 13`.
  56. | Index | Role | Rule |
  57. |---|---|---|
  58. | 00 | baseline start | Place the exact source image on the final canvas; do not redraw or rescale it. |
  59. | 01 | in-between | Interpolate 00 -> 02. |
  60. | 02 | keyframe 1 | First generated defining pose. |
  61. | 03-04 | in-betweens | Interpolate 02 -> 05 in chronological order. |
  62. | 05 | keyframe 2 | Second generated defining pose. |
  63. | 06-07 | in-betweens | Interpolate 05 -> 08 in chronological order. |
  64. | 08 | keyframe 3 | Third generated defining pose. |
  65. | 09-10 | in-betweens | Interpolate 08 -> 11 in chronological order. |
  66. | 11 | keyframe 4 | Fourth generated defining pose. |
  67. | 12 | in-between | Interpolate 11 -> 13. |
  68. | 13 | baseline end | Exact copy of frame 00. |
  69. 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.
  70. 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`.
  71. Persist `previewBackground: "#FFFFFF"` in `manifest.json`.
  72. ## Motion Library Patterns
  73. The local `motion/` library shows these practical timing patterns:
  74. - **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.
  75. - **Idle:** small settle/rise/settle breathing loop, usually around `5%` width/height variation.
  76. - **Move/walk:** contact/down/passing/up/opposite-contact, with clear feet alternation, small body bob, and stable mass.
  77. - **Block:** compact guard raise/hold/return, fixed feet, little scale change.
  78. - **Hit/suffer:** impact/recoil/squash/recovery; face and accessories can exaggerate, but identity stays locked.
  79. - **Death:** imbalance/fall/impact/rest; do not force the final frame to loop to neutral.
  80. - **Born/spawn:** small seed/egg/portal/curled silhouette unfolds into full identity; large size change is valid only for spawn-like actions.
  81. - **Skill/cast:** anticipation/charge/peak cast/hold/recovery; detached effects should be separate overlays unless explicitly requested in the character sheet.
  82. In every pose-sheet prompt, include the stable canvas rules:
  83. ```text
  84. Same apparent character size in every cell.
  85. Same foot/bottom baseline in every cell.
  86. Body center stays near the same cell center except for intentional lunges.
  87. Complete character, weapons, horns, ears, tails, claws, and effects remain inside the cell.
  88. Allow the silhouette to widen for attacks, but do not scale the character smaller or larger.
  89. ```
  90. 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.
  91. ### Action Prompt Templates
  92. Use these beat templates when the user gives only a broad action request:
  93. | Action | Key pose 02 | Key pose 05 | Key pose 08 | Key pose 11 |
  94. |---|---|---|---|---|
  95. | Compact melee slash | crouch/wind up; weapon draws up/back on locked side | fastest slash/chop; clear contact silhouette | low/front follow-through; body overcommitted | weapon returns to ready guard |
  96. | Horn/body bash | body compresses; head/horn pulls back; side limbs brace | forward/down lunge; horn/shell/face leads | lowest compressed impact hold | body rises and re-centers |
  97. | Claw swipe | active claw pulls back; anchor claw visible | active claw maximum extension | torso twist and follow-through | active claw returns to guard |
  98. | Ground smash | body rises or fists/weapon lift overhead | hard drop to ground line | lowest squash; widest impact silhouette | heavy rebound upward |
  99. | Idle | settle | rise | settle | neutral loop return |
  100. | Move/walk | contact | down | passing/up | opposite contact |
  101. | Block | begin guard raise | guard silhouette readable | hold guard | return to neutral |
  102. | Hit/suffer | impact | recoil | squash/stretch | recovery |
  103. | Death | imbalance | fall | impact | rest |
  104. | Born/spawn | seed/egg/portal/curled shape | unfolding | nearly full form | neutral identity |
  105. | Skill/cast | anticipation | charge | peak cast/hold | recovery |
  106. ## Workflow
  107. ### 0. Audit and Standardize the Baseline Frame
  108. For the `/img2mo-std` baseline standardization sub-skill and command reference, read [skills/img2mo-std/SKILL.md](skills/img2mo-std/SKILL.md).
  109. 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.
  110. Before baseline analysis or any `image_gen` call, check whether the input frame is a usable animation baseline:
  111. - foreground subject longest side should be about `300-400 px`;
  112. - transparent or removable background should surround the subject;
  113. - every side should have enough action margin for walk bob, weapon arcs, hair, horns, cloak, tail, wings, or props;
  114. - long weapons, capes, tails, antlers, banners, and large attack silhouettes need extra horizontal/vertical margin;
  115. - source images much larger than this range should be standardized to reduce generation time and reduce model scale drift.
  116. Use the bundled script when the image is too large, too tight, or has a white background:
  117. ```powershell
  118. python scripts\standardize_baseline.py sample\s7.png
  119. ```
  120. 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.
  121. Useful options:
  122. ```powershell
  123. python scripts\standardize_baseline.py sample\s7.png --subject-max 380 --margin-ratio 0.8
  124. python scripts\standardize_baseline.py sample\s7.png --output sample\s7-standard.png
  125. python scripts\standardize_baseline.py sample\s7.png --check-only
  126. ```
  127. Treat the standardized baseline as the `00`/`13` source for validation. Keep the original file unchanged unless the user explicitly asks to overwrite it.
  128. ### 0.5. Load Project Knowledge
  129. Before baseline analysis and prompt writing, check whether `img2mo-knowledge/index.md` exists.
  130. If it exists:
  131. - read `img2mo-knowledge/index.md`;
  132. - for the requested action type, read `img2mo-knowledge/action-patterns.md` if present;
  133. - for style-sensitive requests, read `img2mo-knowledge/style-patterns.md` if present;
  134. - before writing prompts, read `img2mo-knowledge/prompt-patterns.md` if present;
  135. - before validation/rejection decisions, read `img2mo-knowledge/failures.md` if present;
  136. - search `img2mo-knowledge/learnings.jsonl` only for matching action types, character styles, or source tags when detailed examples are useful.
  137. 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.
  138. ### 1. Analyze the Baseline Frame and Establish the Identity Lock
  139. Inspect the source image at original resolution. Before generating images, write a reusable baseline-frame analysis that records every invariant that must survive redraw:
  140. - subject type: what the character, creature, vehicle, weapon, or prop is, and how its overall silhouette reads;
  141. - body structure: count, position, proportion, and facing of head, torso, limbs, wings, tail, claws, horns, shell, exoskeleton, etc.;
  142. - face, expression, silhouette, proportions, and facing;
  143. - palette, outline weight, shading style, material treatment, pixel/hand-drawn/cartoon/realistic style;
  144. - limb count, hand order, clothing, armor, markings, and accessories;
  145. - shoulder-to-limb topology, active-side mapping, anchor limb, and side-specific markings;
  146. - weapon shape, grip, length, emblem, and distinctive small details.
  147. 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.
  148. ### 2. Design Motion Beats and Key Poses
  149. Before generating images, choose readable motion beats:
  150. - idle: settle -> rise -> settle;
  151. - walk: contact -> down -> passing/step-through -> up -> opposite contact;
  152. - attack: guard -> anticipation -> acceleration -> contact -> contact hold -> recovery;
  153. - hit: contact -> recoil -> settle;
  154. - death: imbalance -> collapse -> impact -> rest.
  155. 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.
  156. 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.
  157. ### 3. Write the Four Keyframe Prompts
  158. 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.
  159. **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.
  160. Each keyframe prompt must include:
  161. - fixed identity block: subject, body parts, weapons, proportions, silhouette, palette, outline, material, art style, and details that must not change;
  162. - 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;
  163. - continuity block: motion direction from the previous anchor to the next anchor, foot/bottom baseline, and relationship to the 00/13 loop;
  164. - canvas and background block: complete character, equal cells, stable scale, generous safety margin, flat chroma-key background, no labels/borders/shadows/effects.
  165. 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.
  166. ### 4. Generate One Coherent Key-Pose Sheet
  167. **Required sub-skill:** use built-in `image_gen` for whole-character key-pose redraw.
  168. 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.
  169. 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.
  170. The pose-sheet prompt must explicitly include identity-alignment rules:
  171. - `use the provided baseline image as the visual identity source, not as loose inspiration`;
  172. - `preserve the exact silhouette language, color palette, outline weight, facial features, markings, weapon size, and body-part count from the baseline`;
  173. - `only change pose, weight, limb angles, squash/stretch, and motion timing`;
  174. - `do not redesign, simplify, beautify, add details, remove details, change proportions, or reinterpret the character`.
  175. 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.
  176. 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.
  177. 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.
  178. 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.
  179. 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.
  180. 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.
  181. ### 5. Generate Reference-Guided In-Betweens
  182. **Required sub-skill:** use built-in `image_gen` while referencing both the original baseline image and the approved key-pose sheet.
  183. 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.
  184. 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.
  185. 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.
  186. 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.
  187. 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.
  188. ### 6. Remove Background and Normalize Frames
  189. 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.
  190. 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.
  191. 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.
  192. 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.
  193. 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.
  194. Use the repository helper to build or rebuild GIF previews from delivered full frames:
  195. ```powershell
  196. python scripts\fullframes_to_gif.py output\<action-id>\fullframe --output output\<action-id>\preview.gif --duration-ms 75
  197. ```
  198. 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`.
  199. 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`.
  200. ### 7. Correct Temporal Continuity and Identity Drift
  201. Compare adjacent frames. Correct only failing regions or failing poses. If a key pose changes, regenerate all affected in-betweens.
  202. Inspect face, emblems, palette, silhouette, accessories, limb count, markings, weapon size, proportions, center, baseline, trajectory, and silhouette continuity.
  203. 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.
  204. ### 8. Validate Output
  205. Run deterministic validation for the 14-frame relationship:
  206. ```powershell
  207. python scripts/validate_14frame_pattern.py --baseline source.png --keyframes-dir output/keyframe --fullframes-dir output/fullframe --preview output/preview.gif --prefix hero-attack
  208. ```
  209. Inspect the contact sheet and playback loop. Confirm:
  210. - contiguous naming, RGBA mode, unified canvas size, and transparent corners;
  211. - exactly 14 full frames and exactly 4 keyframes at 02/05/08/11;
  212. - frames 00 and 13 are byte-identical after output, and both are the source image translated only, not redrawn or rescaled;
  213. - each keyframe file is pixel-identical to the corresponding fullframe index;
  214. - `preview.gif` contains exactly 14 frames and uses a pure white `#FFFFFF` background;
  215. - no chroma edge or magenta residue;
  216. - no identity drift, missing details, extra limbs, or scale popping;
  217. - the active limb remains traceable to the same shoulder in every adjacent frame;
  218. - the anchor limb stays visible, attached to the original shoulder, and non-attacking;
  219. - side-specific spots, claws, armor, or accessories follow the correct limb across torso overlap;
  220. - stable foot/bottom baseline and center;
  221. - readable anticipation, acceleration, contact, contact hold, and recovery;
  222. - smooth loop endpoints when looping is requested;
  223. - 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.
  224. 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.
  225. ### 9. Learn From Final Output
  226. 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:
  227. - write output-specific notes to `output/<action-id>/retro.md` when useful;
  228. - append one compact JSON object to `img2mo-knowledge/learnings.jsonl`;
  229. - update concise project-level summaries in `img2mo-knowledge/action-patterns.md`, `style-patterns.md`, `prompt-patterns.md`, or `failures.md`.
  230. Do not write normal learning records into the installed Codex skill directory. Keep project-specific knowledge in `img2mo-knowledge/`.
  231. ## Output Contract
  232. ```text
  233. output/
  234. |-- keyframe-prompts.md # prompts for 02, 05, 08, 11 derived from baseline analysis
  235. |-- keyframe/ # exact generated anchors at 02, 05, 08, 11
  236. |-- fullframe/ # contiguous transparent RGBA sequence 00-13
  237. |-- spritesheet.png # packed sequence
  238. |-- contact-sheet.png # visual consistency review
  239. |-- preview.gif # 14-frame playback loop on solid white #FFFFFF
  240. `-- manifest.json # source, canvas, side/topology lock, key indices, segment plan, frame order
  241. ```
  242. 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.
  243. ## Quick Reference
  244. | Stage | Gate |
  245. |---|---|
  246. | Baseline analysis | Subject, body parts, weapon, art style, invariants, screen-space side mapping, and limb topology are recorded |
  247. | Keyframe prompts | 02, 05, 08, 11 each have one detailed prompt and all inherit the same identity block |
  248. | Key poses | Exactly four anchors occupy 02, 05, 08, and 11 |
  249. | In-betweens | Fixed 1/2/2/2/1 insertions fill the five anchor segments |
  250. | Normalization | One scale, canvas, facing, and stable foot/bottom baseline |
  251. | Correction | Adjacent frames preserve identity and trajectory continuity |
  252. | Delivery | Deterministic validation, contact sheet, and playback loop pass |
  253. ## Example
  254. User: "Use this golem image to make a heavy ground-smash attack animation."
  255. 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.
  256. ## Common Mistakes
  257. - Generating each frame independently: causes identity and timing drift. Use a shared key-pose sheet and reference-guided in-betweens.
  258. - 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.
  259. - Skipping baseline analysis and directly writing prompts: misses subject parts, weapons, style, or side markers. Analyze first, then derive four keyframe prompts.
  260. - 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.
  261. - 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.
  262. - 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.
  263. - Redrawing loop endpoints: 00 and 13 must be the same translated baseline pixels, not similar-looking generated images.
  264. - Auto-fitting each frame: causes scale popping. Use one shared transform.
  265. - 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.
  266. - Accepting a pretty key pose with changed details: visual quality does not excuse identity drift.
  267. - Accepting weapon hand swaps: this is topology failure, not a minor defect. Regenerate and repeat weaponHand/emptyHand locks in the prompt.
  268. - 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.
  269. - 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.
  270. - Trusting validation alone: `OK` only proves file structure, not motion, art, or topology. Inspect the contact sheet and GIF.
  271. - Leaving intermediates in the final directory: the output contract is the delivery surface; failed drafts and debug images mislead downstream use. Clean temporary products.
  272. - Treating "left" or "right" as self-evident: normalize to screen space and record anatomy separately when needed.
  273. - 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.
  274. - Fixing a switch by mirroring one frame: this reverses markings and topology. Regenerate the key pose and dependent in-betweens.
  275. - Adding effects during character generation: detached dust and motion lines complicate extraction. Add effects later as separate assets.
  276. - Checking only single PNGs: a frame can look good alone and fail in motion. Inspect the contact sheet and playback loop.
  277. - Trusting the generated background: remove chroma locally and measure residue.
  278. - Using transparent, checkerboard, gray, or dark GIF backgrounds: preview frames must be composited over pure white `#FFFFFF`.
README.md · README · 372 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <p align="center">
  3. <img src="examples/e1res.gif" height="110" alt="claudecy idle" />
  4. <img src="examples/e2res.gif" height="110" alt="claudecy running" />
  5. <img src="examples/e3res.gif" height="110" alt="claudecy success" />
  6. <img src="examples/e4res.gif" height="110" alt="claudecy talking" />
  7. <img src="examples/e7res.gif" height="110" alt="howl success" />
  8. <img src="examples/e6res.gif" height="110" alt="howl running" />
  9. </p>
  10. # 2dimg2motion.skill
  11. <p align="center">
  12. <strong>English</strong>
  13. &nbsp;·&nbsp;
  14. <a href="README-CN.md"><strong>简体中文</strong></a>
  15. </p>
  16. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  17. [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Standard-green)](https://agentskills.io)
  18. [![Multi-Runtime](https://img.shields.io/badge/Runtime-ClaudeCode%20·%20Codex-blueviolet)]()
  19. <br>
  20. <p align="center">
  21. 2dimg2motion.skill -- not a filter that "makes an image move", but a runnable framework for generating game animation frames
  22. </p>
  23. <br>
  24. <p align="center">
  25. Spritesheet delivery pipeline via key-pose redrawing, identity locking, and limb topology constraints,<br>
  26. it turns every instinct of "how should this character move?" into an executable, verifiable, reusable animation-generation pipeline.<br>
  27. Input one 2D character, creature, weapon, vehicle, or prop image,<br>
  28. and output a style-consistent transparent action sequence ready to import into a game engine.
  29. </p>
  30. ![head](examples/github-header-1.png)
  31. </div>
  32. ---
  33. ## What Is This
  34. `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.
  35. 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.
  36. ## Why It Exists
  37. 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:
  38. - every frame must be a transparent RGBA PNG;
  39. - character proportions, foot baseline, and canvas size must stay stable;
  40. - weapons, arms, horns, tails, and wings must not swap sides or disappear;
  41. - keyframes and in-betweens must form readable motion;
  42. - the final output must be directly usable in Godot, Unity, Cocos, or a custom 2D engine.
  43. 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.
  44. ## Quick Start
  45. ### 1. Install The Skill
  46. 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.
  47. Codex example:
  48. ```powershell
  49. git clone https://github.com/WU-HAOTIAN34/2dimg2motion.git $env:USERPROFILE\.codex\skills\2dimg2motion
  50. ```
  51. Claude Code example:
  52. ```bash
  53. git clone https://github.com/WU-HAOTIAN34/2dimg2motion.git ~/.claude/skills/2dimg2motion
  54. ```
  55. You can also run it directly from this repository during local development. Confirm the dependency:
  56. ```powershell
  57. python -m pip install pillow
  58. ```
  59. ### 2. Use The Main Skill To Generate Animation
  60. In Codex or Claude Code, provide a baseline image and describe the motion:
  61. ```text
  62. /2dimg2motion use sample/s3.png to generate an arm-swing attack animation
  63. ```
  64. Or:
  65. ```text
  66. Generate a walk action from this character image.
  67. /2dimg2motion use sample/s7.png to generate a sword-slash action.
  68. /2dimg2motion use sample/s1.png to make a heavy ground-smash attack animation.
  69. ```
  70. 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`.
  71. ### 3. Use The Baseline Standardization Sub-Skill
  72. 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:
  73. ```text
  74. /img2mo-std s7
  75. /img2mo-std sample\s7.png
  76. ```
  77. It resolves the image path and calls the script to create a standardized baseline image:
  78. ```powershell
  79. python scripts\standardize_baseline.py sample\s7.png
  80. ```
  81. Useful options:
  82. ```powershell
  83. python scripts\standardize_baseline.py sample\s7.png --check-only
  84. python scripts\standardize_baseline.py sample\s7.png --subject-max 360 --margin-ratio 0.75
  85. python scripts\standardize_baseline.py sample\s7.png --output sample\s7-standard.png
  86. ```
  87. Default output:
  88. ```text
  89. sample\<input-stem>-standard.png
  90. ```
  91. The standardized image should become the `00` and `13` baseline frame for later animation generation.
  92. ### 4. Use The Learning Sub-Skill
  93. 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:
  94. ```text
  95. /img2mo-learn output\s3-arm-swing-attack
  96. /img2mo-learn motion\some-reference-folder
  97. /img2mo-learn sample\attack-reference.mp4
  98. ```
  99. Learned notes are written to:
  100. ```text
  101. img2mo-knowledge/
  102. |-- index.md
  103. |-- learnings.jsonl
  104. |-- action-patterns.md
  105. |-- style-patterns.md
  106. |-- prompt-patterns.md
  107. `-- failures.md
  108. ```
  109. Future animation generations read this project-level knowledge first, improving action timing, prompt clauses, canvas margins, and failure checks.
  110. ### 5. Use Scripts Directly
  111. Scripts are for non-creative post-processing and validation only. They do not draw motion.
  112. Standardize a baseline image:
  113. ```powershell
  114. python scripts\standardize_baseline.py sample\s7.png
  115. ```
  116. Convert transparent fullframe PNGs into a white-background GIF preview:
  117. ```powershell
  118. python scripts\fullframes_to_gif.py output\s3-arm-swing-attack\fullframe --output output\s3-arm-swing-attack\preview.gif --duration-ms 75
  119. ```
  120. Validate the 14-frame delivery structure:
  121. ```powershell
  122. 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
  123. ```
  124. On success, it prints:
  125. ```text
  126. OK
  127. ```
  128. ## Showcase
  129. <table>
  130. <tr>
  131. <th align="center"><p align="center">Ronin - Slash</p></th>
  132. <th align="center"><p align="center">Golem - Smash</p></th>
  133. <th align="center"><p align="center">Monster - Claw</p></th>
  134. <th align="center"><p align="center">Giant - Sword Swing</p></th>
  135. <th align="center"><p align="center">Worker - Walk</p></th>
  136. <th align="center"><p align="center">Beetle - Crawl</p></th>
  137. </tr>
  138. <tr>
  139. <td align="center"><img src="examples/s1.png" width="110" alt="ronin input image"></td>
  140. <td align="center"><img src="examples/s2.png" width="110" alt="golem input image"></td>
  141. <td align="center"><img src="examples/s3.png" width="110" alt="monster input image"></td>
  142. <td align="center"><img src="examples/s5.png" width="110" alt="giant input image"></td>
  143. <td align="center"><img src="examples/s6.png" width="110" alt="worker input image"></td>
  144. <td align="center"><img src="examples/s4.png" width="110" alt="beetle input image"></td>
  145. </tr>
  146. <tr>
  147. <td colspan="6"><img src="examples/s1-spritesheet .png" width="1200" alt="ronin slash 14-frame spritesheet"></td>
  148. </tr>
  149. <tr>
  150. <td colspan="6"><img src="examples/s2-spritesheet.png" width="1200" alt="golem smash 14-frame spritesheet"></td>
  151. </tr>
  152. <tr>
  153. <td colspan="6"><img src="examples/s3-spritesheet.png" width="1200" alt="monster claw 14-frame spritesheet"></td>
  154. </tr>
  155. <tr>
  156. <td colspan="6"><img src="examples/s5-spritesheet.png" width="1200" alt="giant sword-swing 14-frame spritesheet"></td>
  157. </tr>
  158. <tr>
  159. <td colspan="6"><img src="examples/s6-spritesheet.png" width="1200" alt="worker walk 14-frame spritesheet"></td>
  160. </tr>
  161. <tr>
  162. <td colspan="6"><img src="examples/s4-spritesheet.png" width="1200" alt="beetle crawl 14-frame spritesheet"></td>
  163. </tr>
  164. </table>
  165. ## Input And Output
  166. The input is usually one static PNG:
  167. ```text
  168. sample/s3.png
  169. ```
  170. Describe the action you want:
  171. ```text
  172. use sample/s3.png to generate an arm-swing attack animation
  173. ```
  174. The output is a standard delivery bundle:
  175. ```text
  176. output/<action-id>/
  177. |-- keyframe-prompts.md # prompts and identity lock for 02/05/08/11
  178. |-- keyframe/ # 4 keyframes at fixed indices 02, 05, 08, 11
  179. |-- fullframe/ # 14 transparent RGBA sequence frames, fixed indices 00-13
  180. |-- spritesheet.png # horizontal packed spritesheet
  181. |-- contact-sheet.png # visual review sheet
  182. |-- preview.gif # 14-frame white-background playback preview
  183. `-- manifest.json # canvas, frame order, topology lock, keyframe indices, and processing notes
  184. ```
  185. `fullframe/*.png` contains the transparent frames you should import into your engine. `preview.gif` is only a human-readable playback preview.
  186. ## Core Mechanisms
  187. ### 1. Identity Lock
  188. 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.
  189. ### 2. Topology Lock
  190. For attacks, waves, sword swings, tail sweeps, and similar actions, the skill records the active limb and anchor limb in screen space, for example:
  191. ```text
  192. activeLimb: screen-right arm
  193. anchorLimb: screen-left arm
  194. ```
  195. This reduces failures like "the right hand suddenly becomes the left hand", "the weapon switches hands", or "the tail root disappears".
  196. ### 3. 14-Frame Structure
  197. Default actions use fixed anchors:
  198. ```text
  199. 00 -> 02 -> 05 -> 08 -> 11 -> 13
  200. ```
  201. `00` and `13` are the baseline image. `02/05/08/11` are the four model-generated key poses. The other frames are in-betweens generated from adjacent anchors. This structure keeps short actions compact and easy to validate.
  202. ### 4. Whole-Character Redraw
  203. Keyframes and in-betweens must be generated by an image model as complete character poses. Scripts may only perform non-creative post-processing: baseline standardization, cell splitting, chroma-key removal, canvas normalization, GIF generation, spritesheet packing, and validation.
  204. ### 5. Verifiable Delivery
  205. The repository includes a validator that checks frame count, naming, RGBA mode, canvas size, transparent corners, whether 00/13 match, whether keyframes are pixel-identical to their corresponding fullframes, and whether the GIF is a 14-frame white-background preview.
  206. ## Supported Action Types
  207. | Action | Common Beats |
  208. |---|---|
  209. | idle | settle -> rise -> settle |
  210. | walk / move | contact -> down -> passing -> up -> opposite contact |
  211. | attack | guard -> anticipation -> acceleration -> contact -> follow-through -> recovery |
  212. | block | raise guard -> hold -> return |
  213. | hit / suffer | impact -> recoil -> squash/stretch -> recovery |
  214. | death | imbalance -> fall -> impact -> rest |
  215. | born / spawn | small/curled shape -> unfold -> full identity |
  216. | skill / cast | anticipation -> charge -> peak cast -> recovery |
  217. ## Workflow
  218. 1. **Standardize the baseline image**: when needed, crop and resize the input image onto a transparent padded canvas to prevent action poses from going out of bounds.
  219. 2. **Analyze the character**: record body structure, colors, style, face, limbs, weapons, accessories, and uncertain areas.
  220. 3. **Establish locks**: write the identity lock, topology lock, weapon/prop ownership, and canvas constraints.
  221. 4. **Design key poses**: design action beats for `02/05/08/11`.
  222. 5. **Generate the key-pose sheet**: generate the four key poses together to reduce identity drift from independent calls.
  223. 6. **Generate in-betweens**: generate 8 in-between frames with the fixed `1/2/2/2/1` insertion plan.
  224. 7. **Post-process**: remove the chroma-key background and normalize canvas, scale, center, and foot baseline.
  225. 8. **Package deliverables**: output fullframe, keyframe, spritesheet, contact-sheet, preview.gif, and manifest.
  226. 9. **Validate and visually inspect**: run structural validation, then inspect the contact sheet and GIF for hand swaps, clipping, cyan fringe, scale popping, or unreadable motion.
  227. ## Repository Structure
  228. ```text
  229. .
  230. |-- SKILL.md # main skill instructions and full generation contract
  231. |-- references/ # key-pose redraw and motion prompt references
  232. |-- skills/img2mo-std/ # baseline standardization sub-skill
  233. |-- scripts/
  234. | |-- standardize_baseline.py
  235. | |-- fullframes_to_gif.py
  236. | `-- validate_14frame_pattern.py
  237. |-- sample/ # input sample images
  238. |-- examples/ # README showcase assets
  239. |-- motion/ # local motion reference library
  240. `-- img2mo-knowledge/ # project-level learned knowledge
  241. ```
  242. ## Design Principles
  243. - **Prefer whole-character generation**: do not fake key poses by rotating local limbs with scripts.
  244. - **Generate shared key poses together**: do not generate 02/05/08/11 as four independent calls.
  245. - **Keep 00/13 identical to the baseline**: loop endpoints must be the same baseline frame.
  246. - **Use one scale strategy per batch**: avoid frame-by-frame auto-fit that causes scale popping.
  247. - **Do not skip visual inspection**: validation scripts catch structural issues, not every animation failure.
  248. - **Keep final directories clean**: final output directories should contain deliverables only, not failed drafts or model source sheets.
  249. ## Dependencies
  250. - Python 3.x
  251. - [Pillow](https://python-pillow.org/)
  252. - Codex / Claude Code / Agent Skills style runtime
  253. - Available image-generation capability for key poses and in-between frames
  254. ## License
  255. MIT © 2026 Haotian Wu
  256. ---
  257. ## Use Case
  258. <div >
  259. <table>
  260. <tr>
  261. <td align="center">
  262. <a href="#小程序://搬家塔防/bQrrvXJtLMv04Bh">
  263. <img src="examples/logo.png" width="120" height="120" alt="Moving Tower Defense Battle"><br>
  264. <strong>Moving Tower Defense Battle</strong>
  265. </a>
  266. <br>
  267. <span>WeChat Mini Game · Tower Defense Strategy</span>
  268. <br>
  269. <img src="https://img.shields.io/badge/WeChat%20Mini%20Game-Live-07C160" alt="WeChat">
  270. </td>
  271. </tr>
  272. </table>
  273. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.