Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
release: v2.22.0
Soohong Kimfef4160205d0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d954bee..837f5de 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 - A character with an item on one side has its left-facing views drawn, not mirrored+## v2.22.0 - A character with an item on one side has its left-facing views drawn, not mirrored, and an attack is filmed with less room above- **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.@@ -13,6 +13,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **The step down asks for the key it plans**: a `gen --transparent --ref` prompt that names no key background gets the `--chroma-key` key's line (`chroma.KEY_BACKGROUND_TEXT`, moved from `video.batch` so a clip's mid-step redraw and this run say the same sentence); a prompt that names a key — its hex code, or "magenta/green background", "chroma key", "screen" — is left as it is, with no second line. `alpha.key_background` records `injected` and the key. A reference on white with no key in the prompt came back on opaque white (3/3) and keying it took the outline and the cream fills; with the line, five takes (three on that reference, two on the transparent one) came back on a magenta key and kept both. `--alpha-mode chroma` and native runs are unchanged. [docs/gen.md](docs/gen.md#transparent-output--strategy-per-provider).- **`--decontam` is skipped, not refused, on a ref raw that came back transparent**: it has no key to remove, and the refusal came after the paid generation. `alpha.decontam` records what was asked and why it was skipped, and stderr says so (a warning for `palette`).- `chroma.classify_raw_alpha` judges on the pixel counts, not the rounded percentages: a raw with alpha 0 under 0.005 % was `no-alpha` and keyed with no warning; it is `ambiguous` now.+- **An attack canvas keeps 20 % of its height above the still, not 35 %** (`STATE_CANVAS["attack"]`; 28 % in front and 20 % behind are unchanged). The extra room only made the body a smaller part of the clip, so `video-loop --body-height` scaled it up to the delivery height; with 20 % the body is larger in the clip and is scaled down. A 1024 px square still now pads to 2276×1280 instead of 2800×1575. 20 % still holds a weapon raised about a third of the body above the head: the canvas adds at least a quarter of the still's height above it, and the still's own margin over the crown does the rest (8 % of its height is enough). A still cropped at the crown needs `--headroom 0.26` or more for an overhead swing. At this headroom the 16:9 ratio, not `--lead`, sets the width of a square still's canvas. [docs/video-pipeline.md](docs/video-pipeline.md#1-canvas--the-input-frame-decides-the-output-frame).+- **`--shape wide` keeps 35 % above** (`WIDE_OVERRIDE`, no longer the attack row): it is forced on states whose own row is another shape — `video-set --shape wide` across a batch, or a canvas widened after the subject touched a side edge — and a jump is one of them; 35 % on 16:9 keeps about the room a jump's tall row leaves above the still. A forced-wide canvas is the same as before; an attack in a `--shape wide` batch gets that row, as a cheer or a projectile already did.## 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@@ -21,8 +23,6 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **`video-frames` reads the picture of a clip that carries more**: it takes the first video stream that is not a cover image (`attached_pic`, `stream_index`), and records `codec`, `pix_fmt`, `audio_streams` and `cover_streams`. A ZCRE clip always has an AAC track and an mjpeg cover; the audio is never extracted and the loop outputs carry no sound.- Measured once end to end: one side walk, 720p 3 s, 52 credits, 33.6 s to generate; the clip was 960×960 H.264 `yuv420p` with an AAC track and a cover, and it cut to a periodic 20-frame loop.- **The places that moved or scaled a keyed picture with BICUBIC map it with coverage and colour apart** (`transform_cell`, beside `resize_cell` in `sprite_gen/util/resample.py`): the gait fallback's scaled-back frames (`video-loop --anchor motion-auto` on a walk that grows or shrinks through the clip) and a curated move, scale, rotation or shear baked on a smooth row (`curation.apply_transform`, so `compose`, the GIF, the PNG export and the cycle bake). BICUBIC over premultiplied RGBA has the same negative lobe as LANCZOS, smaller, and drew the same lighter rim and key tint at the edge. On the synthetic outlined figure (`tests/keyed_figure.py`) it left 1,088 to 1,864 pixels with a colour none of the four source pixels under them had when a frame was scaled back by 0.84x to 1.19x, and 840 to 2,102 for a half-pixel move, a 10° rotation, a 0.75x shrink, a shear and a 1.3x grow with a 15° rotation; none are left. Coverage keeps BICUBIC's edge, held to the coverage of the 2 x 2 source pixels the colour mixes from; colour is a BILINEAR mix of premultiplied colour, so it is no longer sharpened. A pixel row's curated transform (`fit.pixel_unfake`, NEAREST and re-snapped) and an identity transform are unchanged. The scene GIF's downscale stays LANCZOS: it scales opaque composited frames, where there is no coverage to divide by. [docs/video-pipeline.md](docs/video-pipeline.md), [docs/loop-review.md](docs/loop-review.md), [docs/curation.md](docs/curation.md), [docs/pixel-unfake.md](docs/pixel-unfake.md).-- **An attack canvas keeps 20 % of its height above the still, not 35 %** (`STATE_CANVAS["attack"]`; 28 % in front and 20 % behind are unchanged). The extra room only made the body a smaller part of the clip, so `video-loop --body-height` scaled it up to the delivery height; with 20 % the body is larger in the clip and is scaled down. A 1024 px square still now pads to 2276×1280 instead of 2800×1575. 20 % still holds a weapon raised about a third of the body above the head: the canvas adds at least a quarter of the still's height above it, and the still's own margin over the crown does the rest (8 % of its height is enough). A still cropped at the crown needs `--headroom 0.26` or more for an overhead swing. At this headroom the 16:9 ratio, not `--lead`, sets the width of a square still's canvas. [docs/video-pipeline.md](docs/video-pipeline.md#1-canvas--the-input-frame-decides-the-output-frame).-- **`--shape wide` keeps 35 % above** (`WIDE_OVERRIDE`, no longer the attack row): it is forced on states whose own row is another shape — `video-set --shape wide` across a batch, or a canvas widened after the subject touched a side edge — and a jump is one of them; 35 % on 16:9 keeps about the room a jump's tall row leaves above the still. A forced-wide canvas is the same as before; an attack in a `--shape wide` batch gets that row, as a cheer or a projectile already did.## v2.20.0 - A keyed picture is scaled without a light rim or a green tint at the edge wherever the engine scales one: a row frame, a sliced sheet, a scene layerdiff --git a/SKILL.md b/SKILL.mdindex 96464d9..a62fa6a 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 2.21.0+version: 2.22.0description: "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, 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, rig layers, engine exports, repeating backgrounds, projected shadows, motion/contact inspection and optional scene composition from existing assets."license: Apache-2.0depends_on:diff --git a/pyproject.toml b/pyproject.tomlindex 3734d42..45504f7 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 = "2.21.0"+version = "2.22.0"description = "Component-row pipeline for clean 2D game sprites and animation atlases"readme = "README.md"license = "Apache-2.0"