diff --git a/catalog.json b/catalog.json index 97402bd..3083392 100644 --- a/catalog.json +++ b/catalog.json @@ -32,7 +32,7 @@ "fr": "Lire et modifier la scène ouverte dans Blender grâce à l'extension OpenCode Link : changements typés en un pas d'annulation, inspection du Blender lancé, rendus de vérification et en arrière-plan." }, "app": { "name": "Blender", "versions": ">=5.3" }, - "host": { "protocol": 1, "range": "^0.4.3" }, + "host": { "protocol": 1, "range": "^0.4.4" }, "docs": "https://github.com/NeuralNomadsAI/opencode-integrations/blob/main/integrations/blender/plugin/README.md", "status": "preview", "sources": { "git": ["github:NeuralNomadsAI/opencode-integrations#main::path:integrations/blender/plugin"] } diff --git a/integrations/blender/host/opencode_link/blender_app.py b/integrations/blender/host/opencode_link/blender_app.py index 17c5562..1568ac4 100644 --- a/integrations/blender/host/opencode_link/blender_app.py +++ b/integrations/blender/host/opencode_link/blender_app.py @@ -8,11 +8,13 @@ import os import queue import secrets +import tempfile import threading import time import bpy +from . import hints, op_watch from .process import state as process_state from .wire import HostFailure from .native_refs import NativeRefs @@ -413,6 +415,7 @@ def _with_window(self, fn): def undo_push(self, message): self._with_window(lambda: bpy.ops.ed.undo_push(message=message[:63])) + op_watch.undo_stack_made() def undo(self): epoch = self.script_epoch() @@ -544,6 +547,22 @@ def created_refs(self, op, result): def exec_namespace(self): return {"bpy": bpy, "__name__": "__opencode_execute__"} + @staticmethod + def watch_operators(): + return op_watch.watching() + + @staticmethod + def explain(error, code, filename): + return hints.explain(error, code, filename) + + @staticmethod + def process(): + """This Blender's process and the folder its crash report goes to (.crash.txt, or + blender.crash.txt for an unsaved file): the parent of its session temporary folder.""" + session = bpy.app.tempdir + return {"pid": os.getpid(), + "temp_dir": os.path.dirname(os.path.normpath(session)) if session else tempfile.gettempdir()} + # UI datablocks (windows, screens, workspaces) are not the document's content. _UI_DATA = frozenset(("window_managers", "screens", "workspaces")) diff --git a/integrations/blender/host/opencode_link/blender_manifest.toml b/integrations/blender/host/opencode_link/blender_manifest.toml index cfa4705..b6e0215 100644 --- a/integrations/blender/host/opencode_link/blender_manifest.toml +++ b/integrations/blender/host/opencode_link/blender_manifest.toml @@ -1,7 +1,7 @@ schema_version = "1.0.0" id = "opencode_link" -version = "0.4.3" +version = "0.4.4" name = "OpenCode Link" tagline = "Lets OpenCode work on this Blender session" maintainer = "NeuralNomads" diff --git a/integrations/blender/host/opencode_link/core.py b/integrations/blender/host/opencode_link/core.py index 83ad2b2..ab2bfad 100644 --- a/integrations/blender/host/opencode_link/core.py +++ b/integrations/blender/host/opencode_link/core.py @@ -345,6 +345,8 @@ def _hello(self, params): document = self.app.document() if document: hello["document"] = document + if hasattr(self.app, "process"): + hello["process"] = self.app.process() # the plugin says where the crash report is if Blender closes return hello def _reload(self, params): @@ -908,14 +910,28 @@ def _execute_code(self, params): # modified: inspections and runs after a save leave the file saved; a change is reported, never undone. read_only = params.get("read_only") is True rotations = self.app.rotation_snapshot() if hasattr(self.app, "rotation_snapshot") else None + notes, hint = [], [] def run(): - exec(compile(code, filename or "", "exec"), namespace) # noqa: S102 - the dangerous method + # Operator calls watched (guards, the failing operator named); a failure on Blender's API explained + # by what is valid there, read before the failed run is undone. + watch = self.app.watch_operators() if hasattr(self.app, "watch_operators") else contextlib.nullcontext() + with watch as watched: + try: + exec(compile(code, filename or "", "exec"), namespace) # noqa: S102 - the dangerous method + except Exception as error: + found = self.app.explain(error, code, filename) if hasattr(self.app, "explain") else None + if found: + hint.append(found) + raise + finally: + notes.extend(getattr(watched, "notes", None) or []) check = namespace.get("check_is_finished") return check if callable(check) else None done = self._guarded(run, "code", barrier=not read_only) warnings = self.app.rotation_warnings(rotations) if rotations is not None else [] + warnings.extend(notes) if read_only and done.changed: warnings.append("OpenCode: this read_only run changed the document; no undo step groups or undoes it.") @@ -935,6 +951,8 @@ def finish(deferred=None, deferred_error=None): output["warnings"] = warnings if done.error: output.update(message=done.error, traceback=done.trace) + if hint: + output["hint"] = hint[0] if done.changed: output["restored"] = done.restored if self.residue: diff --git a/integrations/blender/host/opencode_link/hints.py b/integrations/blender/host/opencode_link/hints.py new file mode 100644 index 0000000..467fd2b --- /dev/null +++ b/integrations/blender/host/opencode_link/hints.py @@ -0,0 +1,330 @@ +# SPDX-License-Identifier: GPL-3.0-or-later + +"""What is valid where supplied code failed on Blender's API, read from this Blender (RNA, bpy.ops, node types made +in a temporary tree): the closest names, an operator's real signature, a type's properties, an enumeration's items, +a collection's keys (node sockets included), the node types a tree accepts. Computed before the failed run is +undone, so the data the code made is still there. Never raises: no hint rather than a second error. +""" + +import ast +import difflib +import re + +import bpy + +LIST_MAX = 80 +CLOSEST = 6 + +_OPERATOR = re.compile(r'Calling operator "bpy\.ops\.(\w+)\.(\w+)" error, could not be found') +_KEYWORD = re.compile(r'keyword "(\w+)" (unrecognized|missing)') +_ENUM = re.compile(r'enum "([^"]*)" not found in \(([^)]*)\)') +_KEY = re.compile(r'bpy_prop_collection\[key\]: key "([^"]*)" not found') +_INDEX = re.compile(r"bpy_prop_collection\[index\]: index (-?\d+) out of range") +_NODE = re.compile(r"Node type (\w+) undefined") +_POLL = re.compile(r"Operator bpy\.ops\.(\w+)\.(\w+)\.poll\(\) (.*)", re.S) + + +def explain(error, code, filename): + """A dict of what is valid at the failure, or None.""" + try: + text = str(error) + for rule in (_operator_unknown, _operator_poll, _operator_arguments, _attribute, _enum, _collection, _node_type): + hint = rule(error, text, code, filename) + if hint: + return hint + except Exception: # noqa: BLE001 - a hint is a bonus + return None + return None + + +# -- names ---------------------------------------------------------------------------------------------------- +def _closest(name, names): + names = list(dict.fromkeys(names)) + found = difflib.get_close_matches(name, names, n=CLOSEST, cutoff=0.55) + words = [w for w in re.split(r"[_\W]+|(?<=[a-z])(?=[A-Z])", name.lower()) if len(w) > 2] + for candidate in names: + if len(found) >= CLOSEST * 2: + break + if candidate not in found and any(w in candidate.lower() for w in words): + found.append(candidate) + return found + + +def _listed(names): + names = list(names) + out = {"all": names[:LIST_MAX]} + if len(names) > LIST_MAX: + out["more"] = len(names) - LIST_MAX + return out + + +def _prop(p): + d = {"id": p.identifier, "type": p.type} + if p.type == "ENUM": + d["enum"] = [e.identifier for e in p.enum_items][:LIST_MAX] or "dynamic" + elif p.type in ("POINTER", "COLLECTION"): + d["of"] = p.fixed_type.identifier + elif getattr(p, "array_length", 0): + d["array"] = p.array_length + if p.is_readonly: + d["readonly"] = True + if p.description: + d["desc"] = p.description[:120] + return d + + +def _struct(rna, name, members_of=None): + props = [p for p in rna.properties if p.identifier != "rna_type"] + funcs = list(rna.functions) + names = [p.identifier for p in props] + [f.identifier for f in funcs] + closest = _closest(name, names) + by_id = {p.identifier: p for p in props} + hint = {"type": rna.identifier, "missing": name, + "closest": [(_prop(by_id[c]) if c in by_id else {"id": c, "type": "FUNCTION"}) for c in closest]} + hint["properties"] = _listed(p.identifier for p in props) + if funcs: + hint["functions"] = _listed(f.identifier for f in funcs) + return hint + + +# -- rules ---------------------------------------------------------------------------------------------------- +def _operator_unknown(error, text, code, filename): + m = _OPERATOR.search(text) + if not isinstance(error, AttributeError) or not m: + return None + module, name = m.groups() + modules = sorted(dir(bpy.ops)) + if module not in modules: + return {"operator": "%s.%s" % (module, name), "missing": "module %s" % module, + "closest_modules": _closest(module, modules)} + ops = sorted(dir(getattr(bpy.ops, module))) + return {"operator": "%s.%s" % (module, name), "missing": name, + "closest": ["%s.%s" % (module, o) for o in _closest(name, ops)], "in_module": _listed(ops)} + + +def own(rna): + """A struct's properties by identifier, the struct's own one when a base declares it too (an operator's file + element redeclares PropertyGroup.name).""" + found = {} + for p in rna.properties: + if p.identifier != "rna_type": + found[p.identifier] = p + return list(found.values()) + + +def _signature(rna): + out = [] + for p in rna.properties: + if p.identifier == "rna_type": + continue + d = _prop(p) + if p.type == "COLLECTION": + d["element"] = {"type": p.fixed_type.identifier, "properties": [_prop(e) for e in own(p.fixed_type)], + "note": "each element is a dict holding every one of these properties"} + out.append(d) + return out + + +def _operator_rna(error): + idname = getattr(error, "opencode_operator", None) + if not idname: + return None, None + module, _, name = idname.partition(".") + try: + return idname, getattr(getattr(bpy.ops, module), name).get_rna_type() + except Exception: # noqa: BLE001 + return idname, None + + +def _operator_poll(error, text, code, filename): + m = _POLL.search(text) + if not isinstance(error, RuntimeError) or not m: + return None + idname = "%s.%s" % m.groups()[:2] + ctx = bpy.context + seen = {} + for member in ("window", "screen", "area", "region", "mode", "scene", "view_layer", "active_object", "object", "id"): + try: + value = getattr(ctx, member, None) + except Exception: # noqa: BLE001 + value = None + if member == "mode" or value is None: + seen[member] = value + elif member in ("area", "region"): + seen[member] = value.type + else: + seen[member] = getattr(value, "name", None) or type(value).__name__ + hint = {"operator": idname, "poll": m.group(3).strip()[:300], "context": seen, + "give_context": "with bpy.context.temp_override(window=..., area=..., region=..., id=..., active_object=...)"} + try: + rna = getattr(getattr(bpy.ops, m.group(1)), m.group(2)).get_rna_type() + hint["description"] = (rna.description or "")[:300] + except Exception: # noqa: BLE001 + pass + return hint + + +def _operator_arguments(error, text, code, filename): + idname, rna = _operator_rna(error) + if rna is None or not isinstance(error, (TypeError, ValueError)): + return None + hint = {"operator": idname, "signature": _signature(rna)} + keyword = _KEYWORD.search(text) + if keyword and keyword.group(2) == "unrecognized": + hint["unknown"] = keyword.group(1) + hint["closest"] = _closest(keyword.group(1), [p.identifier for p in rna.properties if p.identifier != "rna_type"]) + elif keyword: + hint["missing"] = keyword.group(1) + enum = _ENUM.search(text) + if enum: + items = [i.strip().strip("'\"") for i in enum.group(2).split(",") if i.strip()] + hint["invalid"] = enum.group(1) + hint["closest"] = _closest(enum.group(1), items) + return hint + + +def _attribute(error, text, code, filename): + if not isinstance(error, AttributeError): + return None + obj, name = getattr(error, "obj", None), getattr(error, "name", None) + if not name: + return None + if obj is bpy.types: + return {"missing": "bpy.types.%s" % name, "closest": _closest(name, dir(bpy.types))} + if obj is bpy.context: + return {"missing": "bpy.context.%s" % name, "closest": _closest(name, dir(bpy.context))} + rna = getattr(obj, "bl_rna", None) + return _struct(rna, name) if rna is not None else None + + +def _enum(error, text, code, filename): + m = _ENUM.search(text) + if not isinstance(error, TypeError) or not m: + return None + items = [i.strip().strip("'\"") for i in m.group(2).split(",") if i.strip()] + return {"invalid": m.group(1), "closest": _closest(m.group(1), items), "items": items[:LIST_MAX]} + + +def _collection(error, text, code, filename): + key = _KEY.search(text) + index = _INDEX.search(text) + if not (isinstance(error, KeyError) and key) and not (isinstance(error, IndexError) and index): + return None + wanted = key.group(1) if key else int(index.group(1)) + found = _failing_value(error, code, filename, + lambda node: isinstance(node, ast.Subscript) and _constant(node.slice) == wanted, + lambda node: node.value) + if found is None: + return None + path, collection = found + if not isinstance(collection, bpy.types.bpy_prop_collection): + return None + keys, labels = [], [] + for item in collection: + name = getattr(item, "name", None) or getattr(item, "identifier", None) + if name is None: + continue + ident = getattr(item, "identifier", None) + keys.append(name) + if ident and ident != name: + keys.append(ident) + labels.append("%s (identifier %s)" % (name, ident) if ident and ident != name else name) + hint = {"collection": path, "length": len(collection), "keys": _listed(labels)} + if key: + hint["missing"] = wanted + hint["closest"] = _closest(wanted, keys) + owner = getattr(collection, "id_data", None) + if owner is not None: + hint["of"] = "%s %r" % (type(owner).__name__, owner.name) + return hint + + +def _node_type(error, text, code, filename): + m = _NODE.search(text) + if not isinstance(error, RuntimeError) or not m: + return None + wanted = m.group(1) + names = [n for n in dir(bpy.types) if _is_node(getattr(bpy.types, n, None))] + hint = {"missing": wanted} + found = _failing_value( + error, code, filename, + lambda node: (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == "new" + and node.args and _constant(node.args[0]) == wanted), + lambda node: node.func.value) + tree_type = None + if found is not None and getattr(found[1], "id_data", None) is not None: + tree_type = found[1].id_data.bl_idname + hint["tree_type"] = tree_type + candidates = _closest(wanted, names) + if tree_type: + hint["closest_creatable"] = _creatable(tree_type, candidates) + else: + hint["closest"] = candidates + return hint + + +# -- helpers ---------------------------------------------------------------------------------------------------- +def _is_node(cls): + rna = getattr(cls, "bl_rna", None) + while rna is not None: + if rna.identifier == "Node": + return True + rna = rna.base + return False + + +def _creatable(tree_type, candidates): + out = [] + with bpy.data.temp_data() as data: + tree = data.node_groups.new("hints", tree_type) + for name in candidates: + try: + node = tree.nodes.new(name) + except Exception: # noqa: BLE001 + continue + out.append({"type": name, "name": node.name, + "inputs": [s.name for s in node.inputs][:24], "outputs": [s.name for s in node.outputs][:24]}) + tree.nodes.remove(node) + return out + + +def _constant(node): + return node.value if isinstance(node, ast.Constant) else None + + +def _failing_value(error, code, filename, match, part): + """The value of `part(node)` for the first AST node of the failing line that `match`es, evaluated from the + failing frame's names with attribute reads and constant subscripts only (no call). (source, value) or None.""" + if not isinstance(code, str): + return None + frame, line = None, None + tb = error.__traceback__ + while tb is not None: + if tb.tb_frame.f_code.co_filename == (filename or ""): + frame, line = tb.tb_frame, tb.tb_lineno + tb = tb.tb_next + if frame is None: + return None + scope = dict(frame.f_globals) + scope.update(frame.f_locals) + for node in ast.walk(ast.parse(code)): + if getattr(node, "lineno", None) is None or not node.lineno <= line <= node.end_lineno or not match(node): + continue + target = part(node) + try: + return ast.unparse(target), _value(target, scope) + except Exception: # noqa: BLE001 - not a plain read: try the next candidate + continue + return None + + +def _value(node, scope): + if isinstance(node, ast.Name): + if node.id not in scope: + raise LookupError(node.id) + return scope[node.id] + if isinstance(node, ast.Attribute): + return getattr(_value(node.value, scope), node.attr) + if isinstance(node, ast.Subscript) and isinstance(node.slice, ast.Constant): + return _value(node.value, scope)[node.slice.value] + raise LookupError(type(node).__name__) diff --git a/integrations/blender/host/opencode_link/op_watch.py b/integrations/blender/host/opencode_link/op_watch.py new file mode 100644 index 0000000..4dc7965 --- /dev/null +++ b/integrations/blender/host/opencode_link/op_watch.py @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: GPL-3.0-or-later + +"""The operator calls of supplied code (execute_code), watched while it runs. + +Every `bpy.ops` callable the code creates is wrapped: a failing call names its operator, so the error's hint reads +the operator's real signature. Two calls that close Blender 5.3 from a script are prepared first, as Blender's +interactive path prepares them: + +- a mask stroke (`sculpt.brush_stroke` with the Mask brush or brush_toggle='MASK') on a multiresolution object. + The operator's interactive path creates the grid mask layer before painting; its script path does not, and the + stroke writes into grids never allocated (a heap corruption: Blender closes on the next mode switch or redraw). + The layer is created first, as the interactive path does: inverting the mask twice keeps its values. +- a sculpt-mode operator in a Blender without interface: its sculpt undo step reads the undo stack, which a + background Blender makes at its first undo step only. One step is pushed first when none was yet (an + execute_code that changes the document already pushed its barrier step). + +Where `bpy.ops` creates its callables otherwise (another Blender version), nothing is wrapped. +""" + +import contextlib + +import bpy + +# Sculpt-mode operators that record no sculpt undo step. +_NO_SCULPT_UNDO = frozenset(("sculpt.sculptmode_toggle",)) +_undo_stack = {"made": False} +UNDO_STEP = "OpenCode: undo stack" +UNDO_NOTE = ("OpenCode: pushed a first undo step before %s: a Blender without interface makes its undo stack then, " + "and a sculpt-mode operator closes it without one.") +MASK_LAYER_NOTE = ("OpenCode: created the multiresolution mask layer of %r before the scripted mask stroke " + "(Blender's script path of sculpt.brush_stroke skips it and closes Blender).") + + +def undo_stack_made(): + """An undo step was pushed: from then on this Blender has its undo stack.""" + _undo_stack["made"] = True + + +class _Watch(object): + def __init__(self, create): + self.create = create # the original factory: the guards' own calls are not watched + self.notes = [] + self.prepared = set() + + def before(self, idname, args, kwargs): + module = idname.partition(".")[0] + if module not in ("sculpt", "paint"): + return + obj = getattr(bpy.context, "active_object", None) + sculpting = obj is not None and getattr(obj, "mode", None) == "SCULPT" + if not sculpting: + return + if bpy.app.background and idname not in _NO_SCULPT_UNDO and not _undo_stack["made"]: + self.create("ed", "undo_push")(message=UNDO_STEP) + undo_stack_made() + self.notes.append(UNDO_NOTE % idname) + if idname == "sculpt.brush_stroke" and not _invoked(args) and _masks(kwargs) and _multires(obj): + key = obj.as_pointer() + if key in self.prepared: + return + invert = self.create("paint", "mask_flood_fill") + invert(mode="INVERT") + invert(mode="INVERT") + self.prepared.add(key) + self.notes.append(MASK_LAYER_NOTE % obj.name) + + +def _invoked(args): + # An INVOKE_* call goes through the interactive path, which prepares the layer itself. + return bool(args) and isinstance(args[0], str) and args[0].startswith("INVOKE") + + +def _masks(kwargs): + if kwargs.get("brush_toggle") == "MASK": + return True + paint = getattr(bpy.context.tool_settings, "sculpt", None) + brush = getattr(paint, "brush", None) + return getattr(brush, "sculpt_brush_type", None) == "MASK" + + +def _multires(obj): + return any(m.type == "MULTIRES" and m.show_viewport for m in getattr(obj, "modifiers", ())) + + +class _Operator(object): + """A bpy.ops callable: the same call, poll, get_rna_type and repr, watched.""" + + __slots__ = ("_op", "_idname", "_watch") + + def __init__(self, op, idname, watch): + self._op = op + self._idname = idname + self._watch = watch + + def __call__(self, *args, **kwargs): + try: + self._watch.before(self._idname, args, kwargs) + return self._op(*args, **kwargs) + except Exception as error: + try: + error.opencode_operator = self._idname # read by hints.explain + except Exception: # noqa: BLE001 - an exception without attributes keeps its message + pass + raise + + def __getattr__(self, name): + return getattr(self._op, name) + + def __repr__(self): + return repr(self._op) + + +@contextlib.contextmanager +def watching(): + """Wraps the bpy.ops callables created inside the block; yields the watch (its notes).""" + ops = getattr(bpy, "ops", None) + create = getattr(ops, "_op_create_function", None) + if create is None: + yield _Watch(None) + return + watch = _Watch(create) + ops._op_create_function = lambda module, func: _Operator(create(module, func), "%s.%s" % (module, func), watch) + try: + yield watch + finally: + ops._op_create_function = create diff --git a/integrations/blender/host/ops.json b/integrations/blender/host/ops.json index 14d5d46..6fb3854 100644 --- a/integrations/blender/host/ops.json +++ b/integrations/blender/host/ops.json @@ -1,6 +1,6 @@ { "addon": "opencode_link", - "version": "0.4.3", + "version": "0.4.4", "protocol": 1, "method": "apply", "wire": "params.operations: [{op, args}] with every op below (an edit batch); unknown ops and fields are refused", diff --git a/integrations/blender/plugin/README.md b/integrations/blender/plugin/README.md index 9238f5d..443f0ce 100644 --- a/integrations/blender/plugin/README.md +++ b/integrations/blender/plugin/README.md @@ -39,24 +39,24 @@ The **Plugins** section lists OpenCode for Blender as an integration: its versio - **Which Blender.** `blender_hosts` and `blender_context` name the Blender this conversation acts on (`attached_to`: offer and label). Other conversations attaching or detaching other Blenders, or Blenders appearing, never make this conversation's ownership unverifiable; a permission prompt is refused only when this conversation's own Blender changed meanwhile. - **Across an OpenCode restart.** The plugin keeps each conversation's attachment in its storage (the Blender's offer key only as a SHA-256 digest, with the label; never a token, port or script handle). When the same Blender offers itself again after a restart, the conversation is attached back without asking, once its ownership is verified at its Location; never inside a read. A kept attachment lasts while its Blender is offered and two minutes after it stops; detaching removes it at once. A Blender restarted itself is a new offer: the conversation attaches again as above. - **Upgrading without restarting OpenCode.** A daemon that loads a newer version of the plugin without restarting can keep the older one in memory. Each version keeps its own list of offered Blenders, named after the add-on versions it accepts, so a Blender is always judged by the version that lists it; it offers itself again within 5 seconds. -- **The working method.** When a conversation attaches a Blender, a short method joins it (an instructions entry, about 200 tokens): read the Blender version first, ask Blender itself (`blender_inspect`) before writing code in an area that changed recently, verify each step by its result (`blender_verify` for anything that renders), and write down what you discover. +- **The working method.** When a conversation attaches a Blender, a short method joins it (an instructions entry, about 250 tokens): read the Blender version first, inspect the exact element before coding it (`blender_inspect`, its `search` to find where a setting lives), read an error's hint and inspect again instead of guessing, give operators their context with `temp_override`, turn the acceptance criteria into checks run with `blender_verify` (`criteria`, `visible`) and report the measured values, and write down what you discover. - **Session binding.** Clients read `bindingRead({ sessionID })` at the session's current OpenCode Location: `attached` identifies its live offer and safe label, `none` confirms a verified session without a binding, and `unknown` keeps the state unverified. `status_changed {}` invalidates the read; `detachHost({ sessionID })` detaches. See the [draft 0.2 RPC contract](../../../spec/rpc-contract.md). ## Tools -| Tool | What it does | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blender_hosts` | The offered Blenders (label, document, Blender version, whether this conversation or another one is attached to each) and the add-on's install state; `attach` attaches one (asks permission), `detach` releases this conversation's. | -| `blender_install_host` | Installs or updates OpenCode Link in the newest Blender 5.3 or later (asks permission). | -| `blender_context` | A compact read of the scene: revision, scene settings, collections, markers, a page of objects with their transforms; `ref` gives one object in detail (world bounds, pose bones); `include: ["parts"]` lists a mesh's loose parts (world box, material, dominant vertex group), `region` keeps those in a world box. | -| `blender_apply` | Up to 50 typed operations as one undo step, checked whole before anything changes; a failure part-way restores every changed field. See [Typed operations](#typed-operations). | -| `blender_execute_code` | Python in Blender; every run asks the `blender_execute_code` permission. See [Code execution](#code-execution). | -| `blender_lab` | One of Blender Lab's tools (object and file summaries, screenshots, views, thumbnails), run by the add-on; images come back as attachments. | -| `blender_inspect` | What this Blender really exposes for a type (properties, functions, node sockets), an operator or live data, with the links to the API docs, manual and release notes of its version. | -| `blender_verify` | A low-resolution render of the scene's final output (sequencer, compositing), or from a free viewpoint (`view`: location, target, lens), with facts: black or transparent, brightness, the camera used and why, strips, instances. `frames` returns several frames as one contact sheet; `scene` chooses the scene (the facts name the one read, and warn when it is a shot of a montage). Settings, cameras and frame are restored; the revision stays. | -| `blender_render` | A render in a separate background Blender to an exact output (an image, a frame pattern or an H.264 video, with the montage's sound when it has any; the result lists the streams written), followed as a task (`task`, `wait_s` up to an hour, `cancel`). It renders the saved file (`unsaved`). | -| `blender_save` | Saves the file, under a path, or a copy; a save that failed because another process held the file a moment is retried once and says so (`retried`). | -| `blender_import` | BlenderKit and Sketchfab searches, and imports from them or from a file (glTF, FBX, OBJ, USD; a path or an https URL), followed as a task (`task`, `wait_s`, `cancel`). BlenderKit and Sketchfab need their add-ons. | +| Tool | What it does | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `blender_hosts` | The offered Blenders (label, document, Blender version, whether this conversation or another one is attached to each) and the add-on's install state; `attach` attaches one (asks permission), `detach` releases this conversation's. | +| `blender_install_host` | Installs or updates OpenCode Link in the newest Blender 5.3 or later (asks permission). | +| `blender_context` | A compact read of the scene: revision, scene settings, collections, markers, a page of objects with their transforms; `ref` gives one object in detail (world bounds, pose bones); `include: ["parts"]` lists a mesh's loose parts (world box, material, dominant vertex group), `region` keeps those in a world box. | +| `blender_apply` | Up to 50 typed operations as one undo step, checked whole before anything changes; a failure part-way restores every changed field. See [Typed operations](#typed-operations). | +| `blender_execute_code` | Python in Blender; every run asks the `blender_execute_code` permission. See [Code execution](#code-execution). | +| `blender_lab` | One of Blender Lab's tools (object and file summaries, screenshots, views, thumbnails), run by the add-on; images come back as attachments. | +| `blender_inspect` | What this Blender really exposes: `search` (words found in its types, properties, functions and operators, with their paths and the properties that lead to a type), a type (properties, functions; a node type's real sockets, made in the `tree` named), an operator (parameters, the element type of its collections, its poll here with Blender's reason) or live data; entries beyond `limit` are named, `match` takes a glob or words. With the links to the API docs, manual and release notes of its version. | +| `blender_verify` | `criteria`: the agent's checks (a read-only expression or a `bpy.data` path, a comparison, a value, frames), each measured on the evaluated scene and passed or failed with the value; `visible`: whether an object shows in the render at a frame, otherwise every reason found (out of frame, hidden in render, collection excluded, view layer not rendered, holdout, transparent or zero-density material, no geometry, hidden behind another object). Without them, or with `render` or `view`: a low-resolution render of the scene's final output, or from a free viewpoint (`view`: location, target, lens), with facts: black or transparent, brightness, the camera used and why, strips, instances. `frames` returns several frames as one contact sheet; `scene` chooses the scene (the facts name the one read, and warn when it is a shot of a montage). Settings, cameras and frame are restored; the revision stays. | +| `blender_render` | A render in a separate background Blender to an exact output (an image, a frame pattern or an H.264 video, with the montage's sound when it has any; the result lists the streams written), followed as a task (`task`, `wait_s` up to an hour, `cancel`). It renders the saved file (`unsaved`). | +| `blender_save` | Saves the file, under a path, or a copy; a save that failed because another process held the file a moment is retried once and says so (`retried`). | +| `blender_import` | BlenderKit and Sketchfab searches, and imports from them or from a file (glTF, FBX, OBJ, USD; a path or an https URL), followed as a task (`task`, `wait_s`, `cancel`). BlenderKit and Sketchfab need their add-ons. | `blender_inspect`, `blender_verify`, `blender_render` and `blender_save` send fixed programs of the package (`programs/*.py`) through the host's code execution, read only, with their parameters as JSON data; they ask no permission because they run no code from the model. Without `if_revision` and `command_id`, `blender_apply` applies to the document as it is now under a new `command_id`; with them it is refused when the scene changed, and a replayed `command_id` applies nothing. @@ -129,6 +129,8 @@ Add-on settings (Preferences ▸ Add-ons ▸ OpenCode Link): _OpenCode service_ `blender_execute_code` runs Python in Blender with your rights: it can read and write files, start processes and reach the network. The add-on lists it while it is enabled, and **every run asks the `blender_execute_code` permission** ("ask" unless you allow it in OpenCode's permission settings); a refused run executes nothing. A run that changes the scene is one undo step; a failing one is undone. Blender keeps linked data outside its undo (a linked library, the brush a sculpt or paint mode links): it is named in `restoration.kept_linked`, unused and not saved. When an undo cannot be proven, OpenCode Link is **quarantined**: reads, `blender_verify`, `blender_inspect` and `read_only` code still run, changes wait; `blender_context` shows `quarantine.may_have_changed`, and once you checked it, `blender_context` with `release_quarantine` (that read's revision) lifts it, as does Reset in the add-on's panel. A long script can be a file (`path`): it is read as written, with no escaping through a JSON or JavaScript string, and its tracebacks name the file. See [`SECURITY.md`](../../../SECURITY.md). +A run that fails on Blender's API carries a `hint` read from that Blender before the run is undone: for an unknown attribute, the closest names and the type's properties; for an operator's arguments, its real signature (with the element type of its collections) and the closest names; for an invalid enumeration value, the closest items; for a missing key, the collection's keys (a node's sockets included); for an unknown node type, the closest types the tree creates, with their sockets; for a failed poll, Blender's reason and the context the code had. While a run executes, OpenCode Link prepares two calls Blender 5.3 closes on from a script, as Blender's interactive path prepares them, and says so in `warnings`: a mask stroke (`sculpt.brush_stroke` with the Mask brush or `brush_toggle='MASK'`) on a multiresolution object gets its mask layer first, and in a Blender without interface a sculpt-mode operator gets a first undo step when none was pushed yet. If the attached Blender closes, the next call says so with the crash report it wrote (`.crash.txt` in its temporary folder), instead of an unreachable host. + ## Blender limits - Blender 5.3 or later; edits run in Object mode only. diff --git a/integrations/blender/plugin/host/blender/opencode_link-0.4.3.zip b/integrations/blender/plugin/host/blender/opencode_link-0.4.4.zip similarity index 97% rename from integrations/blender/plugin/host/blender/opencode_link-0.4.3.zip rename to integrations/blender/plugin/host/blender/opencode_link-0.4.4.zip index 050c614..4a7a8d4 100644 Binary files a/integrations/blender/plugin/host/blender/opencode_link-0.4.3.zip and b/integrations/blender/plugin/host/blender/opencode_link-0.4.4.zip differ diff --git a/integrations/blender/plugin/methods/tools/blender_inspect.json b/integrations/blender/plugin/methods/tools/blender_inspect.json index 1769fab..4cc5d5e 100644 --- a/integrations/blender/plugin/methods/tools/blender_inspect.json +++ b/integrations/blender/plugin/methods/tools/blender_inspect.json @@ -1,17 +1,25 @@ { "name": "blender_inspect", "domain": "tools", - "description": "Ask THIS Blender what it really exposes, in one call: a type (properties with type, enum values, default, range; functions and parameters; subtypes; for a node type its real input and output sockets), an operator (parameters, poll) and/or live data (a bpy.data collection, a name and an optional RNA path, with current values; for a Geometry Nodes modifier, its inputs and which access to them works). Returns the Blender version and the links to the official API docs, manual and Python API release notes of this version. Read only.", + "description": "Ask THIS Blender what it really exposes, in one call: search (words found in its types, properties, functions and operators, with their paths and the properties that lead to a type), a type (properties with type, enum values, default, range; functions; subtypes; for a node type its real sockets, in the tree you name), an operator (parameters, the element type of its collections, poll in this context with Blender's reason) and/or live data (a bpy.data collection, a name and an optional RNA path, with current values; for a Geometry Nodes modifier, its inputs and which access works). Entries beyond limit are still named. Returns the version and the links to this version's API docs, manual and Python API release notes. Read only.", "kind": "host-backed", "risk": "read", "args": { + "search": { + "type": "string", + "description": "Words, e.g. \"light linking\", \"compositing node group\", \"cache baked\"." + }, "type": { "type": "string", - "description": "bpy.types name, e.g. NodesModifier, Strip, GreasePencil, ActionChannelbag." + "description": "bpy.types name, e.g. NodesModifier, OperatorStrokeElement, GeometryNodeSimulationInput." + }, + "tree": { + "type": "string", + "description": "For a node type: the tree to make it in (shader, geometry, compositing, texture, or a NodeTree type)." }, "operator": { "type": "string", - "description": "e.g. sequencer.effect_strip_add." + "description": "e.g. sculpt.brush_stroke." }, "data": { "type": "object", @@ -19,11 +27,11 @@ }, "match": { "type": "string", - "description": "Glob on property and function names." + "description": "Keep the properties and functions matching: a glob on names (detail_*), or words found in name or description." }, "limit": { "type": "integer", - "description": "At most this many entries (1 to 200).", + "description": "Entries in detail (1 to 200); the others are named.", "default": 60 } }, diff --git a/integrations/blender/plugin/methods/tools/blender_verify.json b/integrations/blender/plugin/methods/tools/blender_verify.json index aac4192..b67bcfe 100644 --- a/integrations/blender/plugin/methods/tools/blender_verify.json +++ b/integrations/blender/plugin/methods/tools/blender_verify.json @@ -1,10 +1,25 @@ { "name": "blender_verify", "domain": "tools", - "description": "Render frames at low resolution and return the image with facts: black or transparent, mean brightness, the camera actually used and why, sequencer strips, compositing state, evaluated instances per object. By default the scene's final output (sequencer when used, compositing when active); view renders from a free viewpoint instead (a temporary camera; the scene's cameras and markers stay as they are). frames renders several frames as one contact sheet, left to right and top to bottom. Render settings, cameras and the current frame are restored; the revision stays.", + "description": "Check a result by measurement. criteria: your own acceptance checks, each measured on the evaluated scene at its frames and passed or failed with the measured value. visible: whether an object shows in the render at a frame, otherwise every reason found (out of frame, hidden in render, collection excluded, view layer not rendered, holdout, transparent or zero-density material, no geometry, hidden behind another object). Render (the default without criteria or visible, or with render or view): low-resolution frames with facts (black or transparent, brightness, the camera used and why, sequencer, compositing, instances). Settings, cameras and the current frame are restored; the revision stays.", "kind": "host-backed", "risk": "read", "args": { + "criteria": { + "type": "array", + "description": "Up to 50 checks: {expr: a read-only Python expression, or path: from bpy.data; op: < <= > >= == != approx between in contains; value; frame or frames (default: the call's); tol (approx, default 1e-4); label}. In expr: bounds(name).min.z (world bounds of the evaluated geometry), ev(name) (evaluated object), world(name), scene, frame, bpy, Vector, math. Vectors compare element by element.", + "items": { + "type": "object" + } + }, + "visible": { + "type": "object", + "description": "{object, frame or frames}: does it show in the render, and why not." + }, + "render": { + "type": "boolean", + "description": "Also render (default: only without criteria and visible)." + }, "scene": { "type": "string", "description": "Default: the active scene. The facts say which scene was read (scene, scene_read) and warn when it is a shot shown by another scene's montage." @@ -22,7 +37,7 @@ }, "view": { "type": "object", - "description": "{location: [x, y, z], target: [x, y, z] or an object name or {object, bone}, lens?: mm (default 50)}: a free viewpoint, world space." + "description": "{location: [x, y, z], target: [x, y, z] or an object name or {object, bone}, lens?: mm (default 50)}: render from a free viewpoint, world space." }, "size": { "type": "integer", diff --git a/integrations/blender/plugin/package.json b/integrations/blender/plugin/package.json index 7e62b25..43facbd 100644 --- a/integrations/blender/plugin/package.json +++ b/integrations/blender/plugin/package.json @@ -1,6 +1,6 @@ { "name": "@neuralnomads/opencode-blender", - "version": "0.4.3", + "version": "0.4.4", "description": "OpenCode for Blender: lets OpenCode read and change an open Blender scene through an authenticated local host, with typed edits, inspection, verification renders and background renders.", "license": "MIT AND GPL-3.0-or-later", "type": "module", @@ -60,10 +60,10 @@ "host": { "app": "blender", "protocol": 1, - "range": "^0.4.3", + "range": "^0.4.4", "appVersions": ">=5.3", - "payload": "host/blender/opencode_link-0.4.3.zip", - "sha256": "cf388a718dd4e6d1654ee89c40779e4bc53abc4deb664df76d412b235bb98a27" + "payload": "host/blender/opencode_link-0.4.4.zip", + "sha256": "4c22359a8e759ae1da003eef5213d3c90334096278260e1968a535b1cc1d4f3c" } } } diff --git a/integrations/blender/plugin/programs/inspect.py b/integrations/blender/plugin/programs/inspect.py index eaa974e..5b41589 100644 --- a/integrations/blender/plugin/programs/inspect.py +++ b/integrations/blender/plugin/programs/inspect.py @@ -1,17 +1,42 @@ # SPDX-License-Identifier: GPL-3.0-or-later # blender_inspect (fixed program, read only): what THIS Blender really exposes for a type, an operator or -# live data, with the official documentation and Python API release notes of this version. -# PARAMS is prepended by the plugin: {"type"?, "operator"?, "data"?: {"collection", "name", "path"?}, "match"?, "limit"?} +# live data, or where words appear in its API, with the official documentation and Python API release notes of +# this version. Everything is read from the running Blender (RNA, bpy.ops, nodes made in a temporary tree). +# PARAMS is prepended by the plugin: {"type"?, "operator"?, "data"?: {"collection", "name", "path"?}, "search"?, +# "tree"?, "match"?, "limit"?} +import difflib import fnmatch import math +import re import bpy P = PARAMS # noqa: F821 VER = "%d.%d" % bpy.app.version[:2] API = "https://docs.blender.org/api/%s/" % VER -LIMIT = int(P.get("limit") or 60) +LIMIT = max(1, min(200, int(P.get("limit") or 60))) MATCH = P.get("match") +NAMES_MAX = 400 # names listed beyond the detailed entries, so nothing is cut silently + + +def matches(ident, name="", desc=""): + """match: a glob on the identifier when it has * ? or [, otherwise words all found in the identifier, name or + description (case-insensitive).""" + if not MATCH: + return True + if any(c in MATCH for c in "*?["): + return fnmatch.fnmatchcase(ident, MATCH) + hay = " ".join((ident, name or "", desc or "")).lower() + return all(w in hay for w in MATCH.lower().split()) + + +def detailed(items, info, key, d): + """The first LIMIT items in detail under key; the others by name, with how to see them.""" + d[key] = [info(i) for i in items[:LIMIT]] + rest = [i.identifier for i in items[LIMIT:]] + if rest: + d[key + "_more"] = {"count": len(rest), "names": rest[:NAMES_MAX], + "details": "pass match (a glob or words) or a larger limit"} out = { "blender": bpy.app.version_string, "links": { @@ -99,19 +124,27 @@ def struct_info(rna, holder=None): d = {"type": rna.identifier, "base": rna.base.identifier if rna.base else None, "doc": "%sbpy.types.%s.html" % (API, rna.identifier)} if rna.description: d["desc"] = rna.description[:200] - props = [p for p in rna.properties if p.identifier != "rna_type" and (not MATCH or fnmatch.fnmatchcase(p.identifier, MATCH))] - d["properties"] = [prop_info(p, holder) for p in props[:LIMIT]] - if len(props) > LIMIT: - d["properties_truncated"] = len(props) - funcs = [f for f in rna.functions if not MATCH or fnmatch.fnmatchcase(f.identifier, MATCH)] - d["functions"] = [func_info(f) for f in funcs[:LIMIT]] + props = [p for p in rna.properties if p.identifier != "rna_type" and matches(p.identifier, p.name, p.description)] + detailed(props, lambda p: prop_info(p, holder), "properties", d) + funcs = [f for f in rna.functions if matches(f.identifier, "", f.description)] + detailed(funcs, func_info, "functions", d) subs = sorted({t.bl_rna.identifier for t in (getattr(bpy.types, n, None) for n in dir(bpy.types)) if hasattr(t, "bl_rna") and t.bl_rna.base is not None and t.bl_rna.base.identifier == rna.identifier}) if subs: - d["subtypes"] = subs[:80] + d["subtypes"] = subs[:NAMES_MAX] + if MATCH and not props and not funcs: + d["match_found_nothing"] = {"match": MATCH, "properties": [p.identifier for p in rna.properties][:NAMES_MAX]} return d +def element_info(p): + """The element type of an operator's collection (or pointer) property: what each item holds.""" + rna = p.fixed_type + own = {e.identifier: e for e in rna.properties if e.identifier != "rna_type"} # the struct's own one wins + return {"type": rna.identifier, "properties": [prop_info(e) for e in own.values()], + **({"note": "each element: a dict holding every one of these properties"} if p.type == "COLLECTION" else {})} + + def modifier_inputs(mod): """Geometry Nodes modifier inputs: interface sockets and the access that actually works here.""" group = getattr(mod, "node_group", None) @@ -199,14 +232,61 @@ def socket_info(s, temporary, values=True): return d -def node_info(rna, live=None): +def tree_types(): + """The node tree types of this Blender (NodeTree's subtypes).""" + return sorted(n for n in dir(bpy.types) if n != "NodeTree" and is_type_of(getattr(bpy.types, n, None), "NodeTree")) + + +def is_type_of(cls, base): + rna = getattr(cls, "bl_rna", None) + while rna is not None: + if rna.identifier == base: + return True + rna = rna.base + return False + + +def chosen_tree(value): + """tree: a NodeTree type, or a word its name starts with (shader, geometry, compositing, texture).""" + trees = tree_types() + if value in trees: + return value + found = [t for t in trees if t.lower().startswith(str(value).lower()[:6])] + if len(found) == 1: + return found[0] + raise ValueError("tree %r: one of %s" % (value, trees)) + + +def creatable(tree_type, wanted): + """Node types closest to `wanted` that this Blender creates in a tree of tree_type, with their sockets' names.""" + names = [n for n in dir(bpy.types) if is_type_of(getattr(bpy.types, n, None), "Node")] + words = [w for w in re.split(r"(?<=[a-z])(?=[A-Z])", wanted) if len(w) > 2 and w not in ("Node", "Shader", "Geometry", "Compositor", "Function", "Texture")] + candidates = difflib.get_close_matches(wanted, names, n=8, cutoff=0.5) + candidates += [n for n in names if n not in candidates and any(w.lower() in n.lower() for w in words)] + out = [] + with bpy.data.temp_data() as td: + tree = td.node_groups.new("inspect", tree_type) + for name in candidates: + try: + node = tree.nodes.new(name) + except Exception: # noqa: BLE001 + continue + out.append({"type": name, "label": node.name, "inputs": [s.name for s in node.inputs][:24], + "outputs": [s.name for s in node.outputs][:24]}) + tree.nodes.remove(node) + if len(out) >= 12: + break + return out + + +def node_info(rna, live=None, tree_type=None): """Own properties (with values for a live node) and real sockets of a node type or a node.""" d = {"type": rna.identifier, "base": rna.base.identifier if rna.base else None, "doc": "%sbpy.types.%s.html" % (API, rna.identifier)} if rna.description: d["desc"] = rna.description[:200] - own = [p for p in rna.properties if p.identifier not in NODE_PROPS and (not MATCH or fnmatch.fnmatchcase(p.identifier, MATCH))] - d["properties"] = [prop_info(p, live) for p in own[:LIMIT]] - tree_type = next((tree for prefix, tree in TREES if rna.identifier.startswith(prefix)), "GeometryNodeTree") + own = [p for p in rna.properties if p.identifier not in NODE_PROPS and matches(p.identifier, p.name, p.description)] + detailed(own, lambda p: prop_info(p, live), "properties", d) + tree_type = tree_type or next((tree for prefix, tree in TREES if rna.identifier.startswith(prefix)), "GeometryNodeTree") with bpy.data.temp_data() as td: tree = td.node_groups.new("inspect", live.id_data.bl_idname if live is not None else tree_type) try: @@ -214,6 +294,7 @@ def node_info(rna, live=None): except Exception as ex: # noqa: BLE001 node = None d["sockets_error"] = "cannot create %s in a %s: %s" % (rna.identifier, tree.bl_idname, str(ex)[:160]) + d["creatable_in_%s" % tree.bl_idname] = creatable(tree.bl_idname, rna.identifier) menus = {} if node is not None: if live is None: @@ -230,13 +311,19 @@ def node_info(rna, live=None): return d +TREE = chosen_tree(P["tree"]) if P.get("tree") else None + if P.get("type"): t = getattr(bpy.types, P["type"], None) if t is None or not hasattr(t, "bl_rna"): - close = sorted(n for n in dir(bpy.types) if P["type"].lower() in n.lower())[:30] - out["type"] = {"error": "no type %r in this Blender" % P["type"], "similar": close} + names = dir(bpy.types) + close = difflib.get_close_matches(P["type"], names, n=10, cutoff=0.5) + close += sorted(n for n in names if P["type"].lower() in n.lower() and n not in close) + out["type"] = {"error": "no type %r in this Blender" % P["type"], "similar": close[:40]} + if TREE: + out["type"]["creatable_in_%s" % TREE] = creatable(TREE, P["type"]) elif is_node_type(t.bl_rna) and t.bl_rna.identifier not in ("Node", "ShaderNode", "GeometryNode", "CompositorNode", "FunctionNode", "TextureNode", "NodeInternal"): - out["type"] = node_info(t.bl_rna) + out["type"] = node_info(t.bl_rna, tree_type=TREE) else: out["type"] = struct_info(t.bl_rna) @@ -248,19 +335,41 @@ def node_info(rna, live=None): except Exception: # noqa: BLE001 rna = None if rna is None: - mod_ops = getattr(bpy.ops, module, None) - out["operator"] = {"error": "no operator %r in this Blender" % P["operator"], "in_module": sorted(dir(mod_ops))[:80] if mod_ops else []} + modules = sorted(dir(bpy.ops)) + mod_ops = getattr(bpy.ops, module, None) if module in modules else None + in_module = sorted(dir(mod_ops)) if mod_ops else [] + out["operator"] = {"error": "no operator %r in this Blender" % P["operator"], + "closest": ["%s.%s" % (module, n) for n in difflib.get_close_matches(name, in_module, n=8, cutoff=0.5)], + "in_module": in_module[:NAMES_MAX]} + if mod_ops is None: + out["operator"]["closest_modules"] = difflib.get_close_matches(module, modules, n=6, cutoff=0.5) else: try: poll = op.poll() except Exception as ex: # noqa: BLE001 poll = "unknown: %s" % ex - out["operator"] = { + report = {"in_this_context": poll} + if poll is False: + # Blender checks poll before running: the call fails at once, with the reason it gives, if any. + try: + op() + except Exception as ex: # noqa: BLE001 + report["blender_says"] = str(ex)[:300] + ctx = bpy.context + report["context"] = {"window": ctx.window is not None, "area": ctx.area.type if ctx.area else None, + "region": ctx.region.type if ctx.region else None, "mode": ctx.mode, + "active_object": ctx.active_object.name if ctx.active_object else None, + "id": getattr(ctx, "id", None) is not None} + report["give_context"] = "bpy.context.temp_override(window=..., area=..., region=..., id=..., active_object=...)" + props = [p for p in rna.properties if p.identifier != "rna_type"] + info = { "id": P["operator"], "name": rna.name, "desc": (rna.description or "")[:300], "doc": "%sbpy.ops.%s.html#bpy.ops.%s.%s" % (API, module, module, name), - "poll_without_ui_context": poll, - "properties": [prop_info(p) for p in rna.properties if p.identifier != "rna_type"][:LIMIT], + "poll": report, } + detailed(props, lambda p: dict(prop_info(p), **({"element": element_info(p)} if p.type in ("COLLECTION", "POINTER") else {})), + "properties", info) + out["operator"] = info if P.get("data"): spec = P["data"] @@ -288,4 +397,72 @@ def node_info(rna, live=None): info["geometry_nodes_inputs"] = modifier_inputs(target) out["data"] = info +def search(text): + """Where words appear in this Blender's API: types, their own properties and functions, operators. Every word + is found in the identifier, name or description; identifier matches rank first. A type lists the properties + that lead to it (reached_by).""" + words = [w.lower() for w in str(text).split() if w] + if not words: + raise ValueError("search: give one or more words") + + def score(ident, name, desc): + ident, name = ident.lower(), (name or "").lower() + hay = " ".join((ident, name, (desc or "").lower())) + if not all(w in hay for w in words): + return 0 + return sum(3 if w in ident else 2 if w in name else 1 for w in words) + + hits, reached = [], {} + for type_name in dir(bpy.types): + rna = getattr(getattr(bpy.types, type_name, None), "bl_rna", None) + if rna is None or rna.identifier != type_name: + continue + inherited = {p.identifier for p in rna.base.properties} if rna.base else set() + inherited_f = {f.identifier for f in rna.base.functions} if rna.base else set() + s = score(type_name, rna.name, rna.description) + if s: + hits.append((s + 1, {"kind": "type", "path": type_name, "desc": (rna.description or "")[:120]})) + for p in rna.properties: + if p.identifier == "rna_type" or p.identifier in inherited: + continue + if p.type in ("POINTER", "COLLECTION"): + reached.setdefault(p.fixed_type.identifier, []).append("%s.%s" % (type_name, p.identifier)) + s = score(p.identifier, p.name, p.description) + if s: + kind = p.type + (":" + p.fixed_type.identifier if p.type in ("POINTER", "COLLECTION") else "") + hits.append((s, {"kind": "property", "path": "%s.%s" % (type_name, p.identifier), "type": kind, + "desc": (p.description or "")[:120]})) + for f in rna.functions: + if f.identifier in inherited_f: + continue + s = score(f.identifier, "", f.description) + if s: + hits.append((s, {"kind": "function", "path": "%s.%s()" % (type_name, f.identifier), + "desc": (f.description or "")[:120]})) + for module in dir(bpy.ops): + for name in dir(getattr(bpy.ops, module)): + try: + rna = getattr(getattr(bpy.ops, module), name).get_rna_type() + except Exception: # noqa: BLE001 + continue + s = score("%s.%s" % (module, name), rna.name, rna.description) + if s: + hits.append((s, {"kind": "operator", "path": "bpy.ops.%s.%s" % (module, name), + "desc": (rna.description or "")[:120]})) + hits.sort(key=lambda h: (-h[0], len(h[1]["path"]), h[1]["path"])) + results = [] + for _, hit in hits[:LIMIT]: + if hit["kind"] == "type" and reached.get(hit["path"]): + hit["reached_by"] = reached[hit["path"]][:8] + results.append(hit) + found = {"words": words, "found": len(hits), "results": results} + if len(hits) > LIMIT: + found["more"] = {"count": len(hits) - LIMIT, "paths": [h[1]["path"] for h in hits[LIMIT:LIMIT + NAMES_MAX]], + "details": "add words, or inspect a path's type or operator"} + return found + + +if P.get("search"): + out["search"] = search(P["search"]) + result = out diff --git a/integrations/blender/plugin/programs/verify.py b/integrations/blender/plugin/programs/verify.py index d8594b7..3659990 100644 --- a/integrations/blender/plugin/programs/verify.py +++ b/integrations/blender/plugin/programs/verify.py @@ -5,7 +5,11 @@ # temporary camera at view.location looking at view.target, lens in millimetres), the markers' cameras and the # sequencer set aside for it. Several frames come back as one contact sheet, left to right and top to bottom. # Render settings, cameras, markers and the current frame are restored afterwards; the temporary camera goes. -# PARAMS is prepended by the plugin: {"scene"?, "frame"?, "frames"?, "view"?, "size"?} +# criteria: the agent's own checks (a read-only expression or a bpy.data path, a comparison, a value, frames), +# each measured on the evaluated scene and passed or failed. visible: whether an object shows in the render at +# a frame, with every reason found when it does not. With either, the render runs only when asked (render, view). +# PARAMS is prepended by the plugin: {"scene"?, "frame"?, "frames"?, "view"?, "size"?, "criteria"?, "visible"?, +# "render"?} import base64 import math import os @@ -156,122 +160,441 @@ def shown_by(target): scene.name, ", ".join(repr(m) for m in montages), montages[0])) per_frame = [output_facts(f) for f in frames] -old_frame = scene.frame_current -saved = {"pct": r.resolution_percentage, "path": r.filepath, "fmt": im.file_format, "mode": im.color_mode, - "media": getattr(im, "media_type", None), "camera": scene.camera, "sequencer": r.use_sequencer} -markers = [(m, m.camera) for m in scene.timeline_markers] -cycles = getattr(scene, "cycles", None) -eevee = getattr(scene, "eevee", None) -saved_samples = (getattr(cycles, "samples", None), getattr(eevee, "taa_render_samples", None)) -path = os.path.join(tempfile.gettempdir(), "opencode_verify_%d.png" % os.getpid()) -sheet_path = os.path.join(tempfile.gettempdir(), "opencode_verify_sheet_%d.png" % os.getpid()) -camera = None -tiles = [] -image_b64 = None -try: - if view is not None: - data = bpy.data.cameras.new("OpenCode verify view") - data.lens = lens - data.clip_end = max(data.clip_end, (look - eye).length * 4) - camera = bpy.data.objects.new("OpenCode verify view", data) - scene.collection.objects.link(camera) - camera.location = eye - camera.rotation_euler = (look - eye).to_track_quat("-Z", "Y").to_euler() - for marker, _bound in markers: - marker.camera = None - scene.camera = camera - r.use_sequencer = False - r.resolution_percentage = max(1, min(100, int(100 * tile / max(r.resolution_x, r.resolution_y)))) - if saved["media"] is not None: - im.media_type = "IMAGE" - im.file_format = "PNG" - im.color_mode = "RGBA" - r.filepath = path - if cycles is not None and saved_samples[0]: - cycles.samples = min(saved_samples[0], 16) - if eevee is not None and saved_samples[1]: - eevee.taa_render_samples = min(saved_samples[1], 8) - for facts in per_frame: - scene.frame_set(facts["frame"]) - dg = bpy.context.evaluated_depsgraph_get() - counts = {} - for inst in dg.object_instances: - if inst.is_instance and inst.parent is not None: - key = inst.parent.original.name - counts[key] = counts.get(key, 0) + 1 - facts["instances_by_object"] = dict(sorted(counts.items(), key=lambda kv: -kv[1])[:20]) - facts["visible_objects"] = sum(1 for o in scene.objects if o.visible_get() and o != camera) - bpy.ops.render.render(write_still=True, scene=scene.name) - img = bpy.data.images.load(path) + +# --- criteria: the agent's own acceptance checks, each measured on the evaluated scene at its frames ----------- +CRITERIA = P.get("criteria") or [] +VISIBLE = P.get("visible") +RENDER = bool(P["render"]) if "render" in P else (view is not None or not (CRITERIA or VISIBLE)) +OPS = ("<", "<=", ">", ">=", "==", "!=", "approx", "between", "in", "contains") +SAFE_BUILTINS = {n: __builtins__[n] if isinstance(__builtins__, dict) else getattr(__builtins__, n) for n in ( + "abs", "min", "max", "len", "round", "sum", "any", "all", "sorted", "int", "float", "bool", "str", "list", + "tuple", "set", "range", "zip", "enumerate", "isinstance")} +if not isinstance(CRITERIA, list) or len(CRITERIA) > 50: + raise ValueError("criteria: a list of at most 50 {expr or path, op, value, frame or frames, label?}") + + +def read_only_expression(text): + """An expression that reads: no assignment, no operator call, no private attribute.""" + import ast + tree = ast.parse(text, mode="eval") + for node in ast.walk(tree): + if isinstance(node, (ast.NamedExpr, ast.Lambda)): + raise ValueError("criteria: %r is not a plain read" % text) + if isinstance(node, ast.Attribute) and (node.attr.startswith("_") or node.attr == "ops"): + raise ValueError("criteria: %r reaches %s, which is not a read" % (text, node.attr)) + if isinstance(node, ast.Name) and node.id.startswith("_"): + raise ValueError("criteria: %r names %s" % (text, node.id)) + return compile(tree, "", "eval") + + +class Box(object): + """World-space bounds: min, max, size and center (Vectors).""" + + def __init__(self, points): + self.min = Vector([min(p[i] for p in points) for i in range(3)]) + self.max = Vector([max(p[i] for p in points) for i in range(3)]) + self.size = self.max - self.min + self.center = (self.min + self.max) / 2 + + def __repr__(self): + return "Box(min=%s, max=%s)" % (rounded(self.min), rounded(self.max)) + + +def evaluated_points(obj, dg): + """World-space points of obj's evaluated geometry: its mesh when it has one, its bounds otherwise, and the + bounds of the instances it makes (Geometry Nodes, particles, collections).""" + ev = obj.evaluated_get(dg) + points = [] + if obj.type in ("MESH", "CURVE", "SURFACE", "FONT", "META"): + mesh = ev.to_mesh() try: - w, h = img.size - px = img.pixels[:] + mw = ev.matrix_world + points = [mw @ v.co for v in mesh.vertices] finally: - bpy.data.images.remove(img) - n = w * h - lum = [0.2126 * px[i] + 0.7152 * px[i + 1] + 0.0722 * px[i + 2] for i in range(0, len(px), 4)] - alpha = px[3::4] - mean = sum(lum) / n - std = (sum((x - mean) ** 2 for x in lum) / n) ** 0.5 - facts["image"] = { - "size": [w, h], "mean_luminance": round(mean, 4), "max_luminance": round(max(lum), 4), "luminance_std": round(std, 4), - "mean_rgb": [round(sum(px[c::4]) / n, 4) for c in range(3)], - "mean_alpha": round(sum(alpha) / n, 4), "transparent_fraction": round(sum(1 for a in alpha if a < 0.01) / n, 4), - } - facts["image"]["black"] = max(lum) < 0.02 - facts["image"]["transparent"] = facts["image"]["mean_alpha"] < 0.01 - facts["image"]["uniform"] = std < 0.002 - if len(frames) == 1: - with open(path, "rb") as fh: - image_b64 = base64.b64encode(fh.read()).decode("ascii") - else: - tiles.append((w, h, px)) - if tiles: - # One sheet: tiles left to right, top to bottom (Blender's pixel rows run bottom-up), white gaps. - w, h = max(t[0] for t in tiles), max(t[1] for t in tiles) - sheet_w, sheet_h = cols * w, rows * h - sheet = [1.0] * (sheet_w * sheet_h * 4) - for index, (tw, th, px) in enumerate(tiles): - col, row = index % cols, rows - 1 - index // cols - for y in range(th): - start = ((row * h + y) * sheet_w + col * w) * 4 - sheet[start:start + tw * 4] = px[y * tw * 4:(y + 1) * tw * 4] - out = bpy.data.images.new("OpenCode verify sheet", sheet_w, sheet_h, alpha=True) + ev.to_mesh_clear() + elif obj.type not in ("EMPTY", "CAMERA", "LIGHT", "SPEAKER", "LIGHT_PROBE"): + points = [ev.matrix_world @ Vector(c) for c in ev.bound_box] + for inst in dg.object_instances: + if inst.is_instance and inst.parent is not None and inst.parent.original == obj: + points += [inst.matrix_world @ Vector(c) for c in inst.object.bound_box] + return points + + +def namespace(dg, f): + def ev(name): + return bpy.data.objects[name].evaluated_get(dg) + + def bounds(name): + points = evaluated_points(bpy.data.objects[name], dg) + if not points: + raise ValueError("%r has no geometry at frame %d" % (name, f)) + return Box(points) + + def world(name): + return ev(name).matrix_world.translation.copy() + + return {"__builtins__": SAFE_BUILTINS, "bpy": bpy, "math": math, "Vector": Vector, "scene": scene, + "frame": f, "depsgraph": dg, "ev": ev, "bounds": bounds, "world": world} + + +def rounded(value): + if isinstance(value, float): + return round(value, 6) if math.isfinite(value) else str(value) + if isinstance(value, (bool, int, str)) or value is None: + return value + if hasattr(value, "bl_rna"): + return getattr(value, "name", None) or value.bl_rna.identifier + if isinstance(value, Box): + return {"min": rounded(value.min), "max": rounded(value.max)} + try: + return [rounded(v) for v in value][:64] + except TypeError: + return repr(value)[:200] + + +def compare(measured, op, value, tol): + def numbers(x): + if isinstance(x, str): + return None try: - out.pixels.foreach_set(sheet) - out.filepath_raw = sheet_path - out.file_format = "PNG" - out.save() - finally: - bpy.data.images.remove(out) - with open(sheet_path, "rb") as fh: - image_b64 = base64.b64encode(fh.read()).decode("ascii") - summary["sheet"] = {"size": [sheet_w, sheet_h], "columns": cols, "rows": rows, - "order": "left to right, top to bottom: frames %s" % frames} -finally: - r.resolution_percentage = saved["pct"] - r.filepath = saved["path"] - if saved["media"] is not None: - im.media_type = saved["media"] - im.file_format = saved["fmt"] - im.color_mode = saved["mode"] - if cycles is not None and saved_samples[0]: - cycles.samples = saved_samples[0] - if eevee is not None and saved_samples[1]: - eevee.taa_render_samples = saved_samples[1] - if camera is not None: - for marker, bound in markers: - marker.camera = bound - scene.camera = saved["camera"] - r.use_sequencer = saved["sequencer"] - data = camera.data - bpy.data.objects.remove(camera, do_unlink=True) - bpy.data.cameras.remove(data) - scene.frame_set(old_frame) - for leftover in (path, sheet_path): - if os.path.exists(leftover): - os.remove(leftover) + return [float(v) for v in x] + except (TypeError, ValueError): + return None + + if op == "in": + return measured in value + if op == "contains": + return value in measured + if op == "between": + lo, hi = value + seq = numbers(measured) + return all(lo <= v <= hi for v in seq) if seq is not None else lo <= measured <= hi + seq = numbers(measured) + if seq is not None and op != "==" and op != "!=" or (seq is not None and isinstance(value, (list, tuple))): + targets = numbers(value) if isinstance(value, (list, tuple)) else [value] * len(seq) + if targets is None or len(targets) != len(seq): + raise ValueError("value: %d numbers to compare with %s" % (len(seq), rounded(measured))) + return all(compare(m, op, t, tol) for m, t in zip(seq, targets)) + if op == "approx": + return abs(measured - value) <= tol + return {"<": measured < value, "<=": measured <= value, ">": measured > value, ">=": measured >= value, + "==": measured == value, "!=": measured != value}[op] + + +def criterion_frames(c): + if "frames" in c: + return [int(x) for x in c["frames"]] + return [int(c["frame"])] if "frame" in c else frames + + +def render_view_layers(): + return [vl for vl in scene.view_layers if vl.use] or [bpy.context.view_layer] + + +def depsgraph_at(): + if scene == bpy.context.scene: + return bpy.context.evaluated_depsgraph_get() + dg = render_view_layers()[0].depsgraph + dg.update() + return dg + + +def layer_paths(layer, target, path=()): + """The LayerCollection chains from layer down to every collection holding target.""" + here = path + (layer,) + if target.name in layer.collection.objects: + yield here + for child in layer.children: + yield from layer_paths(child, target, here) + + +def material_reasons(obj): + """Materials that render nothing: no surface or volume to the output, Alpha 0, zero density.""" + out = [] + for slot in obj.material_slots: + m = slot.material + if m is None or not m.node_tree: + continue + nodes = m.node_tree.nodes + output = next((n for n in nodes if n.bl_idname == "ShaderNodeOutputMaterial" and n.is_active_output), None) + if output is not None and not any(s.is_linked for s in output.inputs): + out.append("material %r: nothing connected to its output" % m.name) + for n in nodes: + if not any(o.is_linked for o in n.outputs): + continue # a node feeding nothing renders nothing either way + alpha = n.inputs.get("Alpha") + if alpha is not None and n.bl_idname.startswith("ShaderNodeBsdf") and not alpha.is_linked and alpha.default_value <= 0.001: + out.append("material %r: %s Alpha is 0 (transparent)" % (m.name, n.name)) + density = n.inputs.get("Density") + if density is not None and n.bl_idname.startswith("ShaderNodeVolume") and not density.is_linked and density.default_value <= 0: + out.append("material %r: %s Density is 0" % (m.name, n.name)) + return out + + +def visibility(obj, f, dg): + """Whether obj shows in the render at frame f, and every reason found when it does not.""" + from bpy_extras.object_utils import world_to_camera_view + reasons, notes = [], [] + if obj.name not in scene.objects: + reasons.append("not in scene %r" % scene.name) + layers = render_view_layers() + rendered_in = [] + for vl in scene.view_layers: + paths = list(layer_paths(vl.layer_collection, obj)) + if not paths: + continue + ok = False + for chain in paths: + names = "/".join(lc.name for lc in chain[1:]) or "Scene Collection" + if any(lc.exclude for lc in chain): + reasons.append("collection %s excluded from view layer %r" % (names, vl.name)) + elif any(lc.collection.hide_render for lc in chain): + reasons.append("collection %s hidden in render" % names) + elif any(lc.holdout for lc in chain): + reasons.append("collection %s is a holdout in view layer %r (renders as a hole)" % (names, vl.name)) + else: + ok = True + if any(lc.indirect_only for lc in chain): + notes.append("collection %s is indirect only in %r (seen in reflections only, Cycles)" % (names, vl.name)) + if ok and vl in layers: + rendered_in.append(vl.name) + elif ok: + reasons.append("view layer %r holding it is not rendered (Use for rendering off)" % vl.name) + if obj.hide_render: + reasons.append("hidden in render (hide_render)") + if not getattr(obj, "visible_camera", True): + reasons.append("invisible to the camera (Ray Visibility: Camera off)") + if getattr(obj, "is_holdout", False): + reasons.append("holdout object (renders as a hole)") + if abs(obj.evaluated_get(dg).matrix_world.determinant()) < 1e-12: + reasons.append("scaled to zero") + reasons += material_reasons(obj) + points = evaluated_points(obj, dg) + if not points: + reasons.append("no geometry at this frame (evaluated geometry empty)") + cam_name, via = camera_at(scene, f) + cam = bpy.data.objects.get(cam_name) if cam_name else None + report = {"frame": f, "camera": cam_name, "camera_via": via} + if cam is None: + reasons.append("no camera") + elif points: + clip = (cam.data.clip_start, cam.data.clip_end) + proj = [world_to_camera_view(scene, cam.evaluated_get(dg), p) for p in points] + xs, ys, zs = [p.x for p in proj], [p.y for p in proj], [p.z for p in proj] + report["screen_box"] = [round(min(xs), 4), round(min(ys), 4), round(max(xs), 4), round(max(ys), 4)] + report["depth"] = [round(min(zs), 4), round(max(zs), 4)] + inside = sum(1 for x, y, z in zip(xs, ys, zs) if 0 <= x <= 1 and 0 <= y <= 1 and clip[0] <= z <= clip[1]) + if max(zs) < clip[0]: + reasons.append("behind camera %r (or nearer than its clip start %g)" % (cam_name, clip[0])) + elif min(zs) > clip[1]: + reasons.append("beyond camera %r's clip end %g" % (cam_name, clip[1])) + elif not inside and (max(xs) < 0 or min(xs) > 1 or max(ys) < 0 or min(ys) > 1): + reasons.append("out of frame of camera %r (screen box %s, the frame is 0..1)" % (cam_name, report["screen_box"])) + elif inside < len(points): + notes.append("partly in frame: %d of %d points" % (inside, len(points))) + if not reasons: + origin = cam.evaluated_get(dg).matrix_world.translation + center = sum(points, Vector()) / len(points) + blockers, samples = set(), [center] + points[:: max(1, len(points) // 8)][:8] + for p in samples: + direction = p - origin + hit, _, _, _, hit_obj, _ = scene.ray_cast(dg, origin, direction.normalized(), distance=direction.length - 1e-3) + if hit and hit_obj is not None and hit_obj.original != obj: + blockers.add(hit_obj.original.name) + continue + blockers.add(None) + if None not in blockers and blockers: + reasons.append("hidden behind %s from camera %r" % (sorted(blockers), cam_name)) + elif len(blockers) > 1: + notes.append("partly hidden behind %s" % sorted(b for b in blockers if b)) + report["visible"] = not reasons + if reasons: + report["reasons"] = list(dict.fromkeys(reasons)) + if notes: + report["notes"] = notes + if rendered_in: + report["view_layers"] = rendered_in + return report + + +def run_checks(): + compiled = [] + for i, c in enumerate(CRITERIA): + if not isinstance(c, dict) or not (("expr" in c) ^ ("path" in c)) or c.get("op") not in OPS or "value" not in c: + raise ValueError("criteria[%d]: {expr or path, op: one of %s, value, frame or frames, tol?, label?}" % (i, OPS)) + text = c["expr"] if "expr" in c else "bpy.data." + c["path"] + compiled.append((c, text, read_only_expression(text), criterion_frames(c))) + targets = [] + if VISIBLE: + spec = {"object": VISIBLE} if isinstance(VISIBLE, str) else VISIBLE + obj = bpy.data.objects.get(spec.get("object", "")) if isinstance(spec, dict) else None + if obj is None: + raise ValueError("visible: no object %r" % (spec.get("object") if isinstance(spec, dict) else VISIBLE)) + targets = [int(x) for x in spec.get("frames") or [spec.get("frame", frames[0])]] + wanted = sorted({f for *_, fs in compiled for f in fs} | set(targets)) + measured = {} + seen = [] + old = scene.frame_current + try: + for f in wanted: + scene.frame_set(f) + dg = depsgraph_at() + for index, (c, text, code, fs) in enumerate(compiled): + if f not in fs: + continue + try: + value = eval(code, namespace(dg, f)) # noqa: S307 - a checked read-only expression + entry = {"frame": f, "measured": rounded(value), + "passed": bool(compare(value, c["op"], c["value"], float(c.get("tol", 1e-4))))} + except Exception as ex: # noqa: BLE001 + entry = {"frame": f, "passed": False, "error": ("%s: %s" % (type(ex).__name__, ex))[:300]} + measured.setdefault(index, []).append(entry) + if f in targets: + seen.append(visibility(obj, f, dg)) + finally: + scene.frame_set(old) + out = {} + if compiled: + rows = [] + for index, (c, text, _code, _fs) in enumerate(compiled): + entries = measured.get(index, []) + row = {"label": c.get("label") or text, "check": "%s %s %s" % (text, c["op"], c["value"]), + "passed": bool(entries) and all(e["passed"] for e in entries)} + row.update(entries[0] if len(entries) == 1 else {"frames": entries}) + rows.append(row) + out["criteria"] = rows + out["all_passed"] = all(row["passed"] for row in rows) + out["failed"] = [row["label"] for row in rows if not row["passed"]] + if targets: + out["visible"] = {"object": obj.name, "frames": seen} if len(seen) > 1 else dict(seen[0], object=obj.name) + return out + + +checks = run_checks() if (CRITERIA or VISIBLE) else {} + + +def render_frames(): + """The renders (unchanged since 0.4.2): settings, cameras and the current frame restored; the PNG or sheet.""" + old_frame = scene.frame_current + saved = {"pct": r.resolution_percentage, "path": r.filepath, "fmt": im.file_format, "mode": im.color_mode, + "media": getattr(im, "media_type", None), "camera": scene.camera, "sequencer": r.use_sequencer} + markers = [(m, m.camera) for m in scene.timeline_markers] + cycles = getattr(scene, "cycles", None) + eevee = getattr(scene, "eevee", None) + saved_samples = (getattr(cycles, "samples", None), getattr(eevee, "taa_render_samples", None)) + path = os.path.join(tempfile.gettempdir(), "opencode_verify_%d.png" % os.getpid()) + sheet_path = os.path.join(tempfile.gettempdir(), "opencode_verify_sheet_%d.png" % os.getpid()) + camera = None + tiles = [] + image_b64 = None + try: + if view is not None: + data = bpy.data.cameras.new("OpenCode verify view") + data.lens = lens + data.clip_end = max(data.clip_end, (look - eye).length * 4) + camera = bpy.data.objects.new("OpenCode verify view", data) + scene.collection.objects.link(camera) + camera.location = eye + camera.rotation_euler = (look - eye).to_track_quat("-Z", "Y").to_euler() + for marker, _bound in markers: + marker.camera = None + scene.camera = camera + r.use_sequencer = False + r.resolution_percentage = max(1, min(100, int(100 * tile / max(r.resolution_x, r.resolution_y)))) + if saved["media"] is not None: + im.media_type = "IMAGE" + im.file_format = "PNG" + im.color_mode = "RGBA" + r.filepath = path + if cycles is not None and saved_samples[0]: + cycles.samples = min(saved_samples[0], 16) + if eevee is not None and saved_samples[1]: + eevee.taa_render_samples = min(saved_samples[1], 8) + for facts in per_frame: + scene.frame_set(facts["frame"]) + dg = bpy.context.evaluated_depsgraph_get() + counts = {} + for inst in dg.object_instances: + if inst.is_instance and inst.parent is not None: + key = inst.parent.original.name + counts[key] = counts.get(key, 0) + 1 + facts["instances_by_object"] = dict(sorted(counts.items(), key=lambda kv: -kv[1])[:20]) + facts["visible_objects"] = sum(1 for o in scene.objects if o.visible_get() and o != camera) + bpy.ops.render.render(write_still=True, scene=scene.name) + img = bpy.data.images.load(path) + try: + w, h = img.size + px = img.pixels[:] + finally: + bpy.data.images.remove(img) + n = w * h + lum = [0.2126 * px[i] + 0.7152 * px[i + 1] + 0.0722 * px[i + 2] for i in range(0, len(px), 4)] + alpha = px[3::4] + mean = sum(lum) / n + std = (sum((x - mean) ** 2 for x in lum) / n) ** 0.5 + facts["image"] = { + "size": [w, h], "mean_luminance": round(mean, 4), "max_luminance": round(max(lum), 4), "luminance_std": round(std, 4), + "mean_rgb": [round(sum(px[c::4]) / n, 4) for c in range(3)], + "mean_alpha": round(sum(alpha) / n, 4), "transparent_fraction": round(sum(1 for a in alpha if a < 0.01) / n, 4), + } + facts["image"]["black"] = max(lum) < 0.02 + facts["image"]["transparent"] = facts["image"]["mean_alpha"] < 0.01 + facts["image"]["uniform"] = std < 0.002 + if len(frames) == 1: + with open(path, "rb") as fh: + image_b64 = base64.b64encode(fh.read()).decode("ascii") + else: + tiles.append((w, h, px)) + if tiles: + # One sheet: tiles left to right, top to bottom (Blender's pixel rows run bottom-up), white gaps. + w, h = max(t[0] for t in tiles), max(t[1] for t in tiles) + sheet_w, sheet_h = cols * w, rows * h + sheet = [1.0] * (sheet_w * sheet_h * 4) + for index, (tw, th, px) in enumerate(tiles): + col, row = index % cols, rows - 1 - index // cols + for y in range(th): + start = ((row * h + y) * sheet_w + col * w) * 4 + sheet[start:start + tw * 4] = px[y * tw * 4:(y + 1) * tw * 4] + out = bpy.data.images.new("OpenCode verify sheet", sheet_w, sheet_h, alpha=True) + try: + out.pixels.foreach_set(sheet) + out.filepath_raw = sheet_path + out.file_format = "PNG" + out.save() + finally: + bpy.data.images.remove(out) + with open(sheet_path, "rb") as fh: + image_b64 = base64.b64encode(fh.read()).decode("ascii") + summary["sheet"] = {"size": [sheet_w, sheet_h], "columns": cols, "rows": rows, + "order": "left to right, top to bottom: frames %s" % frames} + finally: + r.resolution_percentage = saved["pct"] + r.filepath = saved["path"] + if saved["media"] is not None: + im.media_type = saved["media"] + im.file_format = saved["fmt"] + im.color_mode = saved["mode"] + if cycles is not None and saved_samples[0]: + cycles.samples = saved_samples[0] + if eevee is not None and saved_samples[1]: + eevee.taa_render_samples = saved_samples[1] + if camera is not None: + for marker, bound in markers: + marker.camera = bound + scene.camera = saved["camera"] + r.use_sequencer = saved["sequencer"] + data = camera.data + bpy.data.objects.remove(camera, do_unlink=True) + bpy.data.cameras.remove(data) + scene.frame_set(old_frame) + for leftover in (path, sheet_path): + if os.path.exists(leftover): + os.remove(leftover) + return image_b64 + + +image_b64 = render_frames() if RENDER else None if len(per_frame) > 1: summary["frames"] = per_frame if len(per_frame) == 1: @@ -279,4 +602,4 @@ def shown_by(target): if summary.get("warnings") or per_frame[0].get("warnings"): merged["warnings"] = summary.get("warnings", []) + per_frame[0].get("warnings", []) result = {"blender": bpy.app.version_string, "facts": merged if len(per_frame) == 1 else summary, - "image_base64": image_b64} + "image_base64": image_b64, **checks} diff --git a/integrations/blender/plugin/src/closed.ts b/integrations/blender/plugin/src/closed.ts new file mode 100644 index 0000000..94c8402 --- /dev/null +++ b/integrations/blender/plugin/src/closed.ts @@ -0,0 +1,49 @@ +// A Blender that closed under a conversation: its process gone, and the crash report Blender wrote, if any. The +// add-on's hello names its process and the folder Blender writes ".crash.txt" to; a later call that +// finds the Blender unreachable, or its offer gone, says so instead of a bare "unreachable". + +import { readdirSync, statSync } from "node:fs" +import { join } from "node:path" + +import { isAlive } from "./tasks.ts" + +export type HostProcess = { pid: number; tempDir: string; label?: string; since: number; offerID?: string } + +export function readProcess(hello: unknown, label?: string, now = Date.now()): HostProcess | null { + const found = (hello as { process?: { pid?: unknown; temp_dir?: unknown } } | null)?.process + if (!found || !Number.isInteger(found.pid) || (found.pid as number) <= 0) return null + if (typeof found.temp_dir !== "string" || !found.temp_dir) return null + return { pid: found.pid as number, tempDir: found.temp_dir, label, since: now } +} + +// The newest crash report written in the process's crash folder since this conversation first reached it. +export function crashReport(host: HostProcess): string | null { + let names: string[] + try { + names = readdirSync(host.tempDir) + } catch { + return null + } + let newest: { path: string; time: number } | null = null + for (const name of names) { + if (!name.endsWith(".crash.txt")) continue + const path = join(host.tempDir, name) + try { + const time = statSync(path).mtimeMs + if (time >= host.since - 1_000 && (!newest || time > newest.time)) newest = { path, time } + } catch { + // removed meanwhile + } + } + return newest?.path ?? null +} + +// null while the process lives: then the usual unreachable message stands. +export function closedMessage(host: HostProcess, alive: (pid: number) => boolean = isAlive): string | null { + if (alive(host.pid)) return null + const name = host.label ? ` (${host.label})` : "" + const report = crashReport(host) + return report + ? `Blender closed${name}: its process ${host.pid} has ended. Crash report: ${report}. Open Blender again and attach it (blender_hosts).` + : `Blender closed${name}: its process ${host.pid} has ended, with no crash report in ${host.tempDir}. Open Blender again and attach it (blender_hosts).` +} diff --git a/integrations/blender/plugin/src/integration.ts b/integrations/blender/plugin/src/integration.ts index 7de25d5..f5c912e 100644 --- a/integrations/blender/plugin/src/integration.ts +++ b/integrations/blender/plugin/src/integration.ts @@ -9,6 +9,7 @@ import type { Plugin } from "@opencode/plugin" import type { ToolContext } from "@opencode/plugin/promise/tool" import { type AttachmentStorage, createAttachments, trackAdvertise } from "./attachments.ts" +import { closedMessage, type HostProcess, readProcess } from "./closed.ts" import { extensionsDir, inspectHost, installHost } from "./host-install.ts" import { type BindingAuthority, @@ -19,6 +20,7 @@ import { HostError, type HostExpectation, type IntegrationMarker, + isWslDaemon, loadMethodRegistry, type OfferRegistry, registerPluginTools, @@ -301,6 +303,30 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) return offer ? { offerID: offer.offerID, label: offer.label } : null } + // The process of the Blender each conversation last reached (its hello): a later call that cannot reach it says + // that Blender closed, and where its crash report is. Not from WSL, where Blender's process is on Windows. + const reached = new Map() + const helloed = new Map() // sessionID -> the offer whose hello was read + const wsl = deps.wsl ?? (() => isWslDaemon()) + const closedFor = (sessionID: string) => { + const host = reached.get(sessionID) + return host && !wsl() ? closedMessage(host) : null + } + const remember = async (context: ToolContext, held: Ticket) => { + if (helloed.get(context.sessionID) === held.bound.offerID) return + helloed.set(context.sessionID, held.bound.offerID) + try { + const found = readProcess(await hello(held.bound, context.signal), held.label) + if (found) reached.set(context.sessionID, { ...found, offerID: held.bound.offerID }) + else reached.delete(context.sessionID) + } catch { + // an add-on without process in its hello, or a failed hello: the call itself reports + } + } + + const hello = async (bound: HostBinding, signal: AbortSignal) => + (await requestHost(bound.endpoint, "hello", {}, { signal, timeoutMs: HELLO_TIMEOUT_MS })) as Hello + // The conversation's attached Blender. Without one, the only offered Blender, compatible and attached to no // conversation, attaches itself (spec FAM-5): checked against the ownership snapshot with no wait in between. const ticket = async (context: ToolContext): Promise => { @@ -329,6 +355,8 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) } } if (!bound) { + const closed = closedFor(context.sessionID) + if (closed) throw new Error(closed) if (!offers.length) throw new Error("No Blender is offered: open Blender 5.3 or later with the OpenCode Link add-on enabled.") const list = offers @@ -365,6 +393,7 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) `The attached Blender's OpenCode Link has no ${method} method: install OpenCode Link ${pkg.version} (blender_install_host) and restart Blender.`, ) } + await remember(context, held) try { return await requestHost( bound.endpoint, @@ -373,13 +402,11 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) { signal: context.signal, timeoutMs }, ) } catch (error) { - throw hostError(error) + const closed = error instanceof HostError && error.code === "unreachable" ? closedFor(context.sessionID) : null + throw closed ? new Error(closed) : hostError(error) } } - const hello = async (bound: HostBinding, signal: AbortSignal) => - (await requestHost(bound.endpoint, "hello", {}, { signal, timeoutMs: HELLO_TIMEOUT_MS })) as Hello - // A fixed program through the host's code execution, read only (programs.ts). const program = async (context: ToolContext, name: ProgramName, params: unknown, timeoutMs?: number) => { const out = (await callHost( @@ -549,22 +576,27 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) }, async blender_inspect(args, context) { - if (args.type === undefined && args.operator === undefined && args.data === undefined) - throw new Error("Give type, operator and/or data.") + if ( + args.type === undefined && + args.operator === undefined && + args.data === undefined && + args.search === undefined + ) + throw new Error("Give type, operator, data and/or search.") return json(await program(context, "inspect", args)) }, async blender_verify(args, context) { - const result = (await program(context, "verify", args, VERIFY_TIMEOUT_MS)) as { - facts?: unknown + const { image_base64, ...rest } = (await program(context, "verify", args, VERIFY_TIMEOUT_MS)) as { image_base64?: string - blender?: string - } - const text = json({ blender: result.blender, facts: result.facts }) - if (!result.image_base64) return text + } & Record + // Criteria first: what passed and failed, measured, then the facts. + const { blender, facts, ...checks } = rest + const text = json({ blender, ...checks, facts }) + if (!image_base64) return text return [ { type: "text", text }, - { type: "file", uri: `data:image/png;base64,${result.image_base64}`, mime: "image/png", name: "verify.png" }, + { type: "file", uri: `data:image/png;base64,${image_base64}`, mime: "image/png", name: "verify.png" }, ] }, diff --git a/integrations/blender/plugin/src/method.ts b/integrations/blender/plugin/src/method.ts index 9782db0..47525e4 100644 --- a/integrations/blender/plugin/src/method.ts +++ b/integrations/blender/plugin/src/method.ts @@ -4,13 +4,12 @@ export const METHOD_KEY = "blender.method" export const METHOD_TEXT = [ "Working on the open Blender:", - "- Read its version first (blender_hosts, blender_inspect): your knowledge of its Python API may be older than it.", - "- Before writing code for modifiers or Geometry Nodes inputs, the sequencer, compositing, Grease Pencil, animation", - " or render output, ask Blender itself with blender_inspect (type, operator or live data).", - "- If it is still unclear, read the official docs and the Python API release notes of THIS version (links in", - " blender_inspect's result).", - "- Verify each step by its result, not by the absence of an error: read back what changed, and use blender_verify", - " for anything that renders (black or transparent image, camera used, sequencer and compositing state).", + "- Your knowledge of its Python API may be older than it: read its version (blender_hosts, blender_inspect).", + "- Inspect the exact element before coding it: blender_inspect search (words) finds where a setting lives; then its type, operator, node type in its tree or live data.", + "- After an error, read its hint (closest names, real signature, keys, sockets) and inspect again; never guess twice.", + "- An operator that needs a context gets it from bpy.context.temp_override(window, area, region, id, ...).", + "- Before finishing, turn your acceptance criteria into checks (value, comparison, frames): blender_verify criteria, and visible for what must be seen. Report measured values; a failed check is not done.", + "- Still unclear: the docs and Python API release notes of THIS version (links in blender_inspect).", "- Write down what you discover (a recent change, a silent failure) in your report, with the Blender version.", ].join("\n") diff --git a/integrations/blender/test/MANUAL.md b/integrations/blender/test/MANUAL.md index 296e741..a8c7e2e 100644 --- a/integrations/blender/test/MANUAL.md +++ b/integrations/blender/test/MANUAL.md @@ -19,6 +19,8 @@ The CI runs the add-on's tests, the plugin's tools and the conformance checks in | 6 | "Take a screenshot of the window" (`blender_lab`). | The image comes back as an attachment. | | 7 | "Run `print(1)` in Blender." | `blender_execute_code` asks permission; a refusal runs nothing. | | 8 | Disable OpenCode Link in the preferences. | Within 15 s `blender_hosts` lists no Blender and the conversation is no longer attached. | +| 9 | "Add a Multires sphere and paint a mask stroke on it by script." | The stroke runs, `warnings` says the mask layer was created first; leaving Sculpt mode keeps Blender open. | +| 10 | "Mark the sphere as an asset and generate its preview by script." | With `bpy.context.temp_override(id=...)` the preview is generated (`preview.image_size` 128 × 128, not empty). | ## Quarantine diff --git a/integrations/blender/test/blender.test.ts b/integrations/blender/test/blender.test.ts index 7299ce7..5a6bbf0 100644 --- a/integrations/blender/test/blender.test.ts +++ b/integrations/blender/test/blender.test.ts @@ -16,6 +16,8 @@ const skip = blenderBin ? false : "BLENDER_TEST_BIN is not set" const OPS042_TESTS = 10 // The tests of ops043_tests.py: the blockers of the 0.4.2 exercises (QA journal, Luna section). const OPS043_TESTS = 3 +// The tests of ops044_tests.py: the 0.4.3 exercises' findings (QA journal, Luna section). +const OPS044_TESTS = 12 const folder = join(import.meta.dirname, "blender") type Result = { passed: string[]; failed: Array<{ name: string; error: string; trace: string }> } @@ -137,6 +139,157 @@ describe("OpenCode Link in Blender (background)", { skip }, () => { assert.equal((await hostScript("ops043_tests.py", (scratch) => [scratch], 400_000)).passed.length, OPS043_TESTS) }) + it("passes the tests of the 0.4.3 exercises' findings (0.4.4)", async () => { + assert.equal((await hostScript("ops044_tests.py", (scratch) => [scratch], 400_000)).passed.length, OPS044_TESTS) + }) + + it("blender_inspect finds the API by words and shows elements, sockets and names beyond its limit (0.4.4)", async () => { + const { plugin, stop, json } = await served() + try { + const inspect = async (args: Record) => json(await plugin.tool("blender_inspect", args)) + const paths = (found: { search: { results: Array<{ path: string }> } }) => found.search.results.map((r) => r.path) + // Luna 07 (light linking on Object) and 08 (the 5.3 compositing tree on the scene). + assert.ok(paths(await inspect({ search: "light linking" })).includes("Object.light_linking")) + assert.ok(paths(await inspect({ search: "compositing node group" })).includes("Scene.compositing_node_group")) + // Luna 02: the stroke's elements, and the poll with Blender's reason. + const stroke = (await inspect({ operator: "sculpt.brush_stroke" })).operator + const elements = stroke.properties.find((p: { id: string }) => p.id === "stroke").element + assert.equal(elements.type, "OperatorStrokeElement") + assert.ok(elements.properties.some((p: { id: string }) => p.id === "x_tilt")) + assert.equal(stroke.poll.in_this_context, false) + assert.match(stroke.poll.blender_says, /poll\(\)/) + // Luna 04 and 08: a node type made in the tree named, or what that tree makes instead. + const simulation = (await inspect({ type: "GeometryNodeSimulationInput", tree: "geometry" })).type + assert.equal(simulation.tree_type, "GeometryNodeTree") + assert.ok( + simulation.outputs.some((s: { name: string }) => s.name === "Delta Time"), + JSON.stringify(simulation), + ) + const composite = (await inspect({ type: "CompositorNodeComposite", tree: "compositing" })).type + assert.ok(Array.isArray(composite.creatable_in_CompositorNodeTree), JSON.stringify(composite).slice(0, 800)) + // Luna 05: entries beyond the limit are named, not cut. + const fluid = (await inspect({ type: "FluidDomainSettings", limit: 40 })).type + assert.equal(fluid.properties.length, 40) + assert.ok(fluid.properties_more.count > 0 && fluid.properties_more.names.length === fluid.properties_more.count) + assert.ok((await inspect({ type: "FluidDomainSettings", match: "cache" })).type.properties.length > 0) + } finally { + await stop() + } + }) + + it("blender_verify measures the agent's criteria and says why an object is not seen (0.4.4)", async () => { + const { plugin, stop, json } = await served() + try { + const built = json( + await plugin.tool("blender_execute_code", { + code: [ + "import bpy, math", + "sc = bpy.context.scene", + "bpy.data.objects.remove(bpy.data.objects['Cube'])", + "bpy.ops.object.camera_add(location=(0, -10, 1), rotation=(math.radians(90), 0, 0))", + "sc.camera = bpy.context.object", + "bpy.ops.mesh.primitive_cube_add(size=1, location=(0, 0, 1.38))", + "t = bpy.context.object; t.name = 'Tissue'", + "t.keyframe_insert('rotation_euler', frame=1)", + "t.rotation_euler.z = math.radians(90); t.keyframe_insert('rotation_euler', frame=10)", + "bpy.ops.mesh.primitive_cube_add(size=1, location=(1, 0, 1)); bpy.context.object.name = 'Hidden'", + "bpy.context.object.hide_render = True", + "bpy.ops.mesh.primitive_cube_add(size=1, location=(100, 0, 1)); bpy.context.object.name = 'Away'", + "c = bpy.data.collections.new('Props'); sc.collection.children.link(c)", + "o = bpy.data.objects.new('Crate', bpy.data.meshes['Cube']); c.objects.link(o)", + "bpy.context.view_layer.layer_collection.children['Props'].exclude = True", + "sc.frame_set(1)", + ].join("\n"), + }), + ) + assert.equal(built.status, "executed", JSON.stringify(built).slice(0, 1500)) + const verify = async (args: Record) => { + const out = await plugin.tool("blender_verify", args) + assert.equal(typeof out.content, "string", "no render without render or view") + return json(out) + } + // Luna 06: z-min 0.88 against a "< 0.7" threshold is a failed check, measured. + const checked = await verify({ + criteria: [ + { label: "tissue under 0.7", expr: "bounds('Tissue').min.z", op: "<", value: 0.7 }, + { label: "top above 1", path: "objects['Tissue'].location.z", op: ">", value: 1 }, + // Luna 09: the pose is measured at its frames, not assumed. + { + label: "turned", + expr: "ev('Tissue').rotation_euler.z", + op: "approx", + value: 1.5708, + tol: 0.001, + frames: [1, 10], + }, + ], + }) + assert.equal(checked.all_passed, false) + assert.deepEqual(checked.failed, ["tissue under 0.7", "turned"]) + const [under, top, turned] = checked.criteria + assert.equal(under.measured, 0.88) + assert.equal(top.passed, true) + assert.deepEqual( + turned.frames.map((f: { frame: number; passed: boolean }) => [f.frame, f.passed]), + [ + [1, false], + [10, true], + ], + ) + const seen = async (object: string) => (await verify({ visible: { object, frame: 1 } })).visible + assert.equal((await seen("Tissue")).visible, true) + assert.match((await seen("Hidden")).reasons.join(" "), /hidden in render/) + assert.match((await seen("Away")).reasons.join(" "), /out of frame/) + assert.match((await seen("Crate")).reasons.join(" "), /excluded from view layer/) + await assert.rejects( + plugin.tool("blender_verify", { criteria: [{ expr: "bpy.ops.render.render()", op: "==", value: 1 }] }), + /not a read/, + ) + } finally { + await stop() + } + }) + + it("a call after Blender closed says so, with the crash report Blender wrote (0.4.4)", async () => { + const iso = isolatedRoot("blender-closed-") + const stopFile = join(iso.root, "stop") + installTestAddon(iso) + const run = runBlender(iso, join(folder, "serve.py"), [ + "--listen-only", + "--seconds", + "120", + "--stop-file", + stopFile, + ]) + const plugin = await loadPlugin() + try { + let line: string | undefined + for (let attempt = 0; attempt < 600 && !line; attempt += 1) { + line = run + .output() + .split("\n") + .find((entry) => entry.startsWith("ENDPOINT ")) + if (!line) await new Promise((resolve) => setTimeout(resolve, 100)) + } + assert.ok(line, run.output().slice(-2000)) + const { port, token, script_handle } = JSON.parse(line.slice("ENDPOINT ".length)) + await plugin.rpc("advertise", announcement({ port, token }, script_handle)) + assert.equal(typeof JSON.parse(String((await plugin.tool("blender_context")).content)).revision, "number") + writeFileSync(stopFile, "") + await run.exited + await assert.rejects(plugin.tool("blender_context"), /Blender closed.*has ended, with no crash report in /) + // Where Blender writes its own report when it crashes (an unsaved file: blender.crash.txt). + const report = join(iso.root, "tmp", "blender.crash.txt") + writeFileSync(report, "# Blender 5.3.0\n") + await assert.rejects(plugin.tool("blender_context"), /Blender closed.*Crash report: .*blender\.crash\.txt/) + } finally { + writeFileSync(stopFile, "") + await run.exited + await plugin.cleanup() + iso.cleanup() + } + }) + it("passes the tests of the western film's v7 frictions (0.4.2)", async () => { assert.equal((await hostScript("ops042_tests.py", (scratch) => [scratch], 400_000)).passed.length, OPS042_TESTS) }) diff --git a/integrations/blender/test/blender/ops044_tests.py b/integrations/blender/test/blender/ops044_tests.py new file mode 100644 index 0000000..0ab47ee --- /dev/null +++ b/integrations/blender/test/blender/ops044_tests.py @@ -0,0 +1,217 @@ +"""The 0.4.3 exercises' findings (QA journal, Luna section): errors that say what is valid, operator calls that +close Blender 5.3 from a script, the crash report's folder in hello. Each fails on the 0.4.3 add-on and passes on +0.4.4, in a private background Blender 5.3 (run by blender.test.ts). Prints RESULT . +Usage: blender -b --factory-startup --python ops044_tests.py -- +""" + +import importlib +import json +import os +import sys +import traceback + +import addon_utils +import bpy + +MODULE = "bl_ext.user_default.opencode_link" +addon_utils.enable(MODULE, default_set=True, handle_error=None) +addon = importlib.import_module(MODULE + ".addon") +session = addon.session() +core, app = session.core, session.app +session.stop() +SCRATCH = sys.argv[sys.argv.index("--") + 1] + +results = {"passed": [], "failed": [], "host_version": core.version} +TESTS = [] + + +def test(fn): + TESTS.append(fn) + return fn + + +def check(condition, message): + if not condition: + raise AssertionError(message) + + +def empty(): + bpy.ops.wm.read_factory_settings(use_empty=True) + core.quarantined = False + core.quarantine = None + bpy.context.view_layer.update() + addon.pump(0.05) + + +def run_code(text, read_only=False): + params = {"script_handle": app.script_handle(), "code": text} + if read_only: + params["read_only"] = True + return core.handle("execute_code", params) + + +def hint_of(text): + out = run_code(text) + check(out["status"] == "failed", "the code fails: %s" % out) + check("hint" in out, "the failure carries a hint: %s" % json.dumps(out)[:600]) + return out, out["hint"] + + +# -- (4) first, while this background Blender has pushed no undo step: no undo stack yet -------------------------- +@test +def c_a_sculpt_operator_without_interface_or_undo_step_no_longer_closes_blender(): + # read_only: no barrier step either. On 0.4.3 the sculpt undo step of the fill closes Blender here. + out = run_code("import bpy\nbpy.ops.mesh.primitive_uv_sphere_add()\nbpy.ops.object.mode_set(mode='SCULPT')\n" + "bpy.ops.paint.mask_flood_fill(mode='VALUE', value=0.7)\nbpy.ops.object.mode_set(mode='OBJECT')\n" + "result = {'mode': bpy.context.mode}", read_only=True) + check(out["status"] == "executed" and out["result"] == {"mode": "OBJECT"}, "runs: %s" % out.get("message")) + check(any("first undo step" in w for w in out.get("warnings", [])), "and says why: %s" % out.get("warnings")) + + +# -- (1) errors that say what is valid, read from this Blender --------------------------------------------------- +@test +def e02_an_unknown_property_names_the_closest_ones_of_its_type(): + empty() + out, hint = hint_of("import bpy\nbpy.context.scene.tool_settings.sculpt.detail_type = 'RELATIVE'") + check(hint["type"] == "Sculpt" and hint["missing"] == "detail_type", "the type and the name: %s" % hint) + closest = [c["id"] for c in hint["closest"]] + check("detail_type_method" in closest, "the real property is proposed: %s" % closest) + method = next(c for c in hint["closest"] if c["id"] == "detail_type_method") + check(method["type"] == "ENUM" and len(method["enum"]) >= 2, "with its enumeration: %s" % method) + check("detail_size" in hint["properties"]["all"], "the type's properties are listed") + + +@test +def e_an_operator_argument_gets_the_operators_real_signature(): + empty() + out, hint = hint_of("import bpy\nbpy.ops.mesh.primitive_uv_sphere_add(segmentz=8)") + check(hint["operator"] == "mesh.primitive_uv_sphere_add" and hint["unknown"] == "segmentz", "named: %s" % hint) + check(hint["closest"][0] == "segments", "closest: %s" % hint["closest"]) + check(any(p["id"] == "ring_count" for p in hint["signature"]), "the signature lists every parameter") + + +@test +def e_a_collection_element_names_every_property_it_needs(): + empty() + out, hint = hint_of("import bpy\nbpy.ops.wm.append(directory='/nowhere/', files=[{'nam': 'x'}])") + files = next(p for p in hint["signature"] if p["id"] == "files") + check(files["element"]["type"] == "OperatorFileListElement", "the element type: %s" % files) + check([e["id"] for e in files["element"]["properties"]] == ["name"], "its properties: %s" % files["element"]) + check(hint.get("missing") == "name", "the missing key: %s" % hint) + + +@test +def e_an_invalid_enumeration_value_gets_the_closest_items(): + empty() + out, hint = hint_of("import bpy\nbpy.ops.mesh.primitive_cube_add()\nbpy.ops.object.mode_set(mode='SCULPTING')") + check(hint["invalid"] == "SCULPTING" and hint["closest"][0] == "SCULPT", "closest: %s" % hint) + out, hint = hint_of("import bpy\nbpy.ops.mesh.primitive_cube_add()\nbpy.context.object.display_type = 'WIREFRAME'") + check("WIRE" in hint["closest"], "a property's enumeration too: %s" % hint) + + +@test +def e04_a_missing_socket_lists_the_nodes_real_sockets(): + empty() + out, hint = hint_of("import bpy\nm = bpy.data.materials.new('M')\nm.use_nodes = True\n" + "node = m.node_tree.nodes['Principled BSDF']\nnode.inputs['Base Colour'].default_value = (1, 0, 0, 1)") + check(hint["missing"] == "Base Colour" and hint["closest"][0] == "Base Color", "closest socket: %s" % hint) + check("node.inputs" == hint["collection"] and "Roughness" in hint["keys"]["all"], "the collection read: %s" % hint) + check(not bpy.data.materials, "the failed run is undone after the hint was read") + + +@test +def e08_an_unknown_node_type_lists_what_the_tree_creates(): + empty() + out, hint = hint_of("import bpy\ng = bpy.data.node_groups.new('C', 'CompositorNodeTree')\n" + "g.nodes.new('CompositorNodeComposite')") + check(hint["missing"] == "CompositorNodeComposite" and hint["tree_type"] == "CompositorNodeTree", "named: %s" % hint) + check(isinstance(hint["closest_creatable"], list), "creatable node types listed: %s" % hint) + out, hint = hint_of("import bpy\nm = bpy.data.materials.new('M')\nm.use_nodes = True\n" + "m.node_tree.nodes.new('ShaderNodeBsdfPrincipalled')") + check(hint["closest_creatable"][0]["type"] == "ShaderNodeBsdfPrincipled", "closest: %s" % hint["closest_creatable"][:2]) + check("Base Color" in hint["closest_creatable"][0]["inputs"], "with its sockets") + + +@test +def e_an_unknown_operator_names_the_closest_ones(): + empty() + out, hint = hint_of("import bpy\nbpy.ops.object.mode_sett(mode='OBJECT')") + check("object.mode_set" in hint["closest"], "closest: %s" % hint) + + +@test +def e09_a_failed_poll_shows_blenders_reason_and_the_context_it_had(): + empty() + out, hint = hint_of("import bpy\nbpy.ops.ed.lib_id_generate_preview()") + check(hint["operator"] == "ed.lib_id_generate_preview" and hint["context"]["id"] is None, "context: %s" % hint) + check("temp_override" in hint["give_context"], "how to give it: %s" % hint) + + +@test +def e_watched_operators_behave_as_blenders_own(): + empty() + out = run_code("import bpy\nop = bpy.ops.mesh.primitive_cube_add\n" + "result = {'poll': op.poll(), 'rna': op.get_rna_type().identifier, 'idname': op.idname()," + " 'run': sorted(op(size=2)), 'repr': repr(op)[:28]}") + check(out["status"] == "executed", "runs: %s" % out) + check(out["result"] == {"poll": True, "rna": "MESH_OT_primitive_cube_add", "idname": "MESH_OT_primitive_cube_add", + "run": ["FINISHED"], "repr": "bpy.ops.mesh.primitive_cube_"}, "same results: %s" % out["result"]) + check(type(bpy.ops.mesh.primitive_cube_add).__name__ == "BPyOpFunction", "bpy.ops restored after the run") + + +# -- (4) calls that close Blender 5.3 from a script --------------------------------------------------------------- +@test +def c02_a_scripted_mask_stroke_on_multires_gets_its_mask_layer_first(): + """The decision of the guard, its window-only part replayed with a recorder (strokes need a window).""" + empty() + watch_module = importlib.import_module(MODULE + ".op_watch") + bpy.ops.mesh.primitive_uv_sphere_add() + obj = bpy.context.object + obj.modifiers.new("Multires", "MULTIRES") + bpy.ops.object.multires_subdivide(modifier="Multires", mode="CATMULL_CLARK") + bpy.ops.object.mode_set(mode="SCULPT") + calls = [] + + class Windowed(object): + background = False + + real = watch_module.bpy + proxy = type("Bpy", (), {"app": Windowed, "context": bpy.context, "ops": bpy.ops}) + watch_module.bpy = proxy + try: + watch = watch_module._Watch(lambda module, name: (lambda **kw: calls.append((module, name, kw)))) + watch.before("sculpt.brush_stroke", (), {"brush_toggle": "None"}) + check(calls == [], "a draw stroke needs nothing: %s" % calls) + watch.before("sculpt.brush_stroke", ("INVOKE_DEFAULT",), {"brush_toggle": "MASK"}) + check(calls == [], "an invoked stroke prepares itself") + watch.before("sculpt.brush_stroke", (), {"brush_toggle": "MASK"}) + check(calls == [("paint", "mask_flood_fill", {"mode": "INVERT"})] * 2, "the layer made, mask kept: %s" % calls) + watch.before("sculpt.brush_stroke", (), {"brush_toggle": "MASK"}) + check(len(calls) == 2, "once per object and run") + check(watch.notes and "mask layer" in watch.notes[0], "and said: %s" % watch.notes) + obj.modifiers.remove(obj.modifiers[0]) + other = watch_module._Watch(lambda module, name: (lambda **kw: calls.append((module, name, kw)))) + other.before("sculpt.brush_stroke", (), {"brush_toggle": "MASK"}) + check(len(calls) == 2, "without multires nothing is needed") + finally: + watch_module.bpy = real + bpy.ops.object.mode_set(mode="OBJECT") + + +@test +def c_hello_names_the_process_and_the_folder_of_its_crash_report(): + hello = core.handle("hello", {}) + process = hello.get("process") or {} + check(process.get("pid") == os.getpid(), "the pid: %s" % hello) + check(os.path.isdir(process.get("temp_dir", "")), "an existing folder: %s" % process) + check(os.path.normpath(bpy.app.tempdir).startswith(os.path.normpath(process["temp_dir"])), "the session folder's parent") + + +for fn in TESTS: + try: + fn() + results["passed"].append(fn.__name__) + except Exception as error: # noqa: BLE001 + results["failed"].append({"name": fn.__name__, "error": "%s: %s" % (type(error).__name__, error), + "trace": traceback.format_exc()[-1500:]}) +print("RESULT " + json.dumps(results), flush=True) diff --git a/integrations/blender/test/plugin.test.ts b/integrations/blender/test/plugin.test.ts index 9516169..a6b0434 100644 --- a/integrations/blender/test/plugin.test.ts +++ b/integrations/blender/test/plugin.test.ts @@ -27,7 +27,7 @@ async function plugin(input: Parameters[0] = {}): Promise { await loaded.tool("blender_context") assert.equal(loaded.registry.binding("ses_test")?.offerID, offerIDs[0]) assert.deepEqual(loaded.permissions, []) + // The offer's hello, then this conversation's: it names the process, for a call after Blender closed. assert.deepEqual( hosts[0]?.requests.map((request) => request.method), - ["hello", "scene"], + ["hello", "hello", "scene"], ) // The method joins the conversation once. await loaded.tool("blender_context") @@ -819,7 +820,7 @@ describe("tools", () => { const other = await plugin() await other.rpc("advertise", announcement(old.endpoint, old.scriptHandle)) other.registry.attach(other.registry.hosts().offers[0]?.offerID as string, "ses_test") - await assert.rejects(other.tool("blender_context"), /no scene method: install OpenCode Link 0\.4\.3/) + await assert.rejects(other.tool("blender_context"), /no scene method: install OpenCode Link 0\.4\.4/) assert.ok(loaded) }) }) diff --git a/integrations/blender/test/publication.test.ts b/integrations/blender/test/publication.test.ts index 7a1305a..ab954b8 100644 --- a/integrations/blender/test/publication.test.ts +++ b/integrations/blender/test/publication.test.ts @@ -6,7 +6,7 @@ test("only Blender is publishable, with public access and trusted-publishing met const plugin = new URL("../plugin/", import.meta.url) const pkg = JSON.parse(readFileSync(new URL("package.json", plugin), "utf8")) assert.equal(pkg.name, "@neuralnomads/opencode-blender") - assert.equal(pkg.version, "0.4.3") + assert.equal(pkg.version, "0.4.4") assert.equal(pkg.private, undefined) assert.equal(pkg.publishConfig.access, "public") assert.equal(pkg.repository.url, "https://github.com/NeuralNomadsAI/opencode-integrations") diff --git a/integrations/blender/test/unit.test.ts b/integrations/blender/test/unit.test.ts index c28c48c..d86ab1f 100644 --- a/integrations/blender/test/unit.test.ts +++ b/integrations/blender/test/unit.test.ts @@ -1,13 +1,15 @@ // Units without a host: the plugin's validation of edit batches against the add-on's published operations -// (host/ops.json), the fixed programs, render task verification and the working method. +// (host/ops.json), the fixed programs, render task verification, the notice of a closed Blender and the working +// method. import assert from "node:assert/strict" import { execFileSync } from "node:child_process" -import { mkdtempSync, readFileSync, writeFileSync } from "node:fs" +import { mkdtempSync, readFileSync, utimesSync, writeFileSync } from "node:fs" import { tmpdir } from "node:os" import { join } from "node:path" import { describe, it } from "node:test" +import { closedMessage, readProcess } from "../plugin/src/closed.ts" import { readPackage } from "../plugin/src/integration.ts" import { METHOD_TEXT, methodAttacher, resetMethodForTests } from "../plugin/src/method.ts" import { programCode } from "../plugin/src/programs.ts" @@ -154,6 +156,30 @@ describe("fixed programs and render tasks", () => { }) }) +describe("a Blender that closed", () => { + it("is said with its process and the crash report it wrote since it was reached, never while it lives", () => { + const dir = mkdtempSync(join(tmpdir(), "blender-closed-")) + assert.equal(readProcess({ process: { pid: -1, temp_dir: dir } }), null) + assert.equal(readProcess({ process: { pid: 12, temp_dir: "" } }), null) + assert.equal(readProcess({ revision: 1 }), null) + const host = readProcess({ process: { pid: 4242, temp_dir: dir } }, "Blender: shot.blend", Date.now()) + assert.ok(host) + assert.equal( + closedMessage(host, () => true), + null, + ) + const old = join(dir, "earlier.crash.txt") + writeFileSync(old, "") + utimesSync(old, new Date(Date.now() - 60_000), new Date(Date.now() - 60_000)) + assert.match( + String(closedMessage(host, () => false)), + /^Blender closed \(Blender: shot\.blend\): its process 4242 has ended, with no crash report in /, + ) + writeFileSync(join(dir, "shot.crash.txt"), "# Blender 5.3.0\n") + assert.match(String(closedMessage(host, () => false)), /Crash report: .*shot\.crash\.txt\. Open Blender again/) + }) +}) + describe("the working method", () => { it("is short, joins a conversation once, and never fails a Blender call", async () => { assert.ok(METHOD_TEXT.split("\n").length <= 10 && METHOD_TEXT.length < 1_000) diff --git a/package-lock.json b/package-lock.json index 48cef6e..460f882 100644 --- a/package-lock.json +++ b/package-lock.json @@ -39,7 +39,7 @@ }, "integrations/blender/plugin": { "name": "@neuralnomads/opencode-blender", - "version": "0.4.3", + "version": "0.4.4", "license": "MIT AND GPL-3.0-or-later", "devDependencies": { "@opencode/plugin": "2.2.5", diff --git a/spec/README.md b/spec/README.md index b65f776..d18ef52 100644 --- a/spec/README.md +++ b/spec/README.md @@ -19,9 +19,9 @@ The integration's `package.json` carries a marker under `opencodeIntegration`, r "host": { "app": "blender", "protocol": 1, - "range": "^0.4.3", + "range": "^0.4.4", "appVersions": ">=5.3", - "payload": "host/blender/opencode_link-0.4.3.zip", + "payload": "host/blender/opencode_link-0.4.4.zip", "sha256": "" } }