Move _head_proto into blender_assets.py and add assemble --head-proto; verify prototype weights

tools/blender_assets.py

@@ -855,6 +855,116 @@ def _face(mats, spec):
     return parts
 
 
+def _head_proto(mats, spec, subdiv=48):
+    """Connected head shell with sculpted sockets, nose, lips, ears and brow/cheek/jaw.
+
+    The model-overhaul prototype: the skin features are displaced out of one
+    head mesh instead of floating spheres, so the face is a single connected
+    surface with loop-based eye sockets and protruding nose/lip/ear volumes. The
+    eyeballs (sclera/iris/lids) stay separate — they are not skin. Blender Z-up,
+    face front −Y. `subdiv` is the UV-sphere u-segments (24/48/64 variants); s48
+    is the chosen default after the 1.5 m/1.85 m comparison.
+    """
+    skin, acc, hair = mats["skin"], mats["accessory"], mats["hair"]
+    white = material("eye_white", textured_solid=True)
+    rings = max(14, subdiv // 2 + 2)
+    head = sphere("HeadShell", 0.155, (0, 0, 1.635), skin, seg=subdiv, rings=rings,
+                  scale=(0.90, 0.96, 1.08))
+    _shape_head_mesh(head)  # brow ridge + cheekbone + jaw/chin planes
+    bm = bmesh.new()
+    bm.from_mesh(head.data)
+
+    # Pass 1: skull shape — flatten the face plane and taper the jaw/chin.
+    for v in bm.verts:
+        x, y, z = v.co
+        if y < -0.03 and 1.44 < z < 1.76:
+            v.co.y = -0.13 + (y + 0.13) * 0.10  # flatten the forward bulge
+        if y < -0.03 and z > 1.70:
+            v.co.y += (z - 1.70) * 0.35  # forehead slopes back to the crown
+        if z < 1.58:
+            taper = max(0.0, 1.0 - (1.58 - z) / 0.12)
+            v.co.x *= 1.0 - 0.16 * taper  # narrow the lower face
+
+    # Pass 2: features on the flattened face.
+    for v in bm.verts:
+        x, y, z = v.co
+        ax = abs(x)
+        # --- brow step ---
+        brow = (max(0.0, 1.0 - abs(z - 1.695) / 0.022)
+                * max(0.0, 1.0 - abs(ax - 0.050) / 0.045))
+        if brow > 0:
+            v.co.y -= 0.016 * brow
+        # --- eye sockets: recess the floor, leave a raised orbital rim ---
+        for s in (-1.0, 1.0):
+            r = math.hypot(x - 0.052 * s, z - 1.664)
+            if r < 0.036:
+                v.co.y += 0.018 * (1.0 - r / 0.036)
+            elif r < 0.046:
+                v.co.y -= 0.010 * (1.0 - (r - 0.036) / 0.010)
+        # --- nose: a wide bridge/tip with ala wings ---
+        if y < 0 and ax < 0.075:
+            band = max(0.0, 1.0 - abs(z - 1.632) / 0.055)
+            if band > 0:
+                tip = max(0.0, 1.0 - abs(z - 1.615) / 0.032)
+                v.co.y -= (0.060 * tip + 0.018 * max(0.0, band - tip)) \
+                          * (1.0 - ax / 0.075)
+            for s in (-1.0, 1.0):
+                ar = math.hypot((x - 0.024 * s) / 0.014, (z - 1.604) / 0.013)
+                if ar < 1.0:
+                    v.co.y -= 0.022 * (1.0 - ar)
+        # --- chin bump + jaw step ---
+        if y < 0 and ax < 0.040:
+            chin = max(0.0, 1.0 - abs(z - 1.548) / 0.022)
+            if chin > 0:
+                v.co.y -= 0.030 * chin
+            step = max(0.0, 1.0 - abs(z - 1.516) / 0.016)
+            if step > 0:
+                v.co.y += 0.024 * step
+        # --- mouth: recessed line + upper/lower lip volumes ---
+        if y < 0 and ax < 0.030:
+            if abs(z - 1.583) < 0.012:
+                v.co.y += 0.008
+            if abs(z - 1.590) < 0.008:
+                v.co.y -= 0.014
+            if abs(z - 1.577) < 0.010:
+                v.co.y -= 0.018
+    # --- ears: helix rim + concha recess + a lobe ---
+    for v in bm.verts:
+        x, y, z = v.co
+        r = math.hypot((z - 1.60) / 0.055, (y - 0.002) / 0.045)
+        near = abs(x) - 0.138
+        sign = 1.0 if x >= 0 else -1.0
+        if -0.02 < near < 0.06 and r < 1.0:
+            if r < 0.30:
+                v.co.x -= 0.018 * (1.0 - r / 0.30) * sign
+            else:
+                v.co.x += 0.045 * (1.0 - r) * sign
+        lr = math.hypot((z - 1.575) / 0.016, (y + 0.012) / 0.016)
+        if -0.02 < near < 0.05 and lr < 1.0:
+            v.co.x += 0.032 * (1.0 - lr) * sign
+    bm.normal_update()
+    bm.to_mesh(head.data)
+    bm.free()
+
+    # Eyeballs stay separate for readability; lids wrap the socket rim.
+    parts = [head]
+    for s in (-1.0, 1.0):
+        ex, ey, ez = 0.052 * s, -0.134, 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, ey - 0.006, 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, ey - 0.004, 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.143, 1.699),
+                         hair, rot=(0, 0.14 * s, 0.0)))
+    return parts
+
+
 def _hands_and_shoes(mats, spec):
     skin = mats["skin"]
     shoe = mats["accessory"]
@@ -986,7 +1096,7 @@ def _clothing(spec, mats):
     return parts
 
 
-def build_character(name):
+def build_character(name, head_proto=False):
     spec = dict(CHARACTERS[name])
     if name == "npc_hoodie":
         spec["beard"] = True
@@ -1001,7 +1111,7 @@ def build_character(name):
     _assign_body_slots(body, spec, body_mats)
     _auto_weights(body, layout)
 
-    head_parts = _face(mats, spec)
+    head_parts = _head_proto(mats, spec) if head_proto else _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")