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: document terminal window selection and end-frame inputs

Soohong Kim02c751e1684b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49f5a23..f7fb187 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
+- 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 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.
+
- **Behavior change: a flag given together with a file that holds the same key wins, and one stderr line says so — for `prepare --request` / `--request-json` and `pixel-draw --spec` alike.** `pixel-draw` refused the pair; `prepare` let the flag win for most keys in silence, and let the request win for three: `--style`, `--cell-size` and `--safe-margin` were dropped when the request carried a style, a cell size or a margin. Now every such key takes the flag and the run says `[prepare] --style, --cell-size given both as a flag and in --request-json: the flag wins` (`gen.base.flags_over_spec`, the one answer, [run contract](docs/run-contract.md#1-pipeline-stages)). A cell flag replaces the measure however the request spelled it (`size`, `width`, `cell_width`). `prepare`'s note no longer lists a request's `subject` among the keys it drops — it was always carried.
- **Behavior change: an answered provider request is sent again only when the provider documents the answer as a request it did not take — one rule for every direct call.** `gen`'s OpenAI and Grok image POSTs, the facing check and the clip POST of the video verbs were never sent again, and `pixel-draw`'s Anthropic transport sent 429 and every 5xx again after 10 s and 30 s. Now each asks `gen.retry`: OpenAI 429 (but its billing codes — a spent credit balance, a spend or usage limit, `insufficient_quota` — which ask you to act) and 503 overloaded; xAI 429; Anthropic 429 (but its spend cap), 500 and 529 — read off each provider's error and rate-limit pages on 2026-10-13 ([a refused request sent again](docs/gen.md#a-refused-request-sent-again)). Not sent again any more: Anthropic 502, 503 and 504 (`timed out while processing`). The wait is the answer's `retry-after` when it is at most 120 s (a longer one is not cut short: the request is not sent again), else the doubling the video polls already waited by, 8 s then 16 s; twice at most, each on stderr as `[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — asking again in 8s (1 of 2)`. A refusal still there ends the call as before, its line saying `sent 3 times, no provider fallback` in place of `no retry or provider fallback`. A request with no answer it could read is still never sent again. `video-set` runs each clip once: its own rerun of a clip whose log said `HTTP 429` (15 s, 30 s) is gone, as it made every POST a second retry loop on top of the first. The video polls and downloads also ask again on `529`.
- **Fix: a refusal whose body broke on the way is no answer on every transport.** `xai.http_json` already said so; `openai-gen` let the broken read escape as a traceback, and `pixel-draw`'s Anthropic transport read it as a refusal with an empty body (and sent a 429 or 5xx again). Both now end as a request that got no answer — the server may have taken it — through the one reader of a refusal's body, `xai.error_body`. An OpenAI answer cut short (`IncompleteRead`) is that line too, not a traceback.
diff --git a/docs/states-and-frames.md b/docs/states-and-frames.md
index 83386ef..c8a1325 100644
--- a/docs/states-and-frames.md
+++ b/docs/states-and-frames.md
@@ -4,6 +4,23 @@
> `SKILL.md` 허브에서 분리한 시나리오 상세. 요청할 상태(state) 목록과 프레임 수를 정할 때 이 문서를 따른다.
+## Video Path State Defaults
+
+Video path defaults apply strictly to the video path, independent of component-row simple states. Mode `once` executes a single action transitioning from an initial pose to a stable final pose, skipping return motion, with no seam gate or wrap correction. Mode `one-shot` executes a `rest -> action -> rest` cycle requiring seam closure.
+
+Six states automatically select `once` across `sprite-gen video-prompt`, `sprite-gen video-set`, and `sprite-gen video-loop --cycle auto`. Defaults for `idle`, `walk`, `run`, `jump`, and `attack` remain unchanged. Cyclic states (`idle`, `walk`, `run`, `talk`, `blink`, `breathe`) reject explicit `--cycle once`, but overrides allow `jump`, `attack`, or custom actions.
+
+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.
+
+| State | End Pose |
+|---|---|
+| `death` | lying prone on ground |
+| `fall` | grounded resting pose after downward drop |
+| `land` | low crouch after descent |
+| `cast` | raised implement or forward body in casting pose with no effects |
+| `hurt_hold` | held recoil |
+| `transform` | final changed form |
+
## Simple MVP Scope
The default user promise is deliberately simple:
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 10d5569..8ff1e0f 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -714,6 +714,24 @@ forced canvas is the forced-wide row (35 % above), so a jump in that batch keeps
head-room; an attack in it gets that row too, not its own 20 %. A walk or run gets its own wide
row, with nothing above (section 1).
+## Video Processing Pipeline and Terminal Gate
+
+```bash
+sprite-gen video-canvas --still still.png --state death --out canvas.png
+sprite-gen video-prompt --direction side --state death > prompt.txt
+sprite-gen video --image canvas.png --prompt-file prompt.txt --duration 3 --resolution 480p --out clip.mp4
+sprite-gen video-frames --clip clip.mp4 --out-dir frames --spill auto --reference canvas.png
+sprite-gen video-loop --frames-dir frames/keyed --fps 24 --state death --cycle once --out-dir out
+```
+
+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.
+
+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.
+
+In `sprite-gen video`, `--image` is the start frame and `--last-frame` is the end frame. Unpinned execution is the default when omitting terminal canvas arguments. Newly added flags are `video-prompt --end-frame final.png` and `video-set --end-frame ITEM=PATH`. Both are nonloop-only; `video-prompt` also refuses `--no-last-frame`. `video-prompt` only prints instructions, does not open/validate image, whereas `video-set` checks final canvas dimensions and corner key match initial canvas. Nonloop clip cache identity includes end image SHA256; a changed end pin cache rejects until user explicitly `--force` regenerates. Terminal stability checks remain strictly enforced with pins.
+
## 4. Loop — period first, seam second, then the gait floor
The 2026-09-08 lesson: a single-start "most similar later frame" search lands on the
diff --git a/tests/video/test_once.py b/tests/video/test_once.py
index 650018d..6bbb338 100644
--- a/tests/video/test_once.py
+++ b/tests/video/test_once.py
@@ -117,7 +117,7 @@ def test_terminal_gate_rejects_still_and_accumulated_drift():
select_cut(np.abs(values[:, None] - values[None, :]), np.ones(30), fps=24)
[email protected]("after", ["standing", "shaking"])
[email protected]("after", ["standing", "shaking", "clipped"])
def test_once_cuts_at_the_first_settled_ground_pose_before_later_motion(tmp_path, after):
files = keyed(tmp_path / "keyed")
initial = Image.open(files / "0000.png")
@@ -126,6 +126,10 @@ def test_once_cuts_at_the_first_settled_ground_pose_before_later_motion(tmp_path
settled.save(files / f"{k:04d}.png")
for k in range(55, 90):
(initial if after == "standing" or k % 2 else settled).save(files / f"{k:04d}.png")
+ if after == "clipped":
+ outside = Image.new("RGBA", initial.size)
+ ImageDraw.Draw(outside).rectangle((0, 40, 20, 60), fill=(200, 80, 30, 255))
+ outside.save(files / "0070.png")
report = cut(tmp_path)
assert report["cycle"]["end_frame"] == 44
assert report["cycle"]["terminal"]["start"] == 40