Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
video-loop: GIF/WebP frame count follows the cycle at a fixed playback rate
Soohong Kim9d14ef9324d6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d852ae9..13be34e 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.1.0)++- `video-loop` GIF/WebP frame count follows the cycle length at a fixed playback rate (`--gif-fps`, default 12) instead of a per-state fixed count: a 2.5 s jump now gets ~30 frames at ~84 ms instead of 12 frames at 210 ms, so every state plays at the same density. `--n-out` still overrides; the report records `gif_fps`.+## v2.0.0 - Four pipelines, one taxonomy### Highlightsdiff --git a/SKILL.md b/SKILL.mdindex 322c9cf..1a78b80 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 2.0.0+version: 2.1.0description: "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 c4737f6..0b7fd2b 100644Binary files a/docs/assets/hero-paladin-jump.gif and b/docs/assets/hero-paladin-jump.gif differdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex b071c9f..27899c4 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -120,6 +120,10 @@ Outputs: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`.+ `n_out` is a **playback density, not a fixed count**: `round(cycle_seconds × --gif-fps)`+ (default 12 fps, floor 4, never more than the cycle holds), so a 2.5 s jump gets ~30 frames+ and a 1.1 s walk ~13 and both play at the same rate. A fixed 12 made the jump hold each+ frame 210 ms while the walk held 90 ms (2026-09-09). `--n-out` still overrides.- `<name>.webp` — same frames, lossless, `img2webp -exact` (Pillow's animated WebP writerdoes not pass `exact` and rewrites RGB under transparent pixels).diff --git a/pyproject.toml b/pyproject.tomlindex 4a6d5ba..5338c9c 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.0"+version = "2.1.0"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 5c52b80..ba1ed43 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -45,6 +45,8 @@ STRIP_MAX_HEIGHT = 520SEAM_RATIO_MAX = 2.0 # loop seam / mean adjacent distance inside the cycleSPECK_MIN_FRACTION = 0.01 # detached components smaller than this fraction of the body are keying specksPERIODICITY_MIN = 0.15 # the period must dip at least 15% below the profile mean (flat profile = no repeat)+GIF_FPS_DEFAULT = 12.0 # GIF/WebP playback density: n_out = cycle_seconds x this, so a 2.5 s jump and a 1.1 s walk play at the same rate+GIF_FRAMES_MIN = 4ONE_SHOT_MIN_CONTRAST = 3.0 # one-shot: the excursion peak must stand this far above the rest-pose noise (in MADs)ONE_SHOT_PAD = 2 # one-shot: rest frames kept on each side of the excursion so the seam is rest -> restCYCLE_MODES = ("auto", "periodic", "one-shot")@@ -54,7 +56,6 @@ CYCLE_MODES = ("auto", "periodic", "one-shot")class LoopProfile:min_frac: float # window as a fraction of the clip's frame countmax_frac: float- n_out: int # frames in the resampled GIF/WebPwhy: strperiodic: bool = True # gate: the profile must show a real period (idle is exempt)one_shot_ok: bool = False # the state is an action that may legitimately happen once (jump, attack) -> one-shot detector may take over@@ -62,12 +63,12 @@ class LoopProfile:# State -> detection window. Fractions of the clip length so 6 s and 10 s clips both work.STATE_PROFILES: dict[str, LoopProfile] = {- "idle": LoopProfile(0.60, 0.95, 16, "breathing is slow and not strictly periodic; the lowest seam is a long window", periodic=False),- "walk": LoopProfile(0.06, 0.31, 12, "full gait = two steps; the floor admits a legless body's fast bounce (~13 frames at 24 fps) — the 15% depth rule, not the window, rejects the one-step half period"),- "run": LoopProfile(0.07, 0.23, 10, "faster gait"),- "jump": LoopProfile(0.11, 0.45, 12, "crouch-spring-land-return", one_shot_ok=True),- "attack": LoopProfile(0.11, 0.45, 12, "swing and return to ready", one_shot_ok=True),- "default": LoopProfile(0.10, 0.45, 12, "generic in-place action", one_shot_ok=True),+ "idle": LoopProfile(0.60, 0.95, "breathing is slow and not strictly periodic; the lowest seam is a long window", periodic=False),+ "walk": LoopProfile(0.06, 0.31, "full gait = two steps; the floor admits a legless body's fast bounce (~13 frames at 24 fps) — the 15% depth rule, not the window, rejects the one-step half period"),+ "run": LoopProfile(0.07, 0.23, "faster gait"),+ "jump": LoopProfile(0.11, 0.45, "crouch-spring-land-return", one_shot_ok=True),+ "attack": LoopProfile(0.11, 0.45, "swing and return to ready", one_shot_ok=True),+ "default": LoopProfile(0.10, 0.45, "generic in-place action", one_shot_ok=True),}@@ -339,6 +340,7 @@ def run_loop(name: str,report_path: Path | None,cycle_mode: str = "auto",+ gif_fps: float = GIF_FPS_DEFAULT,) -> 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)}")@@ -350,7 +352,6 @@ def run_loop(n = len(files)lo = min_len if min_len is not None else max(4, round(n * prof.min_frac))hi = max_len if max_len is not None else max(lo + 2, round(n * prof.max_frac))- n_out = n_out or prof.n_outD = distance_matrix(files)periodic_attempt: dict[str, Any] | None = Noneif cycle_mode == "one-shot":@@ -373,6 +374,10 @@ def run_loop("regenerate the clip, or pass --cycle one-shot for a single performed action")i, L = cycle["start"], cycle["length"]+ # playback density, not a fixed count: a long cycle gets more frames so every state plays at+ # ~gif_fps (a fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk held 90 ms)+ if n_out is None:+ n_out = max(GIF_FRAMES_MIN, round(L / fps * gif_fps))n_out = min(n_out, L) # never ask for more distinct frames than the cycle holdsout_dir = out_dir.expanduser().resolve()@@ -432,6 +437,7 @@ def run_loop("periodic_attempt": periodic_attempt,"cycle_seconds": round(cycle_seconds, 4),"n_out": n_out,+ "gif_fps": gif_fps,"delay_ms": delay_ms,"resampled_seam_ratio": round(seam_ratio, 4),"seam_max": seam_max,@@ -454,7 +460,8 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--state", help="motion state (idle/walk/run/jump/attack) — selects the detection window")parser.add_argument("--min-len", type=int, help="override: minimum cycle length in frames")parser.add_argument("--max-len", type=int, help="override: maximum cycle length in frames")- parser.add_argument("--n-out", type=int, help="frames in the GIF/WebP (default from the state profile)")+ parser.add_argument("--n-out", type=int, help="frames in the GIF/WebP (default: cycle seconds x --gif-fps)")+ parser.add_argument("--gif-fps", type=float, default=GIF_FPS_DEFAULT, help=f"GIF/WebP playback density (default {GIF_FPS_DEFAULT:g}); every state plays at this rate regardless of cycle length")parser.add_argument("--seam-max", type=float, default=SEAM_RATIO_MAX, help=f"loop seam gate (default {SEAM_RATIO_MAX})")parser.add_argument("--cycle", choices=CYCLE_MODES, default="auto", help="auto: periodic first, one-shot failover for action states (recorded in the report); periodic / one-shot force one detector")parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")@@ -467,7 +474,7 @@ def run(**kwargs: object) -> int:fps=float(kwargs.get("fps") or 24.0), state=kwargs.get("state"), # type: ignore[arg-type]min_len=kwargs.get("min_len"), max_len=kwargs.get("max_len"), n_out=kwargs.get("n_out"), # type: ignore[arg-type]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"),+ cycle_mode=str(kwargs.get("cycle") or "auto"), gif_fps=float(kwargs.get("gif_fps") or GIF_FPS_DEFAULT),)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 cce91dc..17a0bbc 100644--- a/tests/video/test_video_pipeline.py+++ b/tests/video/test_video_pipeline.py@@ -134,7 +134,7 @@ def test_run_frames_extracts_a_real_clip(tmp_path: Path) -> None:# --- loop -----------------------------------------------------------------------------def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64)) -> list[Path]:+def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64), stamp: bool = False) -> list[Path]:"""A 'walker': a body block plus one leg that swings with `period`; the swing ismirror-symmetric every half period (the classic 1.5-cycle trap) but a side markerbreaks the symmetry slightly, exactly like a near/far leg in a side view."""@@ -155,6 +155,9 @@ def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64)) -> list[# near-leg marker only on the first half of the periodif math.sin(phase) >= 0:im.putpixel((leg_x, 50), (255, 255, 0, 255))+ if stamp: # recolour one BODY pixel per frame so no two frames are identical (a detached+ # marker would be erased as a speck; GIF writers merge byte-identical frames)+ im.putpixel((26 + t % 12, 10 + (t // 12) % 30), (90, 200, 90, 255))p = d / f"frame-{t:04d}.png"im.save(p)files.append(p)@@ -289,6 +292,22 @@ def test_strip_cap_is_on_pixels_not_cells() -> None:assert strip.width == meta["w"] * meta["frames"]+def test_gif_frame_count_follows_cycle_length_at_a_fixed_playback_rate(tmp_path: Path) -> None:+ """A 2.5 s jump used to get the same 12 frames as a 1.1 s walk and play at ~5 fps+ (2026-09-09, lead: '점프만 혼자 왜 프레임이 느리냐')."""+ (tmp_path / "long").mkdir()+ _gait_frames(tmp_path / "long", period=60, n=150, stamp=True) # 60 frames @ 24 fps = 2.5 s+ rep = loop_mod.run_loop(tmp_path / "long" / "keyed", tmp_path / "long-out", fps=24.0, state="jump", min_len=None, max_len=None, n_out=None, seam_max=2.0, name="j", report_path=None)+ assert rep["n_out"] == 30 and 80 <= rep["delay_ms"] <= 90+ (tmp_path / "short").mkdir()+ _gait_frames(tmp_path / "short", period=26, n=100, stamp=True) # 1.08 s+ rep2 = loop_mod.run_loop(tmp_path / "short" / "keyed", tmp_path / "short-out", fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=2.0, name="w", report_path=None)+ assert 12 <= rep2["n_out"] <= 14 and abs(rep2["delay_ms"] - rep["delay_ms"]) <= 15 # ~1.1 s at 12 fps; the period may resolve to 24-26+ explicit = loop_mod.run_loop(tmp_path / "short" / "keyed", tmp_path / "short-out2", fps=24.0, state="walk", min_len=None, max_len=None, n_out=8, seam_max=2.0, name="w8", report_path=None)+ assert explicit["n_out"] == 8+ assert rep["n_out"] <= rep["cycle"]["length"] and rep2["n_out"] <= rep2["cycle"]["length"]++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):