# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-wu-haotian34-2dimg2motion-2dimg2motion`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [WU-HAOTIAN34](https://agentstack.voostack.com/s/wu-haotian34)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [WU-HAOTIAN34](https://github.com/WU-HAOTIAN34)
- **Source:** https://github.com/WU-HAOTIAN34/2dimg2motion

## Install

```sh
agentstack add skill-wu-haotian34-2dimg2motion-2dimg2motion
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](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.

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`.

| Index | Role | Rule |
|---|---|---|
| 00 | baseline start | Place the exact source image on the final canvas; do not redraw or rescale it. |
| 01 | in-between | Interpolate 00 -> 02. |
| 02 | keyframe 1 | First generated defining pose. |
| 03-04 | in-betweens | Interpolate 02 -> 05 in chronological order. |
| 05 | keyframe 2 | Second generated defining pose. |
| 06-07 | in-betweens | Interpolate 05 -> 08 in chronological order. |
| 08 | keyframe 3 | Third generated defining pose. |
| 09-10 | in-betweens | Interpolate 08 -> 11 in chronological order. |
| 11 | keyframe 4 | Fourth generated defining pose. |
| 12 | in-between | Interpolate 11 -> 13. |
| 13 | baseline end | Exact copy of frame 00. |

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:

```text
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:

| Action | Key pose 02 | Key pose 05 | Key pose 08 | Key pose 11 |
|---|---|---|---|---|
| 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 |
| 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 |
| Claw swipe | active claw pulls back; anchor claw visible | active claw maximum extension | torso twist and follow-through | active claw returns to guard |
| Ground smash | body rises or fists/weapon lift overhead | hard drop to ground line | lowest squash; widest impact silhouette | heavy rebound upward |
| Idle | settle | rise | settle | neutral loop return |
| Move/walk | contact | down | passing/up | opposite contact |
| Block | begin guard raise | guard silhouette readable | hold guard | return to neutral |
| Hit/suffer | impact | recoil | squash/stretch | recovery |
| Death | imbalance | fall | impact | rest |
| Born/spawn | seed/egg/portal/curled shape | unfolding | nearly full form | neutral identity |
| Skill/cast | anticipation | charge | peak cast/hold | recovery |

## 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](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:

```powershell
python scripts\standardize_baseline.py sample\s7.png
```

Default output is `sample/-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:

```powershell
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;
-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [WU-HAOTIAN34](https://github.com/WU-HAOTIAN34)
- **Source:** [WU-HAOTIAN34/2dimg2motion](https://github.com/WU-HAOTIAN34/2dimg2motion)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wu-haotian34-2dimg2motion-2dimg2motion
- Seller: https://agentstack.voostack.com/s/wu-haotian34
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.