Skip to content

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

fix(video): say what an attack keeps still once, after a caller's motion too

Soohong Kim7a5614520474
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index f77dca8..3cb2dca 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -84,10 +84,15 @@ quadruped and a legless blob into a contradiction (2026-09-09).
An attack is a timed strike, not a repeat. `MOTION_TEXT["attack"]` asks for the same attack
twice, each a windup (about 0.5 s), one strike in front (about 0.25 s), a held impact pose
-(about 0.3 s) and a recovery to the exact starting stance (about 0.5 s), with what the subject
-holds kept in the grip the image shows — one hand stays one hand, both hands stay both hands,
-never let go, switched or taken in an extra hand — and the body never turning. Naming one hand
-for a weapon the still draws in both hands made the clip let go and grab again mid-attack. Its template
+(about 0.3 s) and a recovery to the exact starting stance (about 0.5 s), then `HOLD_TEXT["attack"]`:
+every grip stays the one the image shows — one hand stays one hand, both hands stay both hands,
+nothing let go or switched to the other hand — a hand the strike does not use stays where it is
+drawn with whatever it holds (a shield, a lantern), and the body never turns. Naming one hand
+for a weapon the still draws in both hands made the clip let go and grab again mid-attack.
+A caller's own motion paragraph (`build_prompt(motion=...)`) gets the same `HOLD_TEXT` sentence
+after it, once, then `REPEAT_TEXT`: a request interpreter writes its motion before the still
+exists and cannot know where the other hand's item is drawn, so it writes the choreography and
+the engine says what stays put. Its template
(`ACTION_COMMON_TEXT`) drops the "evenly paced" line, keeps what the subject holds inside the
frame, and asks for crisp frames without motion blur. `video-set` asks attack clips for 4 s
(`STATE_DURATION_SECONDS`; every other state keeps 3 s, and `--duration` overrides every state)
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 6ed570e..e848e49 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -58,6 +58,16 @@ VIEW_TEXT = {
"front": "seen from the front, facing the viewer directly",
"back": "seen from directly behind, facing away from the viewer",
}
+# What stays put while an attack moves, said once: after the built-in attack sentence and after a
+# caller's own motion paragraph alike. A request interpreter writes its motion before the still
+# exists, so it cannot know where the other hand's shield or lantern is drawn; the engine holds it.
+HOLD_TEXT = {
+ "attack": (
+ "Every grip stays exactly as shown in the image: one hand stays one hand, both hands stay both hands, "
+ "and nothing is let go or switched to the other hand. A hand the motion does not use stays where it is "
+ "drawn, with anything it holds, and the body keeps facing the same direction without turning."
+ ),
+}
MOTION_TEXT = {
# A side-view full body asked for "a subtle weight sway" and an evenly paced loop steps in place
# more often than not, so the feet are held and walking is named as what not to do.
@@ -71,12 +81,10 @@ MOTION_TEXT = {
"run": "moves in place on a treadmill: a fast locomotion cycle for this body type with a bounding rhythm and clear repeating ground contacts.",
"jump": "performs a modest vertical hop in place over and over: compress, spring up about half the body height, land softly, return to the exact starting stance, repeat at an even rhythm. Same height every time.",
"attack": (
- "performs the same melee attack twice in a row with what it is already holding, gripped exactly as in the image "
- "— one hand stays one hand, both hands stay both hands — (bare hands only if it holds nothing), keeping every "
- "piece of its gear and outfit exactly as drawn. Each attack is a windup (about 0.5 s), one clean strike in front "
- "(about 0.25 s), a held impact pose (about 0.3 s), then a recovery to the exact starting stance (about 0.5 s). "
- "What it holds is never let go, switched to the other hand or taken in an extra hand, and the body keeps facing "
- "the same direction without turning."
+ "performs the same melee attack twice in a row with what it is already holding (bare hands only if it holds "
+ "nothing), keeping every piece of its gear and outfit exactly as drawn. Each attack is a windup (about 0.5 s), "
+ "one clean strike in front (about 0.25 s), a held impact pose (about 0.3 s), then a recovery to the exact "
+ "starting stance (about 0.5 s). " + HOLD_TEXT["attack"]
),
"cheer": "celebrates in place: rises into a raised, spread-out cheer pose, holds it for a beat, then settles back to the exact starting stance, repeating at an even rhythm.",
"wave": "waves in place: lifts one side into a friendly wave, sways it a few times, then settles back to the exact starting stance, repeating at an even rhythm.",
@@ -127,7 +135,8 @@ def build_prompt(direction: str, state: str, character: str | None, facing: str
`motion` replaces the built-in state sentence with the caller's own description of the
motion, written as whole sentences about the subject (a request interpreter's output, for
- instance). The frame, camera, background and design rules stay the engine's.
+ instance). What stays put (`HOLD_TEXT`), the repeat count (`REPEAT_TEXT`) and the frame,
+ camera, background and design rules stay the engine's.
"""
validate_facing(facing)
view = VIEW_TEXT.get(direction, f"seen from the {direction}").format(facing=facing)
@@ -142,9 +151,10 @@ def build_prompt(direction: str, state: str, character: str | None, facing: str
if not motion:
raise SystemExit("video: motion description is empty")
head = "2D game sprite animation. The character {motion} The character is {view}."
+ hold = f" {HOLD_TEXT[state]}" if state in HOLD_TEXT else ""
repeat = f" {REPEAT_TEXT[state]}" if state in REPEAT_TEXT else ""
subject = character.strip().rstrip(".") if character else "The character"
- return f"2D game sprite animation. {motion}{repeat} {subject} is {view}." + template[len(head):]
+ return f"2D game sprite animation. {motion}{hold}{repeat} {subject} is {view}." + template[len(head):]
text = template.format(motion=MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."), view=view)
return text.replace("The character", character, 1) if character else text
diff --git a/tests/video/test_attack_motion.py b/tests/video/test_attack_motion.py
index 3011176..267f7c0 100644
--- a/tests/video/test_attack_motion.py
+++ b/tests/video/test_attack_motion.py
@@ -1,4 +1,4 @@
-"""Attack clips: a timed strike twice, one hand, no turning, pinned to end where they start.
+"""Attack clips: a timed strike twice, the drawn grip, no turning, pinned to end where they start.
A 4 s clip, the frame, camera and background rules without the "evenly paced" line, and a
caller's own motion paragraph (`build_prompt(motion=...)`) in place of the built-in one.
@@ -18,11 +18,15 @@ FIXTURE = Path(__file__).parents[1] / "fixtures" / "facing" / "left.png"
def test_attack_text_is_timed_keeps_the_drawn_grip_and_is_twice() -> None:
text = batch_mod.build_prompt("side", "attack", None)
- for phrase in ("twice in a row", "gripped exactly as in the image", "one hand stays one hand, both hands stay both hands",
+ for phrase in ("twice in a row", "Every grip stays exactly as shown in the image", "one hand stays one hand, both hands stay both hands",
"windup (about 0.5 s)", "strike in front (about 0.25 s)", "held impact pose (about 0.3 s)",
- "exact starting stance", "never let go, switched to the other hand or taken in an extra hand",
+ "exact starting stance", "nothing is let go or switched to the other hand",
+ "A hand the motion does not use stays where it is drawn, with anything it holds",
"without turning", "anything it holds always stay fully inside the frame", "no motion blur"):
assert phrase in text, phrase
+ # what stays put is said once, in the same words a caller's own motion gets
+ assert text.count(batch_mod.HOLD_TEXT["attack"]) == 1
+ assert text.count("stays exactly as shown") == 1 and text.count("without turning") == 1
# the grip is the image's: a heavy weapon drawn in both hands is not asked into one
assert "hand nearest the viewer" not in text
assert "evenly paced" not in text
@@ -34,7 +38,8 @@ def test_attack_text_is_timed_keeps_the_drawn_grip_and_is_twice() -> None:
def test_a_callers_motion_replaces_the_built_in_sentence() -> None:
motion = "The knight draws the sword back, then strikes forward and holds the impact pose. It never turns."
text = batch_mod.build_prompt("side", "attack", "A small knight.", facing="right", motion=motion)
- assert text.startswith(f"2D game sprite animation. {motion} Perform this attack twice in a row with the same timing each time. "
+ hold = batch_mod.HOLD_TEXT["attack"]
+ assert text.startswith(f"2D game sprite animation. {motion} {hold} Perform this attack twice in a row with the same timing each time. "
"A small knight is seen from the exact side, facing right. Stays centered")
assert text.endswith("no motion blur, no smears and no afterimages.")
assert "melee attack" not in text # the built-in attack sentence is not added on top
@@ -42,7 +47,7 @@ def test_a_callers_motion_replaces_the_built_in_sentence() -> None:
assert "The character is seen from the front" in batch_mod.build_prompt("front", "attack", None, motion=" Strikes.\n Holds. ")
# a state with no repeat sentence and its own template
walk = batch_mod.build_prompt("side", "walk", None, motion="The fox trots in place.")
- assert "Perform this attack" not in walk and walk.endswith("so the animation loops.")
+ assert "Perform this attack" not in walk and hold not in walk and walk.endswith("so the animation loops.")
with pytest.raises(SystemExit):
batch_mod.build_prompt("side", "attack", None, motion=" \n ")