Skip to content

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

docs(prompt): prompt assembly, the far arm of a side view, the reworked handed-check; changelog

Soohong Kimf77ef87eebcb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 837f5de..52dd4d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,21 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v2.23.0)
+
+- **Every engine sentence goes on a prompt through one place, and none is said twice** (`sprite_gen/gen/prompt_parts.py`, `Prompt.add`). A prompt is the caller's text and then the engine's pieces — the view, the turn over a reference, a handed item, the key background, the layout guide; for a clip the hold, the frame and camera rules, a Lite model's sentences and the side view's hold. Each piece was attached where it was made, so some were said twice and some disagreed. A sentence the prompt already has is now dropped, a piece whose topic the prompt covers is left out, and one the prompt rules out is refused. `gen.still_prompt`, `batch.clip_prompt_parts`, `walk_start_prompt` and `video.side_view_prompt` build on it. [docs/prompt-assembly.md](docs/prompt-assembly.md).
+- **Fix: a reference still with `--direction` said the turn twice, the second time as a full profile.** After the view sentence, the reference piece said "The subject must be facing left (toward the left edge of the image)", which asked a three-quarter view for a side view's turn. With `--direction` it now says only what the view sentence does not: "Left here means toward the left edge of the image, regardless of the reference image's orientation. Preserve the subject's design." A reference run with `--facing` alone is unchanged.
+- **Fix: a facing correction's regeneration carried the facing sentence twice** (`--facing-fix regen`): the correction now replaces the sentence it corrects.
+- **Fix: a key background is read however it is worded, and not when ruled out** (`chroma.named_key_background`). "A background of pure magenta" and "magenta-colored background" were not read, so the key line went on a second time. "No green screen" and "holding a green key" were read as asking for green, so a reference run got no key line and came back on a light ground. The name before or after "background" / "backdrop", "keyed on magenta" and "on a green key" are read now; a negation right before the key's name rules it out (`chroma.ruled_out_key_backgrounds`). A prompt that rules out the key `--chroma-key` chose is refused before the model runs.
+- **Fix: `video --direction side` added its side-view hold after a clip prompt that already had it.** A `video-prompt` or `video-set` prompt is sent as it is, and one that faces the other way than `--facing` is refused before the facing inspection.
+- **A walk or run says "in place" and its view once.** The side and diagonal gait sentences ended "without moving across the screen" and the frame sentence said "does not move across the screen"; the gait sentences and holds no longer add it. A walk or run seen from the front, from behind or at a diagonal said its view in the gait sentence ("facing the viewer", "keeps the exact three-quarter back angle of the image") and again in the view sentence ("The character is seen from the front, facing the viewer directly."); its prompt now leaves the view sentence out (`batch.GAIT_SAYS_VIEW`). A side gait keeps the view sentence, and a caller's own side gait is held with "It stays in place as if on a treadmill." (its facing is the view sentence's). Other states are unchanged. A cached `video-set` clip made with the old wording is refused as before ("cached clip prompt differs"); pass `--force` to film it again.
+- **The caller's own words are reported, not edited.** Text that turns the subject another way than `--facing` (or to a side in a front or back view), or puts a `--handed` item on its other side, is sent as written with a warning; text that repeats an option gets a note. `gen` prints them and records `extra.prompt_notes`; `video-prompt --json` lists conflicts in `warnings` and all of them in `notes`; `video-set` records `prompt_notes` per item.
+- **Fix: a watch on the far wrist was in no frame of a side walk.** 2.22.0 said every item on the far side of a side view hidden, and never named it in the clip ("the wrist in front of the body stays bare"). A walking character's far arm comes forward of the body with every step, and what it wears shows then. An item on a far arm or leg (`handedness.limb` reads the body part) is now said to show wherever that limb is out in front of the body: in the still ("wherever the far arm reaches out in front of the body, clear of its outline, the black smartwatch shows whole on it; where the body covers that arm, it is hidden") and in a walk or run ("stays on the wrist that wears it in the image, on the arm on the far side of the body, and shows each time that arm swings forward; the arm nearer the viewer stays bare, exactly as in the image"). On the near arm the walk says the other arm stays bare "both where it shows behind the body and where it swings out in front of it". Both start "Both arms swing back and forth with each step, opposite to the legs.", and no sentence holds an arm still. A far part that does not swing (a pin on the far side of the head) and a state that does not step (idle, attack) keep the 2.22.0 sentences. [docs/video-pipeline.md](docs/video-pipeline.md#handedness--an-item-on-one-side).
+- **A clip keeps what its first frame shows**: for a walk or run with an item on the far limb of a side view, `video-prompt --json` (`still_needs`, and stderr) and `video-set` (each item's `still_needs`) say the still must be drawn mid-stride with that limb out in front of the body and the item in view. The docs give the pose sentence for the prompt.
+- **One handed sentence per wrist, not per item**: with an item on each wrist a side clip said "the wrist in front of the body stays bare" and "the red ribbon stays on the wrist in front of the body" together, and with two items on one wrist it said the same sentence twice. Items on one part share a sentence, a part another item is on is not called bare, and a still says "none of it" there. A diagonal's clip sentence also reads "…, nearer the viewer, for the whole clip" (the comma was missing).
+- **`handed-check` passes a far arm's item in view and fails the near arm's** (side views): 2.22.0 failed every frame that showed the far item whole ("in full view on the far side"). An item on a far arm or leg must now be out in front of the body in every frame it shows — on the facing side of the body's centre by at least a tenth of the body's height (`far_in_front`); at or behind the centre it is on the near limb. With the new `--state walk|run` it must also show in at least a quarter of the frames (`far_shown`; unchecked without `--state` or for a state that does not step). A side view's near item must show in three quarters of the frames, not half: a far item turned over to face the other way shows in about half. A far part that does not swing keeps the hidden-or-a-sliver rule (`far_hidden`), and a diagonal's near side keeps half.
+- **`tests/gen/test_prompt_assembly.py`** draws every prompt in the option table as text — views, facings, items, what the caller's text already says, states, clip models, the correction, the start still and the hand-offs between verbs — and checks each for a sentence said twice, words that turn the subject both ways, more than one key background, a limb called bare and dressed at once, and a swinging arm in a state that does not step.
+
## v2.22.0 - A character with an item on one side has its left-facing views drawn, not mirrored, and an attack is filmed with less room above
- **Handedness, said once** (`sprite_gen/gen/handedness.py`): `--handed "<item>=<left|right> [part]"` names an item on one of the character's own sides ("the black smartwatch=left wrist"); the engine works out where that side is in each view — the picture's right or left in a front, back or diagonal view, near or far in a side or diagonal view (`placement`) — and says it in the prompts (`text`). `sprite-gen gen --direction <view> [--facing …] --handed …` adds the engine's still view sentence and, per item, which side it is on, where that is in the view, and that the sentence outranks an attached picture; with `--handed`, `--facing-fix mirror` is refused and `regen` never falls back to a mirror. `video-prompt --handed` and `video-set --handed` end the clip prompt with where the item stays, anchored to the first frame and named once where it shows; on the far side of a side view it is not named at all — the near arm "stays bare, exactly as in the image" — since a clip prompt that names a hidden item draws it on the near arm. [docs/video-pipeline.md](docs/video-pipeline.md#handedness--an-item-on-one-side).
diff --git a/SKILL.md b/SKILL.md
index a62fa6a..d6f89b0 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -70,9 +70,9 @@ it never changes the requested direction. Image correction requires explicit opt
| Command option | Values and default | Behavior |
|---|---|---|
-| `gen --facing` | `preserve` (default), `right`, `left` | With `--ref`, an explicit direction adds a prompt requirement and checks the generated still. |
+| `gen --facing` | `preserve` (default), `right`, `left` | With `--ref`, an explicit direction adds a prompt requirement and checks the generated still. With `--direction` the view sentence says the turn and this piece only pins the image edge ([prompt-assembly](docs/prompt-assembly.md)). |
| `gen --facing-fix` | `none` (default), `mirror`, `regen` | Record without correction; opt into mirroring an observed opposite or regenerating once and rechecking. A still-opposite regeneration is mirrored. |
-| `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 --direction` | `side`, `front`, `back`, `front_diagonal`, `back_diagonal`; unset by default | `side` opts into facing inspection and a matching prompt requirement (not repeated on a `video-prompt` prompt, which already says it; refused when that prompt faces the other way); 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 --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. |
@@ -87,7 +87,10 @@ front-facing observations also remain unchanged. Mirroring does not preserve lef
It stays the default, since drawing the left-facing views costs as much again; for a character with a watch on
one wrist or a pin on one side, offer to draw them instead with `--handed` and check them with `handed-check`
(a colour-marked item, frame by frame; `--board` for the eye) —
-[handedness](docs/video-pipeline.md#handedness--an-item-on-one-side).
+[handedness](docs/video-pipeline.md#handedness--an-item-on-one-side). In a side view an item on the far arm
+shows each time that arm swings forward, never hidden for the whole walk: draw that side still mid-stride with
+the far arm out in front of the body and the item in view (`video-prompt` says so under `still_needs`), do not
+hold the arms still, and check the loop with `handed-check --state walk`.
## Execution routes
@@ -113,6 +116,8 @@ one wrist or a pin on one side, offer to draw them instead with `--handed` and c
| Optional scene placement, lighting, camera and render | `scene-render`, `scene-inspect` | [scene](docs/scene.md) |
| Defaults | `defaults show`, `defaults save`, `defaults clear` | [user-workflow](docs/user-workflow.md#one-settings-owner) |
+Say a thing once: what an option says, leave out of the prompt. `--direction`, `--facing`, `--handed`, the key background and `video --direction side` each add their own sentence, in one place that drops what the prompt already has. Your prompt carries the subject, its design and its pose. Text that says the opposite of an option ("facing left" with `--facing right`, the item on the other wrist) is sent as written with a warning (`extra.prompt_notes`, `video-prompt`'s `warnings`): fix the prompt, do not send it — [prompt-assembly](docs/prompt-assembly.md).
+
`gen --transparent` with `--ref` plans a chroma key (adding the key's background line to a prompt that names none), and publishes a result that already came back transparent on its own alpha instead of keying its outline away; `alpha.strategy_source` in the report says which (`refs-attached` keyed, `refs-attached-raw-alpha` not) — [gen](docs/gen.md#transparent-output--strategy-per-provider).
Use existing automatic pipeline stages for background removal, extraction, alignment and export. Do not ask users to select each script. For a direct utility request, run that utility; no unrelated generation questions are needed. Preserve the row pipeline and component extraction for image sprites. One-shot grid generation and fixed cell cutting are not an alternative sprite-generation route.
diff --git a/docs/README.md b/docs/README.md
index a32795a..7be3d1b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -75,6 +75,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| Doc | Owns |
|---|---|
| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage |
+| [prompt-assembly.md](prompt-assembly.md) | What the engine adds to a still or clip prompt, each piece once: the pieces, what counts as already said, what is refused, and the notes on the caller's own words |
| [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing) with the user's own credential |
| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch |
| [loop-review.md](loop-review.md) | Automatic loop decisions, ambiguous gait review, visual evidence and explicit cut/alignment overrides |
diff --git a/docs/gen.md b/docs/gen.md
index 6da86df..54a1fb0 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -220,6 +220,13 @@ Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT
**`--handed`** adds, per item, which of the character's own sides it is on and where that side is in
the view; with it, `--facing-fix mirror` is refused and `regen` never mirrors. See
[video-pipeline](video-pipeline.md#handedness--an-item-on-one-side).
+- **Each engine sentence is said once.** The view, the turn over a reference, the handed item, the
+ key background and the layout guide are attached in one place, which leaves out what the prompt
+ already says: with `--direction` the reference piece no longer repeats the turn, a facing correction
+ replaces the sentence it corrects, and a key background the prompt names gets no second line. Where
+ your own text says the opposite of an option ("facing left" with `--facing right`) it is left as
+ written and stderr warns; the report lists it under `extra.prompt_notes`. See
+ [prompt-assembly](prompt-assembly.md).
## `--quality` and `--resolution` — the two billed knobs
@@ -275,11 +282,15 @@ strategy it can execute, and `--alpha-mode auto` (the default) follows it:
prompt, so the engine adds the `--chroma-key` key's line
(`chroma.KEY_BACKGROUND_TEXT`, the sentence a clip's mid-step redraw also ends on)
to a prompt that names no key, and leaves a prompt that does as it is — no second
- line. A prompt names a key with the key's hex code (`#FF00FF`, `00ff00`) or the
- key's name right before "background", "backdrop", "chroma key", "key" or "screen"
- (`chroma.named_key_background`); a colour in the subject ("a green frog") is not a
- key. A prompt that names the other key is left on it: the matte reads the key off
- the borders. `alpha.key_background` records `{"injected": true|false, "key": …}`,
+ line. A prompt names a key with the key's hex code (`#FF00FF`, `00ff00`), the key's
+ name before "background", "backdrop", "screen" or "chroma key" ("a green screen",
+ "magenta-colored background"), the name after one ("a background of pure magenta"),
+ or "keyed on magenta" / "on a green key" (`chroma.named_key_background`). A colour in
+ the subject ("a green frog", "holding a green key") is not a key, and neither is one
+ the prompt rules out ("no green screen"): that prompt gets the line. A prompt that
+ rules out the very key `--chroma-key` chose is refused before the model runs — pass
+ the other key. A prompt that names the other key is left on it: the matte reads the
+ key off the borders. `alpha.key_background` records `{"injected": true|false, "key": …}`,
stderr says which, and the report's `prompt` is the prompt sent. Without the line a
reference on white came back on opaque white (3/3, 2026-10-04) and keying white took
the outline and the cream fills with it. With it (the same prompt otherwise, three
diff --git a/docs/prompt-assembly.md b/docs/prompt-assembly.md
new file mode 100644
index 0000000..ff5defb
--- /dev/null
+++ b/docs/prompt-assembly.md
@@ -0,0 +1,100 @@
+# Prompt assembly — the caller's text, then the engine's pieces, each said once
+
+A prompt the engine sends is the caller's own text and then the engine's sentences. Every engine
+sentence is a **piece** with a topic, and every piece goes on through one place
+(`sprite_gen/gen/prompt_parts.py`, `Prompt.add`). That place checks what the prompt already says, so
+a piece is not said twice and two pieces do not disagree. The caller's text is never edited.
+
+## The pieces
+
+**A still** (`sprite-gen gen`, `gen.still_prompt`), in this order:
+
+| Piece | When | Sentence from |
+|---|---|---|
+| the caller's text | always | `--prompt` / `--prompt-file` |
+| view | `--direction` | `batch.still_view_text` |
+| handed | `--direction --handed` | `handedness.text` |
+| facing | `--ref` with `--facing` | `facing.prompt_suffix` |
+| key background | `--transparent --ref` when `auto` plans a key | `chroma.KEY_BACKGROUND_TEXT` |
+| layout guide | `--layout-guide` | `gen.layout_guide_text` |
+
+With `--direction`, the view sentence says the turn, so the facing piece says only what it does not:
+"Left here means toward the left edge of the image, regardless of the reference image's
+orientation. Preserve the subject's design." Without `--direction` it says the turn itself ("The
+subject must be facing left (toward the left edge of the image), …"). Said after a three-quarter
+view sentence, that full-profile wording asked for a different turn than the view's 45 degrees.
+
+A facing correction (`--facing-fix regen`) regenerates with the facing piece **replaced** by its
+correction ("CORRECTION REQUIRED: …"), said last. It is not added after the sentence it corrects.
+
+**A clip** (`video-prompt`, `video-set`, `batch.clip_prompt_parts`):
+
+| Piece | When | Sentence from |
+|---|---|---|
+| motion | always | the state's own (`MOTION_TEXT`, `VIEW_MOTION_TEXT`), or the caller's `--motion` |
+| hold, gait hold, repeat | a caller's `--motion` | `HOLD_TEXT`, `GAIT_HOLD_TEXT`, `REPEAT_TEXT` |
+| view, frame, camera, background, design, rhythm | always | `VIEW_TEXT` in `COMMON_TEXT` / `PINNED_LOOP_TEXT` / `ACTION_COMMON_TEXT` |
+| Lite walk, Lite head | a Lite model's walk | `LITE_WALK_TEXT`, `LITE_HEAD_TEXT` |
+| handed | `--handed` | `handedness.text(clip=True)` |
+| side view | `sprite-gen video --direction side` | `video.side_view_prompt` |
+
+The walk paragraph says a thing once too. That a gait does not move across the screen is the frame
+sentence's ("does not move across the screen"); the side and diagonal gait sentences and holds no
+longer add "without moving across the screen". A walk or run seen from the front, from behind or at
+a diagonal says its view in the gait sentence or hold ("facing the viewer", "keeps the exact
+three-quarter back angle of the image"), so the view sentence is left out of its prompt
+(`batch.GAIT_SAYS_VIEW`); a side gait keeps the view sentence, which carries the facing.
+
+`video --direction side` holds the side view ("The subject stays in exact side view, facing left. No
+turning around.") only for a prompt that does not say it already: a `video-prompt` or `video-set`
+prompt does ("seen from the exact side, facing left") and is sent as it is.
+
+The handed piece of a clip is one sentence per wrist (or other part), not per item: two items on one
+wrist share it, and with an item on each wrist neither sentence calls the other wrist bare. In a
+side view's walk or run it says the far arm's item shows each time that arm swings forward
+([handedness](video-pipeline.md#handedness--an-item-on-one-side)).
+
+**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.
+
+## What "already said" means
+
+- **The same sentence.** A sentence the prompt already carries, word for word, is dropped from the
+ piece. A start-still prompt handed back to `gen --direction --handed` keeps one copy of the handed
+ sentences; a `--motion` paragraph that quotes an engine rule ("Camera completely locked, …") is
+ not followed by the rule again.
+- **The same topic** (`prompt_parts.ALREADY_SAID`). A key background the prompt names leaves the key
+ line out. It is read from the hex code (`#FF00FF`, `00ff00`), the key's name before "background",
+ "backdrop", "screen" or "chroma key" ("a green screen", "magenta-colored background"), the name
+ after one ("a background of pure magenta", "background: solid green"), or "keyed on magenta" /
+ "on a green key" (`chroma.named_key_background`). A colour in the subject is not a key ("a green
+ frog", "holding a green key"), and neither is one the prompt rules out ("no green screen",
+ "without a magenta background").
+- **The opposite, in the engine's own words, is refused** before anything is generated: a prompt
+ that rules out the key the engine would ask for ("no green screen" with `--chroma-key green`), and
+ a clip prompt that says the side view faces one way sent to `video --direction side --facing` the
+ other.
+
+## The caller's own words
+
+The engine cannot tell which of two statements the caller meant, so it reports and does not edit:
+
+| The text says | The option says | Result |
+|---|---|---|
+| "facing left", "walks to the left" | `--facing right`, or a front or back view | a **conflict**: a warning on stderr |
+| "a black smartwatch on its right wrist" | `--handed "the black smartwatch=left wrist"` | a **conflict**: a warning on stderr |
+| "facing right" | `--facing right` | a **repeat**: a note that it is said twice |
+| "a black smartwatch on its left wrist" | the same `--handed` | a **repeat**: a note |
+
+`gen` prints them as `[gen] warning: …` / `[gen] note: …` and records them in the report's
+`extra.prompt_notes`. `video-prompt --json` puts conflicts in `warnings` and all of them in `notes`.
+`video-set` records them per item as `prompt_notes`.
+
+## The check
+
+`tests/gen/test_prompt_assembly.py` draws every prompt in the option table as text, with no
+generation: five views, both facings, no item / one / two on one wrist / one on each wrist, a
+caller's text that names the key, the turn or the item's side or does not, every state, both clip
+models, a caller's own motion, the facing correction, the start still and the hand-offs between
+verbs. Each prompt is checked for a sentence said twice, words that turn the subject both ways, and
+more than one key background. A new option is a new row in that file's tables.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 13ad1be..dea0dfd 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -131,8 +131,10 @@ the default is generic on purpose, because how a character walks (high steps, a
march) is the caller's to say. The front run keeps its sentence.
Since 2.16.0 every walk and run takes that form, from every view: the side walk "walks
-naturally in place, as if on a treadmill, without moving across the screen" (it said "moves in
-place on a treadmill" as a place and asked for "an even left-right or front-back rhythm"), the
+naturally in place, as if on a treadmill" (it said "moves in place on a treadmill" as a place
+and asked for "an even left-right or front-back rhythm"; until 2.22.0 it also ended "without
+moving across the screen", which the frame sentence says — "does not move across the screen" —
+so a side or diagonal gait no longer says it a second time), the
side run "runs naturally in place …", and the front and back runs "runs naturally in place,
facing (away from) the viewer, as if on a treadmill …" (the front run spelled its strides out
and said "toward the viewer" and "without coming any closer" in one clause). On one character,
@@ -144,12 +146,16 @@ right, the way an isometric game's character walks down and up to the right (tur
left; a character with an item on one side has them drawn facing left instead, see
[handedness](#handedness--an-item-on-one-side)). A walk or run in one says where it heads on the screen in those words: "walks naturally in
place, as if on a treadmill, heading diagonally away from the viewer toward the upper right, like a
-character walking up and to the right in an isometric game, without moving across the screen. It
+character walking up and to the right in an isometric game. It
keeps the exact three-quarter back angle of the image the whole time: its back stays turned toward
the viewer at that angle and its face stays hidden. It never turns into a side view." (and "toward
the viewer and to the right … three-quarter front angle" for the front one). It is filmed pinned to
its first frame (`PINNED_GAIT_VIEWS`, `pins_last_frame`) with the return sentence, and cut as any
-walk (`--anchor motion-auto`). The clip's view sentence points at the image ("seen from a
+walk (`--anchor motion-auto`). The view is said once: a walk or run seen from the front, from behind
+or at a diagonal says it in the gait sentence ("facing the viewer", "keeps the exact three-quarter
+back angle of the image"), so its prompt leaves the view sentence out (`GAIT_SAYS_VIEW`); a side gait
+keeps it ("The character is seen from the exact side, facing right."), and so does every other state,
+whose view sentence points at the image ("seen from a
three-quarter back angle, turned exactly as in the image"); a still drawn at a diagonal from another
picture takes `STILL_VIEW_TEXT` instead (`still_view_text`), which says the whole body and head turn
about 45 degrees and which way the feet point — told less, a three-quarter back view came out as a
@@ -212,7 +218,8 @@ paragraph — whole sentences about the subject, such as a request interpreter w
request — in place of the built-in state sentence. The frame, camera, background and design
rules stay the engine's, and an attack keeps its `HOLD_TEXT` sentence after the paragraph. A
walk or run gets `GAIT_HOLD_TEXT` for its view after the paragraph instead: it stays in place as
-if on a treadmill and keeps facing the viewer, away from the viewer or `{facing}` the whole time,
+if on a treadmill and keeps facing the viewer or away from the viewer the whole time (a diagonal
+keeps the image's angle; a side view's facing is its view sentence's, said once),
so a caller describes the gait (a sneak, a march, a lazy stroll) and the engine keeps it on the
spot. On one character, one clip each: a march lifted the knees high as asked and stayed in
place, a lazy stroll seen from behind kept facing away, and a tiptoe sneak kept facing the viewer
@@ -270,6 +277,11 @@ sprite-gen video-frames --clip item/clip.mp4 --out-dir item/frames --spill auto
sprite-gen video-loop --frames-dir item/frames/keyed --out-dir item/loop --fps 24 --state walk --cycle auto --facing right --name side-walk
```
+The prompt is sent as printed. `sprite-gen video --direction side` does not add its side-view hold to
+it (it already says "seen from the exact side, facing right"), and refuses it when `--facing` is the
+other way. `--character` or `--motion` words that turn the subject another way than `--facing`, or put
+a `--handed` item on its other side, come back in `warnings` ([prompt-assembly](prompt-assembly.md)).
+
`video-prompt --json` also gives the duration (the state's own, as `video-set`), whether the clip
ends on the canvas (`last_frame`), the loop cut (`cycle`) and these commands with placeholders; a
front or back walk adds `start_still`, the mid-step redraw `video-set` makes before its canvas
@@ -317,26 +329,55 @@ middle of the body — only near and far.
**The still.** `sprite-gen gen --direction <view> [--facing right|left] --handed …` adds the engine's
view sentence (`still_view_text`, the one a diagonal or front still is drawn with) and, per item, the
handedness sentence (`handedness.text`): the item is on the own left wrist only and the right wrist has
-none; where that wrist is in this view (at the picture's right, on the far side; or, facing right,
-behind the body, hidden or a sliver); and that these sentences decide the side whatever an attached
-picture shows. A side or diagonal view needs `--facing`, a front or back view takes none. With
-`--handed`, `--facing-fix mirror` is refused and `regen` never falls back to mirroring a still-opposite
-retry: a mirror moves the item. Do not attach a picture whose item is on the other side — a mirrored
-still, or a side picture drawn the wrong way: check it with `handed-check` first. A front or back
-picture, where the item's side is plain, is the safe reference.
+none; where that wrist is in this view (at the picture's right, on the far side); and that these
+sentences decide the side whatever an attached picture shows. A side or diagonal view needs `--facing`,
+a front or back view takes none. With `--handed`, `--facing-fix mirror` is refused and `regen` never
+falls back to mirroring a still-opposite retry: a mirror moves the item. Do not attach a picture whose
+item is on the other side — a mirrored still, or a side picture drawn the wrong way: check it with
+`handed-check` first. A front or back picture, where the item's side is plain, is the safe reference.
+
+**The far arm of a side view.** A side view hides the far side behind the body, except for what swings
+out from behind it: an arm or a leg (`handedness.limb` reads the body part — wrist, hand, arm, ankle,
+foot, …). A walking character's far arm comes forward of the body with every step, and what it wears
+shows then. So an item on a far limb is said to show wherever that limb is out in front of the body
+and to be hidden where the body covers it; a far part that does not swing (a pin on the far side of
+the head) is still said hidden. 2.22.0 said every far item hidden and never named it in the clip, and
+a watch on the far wrist was then in no frame of the side walk.
+
+A clip keeps what its first frame shows and makes up what it hides. For a walk or run with an item on
+the far arm, draw the side still **mid-stride with both arms in view**, and say the pose in your
+prompt — the engine's sentence says where the item shows, not how the character stands:
+
+> caught in the middle of a walking stride: the far arm swings forward, its forearm and hand out in
+> front of the chest, clear of the body's outline, with the watch on that wrist in plain sight; the
+> near arm swings back past the body and shows whole
+
+`video-prompt --json` names this under `still_needs` (and on stderr), and `video-set` under each
+item's `still_needs`, whenever a walk or run has an item on the far limb of a side view.
**The clip.** `video-prompt --handed …` and `video-set --handed …` end the clip prompt with where the
item stays (`build_prompt(handed=...)`). The clip starts from a still already drawn with the item in
place, so the sentence anchors to the image and names the item once, positively, where it shows: "The
-black smartwatch stays on the wrist at the right of the picture, nearer the viewer for the whole clip,
-exactly as in the image, and on no other wrist." Where the item is hidden — the far side of a side
-view — the item is not named at all: "The wrist in front of the body stays bare, exactly as in the
-image, for the whole clip." A clip prompt that names a hidden item, and lists what the near arm must
-not wear, draws it on the near arm. A far arm that swings into view can still grow a bare band in a
-near-side view; holding the arms still (`--motion`) is the caller's choice, and `handed-check --strap`
-finds it. A front or back walk's mid-step redraw (`walk_start_prompt`, `video-prompt`'s `start_still`)
-ends with the still's handedness sentences too: redrawn from the base alone, the model may put the item
-on the other wrist.
+black smartwatch stays on the wrist at the right of the picture, nearer the viewer, for the whole clip,
+exactly as in the image, and on no other wrist." In a side view's walk or run the arms are said to
+swing ("Both arms swing back and forth with each step, opposite to the legs."), and then:
+
+- on the far arm: "The black smartwatch stays on the wrist that wears it in the image, on the arm on
+ the far side of the body, and shows each time that arm swings forward; the arm nearer the viewer
+ stays bare, exactly as in the image."
+- on the near arm: "The black smartwatch stays on the wrist that wears it in the image, on the arm
+ nearer the viewer; the other arm, on the far side of the body, stays bare both where it shows behind
+ the body and where it swings out in front of it."
+
+No sentence holds an arm still: the arms swing with the walk. The other arm is said bare, never as a
+list of what it must not wear — a clip prompt that lists that draws it there. Where nothing brings the
+far side into view — a part that does not swing, or a state that does not step (idle, attack) — the
+item is not named at all: "The wrist in front of the body stays bare, exactly as in the image, for the
+whole clip." Items on the same wrist share one sentence, and with an item on each wrist neither is
+called bare. `handed-check --strap` finds a bare band that a clip still grows on the other arm. A front
+or back walk's mid-step redraw (`walk_start_prompt`, `video-prompt`'s `start_still`) ends with the
+still's handedness sentences too: redrawn from the base alone, the model may put the item on the other
+wrist.
**Left-facing views, drawn.** `video-set --facing right,left` films every side and diagonal view both
ways, each from its own still: `--base side@right=E.png --base side@left=W.png --base
@@ -349,7 +390,7 @@ left-facing diagonal is canvassed, prompted ("heading diagonally toward the view
and cut (`video-loop --facing left`) as a left one. One facing keeps the item names and table as before.
**The check.** `sprite-gen handed-check --strip <loop>.strip.png --direction <view> [--facing …]
---handed … --marker '#RRGGBB'` (or `--image`, `--frames-dir`) finds the item by a saturated colour
+[--state walk] --handed … --marker '#RRGGBB'` (or `--image`, `--frames-dir`) finds the item by a saturated colour
nothing else on the character has — a watch's screen — and checks every frame:
- a view with a picture side: every blob of that hue is on that side of the body's centre (the mean x
@@ -357,14 +398,22 @@ nothing else on the character has — a watch's screen — and checks every fram
- every view: the item in at most one place (blobs within 2 % of the body height are one; one smaller
than a quarter of the largest is a speck — a clip's colour blocks tint outlines toward the item's
hue — recorded and drawn, not judged);
-- the near side of a side or diagonal view: the item shows in at least half the frames — in a side view,
- against `--reference`, as more than a sliver (its largest blob larger than half the item seen whole):
- a side view has no picture side, so a far sliver turned over must not count as the near item shown;
-- the far side of a side view: no blob larger than half the item seen whole on `--reference` (a keyed
- front or back picture).
-
-Without `--reference` neither side-view size rule is checked; the report says so (`far_hidden` /
-`near_whole`: `checked: false`) and a near frame counts as shown by any blob.
+- the near side of a diagonal view: the item shows in at least half the frames; of a side view, in at
+ least three quarters — a near arm is in view the whole walk, a far arm's item for the half of it the
+ arm is forward, and in a side view that share is what tells the two apart. Against `--reference` a
+ frame counts only when the item is more than a sliver (its largest blob larger than half the item
+ seen whole);
+- the far side of a side view, an item on an arm or a leg: every blob is out in front of the body —
+ on the facing side of the body's centre by at least a tenth of the body's height (`far_in_front`).
+ An item that shows at or behind the centre is on the near limb, the wrong one. With `--state walk`
+ or `run` it must also show in at least a quarter of the frames (`far_shown`); without `--state`, or
+ for a state that does not step, that is reported unchecked. Against `--reference` a sliver is not
+ judged for where it is;
+- the far side of a side view, an item that does not swing: no blob larger than half the item seen
+ whole on `--reference` (a keyed front or back picture; `far_hidden`).
+
+Without `--reference` the size rules are not checked; the report says so (`far_hidden` /
+`near_whole`: `checked: false`) and a frame counts as shown by any blob.
`--strap '#RRGGBB' --zone TOP,BOTTOM` adds the item's band seen without its marker: pixels of that
colour in those rows of the body (fractions of its height), eroded so outlines drop out, wider and
@@ -375,10 +424,11 @@ expected, red not) and bands boxed, for what pixels cannot judge: an unmarked it
the wrong hand. The exit code is 1 on a failure.
A set that made its left-facing views by mirroring fails: a front view turned over puts the item on
-the wrong side; a side view facing right (item hidden on the far arm, or a sliver of it) turned over
-hides it, or leaves the sliver, on the near arm — the sliver is caught against `--reference` only; a
-diagonal turned over moves it across the picture. `tests/qa/test_handed_check.py` draws each view as it
-should look, passes it, and fails it turned over.
+the wrong side; a side walk facing right (the item on the far arm, in view while that arm is forward)
+turned over shows it in too few frames for a near arm; one facing left (the item on the near arm,
+crossing the body) turned over shows it behind the body's centre; a diagonal turned over moves it
+across the picture. `tests/qa/test_handed_check.py` draws each view as it should look, passes it, and
+fails it turned over.
## 3. Frames — extract, key, check the edges