Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

feat: route terminal-pose states and accept end-frame canvases

Soohong Kim375e51663843
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 0dbcacb..9bb1b1f 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -39,6 +39,7 @@ from sprite_gen.video import align as align_mod
from sprite_gen.video import body_plan as body_mod
from sprite_gen.video.body_plan import Body
from sprite_gen.video import rife as rife_mod
+from sprite_gen.video import nonloop
START_GAP_SECONDS = 2.0
# Clip length the batch asks the video model for. 3 s holds two or more cycles of every
@@ -436,13 +437,17 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:
validate_facing(facing)
view = VIEW_TEXT.get(direction, f"seen from the {direction}").format(facing=facing)
turned = facing if direction in handed_mod.LATERAL_VIEWS else None
- if state in ACTION_TEXT_STATES:
+ if state in nonloop.STATES:
+ template = "2D game sprite animation. The character {motion} The character is {view}. " + nonloop.COMMON_TEXT
+ elif state in ACTION_TEXT_STATES:
template = ACTION_COMMON_TEXT
elif (state in PINNED_LOOP_STATES or (state in GAIT_STATES and direction in PINNED_GAIT_VIEWS)) if pinned is None else pinned:
template = PINNED_LOOP_TEXT
else:
template = COMMON_TEXT
stands_on = body_mod.text(body_plan)
+ if state in nonloop.STATES and body_plan:
+ stands_on = " ".join((b.figure + ": " if b.figure else "") + nonloop.ANATOMY_TEXT.get(b.plan, "") for b in body_plan).strip()
stands_on = f" {stands_on}" if stands_on else ""
if direction == "back" and state in GAIT_STATES and not body_mod.biped(body_plan):
stands_on += f" {BACK_GAIT_TEXT_ANY_BODY['scene' if body_mod.scene(body_plan) else 'one']}"
@@ -464,6 +469,7 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:
built_in = (VIEW_MOTION_TEXT[(state, direction)].format(facing=facing) if (state, direction) in VIEW_MOTION_TEXT
else IDLE_TEXT_ANY_BODY if state == "idle" and not body_mod.biped(body_plan)
else ATTACK_TEXT_ANY_BODY if state == "attack" and not body_mod.biped(body_plan)
+ else nonloop.MOTION_TEXT[state] if state in nonloop.STATES
else MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."))
text = template.format(motion=built_in + stands_on, view=view)
text = ((text.replace("The character", character, 1) if character else text)
@@ -655,7 +661,12 @@ def run_item(
still_provider: str | None = None,
handed: list[Handed] | None = None,
body_plan: list[Body] | None = None,
+ end_frame: Path | None = None,
) -> dict[str, Any]:
+ if end_frame is not None and state not in nonloop.STATES:
+ raise SystemExit("video-set: --end-frame requires a non-loop state")
+ if state in nonloop.STATES and (fit == "tight" or anchor != "none"):
+ raise SystemExit("video-set: non-loop states need --fit state and --anchor none to preserve the terminal pose")
if walk_start not in WALK_START_MODES:
raise SystemExit(f"video-set: --walk-start must be one of {', '.join(WALK_START_MODES)}")
if anchor == "motion-auto" and not loop_mod.profile_for(state).gait:
@@ -739,9 +750,14 @@ def run_item(
# would be a second retry loop on top of the first, each of its POSTs a request.
_staggered_start(gap)
pin = {"last_frame": canvas_png} if pins_last_frame(state, direction) else {}
+ if end_frame is not None:
+ with Image.open(end_frame) as final, Image.open(canvas_png) as initial:
+ if final.size != initial.size or canvas_mod.corner_key(final) != canvas_mod.corner_key(initial):
+ raise SystemExit("video-set: end frame must match the start canvas size and background key")
+ pin = {"last_frame": end_frame}
attempts = [video_runner(canvas_png, prompt, clip, clip_report, duration=duration, resolution=resolution,
log=item_dir / "clip.log", **pin)]
- result["clip"] = {"attempts": attempts, "duration": duration, "last_frame": pins_last_frame(state, direction)}
+ result["clip"] = {"attempts": attempts, "duration": duration, "last_frame": str(end_frame) if end_frame is not None else pins_last_frame(state, direction)}
if attempts[-1] != 0 or not clip.exists():
raise SystemExit(f"clip generation failed after {len(attempts)} attempt(s); see {item_dir / 'clip.log'}")
@@ -752,7 +768,7 @@ def run_item(
result["frames"] = {k: fr[k] for k in ("fps", "frames", "alpha_zero_pct_min", "alpha_zero_pct_max")}
result["frames"]["spill"] = fr.get("spill", {}).get("mode")
lp = loop_mod.run_loop(Path(fr["keyed_dir"]), item_dir / "loop", fps=float(fr["fps"]), state=state, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX, name=item, report_path=item_dir / "loop.report.json", anchor=anchor, body_height=body_height,
- cycle_mode="pinned" if state in PINNED_LOOP_STATES else "auto",
+ cycle_mode="once" if state in nonloop.STATES else "pinned" if state in PINNED_LOOP_STATES else "auto",
facing=facing if direction in handed_mod.LATERAL_VIEWS else "right")
result["loop"] = {"kind": lp["cycle"].get("kind", "periodic"), "cycle": lp["cycle"]["length"], "period": lp["cycle"]["period_global"], "cycle_ratio": round(lp["cycle"]["ratio"], 3), "seam_ratio": lp["resampled_seam_ratio"], "n_out": lp["n_out"], "drift_px": lp["strip"].get("drift_px", 0), "gif": lp["gif"]["file"], "webp": lp["webp"]["file"], "strip": lp["strip"]["path"]}
result["loop"]["review_recommended"] = lp["cycle"].get("review_recommended", False)
@@ -938,7 +954,7 @@ def write_table(results: list[dict[str, Any]], path: Path, *, both: bool = False
status += " (jump not repaired: no RIFE)"
# a cut whose steps are known is two of them; one the step screen suspects may be one
cycle = f"{lp['cycle']}" + (f" ({lp['steps']} steps)" if lp.get("steps") else " (one step?)" if lp.get("step_screen") else "")
- lines.append(f"| {_view_label(r, both)} | {r['state']} | {lp.get('kind', 'periodic')} | {cycle} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | {status} |")
+ lines.append(f"| {_view_label(r, both)} | {r['state']} | {lp.get('kind', 'periodic')} | {cycle} | {lp['period'] if lp['period'] is not None else '-'} | {format(lp['seam_ratio'], '.2f') if lp['seam_ratio'] is not None else '-'} | {lp['n_out']} | {status} |")
else:
lines.append(f"| {_view_label(r, both)} | {r['state']} | - | - | - | - | - | FAIL: {r.get('error', '')[:80]} |")
text = "\n".join(lines) + "\n"
@@ -976,6 +992,7 @@ def run_set(
handed: list[Handed] | None = None,
align_feet: dict[str, str] | None = None,
body_plan: list[Body] | None = None,
+ end_frames: dict[str, Path] | None = None,
) -> dict[str, Any]:
"""`bases` maps a view to its still; `facing` is right, left or `right,left` (`facings_of`), and a view filmed
both ways is keyed `view@right` and `view@left` (`resolve_bases`). `handed` (`handedness.parse`) puts each
@@ -1004,6 +1021,12 @@ def run_set(
raise SystemExit(f"video-set: base still for '{direction}' not found: {base}")
# (item, direction, state, facing, base); a set filmed both ways names a lateral item's facing
items = [(f"{d}-{f}-{s}" if both and f else f"{d}-{s}", d, s, f or facings[0], b) for d, f, b in views for s in states]
+ for item, path in (end_frames or {}).items():
+ selected = [state for name, _, state, _, _ in items if name == item]
+ if not selected or selected[0] not in nonloop.STATES or not path.is_file():
+ raise SystemExit(f"video-set: --end-frame {item} needs a non-loop item and an existing image")
+ if any(s in nonloop.STATES for s in states) and (fit == "tight" or anchor != "none"):
+ raise SystemExit("video-set: non-loop states need --fit state and --anchor none")
aligned_items = [i for i, _, s, _, _ in items if align_cycles == "auto" and loop_mod.profile_for(s).gait
and sum(1 for _, _, s2, _, _ in items if s2 == s) >= 2]
for item, foot in (align_feet or {}).items():
@@ -1027,7 +1050,7 @@ def run_set(
return prepare_side
with ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:
- futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan): i for i, d, s, f, b in items}
+ futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {})): i for i, d, s, f, b in items}
for fut in as_completed(futures):
r = fut.result()
results.append(r)
@@ -1069,12 +1092,23 @@ def _parse_bases(values: list[str]) -> dict[str, Path]:
return bases
+def _parse_end_frames(values: list[str]) -> dict[str, Path]:
+ result = {}
+ for value in values:
+ item, sep, path = value.partition("=")
+ if not sep or not item or not path or item in result:
+ raise SystemExit("video-set: --end-frame expects each ITEM=PATH once")
+ result[item] = Path(path).expanduser().resolve()
+ return result
+
+
def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--base", action="append", default=[], help="direction=still.png (repeatable: side=..., front=..., back=...); filmed facing right,left, a side or diagonal view takes one still per facing: side@right=..., side@left=...")
parser.add_argument("--facing", default="right", help="which way the side and diagonal views face, for both prompt and canvas: right (default), left, or right,left to film each of them both ways from a still drawn each way (no mirroring); ignored for front/back")
parser.add_argument("--facing-fix", choices=facing_mod.FIXES, default="none", help="side inputs: record only (none, default), or opt into mirror (refused with --handed)")
parser.add_argument("--handed", action="append", default=[], metavar="ITEM=SIDE [PART]", help="an asymmetric item on one of the character's own sides, e.g. 'the black smartwatch=left wrist' (repeatable): every clip prompt says where it is in its view and that it stays there")
parser.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help="what the character stands on: biped (default), quadruped or legless; a scene of several figures names each, e.g. 'the man=biped' 'the horse=quadruped' (repeatable): no prompt names a part the body lacks")
+ parser.add_argument("--end-frame", action="append", default=[], metavar="ITEM=PATH", help="non-loop item: terminal-pose canvas with the same size and key as the starting canvas (repeatable)")
parser.add_argument("--states", default="idle,walk,run,jump,attack", help="comma list of motion states")
parser.add_argument("--out-dir", required=True, type=Path, help="batch root; one folder per direction-state")
parser.add_argument("--character", help="short subject phrase used in the prompts (e.g. 'The armored knight')")
@@ -1102,6 +1136,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
def run(**kwargs: object) -> int:
payload = run_set(
+ end_frames=_parse_end_frames(list(kwargs.get("end_frame") or [])),
bases=_parse_bases(list(kwargs.get("base") or [])), # type: ignore[arg-type]
states=[s.strip() for s in str(kwargs.get("states") or "").split(",") if s.strip()],
root=Path(str(kwargs["out_dir"])), character=kwargs.get("character"), # type: ignore[arg-type]
diff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.py
index 8cddfc8..141ef9e 100644
--- a/sprite_gen/video/canvas.py
+++ b/sprite_gen/video/canvas.py
@@ -78,6 +78,12 @@ STATE_CANVAS: dict[str, CanvasProfile] = {
"cheer": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "arms raised and spread leave a 1:1 frame"),
"wave": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "a raised waving arm leaves a 1:1 frame"),
"celebrate": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "same envelope as cheer"),
+ "death": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the death terminal pose"),
+ "fall": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the fall terminal pose"),
+ "land": CanvasProfile(SHAPE_TALL, 3 / 4, 0.34, 0.0, 0.0, "room for the land terminal pose"),
+ "cast": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.25, 0.25, 0.25, "room for the cast terminal pose"),
+ "hurt_hold": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the hurt_hold terminal pose"),
+ "transform": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.25, 0.25, 0.25, "room for the transform terminal pose"),
"default": CanvasProfile(SHAPE_SQUARE, 1.0, 0.0, 0.0, 0.0, "in-place motion fits the still's own frame"),
}
# `--shape wide` is not the attack row. It is forced on a state whose own row is
diff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.py
index ecf1815..15b2724 100644
--- a/sprite_gen/video/clip_prompt.py
+++ b/sprite_gen/video/clip_prompt.py
@@ -19,6 +19,7 @@ from __future__ import annotations
import argparse
import json
import sys
+from pathlib import Path
from typing import Any
from sprite_gen.gen.facing import FACINGS
@@ -26,6 +27,7 @@ from sprite_gen.gen import handedness as handed_mod
from sprite_gen.gen.handedness import Handed
from sprite_gen.video import batch as batch_mod
from sprite_gen.video import body_plan as body_mod
+from sprite_gen.video import nonloop
from sprite_gen.video.body_plan import Body
DEFAULT_MODEL = "grok-imagine-video-1.5"
@@ -35,7 +37,7 @@ START_STILL_KEYS = ("green", "magenta")
def plan_prompt(*, direction: str, state: str, facing: str = "right", character: str | None = None,
motion: str | None = None, model: str = DEFAULT_MODEL, last_frame: bool = True,
unpinned: bool = False, duration: int | None = None, key: str = "green",
- handed: list[Handed] | None = None, body_plan: list[Body] | None = None) -> dict[str, Any]:
+ handed: list[Handed] | None = None, body_plan: list[Body] | None = None, end_frame: Path | None = None) -> dict[str, Any]:
"""The prompt `video-set` would send for (direction, state), and how its clip is to be cut. `handed`
(`handedness.parse`) adds where each asymmetric item is in this view, as `video-set --handed` does;
`body_plan` (`body_plan.parse_all`) what the subject stands on, as `video-set --body-plan` does."""
@@ -45,6 +47,11 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:
raise SystemExit(f"video-prompt: --key must be one of {', '.join(START_STILL_KEYS)}, got {key!r}")
if unpinned and last_frame:
raise SystemExit("video-prompt: --unpinned goes with --no-last-frame (a source that can pin the end frame films it pinned)")
+ if end_frame is not None:
+ if state not in nonloop.STATES:
+ raise SystemExit("video-prompt: --end-frame requires a non-loop state")
+ if not last_frame:
+ raise SystemExit("video-prompt: this source cannot pin an end frame")
wants_pin = batch_mod.pins_last_frame(state, direction)
warnings: list[str] = []
pinned: bool | None = None
@@ -63,13 +70,13 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:
prompt = parts.text
# the caller's own words (--character, --motion) against the engine's: a conflict is a warning
warnings += [note["text"] for note in parts.notes if note["kind"] == "conflict"]
- cycle = "pinned" if pins and state in batch_mod.PINNED_LOOP_STATES else "auto"
+ cycle = "once" if state in nonloop.STATES else "pinned" if pins and state in batch_mod.PINNED_LOOP_STATES else "auto"
# as video-set places and cuts: a side or diagonal view takes the facing, front and back face right
canvas_facing = loop_facing = facing if direction in handed_mod.LATERAL_VIEWS else "right"
mid_step = batch_mod.starts_mid_step(state, direction, body_plan)
still = "<dir>/walk-start.png" if mid_step else "<still.png>"
duration = batch_mod.duration_for(state, duration)
- end = ", end frame <dir>/canvas.png" if pins else ""
+ end = f", end frame {end_frame}" if end_frame is not None else ", end frame <dir>/canvas.png" if pins else ""
record: dict[str, Any] = {
"kind": "sprite-gen-video-prompt",
"direction": direction,
@@ -80,7 +87,7 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:
"model": model,
"prompt": prompt,
"duration": duration,
- "last_frame": "canvas" if pins else None,
+ "last_frame": str(end_frame) if end_frame is not None else "canvas" if pins else None,
"cycle": cycle,
"commands": {
"canvas": f"sprite-gen video-canvas --still {still} --state {state} --facing {canvas_facing} --out <dir>/canvas.png --report <dir>/canvas.report.json",
@@ -114,6 +121,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--motion", help="the caller's own motion paragraph in place of the state's sentence (build_prompt(motion=...))")
parser.add_argument("--model", default=DEFAULT_MODEL, help=f"clip model the prompt is for (default {DEFAULT_MODEL}); a Lite model calms a walk")
parser.add_argument("--duration", type=int, help="seconds to ask for (default: the state's own, as video-set)")
+ parser.add_argument("--end-frame", type=Path, help="non-loop terminal-pose canvas to pin instead of returning to the starting image")
parser.add_argument("--no-last-frame", action="store_true", help="the clip source cannot pin an end frame (ZCRE's grok-imagine-video-1.5): states filmed pinned are refused")
parser.add_argument("--unpinned", action="store_true", help="with --no-last-frame: film a pinned state without the pin, with a warning, instead of refusing it")
parser.add_argument("--key", choices=START_STILL_KEYS, default="green", help="the still's chroma key, for a front or back walk's mid-step redraw sentence (default green)")
@@ -122,6 +130,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
def run(**kwargs: object) -> int:
record = plan_prompt(
+ end_frame=kwargs.get("end_frame"),
direction=str(kwargs["direction"]), state=str(kwargs["state"]), facing=str(kwargs.get("facing") or "right"),
character=kwargs.get("character"), motion=kwargs.get("motion"), # type: ignore[arg-type]
model=str(kwargs.get("model") or DEFAULT_MODEL), last_frame=not kwargs.get("no_last_frame"),