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(video): the prop plate in video-pipeline section 1 and a pointer in section 3, SKILL.md, the docs index, and the CHANGELOG's Unreleased (v3.12.0)

Soohong Kim4b16107485e4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7cb922..9b23f9b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v3.12.0)
+
+**Upgrading from 3.11.0: runs without the new options produce unchanged outputs: every canvas, frame, strip, GIF, WebP, and report keeps its exact bytes (with only the loop report's `producer.implementation_sha256` changing with source code changes).**
+
+- **New: `video-canvas --prop-plate`** paints a flat magenta plate, RGB (255, 0, 255), on the canvas in front of the subject (`--facing`) standing on the subject's foot row, sized by `canvas.subject_box` (height 0.49, thickness 0.20, near side 0.84 of subject height ahead of the subject's front). Requires a green key and `--report`. Refuses non-green keys, missing `--report`, state `effect`, or plates extending past the canvas edge. The report records `prop_plate` with `box`, `rgb`, `subject`, and `of_subject_height`.
+- **New: `video-frames --prop-plate <canvas report json>`** reads the plate box from the canvas report, scales it outward to frame coordinates with a 3 px rim (`erase_box`), and erases the plate from keyed frames before handover. Pixels are erased where red and blue lead green by more than 35 and are within 90 of each other, or where each channel (including alpha) is within 40 of the whole-clip median. Refused runs keep the plate; `video-loop` cuts of erased frames carry no plate; `video-set` does not paint or erase a plate. The report records `prop_plate`.
+- Limits: the video model must keep the plate in place; a one-pixel shift leaves grey blend lines down the sides (188 and 95 pixels in synthetic tests). Subject edge pixels tinted magenta by the codec are erased (2 pixels in each of two frames in synthetic tests). No other guard, retry, or measurement is added.
+- Python callers: `sprite_gen.video.prop_plate` (`place`, `paint`, `read`, `frame_box`, `erase`; constants `RGB`, `HEIGHT`, `WIDTH`, `GAP`, `RIM`, `MAGENTA_LEAD`, `MAGENTA_BALANCE`, `STILL_TOLERANCE`); `canvas.run_canvas(..., prop_plate=False)`; `frames.run_frames(..., prop_plate=None)`; `frames.key_frames(..., plate=None)`.
+- **Docs**: [video-pipeline.md](docs/video-pipeline.md) section 1 subsection and section 3 pointer; `SKILL.md`; `docs/README.md`.
+- **Tests**: `tests/video/test_prop_plate.py` (12 synthetic tests: canvas painting facing right and left, unchanged canvas without option, refusals for bounds, key, and report, frame erasing, one-pixel model shifts, subject crossing preservation, frames outside the box, erase reading the canvas report box, refusal for report without plate or not a canvas report, frame box arithmetic, loop cuts without magenta). Red first: median without alpha lost 47, 47, 136 and 136 outline pixels in frames 8 to 11; with alpha, 2, 2, 0, and 0 codec-tinted pixels. Mutation check: median without alpha fails test 7; no magenta rule fails tests 6 and 12; no median rule fails test 6; rim 0 fails three tests; unscaled box fails two.
+
## v3.11.0 - Sway regions laid over the figure (--region-over), rims widened for shear (--region-shear), figure membranes (--region-membrane), and recut strip pairing by cell records (--read-on-cut)
**Upgrading from 3.10.1: `video-loop` writes `cell_record` into every strip record `<name>.strip.json`, and `video-sway` gains options that shape a `--region-mask` region alongside `--read-on-cut`. Strips, frames and records keep their bytes by default, but `video-sway --read-on-cut` reads cuts by that record alone and refuses cuts made without it.** New options `--region-over` and `--region-shear` shape the region mask and its rim; both are off by default, and when not given, strips, frames, and records remain byte for byte what they were. With `--region-crease` the wear wears the crease in as before; laid over the figure the region reaches down to the crease again in every cell, changing those runs' output. Runs with `--region-over` and runs with `--region-membrane` draw differently than in 3.10.1; the four new membrane options are off by default and byte for byte as before when not given. New options `--region-over-solid`, `--region-rim-round`, `--region-membrane` and `--read-on-cut` are off by default; when not given, strips, frames, and records remain byte for byte what they were. Runs with `--read-on` alone behave as before, except that its no-match message now names `--read-on-cut`. The refusal for `--region-over` or `--region-shear` given without `--region-mask` keeps refusing the same runs, and its message now names the new options too: "--region-over, --region-over-solid, --region-rim-round, --region-shear and --region-membrane shape a region mask; they need --region-mask" (it was "--region-over and --region-shear shape a region mask; they need --region-mask").
diff --git a/SKILL.md b/SKILL.md
index 4ac40c7..1029ca6 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -135,6 +135,8 @@ Every cut is read for held cells (neighbour cells showing the same picture), and
A move played once (a jump, a vault: `once`, `once-return`, `one-shot`) carries its root motion in the strip sidecar by default, the cells unchanged: `root_motion` gives each cell's root (the body's mass centre, cell px), what it stands on, and each air's take-off, landing, seconds and apex; a game reads `root` to place each cell and moves the body on its own physics. A move cut out of a longer motion is named with `video-loop --cycle once --start S --length L`, a hand on something the clip does not draw with `--contact hand=A:B`, metres with `--meters-per-px`. To give the air its own length, gravity and speed, `--air-retime gravity=G,air=T,speed=V` redraws it on that parabola with RIFE's frames between; contacts and the take-off and landing stay as filmed. Tell the user each air in one line, its seconds and its apex (the summary's `air`, e.g. `air 0.42 s, apex 0.21 m`). Details in [video-pipeline](docs/video-pipeline.md#root-motion--a-cut-played-once-where-the-body-is-what-it-stands-on-its-air).
+For a move over an obstacle that clears a low wall (such as a vault or a jump), paint a flat magenta plate on the green key with `video-canvas --prop-plate` (which requires `--report`), then pass that canvas report to `video-frames --prop-plate <canvas report json>` to erase the plate from keyed frames. The plate box lives in the canvas report, which `video-frames` reads directly to scale and position the erase box; there is no second copy. If the video model drew the plate off its place by even a single pixel, grey blend lines remain down its sides: tell the user if any keyed frame kept lines of the plate. Details in [video-pipeline](docs/video-pipeline.md#prop-plate---prop-plate).
+
A pinned idle or attack whose last frame the video model drew again has its wrap blended by default (`video-loop --wrap-blend auto`, a redraw only; `off` cuts as filmed), with details in [loop repair](docs/loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again).
Scene creation consumes finished assets and remains optional. Asset metadata owns frames, native durations and anchors; scene specs own placement, scale, playback rate, planes, camera and light. Measure stride only with declared same-foot contact and an isolated foot ROI; unknown contact stays unverified. Apply only a verified report for the exact selected asset with an explicit scene direction. Never infer walking direction from the bottommost silhouette, reverse frames or change source assets to make a scene work.
diff --git a/docs/README.md b/docs/README.md
index 9b5f007..0982363 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -40,7 +40,7 @@ flowchart LR
| Pipeline / tool group / workflow | Entry doc | Verbs |
|---|---|---|
| **A · atlas rows** — one still becomes a runtime sprite sheet | [run-contract.md](run-contract.md) | `prepare` → `gen` / `gen-set` → `extract` → `compose-atlas`; optional `curation` and recompose |
-| **B · video → loop** — one still becomes transparent motion loops | [video-pipeline.md](video-pipeline.md) | `video-canvas` → `video` (or `video-prompt` and a video MCP on your agent) → `video-frames` → `video-loop`, `video-set`, `video-cycle-align`, `video-sway`, the Sway layer (`video-sway-inspect` shows every cell of it and moves nothing; old names `video-follow`, `video-follow-inspect`), `video-set-sheet` (a set's directions on one sheet, on one ground line), `video-stop` (a walk or run that stops, from the clip's own start played backwards); `handed-check` for an item on one side |
+| **B · video → loop** — one still becomes transparent motion loops | [video-pipeline.md](video-pipeline.md) | `video-canvas` → `video` (or `video-prompt` and a video MCP on your agent) → `video-frames` → `video-loop`, `video-set`, `video-cycle-align`, `video-sway`, the Sway layer (`video-sway-inspect` shows every cell of it and moves nothing; old names `video-follow`, `video-follow-inspect`), `video-set-sheet` (a set's directions on one sheet, on one ground line), `video-stop` (a walk or run that stops, from the clip's own start played backwards); `handed-check` for an item on one side; obstacle plate painted and erased (`--prop-plate`) |
| **C · utilities** — imported images in, clean cuts out | [sheet-slicing.md](sheet-slicing.md) | `cutout`, `slice-sheet`, `ui-kit`, `unpack-atlas` |
| **D · post-processing** — finished sheets, refined | [recolor.md](recolor.md) | `recolor`, `recolor-palette`, breathing (compose, or `breathe` on a folder of frames), `export-pngs`, `export-aseprite` |
| **E · asset tools** — independent background, shadow and motion tools | [asset-tools.md](asset-tools.md) | `background-tile`, `shadow`, `inspect-motion` |
@@ -84,7 +84,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| [logo.md](logo.md) | `sprite-gen logo`: a title logo or wordmark lettered by the model into a title screen or poster, only its lettering redrawn on a chroma key, cut out with its glow kept — the steps, files, report, text check and refusals, the key choice, the logo matte and its known limit |
| [prompt-assembly.md](prompt-assembly.md) | What the engine adds to a still or clip prompt and when: the pieces, the 2.22.0 freeze without `--handed`, what counts as already said, and the notes on the caller's own words |
| [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit` / `video-resume`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing, asking again for an unfinished generation) with the user's own credential |
-| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, a single play's root motion and its air retimed, the batch, a set's directions on one sheet, a walk or run's stop |
+| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, a single play's root motion and its air retimed, obstacle plate painted and erased (--prop-plate), the batch, a set's directions on one sheet, a walk or run's stop |
| [loop-review.md](loop-review.md) | Automatic loop decisions, ambiguous gait review, visual evidence and explicit cut/alignment overrides |
| [loop-repair.md](loop-repair.md) | RIFE (where it runs, cost, licences, `sprite-gen rife install`, what runs without it), jump-frame repair, the flow reading (frames off a walk's way), the eased retime (a part that rushes on its way), the overlapped wrap (a part on its own beat at a two-step cut's wrap), the part pop (a hand or a foot that jumps at the wrap), the jolt index and its gate, one cycle length per direction set |
| [frame-interpolation.md](frame-interpolation.md) | Generative in-betweens for sprite frames, recorded as a take |
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 5f5604a..46adbfa 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -1,6 +1,6 @@
# Video → sprite pipeline (engine SSoT)
-> Owns: Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, a single play's root motion and its air retimed, the batch, a set's sheet, a walk or run's stop · Index: [docs/README.md](README.md)
+> Owns: Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, a single play's root motion and its air retimed, obstacle plate painted and erased (--prop-plate), the batch, a set's sheet, a walk or run's stop · Index: [docs/README.md](README.md)
One still becomes a whole motion set: the still is padded into the canvas a state
needs, Grok Imagine animates it in place, the clip is keyed frame by frame, and one
@@ -95,6 +95,21 @@ padding is that same pure key. A corner that survives the matte fails loud
(the still is not on a key the engine can cut). `--key white` keeps the old behaviour: no
chroma key, the padding is the corner colour.
+### Prop plate: `--prop-plate`
+
+A move over an obstacle (a vault, a jump over a low wall) needs something to clear. When asked in words for a wall in the background colour, a video model draws a black slab, and keying leaves that slab in the keyed frames. The obstacle is therefore painted into the still the clip is made from as a flat magenta plate, RGB (255, 0, 255), on the green key, which keying does not take and a later erase pass removes. `video-canvas --prop-plate` (off by default) paints this plate in front of the subject on the side it faces (`--facing`), standing on the subject's foot row (the plate's bottom row is the subject's bottom row). Sized from `canvas.subject_box` on the canvas whose background was normalized to the exact green key, its height is 0.49 of the subject height, its thickness is 0.20, and its near side is 0.84 of the subject height ahead of the subject's front. The flag requires a green key and `--report`. A run writes no canvas and refuses if the key is not green ("--prop-plate paints a magenta plate on a green key"), if `--report` is omitted, for state `effect` ("an effect keeps its source canvas; drop --prop-plate"), or if the plate falls past the canvas edge on the facing side ("frame the subject with room in front (--shape wide, --lead)"). The report records `prop_plate`: `box` (left, top, right, bottom in canvas pixels, right and bottom one past), `rgb`, `subject`, and `of_subject_height` (`height`, `width`, `gap`). This box is the single value used for painting and erasing; `video-frames` reads it from the report with no second copy.
+
+`video-frames --prop-plate <canvas report json>` takes the canvas report path, joining the inputs a run never overwrites. It is checked before frame extraction and refused before keying if the file is not a canvas report or holds no plate ("holds no plate; the canvas was made without --prop-plate"). The box is scaled to the clip's frames by the ratio of frame size to canvas size rounded outward on each axis, then widened by a 3 px rim on each side (`erase_box`). On a run that passed, every keyed frame is erased inside `erase_box` before handover: a pixel becomes fully transparent when red and blue lead green by more than 35 and red and blue are within 90 of each other, or when each channel (with alpha as one of the channels) is within 40 of the median that pixel shows over the whole clip. The median represents the plate and its surroundings because the subject crosses for part of the clip only; checking alpha prevents transparent background pixels from reading as black, keeping the subject's dark outline intact across the rim. Refused runs keep the plate in their refused folder. The frames report adds `prop_plate` (`canvas_report`, `erase_box`, `rim`, `frames`, `frames_changed`, `erased_px`). `video-loop` cuts of erased frames carry no plate; `video-set` does not paint or erase a plate.
+
+The video model must keep the plate where the canvas has it. In a frame where the model draws the plate one pixel off, the plate's sides stay as the codec's grey blend of magenta and green about one pixel wide down each side, which neither erase rule takes (in synthetic tests, frames with the plate one pixel to the right keep 188 and 95 such pixels). Subject edge pixels tinted magenta by the codec are erased with the plate (2 pixels in each of two frames in synthetic tests). No other guard, retry, or measurement is added.
+
+```bash
+sprite-gen video-canvas --still still.png --out canvas.png --state jump --key green --facing right --prop-plate --report canvas.json
+# film canvas.png into clip.mp4 (section 2)
+sprite-gen video-frames --clip clip.mp4 --out-dir frames --key green --reference canvas.png --prop-plate canvas.json
+sprite-gen video-loop --frames-dir frames/keyed --out-dir loop --fps 24 --state jump
+```
+
## 2. Clip — `sprite-gen video`
For loops, prompt for **in-place, evenly paced, returns-to-start** motion on a flat
@@ -296,6 +311,8 @@ accepts only the subject at the edge — the clipping a `--fit tight` canvas cho
and still fails a frame where the key alone reaches the edge, which is a keying defect
whatever the framing.
+When filmed from a canvas holding an obstacle plate, `video-frames --prop-plate` erases the plate from every keyed frame before handover ([section 1](#prop-plate---prop-plate)).
+
**A drawing cut by its own frame**. A bust or half-length drawing runs off the frame
itself (its sleeve is cut off at the left, its hair at the top). In every frame of its clip the
subject touches those edges, and no taller or wider canvas gives it room there. The new default, `edge_policy: "border"`,