Skip to content

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

docs(video): a once-hold of your own ends on a drawing other than its first; the terminal states keep their body-geometry screen

Soohong Kime33789025b94
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1442b9c..9e8eeff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
-- **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`); 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 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.
+- **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.
- **Behavior change: `pixel-draw` runs on your Claude subscription first, and on `ANTHROPIC_API_KEY` only without one** — the order `codex` and `grok` keep. When `claude auth status` says Claude Code is signed in with a subscription (`claude.ai` or `oauth_token`), every call — the drawings, the row repairs, the pick — goes through the unmodified `claude` binary in print mode, from an empty directory, with no tool, no session written and no CLAUDE.md, hook, skill, plugin or MCP server loaded, and costs nothing per call: `report.json` says `auth_source: claude-login`, each call's `mode` is `subscription` and its `cost_usd` `0`, its usage kept. The child never sees `ANTHROPIC_API_KEY`, which print mode would use instead of the login. Without a subscription login the run uses the key as before, billed per call and said on stderr; with neither it is refused naming both, before the run folder is made. A login that refuses a call, has expired or has reached its usage limit fails the call; the run never switches to the key on its own. `--batch` is the API's Message Batches and runs on the key even when signed in. An answer the binary continues past the output cap is read whole from every message, not from its `result`, which holds only the last part; one it cannot finish is read as `stop_reason: max_tokens`, so the one redraw one effort lower happens on either route. One call may take up to `SPRITE_GEN_CLAUDE_CALL_TIMEOUT_SECONDS` (1800). When candidates ask at once, none of their requests leaves before the billing line has been printed. `report.json`'s `auth_source` is what the calls ran on by their records, `mixed` (with `auth_sources`) for a run resumed under the other credential. A `--resume` that reads every call back no longer prints the billing line ([pixel-draw](docs/pixel-draw.md#which-credential-a-call-runs-on)).
- **Behavior change: every metered call says so on the terminal, and every report names what a call ran on.** How codex is signed in is one reading, `codex_provider.codex_login` (`codex login status`), for the default provider resolution, `gen --provider codex`, the codex facing check and `workflow`: a codex signed in with an API key used to run with no word about it and the workflow called it a subscription; it now prints the per-call charge line before `codex exec` runs, its report records `extra.auth_source: codex-api-key` (`codex-login` on ChatGPT), and `workflow` asks to confirm the API credit. A codex that is not signed in is refused with the reason before it runs. `gen-set` and `video-set` keep each item's output in its log, but a child's billing line and a default provider switch now also print on the terminal as they happen (`base.run_logged`), each `gen-set` row records `auth_source`, and each `video-set` clip result too. `sound` prints the same billing line as every other metered route (it printed its own) and its receipt records `auth_source`. One function reads a provider key from the environment (`base.env_api_key`: a key, none, or a refusal of an empty one) for Anthropic, OpenAI, xAI and ElevenLabs; one function says what to do when xAI rejects a credential (`xai.rejected_fix`), so `gen --provider grok` now gives the same `grok models` refresh as `video`. `workflow` probes a provider once for its images and videos (they share one credential) and asks the API-credit question by that provider's name rather than always about Grok video. Docs: the credential table in the README, grok's `XAI_API_KEY` route in the help and SKILL.md, the sound billing line, `SPRITE_GEN_GEN_TIMEOUT_SECONDS` and `SPRITE_GEN_CLAUDE_READ_TIMEOUT_SECONDS`, and `gen-set --provider` (`codex` or `grok`).
@@ -42,7 +42,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- Added `sprite-gen sound` CLI and game-pack audio integration for ElevenLabs SFX/BGM generation, featuring SQLite request deduplication, cosine loop crossfading, multi-pass FFmpeg loudnorm/alimiter normalization, dual Opus/AAC encoding, and Web Audio loop boundary metadata.
-- Added `--cycle once` nonloop motion support with automatic selection for `death`, `fall`, `land`, `cast`, `hurt_hold`, and `transform`, rejection on cyclic states, no seam gate or wrap correction, and a terminal stability gate searching the whole clip for the first stable terminal window ($K = \max(4, \lceil\text{fps} \times 0.2\rceil)$) after action departure (ending at window end, discarding later recovery or shaking), with conservative candidate end pose geometric screening (alpha >= 8 body boxes; height <= 80% of initial for `death`/`fall`, changed geometry for other states) and retained cut edge contact validation (ignoring discarded tail).
+- Added `--cycle once` nonloop motion support with automatic selection for `death`, `fall`, `land`, `cast`, `hurt_hold`, and `transform`, rejection on cyclic states, no seam gate or wrap correction, and a terminal stability gate searching the whole clip for the first stable terminal window ($K = \max(4, \lceil\text{fps} \times 0.2\rceil)$) after action departure (ending at window end, discarding later recovery or shaking), with conservative candidate end pose geometric screening (alpha >= 8 body boxes; height <= 80% of initial for `death`/`fall`, changed geometry for the other named states) and retained cut edge contact validation (ignoring discarded tail).
- Added nonloop-only flags `video-prompt --end-frame final.png` (refuses `--no-last-frame`, prints instructions without image validation) and `video-set --end-frame ITEM=PATH` (checks final canvas dimensions and corner key match initial canvas), with clip cache tracking end-image SHA256 where changed end pins reject until user explicitly `--force` regenerates.
- Added endpoint-preserving strip downsampling with candidate events (`events:[{"frame": n, "name":"motion_peak"}]` using zero-based output cell indices mapped to keyed source frames via `source_cut.samples`) and `once` preview handling, with nonloop cycles insisting on existing `--anchor none` and `--fit state` while rejecting non-none anchor and tight fit.
diff --git a/docs/states-and-frames.md b/docs/states-and-frames.md
index 6399b3f..2b56e84 100644
--- a/docs/states-and-frames.md
+++ b/docs/states-and-frames.md
@@ -12,7 +12,7 @@ Six states automatically select `once` across `sprite-gen video-prompt`, `sprite
These defaults are presets. `--play loop|once-return|once-hold|lifetime` (`video-set`, `video-prompt`) films a motion in the mode the request names — a named state, or a word of your own described with `--motion` (a punch, typing at a desk, a block) — and the end-frame pin, the prompt's ending, the cut and the strip's `loop` follow it. The six states below play once-hold only, `effect` lifetime only, and the cyclic states loop only. See [play modes](video-pipeline.md#play-modes).
-Motion prompts request a 0.4 s hold. Anatomy is preserved across body plans (`quadruped`, `legless`). Headroom requires symmetric side margins for `death` and `hurt_hold`, overhead room for `cast` and `transform`, and descent room for `land`; border contact is refused. Candidate end pose geometry requires median end-window height <= 80% of initial height for `death` and `fall`, while other `once` states require changed geometry (conservative geometric screen; inspect semantic pose visually). Root displacement metadata is omitted. See [video-pipeline.md](video-pipeline.md) for gate and metadata details.
+Motion prompts request a 0.4 s hold. Anatomy is preserved across body plans (`quadruped`, `legless`). Headroom requires symmetric side margins for `death` and `hurt_hold`, overhead room for `cast` and `transform`, and descent room for `land`; border contact is refused. Candidate end pose geometry requires median end-window height <= 80% of initial height for `death` and `fall`, while the other four require changed geometry (conservative geometric screen; inspect semantic pose visually). A motion of your own played once-hold, or any other state cut `--cycle once`, is screened by its drawing instead, so a pose that changes inside an unchanged body outline counts and the first drawing come back does not ([terminal gate](video-pipeline.md#video-processing-pipeline-and-terminal-gate)). Root displacement metadata is omitted. See [video-pipeline.md](video-pipeline.md) for gate and metadata details.
| State | End Pose |
|---|---|
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 986e16b..3292882 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -726,7 +726,7 @@ sprite-gen video-loop --frames-dir frames/keyed --fps 24 --state death --cycle o
In the sequence above, replace 24 with the `fps` value from `frames.report.json`. For batch operations, `sprite-gen video-set --end-frame` takes `ITEM=PATH` (e.g., `--end-frame side-death=final.png`). With no seam gate or wrap correction, nonloop insists on `--anchor none` and `--fit state`, with no optional override to anchor; nonloop states reject non-none anchor and tight fit. See [states-and-frames.md](states-and-frames.md) for the state table.
-For `--cycle once`, the terminal gate searches the whole clip for the first stable terminal window of $K = \max(4, \lceil\text{fps} \times 0.2\rceil)$ frames after action departure, then ends at the window end and discards later recovery or shaking. Across the window, pairwise window distance diameter divided by median subject mass must be $\le 0.025$ (premultiplied RGBA thumbnail difference divided by median terminal subject mass), detecting jitter and slow drift regardless of canvas padding. The first frame precedes departure from the initial pose. The gate refuses clips with no action; the retained cut must have a visible body and no alpha >= 8 pixels touching any source edge, ignoring the discarded tail for that check. Candidate end pose geometry uses alpha >= 8 body boxes, rejecting candidates as returned starting geometry if height and width/height ratio are each within 5% of initial and bottom movement is <= 2% of initial height. `death` and `fall` require median end-window height <= 80% of initial height, while other `once` states require changed geometry. This provides a conservative geometric screen; inspect semantic pose visually.
+For `--cycle once`, the terminal gate searches the whole clip for the first stable terminal window of $K = \max(4, \lceil\text{fps} \times 0.2\rceil)$ frames after action departure, then ends at the window end and discards later recovery or shaking. Across the window, pairwise window distance diameter divided by median subject mass must be $\le 0.025$ (premultiplied RGBA thumbnail difference divided by median terminal subject mass), detecting jitter and slow drift regardless of canvas padding. The first frame precedes departure from the initial pose. The gate refuses clips with no action; the retained cut must have a visible body and no alpha >= 8 pixels touching any source edge, ignoring the discarded tail for that check. A named terminal state's candidate end pose is screened by its geometry on alpha >= 8 body boxes, rejecting candidates as returned starting geometry if height and width/height ratio are each within 5% of initial and bottom movement is <= 2% of initial height. `death` and `fall` require median end-window height <= 80% of initial height, while `land`, `cast`, `hurt_hold` and `transform` require changed geometry. This provides a conservative geometric screen; inspect semantic pose visually. Any other motion cut `once` — a once-hold of a word of your own ([play modes](#play-modes)), or `--cycle once` on `jump`, `attack` or another state — is screened by its drawing instead: each end-window frame is moved sideways until its body box is centred where the first frame's is, and its median distance from the first frame (premultiplied RGBA thumbnail difference divided by the subject mass, as the action departure is read) must exceed 0.05. Its body box may keep its size and floor, so a shield raised across the chest is an end pose, while the first drawing come back, in place or slid sideways, is refused as the starting pose. The report's `cycle.terminal.pose` records the screen: `profile` `ground` or `changed` with the geometry ratios, or `drawing` with `departure`, `departure_min` and `shift_px` (the sideways move taken out).
Strip and preview downsampling preserves start and end endpoints. Strip metadata includes `loop: false`, `hold_last: true`, `end_frame`, and candidate `events:[{"frame": n, "name":"motion_peak"}]`. Strip `end_frame` and event `frame` are zero-based output cell indices. Report `cycle.end_frame` and `cycle.event_frame` are keyed source frame indices. `source_cut.samples` maps each strip output cell to its keyed source frame; they are not numerically equal after trimming/subsampling. WebP previews set `loop=1`, GIF previews omit loop extension, and decoded preview verification enforces `once` behavior.
@@ -1151,7 +1151,7 @@ sprite-gen video-set --base side=side.png --base front=front.png --states idle,p
|---|---|---|---|---|
| `loop` | as the state is filmed: an idle or attack pinned to its first frame, a walk or run pinned in a diagonal view, any other unpinned | an evenly paced repeat, or the return to the first pose where pinned | `pinned` for an idle or attack, otherwise `periodic` | `loop: true` |
| `once-return` | pinned to end on its first frame | one action, then the first pose again (after your text: `It does this once, then returns to the exact pose of the first frame.`) | `once-return`: the whole clip, its last frame too, gated by the pin | `loop: false`, `hold_last: false`, `returns: true`; the first and last cells are the first pose |
-| `once-hold` | unpinned (`--end-frame ITEM=PATH` pins a terminal pose) | one action, its last pose held still for 0.4 s | `once` | `loop: false`, `hold_last: true` |
+| `once-hold` | unpinned (`--end-frame ITEM=PATH` pins a terminal pose) | one action, its last pose held still for 0.4 s | `once`: the first settled pose whose drawing is not its first, a change inside an unchanged body outline included (a terminal state's by its own body geometry) | `loop: false`, `hold_last: true` |
| `lifetime` | framed as an effect and pinned to an empty black frame | an effect that appears and is gone | `lifetime` | `loop: false`, `blend: add` |
`STATE=…` applies to every view of that state and `ITEM=…` (`side-punch=…`) to one item, whose own