Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(loop-repair): a filmed ghost with no clean frame beside it is a retake reason; one record, reasons in order
Soohong Kim15f7e6eadbab
diff --git a/SKILL.md b/SKILL.mdindex 6cc62a0..440a5d4 100644--- a/SKILL.md+++ b/SKILL.md@@ -142,4 +142,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 or carries a ghost takes the nearer source frame, and a filmed ghost frame a clean one beside it; a made frame the report names as a possible cross-fade of two drawings, `look`, is kept — look at it, and where the legs show twice use `--between nearest` or film that direction again) 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). `video-loop --anchor motion-auto` already cuts a walk two steps long — one cycle — where a staff held above the head closes only there (`cycle.steps`, `strip.json` `steps: 2`; `video-cycle-align` aligns it as the one cycle it is). When its report's `cycle.step_screen` says `suspect` (a slow walk cut one step long), or `video-cycle-align` stops on a loop under `one_step`, count the steps in the loop (how often each foot lands) and cut it again with `video-loop --steps 1` if it is one step (`--steps 2` if it is two); never stretch or double it by hand. When `video-loop` warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), or that the held part does not close at the wrap below its top, that part does not close at the cut: look at the loop, and try `--cycle fixed` with another cut before filming again; a walk refused for no cycle names in its report's `cycle.candidates` the windows it measured, best first, for a cut you must deliver anyway ([loop-repair](docs/loop-repair.md) section 3, "The seam pop" and "The held side").+[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 or carries a ghost takes the nearer source frame, and a filmed ghost frame a clean one beside it; a made frame the report names as a possible cross-fade of two drawings, `look`, is kept — look at it, and where the legs show twice use `--between nearest` or film that direction again) 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; or `filmed-ghost`: a filmed ghost frame has filmed ghosts on both sides, so no clean frame stands there and the loop shows it — `reasons` lists both where both apply), 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). `video-loop --anchor motion-auto` already cuts a walk two steps long — one cycle — where a staff held above the head closes only there (`cycle.steps`, `strip.json` `steps: 2`; `video-cycle-align` aligns it as the one cycle it is). When its report's `cycle.step_screen` says `suspect` (a slow walk cut one step long), or `video-cycle-align` stops on a loop under `one_step`, count the steps in the loop (how often each foot lands) and cut it again with `video-loop --steps 1` if it is one step (`--steps 2` if it is two); never stretch or double it by hand. When `video-loop` warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), or that the held part does not close at the wrap below its top, that part does not close at the cut: look at the loop, and try `--cycle fixed` with another cut before filming again; a walk refused for no cycle names in its report's `cycle.candidates` the windows it measured, best first, for a cut you must deliver anyway ([loop-repair](docs/loop-repair.md) section 3, "The seam pop" and "The held side").diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex bb32e4f..b8db669 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -616,12 +616,16 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-is a ghost too, under `auto` and `nearest`; a made frame that is a ghost gives way like anyfaulty one, to the nearer source frame, or to the other beside its time where the nearer is afilmed ghost. `rife` keeps both, named. Where both frames beside it are ghosts the ghost is- kept, named, and the line says to film the direction again. A loop already the set's length- is screened the same way.+ kept, named, and the loop is a take to film again (`retake`, reason `filmed-ghost`, below). A+ loop already the set's length is screened the same way.- Each cell where a filmed ghost would have been delivered is listed in `ghost_at` (`at`, theghost `source` as a frame of `cycle.source/`, its `ghost` reading, and the frame `taken` — the- ghost itself where it was kept), with a line in `warnings` ("source frame 5 is a filmed ghost- (…), so source frame 6 beside it was taken there"). `cells_from` says the same per cell.+ ghost itself where it was kept, with why: `kept` is `no-clean-frame` where neither source frame+ beside its time is clean, under any `--between`, and `between-rife` where `rife` kept it beside+ a clean one), with a line in `warnings` ("source frame 5 is a filmed ghost (…), so source frame+ 6 beside it was taken there"). `cells_from` says the same per cell. A made frame given way at+ such a cell says which: the other frame beside its time taken, "the nearer being a filmed+ ghost", or the nearer kept, "the frames beside it being filmed ghosts too".- Where 0.3 % sits: set by eye on drawn walks, between the half-drawn frames (and the framesmade beside them) that a person sees as ghosts, which read well above it, and the frames seenas clean, which read well under it; a sliver of the same kind, too small to see at a strip's@@ -709,11 +713,28 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-`name` and the same numbers), a warning line names it ("film this direction again(held-drawings) — …", by its directory where two loops share a strip name), and `video-set`carries both into its record.+ - **A filmed ghost with no clean frame beside it** (reason `filmed-ghost`): a ghost the screen+ names at a time whose source frames on both sides are ghosts too (three in a row at a whole+ time, two at a time between them) is delivered as filmed — no frame of the take shows the+ drawing there, and nothing but a new take fixes it. A loop with **one or more** such cells+ (`ghost_at` `kept: "no-clean-frame"`, `align.RETAKE_GHOST_KEPT_MIN`) is named whatever its+ hold; a ghost `--between rife` kept beside a clean frame (`between-rife`) is the choice of+ whoever aligned it and is not counted. Its numbers are under `ghost`: the cells `kept`, their+ frames of `cycle.source/` (`sources`), the highest reading (`ghost_max`) and the screen's+ `limit`, with `limits.ghost_kept_min`. Its line: "film this direction again (filmed-ghost) —+ frame(s) 5 show source frame(s) 10 of cycle.source/, filmed ghosts (…), and the source frames+ beside each are filmed ghosts too …".+ - **One record per loop**: `retake` is one object (or `null`). `reason` is the first reason+ that applies, `held-drawings` before `filmed-ghost`, and `reasons` lists every one; the held+ numbers (`hold`, `drawings`, …, `unmade`) stand only where `held-drawings` applies, `ghost`+ only where `filmed-ghost` does, and `limits` carries each one's. A held loop that also keeps a+ ghost reads `reason: "held-drawings"`, `reasons: ["held-drawings", "filmed-ghost"]`, with a+ line for each — one new take fixes both.- **Not named**: a held loop at its own length (nothing is made — on twos it plays at 12 asecond, as filmed), a held loop whose made frames all kept their outline, a held loop squeezedto 13 drawings a second or more (its drawings come closer than on twos), and a loop drawn everyframe with a replaced frame (one soft step, not a gap the take cannot fill).- - **Exit code and words**: the set is still aligned and written (`applied: true`, exit 0) — the+ - **Exit code and words** (both reasons): the set is still aligned and written (`applied: true`, exit 0) — theloop is the best this take allows, and the caller decides: a pipeline with a retake budgetfilms that direction again and aligns the set anew; one without delivers it with the warning.Nothing passes quietly: the line is on stderr and in `warnings`, and `retake` is thediff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex dfe7010..ff61837 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1093,7 +1093,9 @@ under `unnamed_feet`, told back with `--align-foot <item>=left|right`), a failedand 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: thestate's `retake` (reason `held-drawings`, with its numbers; per item under `cycle_align.retake`) and-a warning line ([loop repair](loop-repair.md) section 4, "Held drawings"). Two cases skip the alignment with a warning instead of failing it (`applied: false`,+a warning line ([loop repair](loop-repair.md) section 4, "Held drawings"), as is a loop that delivers a filmed+ghost with no clean frame beside it (reason `filmed-ghost`, its cells under `ghost`; `reasons` lists both+where both apply). Two cases skip the alignment with a warning instead of failing it (`applied: false`,`reason`, and a line under the report's `warnings`): no RIFE (`rife-not-installed`), and a loopthat may hold more than one cycle (`cycle-suspects`, the loops under `suspects`; count them, then`video-cycle-align --cycles <loop>=<k>`). See [loop repair](loop-repair.md) section 4.