security-game/docs/npc-visual-review.md

NPC roster visual review — 0.9.9

Status: revised after owner feedback; awaiting a second signoff. This page is the single review point for the Quaternius roster in ADR-0017 and ADR-0018. Every character name the game ships is captured here at gameplay distance, in two studio views, and in the three animation poses the runtime drives.

What changed since the first review

The first pass was signed off with follow-ups and rejected three checklist rows: faces at portrait distance, hands and hand-held gear, and head gear on the skull. The body findings were all build defects, not art. This revision covers what was fixed and what is still open.

Owner finding	Cause	Status
npc_guard holes in the upper body	the build deleted the Worker_Vest material, and on the modular Worker the vest is the torso	fixed — the vest is the cloth slot, nothing is deleted
npc_firefighter, npc_crowd_d broken shoulders	same, plus the deleted Worker_Yellow hat was the skull crown	fixed — the crown stays and takes the hair tint
one unibrow on npc_guard, npc_vest, npc_crowd_d	the Worker's Eyebrows is one bar across the face and its eye quads are oversized	fixed — the bar is cut, the hoodie's brows are transplanted 20 mm above the eye line
Worker roles had no visible eyes	the Worker's own eye quads sit inside the head	fixed — the hoodie's eye pair is transplanted with a 4 mm forward offset
arms intersecting the body on npc_dress, npc_jacket, npc_crowd_a, npc_crowd_d	the baked rest aimed the upper arm straight down, which fails on the narrow bases	reduced — the arm rests 7° out from vertical (mesh width 0.180 → 0.220 on casual, 0.228 → 0.262 on hoodie)
head gear did not sit on the skull	gear is authored around the procedural head centre (1.62); the Quaternius head centre is 1.69	resolved by removal — see below
performer cone swallowed the head	a 0.44 m cone authored for the old body	removed — the performer carries a baton and board in the hands
faces had no mouth at all	none of the three upstream heads carries a mouth material	fixed — a small lip block is placed on the measured skin surface for every base (dark maroon, not tinted)

Hats and head items

The firefighter helmet is the only head gear in the roster. Caps, hoods and the performer cone were removed from the role table, the per-character gear list and the performer props, so no character can hide its face behind a hat. That also retired the head-gear lift/scale compensation the caps needed on the Quaternius head.

Role	Head gear	Body / hand items
npc_firefighter	firefighter helmet	SCBA tank, flashlight
npc_influencer	none	sunglasses, shoulder bag, phone
npc_tourist	none	backpack, camera
npc_authorized_guest	none	lanyard
npc_performer	none	baton and board in the hands
npc_protester	none	pole and sign in the hands
every other role	none	role tint only

1. Full-body roster (12 roles)

One tile per shipped character, neutral studio, camera at 4.2 m.

2. Front and profile per role

Front set, then profile. Use this for silhouette, head size and gear placement without perspective hiding anything.

3. Crowd distance (8 m)

The distance the player actually sees a passer-by from the sidewalk.

4. Animation poses (idle / sit / walk contact)

Six roles × three poses, driven by the real _animate() path with the FSM frozen. Check that arms hang instead of holding an A-pose, the seated pose puts the forearms on the thighs with the shins down, walk contact keeps contralateral opposition, and nothing pinches or detaches at the shoulder, elbow, hip or knee.

Signoff checklist

Tick a verdict per row. A rejected row becomes a concrete TODO.md task, not an opinion.

#	Question	Verdict
1	Do the twelve characters read as distinct people at 8 m?	x yes ☐ no
2	Is the head size right for the body (no bobblehead, no pinhead)?	x yes ☐ no
3	Do the faces hold up at portrait distance — brows, eyes, mouth, hair?	x yes ☐ no
4	Do the hands and the hand-held items (camera, clipboard, board, baton, parcel) read correctly?	☐ yes x no
5	Is the firefighter helmet the only head gear, and does it sit correctly?	x yes ☐ no
6	Are the role outfits believable for a Hollywood-boulevard shift?	x yes ☐ no
7	Are the seeded tint palettes acceptable, or too pastel/saturated?	x yes ☐ no
8	Do the seated and walking poses hold up?	x yes ☐ no

Signoff: ☐ approved as shipped ☐ approved with the follow-ups below ☐ rejected

Still open

Recorded as tasks in TODO.md under Owner review findings:

1. Eyes have no whites. Every base uses single-colour quads, so eyes read as dark rectangles at portrait distance. A light sclera plus pupil on the Eye slot would finish the face.
2. Hands and hand-held gear — measured and re-fitted. fit now measures hand gear against the Quaternius wrist (y 1.017) and reports size_vs_head, which turned "reads oversized" into a number. Only the clipboard was genuinely mis-authored (grip in the middle of the board); it now grips the top edge. The delivery parcel and the confused-visitor tray became carried props in the hands, and the cap/hood gear were retired with the hats, leaving a 15-piece set. The per-item table is in blender-assets.md. After the owner's grip-height feedback every hand item drops into the palm (HAND_ITEM_DROP), the carried role props drop 0.06 m and the lanyard attach rose from y 1.30 to 1.38. Each piece is now also captured worn by a real avatar (sheet_npc_gear_on_character.jpg) — check row 4 against that sheet. Row 4 is the one still needing an owner verdict.
3. Arms still graze the torso on the worker base — the 7° rest tilt cleared the casual base but not this one.
4. The npc_vest clipboard is oversized on the shorter Quaternius arm.
5. Roster variety is three meshes for twelve roles. Tint and gear carry the difference; the modular part library (hair, outfits) is the fix.
6. npc_dress and npc_hoodie have no coat or dress geometry — they are the casual/hoodie bases with a matching tint.

Measured facts

Metric	Value
Characters	12, all on the Quaternius 62-joint rig
Triangles per character	4,458 (worker, before the head transplant) … 6,424 (casual)
glTF vertices per character	9,370 … 13,440
Budget	24,000 tris / 24,000 verts per character
Tint slots	skin, cloth, pants, hair, accessory, plus fixed detail
Texel density	73–74 px/m on the 256² maps
Height	1.82–1.88 m
24-NPC frame budget	174,976 tris, 0.85 ms average frame (budget 50 ms)
Gates	inspect clean, audit 12/12, fit OK, Godot 278/278, Python 167/167

Reproducing the captures

godot --path . --script res://src/test/capture_npc_baseline.gd -- --out=res://tmp/npc-signoff
godot --path . --script res://src/test/capture_npc_pose.gd \
  --out=res://tmp/npc-signoff-pose --pose=idle   # repeat for sit and walk_contact

History

The page previously carried the 0.9.4 procedural library baseline (eight hand-built characters, the face/hand/neck fixes, the 13-core proportion audit). That mesh no longer ships; its comparison sheets stay in blender_previews/ as records: sheet_npc_baseline_compare-p1.jpg, -body.jpg, -torso.jpg, -face-detail.jpg, sheet_npc_hands_compare.jpg, sheet_npc_hands_grip_compare.jpg.

Per-character sources and build steps are in npc-model-sourcing.md; the face options that led to the full swap are in screens/npc-face-gate/.