Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
release: 3.13.0 — the two Unreleased CHANGELOG sections made one section named for the release, its upgrade note from 3.12.1, pyproject and SKILL.md at 3.13.0
Soohong Kimd2ffa6fc9660
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 644fa29..f2c1a35 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,9 +2,13 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.-## Unreleased - A walk whose feet meet once a cycle is cut one cycle long only where its body or the order the feet are drawn in witnesses it, a walk that starts or stops in its take is named to film again, and video-set cuts a searched walk or run with motion-auto by default+## v3.13.0 - A walk whose feet meet once a cycle is cut one cycle long only where a witness says so, video-set cuts a searched walk or run with motion-auto by default, contract strings written once, read by name-**Upgrading from 3.5.0: `video-set` now cuts searched walk and run loops with `--anchor motion-auto` and their view by default, and `video-loop --anchor motion-auto` recognises crossings that mark cycles where feet hide or step apart instead of cutting two cycles.** Every walk or run item whose loop is searched is now cut with `motion-auto` and its view, producing a different cut and different bytes; `--anchor none` gives the old cut, its pictures and reports byte for byte apart from the engine hash (`producer.implementation_sha256`). Idle, attack, once-hold, lifetime, and once-return items are cut as before. In `video-loop --anchor motion-auto` without `--view`, a walk whose feet are seen together over half the interval at a pass (`crossings.HIDE_SHARE`, 0.5) and whose picture repeats each interval is now counted on cycles only where the body's top line, read less the picture's own flow, rises and falls twice an interval, and that rise and fall must be the body's own, read against its lowest row and its upper body, so the picture moved or zoomed with it witnesses nothing: where the parent engine cut two cycles, the loop is now one cycle with new bytes; where the parent engine kept the search's cut with no `steps`, the cut is the same and the strip and report now record `steps: 2`; where nothing witnesses, its crossings stay on steps with a warning (`cycle-unwitnessed`). A walk whose crossings mark steps (brief passes, or from the side) is cut to the same bytes. With `--view` (or through `video-set`), a front, back, or diagonal walk is evaluated even with brief passes: such a walk is counted on cycles with the same witness, the view's foot cue only refusing where it turns over one interval on; where nothing witnesses, its crossings stay on steps with a warning, and `video-set` leaves a `cycle-unwitnessed` loop out of the cycle alignment. Every report whose clip stands still gains `stands` and `run_limit`, and reports where cycle reading is asked gain `cycles`, with `bob` where the picture passes and `cue` only where a view is given.+**Upgrading from 3.12.1: walk and run cuts and the `video-set` default change, while the contract strings work changes no output.** `video-set` without `--anchor` used to cut everything with `--anchor none`. It now cuts each walk and run item whose loop is searched with `--anchor motion-auto` and passes the item's view to `video-loop`, so those items get a different cut and different bytes. `--anchor none` gives the old cut, its pictures and reports byte for byte apart from the engine hash (`producer.implementation_sha256`). Idle, attack, once-hold, lifetime and once-return items are cut as before. In `video-loop --anchor motion-auto`, crossings are read as marking cycles, not steps, only where a witness that reads no leg says the interval holds two steps. This is asked where feet are seen together over half the interval at a pass (`crossings.HIDE_SHARE`, 0.5), or where `--view` is given and is not `side` (`video-set` passes the view); `video-loop --view` is new. There are two witnesses. One: the body's top line, less the picture's own flow, rises and falls twice an interval, and that rise and fall is the body's own, read against its lowest row and its upper body, so the picture moved or zoomed with it witnesses nothing. Two, from the front, the back or a diagonal only, never from the side: the order the feet are drawn in. The view's foot cue only refuses. A walk 3.12.1 cut two cycles long is now one cycle, with new bytes. A walk where 3.12.1 kept the search's cut with no `steps` keeps its cut, and the strip and report now record `steps: 2`. A walk whose crossings mark steps (brief passes, or from the side) keeps its cut and its pictures. Where nothing witnesses, the crossings stay on steps with a warning naming `cycle-unwitnessed`. Every walk or run cut is now held to the witness's word before it is cut, in `video-loop --anchor motion-auto` with `--cycle auto` or `periodic`. A cut nothing witnesses as whole cycles keeps its length exactly as chosen, is named `cycle-unwitnessed` in the warnings and the report (`cycle.cut_witness`), and is never lengthened or shortened. A walk that starts or stops inside its take gets a `retake` record (`reason: "start-stop"`, `remedy: "retake"`). Its cut is kept and is not refused, and `video-set` names it in its warnings and in `table.md`. `video-set` leaves `cycle-unwitnessed`, `cycle-four-steps` and start-stop loops out of cycle alignment, names them under `left_out`, keeps those loops as cut, and aligns the other directions. Standalone `video-cycle-align` now reads the cut report beside each loop. On a held or four-step cut it stops under its default `--multi-cycle fail` before rewriting any file. `--multi-cycle warn` aligns with a warning, and `--cycles` settles it. Reports gain `stands` and `run_limit` where a clip stands still, `cycles` where cycle reading is asked, and `cycle.cut_witness` only in reports of `--anchor motion-auto` cuts; `--anchor none` reports are unchanged. Report fields `step_count.search.same_picture` and `step_count.same_picture` and the count code `same-picture` are removed.++The contract strings work changes no output: every output, report, JSON body, JSON key order, CLI choice and order, `--help` text, refusal and warning text keeps its bytes, and nothing a user runs behaves differently because of it, apart from two effects. First, `frames/extract.py` and `frames/decontam.py` changed, so `engine_revision` changes; the curation view's heal re-extracts each existing run once when it is next opened, and the frames it writes have the same pixels. Second, `python -m sprite_gen.serve.serve_curation`, `scripts/serve_curation.py` and `scripts/interpolate_frames.py` now load the image providers (`sprite_gen.gen`) when they start, so a malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` stops them at start with its `ValueError` instead of when a reroll or interpolate button is pressed (`sprite-gen curation` already loaded them and is unchanged). `python -m sprite_gen.video.loop` and `scripts/video_loop.py` load the image providers too, and a malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` stops them with its `ValueError`, even for `--help` (`sprite-gen video-loop` already did), while importing `sprite_gen.video.loop` still loads no provider code.++### Walk and run loops- **New: crossing cycle detection (`local_cycle.read_cycles`, `local_cycle.bob_word`, `local_cycle.off_flow`, `local_cycle.twice_an_interval`, `local_cycle.own_beat`, `local_cycle.cue_word`, `crossings.HIDE_SHARE`, `crossings.Reading.hides`, `legs.body_signals`, `CYCLE_SLACK`, `CUE_FLOOR`, `CUE_SWAPPED`, `BOB_TWICE`, `BOB_FLOOR`, `BOB_ROWS`, `BOB_OWN`, `BOB_SCALE`, `BEAT_FRAMES`, `UNWITNESSED`).** In gap mode on a readable reading, when feet can hide behind one another (`reading.overlap` over `crossings.HIDE_SHARE`, 0.5) or when the view is given and is not `side`, crossing intervals are checked to see if they mark full cycles rather than single steps. `repeat_at(distances, span)` reads the mean distance of frames to those lagged by `span` over the clip's mean step from frame to frame. Comparing distances at half, one, and two intervals, crossings mark cycles when `one < half` and `one <= two + CYCLE_SLACK` (0.5), only where a witness that reads no leg says the interval holds two steps, the body's own rise and fall twice an interval: its top line (`legs.strike_signals` `top`) less its flow, read against its lowest row and upper body. New function `local_cycle.off_flow(values, interval)` returns `values` (per frame) less their flow: each frame minus the mean of the interval about it (a moving average one interval long, its two end frames weighted by the part of a frame the interval covers), kept only over the frames the interval fits about (the first and last `ceil(interval/2 - 0.5)` frames drop out), and what is left minus its least-squares straight line; a rise and fall once or twice an interval averages to nothing over one interval and is left whole, while a flow slower than the interval is taken out wholly where it bends no more than a cubic (a constant, a straight drift, an arc, a cubic) and in part where it is a slow sway a few intervals long. `local_cycle.bob_word(signals, interval)` reads the body's top line less its flow (`off_flow(top, interval)`), not the raw line; `swing` is the range of the line left over the body's median height, and `rows` is that range in pixel rows. Where the clip is under an interval long so nothing is left, `says` is null and `why` says its top line less its flow is not read; where `swing` is under `BOB_FLOOR` (0.005) or `rows` is under `BOB_ROWS` (2), `says` is null, `why` says the line's range less its flow is under 0.5 % of the body's height or 2 rows, so it does not rise and fall (the top line is read in whole pixel rows, so a picture drifting up or down makes the line step a row up and down as it rounds, and that rounding, less its own mean over an interval, stays under 2 rows), and `half` and `quarter` are not read. Otherwise it reads the line left's correlation half an interval on (`half`) and a quarter of an interval on (`quarter`), both with `crossings.correlation_on` (each the larger of the two whole lags about the span), saying `"cycles"` only where `half` is `BOB_TWICE` (0.28) or more and `quarter` is `-BOB_TWICE` (-0.28) or less (the line is as it was half an interval on and turned over a quarter on, which is a rise and fall twice an interval; a step's bob is turned over half an interval on, and any flow left over is as it was at both half and a quarter of an interval on so it cannot pass the quarter test), null otherwise with `why` giving both values. Where any frame's lowest solid row is the frame's last row (`legs.body_signals` `edge`), `says` is null, `why`: "its lowest row is the frame's last row in {n} of {N} frames: the feet may run off the frame, and the picture moving is not read off them" (there the lowest row is the frame's, not the feet's). `local_cycle.twice_an_interval(values, interval)` reads `values` (per frame) less their flow (`off_flow`), then a least-squares fit of a mean, the harmonic twice an interval (cos and sin of 4 pi k / `interval`) and the harmonic once an interval (cos and sin of 2 pi k / `interval`), k the frames left counted from the first; it returns the twice-an-interval harmonic as a complex amplitude (its cos coefficient less i times its sin coefficient), in the values' units (a line rising and falling a rows either way twice an interval reads a in magnitude; lines read so over the same frames and interval subtract as they move), or None where fewer than `BEAT_FRAMES` (8) frames are left; where none, `says` is null, `why`: "its top line's rise and fall twice an interval is not read against its lowest row and upper body: under 8 frames are left less the flow". `local_cycle.own_beat(signals, interval)` reads three lines with `twice_an_interval`: the top line (`top`), the lowest solid row (`reach`) and the lowest opaque row (`sole`); it returns, in rows up and down (twice the magnitude): `beat` (the top line's), `lowest` (the lowest row's), `sole`, `less_lowest` (the top line's less the lowest row's: the picture moving taken out), `bands` (`{rows, width, zoom, beat, reads, less}`, per band: its rows below the first solid row, its width in the median frame and `zoom`, in pixels, `beat` in pixels, `reads` is the band's `beat` over its `zoom` (the share of the zoom making the line's rise and fall that the band reads), read whatever its turn: a zoom moves a band's width in step with the line it lifts, but the band's own parts swinging across it (arms, a cape) move it too, in step with the line, against it, or a quarter of the beat off, and the zoom's part is not told from theirs. `less` is what is left of the top line's rise and fall twice an interval less as much of the zoom as the band reads: `less_lowest` times (1 - `reads`), and nothing where `reads` is 1 or more, so a band whose width moves against the line adds nothing to what is left, `reads` and `less` null where the band is not seen), `less_bands` (the least `less`, null where no band is seen), `still_bands` (the number of bands seen whose `reads` is at most 1 - `BOB_SCALE`, 0.4: they hold still on the beat), and `own`, the smaller of `less_lowest` and `less_bands` (None where a line is not read). The floor is the larger of `BOB_ROWS` and `BOB_FLOOR` of the body's median height; where `less_lowest` is under the larger of `BOB_OWN` (0.3) times `beat` and the floor, `says` is null, `why`: "its lowest row rises and falls with it: less the lowest row's, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}; at least 30% and {floor} rows): the picture moves with the body, and the body's own is not told from it"; where no band is seen (`less_bands` null), `says` is null, `why`: "no band of its upper body would show the picture zooming: zoomed in as far as its top line rises and falls twice an interval against its lowest row ({less_lowest} rows of {height}), no band's width moves 1 px (at most {largest zoom}): the picture zooming with the body is not told from the body's own"; where `less_bands` is under the largest of `BOB_OWN` times `beat`, the floor, and `BOB_SCALE` (0.6) times `less_lowest`, `says` is null, `why`: "its upper body's width changes with it: less as much of the zoom as its band {a}% to {b}% of its height below its top reads, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}), {ratio} of the {less_lowest} left against the lowest row (at least 30%, {floor} rows and 0.6): the picture may zoom with the body, and the body's own is not told from it"; otherwise `says` `"cycles"`. This tells them apart because a body rising and falling on its legs leaves its planted foot, the lowest solid row, on the ground, and carries its upper body's bands whole and leaves their widths: the picture moved up and down carries the lowest row with the top line by the same rows, so nothing is left of the line's rise against it, while the picture zoomed in and out widens each band as it lifts the line, as far as the band's outline lets it, so nothing is left once the zoom is taken out too. Where no band would show the zoom, or any band that would moves on the beat (arms swinging past the body's sides, a cape, or the picture zooming), nothing tells the picture zooming from the body's own, and nothing is witnessed; one band holding still says only that no zoom shows in that band (a head drawn narrower as the picture zooms in holds still so). Two limits the code does not catch: (a) a picture zoomed on the beat with every band seen drawn against the zoom, so that each band holds still, is read as the body's own (its band widths are those of an upper body rising whole on its legs; measured on one such drawing, every band within 0.78 px of such a body); (b) a body that rises and falls twice a step on its own legs reads as two steps an interval of one. A walk whose arms swing past its sides on the beat is not witnessed where a band seen moves on the beat (its `reads` over 0.4). Where a walk is not witnessed, its crossings stay on steps, or its cut is held, and either way it is named, never handed out as a cycle unnamed. New `legs.body_signals(frames)` reads per frame `bands`, each band's mean width in alpha, in pixels, read on the same rows in every frame, those of the clip's median body height (`legs.BANDS` = `((0.02, 0.10), (0.10, 0.18), (0.18, 0.26), (0.26, 0.34), (0.34, 0.42), (0.42, 0.50))`), and `edge`, 1 where the lowest solid row is the frame's last row, else 0; only the step count's witness reads them, merged by `loop.read_steps` into the signals it passes to `local_cycle.read_cycles`; `legs.strike_signals` is unchanged, so the loop report's `gait.silhouette.signals` is unchanged, and `--anchor none` still gives the old cut, its pictures and reports byte for byte apart from the engine hash. The directional foot cue (`legs.shade_cue` from the side or diagonal, `legs.depth_cue` from the front or back) is read with a view given by `local_cycle.cue_word(cue, interval, step=None)` and can only refuse cycles: under `CUE_FLOOR` (0.5) of the step it is drawn in (`legs.TONE`, 1/255, or a pixel row of median body height) it says `"alike"`; where it turns over one interval on (`crossings.correlation_on` at or below `CUE_SWAPPED`, `-0.2`) it says `"steps"`, refusing cycles because the other leg leads there; otherwise null. With no view no cue is read at all. Where the view's cue says `"steps"`, the count stands (two steps); else where the bob says `"cycles"`, cycles are marked; otherwise crossings stay on steps with `unwitnessed` true (`local_cycle.UNWITNESSED`) and a warning (`cycle-unwitnessed`). When cycles are marked, `Reading.mark_cycles` sets `per` to 2 and halves `step` and `step_range`: a cut one interval long is two steps, and the search's cut (`--anchor motion-auto`) taken on it writes `steps: {count: 2, by: crossings}`. A fixed cut (`--cycle fixed`, `fixed_count`) and the loop as it plays round (`ring_steps`) read the same; a fixed cut one interval long is counted two steps and not refused, and still writes no `steps`.- **Removed: the same-picture rule (`local_cycle.same_picture`, `local_cycle.same_picture_count`, `local_cycle.SAME_PICTURE_MAX`, count code `same-picture`, report fields `step_count.search.same_picture` and `step_count.same_picture`).** It kept the search's cut, with no `steps`, where the count said one step; it never cut one cycle where the search had found two. `local_cycle.read_cycles` takes its place.@@ -80,9 +84,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- two synthetic loops in `tests/video/test_loop_prop_seam_held.py` (one cut two steps long, one cycle, strip `steps: 2`, and one cut one cycle with no `steps`, neither walker's body rising and falling and its feet never passing, so both reports hold their cuts, nothing witnessing either whole cycles): on copies whose reports the test rewrites to witness their cuts (`cut_witness` saying "two steps" by the screen, nothing held), the aligner works as before: the two-step loop returns half way at its second step, which is no suspect (`status` "steps", `steps` 2, candidates `[2]`), and both loops are resampled to the median of their lengths as cut, nothing kept twice as long, the strip of the two-step copy still saying `steps: 2`, the other none; on the loops as cut, `video-cycle-align` stops on both, each named `held` with reason `cycle-unwitnessed`; a count of one cycle for each (`cycles`, the caller's word) aligns them as they are, to the same median length, each suspect `status` "counted"; a count of 2 for the two-step loop (and 1 for the other) still takes one half out of it, and its strip no longer says `steps`; two copies of the loop with no held part, aligned with a count of one cycle each, are written as before: no `cycles_kept` and no `steps` in their rows, their strip metadata with the same keys, and the cut's source (`source_cut`) as the cut wrote it (previously both aligned with no count, the two-step loop's return read as its steps).- the synthetic cut of 13 cells with its record of its cells, aligned by `video-cycle-align` to 17 cells, in `tests/video/test_sway_read_on_recut.py` (with `--between rife` (a blend standing in for RIFE) the aligned strip record holds no `cell_record`, `cycle_align.cells_from` gives 17 cells, each `{"source": i}` cell is cell i of the cut pixel for pixel and each `{"between": [i, j], "t": t}` cell is a copy of no cell of the cut, `cycle.source/run.strip.json` is the cut's record with 13 cells, source frames 1 to 13, and `video-sway --read-on-cut` is refused `uncertain` on the pair the kept record gives (source frame 4), naming the first made cell, the loop as it was; with `--between nearest` every one of the 17 cells is one of the cut's, and `--read-on-cut` pairs source frame 4 with the cut's cell 3 at shift (3, 2) and carries it through, `cut_cells` equal to the `cells_from` sources).-## Unreleased - Contract strings each written once and read by name--**Upgrading from 3.12.1: every output, report, JSON body, JSON key order, CLI choice and order, `--help` text, refusal and warning text keeps its bytes. Nothing a user runs behaves differently. One visible effect: `frames/extract.py` and `frames/decontam.py` changed, so `engine_revision` changes. The curation view's heal re-extracts each existing run once when it is next opened; the frames it writes have the same pixels. One edge: `python -m sprite_gen.serve.serve_curation`, `scripts/serve_curation.py` and `scripts/interpolate_frames.py` now load the image providers (`sprite_gen.gen`) when they start, because their default provider is read from a declared name. A malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` now stops them at start with its `ValueError`, instead of when a reroll or interpolate button is pressed. `sprite-gen curation` already loaded them, so it is unchanged. `python -m sprite_gen.video.loop` and `scripts/video_loop.py` read `gen.facing.FACINGS` when they run or build their arguments, so they load the image providers too, and a malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` now stops them with its `ValueError`, even for `--help` (`sprite-gen video-loop` already did). Importing `sprite_gen.video.loop` still loads no provider code.**+### Contract strings- **Internal: one declaration per contract string**: a key, kind, mode, provider name or key colour that two or more places write, read or branch on was spelt again at each place, so a one-letter typo passed every test (for example the curation server's `extractOk` spelt `extractOK` made the curator warn on every row with the suite green). Each is now declared once and every use names it:- curation and composer servers: every key of the JSON the curator and composer read, in `serve_curation.Wire` (112 keys and the `X-Filename` download header) and `serve_compose.Wire` (16 keys, plus `TYPE_DIR`, `TYPE_IMAGE`); the heal report and progress file keys in `frames/extract.py` (`HEAL_*`, `PROGRESS_*`, `PROGRESS_PHASE_COMPONENTS`); `curation.CURATION_KIND`, `REF_ANCHOR`, `REF_BASIS`, `REF_GUIDE`, `BREATHE_PIXEL`, `BREATHE_SMOOTH`.diff --git a/SKILL.md b/SKILL.mdindex 09efc6d..63dab42 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 3.12.1+version: 3.13.0description: "Generates images and game sprites through GPT or Grok with guided provider choices, separate saved defaults, automatic cleanup and optional curation. Handles sprite requests, ordinary image generation/editing, typography logos (로고, 타이포그래피, 타이틀 글자, 타이틀 로고, wordmark, logo, title lettering: a title screen drawn with the title in it, its lettering lifted out transparent), standalone image-to-video clips (i2v, animate this still, 그록 영상, 이매진 비디오, 스틸 움직여줘, first/last frame, reference-to-video, 영상 이어붙이기, 영상 편집, extend/edit a clip), clips from a video MCP on the agent (ZCRE, 지크 MCP), chroma removal, animation atlases, video loops, 큐레이션뷰, image candidates, 팔레트 스왑, palette swap, recolor, engine exports, repeating backgrounds, projected shadows, talking face layers over body motions (말하는 얼굴, 입 맞추기, 얼굴 층, lip sync, face pack), motion/contact inspection and optional scene composition from existing assets."license: Apache-2.0depends_on:diff --git a/pyproject.toml b/pyproject.tomlindex 84d7f98..2bbc907 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"name = "sprite-gen"# Release discipline: keep this package metadata version synchronized with# SKILL.md's `version:` field in the same release commit.-version = "3.12.1"+version = "3.13.0"description = "Component-row pipeline for clean 2D game sprites and animation atlases"readme = "README.md"license = "Apache-2.0"