weaponlab-mcp 0.1.0__py3-none-any.whl

weaponlab/__init__.py

@@ -0,0 +1,3 @@
+"""Weapon Lab: find and fix first-person weapon bugs once per kind, then for every weapon, behind a gate. A game's
+own probe measures (docs/PROBE_CONTRACT.md); the Gate judges; Rig Lab and Motion Lab read and mend."""
+__version__ = "0.1.0"

weaponlab/__main__.py

@@ -0,0 +1,79 @@
+"""weaponlab <command>
+  serve                                   the MCP server (also: weaponlab-mcp)
+  contract job|rows|parts <file> [job]    check a probe's file against the contract
+  init [folder]                           a new project: weaponlab.json and empty data
+  gate run <providers> [weapons]          measure and store a run
+  gate verdict <run> [targets]            the verdict on a run
+  gate baseline <run>                     a run becomes the baseline
+  rig fist <dump.obj>                     a melee hilt against the fist
+  motion profile <clip.fbx> [side]        a clip's forearm roll"""
+import json
+import sys
+from pathlib import Path
+
+
+def _csv(s):
+    return [x for x in (s or "").split(",") if x]
+
+
+def init(folder="."):
+    root = Path(folder).resolve()
+    data = root / "weaponlab" / "data"
+    (root / "weaponlab" / "specs").mkdir(parents=True, exist_ok=True)
+    data.mkdir(parents=True, exist_ok=True)
+    cfg = root / "weaponlab.json"
+    if not cfg.exists():
+        cfg.write_text(json.dumps({"probe": {"command": [], "timeout_s": 1800, "busy": []}}, indent=1) + "\n", encoding="utf-8")
+    for name, empty in (("weapons.json", []), ("cases.json", []), ("metrics.json", {}), ("budgets.json", {}),
+                        ("actions.json", {"*": {"idle": {"seconds": 1.6}}})):
+        if not (data / name).exists():
+            (data / name).write_text(json.dumps(empty, indent=1) + "\n", encoding="utf-8")
+    gi = root / ".gitignore"
+    line = "weaponlab/work/"
+    if not gi.exists() or line not in gi.read_text(encoding="utf-8"):
+        with open(gi, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    return {"project": str(root), "next": "set probe.command in weaponlab.json (docs/PROBE_CONTRACT.md), list weapons in weaponlab/data/weapons.json"}
+
+
+def main(argv=None):
+    a = list(sys.argv[1:] if argv is None else argv)
+    if not a or a[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    cmd = a[0]
+    if cmd == "serve":
+        from .server import main as serve
+        serve()
+        return 0
+    if cmd == "contract":
+        from . import contract as C
+        bad = C.check_file(a[1], a[2], a[3] if len(a) > 3 else None)
+        print(json.dumps({"ok": not bad, "problems": bad}, indent=1))
+        return 0 if not bad else 1
+    if cmd == "init":
+        out = init(a[1] if len(a) > 1 else ".")
+    elif cmd == "gate":
+        from . import gate as G
+        if a[1] == "run":
+            out = G.run_providers(_csv(a[2]), _csv(a[3]) if len(a) > 3 else None)
+        elif a[1] == "verdict":
+            out = G.verdict(a[2], _csv(a[3]) if len(a) > 3 else None)
+        elif a[1] == "baseline":
+            out = G.set_baseline(a[2])
+        else:
+            raise SystemExit(__doc__)
+    elif cmd == "rig" and a[1] == "fist":
+        from . import rig as R
+        out = R.fist(a[2])
+    elif cmd == "motion" and a[1] == "profile":
+        from . import motion as M
+        out = M.profile(a[2], *(a[3:4] or ["r"]))
+    else:
+        raise SystemExit(__doc__)
+    print(json.dumps(out, indent=1, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

weaponlab/blender/render_parts.py

@@ -0,0 +1,175 @@
+"""Rig Lab's renders: reads the probe's parts dumps (OBJ in the gun's space, cm, one
+group a component and bone: "<role>|<component>|<asset>|<bone>"), splits each group into its pieces (connected
+triangles), lists them, finds pieces drawn twice, and renders dev views from outside the gun. Writes JSON and PNG
+only under the folder given.
+
+    blender -b --factory-startup -P render_parts.py -- <job.json>
+
+job: {"out": folder, "dumps": [obj paths], "render": true, "views": ["right", "left", "top", "bottom"]}"""
+import json
+import math
+import os
+import sys
+
+import bmesh
+import bpy
+from mathutils import Matrix, Vector
+
+COLORS = {"arms": (0.75, 0.72, 0.68, 1), "gun": (0.12, 0.12, 0.14, 1), "part": (0.15, 0.3, 0.75, 1), "item": (0.95, 0.5, 0.1, 1)}
+
+
+def read_obj(path):
+    """The groups of a parts dump: {group: [triangles of three (x, y, z) in cm]}, and the eye."""
+    groups, verts, cur, eye = {}, [], None, None
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            if line.startswith("v "):
+                verts.append(tuple(float(x) for x in line.split()[1:4]))
+            elif line.startswith("g "):
+                cur = line[2:].strip()
+                groups.setdefault(cur, [])
+            elif line.startswith("f "):
+                i = [int(x) - 1 for x in line.split()[1:4]]
+                groups[cur].append((verts[i[0]], verts[i[1]], verts[i[2]]))
+            elif line.startswith("# eye"):
+                eye = tuple(float(x) for x in line.split()[2:5])
+    return groups, eye
+
+
+def pieces(tris, weld=0.02):
+    """Connected pieces of a triangle soup (vertices within weld cm count as one)."""
+    key = lambda p: (round(p[0] / weld), round(p[1] / weld), round(p[2] / weld))
+    parent = {}
+
+    def find(a):
+        while parent[a] != a:
+            parent[a] = parent[parent[a]]
+            a = parent[a]
+        return a
+
+    for t in tris:
+        ks = [key(p) for p in t]
+        for k in ks:
+            parent.setdefault(k, k)
+        for k in ks[1:]:
+            ra, rb = find(ks[0]), find(k)
+            if ra != rb:
+                parent[rb] = ra
+    out = {}
+    for t in tris:
+        out.setdefault(find(key(t[0])), []).append(t)
+    return list(out.values())
+
+
+def describe(tris):
+    pts = [Vector(p) for t in tris for p in t]
+    lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)))
+    hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)))
+    c = sum(pts, Vector()) / len(pts)
+    area = sum(((Vector(t[1]) - Vector(t[0])).cross(Vector(t[2]) - Vector(t[0]))).length / 2.0 for t in tris)
+    # the shape's own size, whatever its turn: its three principal extents (a signature for twins)
+    import numpy as np
+    a = np.array([[p.x, p.y, p.z] for p in pts])
+    a = a - a.mean(axis=0)
+    w, v = np.linalg.eigh(np.cov(a.T)) if len(a) > 3 else (np.zeros(3), np.eye(3))
+    proj = a @ v
+    ext = sorted((proj.max(axis=0) - proj.min(axis=0)).tolist(), reverse=True)
+    axis = v[:, int(np.argmax(w))].tolist()
+    return {"triangles": len(tris), "center": [round(x, 2) for x in c], "min": [round(x, 2) for x in lo], "max": [round(x, 2) for x in hi],
+            "area_cm2": round(area, 1), "extents": [round(x, 2) for x in ext], "long_axis": [round(x, 3) for x in axis]}
+
+
+def twins(items, tol=0.06):
+    """Pieces drawn twice: the same triangle count and the same three extents (within tol of the size), anywhere."""
+    found = []
+    for i in range(len(items)):
+        for j in range(i + 1, len(items)):
+            a, b = items[i], items[j]
+            if a["triangles"] < 12 or a["triangles"] != b["triangles"]:
+                continue
+            if all(abs(x - y) <= tol * max(x, y, 0.5) for x, y in zip(a["extents"], b["extents"])):
+                found.append({"a": a["id"], "b": b["id"], "apart_cm": round((Vector(a["center"]) - Vector(b["center"])).length, 2)})
+    return found
+
+
+def scene(groups):
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    for g, tris in groups.items():
+        if not tris:
+            continue
+        me = bpy.data.meshes.new("m")
+        bm = bmesh.new()
+        for t in tris:
+            vs = [bm.verts.new(Vector(p) / 100.0) for p in t]
+            try:
+                bm.faces.new(vs)
+            except ValueError:
+                pass
+        bm.to_mesh(me)
+        bm.free()
+        ob = bpy.data.objects.new(g[:60], me)
+        ob.color = COLORS.get(g.split("|")[0], (0.5, 0.5, 0.5, 1))
+        bpy.context.scene.collection.objects.link(ob)
+
+
+def render(out, tag, views):
+    sc = bpy.context.scene
+    sc.render.engine = 'BLENDER_WORKBENCH'
+    sc.display.shading.color_type = 'OBJECT'
+    sc.display.shading.light = 'STUDIO'
+    sc.render.resolution_x, sc.render.resolution_y = 960, 600
+    sc.render.film_transparent = False
+    sc.world = bpy.data.worlds.new("w")
+    sc.world.color = (0.93, 0.93, 0.9)
+    pts = [o.matrix_world @ Vector(c) for o in sc.objects if o.type == 'MESH' for c in o.bound_box]
+    lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)))
+    hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)))
+    mid, size = (lo + hi) / 2, max((hi - lo).length, 0.1)
+    cam_data = bpy.data.cameras.new("c")
+    cam_data.type = 'ORTHO'
+    cam_data.ortho_scale = size * 1.05
+    cam = bpy.data.objects.new("c", cam_data)
+    sc.collection.objects.link(cam)
+    sc.camera = cam
+    # gun space: +Y along the barrel, +Z up, +X the gun's left (Pose Lab's gun frame)
+    dirs = {"right": Vector((-1, 0, 0)), "left": Vector((1, 0, 0)), "top": Vector((0, 0, 1)), "bottom": Vector((0, 0, -1)), "front": Vector((0, 1, 0))}
+    made = []
+    for v in views:
+        d = dirs[v]
+        cam.location = mid + d * size * 2
+        up = Vector((0, 1, 0)) if v in ("top", "bottom") else Vector((0, 0, 1))
+        cam.rotation_euler = (-d).to_track_quat('-Z', 'Y' if v not in ("top", "bottom") else 'Y').to_euler()
+        if v in ("top", "bottom"):
+            cam.rotation_euler = (-d).to_track_quat('-Z', 'Y').to_euler()
+        sc.render.filepath = os.path.join(out, "%s_%s.png" % (tag, v))
+        bpy.ops.render.render(write_still=True)
+        made.append(sc.render.filepath)
+    return made
+
+
+def main():
+    job = json.load(open(sys.argv[sys.argv.index("--") + 1], encoding="utf-8"))
+    out = job["out"]
+    os.makedirs(out, exist_ok=True)
+    result = {}
+    for path in job["dumps"]:
+        tag = os.path.splitext(os.path.basename(path))[0]
+        groups, eye = read_obj(path)
+        items = []
+        for g, tris in groups.items():
+            role, comp, asset, bone = (g.split("|") + ["", "", "", ""])[:4]
+            if role == "arms":
+                continue
+            for k, pc in enumerate(sorted(pieces(tris), key=len, reverse=True)):
+                d = describe(pc)
+                d.update({"id": "%s|%s#%d" % (comp, bone, k), "role": role, "component": comp, "asset": asset, "bone": bone})
+                items.append(d)
+        result[tag] = {"eye": eye, "pieces": items, "twins": twins(items)}
+        if job.get("render"):
+            scene(groups)
+            result[tag]["renders"] = render(out, tag, job.get("views", ["right", "left", "top", "bottom"]))
+    json.dump(result, open(os.path.join(out, "riglab.json"), "w", encoding="utf-8"), indent=1)
+    print("RIGLAB DONE %d dumps" % len(result))
+
+
+main()

