generate2dsprite

name	generate2dsprite
description	Generate and postprocess 2D game sprites and animation sheets: pixel-art characters, NPCs, creatures, spells, projectiles, impacts, props, summons, and transparent PNG/GIF exports. Use when building browser games that need real sprite sheets (not code-drawn placeholders), matching a map art style, or producing magenta-background sheets for chroma-key cleanup. Triggers on "sprite", "sprite sheet", "animation sheet", "pixel art character", "walk cycle", "attack animation", "projectile sprite", "2D game asset".
metadata	{"short-description":"2D sprite sheets: imagine_image + magenta chroma postprocess"}
user-invocable	false

Generate2dsprite

Use this skill for self-contained 2D sprite or animation assets in the app-builder sandbox (TanStack Start + browser games).

When a larger game or playable prototype needs sprites, use this skill for the visible sprite assets and keep runtime/game assembly separate (wire into Phaser / Canvas / DOM after export). Do not replace requested sprite assets with code-drawn placeholders.

App-builder / Grok environment

Item	Value
Skill dir	.grok/skills/generate2dsprite/
Scripts	python3 .grok/skills/generate2dsprite/scripts/<script>.py …
Image tools	imagine_image + imagine_view_media / imagine_create_asset, or the older generate_image / edit_image where those are what the tool list has (see imagine skill for prompt craft)
Inspect images	read_file on the PNG path (not Codex view_image)
Generated image path	imagine_image returns an asset_id; call imagine_view_media to download it into the sandbox, then copy that path into your run dir before processing
Python deps	Pillow + numpy (preinstalled in the image)
Output home	Prefer assets/sprites/<name>/ under /workspace so the app can import them
Engine target	Browser: Canvas 2D, Phaser, or DOM/<img> — not Godot/Unity unless the user asks

Related skills: imagine (image tool usage), game-asset-core (+ game-animation-frames / game-character-consistency for QC and engine-ready defaults), generate2dmap (maps/props), video2dsprite (denser motion via imagine_video), building-games (game loop / integration).

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
• view: topdown | side | 3/4
• sheet: auto | 2x2 | 2x3 | 2x4 | 3x3 | 3x4 | 4x4 | 5x5 | custom_grid | strip_1x3 | strip_1x4
• frames: auto or explicit count
• bundle: single_asset | unit_bundle | spell_bundle | combat_bundle | line_bundle | hero_action_bundle | engine_atlas
• effect_policy: all | largest
• anchor: center | bottom | feet
• margin: tight | normal | safe
• art_style: pixel_art | clean_hd | pixel_inspired | retro_pixel | map_style | project-native
• reference: | | |

Read references/modes.md when the request is ambiguous.

Agent Rules

• 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.
• For controllable heroes, main characters, and high-value player body actions, default attack/shoot/cast body sheets to body-only. Do not include large slash arcs, muzzle flashes, projectiles, impact bursts, detached dust, long trails, or wide detached FX in the body sheet. Generate those as separate fx, projectile, or impact sheets and layer them in the game.
• Only include wide attack FX in the same raw body sheet when the target runtime explicitly supports wider per-action cells plus per-action origin/anchor metadata. Otherwise, a wide FX bbox will force the body to shrink inside the fixed cell.
• Write the art prompt yourself. Do not default to the prompt-builder script.
• Use built-in imagine_image 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 imagine_image.
• When the user provides or implies a visual reference, pass that reference to imagine_image as an asset_id (register a sandbox file with imagine_create_asset first). Also call read_file on a local reference so you can see it; never rely on a filesystem path inside 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.

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

2. Write the prompt manually

Use references/prompt-rules.md.

Choose art_style before writing the prompt:

• 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:

• Wire the reference into the call: pass its asset_id in asset_ids (freshly generated references already have one; register local files with imagine_create_asset first; file paths on the older split tools). Also read_file local references so you can see them.
• 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 imagine_image 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 imagine_image 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 imagine_image:

python3 .grok/skills/generate2dsprite/scripts/make_layout_guide.py \
  --rows <rows> \
  --cols <cols> \
  --cell-width 384 \
  --cell-height 384 \
  --output <run-dir>/references/<rows>x<cols>-layout-guide.png

Then register the guide with imagine_create_asset and pass its asset_id in asset_ids on the imagine_image call (file path on the older split tools) — a guide that is only "visible in conversation" never reaches the image model. Also read_file it so you can see the geometry. Tell imagine_image 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 imagine_image.

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:

• keep the returned asset_id, then call imagine_view_media to download the image into the sandbox
• copy that file into the working output folder as raw-sheet.png (or similar)
• keep the original generated image in place
• to run a further Imagine edit on a postprocessed PNG, register it first with imagine_create_asset and pass the new asset_id

4. Postprocess locally

Run the processor on the raw image:

# --target is ONLY: player | npc | creature | asset
# Map character/spell/projectile/prop/summon/fx → --target asset (or player/npc/creature).
# --mode must be a known grid mode (idle/walk/attack/shoot/jump/…) OR pass both --rows and --cols.
python3 .grok/skills/generate2dsprite/scripts/generate2dsprite.py process \
  --input <run-dir>/raw-sheet.png \
  --target <player|npc|creature|asset> \
  --mode <idle|walk|run|attack|shoot|jump|cast|hurt|projectile|impact|fx|player_sheet|…> \
  --output-dir <run-dir> \
  --shared-scale \
  --align feet
# Custom grid example:
#   --mode sheet --rows 2 --cols 3 --label-prefix frame

List valid targets/modes: python3 …/generate2dsprite.py list-options

The processor is intentionally low-level. The agent chooses:

• rows / cols
• fit_scale
• align
• shared_scale
• component_mode
• component_padding
• 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=largest for body-only hero grids. Use component_mode=all only for projectile, impact, aura, slash FX, or intentionally detached FX sheets, not for fixed-cell hero body attacks that need stable body scale.

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

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
  • attack/shoot/cast body sheets are body-only by default; wide slash arcs, muzzle flashes, projectiles, trails, dust, and hit impacts are separate FX/projectile/impact sheets
  • 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 largest component mode for hero/player body grids; use all for separate FX/projectile/impact sheets

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