Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

45.3 KB
Raw Blame
"""Build every shipped figure GLB — bases and parts — from its recorded source, inside Blender.

    blender -b --python scripts/figures/build_figures.py -- [--out <dir>] [--target biped-rogue]

The ONLY producer of the GLBs under ``src/assets/society/figures/`` and of the
``catalog.json`` the creator reads (docs/agent-society/character-pipeline.md §7).
Per target in ``contract.json``:

1. fetch the source file named in ``sources/<source>.json`` into ``cache/``
   (gitignored) and verify its sha256 — a build never touches an unverified byte;
2. import it, keep the base body meshes and the listed accessories, drop
   IK/control bones, rename the deform bones to the archetype's contract names;
3. keep only the clips the archetype needs, rename them, zero the root's XZ
   motion (locomotion is the runtime's job), close the loops;
4. join the body into one mesh, re-UV every face onto the 16-cell palette strip
   of a fresh 128×128 sheet (nearest-filtered); hair faces get their own
   material slot so headgear can hide them;
5. add the ``FWD`` marker, export the base as a binary glTF;
6. turn every accessory into a part: unparent it at rest, skin it to its
   attach bone with weight 1, re-UV, export it without clips;
7. finish each file with stdlib tools (strip constant channels, prune, write
   ``asset.extras``), run the CI gate on it, and regenerate ``catalog.json`` and
   ``SOURCES.md`` from what was built.

Runs on Windows, macOS and Linux (Blender needs no display in ``-b`` mode). It
never imports ``dodaios.*``: Blender ships its own interpreter.
"""

from __future__ import annotations

import argparse
import hashlib
import importlib.util
import json
import re
import sys
import urllib.request
from pathlib import Path

import bpy  # type: ignore[import-not-found]

HERE = Path(__file__).resolve().parent
REPO = HERE.parents[1]
CACHE = HERE / "cache"
sys.path.insert(0, str(HERE))
import glb_tools as gt  # noqa: E402

CONTRACT = json.loads((HERE / "contract.json").read_text(encoding="utf-8"))
DEFAULT_OUT = REPO / "dodaios/ui/web/frontend/src/assets/society/figures"
CATALOG_PATH = REPO / "dodaios/ui/web/frontend/src/components/society/figures/catalog.json"


def log(msg: str) -> None:
    print(f"[figures] {msg}", flush=True)


# ---------------------------------------------------------------------------
# sources
# ---------------------------------------------------------------------------


def load_source(name: str) -> dict:
    return json.loads((HERE / "sources" / f"{name}.json").read_text(encoding="utf-8"))


def source_slug(source: dict) -> str:
    return re.sub(r"[^a-z0-9]+", "-", source["name"].lower()).strip("-")


def fetch_source_file(source: dict, filename: str) -> Path:
    CACHE.mkdir(exist_ok=True)
    expected = source["files"][filename]
    dest = CACHE / f"{source_slug(source)}-{filename}"
    if not dest.exists():
        url = source["base_url"] + filename
        log(f"fetching {url}")
        with urllib.request.urlopen(url, timeout=120) as resp:  # noqa: S310 - pinned URL + sha256
            dest.write_bytes(resp.read())
    digest = hashlib.sha256(dest.read_bytes()).hexdigest()
    if digest != expected:
        raise SystemExit(f"{dest.name}: sha256 {digest} != recorded {expected}; refusing to build")
    return dest


# ---------------------------------------------------------------------------
# Blender helpers
# ---------------------------------------------------------------------------


def reset_scene() -> None:
    bpy.ops.wm.read_factory_settings(use_empty=True)


def import_glb(path: Path, fps: int) -> None:
    # Keys land on frames at the SCENE rate; at the source's own rate they sit
    # on integer frames, so the export samples every key exactly and a loop
    # closed on the last key stays closed after sampling.
    bpy.context.scene.render.fps = fps
    bpy.ops.import_scene.gltf(filepath=str(path), import_shading="NORMALS")


def find_armature() -> bpy.types.Object:
    arms = [o for o in bpy.data.objects if o.type == "ARMATURE"]
    if len(arms) != 1:
        raise SystemExit(f"expected exactly one armature, found {[a.name for a in arms]}")
    return arms[0]


def iter_fcurves(action: bpy.types.Action):
    """Every F-curve of an action across the legacy and the slotted API."""
    seen = False
    try:
        for fc in action.fcurves:
            seen = True
            yield fc
    except (AttributeError, RuntimeError):
        seen = False
    if seen:
        return
    for layer in getattr(action, "layers", []):
        for strip in layer.strips:
            for bag in getattr(strip, "channelbags", []):
                yield from bag.fcurves


def remove_fcurve(action: bpy.types.Action, fc) -> None:
    try:
        action.fcurves.remove(fc)
        return
    except (AttributeError, RuntimeError):
        pass
    for layer in getattr(action, "layers", []):
        for strip in layer.strips:
            for bag in getattr(strip, "channelbags", []):
                if fc in list(bag.fcurves):
                    bag.fcurves.remove(fc)
                    return


def select_only(objects: list[bpy.types.Object], active: bpy.types.Object) -> None:
    for obj in bpy.data.objects:
        obj.select_set(False)
    for obj in objects:
        obj.select_set(True)
    bpy.context.view_layer.objects.active = active


def set_mode(obj: bpy.types.Object, mode: str) -> None:
    select_only([obj], obj)
    bpy.ops.object.mode_set(mode=mode)


def bone_name_of(data_path: str) -> str | None:
    m = re.match(r'pose\.bones\["([^"]+)"\]', data_path)
    return m.group(1) if m else None


# ---------------------------------------------------------------------------
# normalization steps
# ---------------------------------------------------------------------------


