agent (cont.)

+0:48
  • read_file{"Path":"~/work/lowmarch/docs/portrait-guide.md"}

    input

    {
      "Path": "~/work/lowmarch/docs/portrait-guide.md"
    }

    result, 618 lines

    Partial read (lines 1-800 of 1442). Showing bytes 0-46080 of 60476 in this line range, truncated at the 46080-byte limit. To read the rest of this line range, call this tool again with the same StartLine and EndLine and ByteOffset=46080.
    1: # Portrait guide
    2: 
    3: **Status (2026-11-08):** detail log, kept as written. Start at `docs/handbook.md`, which marks each rule earned or guessed.
    4: 
    5: How we draw Lowmarch portraits, and what each study taught us. Update this after every
    6: portrait so the next one starts further ahead.
    7: 
    8: ## Format
    9: 
    10: - 96×80 mug, ¾ view **facing left** (mirror at runtime for the right side of a dialogue).
    11: - Layers: `back` (hair behind the head), `body` (neck, clothes), `face`, `hair` (front), plus
    12:   overlays `blink`, `talk1`, `talk2` that sit between `face` and `hair`.
    13: - No hard colour cap. Rowan uses 26 colours; spend them where the eye looks (face, hair, trims).
    14: 
    15: ## House style (from the FE8 study, 61 portraits)
    16: 
    17: **Line.** Outline is a dark purple, never black. Lines *inside* a material use that
    18: material's own darkest tone: rosy brown in skin, darkest hair tone between locks.
    19: 
    20: **Skin.** Five tones. The main fill is the *lightest* cream; form comes from warm shadow
    21: steps (yellow-cream → orange → brown → line). Shadows go: under the bangs (cast), the far side
    22: of the nose bridge, under the nose tip, the turned side of the face toward the ear, along the
    23: jaw, under the chin, the neck.
    24: 
    25: **Eyes.** Smaller than you expect. Near eye ≈ 7×5 px, far eye 3–4 px wide and cut by the face
    26: contour. Two-pixel upper lash with a flick at the outer corner; sclera on the nose side;
    27: iris pushed toward the ear so the character looks at the viewer; a catchlight on the pupil;
    28: a short lower lid. Iris uses 3 tones dark-top to light-bottom.
    29: 
    30: **Brows.** Men: heavy, sitting right on the lash line. Women: thin, high.
    31: 
    32: **Nose and mouth.** No outline. The nose is a bridge shadow plus 1–2 dark pixels under the
    33: tip. The mouth is a 3–5 px line with a lower-lip shade beneath.
    34: 
    35: **Hair.** Flows from a crown whorl. Each lock tapers to a tip and has a lit side (toward the
    36: upper left) and a shadow side; the separating line sits on the shadow side. Bangs sweep
    37: toward the way the face turns. Shine is broken streaks on lit locks, never one band.
    38: 
    39: **Body.** The bust fills the bottom ~25 rows and needs bright trims or plate highlights;
    40: a dark, flat costume kills the value structure under the face.
    41: 
    42: **Archetype cues.** Youth: taller eyes. Age: narrower eyes, bags, smile lines, hollow cheeks.
    43: Heavy builds: round masses. Women: rounder cheeks, more eye white, thin high brows.
    44: Villains: slanted eyes, longer nose, asymmetric mouth.
    45: 
    46: ## Workflow
    47: 
    48: 1. **Block in** big masses with vectors (`tools/vecpix.py`): drawn at 4×, shrunk by a
    49:    palette-preserving majority vote, outlined automatically. Good for silhouettes and
    50:    proportions; never for features.
    51: 2. **Face from a template** (`art/templates/face_<archetype>.strokes`), placed with
    52:    `pix.py paint --offset`. Features are hand-placed pixels at final size.
    53: 3. **Hair and cloth with clumps** (`Canvas.clump` + `lock()`): per-lock lit/shadow edges and
    54:    separating lines. Then `pix.py shadow` casts the bangs onto the face.
    55: 4. **Polish** with coordinate strokes (`polish.strokes`). Every hand edit lives in a strokes
    56:    file so `build.py` can rebuild the portrait from source at any time.
    57: 5. **Check at 1×** (the real display size) and in greyscale with `pix.py compare` against
    58:    references. Read the value structure before colour.
    59: 
    60: ## Lessons log
    61: 
    62: ### 01 · Rowan (young man), 2026-10-07
    63: 
    64: - Writing whole 96-character rows by hand invites miscounts. Use absolute-coordinate strokes.
    65: - Bangs hanging straight down read as a curtain. Sweep them toward the face's turn.
    66: - Lines on every lock edge look like planks. Line only the shadow side; layer locks right to left.
    67: - One flat shine band reads as a cap. Break shine into streaks on lit locks.
    68: - A dark navy coat swallowed every detail. Lighter ramp, gold trims, a lit shoulder ridge.
    69: - A thin lock between the eyes became a dark stripe. Keep tips short there, or lighten them.
    70: - Bare forehead between bangs looked like light columns. Always run the cast-shadow pass.
    71: - **Open:** the face reads narrower than FE8 because the sideburn and back hair cover the turned
    72:   cheek. Next time leave the ear and cheek visible. The hair is spikier than FE8's rounder clumps.
    73: 
    74: ### 02 · Head mannequin spike, 2026-10-07
    75: 
    76: Both 2D attempts (mine and Fable's) plateaued on the same thing: perspective was guessed one
    77: pixel at a time. `tools/head3d.py` builds the head in 3D instead (cranium, a lofted face and jaw,
    78: nose, ears, neck), poses it, cel-shades it and shrinks it with the vecpix reduction. Features stay
    79: hand-drawn and are placed at the landmarks the renderer reports.
    80: 
    81: - FE8 light comes from about the camera, not the upper left: a bright face centre with orange
    82:   toward *both* the far contour and the side plane. Use `LIGHT ≈ (0.08, 0.06, 1)`.
    83: - FE8 proportions, young man, measured from the eye line: nose tip ≈ +9 px, mouth ≈ +14,
    84:   chin ≈ +17–20. The ear sits ≈ 17 px behind the mouth, so anime heads are shallower than real ones.
    85:   Move the ear forward and keep the head narrow.
    86: - The chin sits under the mouth, not behind it. A receding loft chin looks wrong at ¾.
    87: - Self-shadowing from a high light darkens the whole face. Faces take only short cast shadows
    88:   (nose, hairline). The neck takes the long one from the jaw.
    89: - Without hair, judge the face with a placeholder cap on. A bald cranium makes every head read as
    90:   a light bulb.
    91: 
    92: ### 03 · Features by angle, 2026-10-07
    93: 
    94: From research into anime-style 3D (Guilty Gear Xrd, view-dependent geometry, Genshin face shadow
    95: maps, anime head drawing guides). The rule everyone follows: anything that looks wrong from an angle
    96: gets authored for that angle.
    97: 
    98: - **Flat eye plane.** A cylinder-like face squeezes the far eye even at 20° ("cursed"). Keep brow and
    99:   eye keys square at the front (pf ≈ 4, m ≈ 0.55) so the eyes sit on a plane that turns at the temple.
    100:   Far/near eye width should be ≈ 0.84 / 0.71 / 0.56 at 20 / 35 / 50°.
    101: - **Features are 2D, drawn per view** (`tools/features.py`). Eye width comes from projected corners.
    102:   The far eye anchors on its inner corner and is clipped by the face. Irises shift toward the viewer by
    103:   ≈ 0.6·sin(yaw)·W/2 px. The mouth spans its projected corners (4–5 px at the front).
    104: - **The nose is an outline, not a shading source.** It uses proxy normals, casts no shadow, and gets
    105:   a dash under the tip plus a short far-side bridge shadow. Its rise grows with yaw (`view` keys).
    106: - **Jaw corner under the earlobe**; the back of the jaw rises into it. The ear runs from the lash line
    107:   to the nose base, tilted back about 12°.
    108: - **Authored shading beats computed shading.** From 35° the strip between the nose line and the far
    109:   contour is forced to the shadow tone, and from 15° the side plane past the outer eye corner stays
    110:   orange. Proxy-normal blend 0.72 with bands 0.84 / 0.72 / 0.45 gives a clean lit centre.
    111: - **View-dependent shape** goes in the preset's `view` table (yaw → values, blended with a
    112:   sharpened lerp). Use it for anything that should cheat by angle.
    113: 
    114: ### 04 · VRoid base, 2026-10-08
    115: 
    116: Our own mannequin plateaued because every shape number was invented. Rendering the unpixelated
    117: model showed it: a flat slab face, a shovel jaw, a spike nose. VRoid's sample models (CC0 and
    118: VRoid Hub licence, see `docs/vroid.md`) give a professionally built anime head, hair, body and
    119: expressions. The first raw render already beat everything we had drawn.
    120: 
    121: - **Use a real 3D reference before tuning shapes.** Judging 3D at 96×80 hides construction errors.
    122:   Always look at the smooth model (`smooth_view`) as well as the pixels.
    123: - **Features from geometry and masks.** Eyes, brows and lashes come from VRoid's alpha-tested face
    124:   parts, which classify to palette roles. Lines get a higher vote weight in the 4×4 reduction so
    125:   thin lids and closed eyes survive.
    126: - **Hair.** VRoid hair is built from strands. Separation lines go where one strand sits in front of
    127:   another, and inner layers drop a tone, which gives FE-style clumps without drawing any.
    128: - **Archetypes are shape controls on the mesh** (face length, jaw, chin, cheeks, eyes, brows, nose,
    129:   mouth, neck, shoulders, head size), plus hair swaps between models and per-character colours.
    130: - **Never deform a face by height bands.** Scaling everything between two heights turned Gorm's face
    131:   into a shield and his chin into a spike. Use three layers instead: bone scales for proportions
    132:   (`bone_pose`), anchored RBF sculpting of named anatomical points (`sculpt`; the eyes, ears, skull
    133:   and neck are held still), and VRoid's own expression shapes at low weight for hooded or stern eyes
    134:   (`rest`). Check every archetype in the smooth view, front and profile, not just at 35° in pixels.
    135: - In a bust, drop the body skin below the neck. Clothes are fitted to the base body, and any change
    136:   of build makes skin poke through.
    137: 
    138: ### 05 · First costume, 2026-10-08
    139: 
    140: `tools/outfit.py` builds costumes in code against a `Fit` (posed bone positions plus the body skin).
    141: The VRoid clothes are dropped when a cast entry names a `costume`.
    142: 
    143: - **One-sided sheets need a known outside.** Give every generated piece `outward_from` (a point, or
    144:   a line with `axis`) so its normals face out. The renderer then shades the inside of a cape or
    145:   collar one tone darker. Wrong winding made the first shoulder plate render as its dark inside.
    146: - **Capes drape; they don't hang.** A cape hung straight down disappears behind the shoulders below
    147:   the frame. Lay its top edge over the shoulders, raise it behind the neck, and clamp it above the
    148:   body's top surface (`Fit.top_height`) plus clearance.
    149: - **Steel at 1×** needs a narrow top band: bands 0.975 / 0.86 / 0.55, or the plate reads as white.
    150: - **Male VRoid eyes read small at 1×.** Lords and youths want eye scale around 1.1–1.15. The
    151:   "surprised" shape shrinks the irises and does not open the lids.
    152: 
    153: ### 06 · Full figure and review tooling, 2026-10-08
    154: 
    155: - **The closed mouth is painted, not modelled.** VRoid's mouth mesh is the inside of the mouth.
    156:   The lip line and nose mark are on the face texture. `Portrait(mouth=...)` picks how they are drawn:
    157:   `texture` (painted line grown 4 texels so it survives the vote), `texture+lip` (plus a lower-lip
    158:   shade), `drawn` (an FE8 mouth between the projected corners), or `none`. Marks only count
    159:   inside the nose-and-mouth window of the shared VRoid face layout, or the ear shading turns brown.
    160: - **Low-poly skin has sparse vertices.** Cross-sections taken from nearby vertices came back empty on
    161:   the thighs, which looked like missing skin; the skin is complete. Take sections from
    162:   triangle-plane intersections, and fit garments to the skin alone. VRoid's own clothes are bulky.
    163: - **Camera elevation is not a nod.** Turn the character first, then tilt the camera
    164:   (`camera_rotation`). Tilting in model space made the battle figure lean sideways.
    165: - **Scenery needs its own light.** The camera-facing light leaves flat ground in shadow; scenery
    166:   uses `SUN`.
    167: - **Keep build scripts in the repo** (`review/<page>/build.py`); the session scratchpad gets wiped.
    168:   Artifact hosting serves `.json`, not `.glb`, so models ship base64-wrapped in `<view>.glb.json`.
    169: 
    170: ### 07 · High resolution and the armour refit, 2026-10-08
    171: 
    172: **Resolution decision (user):** no GBA-native constraint. Render the 3D models as high-resolution
    173: pixel art on a 640×360 base screen (integer scales to 1080p, 1440p, 4K): portraits 192×160
    174: (`BUST_*`), battle 640×360 at 90 px/m (`BATTLE_*`). The 4×4 vote and the inking are vectorised.
    175: Rules tuned at 96×80 (strand lines, mark growth) may need retuning.
    176: 
    177: **Fit (from the armour-fit study: CC0 Quaternius/KayKit references plus measurements of our pieces):**
    178: - Shrink-wrap garments (`outfit.wrap`, `fitting.shrink_wrap`): weld VRoid's UV-seam vertices first,
    179:   Taubin-smooth (plain Laplacian shrinks the surface about 9 mm, putting 44% of the tunic inside the
    180:   body), then set every vertex at the offset with a floor. Offsets: shirt/tunic 6–10 mm, trousers 8,
    181:   boots 17, gloves 2–3, each layer on top +5–8 mm.
    182: - Fit collars and plates by ray casts to what they cover (`collar`, `pauldron`), not fixed ellipses.
    183:   An apex gap is fine; open rims and edges touching nothing are what read as floating. Give rims
    184:   thickness (`thick_grid`).
    185: - The collar rises at the back (44 mm against 28 at the front), sits 9–15 mm off the neck, and its
    186:   front tips stay at least 25 mm below the chin.
    187: - Capes attach: the top edge lies on the tunic under the collar, clasped at the collarbones, and a
    188:   small cloth solve (`drape`) settles it with clearance from 10 mm (shoulders) to 45 mm (hem).
    189:   Build what it drapes over (tails, belt) first.
    190: - Build every piece once in the reference pose with skin weights (copied from the body, limited to
    191:   allowed bones for capes and tails, rigid for plates and props), and pose through the skeleton
    192:   (`repose`), so nothing drifts or pops between animation frames.
    193: 
    194: ### 08 · Live renderer and cloth, 2026-10-08
    195: 
    196: - **The pixel renderer has a real-time GPU port** (`review/vroid-02/index.html`, three.js). It runs a
    197:   colour pass (palette bands per role, camera light, textures for eyes and lids, nose mark) and an
    198:   info pass (role and piece IDs plus depth) into low-res targets, then a composite applies the same
    199:   ink rules as `Portrait.ink`. Use `hex()`-style raw colours and `LinearSRGBColorSpace` output, or
    200:   three.js colour management darkens the palette. The Python renderer stays the reference.
    201: - **Mouth:** `curve` is the default. It traces the painted lip line in 3D and draws it as a tapered
    202:   1-px line (offline: `draw_curve_mouth`; live: a GL line, always one pixel wide at render
    203:   resolution). Under a collar's front opening, keep the throat skin.
    204: - **Cloth in the viewer:** the cape and tails export as grids (`grid`); the browser runs Verlet with
    205:   stretch and bend constraints, a pinned top row, and capsule colliders measured from the body
    206:   (`export_glb.scene_info`). Gold trim on cloth is drawn as lines that follow the particles.
    207: - **Tails collide with hips and legs only.** Hanging sleeves in the collision set hold them out.
    208: 
    209: ### 09 · Painted renderer and battle animation, 2026-10-08
    210: 
    211: Direction change (user): keep the pixel renderer, and add a renderer aiming at Unicorn Overlord's
    212: hand-painted look. Unicorn Overlord has no 3D models: Vanillaware paints 2D parts and puppets them.
    213: So its art is a design study only, and the look comes from our 3D through a painted shader.
    214: 
    215: - **Painted renderer** (viewer, `PAINT_FS`/`PAINT_COMP`): palette ramps blended softly
    216:   (smoothstep ±0.09 around each band), a key light from the upper left, cool shadows (rosy for
    217:   skin), warm lights, a fresnel rim, metal as a sky/ground reflection plus a highlight streak, a hair
    218:   sheen, object-space brush grain (per material: skin 0.02, hair 0.04, cloth 0.10, ground 0.16),
    219:   coloured outlines (a 2.2 px outer silhouette, interior lines at depth breaks, each a darker
    220:   shade of the colour it borders), and crease darkening from depth.
    221: - **One rigged character** (`export_glb.export_skinned`): the reference-pose mesh, VRoid skeleton
    222:   with our bone scales, inverse binds, and per-vertex weights for every piece. Clips are
    223:   authored in `tools/clips.py` as a few key poses, finished with `tools/rig.py` (two-bone leg IK,
    224:   `aim` for the sword, `rotate_world`). Poses accept 4×4 adjustments (`poses.move`) for root motion.
    225: - **Garment weights come from the exact skin they grew from** (`fitting.blend_weights` through
    226:   subdivision). Copying from the nearest skin let one boot take the other leg's bones, and the
    227:   boots stretched into sheets when the legs split.
    228: - **Export a channel for every bone the clip moves away from the reference pose,** even if it
    229:   then holds still: a held fist has no variation, but without a channel it reverts to the open
    230:   reference hand.
    231: - three.js shader includes must start a line: `void main() {\n#include <...>`.
    232: - Cloth on an animated body: hide the skinned cape and read its pinned row with
    233:   `getVertexPosition` each frame; colliders follow bones by name; the simulated copy is a plain mesh
    234:   in world space.
    235: 
    236: ### 10 · Painted renderer tuned to the study, and the costume kit, 2026-10-08
    237: 
    238: The Unicorn Overlord study (24 official images, measured) gave shader rules and a costume
    239: language. The art itself was used for study only; nothing of it is in the repo.
    240: 
    241: - **Painted shader** (`PAINT_FS`):
    242:   - **Ramps.** Each role carries a kind and one base colour (`scene_info` → `paint`, from the
    243:     cast's `paint` dict). The shader builds the ramp: shadows rotate toward violet (cool hues) or
    244:     magenta (warm hues, leather), and lights rotate toward yellow with less saturation.
    245:     Terminators are ±0.03, and the light band starts at `lit` 0.91: at 0.82, everything facing
    246:     the camera landed in the highlight.
    247:   - **Skin** uses the measured ramp (`#f8e1d5` / `#c6a89b` / `#73524f`) with no grain.
    248:   - **Hair** has four bands and a spec band shaped by the strand texture. Keep the texture's
    249:     influence low (0.12), or VRoid's baked streaks turn into noise.
    250:   - **Steel** uses hard bands on the reflection's y. A surface facing the camera (r.y ≈ 0) must
    251:     land on the plate's own grey, not a dark band. Jitter the thresholds with noise stretched
    252:     along the bands, or they break into blobs.
    253:   - **Stage grade:** ambient, key colour and back rim, set per view.
    254: - **Painted line art** (`PAINT_COMP`): the ink is the local hue at saturation 0.2–0.45 and value
    255:   0.19. The silhouette is about 0.42% of the figure's height on screen. Interior lines are 55%
    256:   of that, and only at depth breaks between pieces.
    257: - **Costume kit** (`outfit.py`):
    258:   - `limb_lames`: bands around a limb, cast out of the bone axis. Use at least one row per 15 mm
    259:     along the limb: with sparse rows the calf bulged through between them.
    260:   - `dome` and `fan` (`joint_guard`): couters and poleyns with wings.
    261:   - `pipe`: rolled plate edges, which define plate instead of gold.
    262:   - `panel`: the tabard.
    263:   - `mantle`: the hooded scarf.
    264:   - `shield`: the round shield with a chevron device.
    265:   - The new `lord` builds in the study's layering order: doublet, plate, belts, tabard, scarf.
    266:     The first costume stays as `lord_tunic`.
    267: - **Cloth must start outside what it covers.** The drape only pushes outward along the nearest
    268:   face, so a scarf that starts inside the breastplate stays there. Push it out with level rays
    269:   from the neck axis.
    270:   - Keep overhanging pieces (spaulders) out of that collision set. A ray that passes under one
    271:     lands on the arm and pulls the cloth into the gap.
    272:   - The scarf is short at the sides, so the spaulders stand over its edges.
    273: - **Spaulder spread about 108°.** At 132° the lames' front ends wrapped onto the chest and cut
    274:   through the scarf.
    275: - **Per-cloth colliders** (`export_glb.CLOTH`): panels hanging from the belt meet the legs only.
    276:   The hip capsule's round end pushed the back panel out behind.
    277: - **Contacts are inelastic** (the viewer's `Cloth.step`): 80% of a push-out is added to the
    278:   previous position too. Otherwise a stepping thigh flings the tabard.
    279: - New pixel roles: `signature` (the cast's coat bands) and `doublet` (cream, `Q R S T`).
    280: - **Follow-up after review (user):**
    281:   - **Body proportions.** New shape keys in `bone_pose`: `shoulders` (clavicle length), `arms`
    282:     and `legs` (limb thickness), `torso` (waist to chest), `leg_len` (the hips lift by the leg's
    283:     growth, so the feet stay down) and `hands`. Aldric is now about 7.5 heads (from 6.8), with
    284:     shoulders 1.28.
    285:   - **Bone scales vs. pieces that use a bone's frame.** Pieces that take directions from a bone's
    286:     world matrix (the sword in the hand) must normalise it once the bone carries a scale.
    287:   - **An under-layer next to skin must not be skin-toned.** The cream doublet read as bare arms,
    288:     so the doublet is dark charcoal-navy; borders and devices use a separate cool-white
    289:     `heraldry` role.
    290:   - **Belts cast with the body skin in the set wrap the hanging forearms** in the reference pose,
    291:     and stick out sideways once the arms move. Cast belts onto torso layers only.
    292:   - **Body skin is culled under a costume, so every joint needs an overlap.** The wrist showed a
    293:     gap between the sleeve hem and the glove. Gauntlet cuffs overlap both.
    294: 
    295: ### Milestone · Aldric v9 frozen, 2026-10-08
    296: 
    297: The user froze Aldric here as the reference character and asked to put on record how far the
    298: work has come. In two days, the same character went from:
    299: 
    300: 1. a 96 px GBA-style portrait;
    301: 2. a code-built head mannequin;
    302: 3. a VRoid base with archetype controls (bone scales, an anchored face sculpt, rest morphs);
    303: 4. shrink-wrapped, ray-cast fitted costumes and a high-resolution offline pixel renderer;
    304: 5. a live viewer with 3D, pixel and painted renderers, cloth simulation and a rigged battle
    305:    animation;
    306: 6. a re-dress after a Unicorn Overlord design study, in its layering order, with heroic
    307:    proportions.
    308: 
    309: The user's verdict: "a little too muscular but I like it".
    310: 
    311: - **Snapshot:** `review/out/frozen/aldric-v9/` (the built site, `cast.py` and `outfit.py`).
    312:   Published as version 9 of the viewer artifact.
    313: - **Keep him stable.** Don't change Aldric's cast entry or the `lord` costume unless asked.
    314:   After a change to the shared kit, rebuild and compare his meshes with the snapshot.
    315: 
    316: ### 11 · Elaine, and a two-character bind, 2026-10-08
    317: 
    318: The brief (user): a blonde swordswoman like Saber, next to Aldric in the same viewer, locked in a
    319: sword struggle.
    320: 
    321: - **Base:** `HairSample_Female` (CC0). `Portrait(hair_trim=0.12)` drops any hair piece that
    322:   reaches past 12 cm from the centreline, which removes the twin tails and their ties. That
    323:   leaves the bangs and side locks.
    324: - **Costume** (`knight_dress`): `updo` is a bun, a two-strand braid wound round it, a ribbon
    325:   and a flattened, tapering cowlick. With it come a bodice, tights, a breastplate, a closed
    326:   `skirt` (with `drape(closed=True)` and `closed_grid_mesh`), spaulders, gauntlets, greaves and
    327:   `sabaton`s.
    328:   - **Female bases weight the chest to Bust bones.** Include "Bust" in a plate's bone list, or it
    329:     comes out with two holes.
    330:   - **Feet with toes:** a wrap shows the toes, a squashed ellipsoid reads as a triangular hoof
    331:     (the user caught it), and a shell projected onto the convex hull creases. What worked is a
    332:     parametric shoe last from the foot's measurements: rounded heel and toe, widest at the ball,
    333:     rising to the ankle.
    334:   - **`slice_line` cuts each shared edge twice.** Deduplicate before running a pipe along it, or
    335:     the pipe's first tangent is zero.
    336: - **Proportion scales shear turned limbs.** Scaling the clavicle (`shoulders`) skews the arm
    337:   once it rotates: Aldric's hanging upper arms are about 20% shorter and wider sideways (frozen
    338:   as is). New characters use `shoulder_w`, which moves the arm joints out instead. The rig's
    339:   `ortho` mode rotates through the parent's pure rotation. The duel's grip solve measures the
    340:   real fist after each step (CCD-style), because the analytic arm IK alone undershoots on a
    341:   sheared arm.
    342: - **The bind** (`tools/duel.py`):
    343:   - **Setup:** one stage, a shared crossing point, and a placement per fighter (position and
    344:     yaw). The player stands on the right, turned 62°.
    345:   - **Grip:** `rig.grip` puts the fist on its target with the blade aimed through the crossing
    346:     point. The blades meet within 1 mm; `review/vroid-02/duel_check.py` prints it.
    347:   - **Stance:** a two-handed fighter's left fist sits 9.5 cm down the grip. A long dress gets a
    348:     short stance.
    349:   - **Motion:** the clip loops a push: the crossing point drifts toward whoever is giving ground.
    350: - **Viewer:** a character picker and a Duel view; the fighters stand on a stage group that the
    351:   turn slider rotates. The second character's hair gets its own info-pass role id (11), so the
    352:   pixel renderer inks each character's hair in that character's own darkest tone.
    353: - **Long skirts are posed, not simulated** (`SkirtRig`). A free cloth tube against moving leg
    354:   colliders broke in every variant:
    355:   - pushed out the nearest way, it slipped between the legs;
    356:   - pushed out round the leg, the teleports added energy and the hem flew up;
    357:   - with friction on every iteration, it drifted.
    358: 
    359:   Instead, each column hangs from its waist point at its rest shape and is pushed straight out
    360:   along itself past any leg; rows below a contact hang from it. Segment lengths are kept and the
    361:   pushes are smoothed round the skirt and over time.
    362: - **Clips can ease in from another clip** (`setClip(name, from)`), so cloth sees the legs move
    363:   rather than jump.
    364: - **Cloth contacts have friction, applied once per step** (keeping 40% of the speed). Applied
    365:   inside every constraint iteration, it compounded.
    366: 
    367: ### 12 · Checking what the user sees, 2026-10-08
    368: 
    369: The user's review of Elaine found two things my checks had missed:
    370: - **A shelf at the waist:** the top of her skirt stands out past her hips at the sides.
    371: - **An arm through her body:** in the bind, her right upper arm passes through her chest.
    372: 
    373: Both were hidden by how I checked. Every view had the arms hanging over the sides of the waist. The
    374: offline renderer doesn't run the viewer's skirt rig. And the duel check measured only the fists and
    375: the blades, never the arms against the body. The fixes are tools, not care:
    376: 
    377: - **Check sheets** (`review/vroid-02/sheets.py`): one image per character, plus one for the duel,
    378:   rendered by the review page itself (`index.html?sheet=<name>` in headless Chromium, about 15 s each).
    379:   - **Rows:** arms out (35° from the T-pose: `apose`, a clip exported for checking) and idle, each
    380:     from six angles; the attack keyframes; close-ups of the waist, the wrists and the feet; and a
    381:     close-up of every keyframe the checks flag. The duel sheet shows three beats from four sides,
    382:     plus the bind close up.
    383:   - **Each tile** is posed, gets its cloth settled at that angle, and is rendered by the painted
    384:     renderer, so it is what the user sees.
    385: - **Clearance checks** (`tools/checks.py`, run by every build, reported in the page's panel):
    386:   - **Method:** each arm segment is a capsule (the bone's centre line, with the limb's median
    387:     radius measured from the mesh), tested against the posed torso skin.
    388:   - **Skin-vertex tests failed both ways.** Hanging arms read as several centimetres "inside",
    389:     because of the skinning's squash at the armpit, and VRoid's unused vertices (with zero normals)
    390:     read as touching.
    391:   - **Nearest-vertex signs mislead.** The shoulder top is weighted to the Shoulder bones, so a
    392:     raised arm's nearest torso vertex can be the downward-facing armpit skin. A point counts as
    393:     inside only along the inward normal (|s| > d/2). The upper arm's first half is skipped.
    394:   - **What the checks found:** the v10 bind put Elaine's arm 6.4 cm inside her chest. The shared
    395:     attack clip's follow-through puts the sword arm 2 to 3.5 cm into the chest on both characters.
    396:     Aldric's wind-up is also flagged (the forearm behind the neck, under the mantle) and still to
    397:     be confirmed.
    398: - **The fix for the bind:**
    399:   - **Reach first, search second.** Searching elbow directions (`duel.clear_grip`) cleared the right

    218 more lines not shown.