refactor(tools): group the sixty scripts by what they talk to

One directory with sixty scripts stopped being navigable, and the grouping is also the sandbox boundary:

  Tools/unreal/    commandlets and the two map builders, with ue_common.py and ue_placement.py as the
                   shared imports (they need the engine)
  Tools/blender/   builders, exporters, the FBX preset, the MPFB character pipeline, blender_screenshots
                   (they need the Blender Flatpak)
  Tools/review/    the visual loop: render_screenshots.sh, judge_screenshot.py, hero_compare.py,
                   build_comparison_md.py, e2e_asset_check.py, hero_iterate.sh, visual_loop.py,
                   visual_targets.json
  Tools/gen/       image and texture generation: the ComfyUI driver, deterministic texture writers,
                   reference fetching
  Tools/input/     OS-level input injection
  root             _common.py, check-lfs.sh, addon_compat_probe.py, sibling_asset_audit.py, tests/

Every moved script now resolves the repository root as ../.. and puts the tools root plus its siblings on
sys.path, so 'import ue_common' still works from unreal/. The test suite bootstrap does the same for the five
folders. render_screenshots.sh takes the folder as a third argument to run_cmdlet, and the e2e driver,
hero_iterate.sh and the comparison generator were repointed.

51 README rows now link to their new location, the README gains a Layout section naming each folder's
sandbox, and the architecture notes and Blender README follow the moves.

Verified: 108 tests pass, prettier is clean, judge_screenshot.py and hero_compare.py run from their new
homes, and the e2e run was aborted mid-way (it had been rebuilding an empty DemoMap for 15 minutes) and is
being rerun against the new layout.