def keep_objects(arm: bpy.types.Object, names: set[str]) -> dict[str, bpy.types.Object]:
    kept: dict[str, bpy.types.Object] = {}
    for obj in list(bpy.data.objects):
        if obj is arm:
            continue
        if obj.type == "MESH" and obj.name in names:
            kept[obj.name] = obj
            continue
        bpy.data.objects.remove(obj, do_unlink=True)
    missing = names - set(kept)
    if missing:
        raise SystemExit(f"objects not found in source: {sorted(missing)}")
    return kept


def drop_bones(arm: bpy.types.Object, patterns: list[str]) -> list[str]:
    victims = [b.name for b in arm.data.bones if any(p in b.name for p in patterns)]
    set_mode(arm, "EDIT")
    for name in victims:
        eb = arm.data.edit_bones.get(name)
        if eb is not None:
            arm.data.edit_bones.remove(eb)
    bpy.ops.object.mode_set(mode="OBJECT")
    for action in bpy.data.actions:
        for fc in list(iter_fcurves(action)):
            if bone_name_of(fc.data_path) in victims:
                remove_fcurve(action, fc)
    return victims


def rename_bones(arm: bpy.types.Object, bone_map: dict[str, str], expected: list[str]) -> None:
    for old, new in bone_map.items():
        bone = arm.data.bones.get(old)
        if bone is None:
            raise SystemExit(f"bone {old!r} missing in source armature")
        bone.name = new
    have = {b.name for b in arm.data.bones}
    extra = have - set(expected)
    missing = set(expected) - have
    if extra or missing:
        raise SystemExit(f"bone set mismatch: extra={sorted(extra)} missing={sorted(missing)}")


def filter_clips(clip_map: dict[str, str], clip_spec: dict) -> dict[str, bpy.types.Action]:
    by_source = {v: k for k, v in clip_map.items()}
    kept: dict[str, bpy.types.Action] = {}
    for action in list(bpy.data.actions):
        target = by_source.get(action.name)
        if target is None:
            bpy.data.actions.remove(action)
            continue
        action.name = target
        action.use_fake_user = True
        kept[target] = action
    missing = set(clip_spec) - set(kept)
    if missing:
        raise SystemExit(f"clips missing in source: {sorted(missing)} (have {sorted(kept)})")
    return kept


def normalize_clip(action: bpy.types.Action, loop: bool) -> None:
    for fc in iter_fcurves(action):
        bone = bone_name_of(fc.data_path)
        keys = fc.keyframe_points
        if not len(keys):
            continue
        if bone == "root" and fc.data_path.endswith(".location") and fc.array_index in (0, 2):
            for k in keys:
                k.co[1] = 0.0
                k.handle_left[1] = 0.0
                k.handle_right[1] = 0.0
        if loop and len(keys) > 1:
            keys[-1].co[1] = keys[0].co[1]
        fc.update()


def tag_origin(objects: list[bpy.types.Object]) -> dict[str, str]:
    """Remember which source object each polygon came from (per-mesh cell overrides)."""
    names: dict[str, str] = {}
    for n, obj in enumerate(objects):
        attr = obj.data.attributes.get("jarvis_origin") or obj.data.attributes.new(
            "jarvis_origin", "INT", "FACE"
        )
        for poly in obj.data.polygons:
            attr.data[poly.index].value = n
        names[str(n)] = obj.name
    return names


def join_bodies(bodies: list[bpy.types.Object]) -> bpy.types.Object:
    select_only(bodies, bodies[0])
    if len(bodies) > 1:
        bpy.ops.object.join()
    body = bpy.context.view_layer.objects.active
    body.name = "Body"
    body.data.name = "Body"
    return body


def cell_of(u: float, v_bottom_up: float, grid: dict) -> str:
    col = min(int(u * grid["columns"]), grid["columns"] - 1)
    row = min(int((1.0 - v_bottom_up) * grid["rows"]), grid["rows"] - 1)
    return f"c{col}r{row}"


def reuv_to_palette(
    obj: bpy.types.Object,
    source_names: dict[str, str],
    cell_map: dict,
    grid: dict,
    fallback: dict | None = None,
) -> dict:
    """Move every face's UVs onto its semantic palette cell; tag hair faces; report."""
    sheet = CONTRACT["sheet"]
    cells = sheet["cells"]
    mesh = obj.data
    uv_layer = mesh.uv_layers.active
    if uv_layer is None:
        raise SystemExit(f"{obj.name} has no UV layer")
    origin = mesh.attributes.get("jarvis_origin")
    used: dict[str, int] = {}
    unmapped: dict[str, int] = {}
    hair_faces: list[int] = []
    for poly in mesh.polygons:
        us = [uv_layer.data[li].uv[0] for li in poly.loop_indices]
        vs = [uv_layer.data[li].uv[1] for li in poly.loop_indices]
        cell = cell_of(sum(us) / len(us), sum(vs) / len(vs), grid)
        obj_name = source_names.get(str(origin.data[poly.index].value), "*") if origin else "*"
        semantic = (
            cell_map.get(obj_name, {}).get(cell)
            or cell_map.get("*", {}).get(cell)
            or (fallback or {}).get(cell)
        )
        if semantic is None:
            unmapped[cell] = unmapped.get(cell, 0) + 1
            semantic = "primary"
        idx = cells.index(semantic)
        used[semantic] = used.get(semantic, 0) + 1
        if semantic == "hair":
            hair_faces.append(poly.index)
        cu = (idx + 0.5) / len(cells)
        cv = 1.0 - (sheet["cell_height"] / 2) / sheet["size"]
        for li in poly.loop_indices:
            uv_layer.data[li].uv = (cu, cv)
    if unmapped:
        log(f"WARNING {obj.name}: unmapped atlas cells (painted primary): {unmapped}")
    if origin:
        mesh.attributes.remove(origin)
    return {"used": used, "unmapped": unmapped, "hair_faces": hair_faces}


