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: --foot / --align-foot and unnamed_feet (start_foot_source); changelog

Soohong Kime9b09ba95847
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd43f90..48812e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased - A loop whose foot the set alignment cannot name is told it, one loop at a time
+
+- **New `video-cycle-align --foot <loop>=left|right`** (repeatable; the loop named as for `--cycles`: its `--loop-dir`, its strip's name, its directory's name or a `video-set` item's name) and **`video-set --align-foot <item>=left|right`**: which own foot lands on a loop's first strike, as seen by whoever looked at it — a person, the agent, or a vision call. Where a loop's view cannot tell its feet apart (`start_foot: null`), `--start-foot` was set-wide and there was no way to say "this loop's larger strike is its left foot". Now that loop alone starts as the set's start foot lands — on its first strike, or half a cycle on — and every other loop comes out byte for byte as without it. The answer is about the loop as filmed (its strikes are read from `cycle.source/`), so it holds for a later alignment at the same length; like `--cycles` it is not remembered. A foot given for a loop the view did name is taken too, and where it disagrees the row carries `foot_disagrees` and a warning. A `--foot` that names no loop or two, or is not `left`/`right`, is refused before anything is rewritten; `video-set` refuses an `--align-foot` item that is not a walk or run filmed in two or more directions before filming, and names one given for an item that failed or whose state was not aligned in that state's `feet_unused` and a warning. The way feet are named from the pixels is unchanged.
+- **New in the alignment report: `unnamed_feet`**, per loop whose foot nobody named: `dir`, `name`, `view`, `foot_why`, `candidates` (its two strikes: `strike` 0 and 1, `frame` in the rebuilt `cycle/` and the `path` to that frame — the frame to show whoever looks; the first is the frame the loop starts on) and `settle` (the two `--foot` arguments). The report also gains `feet_given`; every loop row and its `strip.json` `cycle_align` gain `start_foot_source` (`"engine"` where the view's cue named the foot, `"given"` from `--foot`, `null` where nobody did) and `strikes` (the two strikes as frames of the rebuilt `cycle/`), and a told row `foot_given` and, where the engine had not named it, `foot_unnamed_why` instead of `foot_why`. `video-set` carries `unnamed_feet` and `feet_given` per state and `start_foot_source` per item; a stopped set's `command` carries the `--foot` given. The warning for an unnamed loop now names the frame to look at and the `--foot` that settles it. Without `--foot`, the cycle, strip, GIF and WebP are unchanged. [docs/loop-repair.md](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto), [docs/video-pipeline.md](docs/video-pipeline.md).
+
## v2.30.0 - A held loop is judged on the cycle cut out of its clip, not on the whole clip
- **Output change: which loops `video-cycle-align` names for a retake** (`held-drawings`). The hold was read over the whole clip and given to the cut cycle, so a clip held for part of its length and drawn every frame for the rest was judged by the clip: a cycle cut from its every-frame part and stretched could be named (the clip reads as held), and one cut from its held part was passed (the clip reads as drawn every frame). `video-loop` now also reads the hold over the cut, on the clip's own steps as keyed from the cut's first frame into the frame after its last (`cycle_drawings` in the loop report and in `strip.json`: `start`, `length`, `steps`, `hold`, `drawings_per_second`, `contrast`), and the alignment uses it (`drawings.source: "span"`, with the clip's reading under `drawings.clip`). A cut of fewer than 12 steps (`held.SPAN_MIN_STEPS`, one window of the clip's reading) is not read on its own: the clip's reading stands (`source: "clip"`), and the row's `span_why` says so, as it does for a loop cut by 2.29.0. A clip held or drawn every frame throughout reads the same over its cut as over the whole: the cut, the strip, the GIF and the WebP are unchanged, and the loop report and `strip.json` gain `cycle_drawings`. [docs/loop-repair.md](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto).
diff --git a/SKILL.md b/SKILL.md
index 2da726a..0ba962e 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -101,7 +101,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.
| Continue or edit an existing clip | `video-extend`, `video-edit` | [video](docs/video.md) |
| Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |
| A soft part of a walk loop follows the body (a chest, a belly): an ellipse in the first cell, after `video-cycle-align` | `video-follow` | [video-pipeline](docs/video-pipeline.md#6-follow-through--video-follow) |
-| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
+| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart: look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
| Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (subscription routes) | [gen](docs/gen.md) |
| Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default or a fallback | [gen](docs/gen.md#subscription-first--openai-is-named-or-it-does-not-run) |
| Base and direction anchors | `anchor` | [directional-anchor-workflow](docs/directional-anchor-workflow.md) |
@@ -137,4 +137,4 @@ Scene creation consumes finished assets and remains optional. Asset metadata own
## Contracts and advanced tools
-[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted takes the nearer source frame) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4).
+[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted takes the nearer source frame) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides, or `--foot <loop>=left|right` (`video-set --align-foot <item>=…`) once you have looked at the first strike frame of a loop the report lists under `unnamed_feet`), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4).
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 1ca64ba..72b731c 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -262,7 +262,7 @@ same number of frames, starting on the same step.
sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-walk/loop \
--loop-dir set/back-walk/loop [--view front --view side@right --view back] [--start-foot right] \
[--between auto|rife|nearest] [--length N] [--cycles back-walk=2] [--multi-cycle fail|warn] \
- [--state walk] [--report set/walk.cycle-align.json]
+ [--foot side-walk=left] [--state walk] [--report set/walk.cycle-align.json]
```
- **Two cycles in one loop are stopped, and counted by whoever looks**: one length for the set is
@@ -441,12 +441,32 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-
not all name their foot may not start on one foot. Without `--view` no foot is named and the
report says that once. A character drawn without shading on the far leg leaves its side and
diagonal views unnamed; mirroring a loop afterwards (a left view made from a right one) swaps
- its own feet.
+ its own feet. Every loop row says who named its foot: `start_foot_source` `"engine"` (the view's
+ cue), `"given"` (`--foot`, below) or `null` (nobody), and `strikes` — its two strikes as frames of
+ the rebuilt `cycle/`, the larger first.
+- **A foot the engine cannot name is told, one loop at a time**: each loop whose foot is not named
+ is listed in the report's **`unnamed_feet`** — per loop `dir`, `name`, `view`, `foot_why`,
+ `candidates` (the two strikes: `strike` 0 and 1, `frame` in `cycle/`, `path` to that frame; the
+ first is the frame the loop now starts on, the second half a cycle on) and `settle` (the two
+ `--foot` arguments). Whoever looks — a person, the agent, or a vision call shown the two frames —
+ says which own foot lands on the first candidate, and that comes back as
+ **`--foot <loop>=left|right`** (repeatable; `<loop>` is named as for `--cycles`: the `--loop-dir`,
+ its strip's name, its directory's name, or a `video-set` item's name). That loop alone starts as
+ `--start-foot` lands — on the first candidate if it is that foot, half a cycle on if it is the
+ other — and every other loop comes out byte for byte as it would have. The row records
+ `start_foot_source: "given"`, `foot_given` (the feet at the two strikes) and, where the engine had
+ not named it, `foot_unnamed_why`; the report records `feet_given`. A foot given for a loop the
+ view did name is still taken, and where it disagrees the row carries `foot_disagrees` (the cue's
+ reading) and a warning says so. A `--foot` that names no loop, two loops, or something other than
+ `left`/`right` is refused before anything is rewritten. The answer is about the loop as filmed —
+ the strikes are read from `cycle.source/` resampled again — so it holds for every later alignment
+ at the same length, and like `--cycles` it is not remembered: the next alignment needs the same
+ `--foot`. The algorithm that names feet is not changed by it.
- **Rebuilt in place**: `cycle/`, `<name>.strip.png` / `.strip.json`, `.gif`, `.webp` are
rewritten at the loop's own cell rules (`cell_height_cap`, body-height target, anchor), at the
loop's frame rate, so the aligned cycle lasts L*/fps seconds. `strip.json` gains
`cycle_align` (`from`, `to`, `between`, `taken`, `made_by_rife`, `made_at`, `smear` and/or
- `nearest_at`, `drawings`, `retake`, `turned_by`, `turned_on`, `view`, `start_foot`, the seam ratio of the rebuilt
+ `nearest_at`, `drawings`, `retake`, `turned_by`, `turned_on`, `view`, `start_foot`, `start_foot_source`, `strikes`, the seam ratio of the rebuilt
cells, and the re-verified GIF/WebP).
- **The cut as filmed is kept** in `cycle.source/` on the first alignment, and every later
alignment reads from there: running it again, or at another length, never resamples a
@@ -462,6 +482,11 @@ carries `cycle_align` per state and `<state>.cycle-align.json`; a failed alignme
failed (section 1, "Without RIFE"); install it and run `video-cycle-align` on the set's loops.
A set stopped on a suspect is skipped the same way (`reason: "cycle-suspects"`, the loops under
`suspects`, a warning naming them): count their cycles and run `video-cycle-align --cycles`.
+A state whose loops leave a foot unnamed carries them under `cycle_align.<state>.unnamed_feet`; the
+answer goes back as `video-set --align-foot <item>=left|right` (the item's name, e.g. `side-walk`;
+only an item of a walk or run filmed in two or more directions is taken, any other is refused before
+filming), or as `video-cycle-align --foot` on the set's loops. A foot given for an item that failed,
+or whose state was not aligned, is named in that state's `feet_unused` and a warning.
Cutting a loop again with `video-loop` removes its `cycle.source/`, so the next alignment reads
the new cut. An alignment also clears a follow-through (`video-follow`, which moved the old
cells): `follow.source.png` and the strip's `follow` record are removed and the loop's row says
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 53aa686..08f460e 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -291,7 +291,11 @@ order, so that every loop starts as the same own foot lands wherever its view ca
apart. A frame that falls between two source frames is made by RIFE, and the command fails where one
is needed and RIFE is not installed; `--between nearest` makes none. A frame RIFE made that melted
(lost its outline where legs crossed too far) is replaced by the nearer source frame and named
-(`--between auto`, the default; [loop repair](loop-repair.md) section 4).
+(`--between auto`, the default; [loop repair](loop-repair.md) section 4). A loop whose view cannot
+tell its feet apart starts on its larger strike and is listed under the report's `unnamed_feet` with
+its two strike frames in `cycle/`: look at the first, say which own foot lands there, and run the same
+alignment again with `--foot <loop>=left|right` — that loop alone turns to start on the set's foot
+(`start_foot_source: "given"`).
`--character` or `--motion` words that turn the subject another way than `--facing`, or put a
`--handed` item on its other side, come back in `warnings`; the prompt is the same either way
@@ -907,7 +911,8 @@ and turned to start as the same own foot lands in every view — read off the le
ear or a hat's point, and the foot told apart by the item's own view and facing (`--align-cycles
auto`, the default; `off` keeps each loop's own length). The same step stands alone as
`sprite-gen video-cycle-align --loop-dir … --view …`. `set.report.json` carries `cycle_align`
-per state (with `start_foot` per item), a failed alignment is listed as `cycle-align:<state>`,
+per state (with `start_foot` and `start_foot_source` per item, and the loops whose foot nobody named
+under `unnamed_feet`, told back with `--align-foot <item>=left|right`), a failed alignment is listed as `cycle-align:<state>`,
and a made frame with a smear, one that melted and was replaced, or a loop whose foot could not be named is a line under
`warnings`. A held loop stretched past what an interpolator bridges is named for a new take: the
state's `retake` (reason `held-drawings`, with its numbers; per item under `cycle_align.retake`) and