Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(pixel-draw): mark the verb experimental - its flags and report may change, and what a model draws varies from run to run
Soohong Kim4d86adade770
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ae25c8d..c20d08c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the## Unreleased-- **New: `sprite-gen pixel-draw` — Claude Opus draws pixel art of 8–48 px directly, as a pixel grid.** The model writes a palette and one line of keys per pixel row (a character grid, or JSON with `--format json`); code checks it and renders it. `--subject` (or `--spec`), `--size` 8–48 (32), `--kind sprite|icon|tile`, `--frames` (up to four, drawn in one call; `--walk-cycle` for contact, passing, contact, passing), `--palette free[:N]|pico8|#hex,…|file`, `--candidates` (2), `--effort medium|high|xhigh` (high), `--batch` (Message Batches, half price), `--max-tokens` (32000 for one frame, 64000 for more), `--pick vision|human`. G1 reads every answer strictly; a row one key too long or short, a key outside the palette or rows missing at the end go back to the model on their own with a column ruler and are spliced in (two rounds), and an answer still broken — or broken beyond its rows — is drawn once more; a single frame written without its `FRAME` line is recovered and recorded. G2 palette, G3 alpha and G6 frames (one ground line, heights within a pixel, no two frames the same) fail a candidate; G4 tile seam, G5 stray pixels and a walk whose legs barely change sides warn. Of two or more candidates that pass, one vision call at effort low picks (G7). An answer that spent every token thinking is drawn once more one effort lower; a refusal is reported as it came (`refused by the provider's content policy (stop_reason=refusal category=…)`); nothing falls back to another model. The run folder holds `grid.txt` (the truth: edit it and re-render with `--grid`), `palette.json`, `frame-<name>.png` written by an encoder whose bytes depend on the pixels alone, `preview-x<s>.png`, `tiled-3x3.png` for a tile, `anim.gif` for several frames, every call under `calls/` and `report.json` with each call's model, effort, usage (thinking tokens included), price, seconds and request id, the gate results and the repair history. A batch is recorded the moment it is submitted, and `--resume` collects it — and reads every answered call back — instead of buying it twice. It runs on `ANTHROPIC_API_KEY`, billed per call and said so on stderr; the transport is urllib, so the dependency surface stays Pillow and NumPy — [docs/pixel-draw.md](docs/pixel-draw.md).+- **New (experimental): `sprite-gen pixel-draw` — Claude Opus draws pixel art of 8–48 px directly, as a pixel grid.** The model writes a palette and one line of keys per pixel row (a character grid, or JSON with `--format json`); code checks it and renders it. `--subject` (or `--spec`), `--size` 8–48 (32), `--kind sprite|icon|tile`, `--frames` (up to four, drawn in one call; `--walk-cycle` for contact, passing, contact, passing), `--palette free[:N]|pico8|#hex,…|file`, `--candidates` (2), `--effort medium|high|xhigh` (high), `--batch` (Message Batches, half price), `--max-tokens` (32000 for one frame, 64000 for more), `--pick vision|human`. G1 reads every answer strictly; a row one key too long or short, a key outside the palette or rows missing at the end go back to the model on their own with a column ruler and are spliced in (two rounds), and an answer still broken — or broken beyond its rows — is drawn once more; a single frame written without its `FRAME` line is recovered and recorded. G2 palette, G3 alpha and G6 frames (one ground line, heights within a pixel, no two frames the same) fail a candidate; G4 tile seam, G5 stray pixels and a walk whose legs barely change sides warn. Of two or more candidates that pass, one vision call at effort low picks (G7). An answer that spent every token thinking is drawn once more one effort lower; a refusal is reported as it came (`refused by the provider's content policy (stop_reason=refusal category=…)`); nothing falls back to another model. The run folder holds `grid.txt` (the truth: edit it and re-render with `--grid`), `palette.json`, `frame-<name>.png` written by an encoder whose bytes depend on the pixels alone, `preview-x<s>.png`, `tiled-3x3.png` for a tile, `anim.gif` for several frames, every call under `calls/` and `report.json` with each call's model, effort, usage (thinking tokens included), price, seconds and request id, the gate results and the repair history. A batch is recorded the moment it is submitted, and `--resume` collects it — and reads every answered call back — instead of buying it twice. It runs on `ANTHROPIC_API_KEY`, billed per call and said so on stderr; the transport is urllib, so the dependency surface stays Pillow and NumPy — [docs/pixel-draw.md](docs/pixel-draw.md).- **Fix: a poll xAI answers 429 or 5xx asks the same request again — the clip is bought once.** `video`, `video-extend` and `video-edit` ended the run on any non-2xx poll, after xAI had accepted the request and may bill it, and the line read `(HTTP 429)` — what `video-set`, and any caller that backs off on a refused submission, answers by submitting the clip again: a second clip paid for, the first never published. A poll answered `429`, `500`, `502`, `503` or `504` is now asked again on the same `request_id`, after a wait that doubles from 8 s up to 60 s while the polls are refused and goes back to 4 s on an answer; a stderr note says each, the status in plain digits. The poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`) still bounds the whole poll, a pending poll's waits included (and, below, the downloads). A refused POST is still never sent again, and a `400` or `404` poll still ends the run with its status (a `401` or `403` poll is unfinished, below).- **Output change: a generation the poll timeout cut short is unfinished, named by its `request_id`.** Polls still pending or still refused at the timeout end the run with a line that names `request_id=<id>`, says the generation may still finish and be billed, and carries no `(HTTP <n>)`, a refusal line's status — a caller that reads `(HTTP 429)` there sends the request again, unbilled only when it was refused. The pending line keeps its front (`still 'pending' after N polls — poll timeout;`). With `--report` the run leaves a `sprite-gen-video-unfinished` report there (`verb`, `auth_source`, `model`, `request_id`, `out`, `polls`, `polls_refused`, `last_poll`, `elapsed_seconds`) and prints nothing on stdout; Python callers catch `GenerationUnfinished`, a `SystemExit`. The success report gains `polls_refused`, how many of its `polls` xAI answered 429 or 5xx (docs/video.md, An unfinished generation).- **`tests/gen/test_video.py`** scripts the polls: each of the five statuses refused twice, then pending, then done, is asked on the one request with waits 8, 16, 4 and published with `polls_refused` 2; polls refused until a 300 s timeout wait 8, 16, 32, 60 × 4, ask no poll whose wait would reach the timeout and end unfinished after eight with no `(HTTP n)` and no `HTTP 429` on stderr; a pending timeout names the request; a 400 or 404 poll ends at once; a refused POST is sent once; the CLI leaves the unfinished report and an empty stdout. The 500-poll case of the failure table is a 404 now, the status that still ends a run.diff --git a/docs/README.md b/docs/README.mdindex a42988e..7894212 100644--- a/docs/README.md+++ b/docs/README.md@@ -78,7 +78,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.| Doc | Owns ||---|---|| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage |-| [pixel-draw.md](pixel-draw.md) | `sprite-gen pixel-draw`: Claude Opus draws 8–48 px pixel art as a pixel grid — the inputs, the run folder and its report, gates G1–G7, the row repair and the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` |+| [pixel-draw.md](pixel-draw.md) | `sprite-gen pixel-draw` (experimental): Claude Opus draws 8–48 px pixel art as a pixel grid — the inputs, the run folder and its report, gates G1–G7, the row repair and the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` || [prompt-assembly.md](prompt-assembly.md) | What the engine adds to a still or clip prompt and when: the pieces, the 2.22.0 freeze without `--handed`, what counts as already said, and the notes on the caller's own words || [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit` / `video-resume`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing, asking again for an unfinished generation) with the user's own credential || [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch, a set's directions on one sheet |diff --git a/docs/pixel-draw.md b/docs/pixel-draw.mdindex 8d7a793..0e2395f 100644--- a/docs/pixel-draw.md+++ b/docs/pixel-draw.md@@ -1,5 +1,9 @@# `sprite-gen pixel-draw` — Claude Opus draws pixel art as a pixel grid+> **Experimental.** The verb, its flags and its report may change between versions, and the quality of what a model draws+> varies from run to run: expect to compare candidates, re-draw, or touch up `grid.txt` by hand. The numbers below come from a+> small set of measured runs, not from a benchmark.+> Owns: `sprite-gen pixel-draw`: the inputs, the run folder and `report.json`, gates G1–G7, the row repair, the one redraw, the pick between candidates, Message Batches and `--resume`, re-rendering an edited `grid.txt` · Index: [docs/README.md](README.md)The model does not paint an image that is then shrunk to a grid. It writes the grid itself: adiff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex 0bbebaa..679eeb9 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -322,7 +322,7 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab),# Same declaration-once rule: the module owns its argument surface (docs/pixel-draw.md)."pixel-draw": (- "Claude Opus draws 8..48 px pixel art as a pixel grid: gates, row repair, a pick of candidates; grid.txt is the truth, PNGs byte-reproducible (ANTHROPIC_API_KEY, billed per call).",+ "Experimental: Claude Opus draws 8..48 px pixel art as a pixel grid: gates, row repair, a pick of candidates; grid.txt is the truth, PNGs byte-reproducible (ANTHROPIC_API_KEY, billed per call).",pixel_draw.add_arguments,pixel_draw.run,),