Add a gear-vs-body fit report to the Blender asset tool

`blender_assets.py fit` measures each character head width (skin vertices
weighted to Head in y 1.55-1.81) and clothing radius (cloth skirt in y 0.30-0.52,
pants hip fallback), then prints every attached head/back/chest gear bounding box
with head-band status and x/radial skirt clearance. The report confirms the
glasses width and shoulder-bag coat clip, giving the next fit fixes numbers.
Python tooling 87/87; asset audit clean.

tools/blender_assets.py

@@ -14,6 +14,7 @@ integration: nothing in the game loads them yet (see
       --python "$PWD/tools/blender_assets.py" -- render
     # outside Blender (stdlib + Pillow)
     python3 tools/blender_assets.py audit      # GLB contract checks
+    python3 tools/blender_assets.py fit        # gear-vs-body fit measurements
     python3 tools/blender_assets.py sheet      # sheet_<category>.jpg (committed)
     python3 tools/blender_assets.py list
 
@@ -104,6 +105,14 @@ GEAR_ATTACH = {
 # Same attach points in Blender coordinates (Godot (x, y, z) -> Blender (x, -z, y)).
 ATTACH_BLENDER = {"head": (0.0, 0.0, 1.62), "hand": (0.27, -0.02, 0.78),
                   "back": (0.0, 0.0, 1.10), "chest": (0.0, 0.0, 1.30)}
+# Attach points in the authored GLB space (Godot coordinates), used by `fit`.
+ATTACH_GODOT = {"head": (0.0, 1.62, 0.0), "hand": (0.27, 0.78, 0.02),
+                "back": (0.0, 1.10, 0.0), "chest": (0.0, 1.30, 0.0)}
+HEAD_BAND = (1.55, 1.81)  # face/headgear height band in Godot metres
+FIT_HEAD_MATERIALS = ("skin",)
+FIT_CLOTHING_MATERIAL = "cloth"
+FIT_CLOTHING_BAND = (0.30, 0.52)  # hip/skirt band; captures coat/dress flare
+FIT_HIP_BAND = (0.55, 0.95)  # fallback body radius for trousers/vests
 GEAR = {
     "cap": "head", "beanie": "head", "hood": "head", "sunglasses": "head",
     "firefighter_helmet": "head",
@@ -1672,6 +1681,117 @@ def audit_asset(category, name):
     return res
 
 
+def character_fit_reference(name):
+    """Measure a character's head width and hip/skirt radius from its GLB.
+
+    Head width uses skin/hair vertices whose strongest joint is Head inside the
+    fixed head band. Clothing radius uses the cloth vertices in the hip/skirt
+    band. Both are reported in metres and rounded to millimetres.
+    """
+    path = asset_path("npc", name)
+    if not path.is_file():
+        return None
+    try:
+        _magic, _version, _length, _size, gltf, binary = _read_glb(path)
+    except (struct.error, ValueError, KeyError):
+        return None
+    nodes = gltf.get("nodes", [])
+    joints = [nodes[j].get("name", "") for j in gltf.get("skins", [{}])[0].get("joints", [])]
+    materials = [m.get("name", "") for m in gltf.get("materials", [])]
+    head_x: list[float] = []
+    head_y: list[float] = []
+    cloth_x: list[float] = []
+    hip_x: list[float] = []
+    for mesh in gltf.get("meshes", []):
+        for prim in mesh.get("primitives", []):
+            attrs = prim.get("attributes", {})
+            if "POSITION" not in attrs or "JOINTS_0" not in attrs or "WEIGHTS_0" not in attrs:
+                continue
+            mat_index = prim.get("material")
+            mat_name = materials[mat_index] if mat_index is not None and mat_index < len(materials) else ""
+            positions = _accessor(gltf, binary, attrs["POSITION"])
+            joint_rows = _accessor(gltf, binary, attrs["JOINTS_0"])
+            weight_rows = _accessor(gltf, binary, attrs["WEIGHTS_0"])
+            for pos, joint_row, weight_row in zip(positions, joint_rows, weight_rows):
+                strongest = max(range(4), key=lambda i: weight_row[i])
+                bone = joints[joint_row[strongest]] if joint_row[strongest] < len(joints) else ""
+                if (mat_name in FIT_HEAD_MATERIALS and bone == "Head"
+                        and weight_row[strongest] > 0.5 and HEAD_BAND[0] <= pos[1] <= HEAD_BAND[1]):
+                    head_x.append(pos[0])
+                    head_y.append(pos[1])
+                if (mat_name == FIT_CLOTHING_MATERIAL
+                        and FIT_CLOTHING_BAND[0] <= pos[1] <= FIT_CLOTHING_BAND[1]):
+                    cloth_x.append(pos[0])
+                if (mat_name == "pants"
+                        and FIT_HIP_BAND[0] <= pos[1] <= FIT_HIP_BAND[1]):
+                    hip_x.append(pos[0])
+    skirt_radius = max(abs(x) for x in cloth_x) if cloth_x else 0.0
+    hip_radius = max(abs(x) for x in hip_x) if hip_x else 0.0
+    clothing_radius = max(skirt_radius, hip_radius)
+    return {
+        "head_width": round(max(head_x) - min(head_x), 3) if head_x else 0.0,
+        "head_y_min": round(min(head_y), 3) if head_y else 0.0,
+        "head_y_max": round(max(head_y), 3) if head_y else 0.0,
+        "clothing_radius": round(clothing_radius, 3),
+        "clothing_source": "skirt" if skirt_radius >= hip_radius and skirt_radius > 0 else "hip",
+        "head_band": HEAD_BAND,
+    }
+
+
+def _gear_fit(name, reference):
+    attach = GEAR.get(name)
+    if attach not in ("head", "back", "chest"):
+        return None
+    audit = audit_asset("npc_gear", name)
+    bounds = audit.get("bounds")
+    if not bounds:
+        return None
+    offset = ATTACH_GODOT[attach]
+    lo = [bounds["min"][i] + offset[i] for i in range(3)]
+    hi = [bounds["max"][i] + offset[i] for i in range(3)]
+    result = {
+        "name": name,
+        "attach": attach,
+        "min": [round(v, 3) for v in lo],
+        "max": [round(v, 3) for v in hi],
+    }
+    if attach == "head":
+        result.update({
+            "width": round(hi[0] - lo[0], 3),
+            "width_ratio": round((hi[0] - lo[0]) / reference["head_width"], 3)
+            if reference["head_width"] else 0.0,
+            "inside_band": lo[1] >= HEAD_BAND[0] - 0.005 and hi[1] <= HEAD_BAND[1] + 0.005,
+        })
+    else:
+        # Compare the widest point (|x|) and the corner radial extent with the
+        # skirt flare. The radial value catches bags that sit diagonally out.
+        x_extent = max(abs(lo[0]), abs(hi[0]))
+        radial = max(math.hypot(x, z) for x in (lo[0], hi[0]) for z in (lo[2], hi[2]))
+        result.update({
+            "x_extent": round(x_extent, 3),
+            "radial": round(radial, 3),
+            "x_clearance": round(reference["clothing_radius"] - x_extent, 3),
+            "radial_clearance": round(reference["clothing_radius"] - radial, 3),
+        })
+    return result
+
+
+def fit_report():
+    """Return per-character gear fit measurements for the `fit` command/tests."""
+    report = []
+    for character, spec in CHARACTERS.items():
+        reference = character_fit_reference(character)
+        if reference is None:
+            continue
+        rows = []
+        for gear_name in spec.get("gear", []):
+            row = _gear_fit(gear_name, reference)
+            if row:
+                rows.append(row)
+        report.append({"character": character, "reference": reference, "gear": rows})
+    return report
+
+
 def write_manifest(results):
     out = {"generator": "tools/blender_assets.py", "attach_points": GEAR_ATTACH,
            "assets": {}}
@@ -1735,6 +1855,8 @@ def main(argv=None):
         s.add_argument("--only", default="")
     a = sub.add_parser("audit")
     a.add_argument("--json", action="store_true")
+    fit = sub.add_parser("fit")
+    fit.add_argument("--json", action="store_true")
     sub.add_parser("sheet")
     sub.add_parser("list")
     args = ap.parse_args(raw)
@@ -1766,6 +1888,35 @@ def main(argv=None):
     if args.cmd == "sheet":
         contact_sheets()
         return 0
+    if args.cmd == "fit":
+        report = fit_report()
+        if not report:
+            print("no built character assets; run build first", file=sys.stderr)
+            return 2
+        if args.json:
+            print(json.dumps(report, indent=2))
+        else:
+            for entry in report:
+                ref = entry["reference"]
+                print(f"{entry['character']:16s} head_width={ref['head_width']:.3f} m  "
+                      f"clothing_radius={ref['clothing_radius']:.3f} m "
+                      f"({ref['clothing_source']})")
+                for row in entry["gear"]:
+                    lo, hi = row["min"], row["max"]
+                    box = (f"x=[{lo[0]:+.3f},{hi[0]:+.3f}] "
+                           f"y=[{lo[1]:+.3f},{hi[1]:+.3f}] "
+                           f"z=[{lo[2]:+.3f},{hi[2]:+.3f}]")
+                    if row["attach"] == "head":
+                        flag = "inside" if row["inside_band"] else "OUTSIDE"
+                        print(f"  {row['name']:20s} head  {box}  "
+                              f"width={row['width']:.3f} ({row['width_ratio']:.2f}x head) "
+                              f"band={flag}")
+                    else:
+                        clip = "CLIP" if row["x_clearance"] < 0 else "clear"
+                        print(f"  {row['name']:20s} {row['attach']:5s} {box}  "
+                              f"clearance x={row['x_clearance']:+.3f} "
+                              f"r={row['radial_clearance']:+.3f} {clip}")
+        return 0
     results = [audit_asset(c, n) for c, n in catalogue()]
     if args.json:
         print(json.dumps(results, indent=2))