Skip to content

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

release: 3.1.0 — the CHANGELOG section named for the release, pyproject and SKILL.md at 3.1.0

Soohong Kimbb0ec5102c23
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0574eb4..e6ab373 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
-## Unreleased
+## v3.1.0 - Walk and run loop gates for held animation and seam pops, size hold for fixed cuts, talking face layer and default chroma decontamination
**Upgrading from 3.0.0: Fixed walk or run cuts and clips whose feet climb or sink now hold size and feet before cutting, changing bytes when size changes by 1 % or more.** Application scan numbers change for held clips, and held fixed cuts are not restored by `video-loop-repair`. Loops cut with `--size-hold off`, clips changing size by under 1 %, held `motion-auto` cuts on one row, and non-walk cuts keep their bytes. The report records `size_hold` on fixed walk or run cuts, `size_hold.feet` when size is held, `size_hold.anchor_regions` under `--anchor motion`, and `size_hold.at_cut` on fixed cuts; `producer` names the new version.
@@ -118,7 +118,7 @@ The Breathe layer still supports `pixel` and `smooth`.
- See [docs/face-parts.md](docs/face-parts.md) for the request, pack, player, commands, and limits.
- **Tests**: `tests/video/test_face_layer.py` uses `tests/talking_face.py` to check smile and neutral sets; clip entry set and rest; own-mouth timelines, including a close during voiced sound and refusal of a missing or never-closing timeline; a head 60 px from its place and tilted 3 degrees; a head that turns, tilting up to 5 degrees about its mouth while its hair, headset, and cheeks move up to 12 px sideways and its mouth stays where it is, with two of its eleven frames open, whose anchor place is within 1 px of the mouth on closed frames and within 2 px on the two open frames and whose tilt is the band's, below minus 2.5 degrees where the turn is fullest; hand, headset boom, and choker keeps; a tongue in the body's own open mouth, joined to a hand by a finger at its corner, covered by the layer; unchanged pixels outside the weight; synthetic cells keeping the key's colour under no coverage; digests and new-folder pack writes; the player flap against its original numpy rule and the pick against the draft Viterbi over every frame; a line waiting for a clip's own mouth and for a frame its layer can come on at; the live player run by node on a fake audio clock, with two lines requested during a greeting's own mouth, three lines requested on the loop, one line requested during the own mouth and one after it, a line whose voice loads late, a line requested right after a clip whose sound loads late, a line whose voice loads only after the greeting's own mouth has ended or only after the greeting has ended, which waits for the greeting to end while the greeting plays to its end with the layer off, a line that plays on the loop when requested right after a clip whose sound fails to load, and a request that fails; loop and post-greeting bakes with greeting frames unchanged byte for byte; and refusal of a changed pack.
-**Upgrading from 2.45.3: This release changes defaults for video frames.**
+**Upgrading from 3.0.0: This release changes defaults for video frames.**
Outputs that change bytes are frames from `video-frames` and `video-set` on a green or magenta key.
These changes occur within 6 px inside the keyed silhouette only.
@@ -126,9 +126,9 @@ Video frames keyed with explicit `--decontam palette` also change bytes, because
Outputs that do not change bytes include runs on a white key, subjects with no interior, and runs with `--alpha-mode brightness`.
Stills (`cutout`, `gen`) and row extraction (`extract`, `inspect`) do not change bytes.
-Runs with `--decontam off` also give the 2.45.3 bytes back exactly.
+Runs with `--decontam off` also give the 3.0.0 bytes back exactly.
-To get the 2.45.3 frames back, pass:
+To get the 3.0.0 frames back, pass:
`--decontam off`
- **Default change: `video-frames` and `video-set` now default to `--decontam auto` (before: `off`).**
@@ -341,7 +341,7 @@ To get the 2.45.3 frames back, pass:
`tests/video/test_gait_guard_anchor_wide.py` has its stand-in for `run_frames` take `decontam` and checks that the set's `auto` reaches it.
-**Upgrading from 2.45.3: Every cut 2.45.3 passed that neither new reading refuses gives the same loop files byte for byte.** Strip, sidecar, frames, GIF and WebP bytes match with the same stderr save new warning lines, measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains `step_gate` on walk or run loops and `cycle.step_count` on fixed walk or run cuts, `producer` names the new version, and the CLI summary gains `step_gate`, whose `jitter` names the frames entered by steps over 2.5 that are a pixel's jitter, along with `jump_repair.unfixed`. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for `video-loop: loop step ratio` (the clip jumps inside: film again), `video-loop: loop step count refutes the fixed cut` (cutting again by hand failed), and `video-loop: loop frames left off the flow` only if passing `--unfixed refuse`; failure reasons can also be read from `seam_refusal`. Any `--seam-max` past 2.5 lifts the step gate and count refusal, so forced delivery keeps passing `--seam-max 1000`. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut. As a known limit, the seam gate and the body anchor's rule from 2.45.3 still read frames, not drawings, so a walk held on twos or threes whose cut wraps between two drawings is still refused where it closes between its drawings.
+**Upgrading from 3.0.0: Walk and run loops now pass a step gate and fixed walk or run cuts are counted, so some cuts that passed before are refused.** Against 2.45.3, on which this change was built, every cut 2.45.3 passed that neither new reading refuses gave the same loop files byte for byte (strip, sidecar, frames, GIF and WebP bytes, the same stderr save new warning lines), measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains `step_gate` on walk or run loops and `cycle.step_count` on fixed walk or run cuts, `producer` names the new version, and the CLI summary gains `step_gate`, whose `jitter` names the frames entered by steps over 2.5 that are a pixel's jitter, along with `jump_repair.unfixed`. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for `video-loop: loop step ratio` (the clip jumps inside: film again), `video-loop: loop step count refutes the fixed cut` (cutting again by hand failed), and `video-loop: loop frames left off the flow` only if passing `--unfixed refuse`; failure reasons can also be read from `seam_refusal`. Any `--seam-max` past 2.5 lifts the step gate and the count refusal, and forced delivery passes `--seam-max 1000` together with `--seam-pop-max off`, because `--seam-max` does not lift the seam pop gate described below. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut.
- **Behavior change: Walk and run loops that play round now pass a step gate that inspects spacing between drawings.** After the seam gate, cells are read between drawings rather than frame by frame, so held animation on twos or threes does not appear uneven when drawings span multiple frames. The largest step from one drawing to the next, the wrap included, over the mean of the others, must be at most `STEP_RATIO_MAX` (2.5), else the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`, with jump repair reason `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed` before ` — regenerate the clip` where present. A step over 2.5 is exempt from the bound when it is a pixel's jitter (`loop.step_jitter`): the move that aligns its drawing with the previous drawing with the least coverage difference, measured on alpha so colour has no effect, is at most `STEP_JITTER_PX` (1.5) pixels of the frames as filmed, and the step with that move taken back is within 2.5 of the mean. In a walk going away from the camera, foot rises of a whole crop row measure 2.5 to 3.6 times the mean as drawn, black or grey, but move one pixel and pass without a warning line. One frame of a 400 px tall walk cut moved 6 px and back moves 2 pixels of the frames as filmed, and the gate refuses the loop in every colour, including black. The report records `step_gate` on every walk or run loop (`drawings`, `hold`, `mean_step`, `largest_ratio`, `largest_from`, `largest_into`, `wrap_ratio`, `max`, `jitter`, `lifted`, `kept`; `skipped` for fewer than three drawings). The bound is the larger of 2.5 and `--seam-max`, so any `--seam-max` past 2.5 lifts it; a scan or forced delivery with `--seam-max 1000` keeps a loop whose largest step is over 2.5 with warning `video-loop: warning: the loop's largest step between drawings is <ratio>x their mean (into frame <frame>), over 2.5: it jumps inside — kept, as --seam-max <seam-max> lifts the step gate` and `step_gate.kept`.
- **Behavior change: Fixed cuts fail when foot crossings count an odd number of steps.** Manual walk or run cuts using `--cycle fixed` now read the clip's foot crossings and evaluate the cut, matching `--anchor motion-auto`. The report records `cycle.step_count` with `chosen_by: caller`. A cut counted an odd number of steps fails with `video-loop: loop step count refutes the fixed cut <start>/<L> — the clip's crossings count one step, each seen where a walk loops on two, and an odd count swaps the legs at the wrap; cut it again two steps long (about <2 steps> frames)`. An even count is not refused by the count check, and the exemption `--anchor motion-auto` makes for a pass hidden among feet held together (the clip a cut on the same picture) applies identically through shared `local_cycle.same_picture_count`. The strip is unchanged, and there is no `steps` field. Any `--seam-max` past 2.5 lifts this refusal; a scan or forced delivery with `--seam-max 1000` keeps an odd step cut with warning `video-loop: warning: the clip's crossings count the fixed cut <start>/<L> one step, each seen: a walk loops on two steps, and an odd count swaps the legs at the wrap — kept, as --seam-max <seam-max> lifts the step gate` and records `cycle.step_count.lifted`.
@@ -351,6 +351,13 @@ To get the 2.45.3 frames back, pass:
- **Fix: Windows run dir lock handling.** Every command that writes a run dir (for example `extract`, `compose-atlas`, `export-pngs`, `unpack-atlas`) takes a single-writer lock: the entry `.sprite-gen.lock` inside the run dir. Before this fix, on Windows only, when that name held a link pointing at a file that does not exist, the writer followed the link and made the lock file at the link's target, outside the run dir, and that file was left behind when the writer released the lock; also on Windows only, a folder at that name, a link to a folder, or a link whose target is written with forward slashes ended the command with a bare `OSError` (`EACCES` or `EINVAL`) instead of the named refusal. Now on Windows a link or a folder at that name is refused by name, the same as on macOS and Linux (`run dir lock ... is not a lock file (a link or a folder)`), and nothing is followed, made or removed, while macOS and Linux behave exactly as before. The test is `tests/spec/test_run_dir_lock.py`.
+**Upgrading from 3.0.0: commands that write beside what they read now check and refuse any input that overlaps a file or folder the run replaces or deletes, even with `--force`.** This judgment is defined in `docs/run-contract.md` and enforced by `runio.refuse_overlap` before any command creates output. A run is stopped whenever an input matches an output, lies inside it, or passes through anything inside it, and the refusal names both paths.
+
+- **Behavior change: Overlap refusal for inputs and outputs.** Twelve commands now call `runio.refuse_overlap` before making anything, with or without `--force`: `unpack-atlas`, `video-loop`, `video-stop`, `video-frames`, `correction-loop`, `logo`, `video-extend`, `video-edit`, `video-loop-compare`, `video-loop-repair`, `video-source-manifest` and `shadow`. Inputs include paths given to read and files found inside them (such as frames in `--frames-dir`), followed via `runio.follow_path`. Outputs include each file written, folder replaced or emptied, and report, but not folders only added to (which is why `--out-dir` for `video-loop` and `video-stop` is not compared). Comparisons check real path and file identity (`runio.same_folder`, `runio.inside_folder`), treating links and different spellings on volumes that ignore case as identical, while input link loops are refused by name. A link at a written file is refused if it leads to an input, even where the run would replace the link rather than write through it, whereas paths passing through an output and exiting with `..` (such as `out/cycle.source/../keyed`) are permitted. In `logo`, the folder's own `mood.png` and `lettering.png` remain permitted for `--mood` and `--lettering` while any other output file is refused, and `correction-loop` permits an `--out-dir` inside the run dir or one holding an earlier loop's attempts, best candidate and report.
+- **Fix: Directory recursion and casing collisions on volumes that ignore case.** Before, `correction-loop` compared only `--out-dir` itself with the run dir, so with a link `attempt-1` in its `--out-dir` leading to the run dir, the loop wrote its attempt into the run it read. Separately, before, the best candidate's copy of the run dir copied itself into itself until the path was too long. (The default `--out-dir`, `<run-dir>/correction-loop`, lies inside the run dir; the copy now leaves it out.) `correction-loop` now takes an earlier loop's candidate away before the provider makes the next one there. `video-sway-inspect` now refuses an `--out-dir` that is the loop directory spelt in capitals on a volume that ignores case, instead of writing boards into it. In addition, `video-loop-compare`, `video-loop-repair`, `video-source-manifest` and `shadow` now call `runio.refuse_overlap` so reports or outputs spelt in capitals on volumes that ignore case are refused instead of overwriting inputs, while `background-tile`, `inspect-motion`, `scene-inspect`, `scene-render`, `game-pack`, `ui-kit` and `video-sway-inspect` verify their single output with `runio.same_folder` and `runio.inside_folder`.
+- **Behavior change: Unique working folders via stage names.** Any folder a run writes into and then deletes is now created with `runio.new_stage` and named `.<name>.<pid>-<random><suffix>`. These include the frames `video-loop` scales back for a size hold or gait fallback (`.gait-fallback-frames.<pid>-<random>`, removed however the run ends), the PNG frames built into animated WebP files beside the WebP for `video-loop`, `video-stop`, `video-cycle-align`, `video-sway` and `video-loop-repair` (`.<name>.webp.<pid>-<random>.frames`), the working folder `video-frames` keys into (`.keyed.<pid>-<random>.work`), and the working folder of `logo` (`.logo-work.<pid>-<random>`). Folders at old fixed names (`.gait-fallback-frames`, `.webp-frames`, `.keyed.work`, `.logo-work`), whether holding an input or belonging to anyone else, are never written into or removed.
+- **Behavior change: Input protection, staging, and locks in `unpack-atlas`.** `unpack-atlas` never touches its inputs, refusing before making anything and with or without `--force` any input that is the run dir, lies inside it, goes through anything inside it, or holds it. Guarded inputs include `--pngs-dir`, `--atlas`, `--manifest`, the atlas a manifest names, and what the import reads in `--pngs-dir` (every frame, `_base` image, `_refs` PNG, `meta.json`, and every folder it reads one from, any of which may be a link). Refusals name the first entry the input goes through inside the run dir, while paths that only pass through the run dir itself (such as `run/../incoming`) are not refused. The command builds runs in a dedicated staging folder beside the run dir (`.<name>.<pid>-<random>.sg-staging`) and moves prior content aside into a backup folder inside it (`.sg-backup.<pid>-<random>`), never reusing or removing existing staging or backup folders and putting every prior file back on a failed publish. The run dir's single writer lock is the entry `.sprite-gen.lock` itself (`runio.acquire_run_dir_lock`, every writer) and belongs to the process that took it, and a link or a folder at that name is refused by name and never followed, read or removed, so reclaiming a stale lock deletes only a stale lock file.
+
**Upgrading from 3.0.0: A held walk or run whose wrap fell between two drawings, refused before, may now pass.** A walk drawn a frame each gives the same loop files byte for byte. Reports record `seam_read` (`read`, `drawings`, `hold`) on every walk or run whose seam ratio gates the cut, and `seam_after_anchor` gains the same three fields when cells are read again, with `strip.json` and the failure line of the seam gate unchanged.
- **Behavior change: Walk and run loops gated by their seam ratio now measure the seam between drawings.** For any walk or run whose cut is gated by the seam ratio (neither pinned nor played once), the seam is read between drawings using each drawing's first frame (`loop.seam_drawings`, built on `repair.flow_drawings`), matching the reading used by the step gate. This applies in three places: the seam gate itself, both on source frames (`seam_measurement: source-frames`) and rendered cells (`rendered-cells`); the body anchor ramp rule, reading the wrap and every step between the cells' drawings; and candidate evaluation under `--anchor motion-auto` (`loop.seam_on_cells` through `loop.wrap_on_cells`) when selecting two-step cuts or testing overlapped wrap attempts. Loops showing fewer than three drawings continue to be read on every frame (`seam_read.read: cells`).
diff --git a/SKILL.md b/SKILL.md
index c5da475..9f3677f 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: sprite-gen
-version: 3.0.0
+version: 3.1.0
description: "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.0
depends_on:
diff --git a/pyproject.toml b/pyproject.toml
index a44c5ae..c7a0fbc 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.0.0"
+version = "3.1.0"
description = "Component-row pipeline for clean 2D game sprites and animation atlases"
readme = "README.md"
license = "Apache-2.0"