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(gen,video): a horse's sheet does not swing its arms, nor strike with its hands — prepare --body-plan

Soohong Kimf87ac500cba9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3f23ebd..8290f02 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v2.33.0) - A horse's sheet does not swing its arms, and it does not strike with its hands
+
+- **Fix: the sheet rows `prepare` writes gave every body a person's arms, shoulders and hands.** 2.32.0's body plan reached the clip's walk, idle and still but not the rows an image model draws a sheet from: the walk and run rows moved "body, arm, leg, hair, and prop", the front and three-quarter-front walks "alternating leg, arm, shoulder", the diagonal runs traded "foot-contact phases" of "the left and right legs", the wave was "arm pose only: arm down, arm raised, hand tilted" (default action "friendly hand wave gesture"), every row's anchor lock spent its motion on "arm counter-swing" and turned "the body, feet, shoulders", and a diagonal row read its facing by "shoulder overlap, hand/foot placement". A horse's walk sheet came with arms.
+- **Fix: an animal's attack was made with its hands.** The clip's attack (`MOTION_TEXT["attack"]`) struck "with what it is already holding (bare hands only if it holds nothing)", and its hold (`HOLD_TEXT["attack"]`, after a caller's `--motion` too) said "one hand stays one hand, both hands stay both hands … A hand the motion does not use stays where it is drawn", whatever the body.
+- **New `prepare --body-plan`** (the same `biped` / `quadruped` / `legless` / `"<figure>=<plan>"` as `video-set`; repeatable; over the request's `body_plan`): any body but one biped gets rows without the parts it lacks (`STATE_REQUIREMENTS_ANY_BODY`, `ANCHOR_LOCK_ANY_BODY`, the diagonal facing line; the wave lifts one side as the clip's wave does, and its default action is `DEFAULT_ACTIONS_ANY_BODY["wave"]` where the request names none) and every row ends its state requirements with what it stands on (`body_plan.text`). `sprite-request.json` records `body_plan` (absent without one) and a run prepared again from it keeps it. **`video-set` / `video-prompt --body-plan`** now also give the attack `ATTACK_TEXT_ANY_BODY` ("with what it is already holding, or with its own body if it holds nothing") and `HOLD_TEXT_ANY_BODY` (anything it holds stays held the same way; no hand counted); which part strikes is left to the caller's `--motion`. No body plan, or one biped, keeps every clip prompt byte for byte (2.22.0's) and every sheet row byte for byte (2.32.0's, new `tests/fixtures/prepare-rows-v2.32.0.json.gz` drawn by `tests/gen/prepare_freeze_table.py`). The new sentences are not yet measured on an image or clip model. [docs/video-pipeline.md](docs/video-pipeline.md#the-sheet-rows--prepare---body-plan).
+- **`tests/gen/test_body_plan_sheets.py`** draws every sheet row (each state with a sentence of its own, the default states, a state with none, with and without a base image, a direction-contract run) and every clip prompt of every state (built-in and `--motion`, every view and model, `video-prompt`) for a quadruped, a body without legs and a man leading a horse, and finds no arm, hand, fist, wrist, shoulder, chest, hip, knee, shoe, heel, toe or counted foot in any (no leg or foot at all for a body without legs, apart from the sentence saying it has none); against 2.32.0 it fails on the attack's hands and on `prepare`, which took no body plan.
+
## v2.32.0 - A horse is not told a person's walk
- **Fix: an animal's walk and idle named a person's arms and feet.** The walk and run sentences have named no limb since 2.0.0 ("`video-set` motion templates no longer assume a biped"), but four sentences added later were measured on people and said to every body: the Lite walk calm ("a gentle arm swing close to the body", 2.18.0), the Lite back-diagonal head hold ("only the legs, arms and the ends of the hair move", 2.18.0), the idle ("both feet planted flat", chest, shoulders and arms, 2.9.0) and the front or back walk's mid-step redraw ("one foot … directly under its own hip … the arms swing", 2.18.0). Said of a horse, they walk it on a person's legs or stand it up on two. Not a regression of the 2.0.0 fix: these paths came after it.
diff --git a/SKILL.md b/SKILL.md
index bebf7c3..25e793c 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -75,7 +75,7 @@ it never changes the requested direction. Image correction requires explicit opt
| `video --direction` | `side`, `front`, `back`, `front_diagonal`, `back_diagonal`; unset by default | `side` opts into facing inspection and a matching prompt requirement; the others skip it. The two diagonals are three-quarter views turned right (`VIEW_TEXT`); a walk or run in one is filmed pinned (`pins_last_frame`). |
| `video --facing`, `video-set --facing` | `right` (default), `left`; `video-set` also `right,left` | Required side direction. `right,left` films every side and diagonal view both ways, each from its own still (`--base side@left=…`); none is mirrored. |
| `gen --direction`, `--handed`; `video-prompt` / `video-set --handed` | a view; `"<item>=<left\|right> [part]"` | An item on one of the character's own sides: the still and clip prompts say where it is in each view, and mirroring is refused. |
-| `video-prompt` / `video-set` / `gen --direction --body-plan` | `biped` (default), `quadruped`, `legless`; or `"<figure>=<plan>"` per figure of a scene | What the subject stands on: no clip, redraw or still view prompt names a part it lacks (a horse is not walked on a person's legs or stood up), and a scene says it per figure. |
+| `video-prompt` / `video-set` / `gen --direction` / `prepare --body-plan` | `biped` (default), `quadruped`, `legless`; or `"<figure>=<plan>"` per figure of a scene | What the subject stands on: no clip, attack, redraw, still view or sheet row prompt names a part it lacks (a horse is not walked on a person's legs, stood up, given arms in a walk sheet or told to strike with its hands), and a scene says it per figure. |
| `video --facing-fix`, `video-set --facing-fix` | `none` (default), `mirror` | Record the observation; opt into mirroring an observed opposite in a copy. Batch side inspection is enabled by default. |
Direction is requested through the generation and motion prompts, which cannot guarantee model compliance.
diff --git a/docs/gen.md b/docs/gen.md
index 12af456..864459e 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -393,6 +393,11 @@ recorded per row.
One row by hand is the same call `gen-set` makes: `--provider codex` (or `grok`) with
`prompts/<state>.txt`, writing `raw/<state>.png`.
+The row prompts are `prepare`'s, and were measured on people: a walk row moves "body, arm, leg", a
+front walk "alternating leg, arm, shoulder", a wave "arm pose only". For a body that is not one biped,
+`prepare --body-plan quadruped` (or `legless`, or `"<figure>=<plan>"` per figure) writes every row
+without a part the body lacks and says what it stands on
+([sheet rows](video-pipeline.md#the-sheet-rows--prepare---body-plan)).
The row prompts still carry the request chroma key on the background and frame
extraction removes it downstream — rows are generated **without** `--transparent`, so
the native strategy does not apply to them yet (moving rows to native alpha is a
diff --git a/docs/prompt-assembly.md b/docs/prompt-assembly.md
index 167f1d1..e77d8cb 100644
--- a/docs/prompt-assembly.md
+++ b/docs/prompt-assembly.md
@@ -55,10 +55,12 @@ the head, a tail, the body, a leg, a shoulder — gets only where it is, and no
**A body that is not a person** (`--body-plan`, `video/body_plan.py`): with no body plan, or one
biped, nothing changes. A quadruped, a body without legs or a scene of several figures has the idle,
-the Lite walk sentences, the mid-step redraw and the still's view sentence (`gen --direction
---body-plan`) said without the parts it lacks, and what it stands on said after the motion paragraph
-or at the end of the view sentence
-([body plan](video-pipeline.md#a-body-that-is-not-a-person----body-plan)).
+the attack and its hold (`HOLD_TEXT`, after a caller's `--motion` too), the Lite walk sentences, the
+mid-step redraw and the still's view sentence (`gen --direction --body-plan`) said without the parts it
+lacks, and what it stands on said after the motion paragraph or at the end of the view sentence
+([body plan](video-pipeline.md#a-body-that-is-not-a-person----body-plan)). The sheet rows `prepare
+--body-plan` writes take the same plan
+([sheet rows](video-pipeline.md#the-sheet-rows--prepare---body-plan)).
**A front or back walk's start still** (`batch.walk_start_prompt`): the mid-step redraw sentence,
the key background line, then the still's handed sentences.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index fc1b32d..b7ad6e3 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -264,7 +264,8 @@ hips and the toes or heels of both feet at the viewer, or the backs of the shoes
stand it up on two. The walk and run sentences themselves name no limb (since 2.0.0's "`video-set`
motion templates no longer assume a biped"); these came later and were said to every body.
-`video-set --body-plan`, `video-prompt --body-plan`, `gen --direction --body-plan` and
+`video-set --body-plan`, `video-prompt --body-plan`, `gen --direction --body-plan`, `prepare
+--body-plan` and
`build_prompt(body_plan=...)`, `walk_start_prompt(body_plan=...)`, `still_view_text(body_plan=...)`,
`gen.still_prompt(body_plan=...)` name what the subject stands on (`sprite_gen/video/body_plan.py`):
`biped` (the default), `quadruped` or `legless` for the character, or one `<figure>=<plan>` per figure
@@ -275,17 +276,44 @@ biped, keeps every prompt byte for byte. Any other body gets:
|---|---|
| after the motion sentence (or the caller's `--motion`) | what it stands on (`body_plan.text`): "It stays on all four legs, as in the image, and never rises onto its hind legs." / "It has no legs, as in the image, and never grows legs or feet." / "Each figure keeps the body it has in the image: the man on two legs; the horse on all four legs, never rising onto its hind legs." |
| idle | `IDLE_TEXT_ANY_BODY`: the same stillness, standing or resting as in the image, no feet counted, no chest, shoulders or arms |
+| attack | `ATTACK_TEXT_ANY_BODY`: the same timed strike "with what it is already holding, or with its own body if it holds nothing", then `HOLD_TEXT_ANY_BODY["attack"]`: anything it holds stays held the same way, a part the strike does not use stays where it is drawn, no hand counted. Which part strikes (a bite, a head-butt, a forefoot) is not guessed: a caller who knows says it with `--motion`, which gets `HOLD_TEXT_ANY_BODY` after it |
| Lite walk calm | `LITE_WALK_TEXT_LEGGED` (no arm swing; never trotting or galloping) or, with a figure without legs, `LITE_WALK_TEXT_LEGLESS` (no steps or feet) |
| Lite back-diagonal head hold | `LITE_HEAD_TEXT_ANY_BODY`: what moves is what it moves on and its loose ends (a tail, a mane, hair) |
| the still's view sentence (`still_view_text`, `gen --direction`) | `STILL_VIEW_TEXT_ANY_BODY` for the front, back and diagonal views (where the body and head point; no feet, chest, hips, shoulders or shoes), the side view's `VIEW_TEXT` as it is, each ending in what it stands on (`body_plan.still_text`): ", standing on all four legs, not rearing onto its hind legs" / ", resting on its base without legs, never growing any" / ", each figure with the body it has: the man on two legs; the horse on all four legs, never rising onto its hind legs" |
| front or back mid-step redraw | `WALK_START_TEXT_ANY_BODY`: one leg lifted, the others planted, then what it stands on; a body without legs has no step to catch and films from its base (`starts_mid_step` is false, `video-prompt` gives no `start_still`) |
Only the biped sentences were measured on clips; the others say no part the body lacks and are not
-yet measured. `--handed` keeps its own sentences (its arm sentences are for an item on an arm), and an
-attack's grip sentence (`HOLD_TEXT["attack"]`) still speaks of hands. `video-set`, `video-prompt
---json` and `gen`'s `extra.view` record the plan as `body_plan`. An app that draws the still itself
-with `still_view_text` and films with `build_prompt` passes the same `body_plan` to both: the clip
-starts from that still.
+yet measured. `--handed` keeps its own sentences (its arm sentences are for an item on an arm).
+`video-set`, `video-prompt --json` and `gen`'s `extra.view` record the plan as `body_plan`. An app
+that draws the still itself with `still_view_text` and films with `build_prompt` passes the same
+`body_plan` to both: the clip starts from that still.
+
+#### The sheet rows — `prepare --body-plan`
+
+The rows `prepare` writes for an image model (`prompts/<state>.txt`, [atlas workflow](atlas-workflow.md))
+were measured on people too. The walk and run rows moved "body, arm, leg, hair, and prop", the front and
+three-quarter-front walks "alternating leg, arm, shoulder", the diagonal runs traded "foot-contact phases"
+of "the left and right legs", the wave was "arm pose only: arm down, arm raised, hand tilted" (its default
+action "friendly hand wave gesture"), every row's anchor lock spent its motion on "arm counter-swing" and
+turned "the body, feet, shoulders", and a diagonal row read its facing by "shoulder overlap, hand/foot
+placement". `prepare --body-plan` (the same plans and scene form; repeatable; over the request's
+`body_plan`) gives a body that is not one biped:
+
+| Row sentence | for a body that is not one biped |
+|---|---|
+| walk, run, `running-right` / `-left` (`STATE_REQUIREMENTS`) | `STATE_REQUIREMENTS_ANY_BODY`: locomotion through "the movement of the body, whatever it moves on, loose parts such as hair, a mane or a tail, and props only" |
+| `frontwalk`, `45_frontwalk` | "alternating steps of whatever it walks on and body-height changes"; "the contact and passing poses" |
+| the diagonal runs | "alternating contact phases of whatever it moves on so the two sides clearly trade forward reach" |
+| wave | the one side that lifts, as the clip's wave does (`MOTION_TEXT["wave"]`): "lowered, lifted, swaying, returning", the body planted where it stands or rests; the default action `DEFAULT_ACTIONS_ANY_BODY["wave"]` where the request names none |
+| anchor lock (`ANCHOR_LOCK`) | `ANCHOR_LOCK_ANY_BODY`: "the contacts of whatever it moves on, body height, body lean, head bob, the bounce of hair, a mane or a tail"; rotate "the body, face angle, and gaze"; "step phase", "contacts" |
+| a diagonal row's facing | "the silhouette of hair, a mane or a tail, the overlap of near and far parts" |
+| every row, last state requirement | what it stands on (`body_plan.text`), as after a clip's motion sentence |
+
+The run records the plan in `sprite-request.json` as `body_plan` (absent without one), and a run
+prepared again from that request keeps it. No body plan, or one biped, writes every row prompt as
+2.32.0 did, byte for byte (`tests/fixtures/prepare-rows-v2.32.0.json.gz`, `tests/gen/test_prompt_freeze.py`).
+The new rows are not yet measured on an image model. A request's own `action` is its own words and is
+never rewritten.
### A clip from a video MCP on your agent — ZCRE
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index e7fd90e..5fd6d4d 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -27,7 +27,7 @@ from sprite_gen.effects import recolor, shadow
from sprite_gen.scene import render, inspect_scene
from sprite_gen.serve import serve_compose, serve_curation
from sprite_gen.spec import migrate_breathe, migrate_request
-from sprite_gen.gen.prepare import STYLE_DEFAULT, _outline_config
+from sprite_gen.gen.prepare import BODY_PLAN_HELP, STYLE_DEFAULT, _outline_config
from sprite_gen.spec.subject import SUBJECTS
from sprite_gen.workflow import guide, preferences
@@ -83,6 +83,7 @@ def _add_prepare(p: argparse.ArgumentParser) -> None:
p.add_argument("--fit-detail-bias", action=argparse.BooleanOptionalAction, default=None)
p.add_argument("--fit-outline", type=_outline_config, default=None, metavar="{on,off,STRENGTH}")
p.add_argument("--fit-pitch-hint", type=int, default=None)
+ p.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help=BODY_PLAN_HELP)
p.add_argument("--request", type=Path)
p.add_argument("--request-json")
p.add_argument("--force", action="store_true")
diff --git a/sprite_gen/gen/prepare.py b/sprite_gen/gen/prepare.py
index 7fb4983..f4a38a9 100644
--- a/sprite_gen/gen/prepare.py
+++ b/sprite_gen/gen/prepare.py
@@ -24,6 +24,8 @@ from sprite_gen.frames.extract import color_distance
from sprite_gen.compose.layers import require_valid_layer_request
from sprite_gen.spec.layout import TAXONOMY, guide_rel, prompt_rel, raw_rel
from sprite_gen.spec.subject import SUBJECTS
+from sprite_gen.video import body_plan as body_mod
+from sprite_gen.video.body_plan import Body
# Default safe margin is proportional to the cell dimension (floored), not a fixed
@@ -135,6 +137,50 @@ STATE_REQUIREMENTS = {
],
}
+# The rows above were measured on people, and the walk, run and wave rows name what only a person has: an
+# arm, a shoulder, a hand, a foot. Said of a horse, a walk sheet swings its arms. A body that is not one
+# biped (`--body-plan`, `sprite_gen.video.body_plan`) gets these in their place: no part named, the motion
+# left to whatever the body moves on, and every row then says what it stands on (`body_plan.text`). The
+# wave lifts one side, as the clip's wave does (`batch.MOTION_TEXT["wave"]`). Not measured on a sheet.
+_GAIT_ANY_BODY = "the movement of the body, whatever it moves on, loose parts such as hair, a mane or a tail, and props only"
+_NO_TRAILS = STATE_REQUIREMENTS["walk"][2]
+_DIAGONAL_ANY_BODY = {
+ "front": "Use alternating contact phases of whatever it moves on so the two sides clearly trade forward reach.",
+ "back": "Use alternating contact phases of whatever it moves on so the two sides clearly trade backward/forward reach.",
+}
+STATE_REQUIREMENTS_ANY_BODY = {
+ **{state: [rows[0], rows[1], _DIAGONAL_ANY_BODY[state.split("-")[1]], rows[3]]
+ for state, rows in STATE_REQUIREMENTS.items() if state.startswith(("running-front-", "running-back-"))},
+ "running-right": [f"Show rightward locomotion through {_GAIT_ANY_BODY}.", STATE_REQUIREMENTS["running-right"][1], _NO_TRAILS],
+ "running-left": [
+ f"Show leftward locomotion through {_GAIT_ANY_BODY}.",
+ STATE_REQUIREMENTS["running-left"][1],
+ "If an additional rightward gait row is attached, use it only as a motion-rhythm reference for motion phase and body bounce; do not copy its facing direction or redraw the character from that row.",
+ _NO_TRAILS,
+ ],
+ "run": [f"Show locomotion through {_GAIT_ANY_BODY}.", STATE_REQUIREMENTS["run"][1], _NO_TRAILS],
+ "walk": [f"Show locomotion through {_GAIT_ANY_BODY}.", STATE_REQUIREMENTS["walk"][1], _NO_TRAILS],
+ "frontwalk": [
+ "Show front-view walking through alternating steps of whatever it walks on and body-height changes.",
+ "This is difficult: make the contact and passing poses visibly different without changing identity.",
+ _NO_TRAILS,
+ ],
+ "45_frontwalk": [
+ "Show three-quarter-front walking through alternating steps of whatever it walks on and body-height changes.",
+ "This is difficult: make the contact and passing poses visibly different without changing identity.",
+ _NO_TRAILS,
+ ],
+ "wave": [
+ "Show the wave through the pose of the one side that lifts only: lowered, lifted, swaying, returning.",
+ "Keep the body planted where it stands or rests unless the action explicitly requests stepping.",
+ "Do not draw wave marks, motion arcs, lines, sparkles, symbols, or floating effects around the waving side.",
+ ],
+}
+# A default action that names a person's parts, for a body that is not one biped (`normalize_states`).
+DEFAULT_ACTIONS_ANY_BODY = {
+ "wave": "friendly wave gesture lifting one side; the waving side changes clearly while the body stays planted",
+}
+
CHROMA_CANDIDATES = [
("magenta", "#FF00FF"),
("green", "#00FF00"),
@@ -435,8 +481,10 @@ def choose_chroma_key(reference: Path | None, requested: str) -> dict[str, Any]:
return result
-def normalize_states(raw: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
+def normalize_states(raw: dict[str, Any] | None, bodies: list[Body] | None = None) -> dict[str, dict[str, Any]]:
+ """`bodies` (`--body-plan`) that are not one biped take `DEFAULT_ACTIONS_ANY_BODY` where a state names no action."""
source = raw or DEFAULT_STATES
+ defaults = DEFAULT_ACTIONS_ANY_BODY if not body_mod.biped(bodies) else {}
normalized: dict[str, dict[str, Any]] = {}
for state, entry in source.items():
if not isinstance(entry, dict):
@@ -448,7 +496,9 @@ def normalize_states(raw: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
"frames": frames,
"fps": int(entry.get("fps", DEFAULT_STATES.get(state, {}).get("fps", 6))),
"loop": bool(entry.get("loop", True)),
- "action": str(entry.get("action", DEFAULT_STATES.get(state, {}).get("action", state))),
+ # with no states asked for, the default states' actions are defaults too
+ "action": str(entry.get("action") if raw and "action" in entry
+ else defaults.get(state, DEFAULT_STATES.get(state, {}).get("action", state))),
}
# A row's track kind is request truth (docs/layer-tracks.md §3.2) and is
# carried only when declared: an undeclared row IS `base`, and writing
@@ -467,7 +517,7 @@ def normalize_states(raw: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
# rule is written down, and `dropped_key_notes` makes every drop observable
# instead of silent.
REQUEST_KEYS_CARRIED = ("cell", "states", "style",
- "directions", "fit", "rig", "layers")
+ "directions", "fit", "rig", "layers", "body_plan")
# Written by prepare itself, from CLI flags and from measuring the base image. An
# incoming copy is not carried either, but it is restated rather than lost, so the
# note names it separately: `character` comes from --character-id/--description/
@@ -702,7 +752,8 @@ def directional_parts(state: str) -> tuple[str, str] | None:
return match.group(1), match.group(2)
-def directional_requirements(state: str) -> list[str]:
+def directional_requirements(state: str, any_body: bool = False) -> list[str]:
+ """`any_body`: a body that is not one biped, read by its silhouette rather than a person's shoulders, hands and feet."""
parts = directional_parts(state)
if not parts:
return []
@@ -714,7 +765,9 @@ def directional_requirements(state: str) -> list[str]:
requirements = [
f"Lock the whole row to a 45-degree {body_view} view facing {camera_side} and slightly {toward}.",
f"Do not average this into a straight front, straight back, or pure side-view sprite.",
- f"Make {camera_side} readable through face/body orientation, hair silhouette, shoulder overlap, hand/foot placement, and prop angle.",
+ (f"Make {camera_side} readable through face/body orientation, the silhouette of hair, a mane or a tail, the overlap of near and far parts, and prop angle."
+ if any_body else
+ f"Make {camera_side} readable through face/body orientation, hair silhouette, shoulder overlap, hand/foot placement, and prop angle."),
"If a 4-direction reference sheet is attached, use it as the direction SSoT for facing only; do not copy its pose or state.",
"If a single target-direction anchor is attached, its facing direction is authoritative and overrides any paired-row reference.",
]
@@ -750,6 +803,27 @@ def draw_guide(path: Path, frames: int, cell: dict[str, Any]) -> None:
image.save(path)
+# The anchor lock's motion words: a person's (`ANCHOR_LOCK`), and for a body that is not one biped the same
+# without the arms, shoulders, feet or legs it may lack (`ANCHOR_LOCK_ANY_BODY`).
+ANCHOR_LOCK = {
+ "budget": "limb contacts, arm counter-swing, body height, torso lean, head bob, hair bounce",
+ "rotate": "the body, feet, shoulders, face angle, and gaze",
+ "phase": "leg phase",
+ "contacts": "foot contacts",
+}
+ANCHOR_LOCK_ANY_BODY = {
+ "budget": "the contacts of whatever it moves on, body height, body lean, head bob, the bounce of hair, a mane or a tail",
+ "rotate": "the body, face angle, and gaze",
+ "phase": "step phase",
+ "contacts": "contacts",
+}
+
+
+def request_bodies(request: dict[str, Any]) -> list[Body] | None:
+ """The run's body plan (`sprite-request.json` `body_plan`, `--body-plan`); None when it names none."""
+ return [Body(**body) for body in request.get("body_plan") or []] or None
+
+
def row_prompt(request: dict[str, Any], state: str, entry: dict[str, Any]) -> str:
cell = request["cell"]
chroma = request["chroma_key"]
@@ -759,11 +833,17 @@ def row_prompt(request: dict[str, Any], state: str, entry: dict[str, Any]) -> st
cell_height = int(cell["height"])
safe_margin_x = int(cell["safe_margin_x"])
safe_margin_y = int(cell["safe_margin_y"])
+ bodies = request_bodies(request)
+ any_body = not body_mod.biped(bodies)
+ stands_on = body_mod.text(bodies)
state_requirements = [
*direction_prefix_requirements(request, state),
- *directional_requirements(state),
- *STATE_REQUIREMENTS.get(state, []),
+ *directional_requirements(state, any_body),
+ *(STATE_REQUIREMENTS_ANY_BODY.get(state, STATE_REQUIREMENTS.get(state, [])) if any_body
+ else STATE_REQUIREMENTS.get(state, [])),
+ *([stands_on] if stands_on else []),
]
+ anchor_lock = ANCHOR_LOCK_ANY_BODY if any_body else ANCHOR_LOCK
state_requirement_text = ""
if state_requirements:
state_requirement_text = "\n\nState-specific requirements:\n" + "\n".join(
@@ -798,11 +878,11 @@ Animation action: {entry["action"]}.
Anchor lock:
- Accepted idle/direction anchors own character identity, outfit details, colors, face design, asymmetric markings, and side-specific accessories for final action rows.
- Base character images and original character sheets are pre-idle sources only. Do not reinterpret or reintroduce base-character details inside a direction-anchor action row.
-- This row owns motion only. Spend the variation budget on limb contacts, arm counter-swing, body height, torso lean, head bob, hair bounce, and loop continuity.
+- This row owns motion only. Spend the variation budget on {anchor_lock["budget"]}, and loop continuity.
- Do not redesign or reinterpret identity details while animating. Keep face, hair shape, markings, palette, outline weight, body proportions, outfit, props, and silhouette copied from the approved anchors.
- Preserve side-specific features exactly as the approved anchors show them. Do not solve hairpin side, earring side, logos, handed props, scars, one-sided markings, asymmetric clothing, or lighting cues from scratch inside the row.
-- When generating a paired left/right row, use the paired row reference only for timing, scale, and animation intensity. Rotate the body, feet, shoulders, face angle, and gaze to the target facing, but keep identity details attached according to the accepted target-direction anchor.
-- For cyclic locomotion, do not let a single running/walking pose anchor determine every frame's leg phase. When a multi-pose motion reference is attached, use it for foot contacts.
+- When generating a paired left/right row, use the paired row reference only for timing, scale, and animation intensity. Rotate {anchor_lock["rotate"]} to the target facing, but keep identity details attached according to the accepted target-direction anchor.
+- For cyclic locomotion, do not let a single running/walking pose anchor determine every frame's {anchor_lock["phase"]}. When a multi-pose motion reference is attached, use it for {anchor_lock["contacts"]}.
- Prefer a subtler animation over any change that mutates the character identity.
{state_requirement_text}
@@ -826,6 +906,26 @@ Layout requirements:
Output only the sprite strip image."""
+BODY_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; overrides the request's "
+ "body_plan): no row prompt names a part the body lacks, as video-set --body-plan")
+
+
+def parse_body_plan(cli: list[str] | None, raw: Any) -> list[Body] | None:
+ """`--body-plan` if given, else the request's `body_plan` (specs, or `{"plan", "figure"}` as
+ `sprite-request.json` records it)."""
+ if cli:
+ return body_mod.parse_all(list(cli)) or None
+ if raw is None:
+ return None
+ if not isinstance(raw, list):
+ raise SystemExit(f"request body_plan must be a list, got {raw!r}")
+ specs = [str(item) if not isinstance(item, dict)
+ else f"{item['figure']}={item.get('plan')}" if item.get("figure") else str(item.get("plan"))
+ for item in raw]
+ return body_mod.parse_all(specs) or None
+
+
def _outline_config(value: str):
"""Parse --fit-outline: on -> True, off -> False, otherwise a 0..1 strength."""
lowered = value.strip().lower()
@@ -872,6 +972,7 @@ def _build_parser() -> argparse.ArgumentParser:
parser.add_argument("--fit-pitch-hint", type=int, default=None, help="pixel unfake fallback pixel pitch when per-frame detection is inconclusive")
parser.add_argument("--directions", help="comma list of generated directions (e.g. down,side,up); states must be named <direction>_<state>; missing <direction>_idle anchors are synthesized and a generation plan is written")
parser.add_argument("--mirror", help="comma list of target=source pairs covered by runtime mirroring instead of generation (e.g. left=side)")
+ parser.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help=BODY_PLAN_HELP)
parser.add_argument("--request", type=Path)
parser.add_argument("--request-json")
parser.add_argument("--force", action="store_true")
@@ -903,7 +1004,8 @@ def _run(args: argparse.Namespace):
raise SystemExit(f"output dir exists and is not empty: {out_dir}; pass --force")
raw_request = load_request(args.request, args.request_json)
- states = normalize_states(raw_request.get("states"))
+ bodies = parse_body_plan(args.body_plan, raw_request.get("body_plan"))
+ states = normalize_states(raw_request.get("states"), bodies)
# 방향 계약: CLI 가 request JSON 을 override 한다 (fit 과 동일 규칙)
raw_directions = dict(raw_request.get("directions") or {})
if args.directions:
@@ -971,6 +1073,9 @@ def _run(args: argparse.Namespace):
request["subject"] = subject
if directions:
request["directions"] = directions
+ # Body plan: recorded only when named, so a run without one keeps its request as it was.
+ if bodies:
+ request["body_plan"] = [vars(body) for body in bodies]
# 파일 택소노미 계약: 신규 런 기본. 방향 계약과 결합 시 raw/frames/guides/prompts
# 가 <direction>/<pose> 로 나뉜다 (layout.py SSoT). legacy 런은 필드 없음 = flat.
request["layout"] = TAXONOMY
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index bf41af6..5832719 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -193,6 +193,22 @@ MOTION_TEXT = {
"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.",
}
+# The attack's hold and sentence for a body that is not one biped (`body_plan`): what it holds keeps how it is
+# held, with no hand counted, and with nothing held it attacks with its own body — which part strikes is the
+# body's to say (`--motion`), not the engine's to guess (a bite, a head-butt, a forefoot). Not measured on a clip.
+HOLD_TEXT_ANY_BODY = {
+ "attack": (
+ "Anything it holds or carries stays exactly as shown in the image, held the same way, and nothing is dropped "
+ "or moved to another place. A part the motion does not use stays where it is drawn, with anything it holds, "
+ "and the body keeps facing the same direction without turning."
+ ),
+}
+ATTACK_TEXT_ANY_BODY = (
+ "performs one melee attack with what it is already holding, or with its own body if it holds nothing, keeping "
+ "every piece of its gear and outfit exactly as drawn: 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_ANY_BODY["attack"]
+)
# The idle for a body that is not one biped (`body_plan`): the same stillness, with no feet counted and no
# chest, shoulders or arms named, so a horse is not stood up on two feet. Not measured on a clip.
IDLE_TEXT_ANY_BODY = (
@@ -365,7 +381,8 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:
`body_plan` (`body_plan.parse_all`) says what the subject stands on, one plan or one per figure of a scene.
None, or one biped, keeps the sentences measured on people; any other body gets them without a part it
- lacks (`IDLE_TEXT_ANY_BODY`, `LITE_WALK_TEXT_LEGGED` / `_LEGLESS`, `LITE_HEAD_TEXT_ANY_BODY`) and, after the
+ lacks (`IDLE_TEXT_ANY_BODY`, `ATTACK_TEXT_ANY_BODY` / `HOLD_TEXT_ANY_BODY`, `LITE_WALK_TEXT_LEGGED` / `_LEGLESS`,
+ `LITE_HEAD_TEXT_ANY_BODY`) and, after the
motion sentence or the caller's paragraph, what it stands on (`body_plan.text`).
Without `handed` or `body_plan` the prompt is 2.22.0's, to the byte (`tests/gen/test_prompt_freeze.py`). `handed` lists
@@ -388,7 +405,8 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:
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 ""
+ holds = HOLD_TEXT if body_mod.biped(body_plan) else HOLD_TEXT_ANY_BODY
+ hold = f" {holds[state]}" if state in holds else ""
if state in GAIT_STATES and direction in GAIT_HOLD_TEXT:
hold += f" {GAIT_HOLD_TEXT[direction].format(facing=facing)}"
repeat = f" {REPEAT_TEXT[state]}" if state in REPEAT_TEXT else ""
@@ -399,6 +417,7 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:
else:
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 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)
diff --git a/sprite_gen/video/body_plan.py b/sprite_gen/video/body_plan.py
index f12ee05..87fd8e9 100644
--- a/sprite_gen/video/body_plan.py
+++ b/sprite_gen/video/body_plan.py
@@ -5,10 +5,12 @@ The engine's measured walk and idle sentences were measured on people, and some
has: the Lite walk's arm swing (`batch.LITE_WALK_TEXT`), the arms in the Lite back-diagonal head hold
(`LITE_HEAD_TEXT`), the idle's two feet, chest, shoulders and arms (`MOTION_TEXT["idle"]`), and the front
or back walk's mid-step redraw, one foot under each hip and the arms swinging (`WALK_START_TEXT`), and the
-front, back and diagonal still a clip starts from, both feet, chest, hips and shoes (`STILL_VIEW_TEXT`). Said of a
-horse, they walk it on a person's legs or stand it up on two. The caller names the body plan (`parse`,
-`--body-plan`): one for the character ("quadruped"), or one per figure in a scene ("the man=biped",
-"the horse=quadruped").
+front, back and diagonal still a clip starts from, both feet, chest, hips and shoes (`STILL_VIEW_TEXT`), the
+attack's bare hands and grip (`MOTION_TEXT["attack"]`, `HOLD_TEXT["attack"]`), and the sheet rows `prepare` writes
+(`prepare.STATE_REQUIREMENTS`: a walk's arm and leg, a front walk's shoulder, a wave's hand). Said of a
+horse, they walk it on a person's legs, stand it up on two or strike with its hands. The caller names the body plan (`parse`,
+`--body-plan`, also `prepare --body-plan`): one for the character ("quadruped"), or one per figure in a scene
+("the man=biped", "the horse=quadruped").
| plan | stands on | the engine says |
|---|---|---|
@@ -20,7 +22,7 @@ The still a clip starts from is drawn with a view sentence (`batch.still_view_te
that counts a person's feet and names the chest, hips, shoulders and shoes; a body that is not one biped
gets it without them, ending in what it stands on (`still_text`).
-No body, or one biped, is the 2.22.0 prompt to the byte (`tests/gen/test_prompt_freeze.py`). Any other
+No body, or one biped, is the 2.22.0 prompt (a sheet row, 2.32.0's) to the byte (`tests/gen/test_prompt_freeze.py`). Any other
body gets the sentences without the parts it lacks and, after the motion sentence, what it stands on
(`text`); a scene of several figures says it per figure. Only the biped sentences were measured; the
others say no part the body lacks and are not yet measured on a clip.
diff --git a/tests/fixtures/prepare-rows-v2.32.0.json.gz b/tests/fixtures/prepare-rows-v2.32.0.json.gz
new file mode 100644
index 0000000..0fa785f
Binary files /dev/null and b/tests/fixtures/prepare-rows-v2.32.0.json.gz differ
diff --git a/tests/gen/prepare_freeze_table.py b/tests/gen/prepare_freeze_table.py
new file mode 100644
index 0000000..7944483
--- /dev/null
+++ b/tests/gen/prepare_freeze_table.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Every row prompt `prepare` writes for a character with no body plan, drawn through `prepare.run`.
+
+The sheet rows were measured on people, and a body plan (`--body-plan`, 2.33.0) changes only what is said
+to a body that is not one biped. This table is the evidence that a run with no body plan, or one biped, is
+the 2.32.0 run to the byte: it draws every row prompt for every state with a sentence of its own (the walk
+and run rows, the diagonal runs, the wave and the jump), the default states, a state with no sentence,
+with and without a base image, and a direction-contract run, through the entry point 2.32.0 already had —
+so the same code runs against the tag's source and records what it wrote.
+
+Record (from the repo root, the tag's source unpacked somewhere):
+
+ git archive 44d6242 | tar -x -C /tmp/sprite-gen-2.32.0
+ python tests/gen/prepare_freeze_table.py /tmp/sprite-gen-2.32.0 tests/fixtures/prepare-rows-v2.32.0.json.gz
+
+`tests/gen/test_prompt_freeze.py` draws the table again against this tree and compares.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import gzip
+import io
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Iterator
+
+CHARACTER = "A small fox adventurer in a green cloak"
+# every state `prepare` has a sentence for, and one it has none for
+ROW_STATES = ("running-right", "running-left", "running-front-right", "running-front-left", "running-back-right",
+ "running-back-left", "run", "walk", "frontwalk", "45_frontwalk", "wave", "jump", "idle", "attack", "cheer")
+DIRECTION_STATES = ("down_idle", "down_walk", "side_walk", "side_attack", "up_wave")
+
+
+def _requests() -> Iterator[tuple[str, dict[str, Any]]]:
+ """(label, `prepare.run` keyword arguments other than the run dir and base image)."""
+ yield "default-states", {}
+ # no action: a state `prepare` has a default for takes it; the others say their own
+ yield "every-state", {"request_json": json.dumps({"states": {
+ state: {"frames": 4} if state in ("idle", "attack", "jump", "wave") else {"frames": 6, "action": f"{state} cycle"}
+ for state in ROW_STATES}})}
+ yield "directions", {"request_json": json.dumps({"states": {state: {"frames": 4} for state in DIRECTION_STATES}}),
+ "directions": "down,side,up", "mirror": "left=side"}
+
+
+def draw(**extra: Any) -> dict[str, str]:
+ """Every row prompt, keyed by `<request>/<base>/<prompt path>`; `extra` goes to every `prepare.run`."""
+ from PIL import Image
+ from sprite_gen.gen import prepare
+
+ out: dict[str, str] = {}
+ with tempfile.TemporaryDirectory() as tmp:
+ base = Path(tmp) / "base.png"
+ Image.new("RGB", (32, 32), (90, 140, 60)).save(base)
+ for (label, kwargs), with_base in ((r, b) for r in _requests() for b in (False, True)):
+ run_dir = Path(tmp) / f"{label}-{with_base}"
+ with contextlib.redirect_stdout(io.StringIO()):
+ prepare.run(out_dir=run_dir, character_id="fox", description=CHARACTER,
+ base_image=base if with_base else None, **kwargs, **extra)
+ for prompt in sorted((run_dir / "prompts").rglob("*.txt")):
+ name = f"{label}/{'base' if with_base else 'no-base'}/{prompt.relative_to(run_dir / 'prompts')}"
+ out[name] = prompt.read_text(encoding="utf-8")
+ return out
+
+
+def write(path: Path, table: dict[str, str]) -> None:
+ data = json.dumps(table, ensure_ascii=False, indent=1, sort_keys=True).encode() + b"\n"
+ with open(path, "wb") as raw, gzip.GzipFile(fileobj=raw, mode="wb", mtime=0, filename="") as out:
+ out.write(data)
+
+
+def read(path: Path) -> dict[str, str]:
+ with gzip.open(path, "rb") as file:
+ return json.loads(file.read())
+
+
+if __name__ == "__main__":
+ source, target = Path(sys.argv[1]).resolve(), Path(sys.argv[2])
+ sys.path.insert(0, str(source))
+ import sprite_gen
+
+ assert Path(sprite_gen.__file__).resolve().is_relative_to(source), sprite_gen.__file__
+ write(target, draw())
+ print(f"{target}: {len(read(target))} prompts from {source}")
diff --git a/tests/gen/test_body_plan_sheets.py b/tests/gen/test_body_plan_sheets.py
new file mode 100644
index 0000000..0e2364f
--- /dev/null
+++ b/tests/gen/test_body_plan_sheets.py
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A sheet of a horse does not swing its arms, and a horse's attack is not made with its hands (`--body-plan`).
+
+The clip's walk, idle and still took a body plan in 2.32.0; the sheet rows `prepare` writes and the clip's
+attack did not. The walk and run rows moved "body, arm, leg", the front walks "alternating leg, arm,
+shoulder", the wave "arm pose only ... hand tilted", every row's anchor lock spent its motion on "arm
+counter-swing" and turned "the body, feet, shoulders", the diagonal rows read the facing by "shoulder overlap,
+hand/foot placement", and the attack struck "bare hands only if it holds nothing" with "one hand stays one
+hand". A quadruped, a body without legs and a scene of a man leading a horse each get rows and an attack with
+no part they lack; no body plan, or one biped, keeps every prompt byte for byte (`test_prompt_freeze.py`).
+Subjects are synthetic.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import prepare_freeze_table as table
+from sprite_gen.gen import prepare
+from sprite_gen.video import batch, body_plan as bp, clip_prompt
+
+FIXTURE = Path(__file__).resolve().parents[1] / "fixtures" / "prepare-rows-v2.32.0.json.gz"
+LITE, PRO = "grok-imagine-video-1.5-lite", "grok-imagine-video-1.5"
+BODIES = {
+ "quadruped": (["quadruped"], "A brown horse"),
+ "legless": (["legless"], "A green slime"),
+ "scene": (["the man=biped", "the horse=quadruped"], "A man leading a brown horse by its reins"),
+}
+# Words that name a part only a person has, or count a person's feet (as `tests/video/test_body_plan.py`), and a fist.
+PERSON = re.compile(r"\b(arms?|hands?|fists?|wrists?|elbows?|shoulders?|chest|hips?|hip-width|knees?|both feet|one foot|"
+ r"the other foot|shoes?|heels?|toes?)\b", re.IGNORECASE)
+# A body without legs has no legs or feet to step on, apart from the sentence saying it has none.
+LEGS = re.compile(r"\b(legs?|feet|foot)\b", re.IGNORECASE)
+
+
+def _named(text: str, specs: list[str]) -> list[str]:
+ bodies = bp.parse_all(specs)
+ words = {m.group(0).lower() for m in PERSON.finditer(text)}
+ if bp.legless(bodies):
+ words |= {m.group(0).lower() for m in LEGS.finditer(text.replace(bp.text(bodies), ""))}
+ return sorted(words)
+
+
[email protected](scope="module")
+def rows() -> dict[str, dict[str, str]]:
+ return {name: table.draw(body_plan=specs) for name, (specs, _) in BODIES.items()}
+
+
[email protected]("body", list(BODIES))
+def test_no_sheet_row_names_a_part_the_body_lacks(body, rows) -> None:
+ """Every row `prepare` writes — each state with a sentence of its own, the default states, a state with
+ none, with and without a base image, and a direction-contract run — and each says what it stands on."""
+ specs, _ = BODIES[body]
+ drawn = rows[body]
+ assert sorted(drawn) == sorted(table.read(FIXTURE))
+ assert not {name: words for name, text in drawn.items() if (words := _named(text, specs))}
+ assert all(bp.text(bp.parse_all(specs)) in text for text in drawn.values())
+
+
+def _every_clip(body_plan, character):
+ """Each clip prompt for every state the engine has a sentence for, and one it has none for: built-in and a
+ caller's paragraph, every view and model; and the video-prompt record."""
+ for view, state, model in itertools.product(batch.VIEW_TEXT, (*batch.MOTION_TEXT, "kick"), (None, PRO, LITE)):
+ yield f"{view}/{state}/{model}", batch.build_prompt(view, state, character, model=model, body_plan=body_plan)
+ yield (f"{view}/{state}/{model}/motion",
+ batch.build_prompt(view, state, character, motion="It strikes once, about 1 s.", model=model,
+ body_plan=body_plan))
+ for view, state in itertools.product(batch.VIEW_TEXT, batch.MOTION_TEXT):
+ yield f"video-prompt/{view}/{state}", clip_prompt.plan_prompt(
+ direction=view, state=state, character=character, body_plan=body_plan)["prompt"]
+
+
[email protected]("body", list(BODIES))
+def test_no_clip_prompt_of_any_state_names_a_part_the_body_lacks(body) -> None:
+ specs, character = BODIES[body]
+ named = {name: _named(text, specs) for name, text in _every_clip(bp.parse_all(specs), character)}
+ assert len(named) > 250
+ assert not {name: words for name, words in named.items() if words}
+
+
+def test_without_a_body_plan_the_v2_32_rows_and_attack_did_name_a_persons_parts() -> None:
+ """What the report was about, as 2.32.0 said it to every body."""
+ frozen = table.read(FIXTURE)
+ assert "body, arm, leg, hair" in frozen["every-state/base/walk.txt"]
+ assert "alternating leg, arm, shoulder" in frozen["every-state/base/frontwalk.txt"]
+ assert "alternating leg, arm, shoulder" in frozen["every-state/base/45_frontwalk.txt"]
+ assert "hand tilted" in frozen["every-state/base/wave.txt"]
+ assert "friendly hand wave gesture" in frozen["default-states/base/wave.txt"]
+ assert "arm counter-swing" in frozen["every-state/base/jump.txt"]
+ assert "shoulder overlap, hand/foot placement" in frozen["every-state/base/running-front-right.txt"]
+ attack = batch.build_prompt("side", "attack", "A brown horse")
+ assert "bare hands only if it holds nothing" in attack and "one hand stays one hand" in attack
+ assert "one hand stays one hand" in batch.build_prompt("side", "attack", "A brown horse", motion="It bites.")
+
+
+def test_a_horse_attacks_with_what_it_holds_or_its_own_body() -> None:
+ horse = bp.parse_all(["quadruped"])
+ assert batch.build_prompt("side", "attack", "A brown horse", body_plan=horse) == (
+ "2D game sprite animation. A brown horse performs one melee attack with what it is already holding, or with "
+ "its own body if it holds nothing, keeping every piece of its gear and outfit exactly as drawn: 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). Anything it holds or carries stays exactly as shown in the "
+ "image, held the same way, and nothing is dropped or moved to another place. A part the motion does not use "
+ "stays where it is drawn, with anything it holds, and the body keeps facing the same direction without "
+ "turning. It stays on all four legs, as in the image, and never rises onto its hind legs. The character is "
+ "seen from the exact side, facing right. Stays centered in the frame and does not move across the screen; "
+ "the body, hair and anything it holds always stay fully inside the frame with margin. Camera completely "
+ "locked, no zoom, no pan, no reframing. The background stays a perfectly flat, pure chroma-key fill for the "
+ "whole clip — no shadows, no ground line, no particles, no lighting changes, no effects. Keep the design, "
+ "colors and proportions exactly as in the image. Crisp, clean frames with no motion blur, no smears and no "
+ "afterimages."
+ )
+ told = batch.build_prompt("side", "attack", "A brown horse", motion="It bites.", body_plan=horse)
+ assert told.startswith(f"2D game sprite animation. It bites. {bp.ONE_TEXT['quadruped']} "
+ f"{batch.HOLD_TEXT_ANY_BODY['attack']} A brown horse is seen")
+
+
+def test_a_horse_walk_row_and_wave(rows) -> None:
+ drawn = rows["quadruped"]
+ walk = drawn["every-state/base/walk.txt"]
+ assert ("- Show locomotion through the movement of the body, whatever it moves on, loose parts such as hair, a "
+ "mane or a tail, and props only.\n") in walk
+ assert walk.index("- Do not draw speed lines") < walk.index(f"- {bp.ONE_TEXT['quadruped']}\n") < walk.index(
+ "Transparency and artifact rules:")
+ assert ("Animation action: friendly wave gesture lifting one side; the waving side changes clearly while the "
+ "body stays planted.") in drawn["default-states/base/wave.txt"]
+ # a state with no sentence of its own still says what the body stands on
+ assert f"State-specific requirements:\n- {bp.ONE_TEXT['quadruped']}\n" in drawn["every-state/base/cheer.txt"]
+
+
+def _prepare_cli(*args: str) -> subprocess.CompletedProcess:
+ return subprocess.run([sys.executable, "-m", "sprite_gen.cli", "prepare", *args], text=True, capture_output=True)
+
+
+def test_the_sheet_cli_takes_records_and_carries_the_body_plan(tmp_path) -> None:
+ first = tmp_path / "first"
+ result = _prepare_cli("--out-dir", str(first), "--character-id", "horse", "--description", "A brown horse",
+ "--request-json", json.dumps({"states": {"walk": {"frames": 6}, "wave": {"frames": 4}}}),
+ "--body-plan", "the man=biped", "--body-plan", "the horse=quadruped")
+ assert result.returncode == 0, result.stderr
+ request = json.loads((first / "sprite-request.json").read_text())
+ assert request["body_plan"] == [{"plan": "biped", "figure": "the man"}, {"plan": "quadruped", "figure": "the horse"}]
+ assert request["states"]["wave"]["action"] == prepare.DEFAULT_ACTIONS_ANY_BODY["wave"]
+ # the recorded request, reused, carries its body plan: same rows, nothing dropped
+ again = tmp_path / "again"
+ result = _prepare_cli("--out-dir", str(again), "--character-id", "horse", "--description", "A brown horse",
+ "--request", str(first / "sprite-request.json"))
+ assert result.returncode == 0 and "body_plan" not in result.stderr, result.stderr
+ assert json.loads((again / "sprite-request.json").read_text())["body_plan"] == request["body_plan"]
+ for prompt in (first / "prompts").rglob("*.txt"):
+ assert (again / "prompts" / prompt.relative_to(first / "prompts")).read_text() == prompt.read_text()
+ # the CLI's body plan overrides the request's
+ legless = tmp_path / "legless"
+ prepare.run(out_dir=legless, character_id="slime", request=first / "sprite-request.json", body_plan=["legless"])
+ assert json.loads((legless / "sprite-request.json").read_text())["body_plan"] == [{"plan": "legless", "figure": ""}]
+ # without one, the request has no body_plan key at all
+ plain = tmp_path / "plain"
+ prepare.run(out_dir=plain, character_id="fox")
+ assert "body_plan" not in json.loads((plain / "sprite-request.json").read_text())
+
+
[email protected]("args, match", [
+ (["--body-plan", "horse"], "expected"),
+ (["--body-plan", "quadruped", "--body-plan", "the man=biped"], "names each figure"),
+ (["--request-json", json.dumps({"body_plan": "quadruped"})], "must be a list"),
+])
+def test_a_sheet_body_plan_is_refused_before_the_run_dir_is_written(tmp_path, args, match) -> None:
+ result = _prepare_cli("--out-dir", str(tmp_path / "run"), "--character-id", "horse", *args)
+ assert result.returncode != 0 and re.search(match, result.stderr), result.stderr
+ assert not (tmp_path / "run").exists()
diff --git a/tests/gen/test_prompt_freeze.py b/tests/gen/test_prompt_freeze.py
index 224077d..84c3023 100644
--- a/tests/gen/test_prompt_freeze.py
+++ b/tests/gen/test_prompt_freeze.py
@@ -66,3 +66,20 @@ def test_the_default_walk_keeps_its_treadmill_and_screen_sentences(frozen, drawn
assert "The character is seen from the exact side, facing right." in side
front = drawn["clip/front@right/walk/built-in/default/pinned=None/no-character"]
assert "The character is seen from the front" in front
+
+
+PREPARE_FIXTURE = Path(__file__).resolve().parents[1] / "fixtures" / "prepare-rows-v2.32.0.json.gz"
+
+
[email protected]("body_plan", [None, ["biped"]], ids=["no-body-plan", "biped"])
+def test_every_sheet_row_with_no_body_plan_or_one_biped_is_2_32_0s_byte_for_byte(body_plan) -> None:
+ """The rows `prepare` writes (`prepare_freeze_table.py`) were frozen at 2.32.0 when the body plan reached
+ them: a run with no body plan, or `--body-plan biped`, writes every row prompt as 2.32.0 did."""
+ import prepare_freeze_table as rows
+
+ frozen = rows.read(PREPARE_FIXTURE)
+ drawn = rows.draw(**({"body_plan": body_plan} if body_plan else {}))
+ assert sorted(drawn) == sorted(frozen) and len(frozen) == 52
+ changed = [name for name in frozen if drawn[name] != frozen[name]]
+ assert not changed, (f"{len(changed)} of {len(frozen)} sheet rows differ from 2.32.0; first:\n"
+ + _first_difference(changed[0], frozen[changed[0]], drawn[changed[0]]))