Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
video-loop: body_h is the standing height; --body-height scales every state to one size
Soohong Kim43b175bc33fc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 78acff3..d108132 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,10 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased (v2.0.3)++- `video-loop` `body_h` is the standing height (tallest floor-contact frame) instead of the cycle's median bbox height, which under-measured jumps and over-scaled them by ~22 %; `--body-height N` scales every state to the same standing height directly in the pipeline (`--strip-height` remains the cap). README heroes regenerated at one standing height.+## v2.0.2 - Heroes from the pipeline- `video-loop` GIF/WebP default rate is now 24 fps (the source rate): every cycle frame is kept, so fast actions never read slow; `--gif-fps 12` restores the lighter output.diff --git a/README.es.md b/README.es.mdindex dd7db7a..14d7afd 100644--- a/README.es.md+++ b/README.es.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>Cada bucle de arriba empezó como <b>una sola imagen fija</b>: rellenada al lienzo que su movimiento necesita, animada por Grok Imagine, recortada fotograma a fotograma y cortada en su periodo real en un GIF transparente — pipeline B, <code>sprite-gen video-set</code>.</sub></p>diff --git a/README.fr.md b/README.fr.mdindex 9d4e686..4ce1516 100644--- a/README.fr.md+++ b/README.fr.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>Chaque boucle ci-dessus est partie d'<b>une seule image fixe</b> : rembourrée au canevas que son mouvement exige, animée par Grok Imagine, détourée image par image et coupée à sa vraie période en GIF transparent — pipeline B, <code>sprite-gen video-set</code>.</sub></p>diff --git a/README.ja.md b/README.ja.mdindex 5ce2ab9..f45a5ba 100644--- a/README.ja.md+++ b/README.ja.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>上のループはすべて<b>静止画一枚</b>から生まれた: モーションに合うキャンバスへパディング → Grok Imagine で動かす → フレームごとにキーイング → 真の周期で切って透明 GIF に — パイプライン B、<code>sprite-gen video-set</code>。</sub></p>diff --git a/README.ko.md b/README.ko.mdindex f29bf7f..2643bbd 100644--- a/README.ko.md+++ b/README.ko.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>위 루프는 전부 <b>정지 이미지 한 장</b>에서 나왔다: 모션에 맞는 캔버스로 패딩 → Grok Imagine 으로 움직임 → 프레임마다 키잉 → 진짜 주기에서 잘라 투명 GIF 로 — 파이프라인 B, <code>sprite-gen video-set</code>.</sub></p>diff --git a/README.md b/README.mdindex 12c55cb..38d50ef 100644--- a/README.md+++ b/README.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>Every loop above started as <b>one still image</b>: padded into the canvas its motion needs, animated by Grok Imagine, keyed frame by frame, and cut at its true period into a transparent GIF — pipeline B, <code>sprite-gen video-set</code>.</sub></p>diff --git a/README.zh-Hans.md b/README.zh-Hans.mdindex c05f315..3a5745c 100644--- a/README.zh-Hans.md+++ b/README.zh-Hans.md@@ -9,11 +9,11 @@</p><p align="center">- <img src="docs/assets/hero-paladin-walk.gif" height="200" alt="paladin walk loop" />- <img src="docs/assets/hero-paladin-run.gif" height="200" alt="paladin run loop" />- <img src="docs/assets/hero-paladin-jump.gif" height="301" alt="paladin jump loop" />- <img src="docs/assets/hero-wolf-walk.gif" height="200" alt="wolf walk loop" />- <img src="docs/assets/hero-slime-walk.gif" height="200" alt="slime walk loop" />+ <img src="docs/assets/hero-paladin-walk.gif" height="202" alt="paladin walk loop" />+ <img src="docs/assets/hero-paladin-run.gif" height="206" alt="paladin run loop" />+ <img src="docs/assets/hero-paladin-jump.gif" height="246" alt="paladin jump loop" />+ <img src="docs/assets/hero-wolf-walk.gif" height="203" alt="wolf walk loop" />+ <img src="docs/assets/hero-slime-walk.gif" height="203" alt="slime walk loop" /></p><p align="center"><sub>上面每个循环都来自<b>一张静止图</b>:填充到动作所需的画布 → 由 Grok Imagine 驱动 → 逐帧抠像 → 在真实周期处剪成透明 GIF — 流水线 B,<code>sprite-gen video-set</code>。</sub></p>diff --git a/SKILL.md b/SKILL.mdindex 7f7ef5a..162fe1e 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 2.0.2+version: 2.0.3description: "Generate clean 2D game sprites and animation atlases with a component-row pipeline: base identity, numeric sprite-request SSoT, per-state layout guides, image-gen row strips, chroma-key alpha cleanup, connected-component frame extraction, cell-based atlas composition, QA reports, and runtime manifest frame_layout. Its curation webview also serves ANY image-candidate set (icons, logos, generated drafts) — agent chat can't render images, this can: unpack_atlas_run --pngs-dir import, then serve_curation side-by-side compare/pick. Palette-swap bake (`sprite-gen recolor`) turns a base sheet + palette map into N colourway sheets; the curation view blink-compares and adopts a pick into curation.json.recolor.picked. Curation triggers (KR/EN): 큐레이션, 큐레이션뷰, 큐레이션 해줘, 이미지 후보 보여줘/안 보임, 나란히 비교, 골라볼게 띄워줘, curation view, show image candidates side by side, let me pick. Recolor triggers (KR/EN): 팔레트 스왑, 팔레트 베이크, 리컬러, 색깔 바꾸기, 컬러웨이, 색 변형, 팔레트 맵, 색갈이, palette swap, recolor, colourway, colorway, bake variants, palette map."license: Apache-2.0depends_on:diff --git a/docs/assets/hero-paladin-jump.gif b/docs/assets/hero-paladin-jump.gifindex e91ae3a..0ecba49 100644Binary files a/docs/assets/hero-paladin-jump.gif and b/docs/assets/hero-paladin-jump.gif differdiff --git a/docs/assets/hero-paladin-run.gif b/docs/assets/hero-paladin-run.gifindex b926270..6d56618 100644Binary files a/docs/assets/hero-paladin-run.gif and b/docs/assets/hero-paladin-run.gif differdiff --git a/docs/assets/hero-paladin-walk.gif b/docs/assets/hero-paladin-walk.gifindex 964c829..6a210fc 100644Binary files a/docs/assets/hero-paladin-walk.gif and b/docs/assets/hero-paladin-walk.gif differdiff --git a/docs/assets/hero-slime-walk.gif b/docs/assets/hero-slime-walk.gifindex 1fa614d..2e3df59 100644Binary files a/docs/assets/hero-slime-walk.gif and b/docs/assets/hero-slime-walk.gif differdiff --git a/docs/assets/hero-wolf-walk.gif b/docs/assets/hero-wolf-walk.gifindex e518bd6..165d579 100644Binary files a/docs/assets/hero-wolf-walk.gif and b/docs/assets/hero-wolf-walk.gif differdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 38e6318..d5db236 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -118,9 +118,12 @@ Outputs:pad** so feet meet the floor, bottom-aligned, ≤ 64 cells **and ≤ 32 000 px wide** becauseChrome refuses images near 32 767 px — the cap is on pixels, so a 650 px cell allows 49cells and the meta says `subsampled`; ≤ 520 px tall) with `frames · w · h · body_h · delay_ms ·- cycle_frames · cycle_seconds`. `body_h` is the standing body height (median per-frame- bbox height): scale a jump strip — whose cells include air room — by `body_h`, not `h`,- and it reads the same size as a walk strip. `delay_ms = cycle_seconds / frames`, so a+ cycle_frames · cycle_seconds`. `body_h` is the **standing height** — the tallest frame whose feet touch the floor+ (a median over the cycle undercounts a jump, whose crouch and airborne frames dominate,+ and then over-scales it by ~22 %, 2026-09-09). Scale a jump strip — whose cells include+ air room — by `body_h`, not `h`, and it reads the same size as a walk strip;+ `--body-height N` does that scaling in the pipeline so every state comes out at the same+ character size (`--strip-height` stays the cap). `delay_ms = cycle_seconds / frames`, so a24 fps clip yields 41.67 ms cells; render at 24 fps to keep one cell per frame(a 30 fps render of 24 fps cells is a 5:4 pulldown and judders).- `<name>.gif` — `n_out` frames evenly across the cycle, 1-bit alpha, disposal 2, `loop=0`.diff --git a/pyproject.toml b/pyproject.tomlindex a0a5666..7f8e4c7 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.0.2"+version = "2.0.3"description = "Component-row pipeline for clean 2D game sprites and animation atlases"readme = "README.md"license = "Apache-2.0"diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 158d92c..a57578d 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -253,7 +253,7 @@ def _scrub(image: Image.Image) -> int:return n-def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS, max_height: int = STRIP_MAX_HEIGHT, max_width: int = STRIP_MAX_WIDTH, cycle_seconds: float) -> tuple[Image.Image, dict[str, Any]]:+def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS, max_height: int = STRIP_MAX_HEIGHT, max_width: int = STRIP_MAX_WIDTH, cycle_seconds: float, body_height: int | None = None) -> tuple[Image.Image, dict[str, Any]]:"""Union-crop (no bottom pad so feet meet the floor), scale, bottom-align, tile horizontally.The cell count is capped by the strip's PIXEL width (`max_width`) as well as by@@ -268,9 +268,15 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,top = max(0, min(b[1] for b in boxes) - 8)right = min(frames[0].width, max(b[2] for b in boxes) + 8)bottom = max(b[3] for b in boxes)- heights = sorted(b[3] - b[1] for b in boxes)- body_src = heights[len(heights) // 2]+ # body_h = the STANDING height: the tallest frame whose feet touch the floor. A median+ # over the whole cycle undercounts a jump (crouch + airborne frames dominate) and then+ # over-scales it — the 2026-09-09 hero read 22 % taller than the walk beside it.+ floor = max(b[3] for b in boxes)+ grounded = [b[3] - b[1] for b in boxes if b[3] >= floor - 4] or [b[3] - b[1] for b in boxes]+ body_src = max(grounded)scale = min(1.0, max_height / (bottom - top))+ if body_height is not None:+ scale = min(scale, body_height / body_src) # match the standing height; max_height stays an upper boundw = round((right - left) * scale)h = round((bottom - top) * scale)cap = max(1, min(max_cells, max_width // max(1, w)))@@ -293,6 +299,7 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,"subsampled": L > cap,"cell_cap": cap,"top_margin_px": top,+ "body_height_target": body_height,}return strip, meta@@ -359,6 +366,7 @@ def run_loop(start: int | None = None,length: int | None = None,strip_height: int = STRIP_MAX_HEIGHT,+ body_height: int | None = None,) -> dict[str, Any]:if cycle_mode not in CYCLE_MODES:raise SystemExit(f"video-loop: unknown --cycle {cycle_mode!r}; expected one of {', '.join(CYCLE_MODES)}")@@ -418,7 +426,7 @@ def run_loop(frames.append(im)cycle_seconds = L / fps- strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds)+ strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height)strip_path = out_dir / f"{name}.strip.png"strip.save(strip_path)atomic_write_text(out_dir / f"{name}.strip.json", json.dumps(strip_meta, indent=2) + "\n")@@ -489,6 +497,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--start", type=int, help="fixed cut: first keyed frame of the cycle (with --cycle fixed)")parser.add_argument("--length", type=int, help="fixed cut: cycle length in frames (with --cycle fixed)")parser.add_argument("--strip-height", type=int, default=STRIP_MAX_HEIGHT, help=f"cell/strip/GIF height cap in px (default {STRIP_MAX_HEIGHT}); the cycle is scaled down to fit, never up")+ parser.add_argument("--body-height", type=int, help="scale so the STANDING height (tallest floor-contact frame) is this many px — the same value across states gives the same character size; --strip-height stays the cap")parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")parser.add_argument("--report", type=Path)@@ -501,6 +510,7 @@ def run(**kwargs: object) -> int:seam_max=float(kwargs.get("seam_max") or SEAM_RATIO_MAX), name=str(kwargs.get("name") or "loop"), report_path=kwargs.get("report"), # type: ignore[arg-type]cycle_mode=str(kwargs.get("cycle") or "auto"), gif_fps=float(kwargs.get("gif_fps") or GIF_FPS_DEFAULT),start=kwargs.get("start"), length=kwargs.get("length"), strip_height=int(kwargs.get("strip_height") or STRIP_MAX_HEIGHT), # type: ignore[arg-type]+ body_height=kwargs.get("body_height"), # type: ignore[arg-type])summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio")}diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.pyindex 6cfcccc..47474c7 100644--- a/tests/video/test_video_pipeline.py+++ b/tests/video/test_video_pipeline.py@@ -336,6 +336,28 @@ def test_strip_height_caps_the_output_size(tmp_path: Path) -> None:assert Image.open(rep["gif"]["file"] if Path(rep["gif"]["file"]).is_absolute() else tmp_path / "h" / rep["gif"]["file"]).height <= 100+def test_body_h_is_the_standing_height_not_the_cycle_median() -> None:+ """A jump cycle: 10 standing frames (60 px tall), 20 crouched (40 px) and 30 airborne+ (60 px, lifted). The median height is not the standing height; body_h must be 60 and+ --body-height must scale the standing frames, not the median."""+ frames = []+ def body(top, height):+ im = Image.new("RGBA", (80, 120), (0, 0, 0, 0))+ for y in range(top, top + height):+ for x in range(30, 50):+ im.putpixel((x, y), (200, 60, 60, 255))+ return im+ frames += [body(60, 60) for _ in range(10)] # standing on the floor (bottom = 119)+ frames += [body(80, 40) for _ in range(20)] # crouched on the floor+ frames += [body(20, 60) for _ in range(30)] # airborne (bottom = 79)+ strip, meta = loop_mod.build_strip(frames, cycle_seconds=60 / 24)+ assert meta["body_h"] == 60+ strip2, meta2 = loop_mod.build_strip(frames, cycle_seconds=60 / 24, body_height=30)+ assert meta2["body_h"] == 30 and meta2["body_height_target"] == 30 and meta2["h"] == 54 # union crop 108 px (8 px top margin) → 0.5+ strip3, meta3 = loop_mod.build_strip(frames, cycle_seconds=60 / 24, body_height=30, max_height=40)+ assert meta3["h"] <= 40, "--strip-height stays the cap"++def test_drop_specks_erases_detached_slivers_only() -> None:im = Image.new("RGBA", (40, 40), (0, 0, 0, 0))for y in range(5, 35):