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](adr/0017-quaternius-npc-base.md) and
[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md). 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 |

## 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.

![NPC roster full body](blender_previews/sheet_npc_roster_0.9.9.jpg)

## 2. Front and profile per role

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

![NPC roster front and profile](blender_previews/sheet_npc_roster_views_0.9.9.jpg)

## 3. Crowd distance (8 m)

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

![NPC roster at crowd distance](blender_previews/sheet_npc_roster_crowd_0.9.9.jpg)

## 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.

![NPC roster poses](blender_previews/sheet_npc_roster_poses_0.9.9.jpg)

## 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? | ☐ yes ☐ no |
| 2 | Is the head size right for the body (no bobblehead, no pinhead)? | ☐ yes ☐ no |
| 3 | Do the faces hold up at portrait distance — brows, eyes, mouth, hair? | ☐ yes ☐ no |
| 4 | Do the hands and the hand-held items (camera, clipboard, board, baton) read correctly? | ☐ yes ☐ no |
| 5 | Is the firefighter helmet the only head gear, and does it sit correctly? | ☐ yes ☐ no |
| 6 | Are the role outfits believable for a Hollywood-boulevard shift? | ☐ yes ☐ no |
| 7 | Are the seeded tint palettes acceptable, or too pastel/saturated? | ☐ yes ☐ no |
| 8 | Do the seated and walking poses hold up? | ☐ 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. **Arms still graze the torso on the `worker` base** — the 7° rest tilt cleared the `casual` base
   but not this one.
3. **The `npc_vest` clipboard is oversized** on the shorter Quaternius arm.
4. **Roster variety is three meshes for twelve roles.** Tint and gear carry the difference; the
   modular part library (hair, outfits) is the fix.
5. `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

```sh
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`](npc-model-sourcing.md); the face options that led to the full swap are in
[`screens/npc-face-gate/`](screens/npc-face-gate/README.md).