/video2dsprite

name: video2dsprite
description: Turn one approved master still into a character's whole animated sprite set - one image-to-video clip per action (idle, walk, run, attack, jump, hurt, cast and so on), all from that still, generated through generate2dmedia route_media.py (the xAI API when a key is configured, else the local Grok CLI) - then gate each take, key it with a soft matte, register it to the master, pick loops or retime actions, finish (HD by default, pixel on request) and package fixed-canvas frames, alpha WebM, packed MP4 for iPhone and a PNG fallback with engine metadata and a JS runtime. Also processes a supplied clip. Use for character and creature animation, fluid motion and any video-to-sprite work. Not for FX, icon or prop sheets (generate2dsprite), maps or plate loops (generate2dmap), code-drawn animation (codeart2d, only on request) or calling a video API by itself (generate2dmedia).

Video to 2D Animation

An approved still sets identity and geometry, a video model supplies motion, and deterministic tools prepare it for the engine. Video is not promised to be smaller, seamless or cheaper than sheets.

Use when

• Animating a character or creature: every action comes from one approved master still, one clip per action.
• Fluid motion from an accepted master: idle breathing, walks, runs, attacks, casts, hair, capes, creatures.
• A supplied clip must become transparent, registered, looped frames and engine video.

Do not use when

• FX, icon or prop sheets: [generate2dsprite](../generate2dsprite/SKILL.md).
• Water, fire or mist inside a still scene plate: [generate2dmap](../generate2dmap/SKILL.md). Only an API or CLI call: [generate2dmedia](../generate2dmedia/SKILL.md).
• Code-drawn animation the user asked for: [codeart2d](../codeart2d/SKILL.md).

Capability check (once per session)

Run `python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json`, where `<tools>` lists the media tools in your own tool list (`image_gen`, `image_edit`, `image_to_video`) or `none`. Its `ROUTES` block shows which API keys are configured (yes or no), the local readiness and the resolved order. If `encoding.stdout` fails, set `PYTHONUTF8=1`. `python "<skill-dir>/scripts/video2dsprite.py" doctor` checks ffmpeg (5.1+, VP9 alpha round trip).

Art source

The master still comes from [generate2dsprite](../generate2dsprite/SKILL.md) (image generation, approved by the user) or from the user. Motion is image-to-video, one clip per action from that master; record the route as `art_source` and name it in your reply:

1. **API**, when a key is configured: xAI Grok Imagine Video (`XAI_API_KEY`), BytePlus Seedance (`ARK_API_KEY`) or fal.ai (`FAL_KEY`: Kling v3, Veo 3.1, Luma Ray 3.2, MiniMax H3, Wan 3.0, Vidu Q3, LTX) ([route-media.md](../generate2dmedia/references/route-media.md)). The configured key is the owner's consent, so there is no per-call question. `--last-frame <still>` pins idle and attack clips to end on their first pose. 2. **Local**: your own image-to-video tool (Grok's native `image_to_video`) when you have one, otherwise the user's Grok CLI in ACP mode (it cannot pin a last frame; the result says `lastFrameUsed`). 3. A clip the user supplies (no account needed). 4. codeart2d only when the user explicitly asks for code-drawn animation, or when `route_media.py` prints `no-route` (exit 3); otherwise prepare the job and prompt, explain the gap, and never invent a successful generation.

Every clip goes through one command: `python "<skill-dir>/../generate2dmedia/scripts/route_media.py" video --prompt-file <job>/prompt.txt --reference <job>/input.png --last-frame <job>/input.png --duration 6 --resolution 720p --out-dir <new>`. It prints one JSON line with `route`, `artifact`, `sha256`, `estimateUsd` and `lastFrameUsed`. The finish is HD by default; the pixel finish is an option when the user asks for pixel art.

A whole sprite set from one still

For a character's game set, use `sprite_set.py`: one approved master (generate2dsprite `master.json`) in, one image-to-video clip per action out, keyed, gated, registered, cut, finished and packaged. For one clip or a supplied video, use the pipeline below. Details: [sprite-set.md](references/sprite-set.md). Prompts and fix clauses: [motion-prompts.md](references/motion-prompts.md).

1. **Plan.** `python "<skill-dir>/scripts/sprite_set.py" plan --master <art>/master.json --output-dir <set>`. Defaults: `--actions idle,walk,run,attack,jump,hurt`, `--finish` from the master (hd default; pixel or hibit), `--target-height` 256 hd or 80 pixel and hibit. Jump gets a 3:4 canvas with 34% headroom and attack a 16:9 one; idle and attack pin the end frame to the master. Read each action's `prompt` in `<set>/set_plan.json`, and edit `motion`, `negatives` or `gates` there before the run if needed. 2. **Run.** `python "<skill-dir>/scripts/sprite_set.py" run --plan <set>/set_plan.json`. Clips come from generate2dmedia `route_media.py`, then:

• soft-matte keying;
• numeric gates: area 0.72-1.32, feet, identity (a warning unless the design is lost), zoom, turning around, edge, background, extra objects, motion, end pose, colour bleed, one-shot timing;
• up to 3 takes, each retake carrying the fix clause for the gate that failed; if every take fails, the best usable window is kept;
• registration, then a loop, or a one-shot retimed to game length from its motion energy (attack 0.7 s with the hit at 40%, jump 0.9 s, hurt 0.5 s, cast 0.9 s; set in the plan's `timing`);
• `finish_frames.py` hd, pixel or hibit, with the colour lock to the master on by default for hd and pixel (`plan --no-colour-lock`; hibit never locks);
• png, webm and packed packages, verified.

Run it again to resume; nothing is generated twice. 3. **No route (exit 3).** Make the clip with your own image-to-video tool from the input and prompt that the summary names, save it as the named `media/clip.mp4`, a