generate2dsprite

Generate 2D Sprite

Make the smallest asset bundle the game needs, at its real display size, camera and style. Game logic (collision, damage, timing) stays independent of the art.

Use when

• A character, creature, prop, item, icon or FX is needed as a master still, a sheet or clips.
• Frames already exist (generated, painted, code-drawn) and need clips, palettes or an engine export.

Do not use when

• Maps, tiles, terrain, parallax or scene plates: generate2dmap.
• Animating a character: approve one master here, then video2dsprite makes one clip per action (video-handoff.md).
• Code-drawn art the user asked for: codeart2d. Only an API or CLI call: generate2dmedia.

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.

Art source

Image generation is the default art source for characters, creatures, props, icons and FX. Record it as art_source (api, host_image, existing, or code only on request) and name the route in your reply. A route the user names explicitly wins.

1. API, when a key is configured: OpenAI (OPENAI_API_KEY), Google Gemini (GEMINI_API_KEY), xAI (XAI_API_KEY), BytePlus Seedream (ARK_API_KEY) or fal.ai (FAL_KEY), in the environment or the user config file (route-media.md). The configured key is the owner's consent, so there is no per-call question.
2. Local: your own image tool (Codex image_gen, Grok's native tool) when you have one, otherwise the user's signed-in Codex CLI, then Grok CLI.
3. codeart2d only when the user explicitly asks for code-drawn art, or when route_media.py prints no-route (exit 3). Then say "code-drawn, no image model".

Every image goes through one command: python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>. It picks the route in that order and prints one JSON line with route, artifact, sha256 and estimateUsd; resolve --kind image says which route would run. Existing art the user supplies is always welcome. Never claim a generation that did not happen; keep the prompt and contract and report a missing capability.

• Finish: HD is the default: full colour, clean alpha, one registration and a premultiplied area downscale to the game height. The pixel finish (one shared palette, binary alpha, no dither) is an option when the user asks for pixel art. Never prompt an image model for a logical pixel grid; the pixel look comes from the finish.
• Characters: approve one master still per character, then animate it with video2dsprite: one image-to-video clip per action, all from that master (sprite_set.py). Keep every action's body height from the master's rest pose.
• Sheets are for FX, icons and props (and frames the user supplies), not for character animation.

Master still (every character animation starts here)

One approved master still per character, then one image-to-video clip per action from it (video2dsprite); sheets are for FX, icons and props. Wording: prompt-rules.md; commands, framing and master.json: master-still.md.

1. Spec (--spec <json> and/or flags): --name, --subject, --identity (long and precise), --facing left|right|front|back, --class hero|mob|boss|prop, --finish hd|pixel (HD default; pixel only when asked), --identity-ref (FIRST image, copied exactly), --style-ref (SECOND: an approved peer sprite, style and framing only), --key (default #FF00FF; green or blue for purple and pink designs).
2. Generate: python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <new>. Each take goes through generate2dmedia route_media.py (API key first, then the local daemon); takes.png shows them side by side. Exit 3 means no route: say so; codeart2d is the fallback ("code-drawn, no image model"). With the host's own image tool: run master_still.py prompt and attach the listed references in that order.
3. Choose by looking: identity, facing, nothing touching an edge, no text.
4. Fix a near-miss by edit, never by re-roll: master_still.py edit --run <dir> --take N --change "<one change>" --output-dir <new> (or --master <dir>).
5. Approve: master_still.py approve --run <dir> --take N --output-dir <new> (a still from elsewhere: --still <png> --route <what made it>). It keys the still, crops it with a 6 px margin, LANCZOS-scales it to the class framing on 1024x1024 (hero 788 px tall, top margin 138 px) and writes master.png (opaque, pure key), master_rgba.png and master.json (generate2dsprite.master.v1).
6. Motion steps read master.json (identity_recap, facing, finish, class, framing, key, files, transform, route) and never re-measure the still; every clip prompt starts with "The same <identity_recap>".

Report the route from master.json route. A FORGE_ROUTE_MEDIA_FAKE warning means the image is not a real generation.

Host notes

• Codex: image_gen is your own image tool; with no configured key use it and look at results with view_image. An image this session made that is not in the project: python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>, then process generated.png. codeart2d and generate2dmedia are explicit-only: open their SKILL.md when this one routes there.
• Claude Code: no built-in image generator: route_media.py takes the API or the local CLIs. Look at every PNG you make with Read; run tools with Bash; <skill-dir> is ${CLAUDE_SKILL_DIR}.
• Grok: its native image and video tools are your own tools; use their real schema.

Commands

Run each tool as one line from the user's project root: python "<skill-dir>/scripts/<tool>.py" .... <skill-dir> is this skill's folder; sibling skills sit beside it (<skill-dir>/../video2dsprite). Keep inputs and outputs inside the project. Every tool writes a new --output-dir: it refuses an existing one, stages beside it and publishes only after its checks (--strict-qc / --strict publish nothing on failure). Success prints one JSON line; errors print error: ... and exit 1; usage errors exit 2. Needs Python 3.10+, numpy and Pillow (scipy recommended). --help lists every flag.

Plan the asset

Record identity and reference, camera and facing, style, game display size, finish (HD by default, pixel on request), action list and phases, loop or one-shot, motion envelope, shared root and output format. Keep one accepted master and one source-to-display scale per character; mobs are no taller than the hero unless planned. A grid is not smoothness: pose spacing, timing, the loop seam and ground contact matter more. Poses, NEAR/FAR legs and timing: animation-planning.md.

• Alpha: native_alpha keeps real transparency (a painted checkerboard is not alpha); chroma_key uses flat magenta only when the subject has none; opaque keeps whole images (assemble_frames.py).
• Sampling: lanczos or a premultiplied area resize for generated art; nearest only for a verified pixel grid. A high-resolution pixel-like painting is not clean 32 px art.
• A shared root is not a per-frame alpha-bbox bottom: keep intentional flight, jumps, bob and recoil.

Generate (image routes)

Write the prompt yourself (prompt-rules.md; grids, phases and presets in action-recipes.md). Attach references through --reference (or your tool's real image input); a path in prose is not a reference. Keep the accepted master in every generation and describe absolute phases, not chained edits; a fix is an edit of the approved still that names the only change. Generate one action family at a time and keep wide slashes, trails and projectiles out of the body sheet. Verify the actual route, model and returned size; never claim them from the prompt.

Pipeline

Sheets (FX, icons, props): sheet_qc.py spill on the raw sheet, then generate2dsprite.py process, then sheet_qc.py frames, then scale_frames.py, then build_animation_clips.py, then export_engine.py. Character actions come back from video2dsprite as packaged clips.

Need	Route
Plan a sheet for an image tool (aspect, grid, guide, prompt)	plan_guide.py --frames N --cycle run --output-dir <new>; attach guide.png, paste prompt.txt. Fixed scale and feet line: make_anchor_layout.py; empty safe frame: make_layout_guide.py
Check a raw sheet before slicing	sheet_qc.py spill --input <sheet> --rows R --cols C --output-dir <new>; crossing parts mean regenerate with more margin or slice by ownership, never a largest-component filter
Key, slice and register a sheet	generate2dsprite.py process --input <sheet> --target asset --mode <mode> --rows R --cols C --output-dir <new> --strict-qc (geometry v2; processing.md)
Pixel art drawn at M source px per art px	process --resampler nearest --logical-pixel M --pixel-scale N (whole scales only)
Jumps, bob or recoil on one registration point	process --scale-strategy registered (or --anchor-px X,Y)
One character's scale across actions	process --write-scale-profile <p.json> on the grounded reference, then --scale-profile <p.json> --max-profile-scale-drift 0.08
Canvas does not divide into the grid; other row order	process --grid-rounding nearest or --pad-to-grid; --direction-order down,up,left,right (modes.md)
Identity, NEAR/FAR alternation, drift, baselines	sheet_qc.py frames --sheet <sheet> --rows R --cols C --cycle run --output-dir <new>; a duplicated half-cycle means regenerate the second half. On code-drawn frames (art_source=code) identity_residual and torso_drift are advisory
Game size on one canvas and root, never clamped	scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <new>; later actions add --profile <first>/scale-frames.json --action-padding L,T,R,B
Clips with timing, events, transitions	build_animation_clips.py --manifest clips.json --output-dir <new>; read the lints and review/ (frames-and-clips.md)
Whole frames or a scene loop (no keying)	assemble_frames.py (--key chroma, --slice ownership; --loop-overlap K --ambient for ambient loops only)
Shared palette, locks, variants, flicker (pixel finish)	palette_tool.py build, apply, lock, quantize-seq, variants, luts; strict logical grid: pixel_reduce.py (palette-and-pixels.md)
Engine export	export_engine.py --clips <animation-clips.json> --target all --output-dir <new>; Sprite3D: --target godot-sprite3d --world-height <units> (engine-export.md)
Play clips in a game (gait, hit-stop, transitions)	runtime-integration.md
Code-drawn sprites, rigs or FX, only on request	codeart2d render_pixelspec.py, rig_animate.py or fx_build.py with --build-clips (never process), then export_engine.py; disclose them as code-drawn

Acceptance

• Review at game size: silhouette and identity, contact and flight, loop seam or one-shot recovery, alpha over light and dark, extremities, scale across actions, root and collider.
• Quote numbers for quality claims: pipeline-meta.json matte.qa (a key_ring_spill warning: add --despill-radius 1 or --key-quality soft), sheet-qc.json, the clip builder's lints. Numeric QC finds symptoms; it never approves anatomy or motion.
• Report every WARN or FAIL check verbatim (id, value, threshold, files) from each published QA envelope; never say "all checks passed" when any published envelope has a warn.
• Deliver accepted source art, runtime frames or clips, preview, prompt and provenance (route, model, estimateUsd), QA and remaining limits. Keep the last accepted bundle when revising.

References

processing.md (process flags, legacy switches), modes.md, prompt-rules.md, action-recipes.md, character-animation.md (animation index), frames-and-clips.md, palette-and-pixels.md, engine-export.md, runtime-integration.md, video-handoff.md; data contracts in references/schemas/sprite.schema.json.