Walk and attack animations for knight and kobold; the dead topple, sink and fade (death animations where drawn)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

art/generated/sprites/anim/PROMPTS.md

@@ -0,0 +1,151 @@
+# Creature animations (pilot: knight, kobold)
+
+Generated on 2026-11-07 with `fal-ai/nano-banana-pro/edit` (`resolution: 2K`, `num_images: 1`,
+`output_format: png`), following the imp's digging animation (`../../imp-sprite/PROMPTS.md`).
+
+Every sheet has the layout of `imp-hack-*.png`: 4 frames across, 5 views down (front, front
+three-quarter turned right, side facing right, back three-quarter turned away to the right,
+back), transparent, the feet on the bottom row of every cell, the SAME body scale, feet row and
+palette as the creature's idle sheet (`../<id>-32.png` / `-64.png`), so frames and idle line up.
+
+| file | size |
+| --- | --- |
+| `<id>-walk-32.png`, `<id>-attack-32.png` | 128x160 |
+| `<id>-walk-64.png`, `<id>-attack-64.png` | 256x320 |
+| `<id>-<anim>-<size>-preview.png` | frames scaled up (8x / 4x), the idle view in the right column, dotted feet row |
+
+`walk`: contact, passing, contact (other leg), passing; the creature walks in place (the game
+moves it). `attack`: wind-up, strike, impact, recover; the feet stay in place.
+
+## Script
+
+`../scripts/make_anim.py` (Pillow venv: `/tmp/sprvenv/bin/python -I`; reads the key from
+`~/.config/dungeoncraft/fal-key`, never prints it):
+
+```bash
+S=art/generated/sprites/scripts/make_anim.py
+python $S gen <id> <walk|attack> [front|back|both] [--suffix -2] [--strict] [--front-src F] [--print]
+python $S pix <id> <walk|attack> [--front F] [--back B] [--view V=SPEC ...] [--add-colors "R,G,B;..."]
+```
+
+### gen
+
+1. **front request** (`<id>-<anim>-front-raw<S>.png`, `aspect_ratio 4:5`): reference = the idle
+   raw (`../<id>-raw.png`, the `--crop` of `../scripts/extra.txt` if any) at half size with the
+   background (and any frame lines, e.g. the kobold's raw) repainted in flat key colour. Asks for
+   the full 5x4 grid; rows 1-3 are used, rows 4-5 sometimes too (see below).
+2. **back request** (`<id>-<anim>-back-raw<S>.png`, `aspect_ratio 16:9`): references = the same
+   idle reference + rows 1-3 of the front raw (`--front-src` picks another front raw). 2x4 grid.
+   `--strict` adds a sentence that all eight figures, the strike frames included, are seen from
+   behind (no visor/face/emblem) and that the back three-quarter row is turned clearly right.
+
+Prompts: built by `prompt_front` / `prompt_back` from the creature's idle description
+(`creatures.py`), the per-creature `WEAPON` and `ATTACK` texts and the generic `WALK_*` frame
+texts in `make_anim.py`. A batch for all creatures needs a `WEAPON` and an `ATTACK` entry for each
+one (the walk text is generic). `--print` shows the prompts. Example (kobold attack, front):
+
+```text
+The attached image is a pixel art sprite sheet of the "Kobold" in five views (left to right: front, front three-quarter turned right, side facing right, back three-quarter turned away to the right, back). A small scaly lizard-folk warrior: ... It holds an upright wooden spear with a steel tip in its right hand.
+
+Create a new pixel art sprite sheet of exactly the same character - same proportions, colours, outline, pixel size, clothes and equipment - showing a spear thrust: the kobold holds the spear level with both hands and stabs it forward at an enemy in front of it.
+
+Layout: a grid of 5 rows and 4 columns, every figure the same size, evenly spaced, each in its own equal cell, all standing on the same baseline within their row.
+Rows (one view per row, top to bottom): 1 front view facing the viewer, 2 front three-quarter view turned to the right, 3 side view facing right, 4 back three-quarter view turned away to the right, 5 back view.
+Columns (animation frames, left to right): 1 wind-up - the spear pulled back, held level at waist height with both hands, the tip pointing forward, body leaning back; 2 strike - the spear pushed forward, body leaning forward; 3 impact - the spear fully thrust forward, arms stretched out, body lunging forward, a small white spark at the spear tip; 4 recover - the spear pulled back to the ready position, body upright.
+The feet stay in place in all four frames; only arms, weapon, head and upper body move.
+Every frame of a row keeps exactly that row's view direction (the side view row stays in profile facing right in all four frames, the back rows never show the face), and the character holds the same wooden spear with the steel tip in the right hand in every single frame.
+
+Style: identical to the attached sheet - crisp retro pixel art, hard square pixels, one-pixel near-black outline, limited palette, no anti-aliasing, no blur. Flat pure magenta (#FF00FF) background everywhere, no ground, no shadows, no text, no labels, no frame lines, no grid lines, no motion lines.
+```
+
+The first four front requests (`*-front-raw.png`) were sent without the "Every frame of a row
+keeps ..." sentence and without "no motion lines"; the knight attack strike frame also asked
+for "a short white motion arc behind the blade" (the model drew big white swoosh rings; removed).
+The back prompt is the imp's back prompt with the character's name and frame texts.
+
+### pix
+
+Per view row: the row is cut out of the raw (bands found by the empty rows between them,
+falling back to cuts at the emptiest rows near even splits when weapons touch the next row),
+pixelized with `tools/pixelize_sprite.py --grid 1xN --size S --feet S-1 --outline-weight 0.6
+--palette ../<id>-S.png`, and:
+
+- **scale**: the step is iterated until the median *core height* of the row's figures equals
+  the core height of the idle view. Core = from the first pixel row whose longest opaque run is
+  at least 20% of the cell wide (a spear tip or a raised blade is narrower, the head is wider)
+  to the last row with a run of at least 3 px. So a spear above the head or a sword raised in
+  the wind-up does not shrink the body.
+- **position**: each frame is shifted so that its core bottom is on the feet row and the median
+  centre of its core rows is at the idle view's centre (the tool itself centres by bounding box,
+  which would push the body away from an outstretched weapon). Pixels pushed out of the cell are
+  cut (logged as `CLIPPED n px`).
+- **check**: the log prints per view the ratio of the frames' median body width to the idle
+  view's (`width ratio`, flagged beyond +-10%): the model sometimes redraws the character
+  stockier or slimmer, which no scaling can hide.
+- `--view V=SPEC` takes the frames of view V from other rows or files:
+  `FILE:BAND/NBANDS:COUNT:PICKS[;FILE:...]` (empty FILE = the front raw; PICKS like `0,2,1,3`,
+  `m1` mirrors). Every source row is scaled on its own, so frames of different raws can be mixed.
+
+## Requests (11 images, about $1.65 at ~$0.15 per 2K image)
+
+| raw | result |
+| --- | --- |
+| `knight-walk-front-raw.png` | rows 1-2 ok; row 3 had SIX figures (4 side + 2 back three-quarter), rows 4-5 mixed. Side row used (figures 0,2,1,3: stride, pass, stride, pass) |
+| `knight-walk-front-raw-2.png` (retry) | all 5 rows correct; front, front 3/4, back 3/4, back used; its side row shows the same stride four times |
+| `knight-attack-front-raw.png` | front and front 3/4 rows nearly identical, side row turned to the front in frames 2-3, big white swoosh rings: dropped |
+| `knight-attack-front-raw-2.png` (retry, new sentence) | rows 1-3 good (raised, over the helm, low at the left, ready) |
+| `knight-attack-back-raw.png` | strike frame (column 2) showed the visor and the chest emblem in both rows: dropped |
+| `knight-attack-back-raw-2.png` (retry, `--strict`) | good: all from behind, row 1 slightly turned |
+| `kobold-walk-front-raw.png` | spear missing in the passing frames of the front and side rows: dropped |
+| `kobold-walk-front-raw-2.png` (retry) | SIX frames per row, spear in nearly all; figures 0,1,3,4 used; back 3/4 row inconsistent |
+| `kobold-walk-back-raw.png` (`--strict`, reference = the first 4 columns of raw-2, `kobold-walk-front-raw-2-4cols.png`) | good back views but the spear vanishes in the passing frames; frames 0 and 2 used |
+| `kobold-attack-front-raw.png` | very good, rows 1-5 all right |
+| `kobold-attack-back-raw.png` | row 1 good; row 2 frames 2-3 are back three-quarter views instead of the back view |
+
+## Commands used
+
+```bash
+cd art/generated/sprites/anim; P="/tmp/sprvenv/bin/python -I"; S=../scripts/make_anim.py
+$P $S pix knight walk --front knight-walk-front-raw-2.png --view "2=knight-walk-front-raw.png:2/4:6:0,2,1,3" \
+    --view "3=knight-walk-front-raw-2.png:3/5:4:0,1,2,3" --view "4=knight-walk-front-raw-2.png:4/5:4:0,1,2,3"
+$P $S pix knight attack --front knight-attack-front-raw-2.png --back knight-attack-back-raw-2.png
+$P $S pix kobold walk --front kobold-walk-front-raw-2.png \
+    --view "0=:0/5:6:0,1,3,4" --view "1=:1/5:6:0,1,3,4" --view "2=:2/5:6:0,1,3,4" \
+    --view "3=kobold-walk-back-raw.png:0/2:4:0;:3/5:6:4;kobold-walk-back-raw.png:0/2:4:2;:3/5:6:4" \
+    --view "4=:4/5:6:0,1,3,4"
+$P $S pix kobold attack --view "4=kobold-attack-back-raw.png:1/2:4:0;kobold-attack-front-raw.png:4/5:4:1,2;kobold-attack-back-raw.png:1/2:4:3"
+```
+
+No extra colours were needed: the steel of both weapons is in the idle palettes.
+
+## Quality
+
+- **knight-walk**: usable. Height and feet line up with idle (core height = the full cell, as
+  in idle), no vertical shift. The model drew the knight about 5-15% wider/stockier than the idle
+  sheet (width ratio 1.01-1.18 in the log), so switching idle -> walk shows a slightly broader
+  knight. Leg motion is small in the front views; the side view comes from the first raw (a
+  separate image, 6 figures in that row) and is a real stride/pass cycle but differs a little in
+  shading from the other rows.
+- **knight-attack**: good motion, readable in every view (sword raised over the shoulder,
+  over the helm, low at the left, ready). Same stockiness as the walk (width ratio up to 1.3 in
+  the front three-quarter row, partly the sword). The knight fills the whole cell height, so
+  a sword raised above the helm is cut at the top of the cell (the tool crops it; not counted in
+  the CLIPPED log). The low impact blade loses up to 5 px at the cell side (64).
+
+- **kobold-walk**: usable. Body, head and feet line up with idle in every view (core heights
+  equal, no vertical shift). The leg motion is subtle (the model draws small steps), the spear
+  stays in the hand in all frames. Back three-quarter: frames 2 and 4 are the same figure
+  (from the front raw-2), frames 1 and 3 come from the back request and are drawn a little
+  narrower, so that view jitters slightly.
+- **kobold-attack**: good. Clear thrust in all views; body and feet line up with idle. The
+  level spear is longer than the cell, so its butt or tip is cut at the cell edge in most
+  frames (up to 8 px at 32, 33 px at 64 in the front impact frame). The front three-quarter
+  wind-up holds the spear pointing backwards. Back view: frames 1 and 4 from the back request,
+  frames 2-3 from row 5 of the front raw (the back request had back three-quarter figures there).
+  The white impact spark is mapped to the nearest palette colour (light grey) or lost.
+
+## Raw files
+
+The raws `*-raw*.png` are large and not covered by `.gitignore` (which only ignores
+`art/generated/sprites/*-raw*.png`); add `art/generated/sprites/anim/*-raw*.png` before
+committing.