Tools/blender/vehicle_from_template.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Turn the provided hot-hatch .blend into UE-ready assets.
+
+    blender -b "Art/blender/vehicle/hot hatch.blend" \
+        --python Tools/blender/vehicle_from_template.py -- \
+        --out /tmp/gigline/hatch --report /tmp/gigline/hatch/report.json
+
+Follows two skills:
+
+* **vehicle-artist** — one object per system (body, wheels, glass, lights, trim,
+  mirrors), collision planned with the body, LODs planned before export.
+* **unreal-export** — scale confirmed with a known dimension, `SM_`/`UCX_` naming,
+  LOD chain, and every asset measured after import.
+
+The template is not to scale: its longest axis is 7.21 m, which no hot hatch is. The
+tool therefore normalises to a documented real length (default 4.05 m) and records the
+factor, rather than exporting whatever units the file happened to use. That is the
+"confirm scale with known-dimension test" step, done before the export instead of after
+the import.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import bpy
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+import fbx_export_preset  # noqa: E402
+
+# A three-door hot hatch: 4.05 m long, 1.75 m wide, 1.42 m tall.
+TARGET_LENGTH_M = 4.05
+TARGET_WIDTH_M = 1.75
+TARGET_HEIGHT_M = 1.42
+
+PARTS: list[str] = []
+
+
+def log(message: str) -> None:
+    PARTS.append(message)
+    print(f"[hatch] {message}")
+
+
+SYSTEM_RULES = (
+    # (system, material substrings that identify it, object-name substrings)
+    ("glass", ("windows",), ("Cube.003",)),
+    ("lights", ("light", "reflector"), ("lights and grill", "Cylinder.003", "Cylinder.004")),
+    ("mirrors", ("mirror",), ("Cube.005",)),
+    ("wheels", ("rubber", "brake caliper", "black shiny metal"), ("Cylinder", "Cylinder.001")),
+    ("trim", ("plastic black", "pure black", "chrome", "black metal", "rough chrome"),
+     ("Cube.001", "Cube.002", "Cube.004", "Cube.006", "Cube.007", "Cylinder.002")),
+)
+
+
+def _colour_rank(colour):
+    """Sort key for picking a paint colour: saturation first, then brightness."""
+    return (max(colour) - min(colour), sum(colour))
+
+
+def read_material(material):
+    """Base colour, roughness and metallic for a material, Principled or legacy.
+
+    The template's car paint is a **legacy node graph** - mix shaders over glossy and
+    diffuse BSDFs - not a Principled shader. Reading only Principled skipped it, which is
+    exactly why the car arrived in Unreal near-black: the paint colour never left Blender.
+    For those graphs the colour is taken from the mix nodes, which is where the red lives.
+    """
+    if not material.use_nodes:
+        return None
+    nodes = material.node_tree.nodes
+    bsdf = nodes.get("Principled BSDF")
+    if bsdf:
+        colour = bsdf.inputs["Base Color"].default_value
+        return {
+            "base_color": [round(colour[0], 4), round(colour[1], 4), round(colour[2], 4)],
+            "roughness": round(bsdf.inputs["Roughness"].default_value, 4),
+            "metallic": round(bsdf.inputs["Metallic"].default_value, 4),
+            "source": "principled",
+        }
+    # Legacy graph: the largest colour found on a mix or diffuse node is the paint.
+    best = None
+    roughness = 0.5
+    metallic = 0.0
+    for node in nodes:
+        if node.type in ("MIX", "MIX_RGB"):
+            for socket in node.inputs:
+                try:
+                    value = socket.default_value
+                except Exception:  # noqa: BLE001 - not every socket has a default
+                    continue
+                if not hasattr(value, "__len__") or len(value) < 3:
+                    continue
+                candidate = (value[0], value[1], value[2])
+                if max(candidate) < 0.03:
+                    continue
+                # Prefer the most saturated colour, not the brightest: the paint's red
+                # (0.49, 0, 0) is darker than the 0.8 grey diffuse beside it, and a
+                # "brightest wins" rule picked the grey - which is how a red car reaches
+                # Unreal as a grey one.
+                if best is None or _colour_rank(candidate) > _colour_rank(best):
+                    best = candidate
+        elif node.type == "BSDF_DIFFUSE":
+            colour = node.inputs["Color"].default_value
+            candidate = (colour[0], colour[1], colour[2])
+            if best is None or _colour_rank(candidate) > _colour_rank(best):
+                best = candidate
+        elif node.type == "BSDF_GLOSSY":
+            try:
+                roughness = round(node.inputs["Roughness"].default_value, 4)
+            except Exception:  # noqa: BLE001
+                pass
+    if best is None:
+        return None
+    return {
+        "base_color": [round(best[0], 4), round(best[1], 4), round(best[2], 4)],
+        "roughness": roughness,
+        "metallic": metallic,
+        "source": "legacy graph",
+    }
+
+
+def ensure_principled(material):
+    """Rewire a legacy graph to a Principled BSDF so the FBX export carries a colour.
+
+    The template's car paint is a mix-shader graph, and the FBX exporter cannot map that -
+    which is why SM_Vehicle_Body arrived in Unreal holding `WorldGridMaterial` (the default
+    fallback) and rendered black while Blender showed red. Converting in place keeps the
+    colour and makes the export uniform.
+    """
+    if not material.use_nodes:
+        return False
+    nodes = material.node_tree.nodes
+    if nodes.get("Principled BSDF"):
+        return False
+    spec = read_material(material)
+    if not spec:
+        return False
+    nodes.clear()
+    output = nodes.new("ShaderNodeOutputMaterial")
+    bsdf = nodes.new("ShaderNodeBsdfPrincipled")
+    colour = spec["base_color"]
+    bsdf.inputs["Base Color"].default_value = (colour[0], colour[1], colour[2], 1.0)
+    bsdf.inputs["Roughness"].default_value = max(0.05, spec.get("roughness", 0.5))
+    bsdf.inputs["Metallic"].default_value = spec.get("metallic", 0.0)
+    material.node_tree.links.new(bsdf.outputs["BSDF"], output.inputs["Surface"])
+    log(f"converted {material.name} to Principled, base "
+        f"{tuple(round(c, 3) for c in colour)}")
+    return True
+
+
+def classify(obj):
+    """Assign an object to a system by its materials first, then by its name."""
+    materials = [m.name.lower() for m in obj.data.materials if m]
+    name = obj.name.lower()
+    for system, materials_hint, names_hint in SYSTEM_RULES:
+        if any(hint in name for hint in (n.lower() for n in names_hint)):
+            return system
+        if any(any(h in material for h in materials_hint) for material in materials):
+            return system
+    return "body"
+
+
+def min_z(objects):
+    from mathutils import Vector
+    lowest = None
+    for obj in objects:
+        for corner in obj.bound_box:
+            z = (obj.matrix_world @ Vector(corner)).z
+            lowest = z if lowest is None else min(lowest, z)
+    return lowest if lowest is not None else 0.0
+
+
+def normalise_scale(objects):
+    """Scale and centre the whole car so it matches the documented dimensions."""
+    xs, ys, zs = [], [], []
+    for obj in objects:
+        for corner in obj.bound_box:
+            world = obj.matrix_world @ __import__("mathutils").Vector(corner)
+            xs.append(world.x)
+            ys.append(world.y)
+            zs.append(world.z)
+    length = max(ys) - min(ys)
+    width = max(xs) - min(xs)
+    height = max(zs) - min(zs)
+    log(f"template bounds: {length:.2f} x {width:.2f} x {height:.2f} m")
+    factor = TARGET_LENGTH_M / length if length > 0.01 else 1.0
+    log(f"scale factor {factor:.4f} (target length {TARGET_LENGTH_M} m, "
+        f"was {length:.2f} m)")
+
+    for obj in objects:
+        obj.scale = tuple(s * factor for s in obj.scale)
+        obj.location = tuple(l * factor for l in obj.location)
+    bpy.context.view_layer.update()
+
+    # Drop the car onto Z 0 and centre it on the origin in X/Y. Ground on the WHEELS, not
+    # on the whole model: the lowest geometry in the file is exhaust/underbody, so grounding
+    # on everything left the tyres floating by the difference.
+    xs, ys, zs = [], [], []
+    for obj in objects:
+        for corner in obj.bound_box:
+            world = obj.matrix_world @ __import__("mathutils").Vector(corner)
+            xs.append(world.x)
+            ys.append(world.y)
+            zs.append(world.z)
+    wheels = [o for o in objects if "rubber" in [m.name.lower() for m in o.data.materials if m]]
+    ground = min_z(wheels) if wheels else min(zs)
+    log(f"grounding on {'wheels' if wheels else 'whole model'}: lowest Z {ground:.3f} m")
+    offset = __import__("mathutils").Vector(
+        (-(min(xs) + max(xs)) / 2.0, -(min(ys) + max(ys)) / 2.0, -ground))
+    for obj in objects:
+        obj.location = tuple(l + o for l, o in zip(obj.location, offset))
+    bpy.context.view_layer.update()
+    log(f"centred and grounded (offset {offset.x:.2f}, {offset.y:.2f}, {offset.z:.2f} m)")
+
+
+def join_system(objects, name):
+    bpy.ops.object.select_all(action="DESELECT")
+    for obj in objects:
+        obj.select_set(True)
+    bpy.context.view_layer.objects.active = objects[0]
+    if len(objects) > 1:
+        bpy.ops.object.join()
+    joined = bpy.context.active_object
+    joined.name = name
+    return joined
+
+
+def add_collision(body):
+    """One convex box per major volume, `UCX_`-prefixed for Unreal."""
+    hulls = []
+    xs, ys, zs = [], [], []
+    for corner in body.bound_box:
+        world = body.matrix_world @ __import__("mathutils").Vector(corner)
+        xs.append(world.x)
+        ys.append(world.y)
+        zs.append(world.z)
+    length, width, height = max(ys) - min(ys), max(xs) - min(xs), max(zs) - min(zs)
+    centre = ((min(xs) + max(xs)) / 2.0, (min(ys) + max(ys)) / 2.0,
+              min(zs) + height * 0.5)
+    bpy.ops.mesh.primitive_cube_add(size=1.0, location=centre)
+    hull = bpy.context.active_object
+    hull.name = "UCX_SM_Vehicle_Body_01"
+    hull.scale = (width * 0.96, length * 0.98, height * 0.62)
+    bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+    hull.hide_render = True
+    hulls.append(hull)
+    log(f"collision: 1 hull {width*0.96:.2f} x {length*0.98:.2f} x {height*0.62:.2f} m")
+    return hulls
+
+
+def decimate_copy(source, name, ratio):
+    bpy.ops.object.select_all(action="DESELECT")
+    source.select_set(True)
+    bpy.context.view_layer.objects.active = source
+    bpy.ops.object.duplicate()
+    copy = bpy.context.active_object
+    copy.name = name
+    modifier = copy.modifiers.new(name="LOD", type="DECIMATE")
+    modifier.ratio = ratio
+    bpy.ops.object.modifier_apply(modifier=modifier.name)
+    return copy
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out", default="/tmp/gigline/hatch")
+    ap.add_argument("--report", default="/tmp/gigline/hatch/report.json")
+    args = ap.parse_args(argv)
+
+    meshes = [o for o in bpy.data.objects if o.type == "MESH"]
+    if not meshes:
+        raise SystemExit("no meshes in the template")
+    log(f"template: {len(meshes)} mesh objects, "
+        f"{sum(len(o.data.vertices) for o in meshes)} vertices")
+
+    normalise_scale(meshes)
+
+    systems = {}
+    for obj in meshes:
+        systems.setdefault(classify(obj), []).append(obj)
+    log("systems: " + ", ".join(f"{k}={len(v)} objects" for k, v in systems.items()))
+
+    os.makedirs(args.out, exist_ok=True)
+    exported = {}
+    joined = {}
+    for system, objects in systems.items():
+        name = {
+            "body": "SM_Vehicle_Body",
+            "glass": "SM_Vehicle_Glass",
+            "lights": "SM_Vehicle_Lights",
+            "mirrors": "SM_Vehicle_Mirrors",
+            "wheels": "SM_Vehicle_Wheels",
+            "trim": "SM_Vehicle_Trim",
+        }[system]
+        obj = join_system(objects, name)
+        joined[system] = obj
+        path = os.path.join(args.out, f"{system}.fbx")
+        bpy.ops.object.select_all(action="DESELECT")
+        obj.select_set(True)
+        bpy.context.view_layer.objects.active = obj
+        fbx_export_preset.export_static(path, selection=True)
+        exported[system] = path
+        tris = sum(len(p.vertices) - 2 for p in obj.data.polygons)
+        log(f"{name}: {tris} triangles -> {path}")
+
+    hulls = add_collision(joined["body"])
+    bpy.ops.object.select_all(action="DESELECT")
+    joined["body"].select_set(True)
+    for hull in hulls:
+        hull.select_set(True)
+    bpy.context.view_layer.objects.active = joined["body"]
+    fbx_export_preset.export_static(os.path.join(args.out, "body.fbx"), selection=True)
+    log("body re-exported with its UCX hull")
+
+    lods = {}
+    for index, ratio in ((1, 0.35), (2, 0.12)):
+        lod = decimate_copy(joined["body"], f"SM_Vehicle_Body_LOD{index}", ratio)
+        path = os.path.join(args.out, f"body_lod{index}.fbx")
+        bpy.ops.object.select_all(action="DESELECT")
+        lod.select_set(True)
+        bpy.context.view_layer.objects.active = lod
+        fbx_export_preset.export_static(path, selection=True)
+        tris = sum(len(p.vertices) - 2 for p in lod.data.polygons)
+        lods[f"body_lod{index}"] = {"path": path, "triangles": tris}
+        log(f"SM_Vehicle_Body_LOD{index}: {tris} triangles")
+        bpy.data.objects.remove(lod, do_unlink=True)
+
+    converted = sum(1 for m in bpy.data.materials if ensure_principled(m))
+    log(f"legacy materials converted for export: {converted}")
+
+    materials = {}
+    for material in bpy.data.materials:
+        found = read_material(material)
+        if found:
+            materials[material.name] = found
+    principled = sum(1 for m in bpy.data.materials
+                     if m.use_nodes and m.node_tree.nodes.get("Principled BSDF"))
+    log(f"materials: {len(materials)} read, {principled} of them Principled, "
+        f"{len(materials) - principled} from legacy graphs")
+
+    report = {
+        "template": bpy.data.filepath,
+        "materials": materials,
+        "target_dimensions_m": {"length": TARGET_LENGTH_M, "width": TARGET_WIDTH_M,
+                                "height": TARGET_HEIGHT_M},
+        "systems": {system: {"object": joined[system].name,
+                             "triangles": sum(len(p.vertices) - 2
+                                              for p in joined[system].data.polygons),
+                             "fbx": exported.get(system)}
+                    for system in joined},
+        "lods": lods,
+        "collision": [h.name for h in hulls],
+        "log": PARTS,
+    }
+    os.makedirs(os.path.dirname(os.path.abspath(args.report)), exist_ok=True)
+    with open(args.report, "w") as handle:
+        json.dump(report, handle, indent=2)
+    print(f"[hatch] report -> {args.report}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())