Sprite Forge

Game-ready sprites from images or text, September 2026 edition. Five pipelines, two wired providers (Retro Diffusion, fal genmedia), and a profile runner so a project can declare its own pipeline.

Cost rule: every provider script is a free dry run until you pass --yes. Retro Diffusion runs check_cost; genmedia prints the exact command and price. Never add --yes on a user's behalf without stating the estimate.

When to use

• Pixel-art characters, 8-direction rotations, animated frames from a start image
• Walk/idle/attack sprite sheets from video (first+last-frame loops)
• HD painted turnarounds via GPT Image 2.5 edits
• Upscaling indexed sprites without new colours (faithful-HD rule)
• Atlas metadata with states, fps, loop, anchor (Phaser/Godot/Flame/Aseprite)
• SVG mascots with GSAP, ASCII art, lil-agents dock videos (unchanged niche)

Not for: 3D generation (meshy skill), photoreal image editing (nano-banana-pro skill), generated sprites where original assets exist and parity is required (see references/pipelines/open-rebellion.md).

Work sequentially inside a pipeline; parallel agents only for independent characters.

Quick start

S=~/.claude/skills/sprite-forge/scripts
# 8-direction pixel sprite (one Retro Diffusion call, $0.25)
python3 $S/turnaround.py --mode pixel --prompt "astromech droid" --ref droid.png --out ./turn   # add --yes
# Walk cycle: Wan 3 clip on chroma -> key -> feet-align -> atlas v2 (+ Aseprite JSON)
python3 $S/video_to_spritesheet.py --provider genmedia --start-frame hero.png --end-frame hero.png \
  --prompt "side-view walk cycle in place, flat #00FF00 background" --duration 4 --cell-size 128x128 \
  --dedup 6 --state walk:12:loop --aseprite-json -o walk.png                                   # add --yes
# Indexed sprite 4x with the same palette
python3 $S/pixel_scale.py --input sprite.png --output sprite_4x.png --mode scale4x
# Frames -> sheet with manifest v2
python3 $S/stitch_spritesheet.py --input-dir frames/ --atlas v2 --state idle:8:loop --cols 8 -o idle.png
# Profile
python3 $S/run_pipeline.py ~/.claude/skills/sprite-forge/pipelines/example.json --dry-run

Pipeline 1: Turnaround (turnaround.py)

• --mode pixel: rd_animation__8_dir_rotation (80x80, <= 5 refs) -> split -> stitch --atlas v2 --directions 8. One paid call.
• --mode hd: anchor -> 4 cardinal edits -> 4 diagonal edits (anchor + two neighbours as refs) -> key if --chroma -> align_frames -> stitch. Default model openai/gpt-image-2.5/sunburst/edit (true alpha); --model fal-ai/nano-banana-2/edit --chroma for typed refs.
• Order in the sheet: S, SE, E, NE, N, NW, W, SW. See references/turnaround.md.

Pipeline 2: Video -> sprite sheet (video_to_spritesheet.py)

[genmedia clip] -> ffmpeg -> chroma_key (once) -> align_frames (feet line, dedup, loop check) -> stitch v2. Default model alibaba/wan-3.0/image-to-video with --end-frame = start frame for a seamless loop; alternates Seedance 2.5, Kling 3 (@Element identity), Hailuo 03 (timecoded multi-state). Per-frame rembg on video is refused (matte flicker) unless --allow-rembg-video. Recipe and model table: references/video-to-spritesheet.md; jitter rules: references/frame-alignment.md.

Pipeline 3: Pixel scaling and palette (deterministic)

• pixel_scale.py --mode nearest|scale2x|scale3x|scale4x, mode-P in, mode-P out, palette block and transparency kept, colour count never grows. --family dir/ --output-dir out/ transforms a frame family and writes family.json with a family sha256.
• Retro Diffusion free tools for the generative side: retro_diffusion.py tool k_centroid_downscale --input-image in.png --field width=64 --field height=64, tool palette_converter --palette pal.png, tool color_reducer --field color_count=16, tool pixel_correction; pixelate (rd_pro__pixelate, $0.18) turns any raster into native pixel art.
• pixel_art_generator.py survives only for the SVG <rect> mascot path (Pipeline 4).

Pipeline 4: SVG characters and GSAP mascots

