# create_pixel_sprite

Create 1–4 small character sprite sheets from a description and optional PNG/JPEG reference.
Discover availability, price and limits with `GET /v1/tools`. MCP endpoint: `/mcp/image`.

Options are flat in MCP, nested in `options` for REST. `idempotency_key` is required: retain
it and the same arguments when retrying a lost response. Poll `get_job`; reconnecting does not
lose the job. Cancel with `cancel_job` while its `can_cancel` capability is true.

| Option | Values |
| --- | --- |
| description | Required, 1–4,000 characters describing one character |
| variants | 1–4 candidate sheets; default 1 |
| transparent | Attempt background removal; default true |
| palette_colors | 16, 32 or 64 shared colors; default 32 |
| palette | Optional 2–64 comma-separated `#RRGGBB` colors, no spaces; replaces automatic palette selection |
| frame_duration_ms | 40–1,000 in increments of 10; default 120 |
| seed | Optional integer 0–4294967295 |

For a reference, supply one `upload_id` or an owned `job_file: {job_id, name}` from a successful,
unexpired job. Omit both for text-only generation. Public URLs, raw file bodies, local paths,
workflow JSON and model selectors are not supported. Local references must be uploaded with
`create_upload` (or `POST /v1/uploads`) and its returned PUT URL first. Reference inputs are
capped at 20 MiB and the account's upload limit; decoded images must fit within 25 million pixels.

```json
{
  "description": "A forest ranger with a green hood and a brown satchel",
  "seed": 42,
  "idempotency_key": "pixel-sprite-example-004"
}
```

REST: `POST /v1/tools/create_pixel_sprite/jobs`, with `description` and `seed` inside `options`.
A new request returns 202; an identical replay returns the original job with 200. A changed
request with the same key returns `idempotency_conflict`. Failed or canceled jobs are refunded.

For each candidate N, download:

- `raw_N.png`: the original 512 × 512 image.
- `sprite_N.png`: a 128 × 128 sheet containing sixteen fixed 32 × 32 cells.
- `sprite_N.json`: palette, rectangles, pivots, animation sequences and QA checks.
- `sprite_N.zip`: raw image, sheet, sixteen frame PNGs, four walk GIFs, `manifest.json`,
  `qa.json`, and `provenance.json`.
- Each ZIP also includes `IMPORTING.md`, `godot/character.tscn`, `godot/sprite_frames.tres`,
  `unity/import.json` and `unity/MCPBytesSpriteImporter.cs.txt`.
- The job also includes `generation.json` with effective settings and version identifiers.

Rows are down, left, right and up. Columns 0–2 contain walk poses; the fourth column contains
arms raised, jump left, jump right and lying still poses respectively. Walk previews play
`[0,1,2,1]`: three generated poses, not four distinct poses. Extra still poses are not complete
jump or death animations. There are no arbitrary actions, eight directions or interpolated frames.

Read QA and inspect the images. `qa_status` is `unreviewed` or `needs_review`, never automatic
artistic approval. Check anatomy, identity, direction, clipping, alpha and enclosed regions.
Background removal may leave unsuitable renders opaque or need further review; keep the raw image.
Each frame keeps its original cell and pivot; the palette is shared across the whole character.
Higher playback speed does not create more motion detail.

Only complete successful jobs publish files. Read the job again for fresh download URLs before
`outputs_expire_at`; download retention and URL expiry are separate.

## Preview and engine setup

The console's job page can play all four directions together, pause, step frames, change preview
speed and pixel zoom, switch light/dark/checkerboard backgrounds, and compare candidates. Select
a candidate to download its sheet or ZIP. These controls do not modify the exported files.

For Godot 4, extract the ZIP inside your project without moving its files relative to each other.
Drag `godot/character.tscn` into a scene; its `SpriteFrames` resource carries the atlas regions,
loop flags and frame timing. The scene uses nearest filtering and a bottom-center origin.

For Unity 6, install the **2D Sprite** package. Install the helper once per project by copying
`unity/MCPBytesSpriteImporter.cs.txt` to `Assets/Editor/MCPBytesSpriteImporter.cs`.
Extract each candidate into its own folder under `Assets`, select its `unity/import.json`, and
choose **Tools > MCPBytes > Import selected sprite export**. The helper creates the sprites,
four AnimationClips, an Animator Controller and a prefab with bottom-center pivots. Repeated
imports create a new output folder and preserve existing sprite IDs. Read `IMPORTING.md`.

Engine setup files are included in newly generated ZIPs. Earlier jobs keep their original files;
the console preview also supports their existing sprite metadata.

## Without MCP

Save the options object in `sprite-options.json`:

```json
{"description":"A forest ranger with a green hood and a brown satchel","seed":42}
```

```bash
python scripts/mcpbytes.py run create_pixel_sprite \
  --options-json sprite-options.json \
  --idempotency-key pixel-sprite-example-004 --out sprites/
```

Add `--upload-id <finished-upload-id>` or `--job-file <job-id> <name>` for a reference. Do not
give a local image as the positional file argument: that mode sends a raw body, which this tool
does not accept. The console performs the upload for you.

Actionable errors: `invalid_image` (reference decoding or bounds), `invalid_options` (unsupported
option combination), `invalid_output` (unusable output), `out_of_memory`, `timeout`, and
`capacity_exhausted` (retry later). A technical success still needs visual review.