spritesheet-gen

---
name: spritesheet-gen
description: Create animation sprite sheets as a uniform grid where each row is one action (idle, walk, attack, etc.) and each column is one animation frame in time order, using the codex-imagegen-backend skill for generation and the greenscreen skill for transparency. Use when an agent needs a multi-frame, multi-action sheet for a single character or object, sliceable into equal cells.
license: MIT
---

# Sprite Sheet Generation

## Role

High-level asset workflow for producing a single character or object as an animation sprite sheet. This skill owns the grid spec, prompting, slicing, and QA. It delegates image generation to `codex-imagegen-backend` and background removal to `greenscreen`. For standalone single-frame sprites, use `sprite-gen` instead.

Before generating, read the `codex-imagegen-backend` and `greenscreen` skills and use their bundled scripts as documented. Python 3 and Pillow are required for alpha validation, slicing, and resizing.

## Grid Semantics

These rules are fixed; state them explicitly in every prompt:

- **Rows = actions.** One action per row (idle, walk, run, attack, jump, hurt, death, ...), ordered top to bottom.
- **Columns = animation frames.** Time order runs left to right; frame 1 is the start pose. Every row has the same number of columns.
- All cells are uniform squares with no gutters, margins, labels, or grid lines. The character is centered in each cell with feet on a consistent baseline and nothing crossing cell boundaries.

## Sheet Spec

Collect one spec per sheet before generating:

- `name` and `output_path`: for example `assets/sheets/hero-walk-attack.png`.
- `subject`: the single character or object on the sheet.
- `style` and `view`: as in `sprite-gen`; side view is the usual choice for platformer sheets.
- `actions`: ordered list, one per row, each with a short motion description.
- `columns`: frames per action. Use the same count for every action; pick a direct-generation grid from the table below. If an action needs fewer frames, repeat its final pose in the trailing cells rather than leaving cells empty.
- `cell_size`: final cell size in the game, for example `128x128`.

## Canvas Size

For direct whole-sheet generation, use 256 px square cells and choose a backend `--size` where `width / columns == height / rows == 256`:

| Grid (columns x rows) | Generated cell | `--size` |
| --- | --- | --- |
| 4 x 4 | 256 px | `1024x1024` |
| 6 x 4 | 256 px | `1536x1024` |
| 4 x 6 | 256 px | `1024x1536` |
| 8 x 8 | 256 px | `2048x2048` |

For any other grid, use frame assembly: generate each frame as an individual transparent square with `sprite-gen`, keep the character and prior frame as references for continuity, resize every frame to 256x256, and composite them into a `columns * 256` by `rows * 256` RGBA canvas. This preserves square cells for grids such as 8 x 4 and 4 x 8 without stretching or ambiguous cropping.

## Workflow

1. Build the prompt from the spec. Enumerate every row and its frames explicitly:

   ```text
   Asset type: game animation sprite sheet, a strict <columns>x<rows> grid on a <width>x<height> canvas
   Subject: <one character/object description>
   Grid: exactly <rows> rows and <columns> columns of uniform <cell>x<cell> px square cells; no gutters, margins, borders, labels, numbers, or grid lines
   Rows (top to bottom, one action per row):
   - Row 1: <action>, frames 1-<columns> left to right showing <motion description>
   - Row 2: <action>, ...
   Columns: animation frames in time order left to right; frame 1 is the start pose; the motion should loop cleanly back to frame 1
   Consistency: identical character, outfit, palette, outline weight, scale, and camera angle in every cell; character centered in each cell, feet on the same baseline across each row, generous padding inside each cell, nothing touching or crossing cell boundaries
   Style/medium: <style>
   View: <side / front / three-quarter / top-down>
   Constraints: exactly one character per cell; no background scene; no ground plane or shadow; no text
   Avoid: watermark, signature, merged or overlapping cells, extra characters
   ```

2. For a direct-generation grid, make one backend call per sheet with the `--size` from the table and `--quality medium` or `high` (grid layouts degrade badly at `low`). For identity consistency with existing assets, pass an approved sprite from `sprite-gen` as `--reference-image` and add `Match the character and rendering style of image 1.`, following the backend's image-order rule. For a frame-assembly grid, follow the frame-assembly path above instead of asking the model for a geometrically invalid whole sheet.
3. For a direct-generation grid, get transparency the same way as `sprite-gen`: try `--background transparent --output-format png` first, validate alpha, and fall back to the `greenscreen` chroma-key workflow if the background came back opaque. Chroma-key the whole sheet in one pass before slicing. For a frame-assembly grid, preserve each frame's validated alpha while compositing and skip whole-sheet keying.
4. Slice the sheet into cells and inspect them:

   ```bash
   python -c "
   from PIL import Image
   from pathlib import Path
   im = Image.open('<sheet.png>')
   cols, rows = <columns>, <rows>
   if im.width % cols or im.height % rows:
       raise SystemExit('sheet dimensions are not divisible by the grid')
   cw, ch = im.width // cols, im.height // rows
   if cw != ch:
       raise SystemExit(f'grid cells are not square: {cw}x{ch}')
   frames = Path('<frames-dir>')
   frames.mkdir(parents=True, exist_ok=True)
   for r in range(rows):
       for c in range(cols):
           im.crop((c * cw, r * ch, (c + 1) * cw, (r + 1) * ch)).save(frames / f'row{r + 1}-frame{c + 1}.png')
   "
   ```

5. QA before reporting success:
   - Every cell contains the full character; nothing is cropped by or bleeds across cell boundaries.
   - Each row shows its assigned action, and frames progress left to right as a plausible animation.
   - The character's identity, scale, and baseline are consistent within each row and across rows.
   - Transparent background with no key-color fringe.
6. Iterate with a single targeted change per retry. For a direct-generation grid, if only one row is wrong, pass the sheet as `--edit-target` and prompt `Change only row <n> to show <action>; keep every other cell exactly unchanged.` If cells are misaligned with the grid, regenerate the whole sheet because alignment rarely survives edits. For a frame-assembly grid, regenerate only the incorrect frames and reassemble the canvas.
7. Downscale the final sheet so each cell equals `cell_size` (`Image.LANCZOS`, or `Image.NEAREST` for pixel art), then save at `output_path`.

## Output Handling

- Save the final sheet at the exact requested `output_path`; keep sliced frames only if the caller asked for individual frame files.
- Report the saved path, the grid (columns x rows, cell size), the row-to-action mapping, and the transparency path used (native or chroma-key).