Skip to content

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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 7f7ef5a..162fe1e 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: sprite-gen
-version: 2.0.2
+version: 2.0.3
description: "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.0
depends_on:
diff --git a/docs/assets/hero-paladin-jump.gif b/docs/assets/hero-paladin-jump.gif
index e91ae3a..0ecba49 100644
Binary files a/docs/assets/hero-paladin-jump.gif and b/docs/assets/hero-paladin-jump.gif differ
diff --git a/docs/assets/hero-paladin-run.gif b/docs/assets/hero-paladin-run.gif
index b926270..6d56618 100644
Binary files a/docs/assets/hero-paladin-run.gif and b/docs/assets/hero-paladin-run.gif differ
diff --git a/docs/assets/hero-paladin-walk.gif b/docs/assets/hero-paladin-walk.gif
index 964c829..6a210fc 100644
Binary files a/docs/assets/hero-paladin-walk.gif and b/docs/assets/hero-paladin-walk.gif differ
diff --git a/docs/assets/hero-slime-walk.gif b/docs/assets/hero-slime-walk.gif
index 1fa614d..2e3df59 100644
Binary files a/docs/assets/hero-slime-walk.gif and b/docs/assets/hero-slime-walk.gif differ
diff --git a/docs/assets/hero-wolf-walk.gif b/docs/assets/hero-wolf-walk.gif
index e518bd6..165d579 100644
Binary files a/docs/assets/hero-wolf-walk.gif and b/docs/assets/hero-wolf-walk.gif differ
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 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** because
Chrome refuses images near 32 767 px — the cap is on pixels, so a 650 px cell allows 49
cells 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 a
24 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.toml
index 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.py
index 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 bound
w = 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.py
index 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):