Add the MakeHuman-head character head source (head=mh) with project eyes/brows/mouth and CC0 attribution

tools/blender_assets.py

@@ -965,6 +965,72 @@ def _head_proto(mats, spec, subdiv=48):
     return parts
 
 
+def _makehuman_head(mats, spec):
+    """MakeHuman head shape plus the project's eye/mouth/brow pieces.
+
+    The AI-judged head rework (2026-11-04) picked the decimated MakeHuman head
+    over the displacement shell: it keeps the nose/chin/jaw landmarks at 1,573
+    tris. The MakeHuman mesh has no eyeballs, so the project's sclera/iris/lid/
+    brow pieces are added at the MakeHuman landmarks (eyes ≈ ±0.052, −0.160,
+    1.664) for readability. Blender Z-up, face front −Y.
+    """
+    skin, acc, hair = mats["skin"], mats["accessory"], mats["hair"]
+    white = material("eye_white", textured_solid=True)
+    src = SRC_DIR / "makehuman_head.glb"
+    before = {o.name for o in bpy.context.scene.objects}
+    bpy.ops.import_scene.gltf(filepath=str(src))
+    # Drop the imported armature / glTF neutral bone; build_character re-weights
+    # the head to the contract rig.
+    for a in list(bpy.context.scene.objects):
+        if a.type == "ARMATURE" and a.name not in before:
+            bpy.data.objects.remove(a, do_unlink=True)
+    # Pick the newly imported mesh, not the already-built body.
+    head = next((o for o in bpy.context.scene.objects
+                 if o.type == "MESH" and o.name not in before
+                 and o.data.materials), None)
+    if head is None:
+        raise SystemExit(f"no head mesh in {src}")
+    head.name = "HeadShell"
+    # The decimated MakeHuman "hair" scalp slot reads as shaggy shards; collapse
+    # the head to one skin slot so the join does not collide with the body's
+    # cloth/pants slots (the project `_hair` cap provides hair later).
+    head.data.materials.clear()
+    head.data.materials.append(skin)
+    # Clean the ragged neck cut left by the Head-group extraction: bisect below
+    # the jaw and cap the hole so the head ends on a clean solid underside.
+    bm = bmesh.new()
+    bm.from_mesh(head.data)
+    bmesh.ops.bisect_plane(bm, geom=bm.verts[:] + bm.edges[:] + bm.faces[:],
+                           plane_co=(0, 0, 1.50), plane_no=(0, 0, -1),
+                           clear_outer=True)
+    boundary = [e for e in bm.edges if e.is_boundary]
+    if boundary:
+        bmesh.ops.holes_fill(bm, edges=boundary)
+    bm.to_mesh(head.data)
+    bm.free()
+    parts = [head]
+    for s in (-1.0, 1.0):
+        # The MakeHuman socket is a deep cavity (floor ≈ −0.105); keep the
+        # sclera recessed so it never breaks the face silhouette.
+        ex, ey, ez = 0.052 * s, -0.125, 1.664
+        parts.append(sphere("EyeWhite", 0.019, (ex, ey, ez), white, seg=10,
+                            rings=6, scale=(1.25, 0.62, 0.85)))
+        parts.append(sphere("Iris", 0.0105, (ex, ey - 0.007, ez), acc, seg=8,
+                            rings=5, scale=(1.0, 0.55, 1.0)))
+        parts.append(sphere("UpperLid", 0.020, (ex, -0.135, ez + 0.014),
+                            skin, seg=8, rings=4, scale=(1.20, 0.32, 0.24),
+                            rot=(math.radians(-10), 0, 0)))
+        parts.append(sphere("LowerLid", 0.017, (ex, -0.135, ez - 0.012),
+                            skin, seg=8, rings=4, scale=(1.10, 0.22, 0.18),
+                            rot=(math.radians(6), 0, 0)))
+        parts.append(box("Brow", (0.055, 0.014, 0.012), (0.052 * s, -0.165, 1.705),
+                         hair, rot=(0, 0.14 * s, 0.0)))
+    # A subtle mouth line on top of the MakeHuman lips for readability.
+    parts.append(sphere("Mouth", 0.028, (0, -0.165, 1.58), acc, seg=8, rings=5,
+                        scale=(1.0, 0.28, 0.12)))
+    return parts
+
+
 def _hands_and_shoes(mats, spec):
     skin = mats["skin"]
     shoe = mats["accessory"]
@@ -1122,7 +1188,10 @@ def _clothing(spec, mats):
     return parts
 
 
-def build_character(name, head_proto=False):
+def build_character(name, head="face"):
+    """Build one character. `head` picks the head source: "face" (current
+    primitive face), "proto" (connected-shell displacement prototype) or
+    "mh" (decimated MakeHuman head + project eyes/brows/mouth)."""
     spec = dict(CHARACTERS[name])
     if name == "npc_hoodie":
         spec["beard"] = True
@@ -1137,7 +1206,12 @@ def build_character(name, head_proto=False):
     _assign_body_slots(body, spec, body_mats)
     _auto_weights(body, layout)
 
-    head_parts = _head_proto(mats, spec) if head_proto else _face(mats, spec)
+    if head == "mh":
+        head_parts = _makehuman_head(mats, spec)
+    elif head == "proto":
+        head_parts = _head_proto(mats, spec)
+    else:
+        head_parts = _face(mats, spec)
     hair_style = spec["hair"] if spec["layer"] != "hood" else "buzz"
     head_parts += _hair(hair_style, mats["hair"])
     head = join(head_parts, "head")