Gemini SVG-as-code for clean vectors (references/gemini-svg-generation.md); pixel_art_generator.py --grid 16-24 --colors 4-6 --merge for rect-based pixel mascots (references/pixel-art-svgs.md); animation_builder.py --preset idle|bounce|lean|wave|walk|walk-and-bounce|walk-and-wave|typing for GSAP timelines (references/gsap-timeline-patterns.md, references/ayotomcs-deconstruction.md); generate_walk_video.py sheet.png --cols 6 --name robot for lil-agents HEVC-alpha dock videos (references/lil-agents-character-spec.md). Trim AI images first: magick in.png -fuzz 15% -trim +repage out.png.

Pipeline 5: ASCII

image_to_ascii.py img.png --mode gray|color|jp2a --width 80 for static art (references/ascii-art-techniques.md); frame-based React components and the asciistudio catalog in references/ascii-animation-components.md and references/animated-ascii-sprites.md; template assets/ascii-animation-template.tsx.

Profiles (pipelines/)

A profile (pipelines/schema.json) is an ordered list of stages over these scripts with ${var} substitution. run_pipeline.py profile.json [--dry-run] [--yes] [--stage name] [--from name] [--force] writes <output_root>/run/<id>/manifest.json with per-stage commands and input/output sha256 and skips unchanged stages. pipelines/example.json is the generic character profile; project profiles live in their repos (Open Rebellion: references/pipelines/open-rebellion.md).

Provider matrix (short)

Need	Use	Alpha
Pixel still / identity	RD rd_pro__default + --ref (<= 9), $0.18	--remove-bg
8 directions, pixel	RD rotate8, $0.25	yes
Animate a start frame	RD `animate --action walking	idle
HD anchor / edits	openai/gpt-image-2.5/sunburst[/edit] via gen_image.py	yes
Many typed refs	fal-ai/nano-banana-2/edit	no, chroma
Loops	alibaba/wan-3.0/image-to-video first+last	no, chroma
Identity-critical clip	fal-ai/kling-video/v3/pro/image-to-video @Element1	no, chroma

Full table, prices, setup commands and PixelLab notes: references/provider-matrix.md. Setup: genmedia CLI (curl https://genmedia.sh/install -fsS | bash, then genmedia setup --non-interactive --api-key "$FAL_KEY"), RETRODIFFUSION_API_KEY in ~/.config/env/secrets.env; optional RD MCP claude mcp add --transport http retro-diffusion https://mcp.retrodiffusion.ai/mcp --header "Authorization: Bearer rdpk-...".

Gotchas

• Feet line, not bbox. Halos and shadows move the bbox; align_frames.py scans for the lowest row with >= 5% solid width. Check feet_line_variance < 1.
• One matte per clip. Chroma-key video frames with one setting; per-frame rembg flickers (perimeter_cv > 0.15).
• RD limits. Styles cap at 384 px, animations at 256 and must match the start frame; input_image must be RGB without alpha (scripts composite onto --matte); negative is ignored; never write "pixel art" in RD prompts; balance is charged before generation.
• genmedia. Use --async for anything over ~5 s (the video script does); verify endpoint ids and field names with genmedia models / genmedia schema; the GPT Image 2.5 endpoint spelling came from a third-party commit.
• Nano Banana 2 still has no alpha; GPT Image 2.5 and RD do. Never key magenta on warm costumes.
• Manifest v2 pastes at cell origin; use --fit scale only for legacy sheets that need centring.
• Pixel art through the aligner: --no-scale, and the scaler uses nearest below 256 px.
• Turnarounds: cardinals, then diagonals; diagonals come out shorter, so never skip the align step.

Dependencies

Pillow (numpy optional, speeds pixel_scale.py), ffmpeg, ImageMagick 7, genmedia CLI (fal), rembg (stills only), jp2a (optional), GSAP 3 via CDN. Keys: FAL_KEY, RETRODIFFUSION_API_KEY (loaded by scripts/_secrets.py from env or ~/.config/env/secrets.env).

Reference

• references/provider-matrix.md, references/landscape-2026-09.md — endpoints, prices, what changed
• references/turnaround.md, references/video-to-spritesheet.md, references/frame-alignment.md, references/chroma-key-transparency.md — pipeline details
• references/gemini-svg-generation.md, references/pixel-art-svgs.md, references/gsap-timeline-patterns.md, references/ayotomcs-deconstruction.md, references/lil-agents-character-spec.md — SVG and mascot
• references/ascii-art-techniques.md, references/ascii-animation-components.md, references/animated-ascii-sprites.md — ASCII
• references/pipelines/open-rebellion.md — project profile pointer
• tests/test_deterministic.py — run python3 tests/test_deterministic.py