sprite-animation-assets

Sprite Animation Assets

Core assessment

The key to animation assets is not that “a single image looks good,” but that the same character or object maintains consistent identity and consistent size in every frame, has a transparent background, and has an action that can loop. First define the frame specifications and states, then generate images group by group, and finally use a script to assemble and validate.

Suitable output: continuous-frame PNGs, single-state GIFs, transparent spritesheets, fixed-grid atlases, web/game animation assets.

Not suitable output: a single transparent asset; route this type to $transparent-visual-assets。

Workflow

1. Define specifications: state names, number of frames per state, canvas size, output format.
2. Generate or confirm one canonical base image to serve as the identity anchor for all frames.
3. Generate continuous frames by state; each group of frames must use the same character reference and the same solid-color background or transparent-background strategy.
4. Visual QA: consistent identity, coherent motion, no floating debris, no text, no ground shadow, no cropping.
5. If needed, first use $transparent-visual-assets to process each frame into a transparent PNG.
6. Use scripts/compose_sprite_set.py to assemble the atlas, and optionally export a GIF preview for each state.
7. Check sprite-set-report.json, then open the atlas/GIF for final validation.

Key points for image generation prompts

Each animation group must lock identity:

Create <frame_count> separated frames of the same <subject> for a looping sprite animation.
Keep the same silhouette, proportions, face, palette, outline style, and accessories in every frame.
Use a flat removable background color <background_color>, with no shadows, text, scenery, motion trails, frame numbers, grid lines, or detached decorative effects.
Each pose must be fully visible, separated from the next pose, and safe to crop into a transparent frame.
Action: <state_action>.

If you need an atlas specification compatible with a Codex custom pet, first read references/sprite-atlas-layouts.md, and use the official hatch-pet extracted 8x9, 192x208, 9-row state convention.

Assembly script

Prepare the manifest:

{
  "cell_width": 192,
  "cell_height": 208,
  "columns": 8,
  "states": [
    {
      "name": "idle",
      "row": 0,
      "frames": ["idle_000.png", "idle_001.png"],
      "durations_ms": [120, 120]
    }
  ]
}

Run:

python "${CODEX_HOME:-$HOME/.codex}/skills/sprite-animation-assets/scripts/compose_sprite_set.py" \
  --manifest /absolute/path/manifest.json \
  --frames-dir /absolute/path/frames \
  --output-atlas /absolute/path/spritesheet.png \
  --output-dir /absolute/path/qa \
  --gif

The script will:

• Center each frame into a fixed cell.
• Keep unused cells fully transparent.
• Output sprite-set-report.json。
• When using --gif , export one GIF preview for each state.

Acceptance criteria

• The number of frames for each state matches the manifest.
• The same character/object maintains the same identity in all frames, without changing species, face, or color scheme.
• All frames have a transparent background or can be cleanly cut out to a transparent background.
• The action can loop, with no obvious jump between the first and last frame.
• Unused cells in the spritesheet must be completely transparent.
• GIFs are only previews; for final web/game assets, prioritize delivering PNG frames or a transparent atlas.