Generate and postprocess general 2D game assets and animation sheets: pixel-art sprites, clean HD map props, creatures, characters, NPCs, spells, projectiles, impacts, props, summons, and transparent GIF exports. Use when Codex should infer the asset plan from a natural-language request, match a reference or map art style, call built-in `image_gen` for solid-magenta raw sheets, and use the local processor only for chroma-key cleanup, frame extraction, alignment, QC, and transparent exports.
Generate and postprocess general 2D game assets and animation sheets: pixel-art sprites, clean HD map props, creatures, characters, NPCs, spells, projectiles, impacts, props, summons, and transparent GIF exports. Use when Codex should infer the asset plan from a natural-language request, match a reference or map art style, call built-in `image_gen` for solid-magenta raw sheets, and use the local processor only for chroma-key cleanup, frame extraction, alignment, QC, and transparent exports.
Generate2dsprite
Use this skill for self-contained 2D sprite or animation assets.
When a larger game or playable prototype needs sprites, use this skill for the visible sprite assets and keep runtime/game assembly separate. Do not replace requested sprite assets with code-drawn placeholders.
Parameters
Infer these from the user request:
asset_type: player | npc | creature | character | spell | projectile | impact | prop | summon | fx
action: single | idle | cast | attack | shoot | jump | hurt | combat | walk | run | hover | charge | projectile | impact | explode | death
Decide the asset plan yourself. Do not force the user to spell out sheet size, frame count, or bundle structure when the request already implies them.
Do not pack unrelated actions into one raw generated sheet just to satisfy a 4x4, 5x5, or custom engine atlas. A raw generated sheet should represent one action family, one continuous sequence, one canonical directional locomotion sheet, or one prop/asset pack.
For controllable heroes, main characters, and high-value player assets with multiple actions, generate separate per-action grid sheets first, QC each action, then deterministically assemble the engine-required atlas only after the grids pass visual review.
Default scale_strategy=preserve --align feet for every character / creature / NPC / enemy / boss body sheet (idle, walk, run, attack, hurt, cast, channel, action, jump, etc.). Preserve keeps raw-cell scale, supports wide attack poses, integrated weapons, capes, ribbons, and aura/flame FX without bbox-fit vertical compression. Past projects have shown preserve produces visually richer character sheets than fit (artistic intent + FX preservation kept), at the cost of ~15-25% body-height variance across actions which reads as natural action-pose tightening rather than glitch.
Use scale_strategy=fit ONLY for: projectiles, item icons, pickups, FX sheets (impact, muzzle flash, hit spark), UI sprites, and other small / grid-uniform / aspect-stable assets where cell-fitting matters more than artistic preservation. Compact bodies and small creatures may also use fit when the user specifically requests grid-uniform sizing.
Same character = same strategy across ALL its action sheets. If you process idle with preserve, every sheet for that character (walk, attack, hurt, etc.) MUST also use preserve. Mixing fit and preserve for one character produces 25-36% body-height drift between actions and is a hard bug — test-2d-gpg2's nobunaga_ember (idle fit 139px, attack preserve 102px) is the canonical failure case. Pick one strategy at the first action and stick to it for the whole character.
For controllable heroes and high-value characters, body sheets MAY include integrated weapons, slash arcs, capes, and auras when using preserve — preserve was designed for exactly this case. Only split into separate FX sheets when the runtime explicitly needs per-action FX origin metadata or layered z-ordering (e.g. weapon must render above an enemy that's between body and screen).
Write the art prompt yourself. Do not default to the prompt-builder script.
Use built-in image_gen for every raw image.
Do not create raw sprite art with Three.js, Canvas, SVG, HTML/CSS drawing, PIL shape drawing, procedural geometry, placeholder primitives, or code-rendered screenshots. Runtime code may display finished generated assets, and scripts may make layout guides or postprocess generated images, but requested sprite art must originate from built-in .
Workflow
1. Infer the asset plan
Pick the smallest useful output.
Examples:
controllable hero with four directions -> player + player_sheet
side-view controllable hero with idle/run/shoot/jump -> player + hero_action_bundle
idle grid sheet, usually 2x2 for 4 frames
run grid sheet, usually 2x2 or 2x3 depending on needed frame count
shoot grid sheet with body/weapon only, usually 2x2
jump grid sheet, usually 2x2
projectile / muzzle flash as separate assets when needed
optional assembled engine atlas after per-action QC
side-view controllable hero with melee attack -> player + hero_action_bundle
attack body grid sheet, usually 2x2 or 2x3, body-only
slash arc / weapon trail as a separate fx sheet when the attack needs a wide visual effect
impact spark as a separate impact sheet when hits need feedback
healer overworld NPC -> npc + single_asset or unit_bundle
large boss idle loop -> creature + idle + 3x3
wizard throwing a magic orb -> spell_bundle
caster cast sheet
projectile loop
impact burst
monster line request -> line_bundle
plan 1-3 forms
per form, make the sheets the request actually needs
Use pixel_art or retro_pixel for classic sprites, 16-bit RPG actors, and requests that explicitly ask for pixel art.
Use clean_hd for map props or assets intended to match clean hand-painted HD maps.
Use pixel_inspired only when the user wants a pixel-adjacent look without retro chunkiness.
Use map_style or project-native when an existing map, game, or reference should define the style.
If a reference is involved:
Make the reference visible first. For local paths, use view_image; for freshly generated references, rely on the image already shown in context.
State the reference role explicitly: preserve identity/style, create an animation sheet for the same subject, create an evolution/variant, or derive a matching prop/FX.
Preserve the stable identity markers from the reference: silhouette, palette, face/eye features, costume marks, major accessories, and material language.
Let only the requested action or evolution change. Do not redesign the subject unless the user asks.
Still require exact sheet shape, solid magenta background, frame containment, and same scale across frames.
Keep the strict parts:
solid #FF00FF background
exact sheet shape
same character or asset identity across frames
same bounding box and pixel scale across frames
explicit containment: nothing may cross cell edges
Mixed-action atlas guardrail:
Do not ask image_gen to generate unrelated action rows in one raw sheet, such as row 1 idle, row 2 run, row 3 shoot, row 4 jump, for a controllable hero or main character.
Do not ask image_gen to generate raw single-row action strips such as 1x4 idle, 1x4 run, 1x4 shoot, or 1x4 jump for a controllable hero, character, creature, NPC, enemy, summon, or animated prop.
If an engine needs a combined 4x4, 5x5, custom atlas, or row-strip delivery format, generate the action grids separately, process and QC them separately, then assemble the delivery atlas deterministically.
Exceptions are canonical directional locomotion sheets, one continuous long action sequence, prop packs, tileset-like atlases, and low-stakes compact enemy combat sheets. These still need one coherent prompt and visual QC.
Keep projectile, muzzle flash, impact, dust trails, and detached FX in separate sheets unless they are intentionally part of the same action silhouette and remain tightly attached.
For controllable heroes and main characters, "tightly attached" is not enough when the effect makes the action bbox much wider or taller than idle/run. Split wide slash arcs, muzzle flashes, long weapon trails, dust clouds, and impact bursts into separate FX sheets by default.
Animated body grid guardrail:
1x4 and other raw single-row sheets are not valid defaults for animated bodies. This includes players, controllable heroes, creatures, NPCs, enemies, summons, animated props, and body-attached combat actions.
Use 2x2 for 4-frame body actions. This is the default for idle, short attack, shoot body, jump, hurt, hover, and compact side-view walk/run actions.
Use 2x3 for 6-frame body actions such as cast, attack, summon, run, charge, or transformation.
Use 2x4, 3x3, 3x4, or 4x4 for longer body actions. Prefer a compact grid over a long row.
For 4-direction top-down walk, 4x4 can remain a raw generation shape because it is a canonical directional locomotion sheet, not four unrelated action rows.
If final runtime needs a row strip, assemble it after QC from the processed multi-row grid frames.
Keep the character centered in every cell. The body centerline should stay near the cell center, feet/bottom anchor should stay on the same y-position when visible, and the subject should occupy only the central safe area with generous magenta padding.
For attack, shoot, cast, charge, and other body actions, the body height should stay close to the accepted idle/run body height. If a fixed-cell runtime is being used, reject body-action output when the body appears more than about 10-15% smaller than idle/run, even if edge_touch_frames is empty.
Map prop pack guardrail:
Use square 2x2, 3x3, and 4x4 raw prop packs only for compact props such as rocks, shrubs, barrels, crates, lamps, small signs, pots, debris, and small ornaments.
Do not use square prop packs for wide or collision-critical map objects: floors, platforms, ledges, terrain chunks, bridges, wall runs, ladders, roads, rails, pipes, long spike traps, gates, doors, buildings, large trees, checkpoints, exits, or build pads.
Use one-by-one generation for unique, large, important, tall, irregular, or collision-aligned props.
Use 1x3 or 1x4 strips for repeatable platform/floor assets, with left cap, middle repeat, right cap, and optional slope/corner/end variant.
Use custom wide cells for multiple similar wide objects. The grid must state explicit non-square cell dimensions and must not mix compact props with platform/terrain objects.
If a square prop pack fails due to edge touch or bad cropping, do not solve it by relaxing QC. Reclassify the object and regenerate with a more suitable sheet shape.
If a layout guide is useful, generate one before calling built-in image_gen:
Then make the guide visible in the conversation context and tell image_gen to use it only for invisible slot count, spacing, centering, and safe padding. The output must not reproduce guide boxes, safe-area rectangles, center marks, labels, borders, or guide background.
Use layout guides deliberately:
recommended for prop_pack_3x3, prop_pack_4x4, tileset-like atlases, fixed multi-row animation grids, and non-directional 16-frame action sequences such as casting, summoning, charging, death, or transformation
optional for 3x3 large idle and high-value showcase loops when previous generations drift in scale or spacing
not the default for 4x4 four-direction walk sheets, because the guide can make directional poses too conservative; use it only after an unguided run fails layout or edge safety
3. Generate the raw image
Use built-in image_gen.
Do not use Three.js, Canvas, SVG, HTML/CSS, PIL drawing, or other code-generated art as the raw sprite source. These are acceptable only for runtime display, debug overlays, deterministic layout guides, or postprocessing already-generated images.
After generation:
find the raw PNG under $CODEX_HOME/generated_images/...
copy or reference it from the working output folder
keep the original generated image in place
4. Postprocess locally
Run scripts/generate2dsprite.py process on the raw image.
The processor is intentionally low-level. The agent chooses:
rows / cols
fit_scale
align
shared_scale
component_mode
component_padding
scale_strategy
edge_touch rejection strategy
Use the processor to gather QC metadata, not to make aesthetic decisions for you.
For hero action bundles, process each action grid as its own sheet before any final atlas assembly. Use component_mode=all for character body sheets (default — keeps capes, weapons, auras attached). Use component_mode=largest only when you explicitly want to strip detached subcomponents (e.g. when the model leaked stray FX into otherwise body-only frames you want clean).
Strategy selection — pick once per character and use the same flag for every action sheet of that character:
--scale-strategy preserve --align feet — DEFAULT for character / creature / NPC / enemy / boss body sheets. Preserve crops the subject, pastes it back into a same-size source canvas on a shared feet anchor, then resizes the whole canvas to the requested output cell. Wide attack poses, integrated weapons, capes, flames, and auras all survive. Cross-action body height varies ~15-25% with model output (raw model variance) and that variance reads as natural action-pose tightening, not glitch.
--scale-strategy fit — for projectiles, item icons, pickups, FX sheets, UI sprites, and small grid-uniform assets where cell-fitting and aspect normalization matter more than artistic preservation. Fit rescales the subject's bbox to fill cell_size × fit_scale, which compresses wide compositions vertically — never use it for character body sheets that include extended weapons, capes, or wide attack poses.
Hard rule: every action sheet for the same character MUST use the same strategy. Mixing produces 25-36% body-height drift between actions (idle fit + attack preserve = idle 139px / attack 102px in test-2d-gpg2). Pick at the first action; stick with it.
5. QC the result
Check:
did any frame touch the cell edge
did any frame resize differently than intended
did detached effects become noise
does the sheet still read as one coherent animation
for hero/player body actions, does the body height match the accepted idle/run scale within roughly 10-15%
for fixed-cell runtimes, did a wide weapon trail or FX arc shrink the body inside the cell
for preserve-scale runs, are feet/bottom anchors aligned without any paste_clamped frames
If not, rerun with different processor settings or regenerate the raw sheet.
6. Return the right bundle
For a single sheet, expect:
raw-sheet.png
raw-sheet-clean.png
sheet-transparent.png
frame PNGs
animation.gif
prompt-used.txt
pipeline-meta.json
For player_sheet, expect:
transparent 4x4 sheet
16 frame PNGs
direction strips
4 direction GIFs
For spell_bundle or unit_bundle, create one folder per asset in the bundle.
For hero_action_bundle, expect:
one raw and processed sheet per action
per-action frame PNGs and GIFs for visual QC
separate projectile / muzzle / slash / impact assets when the hero shoots, casts, or uses wide melee effects
optional assembled engine-atlas-transparent.png only after per-action QC passes
Defaults
idle
small or medium actor -> 2x2
large creature or boss -> 3x3
cast -> prefer 2x3
projectile -> prefer 2x2 for short animated loops; use row strips only when the engine specifically requires a strip, and assemble that strip after QC when practical
impact / explode -> prefer 2x2
walk
topdown actor -> 4x4 for four-direction walk
side-view asset -> 2x2
controllable hero or main player with multiple actions -> hero_action_bundle
generate one action per raw multi-row grid sheet, not as a raw 1x4 strip
body sheets process with --scale-strategy preserve --align feet (the default for characters); integrated weapons, capes, slash arcs, and aura FX in the body sheet are FINE under preserve — that's what preserve was designed for
separate FX / projectile / muzzle-flash / hit-impact sheets only when the runtime needs per-action FX origin metadata or independent z-order layering
default 4-frame action grid is 2x2
use 2x3 for 6-frame actions and 2x4, 3x3, 3x4, or 4x4 for longer actions
do not generate a mixed-action raw 4x4, 5x5, or custom atlas
assemble the final atlas only as a deterministic delivery step if the game requires it
4x4, 5x5, and custom grids
use as raw generation only for one coherent long action sequence, canonical directional locomotion, prop packs, or tileset-like atlases
use as delivery atlases for mixed actions only after separate action sheets pass QC
use shared_scale by default for any multi-frame asset where frame-to-frame consistency matters
use component_mode=all (default) for character body grids; use largest only when stripping leaked detached subcomponents from otherwise body-only frames
strategy selection summary:
Resources
references/modes.md: asset, action, bundle, and sheet selection
references/prompt-rules.md: manual prompt patterns and containment rules
scripts/generate2dsprite.py: postprocess primitive for cleanup, extraction, alignment, QC, and GIF export
image_gen
When the user provides or implies a visual reference, use built-in image edit/reference semantics only after the reference image is visible in the conversation context. If the reference is a local file, call view_image first; do not rely on a filesystem path in the prompt as the visual reference.
Do not force pixel art when the asset is a map prop for $generate2dmap or when the user/project requests a different style. Match the map or reference style first.
Use the script only as a deterministic processor: magenta cleanup, frame splitting, component filtering, scaling, alignment, QC metadata, transparent sheet export, and GIF export.
Do not use scripts to generate the creative image prompt. If a legacy prompt-builder command exists, treat it as historical compatibility only, not the normal skill workflow.
Layout guides are allowed only as deterministic geometry references for image generation. They may show slot count, spacing, centering, and safe padding, but must never define the creative art direction.
Treat script flags as execution primitives chosen by the agent, not user-facing hardcoded workflow.
If a generated sheet touches cell edges, drifts in scale, or breaks a projectile / impact loop, either reprocess with better primitive settings or regenerate the raw sheet.
Do not use raw single-row sheets such as 1x4, 1x6, 1x8, or 1xN for characters, players, controllable heroes, creatures, NPCs, enemies, summons, animated props, or any asset where a body/subject must stay centered. Single-row raw generation is too likely to drift horizontally and crop inconsistently.
For animated body assets, use a multi-row grid by default: 4 frames -> 2x2, 6 frames -> 2x3, 8 frames -> 2x4, 9 frames -> 3x3, 12 frames -> 3x4 or 4x3, 16 frames -> 4x4.
If a game engine needs a final single-row strip or mixed atlas, first generate and QC the action as a multi-row grid, then assemble the delivery strip/atlas deterministically.
In every animated body grid prompt, require the subject body to stay centered in each cell, full body inside the central 60% to 70% safe area, consistent scale across cells, stable feet/bottom anchor line when applicable, and no limbs, weapons, hair, capes, dust, muzzle flashes, or detached FX crossing cell edges.
For hero attack body prompts, explicitly require body height and overall scale to match the accepted idle/run sheet's character size — phrasing like "the character body must be the same height and proportions as the loaded idle reference" + view_image of the prior idle sheet. Preserve will not normalize for you; the model has to produce matching scale, and view_image makes that achievable.
For map prop packs, classify props before choosing a grid. Square 2x2, 3x3, and 4x4 packs are only for compact props. Do not put platforms, floors, bridges, walls, ladders, gates, doors, long hazards, wide/tall props, collision-bearing objects, or tileset/strip pieces into square prop packs; use one-by-one, 1x3/1x4 strips, custom wide cells, or a tileset-like atlas instead.
Keep the solid #FF00FF background rule unless the user explicitly wants a different processing workflow.
characters / creatures / NPCs / enemies / bosses → --scale-strategy preserve --align feet (default for ALL their actions; pick once per character)
projectiles / impacts / item icons / pickups / UI / small grid-uniform assets → --scale-strategy fit
never mix strategies within one character's action set — that produces 25-36% body-height drift