weaponlab/blender/roll.py

@@ -0,0 +1,98 @@
+"""Motion Lab: a forearm's roll. Turns a hand about its forearm's line through a whole clip, the hand's place kept,
+the roll shared out the way a real forearm shares it: the twist bones take a third and two thirds, the hand all of it
+(the radius turns about the ulna along the whole forearm, not at the wrist). A palm-down fist turned a quarter turn
+stands thumb up, so a hilt in it rises the way a sword's does. Bones as Unreal's mannequin names them (lowerarm_r,
+lowerarm_twist_01_r, lowerarm_twist_02_r, hand_r, index_01_r, pinky_01_r).
+
+    blender -b --factory-startup -P roll.py -- <in.fbx> <out.fbx> <side l|r> <degrees | auto | measure>
+
+auto: the turn that stands the knuckle line (index to little finger) most nearly upright at the clip's first frame
+(each clip from its own start: a backhand cut can start palm up while the others start palm down).
+measure: writes nothing; prints MOTIONLAB PROFILE, the knuckle line's angle about the forearm every few frames
+(0: thumb up; past 80 either way breaks the forearm's range).
+Prints MOTIONLAB ROLL <degrees>."""
+import math
+import sys
+
+import bpy
+from mathutils import Matrix, Vector
+
+args = sys.argv[sys.argv.index("--") + 1:]
+src, out, side, want = args[:4]
+bpy.ops.wm.read_factory_settings(use_empty=True)
+bpy.ops.import_scene.fbx(filepath=src)
+arm = [o for o in bpy.data.objects if o.type == 'ARMATURE'][0]
+act = arm.animation_data.action
+sc = bpy.context.scene
+f0, f1 = int(act.frame_range[0]), int(act.frame_range[1])
+P = arm.pose.bones
+lower, hand = P["lowerarm_" + side], P["hand_" + side]
+twists = [(P[n], k) for n, k in (("lowerarm_twist_01_" + side, 1 / 3), ("lowerarm_twist_02_" + side, 2 / 3)) if n in P]
+for b, _ in twists:
+    assert b.parent == lower, "%s is not the forearm's child" % b.name
+assert hand.parent == lower, "the hand is not the forearm's child"
+W = arm.matrix_world
+
+
+def axis_now():
+    a = (W @ hand.head) - (W @ lower.head)
+    return a.normalized()
+
+
+def turned(pb, ang, axis):
+    """pb's armature-space matrix turned by ang about the forearm's line (through pb's head)."""
+    ax = W.to_3x3().inverted() @ axis
+    head = pb.matrix.translation.copy()
+    return Matrix.Translation(head) @ Matrix.Rotation(ang, 4, ax.normalized()) @ Matrix.Translation(-head) @ pb.matrix
+
+
+def profile():
+    out = []
+    for f in range(f0, f1 + 1, max(1, (f1 - f0) // 12)):
+        sc.frame_set(f)
+        ax = axis_now()
+        k = (W @ P["index_01_" + side].head) - (W @ P["pinky_01_" + side].head)
+        k = (k - ax * k.dot(ax)).normalized()
+        up = Vector((0, 0, 1))
+        up = (up - ax * up.dot(ax)).normalized()
+        out.append((f, round(math.degrees(math.atan2(k.dot(ax.cross(up)), k.dot(up))))))
+    return out
+
+
+if want == "measure":
+    pr = profile()
+    print("MOTIONLAB PROFILE %s" % " ".join("%d:%d" % fa for fa in pr))
+    print("MOTIONLAB PROFILE WORST %d" % max(abs(a) for _, a in pr))
+    sys.exit(0)
+sc.frame_set(f0)
+if want == "auto":
+    axis = axis_now()
+    across = (W @ P["index_01_" + side].head) - (W @ P["pinky_01_" + side].head)
+    best = max(range(-180, 181), key=lambda d: (Matrix.Rotation(math.radians(d), 3, axis) @ across).normalized().z)
+    deg = float(best)
+else:
+    deg = float(want)
+print("MOTIONLAB ROLL %.1f" % deg)
+frames = {}
+for f in range(f0, f1 + 1):
+    sc.frame_set(f)
+    axis = axis_now()
+    frames[f] = [(pb, turned(pb, math.radians(deg) * k, axis)) for pb, k in twists + [(hand, 1.0)]]
+for f, mats in frames.items():
+    sc.frame_set(f)
+    for pb, m in mats:
+        pb.rotation_mode = 'QUATERNION'
+        pb.matrix = m
+        bpy.context.view_layer.update()
+        pb.keyframe_insert("location", frame=f)
+        pb.keyframe_insert("rotation_quaternion", frame=f)
+# check: the hand's place kept, the knuckle line turned
+sc.frame_set(f0)
+print("MOTIONLAB ROLL CHECK knuckles up %.2f" % ((W @ P["index_01_" + side].head) - (W @ P["pinky_01_" + side].head)).normalized().z)
+sc.frame_start, sc.frame_end = f0, f1
+for o in bpy.context.scene.objects:
+    o.select_set(o == arm)
+bpy.ops.export_scene.fbx(filepath=out, use_selection=True, object_types={'ARMATURE'}, add_leaf_bones=False, bake_anim=True,
+                         bake_anim_use_all_actions=False, bake_anim_use_nla_strips=False, bake_anim_force_startend_keying=True,
+                         bake_anim_simplify_factor=0.0)
+print("MOTIONLAB ROLL DONE", out, "armature", arm.name, "frames", f0, f1)

weaponlab/blender/track.py

@@ -0,0 +1,74 @@
+"""Motion Lab: a sliding part's track on its axis. A gun clip (the editor's FBX) whose part
+(a carrier, a bolt, a pump) leaves its line as it travels gets its track rebuilt: its seat is the bind pose (the
+model as built, the part in its rails), it travels only along its axis, by the clip's own travel along that axis,
+frame by frame, and it does not turn. Writes the clip as FBX for the editor.
+
+    blender -b --factory-startup -P track.py -- <in.fbx> <out.fbx> <bone> <root bone name> [x,y,z] [seat x,y,z]
+
+The seat: where the part rests, in its own space (pose location); the bind pose if left out. A part can rest away
+from its bind pose (a carrier 1.5 cm off it in one rifle): take the seat from the idle clip then.
+
+The axis: x,y,z in the model's space as Blender reads the FBX (the bore: Rig Lab's barrel piece), turned into the
+part's own space; without it, the clip's own stroke (which keeps a slanted path slanted)."""
+import sys
+
+import bpy
+from mathutils import Quaternion, Vector
+
+args = sys.argv[sys.argv.index("--") + 1:]
+src, out, bone, root = args[:4]
+given = Vector([float(x) for x in args[4].split(",")]) if len(args) > 4 else None
+seat = Vector([float(x) for x in args[5].split(",")]) if len(args) > 5 else Vector((0, 0, 0))
+bpy.ops.wm.read_factory_settings(use_empty=True)
+bpy.ops.import_scene.fbx(filepath=src)
+arm = [o for o in bpy.data.objects if o.type == 'ARMATURE'][0]
+act = arm.animation_data.action
+sc = bpy.context.scene
+f0, f1 = int(act.frame_range[0]), int(act.frame_range[1])
+pb = arm.pose.bones[bone]
+pb.rotation_mode = 'QUATERNION'
+locs = {}
+for f in range(f0, f1 + 1):
+    sc.frame_set(f)
+    locs[f] = pb.location.copy()
+first = locs[f0]
+far = max(locs, key=lambda f: (locs[f] - first).length)
+axis = (locs[far] - first)
+stroke = axis.length
+axis = axis.normalized() if stroke > 1e-6 else Vector((0, 0, 1))
+if given is not None:
+    # the model's axis in the bone's rest frame (pose locations are in it), signed as the stroke goes
+    g = (arm.matrix_world.to_3x3() @ pb.bone.matrix_local.to_3x3()).inverted() @ given
+    g.normalize()
+    axis = g if g.dot(axis) >= 0 else -g
+# the clip's own travel along that axis (its off-axis part, and the offset it starts from, dropped)
+travel = {f: (locs[f] - first).dot(axis) for f in locs}
+off = max(((locs[f] - first) - axis * travel[f]).length for f in locs)
+print("MOTIONLAB TRACK %s: frames %d-%d, stroke %.3f along %s (local), started %s off its bind seat, most off-axis %.3f"
+      % (bone, f0, f1, stroke, tuple(round(x, 3) for x in axis), tuple(round(x, 3) for x in first), off))
+# rebuild the track: drop the old keys of this bone, key the new ones
+try:                                   # Blender 4.4+: an action's curves live in its slot's channel bag
+    from bpy_extras import anim_utils
+    curves = anim_utils.action_get_channelbag_for_slot(act, arm.animation_data.action_slot).fcurves
+except (ImportError, AttributeError):
+    curves = act.fcurves
+for fc in [fc for fc in curves if fc.data_path.startswith('pose.bones["%s"]' % bone)]:
+    curves.remove(fc)
+for f in range(f0, f1 + 1):
+    pb.location = seat + axis * travel[f]
+    pb.rotation_quaternion = Quaternion((1, 0, 0, 0))
+    pb.scale = Vector((1, 1, 1))
+    pb.keyframe_insert("location", frame=f)
+    pb.keyframe_insert("rotation_quaternion", frame=f)
+    pb.keyframe_insert("scale", frame=f)
+sc.frame_start, sc.frame_end = f0, f1        # the bake writes the scene's range: the clip's own
+for o in bpy.context.scene.objects:
+    o.select_set(o == arm)
+clash = bpy.data.objects.get(root)
+if clash and clash != arm:
+    clash.name = clash.name + "_kept"
+arm.name = root
+bpy.ops.export_scene.fbx(filepath=out, use_selection=True, object_types={'ARMATURE'}, add_leaf_bones=False, bake_anim=True,
+                         bake_anim_use_all_actions=False, bake_anim_use_nla_strips=False, bake_anim_force_startend_keying=True,
+                         bake_anim_simplify_factor=0.0)
+print("MOTIONLAB TRACK DONE", out)

weaponlab/config.py

@@ -0,0 +1,102 @@
+"""A Weapon Lab project: one folder with a weaponlab.json. WEAPONLAB_PROJECT names it; otherwise the current folder.
+
+weaponlab.json (every key optional):
+  {"data": "weaponlab/data",      weapons.json, metrics.json, cases.json, budgets.json, actions.json (in git)
+   "specs": "weaponlab/specs",    one <weapon>.json a weapon (in git)
+   "work": "weaponlab/work",      runs, baseline, evals, proposals, dumps, shots (not in git)
+   "probe": {"command": ["MyGame.exe", "-probe={job}", "-log={work}/probe/game-{stamp}.log"],
+             "timeout_s": 1800,
+             "busy": ["UnrealEditor.exe"],     wait while one runs (another job), up to wait_s
+             "refuse": ["MyGame.exe"],         fail at once while one runs (the player's own game)
+             "wait_s": 0, "warmup": true, "low_priority": false,
+             "job_extra": {"quit": true}},    keys added to every job, for the probe's own use
+   "providers": {"poselab": ["python", "-m", "my_poselab_rows"]},   row sources the Gate may run (a name here
+                                                                     replaces the built-in probe or rig)
+   "blender": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"}
+
+Relative paths are from the project folder. Nothing else in Weapon Lab knows where a project lives."""
+import glob
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+DEFAULTS = {"data": "weaponlab/data", "specs": "weaponlab/specs", "work": "weaponlab/work",
+            "probe": {"command": [], "timeout_s": 1800, "busy": [], "refuse": [], "wait_s": 0, "warmup": True,
+                      "low_priority": False, "job_extra": {}},
+            "providers": {}, "blender": None}
+
+
+class Project:
+    def __init__(self, root=None):
+        self.root = Path(root or os.environ.get("WEAPONLAB_PROJECT") or os.getcwd()).resolve()
+        cfg = self.root / "weaponlab.json"
+        raw = json.loads(cfg.read_text(encoding="utf-8-sig")) if cfg.exists() else {}
+        self.config = {**DEFAULTS, **raw, "probe": {**DEFAULTS["probe"], **raw.get("probe", {})}}
+        self.has_config = cfg.exists()
+
+    def _dir(self, key):
+        p = Path(self.config[key])
+        return p if p.is_absolute() else self.root / p
+
+    @property
+    def data(self):
+        return self._dir("data")
+
+    @property
+    def specs(self):
+        return self._dir("specs")
+
+    @property
+    def work(self):
+        return self._dir("work")
+
+    def ensure(self, *parts):
+        p = self.work.joinpath(*parts)
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def probe(self):
+        return self.config["probe"]
+
+    @property
+    def providers(self):
+        return self.config.get("providers") or {}
+
+    def blender(self):
+        """Blender: WEAPONLAB_BLENDER, the project's setting, the PATH, then the usual install folders."""
+        for cand in (os.environ.get("WEAPONLAB_BLENDER"), self.config.get("blender"), shutil.which("blender")):
+            if cand and Path(cand).exists():
+                return Path(cand)
+        pats = []
+        if sys.platform == "win32":
+            for base in (os.environ.get("ProgramFiles", r"C:\Program Files"), r"D:\Blender", r"C:\Blender"):
+                pats += [os.path.join(base, "Blender Foundation", "Blender*", "blender.exe"), os.path.join(base, "blender.exe")]
+        elif sys.platform == "darwin":
+            pats += ["/Applications/Blender.app/Contents/MacOS/Blender"]
+        else:
+            pats += ["/usr/bin/blender", "/snap/bin/blender", os.path.expanduser("~/blender*/blender")]
+        for pat in pats:
+            hits = sorted(glob.glob(pat), reverse=True)
+            if hits:
+                return Path(hits[0])
+        raise FileNotFoundError("Blender not found: set WEAPONLAB_BLENDER or \"blender\" in weaponlab.json")
+
+
+_current = None
+
+
+def project():
+    """The project in use (read once; reset() after changing WEAPONLAB_PROJECT)."""
+    global _current
+    if _current is None:
+        _current = Project()
+    return _current
+
+
+def reset(root=None):
+    global _current
+    _current = Project(root) if root else None
+    return _current