Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge branch 'main' into aldegad/transparent-ref-alpha
Soohong Kimc9b1f8144162
diff --cc CHANGELOG.mdindex f1c1ea6,db4ebac..4187378--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -2,11 -2,13 +2,16 @@@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.- ## Unreleased+ ## Unreleased - A character with an item on one side has its left-facing views drawn, not mirrored++ - **Handedness, said once** (`sprite_gen/gen/handedness.py`): `--handed "<item>=<left|right> [part]"` names an item on one of the character's own sides ("the black smartwatch=left wrist"); the engine works out where that side is in each view — the picture's right or left in a front, back or diagonal view, near or far in a side or diagonal view (`placement`) — and says it in the prompts (`text`). `sprite-gen gen --direction <view> [--facing …] --handed …` adds the engine's still view sentence and, per item, which side it is on, where that is in the view, and that the sentence outranks an attached picture; with `--handed`, `--facing-fix mirror` is refused and `regen` never falls back to a mirror. `video-prompt --handed` and `video-set --handed` end the clip prompt with where the item stays, anchored to the first frame and named once where it shows; on the far side of a side view it is not named at all — the near arm "stays bare, exactly as in the image" — since a clip prompt that names a hidden item draws it on the near arm. [docs/video-pipeline.md](docs/video-pipeline.md#handedness--an-item-on-one-side).+ - **Left-facing views drawn, not mirrored — opt-in**: `video-set --facing right,left` films every side and diagonal view both ways, each from its own still (`--base side@right=… --base side@left=…`); a turned view missing a still for one facing is refused, naming the `gen --direction … --facing …` call that draws it. Items are named `<view>-<facing>-<state>`, the table names the facing, each side still is inspected for its own facing, and gaits are aligned across all eight. With `--handed`, a front or back walk's mid-step redraw is told the item's side as well. Mirroring stays the default (drawing costs as much again); one facing keeps the item names and table as before.+ - **New `sprite-gen handed-check`** checks a still or loop frame by frame: a colour-marked item (`--marker`, a saturated colour nothing else on the character has) must sit on its view's picture side of the body's centre, in one place only, showing in at least half the frames on a near side and, against a `--reference` front or back picture, no more than a sliver on the far side of a side view and more than a sliver on its near side — a side view has no picture side, so a far sliver turned over to face the other way does not count as the near item shown. Without a reference both size rules are reported unchecked (`far_hidden`, `near_whole`). `--strap --zone` adds the item's band seen without its marker (a bare strap on the other arm) within the rows it sits in. Specks of the marker's hue left on outlines by a clip's colour blocks are recorded, not judged. `--board` draws every frame with its verdict; exit 1 on a failure. Drawn test figures pass as they should look and fail turned over in every view, a side view's far sliver against `--reference` (`tests/qa/test_handed_check.py`).+ - **Fix: a diagonal facing left was filmed heading right.** The diagonal walk and run sentences said "to the right" and "toward the upper right" whatever `--facing` was; they now take the facing ("heading diagonally toward the viewer and to the left"). `video-prompt` and `video-set` also cut a left-facing diagonal's loop with `--facing left` (it was always `right`), which mirrors the jump repair's hair box. Right-facing prompts are unchanged.+- **A `gen --transparent` run with `--ref` keeps the alpha it comes back with**: `auto` still plans a chroma key before the model runs (2026-09-08: codex drew a checkerboard in 5 of 6 ref runs asked for alpha), but the raw is read before the key is applied (`chroma.classify_raw_alpha`). A raw with an alpha band, at least 5 % of it at alpha 0 and at least half of its border at alpha 0 is published on its own alpha through the native check, with `alpha.strategy: "native"` and `alpha.strategy_source: "refs-attached-raw-alpha"`. Keying it read the RGB under alpha 0 as the background and took the outline and light fills off: a transparent reference is answered with alpha, and a fox redrawn from one lost its outline and cream belly. A checkerboard, a key background or an opaque RGBA (no alpha band, or no alpha 0) is keyed as before (`refs-attached`); alpha 0 that misses either bar is keyed as before with a `warning`. `alpha.raw_alpha` records the verdict and its numbers on every ref run that planned the key. `--alpha-mode chroma` keys whatever comes back, and `--decontam palette` refuses a raw that came back transparent. [docs/gen.md](docs/gen.md#transparent-output--strategy-per-provider).+- Measured 2026-10-04 on codex `image_gen` (subscription), one transparent front still as the reference, three takes per arm: with the planned key's prompt, a transparent reference came back with real alpha 3/3 and the same still on white came back on opaque white 3/3; asked for alpha (`--alpha-mode native`), both came back with real alpha 3/3, with no checkerboard in 6 runs. The step down is kept until a larger measurement replaces the 2026-09-08 one.+## v2.21.0 - A clip made by a video MCP on your agent (ZCRE) becomes a loop: the prompt comes out, the mp4 goes in- **New `sprite-gen video-prompt`** prints the clip prompt `video-set` sends for one (direction, state) — `build_prompt` with `--character`, `--motion` and `--model` — so an agent that makes the clip itself, with a video MCP connected to it, sends the same sentence. `--json` adds the duration (the state's own), whether the clip ends on the canvas (`last_frame`), the loop cut (`cycle`), the canvas, clip, frames and loop steps with placeholders, and for a front or back walk the mid-step redraw (`start_still`). sprite-gen never calls the MCP: the agent uploads the `video-canvas` still, quotes, asks the user, generates and saves the mp4, and `video-frames` and `video-loop` take it from there. [docs/video-pipeline.md](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre).