Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

Merge remote-tracking branch 'origin/main' into aldegad/run-deadline-retry-wait

Soohong Kim3157b2528698
diff --cc CHANGELOG.md
index dd3b86e,ed49cdb..bf9c35f
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -4,8 -4,7 +4,9 @@@ All notable public changes to `sprite-g
## Unreleased
+- **Behavior change: a refused provider request is sent again only within the time limit of its call, and the waits count in that limit.** Previously a request its provider documents as not taken (a 429, an overload) was sent again after 8 s and 16 s, or after the answer's `retry-after` (at most 120 s), twice, whatever time the call had left, and the time limits did not count those waits: `SPRITE_GEN_GEN_TIMEOUT_SECONDS` bounded each send of an OpenAI or Grok image and of the OpenAI facing check on its own, the Grok facing check's 120 s each read, the clip's poll timeout counted from the send xAI accepted, and a Message Batch's status and results reads waited outside `--batch-wait`. A caller that stops the run at its own ceiling, set above those limits, could kill a request taken after two refusals and hear nothing from the engine. Now each limit counts from the first send and holds the waits: the image calls and the OpenAI facing check count `SPRITE_GEN_GEN_TIMEOUT_SECONDS`, the Grok facing check its 120 s, each of their sends reading only what is left of it; the clip its poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`; the POST itself is still not cut, its answer being the one way to the request id); a batch's reads `--batch-wait`. A wait that would reach the limit is not waited: the refusal ends the call as any refusal does, after one stderr line, `[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — not asking again: the 16s wait would reach the time limit (12s left)`. The limit is read again after the wait, right before the send, as a sleep may wake later than it was asked to: one that woke at the limit or past it sends nothing either, and the refusal ends the call the same way (`… — not asking again: the time limit came during the 8s wait`). A clip's polls and downloads read their poll timeout the same way: a poll or download whose wait woke at it or past it is not sent, and the run ends unfinished on the last one as it came, where the one the transport found no time left to send was counted as a poll or download that got no answer (`timed out`). A realtime `pixel-draw` call has no time limit of its own and is unchanged.
+- **Tests** — `tests/gen/test_retry.py` (a request sent again only while its wait ends before the time limit; the answer's `retry-after` counted the same; a wait that ends at the limit not waited; a wait that woke at the limit or past it sends nothing, the limit read by one judgment, `too_late`, before the wait and right before the send; every direct provider call hands `retry` its limit; the Grok facing check and a Message Batch read whose wait woke past their limit send nothing), `tests/gen/test_openai_provider.py` and `tests/gen/test_grok_provider.py` (with 20 s, the second send waits only the 12 s left and the second 429 ends the call `sent 2 times`; with 8.01 s, an 8 s wait that woke 20 ms late sends nothing and the 429 ends the image call, or the OpenAI facing check, as it came), `tests/gen/test_video.py` (the poll timeout counts from the first send; a 429 whose next wait would reach it ends the run with its status, and so does one whose 8 s wait woke 20 ms past an 8.01 s timeout, with no second POST; a poll or a download whose wait woke past the timeout is not sent, and the run ends on the last one as it came), `tests/gen/test_pixel_draw.py` (each batch read is handed the end of `--batch-wait`). `tests/http_answer.py` is one offline HTTP answer the provider tests share, read whole or a chunk at a time under a deadline.
+ - **Behavior change: requests can pack sound without images.** Previously, a version 1 request required a nonempty `assets` list (refused with "assets must be a nonempty list"), and version 2 required at least one asset, image, tile, UI kit or icon (refused with "game pack request declares nothing to pack"), preventing games drawn in code from packing audio alone. In both versions, `assets` may now be empty or absent when sound is declared (see [docs/game-pack.md#sound-only-packs](docs/game-pack.md#sound-only-packs)). A sound-only request writes exactly `game-pack.json`, `audio-<id>.ogg`, `audio-<id>.m4a` and `sprite-gen-audio-v2.mjs` without atlas pages; its manifest sets `textures` to `[]` and `animations` to `{}` (version 2 also keeps empty `images`, `tiles` and `ui`), while audio entries, sound files and helper module bytes remain identical to packs with images. Requests declaring no assets, scene entries or sounds are refused in both versions with "game pack request declares nothing to pack: give it an asset, a scene entry or a sound" and write nothing. Packs with images (with or without sound) and packs without sound remain byte-for-byte unchanged, and repacking a sound-only request returns the same output. Tests: `tests/compose/test_game_pack_audio.py` (sound-only requests in versions 1 and 2 with `assets` empty or absent write only the manifest, sound files and helper; manifest matches image packs except for empty `textures` and `animations`; sound files and helper match bytes; repacking returns identical results; requests with neither images nor sound are refused without creating an output directory for version 1 and version 2). Synthetic fixtures only.
- **New verb: `video-stop` cuts a walk or run that stops from the clip's own start played backwards.** Given the clip's keyed frames and a walk or run loop (`--frames-dir`, `--loop`), it writes a one-shot strip (`<name>.strip.png`), sidecar (`loop: false`, `hold_last: true`), GIF, WebP, and report (`<name>.stop.report.json`). The stop leaves the loop from the cell nearest the entry (`from_cell`), the first frame after the opening rest within `SAME_POSE` (0.35 steps) of a loop cell, and ends on the clip's first frame, the still as filmed. A seam past the jump line (1.4 steps, `--seam-max`) is refused by `video-stop` with exit code 1 and `status: "failed"` in the report, and so is another motion in the run-up between the rest and the entry, however short: a run-up frame back within `SAME_POSE` (0.35 steps) of a pose the clip had left by `TURN_BACK_AWAY` (one step) or more (the still, or the run-up's own), refused with "the run-up turns back — another motion, that the stop would play backwards", naming the three frames (`turn_back`, the nearest such comeback, is reported either way). A run-up longer than `RUN_UP_MAX_CYCLES` (1.5 cycles) — `source_cut.length` frames, overridden by `--run-up-max` — which plays strides unlike the loop's, is refused with "strides unlike the loop's, that the stop would play backwards"; `--run-up-max` bounds only that length and never lets another motion through. The seam refusal, the another-motion refusal and the run-up refusal can all be named in one message. Drift is taken out by laying the entry on its cell and the first frame on the loop's ground and mean coverage, moving frames between by a straight share of the difference per step; a run leaning away moves the still a few pixels, and drift not straight leaves a little of itself. Strips wider than 32,000 px are refused, `--speed 2` plays every other frame (still kept last), `--max-frames N` spaces frames evenly, and frames shown pass the ghost screen (`interpolation_quality`) as filmed. The pose thumbnails (`gait_fallback.poses`, 48 px cut about the feet) are now public, as the verb reads poses with them ([video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop)).
- **New: a motion plays as its request says — `--play loop|once-return|once-hold|lifetime` — and `video-set --motion` gives each state or item its own motion text.** A state's name used to fix its sentence, its end-frame pin, its cut and whether its strip loops, so every new motion (a punch, typing at a desk, a block, a tool swing) was a change to the engine. `video-set --play STATE=MODE` or `ITEM=MODE` and `video-prompt --play MODE` take the mode as a value of the request, and `video-set --motion STATE=TEXT` or `ITEM=TEXT` the caller's words in place of the state's sentence (an item's own value wins over its state's; a key that names neither, a key given twice or a mode the state cannot play is refused before any clip). A word the engine does not name is filmed under that name in that mode: a once-return is pinned to end on its first frame, asked for as one action that returns to the first pose, and cut whole by the new `video-loop --cycle once-return` (every frame, the last too, gated by the pin), its `strip.json` saying `loop: false`, `hold_last: false`, `returns: true` with the first pose in its first and last cells; a once-hold is cut at its held pose (`once`), the first settled pose whose drawing is not its first — a shield raised inside a body outline that keeps its size and floor is one, the first drawing come back, in place or slid sideways, is not — while the six terminal states keep their body-geometry screen (any other state cut `--cycle once` is screened by its drawing too); a lifetime is framed and filmed as an effect whatever its name; a loop asked for is searched as a loop (`periodic`) and never failed over to a single play. Named states are presets: without `--play` every state is filmed, prompted and cut as before, and an attack played once-return is the same prompt and the same pinned clip, cut whole and played once. `effect`, the six terminal states and the cyclic states refuse any other mode. `set.report.json` records each item's `play` (and `motion`); `video-prompt --json` records `play`. Not measured on a clip model: the sentences for a motion of your own ([video-pipeline](docs/video-pipeline.md#play-modes)).
- **Tests** — `tests/video/test_play.py` (every named state given no mode is pinned, prompted and cut as before, and the same when its preset is named, save that a loop asked for is never failed over; a mode a state cannot play is refused; a once-return asked for pinned with its return sentence and cut whole, or searched where the source cannot pin; the attack played once-return is the attack's prompt; a named state played another way takes the mode's sentence; a once-hold with its end frame; a once-hold of your own ending on a new drawing inside the same body box cut at its held pose, the same clip as `cast` still refused by its body geometry, and one that comes back to its first drawing, in place or slid sideways, refused; a lifetime filmed as an effect whatever its name; a loop of your own; `video-set` modes and texts per state and per item, refused before any clip when a key or mode is wrong; a once-return that does not come back refused; a once-return cut subsampled with both ends kept and played once; the CLIs) and the once-return item filmed end to end in `tests/video/test_clip_prompt.py`, its strip's first and last cells the first pose. Synthetic fixtures only.