spritegen-cli 0.1.0__py3-none-any.whl

spritegen/skill/files/SKILL.md

@@ -0,0 +1,553 @@
+---
+name: spritegen
+description: Generate sprite resources for the game with the spritegen CLI — item icons, HUD pieces, box art, single sprites, character anchors, and full animated character sheets (walk, idle, attack). Use it whenever art has to be generated for the game, when someone asks for a sprite, an icon, a portrait or an animation, when a half-finished asset needs picking up again, and before spending on any fal image or video call, because every paid call here is recorded.
+argument-hint: [what to generate, e.g. iron sword icon | female warrior walk cycle]
+allowed-tools: Bash(spritegen *)
+---
+
+# spritegen
+
+Asked for: $ARGUMENTS
+
+A generator for the game's sprite resources: one image at a time for anything static, or a
+whole pipeline for anything animated. Everything belonging to one asset lives under
+`assets/<name>/`, and no stage takes an input or an output path — that is what lets
+`status` say what comes next and what lets a stage refuse to run out of order.
+
+## Running it
+
+```
+spritegen --help
+spritegen status
+```
+
+It needs `FAL_KEY`. Export it, or put it in a `.env` at the working directory or above —
+an exported variable wins over the file.
+
+Assets go in `assets/` under the working directory, so run every command from the same
+place or set `SPRITEGEN_ASSETS` to say where they live. `status` reads that directory: it
+gives every asset, the stage that completed last, and the stages that could run now.
+
+**If nobody named an asset, resume the one in the middle rather than opening a new one.**
+If there is no half-finished asset, ask what to generate instead of choosing.
+
+## What a sprite's workspace holds
+
+Everything about one sprite is under `spritegen/assets/<sprite>/`, in directories named
+after **what the thing is** rather than after the stage that made it:
+
+```
+prompts/    anchor.v1.md  anchor.v2.md  video.v1.md
+box-art/    anchor/  icon/
+frames/     cutout/
+sheet/as-is/  sheet/sharp/  sheet/pixel-art/
+```
+
+Box art and the anchor belong to the same sprite, so they live in the same directory —
+`anchor --kind box-art` rather than a second asset. The same sheet closed in two art
+directions is two directories under `sheet/`, and **neither of them is the sheet**.
+
+**`spritegen show <sprite>`** answers what exists, where, and which prompt version made
+it, without opening a directory. `--json` is the same answer for a program.
+
+**Prompts are kept and versioned.** The text is copied into the sprite before the paid
+call, so a `--prompt-file` from outside cannot be edited out from under the record. The
+same text twice is one version; an edit is a new one and the old text stays.
+
+## Pick the route before spending anything
+
+| What was asked for | Route |
+|---|---|
+| An item icon, a HUD piece, a single static sprite | `anchor --kind icon`, and stop |
+| Box art, concept art, a look to settle before a character exists | `anchor --kind box-art`, then feed it to the anchor as `--ref` |
+| A character that has to move: walk, idle | the pipeline — `anchor`, then `motion` or `video`, `matte`, `board` |
+| A movement that starts somewhere the anchor is not: attack, cast, death | the same, with `pose` between the anchor and the movement |
+
+All of them are the same stage writing into different directories of the same sprite. The
+difference is what the image is for, and whether anything runs after it.
+
+## The pipeline
+
+<!-- generated: stages -->
+
+`motion` and `video` are alternatives: both hand frames to `matte`, which takes whichever
+of them completed most recently. **Prefer `motion`** — its movement comes from a reference
+sheet that has already been measured, where `video` asks a model to invent a cycle. The
+number is under *Movement* below.
+
+## Generate cheap, finish local
+
+This is the whole cost strategy, and it is why the defaults look low.
+
+**A paid call buys composition and identity. It does not have to buy resolution or a
+clean edge**, because both of those are local now:
+
+- **`spritegen upscale <sprite>`** enlarges an artifact with Real-ESRGAN on this machine.
+  Free, no ledger line, and the original is kept as `<name>.raw.png` so a second run
+  starts from it rather than compounding the model's invention twice.
+- **`matte --backend local`** cuts the background with BiRefNet through `rembg` — the same
+  family of model the paid endpoint runs, on the GPU, for nothing. It is the default.
+
+So `anchor --quality low` and `video --resolution 480p` are the defaults on purpose. Take
+the cheap tier, then enlarge. Both local steps need an optional extra
+(`spritegen-cli[upscale]`, `spritegen-cli[matte]`) and say so when it is missing.
+
+## Before you spend
+
+The remaining paid stages are `anchor`, `motion` and `video`, and they are not cheap.
+
+1. **Say what the first paid call costs and what it decides, before making it.** On the
+   pipeline route the anchor is the extreme case: identity comes from that one image, so an
+   anchor that came out wrong wastes every call after it. Show it and get agreement before
+   running `motion`.
+2. **`--dry-run` first, on any paid stage.** It prints the exact payload and spends
+   nothing. It also cannot advance an asset, so a dry run leaves `status` untouched.
+3. **`spritegen cost <asset>`** says what has been spent already, read from that
+   asset's `ledger.jsonl` and nothing else — still right for an asset whose files were
+   deleted.
+
+`board` and `upscale` are free and local, and `matte` is free on its local backend. A row
+that came out wrong costs nothing to rebuild from frames that were paid for once, so
+re-run `board` with a different `--scale`, `--grid` or `--art` rather than regenerating
+anything.
+
+---
+
+# Route one — a single image
+
+`anchor` is a general image stage: a prompt, optional references, a flat background cut to
+alpha, and the native pixel grid recovered afterwards. An item icon *is* one `anchor` call.
+So is a HUD piece, a portrait, or box art. Open the asset, run one stage, stop — `status`
+will keep offering `motion` and `video`, and for a static asset there is nothing to run.
+
+```
+spritegen new iron-sword
+spritegen anchor iron-sword --kind icon --prompt-file sword.md --transparent --pixelart --count 4
+```
+
+**Generate large and let `--pixelart` bring it down.** The endpoint refuses anything under
+about 655,000 pixels and rounds each side to a multiple of 16, so a 64 px icon cannot be
+asked for directly. Ask for `1024x1024`, describe the icon as drawn at a small native
+resolution, and let `--pixelart` recover that grid. `--scale` then upsizes by an integer
+factor with no resampling.
+
+**Cut the background, do not hope for transparency.** `--transparent` puts the chroma field
+in the prompt and cuts it to alpha afterwards. `--chroma` defaults to `00b140`, chroma
+green, far from skin, steel, fire and stone; change it if the subject is green, and say in
+the prompt that nothing in the subject uses that colour. `--chroma-mode flood` takes only
+what the border reaches, which is what keeps an enclosed hole — the ring of a hilt, a
+window in a HUD frame — from being punched out; `global` takes the key anywhere.
+`--despill` pulls the leaked key out of edge pixels.
+
+**`--count 4` is four candidates for one prompt.** The cheapest place in the whole tool to
+be picky.
+
+What changes between the kinds:
+
+| `--kind` | Size | Pixel grid | Background |
+|---|---|---|---|
+| `icon` — item, HUD piece | square, one object, centred, filling the frame | `--pixelart`, small native resolution | `--transparent` |
+| `anchor` — a sprite | square or portrait | see route two; usually **no** `--pixelart` | `--transparent` |
+| `box-art` — illustration | large, `landscape_4_3` or `portrait_4_3` | **no** `--pixelart` — it is not a sprite | keep the scene; it is art, not an asset |
+
+**`--pixelart` here recovers a grid the art already has.** It is right for an icon drawn
+as flat blocks and wrong for anything else — on a smooth render the detector votes on
+nothing and returns nonsense. The report's `cols` and `rows` are how you check a grid was
+there at all.
+
+Box art is worth one image before a character exists: it settles the silhouette, the
+palette, which shoulder the scabbard is on, what the hair does — things a 166 px sprite is
+too small to argue about. Then it becomes the character's identity reference.
+
+---
+
+# Route two — an animated character
+
+## 1 · The anchor — the one image everything else inherits
+
+The character, once, standing still. Every later stage animates *this image*, so identity
+is decided here and nowhere else.
+
+- **Neutral, facing south.** Straight at the camera, weight even, both feet planted and
+  flat, arms down. No swing, no cast, no spell lit, no weapon raised. A pose-driven
+  endpoint reads the anchor as the rest state it deforms from; an anchor caught mid-swing
+  puts that swing into every frame of the walk.
+- **The weapon hangs clear of the body**, down along the side and angled out, whole blade
+  visible, crossing no part of the figure. A blade drawn across the torso merges with it at
+  166 px and the matte cuts them out as one shape.
+- **Fill the frame, feet to hair.** The row stage scales the whole set by one transform read
+  from the box that holds every frame, so a figure sitting small in its frame arrives small
+  in the sheet cell.
+### Do not ask for pixel art here
+
+This is the change that matters most, and it goes against the obvious instinct.
+
+**The anchor is a clean, sharp render in the target art direction — not pixel art.** Ask
+for flat blocks and you get an anchor a video model cannot animate: it deforms blocks
+rather than a drawing, and what comes back is six similar characters instead of one
+character moving. It was measured — an anchor at 23 colours in ~7 px blocks produced a
+walk that did not hold together, and the same figure rendered sharp did.
+
+The second reason is that a target's own sheet is usually not blocky either. A 166 px
+cell can carry thousands of colours and a real anti-aliased edge; "pixel art" is one art
+direction among several, and the tool supports it as a direction rather than assuming it.
+
+So ask for **the game's proportions and palette discipline, rendered crisply**: hard
+readable silhouette, flat-ish shading in a few steps, no photographic depth of field, no
+soft glow, no film grain — but a normal sharp raster, not blocks on a grid. Generate large
+(`1024x1024`), at `--quality low`, and let the local upscale and the local matte do the
+finishing.
+
+**Pixel art, if the project wants it, is decided at the end and locally.** `board --art
+pixel-art` recovers a grid; `board --art sharp` lands the crisp render on the cell. Both
+are free, both are re-runnable, and both can exist for one sprite at the same time.
+
+```
+spritegen anchor <character> --kind box-art --prompt-file boxart.md --quality low
+spritegen anchor <character> --prompt-file anchor.md --ref <sprite>/box-art/box-art.png     --transparent --count 4
+spritegen upscale <character> --artifact anchor --scale 2
+```
+
+## 2 · The four directions
+
+Outfits are usually drawn south, west and east, with west being east mirrored. The anchor
+is south; the others are anchors of their own, one asset each, taking the south anchor as
+their identity reference:
+
+```
+spritegen new <character>-east
+spritegen anchor <character>-east --prompt-file east.md \
+    --ref <assets>/<character>/anchor/anchor.png
+```
+
+Each prompt says only what changed: the same character, seen from the east, the same
+palette and proportions. **Do not try to turn a character with `motion`** — a pose-driven
+endpoint moves the figure, it does not rotate it.
+
+**West is east flipped, and that is where asymmetry bites.** A scabbard on one hip, a single
+bracer, a braid over one shoulder, the hand holding the weapon — flipping moves every one of
+them to the wrong side. Fix them after the flip, or generate west as its own anchor. In
+motion nobody sees which hip the sword is on; everybody sees it swap hips between two
+directions.
+
+## 3 · `pose` — where an animation starts, when the anchor is not it
+
+**Skip this for a walk or an idle.** The anchor already is where those start, and a pose
+would be a paid call for an image you have.
+
+Reach for it when the movement begins somewhere the anchor is not: an attack begins with
+the weapon already drawn back, a cast with the hands already raised. Asking a video model
+to introduce the weapon *and* the movement in one call asks for two things, and identity
+is the one that gets dropped — the character comes back holding a different sword.
+
+```
+spritegen pose <character> --animation attack --prompt-file attack_start.md --transparent
+spritegen video <character> --pose attack --prompt-file swing.md --model seedance
+```
+
+- **One pose per animation**, in `pose/<animation>/`. The anchor is always its first
+  reference, which is what keeps the character the same character. **`status` offers
+  `pose` once and then stops**, because how many animations a sprite wants is unbounded
+  and it could never say "complete" otherwise — make another whenever you need one, and
+  `show` lists the ones that exist.
+- **The last frame is the first, copied.** `end.png` is `start.png` unless you pass
+  `--end-prompt`, because a cycle that ends where it began is the ordinary case and a
+  second paid call for the same image buys nothing but drift between the two ends.
+  `--no-end` for a movement that does not return — a death. On such a pose, `--loop` on
+  the video still means what it always meant, and closes the clip on the start frame.
+- **`video --pose` sends both ends.** `start.png` as the first frame, `end.png` as the
+  last where the endpoint takes one, which is what `--loop` was approximating with the
+  anchor. `motion --pose` uses the start frame as the image the movement is applied to;
+  there is no last frame there, because a pose-driven endpoint deforms one image.
+
+## 4 · Movement
+
+**Use `motion`.** It builds a clip locally out of a reference sheet the project already
+has and hands it to a pose-driven endpoint together with the anchor: identity from the anchor,
+movement from the clip — movement that was measured rather than invented.
+
+```
+spritegen motion <character> --sheet <path>/<reference_sheet>.png --row 1 --frames 6
+```
+
+`--row` is an animation, and the sheet says which is which: the JSON written beside it lists
+`animations[]` with a `row`, a `name` and a step count. Read it rather than guessing: which
+row holds which animation is the sheet's business, not a convention to assume.
+
+`--frames` is how many frames come out. **Match the reference sheet, not a tutorial's
+advice**: a six-step row is six frames, and `board --grid 3x2` closes them. `--pick
+0,4,9,14,19,24` names exact indices when the even sample lands badly; `--start` and `--end`
+narrow the window it samples from.
+
+**Why not prompt an image model for the grid of frames.** That is the natural thing to try,
+and it was tried: asking for a 3x2 grid of walk frames moved the head-and-torso region 0.25
+between steps against 0.11 for the reference sheet, because the model redraws the character
+in every cell instead of moving it. The result reads as six similar characters rather than
+one character walking. There is deliberately no stage for it.
+
+**`video` is the fallback and the most expensive call here** — billed by second of output.
+Reach for it when there is no sheet row for the movement: an attack, a cast, a death.
+Keep it in place and say so, say no camera movement, close the cycle where it began —
+`--pose` when the movement starts somewhere the anchor is not, `--loop` when it does not, and remember that an image-to-video clip's first frame is the input image standing
+still — start the sample after it rather than at `0`.
+
+## 5 · `matte` — cutting the background
+
+Segmentation, not a colour key: a chroma cut decides by distance to one colour, so it eats
+art wherever the subject is near that colour and leaves halo wherever the key painted over
+a thin contour. Hair is the worst of it — a strand is thinner than the tolerance band.
+
+**`--backend local` is the default, and it costs nothing.** It runs BiRefNet through
+`rembg` on this machine, which is the same family of model the paid endpoint runs. On a GPU
+it is not slower; on a CPU it is, and it says so. Each frame is cut at its own full size,
+with one session shared across all of them — which is where the single consistent edge
+decision comes from.
+
+`--backend fal` is the paid endpoint, for a machine with neither the extra nor a usable
+GPU. There, every frame is joined into one image and cut in a single call, then taken back
+apart: one charge instead of six, and one edge decision instead of six. What it costs is
+resolution, because the endpoint operates at a fixed size. `--no-join` undoes that, at six
+times the price.
+
+Either way, edge decontamination is on and is what kills the coloured halo; if the figure
+is losing its own outline instead, `--no-refine`.
+
+## 6 · `board` — closing it into a sheet row
+
+Free, local, and the stage to re-run rather than regenerate.
+
+```
+spritegen board <character> --grid 3x2 --frames 6 --art sharp
+```
+
+**`--art` is the direction, and it is also the directory.** Three of them, and none is a
+weaker version of another:
+
+| `--art` | What it does | When |
+|---|---|---|
+| `sharp` | Lands the crisp render on the cell: reduces by the exact fraction that fits, then cuts the matte's smear off the alpha without making the outline binary | the art-direction anchor above — **this is the usual one** |
+| `pixel-art` | Recovers a native grid the art already has and rewrites the frames on it | art that is genuinely blocky already |
+| `as-is` | Neither | the art arrived in the direction it was wanted in |
+
+Each writes `sheet/<direction>/`, so one sprite can carry more than one and you can look
+at them side by side. `--colors N` quantises, over the whole row at once.
+
+Three things it does that matter, each a way the animation breaks otherwise:
+
+- **One grid and one palette over the whole row at once**, never per frame. Frame by frame,
+  each cell lands on its own and the sprite flickers.
+- **Cells cut by the declared grid, not by islands of alpha.** The frames arrived in equal
+  cells; finding each figure by its alpha would lose where it sits inside its cell — and
+  where it sits *is* the movement.
+- **One transform for the whole set.** Scale and offset come from the box holding every
+  frame, applied equally. Anchoring each frame on its own pushes the rising frame back down
+  and the walk stands still.
+
+Cells are `--cell` px square, 166 by default. Under `sharp`, a figure larger than the cell
+comes down to it; under the others it does not, and `warning: does not fit the cell` means
+giving a smaller `--scale` or passing `--fit`. **Watch the GIF it writes beside the row** —
+a slide, a hitch or a limb popping shows up in the loop and not in the still.
+
+## 7 · Afterwards
+
+The row is a sheet row, and that is where this tool stops. Packing it into an atlas and
+getting it in front of a player belongs to the project the row is for; so does building the
+reference sheet `motion` drives from. Both are upstream or downstream of spritegen rather
+than stages of it.
+
+---
+
+# When it comes out wrong
+
+| What you see | Where it came from |
+|---|---|
+| The animation is six similar characters, not one moving | a pixel-art anchor. Generate the anchor sharp and take the pixel art at `board --art` |
+| `board --art pixel-art` returned nonsense, `native` looks wrong | there was no grid to recover; the art is smooth, so `--art sharp` is the one |
+| The icon came back at the wrong size | the endpoint's minimum area; generate large, recover the grid with `--pixelart` |
+| A hole in the subject was punched out | `--chroma-mode global`; use `flood`, which takes only what the border reaches |
+| A coloured fringe | the chroma leaked into the edge; `--despill`, and check the subject never uses that colour |
+| Halo around a matted figure | matte edge refinement; leave it on, and check the chroma |
+| A dark rim after `upscale` | should not happen — the transparent RGB is filled before the network sees it. Report it |
+| The character changes between frames | a grid prompt instead of `motion`, or `matte`/`board` run per frame |
+| It flickers | the grid or palette was applied per frame; re-run `board` over the whole set |
+| It slides instead of walking | the movement was not in place — a `video` prompt that let the camera or the figure travel |
+| The figure is tiny in its cell | the anchor did not fill its frame |
+| It does not fit the cell | `--art sharp`, or `--fit`, or a smaller `--scale` |
+| The sword changed hips | a mirrored direction with an asymmetric prop |
+| The attack starts from a neutral stance | no `--pose`; the clip began at the anchor |
+| The weapon appears out of nowhere in frame one | the video call was asked to introduce the weapon and the movement at once. Generate the pose first |
+| The clip does not return to where it started | the endpoint takes no last frame, or the pose was made with `--no-end` |
+| The character changed after re-running an earlier stage | `--force` on `anchor` invalidates every artifact that quoted it — poses, frames, the row. Nothing tracks that; re-run them, in order |
+| `status` shows nothing and the files are there | an older layout; `spritegen migrate` |
+| `show` reports drift | a file was added or removed by hand. Nothing is rewritten for you; decide which side is right |
+| `the upscale needs torch` / `the local matte needs rembg` | the optional extra is not installed; the message names the command |
+| It runs on the CPU and takes minutes | onnxruntime or torch has no GPU build here |
+
+---
+
+# Prompt skeletons
+
+`--prompt-file` sends the file verbatim, so copy a skeleton, fill every `<slot>`, and drop
+what does not apply — an over-specified prompt fights itself.
+
+## An item icon or HUD piece
+
+> True pixel art. A single `<the object>` and nothing else: one object, centred, upright,
+> filling the frame, seen `<straight on / at a slight three-quarter angle>`. No character, no
+> hand holding it, no ground, no scene, no shadow cast onto anything.
+>
+> `<Describe the object: its material, its parts, its trim, what is worn or damaged.>`
+>
+> Resolution — this governs everything: it is drawn at a native resolution of roughly `<32>`
+> art pixels square, then shown enlarged with nearest-neighbour scaling, so every art pixel
+> is a large solid square block of exactly one flat colour, all the same size, aligned to one
+> strict square grid, edges perfectly straight and perfectly hard. No anti-aliasing, no blur,
+> no gradient, no airbrush, no smooth shading, no glow, no glossy specular highlight, no drop
+> shadow, no partially transparent pixel. Shading steps between a small number of flat tones.
+> Diagonals appear as stair steps of whole blocks.
+>
+> Palette: at most `<sixteen>` flat colours in the whole image, hard borders between
+> neighbouring colour areas. `<The colours that matter.>`
+>
+> Background: one single flat colour, uniform across the whole image, touching no part of the
+> object's own palette.
+>
+> No text, no watermark, no border, no frame, no grid lines drawn over the art.
+
+## Box art
+
+`anchor --kind box-art`. Not a sprite: no native resolution, no palette cap, no
+`--pixelart`. Say what the character is, what they wear and carry, the mood and the light,
+and ask for a full-body illustration against a plain background. Its only job is to be the
+identity reference the anchor quotes, and it lives in the same sprite's directory.
+
+## A character anchor
+
+**The one that changed.** No block language, no native resolution, no palette cap — this
+image is animated, and a model deforms a drawing far better than it deforms blocks. What
+it *does* say is everything about the art direction that is not resolution: proportions,
+flat shading, hard silhouette, no photographic finish.
+
+> `<One reference image is supplied. It is the character, and it is used for identity only:
+> take from it EVERY IDENTIFYING DETAIL — hair colour and how it is worn, eyes, the garment
+> and its colours, the armour pieces and their seams, the belt, the footwear, the weapon and
+> its grip and guard, which hand holds it, which hip the scabbard sits on. Take nothing of
+> how it is drawn, nothing of its lighting, and nothing of its background.>`
+>
+> A single top-down RPG character sprite for a tile-based mobile MMORPG, one character only,
+> centred, standing still in a neutral idle pose and facing south, straight toward the
+> camera.
+>
+> Rendering — this governs everything: crisp, clean 2D game art with hard, precise edges and
+> a silhouette that reads instantly at small size. Flat cel shading in a small number of
+> tone steps, each step a clear area rather than a blend. No photographic realism, no depth
+> of field, no bloom, no lens flare, no film grain, no ambient glow, no soft focus, no
+> painterly brush texture, no drop shadow cast onto anything. Colours are saturated and
+> separated: neighbouring areas differ enough to stay distinct when the image is reduced.
+>
+> `<Do NOT ask for pixel art, for a native resolution, for blocks, for nearest-neighbour
+> scaling or for a palette cap. This image is going to be animated, and blocks animate
+> badly. The pixel treatment happens afterwards, locally.>`
+>
+> Proportions: a squat, big-headed game sprite. The head including `<the hair>` is about
+> `<forty>` percent of the figure's total height. Narrow shoulders, a short blocky torso,
+> short thick arms and legs, simple chunky hands and feet. The figure stands upright and
+> fills the frame from `<the top of the head>` to `<the soles of both feet>`, feet flat and
+> planted slightly apart.
+>
+> Camera: roughly forty-five degree top-down three-quarter view, seen slightly from above
+> while still facing the viewer. The camera does not tilt and the figure is not foreshortened.
+>
+> Palette: `<the five or six colours that matter>`, used in flat areas with clean borders
+> between them.
+>
+> Silhouette: `<what keeps the figure from reading as one solid slab — a garment cut short so
+> both legs read as separate shapes, a break at the top of the silhouette.>` In `<the right>`
+> hand, held down along the side and angled out from the body so the whole `<blade>` is
+> visible and crosses no part of the figure: `<the weapon, described>`. `<The other>` hand
+> hangs open and empty. `<The scabbard sits at the belt on the opposite hip.>`
+>
+> Background: one single flat colour, uniform across the whole image, touching no part of the
+> figure's own palette.
+>
+> No text, no watermark, no border, no frame, no grid lines drawn over the art.
+
+### If the project really does want blocks in the anchor
+
+It is the wrong trade for anything that moves, and the reason is above. For a **static**
+sprite that will never be animated, the icon skeleton's resolution paragraph is the one to
+paste in, together with `--pixelart` — prompt and flag, never one of them. Prompt alone
+gives a smooth render that merely looks blocky; the flag alone gives a clean grid over
+mush.
+
+## An animation's starting pose
+
+The anchor's skeleton, minus everything about the character, plus what changed. Its whole
+job is to be the same character in a different position, so most of it is a refusal to
+change anything.
+
+> One reference image is supplied. It is the character, and everything about the character
+> comes from it and only from it: `<hair, eyes, the garment and its colours, the armour
+> pieces, the belt, the footwear, the weapon and its grip, which hand holds it, which hip
+> the scabbard sits on>`. Same palette, same proportions, same rendering, same camera.
+>
+> Only the pose changes. `<The character has drawn the sword back over the right shoulder,
+> both hands on the grip, weight shifted onto the back foot, torso turned slightly away
+> from the camera, the blade angled up and clear of the head so its whole length is
+> visible against the background.>`
+>
+> The character still faces `<south, toward the camera>` and still fills the frame from
+> the top of the head to the soles of both feet.
+>
+> Nothing is added and nothing is taken away — no effects, no particles, no glow, no
+> motion blur, no trails, no added light, no impact lines.
+>
+> Background: one single flat colour, uniform across the whole image, touching no part of
+> the figure's own palette.
+>
+> No text, no watermark, no border, no frame.
+
+## A video movement
+
+Four things carry the whole prompt and none are optional: **in place**, **no camera
+movement**, **the loop closes**, **the character does not change**.
+
+> The character in the supplied image performs `<one walk cycle / one sword swing and
+> recovery / one casting gesture>`, and nothing else happens in the clip.
+>
+> The character stays exactly where it is. It moves in place: it does not travel across the
+> frame, does not step toward or away from the camera, and does not drift in any direction.
+> It faces `<south, straight toward the camera>` for the entire clip. It never turns, never
+> rotates, never shows a `<side or back>` view.
+>
+> The camera does not move. No pan, no zoom, no dolly, no orbit, no shake, no change of
+> framing or focal length. The framing at the last frame is the framing at the first.
+>
+> The clip is one complete cycle and it loops: the final pose returns to the starting pose,
+> so the last frame runs into the first with no jump.
+>
+> The character does not change. Same `<colours, palette, proportions, garment, armour,
+> weapon and how it is held>` as the supplied image, in every frame. Nothing added, nothing
+> taken away — no effects, no particles, no glow, no motion blur, no trails, no added light.
+>
+> The movement itself: `<alternating leg steps, a small vertical bob, a small arm swing, the
+> hair swaying with the step. The blade stays clear of the body throughout.>`
+>
+> The background stays one single flat colour, uniform and unchanged across every frame, with
+> nothing in it: no scenery, no ground plane, no shadow cast onto it, no gradient, no
+> vignette. Nothing in the character uses that colour.
+>
+> No text, no watermark, no border, no frame, no user interface.
+
+---
+
+# Every option
+
+Read out of the CLI's own stage registry when this file was written, so it describes the
+spritegen that wrote it rather than one someone remembers.
+
+<!-- generated: options -->
+
+<!-- generated: endpoints -->
+
+<!-- generated: free -->