---
name: generate-pixel-animation-asset
description: Bridge generated 2D pixel sprite sheets into game-ready animation assets. Use when Codex needs to create, finish, repair, or export pixel-game characters, enemies, NPCs, props, projectiles, FX, or action sheets by orchestrating agent-sprite-forge/$generate2dsprite generation, pixel-spritesheet-slicer cut plans, transparent frame PNG export, preview GIF/contact-sheet QA, and runtime manifest handoff for web games, Godot, Unity, Phaser, or custom 2D engines.
---

# Generate Pixel Animation Asset

## Overview

Turn a prompt, reference image, or existing sprite sheet into animation assets a game can load directly: transparent frame PNGs, action folders, preview GIFs/contact sheets, and a runtime manifest.

This skill is a bridge. Use Agent Sprite Forge for generation and regular grid post-processing; use Pixel Spritesheet Slicer when the generated sheet needs explicit crop rectangles, action classification, or fragment cleanup.

## Workflow

1. Establish the target contract: engine/runtime, asset role, view, required actions, loop/once behavior, target folder, and whether the game needs fixed cells, variable-size frames, or an atlas.
2. If no usable source image exists, generate the raw art with Agent Sprite Forge. Prefer one coherent action per raw sheet. For heroes and high-value characters, generate `idle`, `run/walk`, `attack/shoot/cast`, `hurt`, `jump`, and separate FX/projectile/impact sheets independently before assembling any engine atlas.
3. Run Forge post-processing first for regular grids: magenta cleanup, frame extraction, alignment, shared scale, transparent sheet/frame export, GIF preview, and `pipeline-meta.json`.
4. Decide whether Forge output is enough. Accept it only when `edge_touch_frames` is empty, visual GIF/contact review passes, action labels match the poses, scale/feet anchors are stable, and the runtime can use the exported frames or sheet without live slicing.
5. If the sheet is irregular, mixed, mislabeled, edge-fragmented, or needs per-action variable crop boxes, switch to Slicer. Use `scripts/forge_meta_to_cut_plan.py` to create a starter cut plan from Forge metadata, then manually tighten rectangles by visual inspection.
6. Run Slicer export, margin check, and contact-sheet QA. Iterate the cut plan until no frame includes adjacent sprites, missing limbs, stale fragments, or unrelated effects.
7. Create preview GIFs from the final manifest with `scripts/manifest_to_gifs.py` when Slicer output did not already include GIFs.
8. Run `scripts/validate_animation_asset.py` before delivery. The final handoff should include `assets/frames/<action>/<NN>.png`, `assets/frames/manifest.json`, visual previews, and any engine-specific wiring notes.

## Decision Gate

Use Forge direct output when:

- The generated sheet is a clean grid and each frame belongs to one action.
- Fixed cell sizes and shared scale are acceptable for the target runtime.
- The transparent sheet, individual PNGs, and GIF are visually coherent.
- The animation does not need hand-authored action grouping or crop-specific component filtering.

Escalate to Slicer when:

- Generated cells have uneven spacing, extra subjects, or bad row/column assumptions.
- Browser or engine background-position slicing creates duplicates, wrong actions, or edge fragments.
- Wide slash arcs, spell effects, hearts, dust, or projectiles need `keepDistance` or `keepAll`.
- A single source sheet contains multiple action groups that must become named folders and manifest entries.
- The game should load pre-cut PNG frames instead of slicing a sheet at runtime.

Regenerate rather than over-fix when:

- The character identity changes between frames.
- A body action shrinks because detached FX widened the bounding box.
- Major limbs/weapons are cropped in the source image.
- The requested animation cannot be read as a coherent motion sequence.

## Core Commands

Read `references/upstream-contracts.md` for source paths and detailed command patterns.

Create a starter cut plan from Forge metadata:

```powershell
python .\scripts\forge_meta_to_cut_plan.py `
  --meta ".\runs\hero-idle\pipeline-meta.json" `
  --action idle `
  --speed 180 `
  --output ".\tmp\idle-cut-plan.json"
```

Export Slicer frames:

```powershell
powershell -ExecutionPolicy Bypass -File ".\.upstreams\pixel-spritesheet-slicer\scripts\export-action-frames.ps1" `
  -PlanPath ".\tmp\idle-cut-plan.json" `
  -OutputDir ".\assets\frames"
```

Generate manifest preview GIFs:

```powershell
python .\scripts\manifest_to_gifs.py `
  --frames-root ".\assets\frames" `
  --output-dir ".\assets\previews"
```

Use a Python environment with Pillow for GIF generation. In Codex Desktop, the bundled workspace Python is a good fallback when the default `python` lacks Pillow.

Validate the final package:

```powershell
python .\scripts\validate_animation_asset.py `
  --frames-root ".\assets\frames" `
  --gifs-dir ".\assets\previews"
```

## Quality Bar

- Prefer original generated art plus deterministic processing; do not replace requested sprites with code-drawn placeholders.
- Keep action names truthful to the poses, not merely row names.
- Preserve gameplay-meaningful effects only when they belong to the action frame.
- Use visual review for the final contact sheet or GIFs; automated margin checks are necessary but not sufficient.
- Hand off pre-cut transparent PNGs and a manifest. Do not leave the game dependent on live browser-side sheet slicing when this skill was invoked to produce production-ready animation assets.

## Resources

- `scripts/forge_meta_to_cut_plan.py`: convert Forge `pipeline-meta.json` into a Slicer-compatible starter cut plan.
- `scripts/manifest_to_gifs.py`: build one preview GIF per manifest action.
- `scripts/validate_animation_asset.py`: validate manifest structure, referenced PNG frames, optional alpha, and optional GIF previews.
- `references/upstream-contracts.md`: concise contract for Agent Sprite Forge and Pixel Spritesheet Slicer.
- `references/output-contract.md`: final runtime asset shape and engine handoff guidance.