def hex_rgb(value: str) -> tuple[int, int, int]:
    v = value.lstrip("#")
    return int(v[0:2], 16), int(v[2:4], 16), int(v[4:6], 16)


def write_sheet(path: Path, palette: dict[str, str]) -> None:
    sheet = CONTRACT["sheet"]
    size = sheet["size"]
    cw, ch = sheet["cell_width"], sheet["cell_height"]
    rows: list[bytes] = []
    for y in range(size):
        row = bytearray()
        for x in range(size):
            if y < ch:
                name = sheet["cells"][min(x // cw, len(sheet["cells"]) - 1)]
                r, g, b = hex_rgb(palette[name])
            else:
                r, g, b = (128, 128, 128)
            row += bytes((r, g, b, 255))
        rows.append(bytes(row))
    path.write_bytes(gt.encode_png(size, size, rows, 4))


def sheet_material(name: str, img: bpy.types.Image) -> bpy.types.Material:
    mat = bpy.data.materials.new(name)
    mat.use_nodes = True
    nodes = mat.node_tree.nodes
    links = mat.node_tree.links
    bsdf = nodes.get("Principled BSDF")
    tex = nodes.new("ShaderNodeTexImage")
    tex.image = img
    tex.interpolation = "Closest"
    links.new(tex.outputs["Color"], bsdf.inputs["Base Color"])
    bsdf.inputs["Roughness"].default_value = 1.0
    bsdf.inputs["Metallic"].default_value = 0.0
    return mat


def load_sheet(sheet_path: Path) -> bpy.types.Image:
    img = bpy.data.images.load(str(sheet_path))
    img.colorspace_settings.name = "sRGB"
    return img


def apply_materials(
    obj: bpy.types.Object, img: bpy.types.Image, stem: str, hair_faces: list[int]
) -> None:
    obj.data.materials.clear()
    obj.data.materials.append(sheet_material(f"{stem}-sheet", img))
    if hair_faces:
        # A second slot, same sheet: exports as its own primitive so headgear can hide it.
        obj.data.materials.append(sheet_material(f"{stem}-hair", img))
        for index in hair_faces:
            obj.data.polygons[index].material_index = 1


def add_forward_marker(arm: bpy.types.Object) -> bpy.types.Object:
    fwd = bpy.data.objects.new("FWD", None)
    fwd.empty_display_type = "ARROWS"
    fwd.empty_display_size = 0.2
    # glTF (0, 0.5, 1) == Blender (0, -1, 0.5): the exporter maps Blender -Y to glTF +Z.
    fwd.location = (0.0, -1.0, 0.5)
    fwd.parent = arm
    bpy.context.scene.collection.objects.link(fwd)
    return fwd


def export_glb(path: Path, selection: list[bpy.types.Object], animations: bool) -> None:
    select_only(selection, selection[0])
    bpy.ops.export_scene.gltf(
        filepath=str(path),
        export_format="GLB",
        use_selection=True,
        export_apply=True,
        export_yup=True,
        export_extras=True,
        export_texcoords=True,
        export_normals=True,
        export_tangents=False,
        export_materials="EXPORT",
        export_image_format="AUTO",
        export_skins=True,
        export_def_bones=False,
        export_rest_position_armature=True,
        export_animations=animations,
        export_animation_mode="ACTIONS",
        export_force_sampling=True,
        export_frame_step=1,
        export_optimize_animation_size=True,
        export_leaf_bone=False,
    )


def skin_part_to_bone(part: bpy.types.Object, arm: bpy.types.Object, bone: str) -> None:
    """Unparent the accessory at rest and bind every vertex to its attach bone."""
    arm.data.pose_position = "REST"
    bpy.context.view_layer.update()
    with bpy.context.temp_override(
        active_object=part, object=part, selected_editable_objects=[part], selected_objects=[part]
    ):
        bpy.ops.object.parent_clear(type="CLEAR_KEEP_TRANSFORM")
    select_only([part], part)
    bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
    for group in list(part.vertex_groups):
        part.vertex_groups.remove(group)
    vg = part.vertex_groups.new(name=bone)
    vg.add([v.index for v in part.data.vertices], 1.0, "REPLACE")
    for mod in list(part.modifiers):
        part.modifiers.remove(mod)
    mod = part.modifiers.new("Armature", "ARMATURE")
    mod.object = arm
    part.parent = arm
    part.matrix_parent_inverse.identity()


# ---------------------------------------------------------------------------
# finish (stdlib): extras, samplers, pruning
# ---------------------------------------------------------------------------


def finish_common(glb: gt.Glb, two_sided: bool = False) -> gt.Glb:
    doc = glb.doc
    for sampler in doc.get("samplers", []):
        sampler["magFilter"] = 9728
        sampler["minFilter"] = 9728
        sampler["wrapS"] = 33071
        sampler["wrapT"] = 33071
    if not doc.get("samplers") and doc.get("textures"):
        doc["samplers"] = [{"magFilter": 9728, "minFilter": 9728, "wrapS": 33071, "wrapT": 33071}]
        for tex in doc["textures"]:
            tex["sampler"] = 0
    for mat in doc.get("materials", []):
        mat["alphaMode"] = "OPAQUE"
        # Single-sided is the default and the cheap one: a solid body has no
        # visible back faces. Flat cloth does — a cape is ONE open sheet of
        # 84 triangles with no inside, and culling its back faces makes the
        # half that faces the wearer, and every edge that reaches past the
        # body, vanish. Those parts say so and get both sides.
        if two_sided:
            mat["doubleSided"] = True
        else:
            mat.pop("doubleSided", None)
    for anim in doc.get("animations", []):
        keep_channels = []
        for ch in anim["channels"]:
            if ch["target"].get("path") == "scale":
                vals = gt.accessor_values(glb, anim["samplers"][ch["sampler"]]["output"])
                if all(abs(v - 1.0) < 1e-3 for vec in vals for v in vec):
                    continue
            keep_channels.append(ch)
        anim["channels"] = keep_channels
        used = sorted({ch["sampler"] for ch in keep_channels})
        remap = {old: new for new, old in enumerate(used)}
        anim["samplers"] = [anim["samplers"][i] for i in used]
        for ch in keep_channels:
            ch["sampler"] = remap[ch["sampler"]]
    gt.collapse_constant_channels(glb)
    return gt.prune_unused(glb)


def finish_base(
    glb_path: Path,
    target: dict,
    source: dict,
    archetype: dict,
    uv_report: dict,
    borrowed: dict | None = None,
) -> dict:
    """Write a base's extras. `borrowed` = the clip facts of a shared library.

    A body that borrows its clips carries no animation of its own, so the
    facts the runtime needs — duration, loop, stride — are copied from the
    library and the file it came from is named in `clips_from`.
    """
    glb = finish_common(gt.read_glb(glb_path))
    doc = glb.doc
    skinned = gt.skinned_mesh_nodes(doc)
    lo = [1e9] * 3
    hi = [-1e9] * 3
    tris = 0
    for n in skinned:
        mesh = doc["meshes"][doc["nodes"][n]["mesh"]]
        mlo, mhi = gt.mesh_bounds(doc, mesh)
        lo = [min(a, b) for a, b in zip(lo, mlo, strict=True)]
        hi = [max(a, b) for a, b in zip(hi, mhi, strict=True)]
        tris += gt.triangle_count(doc, mesh)
    clips: dict[str, dict] = dict(borrowed["clips"]) if borrowed else {}
    for name, spec in archetype["clips"].items():
        anim = gt.clip_by_name(doc, name)
        if anim is None:
            continue
        entry: dict = {
            "duration": round(gt.clip_duration(glb, anim), 4),
            "loop": bool(spec["loop"]),
        }
        if spec.get("stride"):
            entry["stride_m"] = round(gt.measure_stride(glb, anim, archetype["feet"]), 4)
        clips[name] = entry
    extras = {
        "contract": CONTRACT["contract"],
        "archetype": target["archetype"],
        "variant": target["variant"],
        "base": target["base"],
        "forward": "+Z",
        "height_m": round(hi[1] - lo[1], 4),
        "target_height_m": archetype["variants"][target["variant"]]["height_m"],
        "clips": clips,
        "palette_cells": uv_report["used"],
        "hair_primitive": bool(uv_report["hair_faces"]),
        "source": f"{source['name']} ({source['license']}) / {target['character']}",
    }
    if borrowed:
        extras["clips_from"] = borrowed["file"]
    doc.setdefault("asset", {})["extras"] = {"jarvis_figure": extras}
    doc["asset"]["generator"] = "Dodaios build_figures.py"
    gt.write_glb(glb_path, doc, glb.blob)
    log(
        f"finished {glb_path.name}: {glb_path.stat().st_size // 1024} KB, "
        f"{tris} tris, clips {sorted(clips)}"
    )
    return {"triangles": tris, "clips": sorted(clips), "height_m": extras["height_m"]}


def finish_part(glb_path: Path, spec: dict, target: dict, source: dict, attach: str) -> dict:
    two_sided = bool(spec.get("two_sided"))
    glb = finish_common(gt.read_glb(glb_path), two_sided=two_sided)
    doc = glb.doc
    doc["animations"] = []
    glb = gt.prune_unused(glb)
    doc = glb.doc
    tris = sum(
        gt.triangle_count(doc, doc["meshes"][doc["nodes"][n]["mesh"]])
        for n in gt.skinned_mesh_nodes(doc)
    )
    extras = {
        "contract": CONTRACT["contract"],
        "archetype": target["archetype"],
        "slot": spec["slot"],
        "attach": attach,
        "hides": spec.get("hides", []),
        "label": spec["label"],
        "styles": spec.get("styles", []),
        "two_sided": two_sided,
        "source": f"{source['name']} ({source['license']}) / {spec['object']}",
    }
    doc.setdefault("asset", {})["extras"] = {"jarvis_part": extras}
    doc["asset"]["generator"] = "Dodaios build_figures.py"
    gt.write_glb(glb_path, doc, glb.blob)
    log(f"finished part {glb_path.name}: {glb_path.stat().st_size // 1024} KB, {tris} tris")
    return {"triangles": tris, "two_sided": two_sided}


_GATE = None


def run_gate(glb_path: Path, sources_md: Path) -> None:
    global _GATE
    gate = REPO / "scripts" / "ci" / "check_society_figures.py"
    if not gate.exists():
        log("gate not present yet — skipping validation")
        return
    if _GATE is None:
        spec = importlib.util.spec_from_file_location("check_society_figures", gate)
        mod = importlib.util.module_from_spec(spec)
        assert spec and spec.loader
        sys.modules["check_society_figures"] = mod
        spec.loader.exec_module(mod)
        _GATE = mod
    problems = _GATE.check_file(glb_path, sources_md=sources_md)
    if problems:
        for p in problems:
            log(f"GATE {glb_path.name}: {p}")
        raise SystemExit(f"{glb_path.name} violates the figure contract")
    log(f"gate OK for {glb_path.name}")


# ---------------------------------------------------------------------------
# one target = one base + its parts
# ---------------------------------------------------------------------------


def build_target(target: dict, out_dir: Path, ledger: Path) -> tuple[dict, list[dict]]:
    archetype = CONTRACT["archetypes"][target["archetype"]]
    source = load_source(target["source"])
    character = source["characters"][target["character"]]
    part_specs = character.get("parts", [])
    if source.get("procedural") == "gigi":
        return build_procedural_gigi(target, source, archetype, out_dir)
    if source.get("procedural") == "humanoid":
        return build_procedural_humanoid(target, source, archetype, out_dir)
    if source.get("procedural") == "quadruped":
        return build_procedural_quadruped(target, source, archetype, out_dir)
    src_file = fetch_source_file(source, f"{target['character']}.glb")
    log(f"building {target['id']} from {src_file.name}")

    reset_scene()
    import_glb(src_file, int(source.get("fps", 30)))
    arm = find_armature()
    wanted = set(character["body_meshes"]) | {p["object"] for p in part_specs}
    objects = keep_objects(arm, wanted)
    bodies = [objects[n] for n in character["body_meshes"]]
    source_names = tag_origin(bodies)

    dropped = drop_bones(arm, source["drop_bone_patterns"])
    log(f"dropped {len(dropped)} control bones")
    rename_bones(arm, source["bone_map"], archetype["bones"])
    kept = filter_clips(source["clip_map"], archetype["clips"])
    for name, action in kept.items():
        normalize_clip(action, archetype["clips"][name]["loop"])

    sheet_path = CACHE / f"{target['id']}-sheet.png"
    write_sheet(sheet_path, character["default_palette"])
    img = load_sheet(sheet_path)

    body = join_bodies(bodies)
    uv_report = reuv_to_palette(body, source_names, character["cell_map"], source["atlas_grid"])
    apply_materials(body, img, target["id"], uv_report["hair_faces"])
    fwd = add_forward_marker(arm)

    out_dir.mkdir(parents=True, exist_ok=True)
    base_path = out_dir / f"{target['id']}.glb"
    export_glb(base_path, [body, arm, fwd], animations=True)
    facts = finish_base(base_path, target, source, archetype, uv_report)
    base_entry = {
        "id": f"{target['archetype']}/{target['base']}",
        "file": base_path.name,
        "archetype": target["archetype"],
        "variant": target["variant"],
        "base": target["base"],
        "label": target["label"],
        "styles": target.get("styles", []),
        "heightM": archetype["variants"][target["variant"]]["height_m"],
        "palette": character["default_palette"],
        "family": source.get("family", source_slug(source)),
        "fitSize": None,
        "source": f"{source['name']} / {target['character']}",
        "license": source["license"],
        **facts,
    }

    # Parts: the clips are gone, the FWD stays out of the selection.
    for action in list(bpy.data.actions):
        bpy.data.actions.remove(action)
    part_entries = []
    parts_dir = out_dir / "parts" / target["archetype"]
    parts_dir.mkdir(parents=True, exist_ok=True)
    for spec in part_specs:
        part = objects[spec["object"]]
        attach = archetype["slots"][spec["slot"]]["attach"]
        skin_part_to_bone(part, arm, attach)
        report = reuv_to_palette(
            part,
            {},
            # The part's own map wins: an accessory can share an atlas cell
            # with something on the body that means a different thing on it.
            {"*": {**character["cell_map"].get("*", {}), **spec.get("cell_map", {})}},
            source["atlas_grid"],
            fallback=source.get("part_cell_map", {}),
        )
        apply_materials(part, img, spec["id"], [])
        part_path = parts_dir / f"{spec['id']}.glb"
        export_glb(part_path, [part, arm], animations=False)
        pfacts = finish_part(part_path, spec, target, source, attach)
        part_entries.append(
            {
                "id": spec["id"],
                "file": f"parts/{target['archetype']}/{part_path.name}",
                "archetype": target["archetype"],
                "slot": spec["slot"],
                "attach": attach,
                "label": spec["label"],
                "styles": spec.get("styles", []),
                "hides": spec.get("hides", []),
                "fits_family": spec.get("fits_family"),
                "fits_size": spec.get("fits_size"),
                "asymmetric": bool(spec.get("asymmetric")),
                "covers": spec.get("covers", []),
                "from_base": target["base"],
                "source": f"{source['name']} / {spec['object']}",
                "license": source["license"],
                "palette_cells": report["used"],
                **pfacts,
            }
        )
    return base_entry, part_entries


def build_procedural_quadruped(
    target: dict, source: dict, archetype: dict, out_dir: Path
) -> tuple[dict, list[dict]]:
    """An animal: rig, body and clips all written by ``quadruped_builder.py``.

    There is no CC0 donor of this archetype, so unlike the humanoids nothing
    is borrowed — the 21-bone skeleton and all seven clips are keyed here.
    """
    import quadruped_builder  # noqa: PLC0415 — Blender-only module beside this file

    log(f"building {target['id']} procedurally")

    def make_rig():
        reset_scene()
        bpy.context.scene.render.fps = quadruped_builder.FPS
        return quadruped_builder.build_rig_with_clips()

    borrowed = ensure_clip_library(source, archetype, out_dir, make_rig)
    reset_scene()
    bpy.context.scene.render.fps = quadruped_builder.FPS
    character = source["characters"][target["character"]]
    sheet_path = CACHE / f"{target['id']}-sheet.png"
    write_sheet(sheet_path, character["default_palette"])
    img = load_sheet(sheet_path)
    arm, body, uv_report = quadruped_builder.build_quadruped(
        character["shape"], CONTRACT["sheet"], img, sheet_material
    )
    apply_materials(body, img, target["id"], uv_report["hair_faces"])
    fwd = add_forward_marker(arm)

    out_dir.mkdir(parents=True, exist_ok=True)
    base_path = out_dir / f"{target['id']}.glb"
    export_glb(base_path, [body, arm, fwd], animations=False)
    facts = finish_base(base_path, target, source, archetype, uv_report, borrowed=borrowed)
    entry = {
        "id": f"{target['archetype']}/{target['base']}",
        "file": base_path.name,
        "archetype": target["archetype"],
        "variant": target["variant"],
        "base": target["base"],
        "label": target["label"],
        "styles": target.get("styles", []),
        "heightM": archetype["variants"][target["variant"]]["height_m"],
        "palette": character["default_palette"],
        "family": source.get("family", source_slug(source)),
        "fitSize": None,
        "clipsFrom": borrowed["file"],
        "source": f"{source['name']} / {target['character']}",
        "license": source["license"],
        "note": (
            f"rig, body and clips written by quadruped_builder.py "
            f"(shape `{character['shape']}`); no external source"
        ),
        **facts,
    }

    for action in list(bpy.data.actions):
        bpy.data.actions.remove(action)
    part_entries = []
    parts_dir = out_dir / "parts" / target["archetype"]
    for part_id in character.get("parts", []):
        spec = dict(quadruped_builder.PART_SPECS[part_id])
        spec["id"] = part_id
        spec["object"] = part_id
        attach = archetype["slots"][spec["slot"]]["attach"]
        part, report = quadruped_builder.build_part(
            part_id, arm, CONTRACT["sheet"], img, sheet_material
        )
        apply_materials(part, img, part_id, [])
        parts_dir.mkdir(parents=True, exist_ok=True)
        part_path = parts_dir / f"{part_id}.glb"
        export_glb(part_path, [part, arm], animations=False)
        pfacts = finish_part(part_path, spec, target, source, attach)
        bpy.data.objects.remove(part, do_unlink=True)
        part_entries.append(
            {
                "id": part_id,
                "file": f"parts/{target['archetype']}/{part_path.name}",
                "archetype": target["archetype"],
                "slot": spec["slot"],
                "attach": attach,
                "label": spec["label"],
                "styles": spec.get("styles", []),
                "hides": spec.get("hides", []),
                "fits_family": spec.get("fits_family"),
                "fits_size": spec.get("fits_size"),
                "asymmetric": bool(spec.get("asymmetric")),
                "covers": spec.get("covers", []),
                "from_base": target["base"],
                "source": f"{source['name']} / {part_id}",
                "license": source["license"],
                "palette_cells": report["used"],
                **pfacts,
            }
        )
    return entry, part_entries


def build_procedural_gigi(
    target: dict, source: dict, archetype: dict, out_dir: Path
) -> tuple[dict, list[dict]]:
    """The mascot: modelled and keyed by gigi_builder.py, finished like any base."""
    import gigi_builder  # noqa: PLC0415 — Blender-only module beside this file

    log(f"building {target['id']} procedurally")
    reset_scene()
    bpy.context.scene.render.fps = gigi_builder.FPS
    character = source["characters"][target["character"]]
    sheet_path = CACHE / f"{target['id']}-sheet.png"
    write_sheet(sheet_path, character["default_palette"])
    img = load_sheet(sheet_path)
    arm, body, uv_report = gigi_builder.build_gigi(CONTRACT["sheet"], img, sheet_material)
    fwd = add_forward_marker(arm)
    out_dir.mkdir(parents=True, exist_ok=True)
    base_path = out_dir / f"{target['id']}.glb"
    export_glb(base_path, [body, arm, fwd], animations=True)
    facts = finish_base(base_path, target, source, archetype, uv_report)
    entry = {
        "id": f"{target['archetype']}/{target['base']}",
        "file": base_path.name,
        "archetype": target["archetype"],
        "variant": target["variant"],
        "base": target["base"],
        "label": target["label"],
        "styles": target.get("styles", []),
        "heightM": archetype["variants"][target["variant"]]["height_m"],
        "palette": character["default_palette"],
        "family": source.get("family", source_slug(source)),
        "fitSize": None,
        "source": f"{source['name']} / {target['character']}",
        "license": source["license"],
        **facts,
    }
    return entry, []


def normalize_donor_rig(source: dict, archetype: dict) -> bpy.types.Object:
    """Import the CC0 donor, keep its skeleton and clips, drop every mesh it ships.

    Shared by the clip library and by every body built on that rig, so the two
    can never drift: the bones a body is weighted to are the bones the clips
    animate, because both came out of this function.
    """
    rig = load_source(source["rig_source"])
    rig_file = fetch_source_file(rig, f"{source['rig_character']}.glb")
    reset_scene()
    import_glb(rig_file, int(rig.get("fps", 30)))
    arm = find_armature()
    keep_objects(arm, set())
    dropped = drop_bones(arm, rig["drop_bone_patterns"])
    log(f"dropped {len(dropped)} control bones")
    rename_bones(arm, rig["bone_map"], archetype["bones"])
    kept = filter_clips(rig["clip_map"], archetype["clips"])
    for name, action in kept.items():
        normalize_clip(action, archetype["clips"][name]["loop"])
    return arm


def clip_library_path(source: dict, out_dir: Path) -> Path:
    return out_dir / source["clip_library"]


def build_clip_library(source: dict, archetype: dict, out_dir: Path, make_rig) -> dict:
    """The nine clips of one rig, once, in a file with no body.

    Nine clips of 23 bones are ~200 KB — five times a procedural body's
    geometry — so shipping a copy inside every look would make a new look cost
    240 KB instead of 40 KB, and rewrite all of them on every rebuild. The
    bodies name this file in `extras.clips_from`; three.js binds a clip by node
    name, and every body of this rig has those nodes.
    """
    arm = make_rig()
    out_dir.mkdir(parents=True, exist_ok=True)
    path = clip_library_path(source, out_dir)
    export_glb(path, [arm], animations=True)

    glb = finish_common(gt.read_glb(path))
    doc = glb.doc
    clips: dict[str, dict] = {}
    for name, spec in archetype["clips"].items():
        anim = gt.clip_by_name(doc, name)
        if anim is None:
            raise SystemExit(f"clip library is missing {name!r}")
        entry: dict = {
            "duration": round(gt.clip_duration(glb, anim), 4),
            "loop": bool(spec["loop"]),
        }
        if spec.get("stride"):
            entry["stride_m"] = round(gt.measure_stride(glb, anim, archetype["feet"]), 4)
        clips[name] = entry
    doc.setdefault("asset", {})["extras"] = {
        "jarvis_clips": {
            "contract": CONTRACT["contract"],
            "archetype": source["clip_archetype"],
            "clips": clips,
            "source": clip_source_credit(source),
        }
    }
    doc["asset"]["generator"] = "Dodaios build_figures.py"
    gt.write_glb(path, doc, glb.blob)
    log(f"clip library {path.name}: {path.stat().st_size // 1024} KB, clips {sorted(clips)}")
    return {"file": path.name, "clips": clips}


def clip_source_credit(source: dict) -> str:
    """Who the clips came from — a CC0 donor, or this repo."""
    if not source.get("rig_source"):
        return f"{source['name']} ({source['license']}) / written by script"
    rig = load_source(source["rig_source"])
    return f"{rig['name']} ({rig['license']}) / {source['rig_character']}"


def ensure_clip_library(source: dict, archetype: dict, out_dir: Path, make_rig) -> dict:
    """Build the library if it is not beside the bodies yet, else read its facts."""
    path = clip_library_path(source, out_dir)
    if path.exists():
        facts = gt.clips_extras(gt.read_glb(path).doc)
        if facts and facts.get("contract") == CONTRACT["contract"]:
            return {"file": path.name, "clips": facts["clips"]}
    return build_clip_library(source, archetype, out_dir, make_rig)


def build_procedural_humanoid(
    target: dict, source: dict, archetype: dict, out_dir: Path
) -> tuple[dict, list[dict]]:
    """A body modelled by ``humanoid_builder.py`` on the CC0 donor's rig and clips.

    The donor gives the skeleton and the nine clips and nothing else: every
    mesh it shipped is deleted before the new body is built, so what ships is
    our geometry on a CC0 rig — the arrangement §12 of the pipeline settled.
    """
    import humanoid_builder  # noqa: PLC0415 — Blender-only module beside this file

    rig = load_source(source["rig_source"])
    character = source["characters"][target["character"]]
    borrowed = ensure_clip_library(
        source, archetype, out_dir, lambda: normalize_donor_rig(source, archetype)
    )
    profile = humanoid_builder.PROFILES[character["profile"]]
    fit_size = humanoid_builder.fit_size(profile)
    log(f"building {target['id']} procedurally on the {source['rig_character']} rig")
    arm = normalize_donor_rig(source, archetype)

    sheet_path = CACHE / f"{target['id']}-sheet.png"
    write_sheet(sheet_path, character["default_palette"])
    img = load_sheet(sheet_path)
    body, uv_report = humanoid_builder.build_humanoid(
        character["profile"], arm, CONTRACT["sheet"], img, sheet_material
    )
    apply_materials(body, img, target["id"], uv_report["hair_faces"])
    fwd = add_forward_marker(arm)

    out_dir.mkdir(parents=True, exist_ok=True)
    base_path = out_dir / f"{target['id']}.glb"
    export_glb(base_path, [body, arm, fwd], animations=False)
    facts = finish_base(base_path, target, source, archetype, uv_report, borrowed=borrowed)
    entry = {
        "id": f"{target['archetype']}/{target['base']}",
        "file": base_path.name,
        "archetype": target["archetype"],
        "variant": target["variant"],
        "base": target["base"],
        "label": target["label"],
        "styles": target.get("styles", []),
        "heightM": archetype["variants"][target["variant"]]["height_m"],
        "palette": character["default_palette"],
        "family": source.get("family", source_slug(source)),
        "fitSize": fit_size,
        "clipsFrom": borrowed["file"],
        "source": f"{source['name']} / {target['character']}",
        "license": source["license"],
        "note": (
            f"body modelled by humanoid_builder.py (profile `{character['profile']}`); "
            f"rig and clips from {rig['name']} ({rig['license']}) / {source['rig_character']}, "
            "every donor mesh deleted"
        ),
        **facts,
    }

    # Accessories, modelled the same way and hung on bones every biped shares,
    # so one file fits every base of its style. Declared on ONE character so
    # the four bodies do not each rebuild the same four files.
    for action in list(bpy.data.actions):
        bpy.data.actions.remove(action)
    part_entries = []
    parts_dir = out_dir / "parts" / target["archetype"]
    for part_id in character.get("parts", []):
        base_spec = humanoid_builder.PART_SPECS[part_id]
        # A garment that wraps the torso is cut to a girth, so it is built once
        # per size class; everything else hangs on a bone the rig places the
        # same way for every body and is built once.
        sizes = sorted(humanoid_builder.WRAP_SIZES) if base_spec.get("wrapping") else [None]
        for size in sizes:
            spec = dict(base_spec)
            variant_id = part_id if size in (None, "slim") else f"{part_id}-{size}"
            spec["id"] = variant_id
            spec["object"] = variant_id
            spec["fits_size"] = size
            attach = archetype["slots"][spec["slot"]]["attach"]
            part, report = humanoid_builder.build_part(
                part_id, arm, CONTRACT["sheet"], img, sheet_material, size=size
            )
            apply_materials(part, img, variant_id, [])
            parts_dir.mkdir(parents=True, exist_ok=True)
            part_path = parts_dir / f"{variant_id}.glb"
            export_glb(part_path, [part, arm], animations=False)
            pfacts = finish_part(part_path, spec, target, source, attach)
            bpy.data.objects.remove(part, do_unlink=True)
            part_entries.append(
                {
                    "id": variant_id,
                    "file": f"parts/{target['archetype']}/{part_path.name}",
                    "archetype": target["archetype"],
                    "slot": spec["slot"],
                    "attach": attach,
                    "label": spec["label"],
                    "styles": spec.get("styles", []),
                    "hides": spec.get("hides", []),
                    "fits_family": spec.get("fits_family"),
                    "fits_size": spec.get("fits_size"),
                    "asymmetric": bool(spec.get("asymmetric")),
                    "covers": spec.get("covers", []),
                    "from_base": target["base"],
                    "source": f"{source['name']} / {part_id}",
                    "license": source["license"],
                    "palette_cells": report["used"],
                    **pfacts,
                }
            )
    return entry, part_entries


def write_ledger(
    path: Path,
    bases: list[dict],
    parts: list[dict],
    sources: dict[str, dict],
    libraries: list[dict],
) -> None:
    lines = [
        "# Figure assets — provenance ledger",
        "",
        "GENERATED by `scripts/figures/build_figures.py` — one row per shipped file",
        "(docs/agent-society/character-pipeline.md §11, gate check 15). Every GLB here is",
        "produced from the recorded source; nothing is hand-exported. Sources are fetched by URL",
        "into `scripts/figures/cache/` and verified by sha256 before the build touches them",
        "(`scripts/figures/sources/*.json`).",
        "",
        "| File | Source | License | What the build changed |",
        "|---|---|---|---|",
    ]
    imported_note = (
        "body meshes joined; IK/control bones dropped; 23 deform bones renamed; clips "
        "kept/renamed, root XZ zeroed, loops closed; faces re-UV'd onto the palette strip; "
        "hair as its own primitive; FWD marker; extras"
    )
    for b in bases:
        lines.append(
            f"| `{b['file']}` | {b['source']} | {b['license']} | {b.get('note') or imported_note} |"
        )
    for lib in libraries:
        lines.append(
            f"| `{lib['file']}` | {lib['source']} | {lib['license']} | rig imported, IK/control "
            "bones dropped, 23 deform bones renamed; clips kept/renamed, root XZ zeroed, loops "
            "closed; every donor mesh deleted — clips only, borrowed by the bodies of this rig |"
        )
    for p in parts:
        lines.append(
            f"| `{p['file'].split('/')[-1]}` | {p['source']} | {p['license']} | unparented at "
            f"rest, skinned to `{p['attach']}` with weight 1; re-UV'd onto the palette strip; "
            "no clips; extras |"
        )
    lines.append("")
    for src in sources.values():
        lines.append(
            f"- **{src['name']}** — {src['author']}, {src['license']} "
            f"({src['license_url']}); files:"
        )
        for fname, sha in src["files"].items():
            lines.append(f"  - `{fname}` sha256 `{sha}`")
    lines.append("")
    lines.append(
        "Licenses recorded at fetch time. CC0 needs no attribution; credit is given anyway."
    )
    path.write_text("\n".join(lines) + "\n", encoding="utf-8")


def main() -> None:
    argv = sys.argv[sys.argv.index("--") + 1 :] if "--" in sys.argv else []
    parser = argparse.ArgumentParser()
    parser.add_argument("--out", default=str(DEFAULT_OUT))
    parser.add_argument("--target", default=None)
    args = parser.parse_args(argv)
    out_dir = Path(args.out)
    targets = [t for t in CONTRACT["targets"] if args.target in (None, t["id"])]
    if not targets:
        raise SystemExit(f"no target named {args.target!r}")

    catalog: dict = {"contract": CONTRACT["contract"], "styles": {}, "bases": [], "parts": []}
    if CATALOG_PATH.exists() and args.target:
        catalog = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
    catalog["styles"] = {k: v for k, v in CONTRACT["styles"].items() if not k.startswith("$")}

    ledger = out_dir / "SOURCES.md"
    built_bases: list[dict] = []
    built_parts: list[dict] = []
    for target in targets:
        base, parts = build_target(target, out_dir, ledger)
        built_bases.append(base)
        built_parts.extend(parts)

    # Merge into the catalog (a single --target rebuild keeps the other entries).
    bases = {b["id"]: b for b in catalog.get("bases", [])}
    for b in built_bases:
        bases[b["id"]] = b
    parts = {p["id"]: p for p in catalog.get("parts", [])}
    for p in built_parts:
        parts[p["id"]] = p
    catalog["bases"] = sorted(bases.values(), key=lambda b: b["id"])
    catalog["parts"] = sorted(parts.values(), key=lambda p: p["id"])
    sources = {t["source"]: load_source(t["source"]) for t in CONTRACT["targets"]}
    # Every clip library a shipped base borrows from, whether this run built it
    # or found it already beside the bodies.
    libraries = []
    for src in sources.values():
        if not src.get("clip_library"):
            continue
        rig = load_source(src["rig_source"]) if src.get("rig_source") else src
        libraries.append(
            {
                "file": src["clip_library"],
                "source": f"{clip_source_credit(src)} — rig and clips only",
                "license": rig["license"],
            }
        )
    write_ledger(ledger, catalog["bases"], catalog["parts"], sources, libraries)
    CATALOG_PATH.write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8")
    log(f"catalog: {len(catalog['bases'])} bases, {len(catalog['parts'])} parts")

    # The gate runs last, against the regenerated ledger.
    for lib in libraries:
        if (out_dir / lib["file"]).exists():
            run_gate(out_dir / lib["file"], ledger)
    for b in built_bases:
        run_gate(out_dir / b["file"], ledger)
    for p in built_parts:
        run_gate(out_dir / p["file"], ledger)


if __name__ == "__main__":
    main()