Official Codebase of 3DCodeVerse
Python
scene probe: an animated child whose zone never forwards update() is a warning, observed without the harness calling it
gaoypeng530c8aa2945b
diff --git a/harness/codeverse3d/spatial/probes.py b/harness/codeverse3d/spatial/probes.pyindex f5002418..2bab6123 100644--- a/harness/codeverse3d/spatial/probes.py+++ b/harness/codeverse3d/spatial/probes.py@@ -182,6 +182,17 @@ def _census_findings(c: dict[str, Any]) -> list[GateFinding]:out: list[GateFinding] = []if not c:return out+ hook_audit = c.get("animation_hooks") or {}+ for hook in hook_audit.get("unobserved", [])[:12]:+ out.append(_f(+ gate, Severity.WARN,+ f"animation hook {hook.get('path', '?')} was not observed during "+ f"update sampling ({hook_audit.get('from_time', 0):g}–{hook_audit.get('to_time', 0):g} s)",+ target=hook.get("zone") or "src/scene.js",+ hint="verify the parent zone forwards update(t, dt) to this asset; captured callback references "+ "or delayed animation can evade this observation, so inspect before changing code",+ kind="unobserved_animation_hook", hook_path=hook.get("path"),+ ))tot = c.get("totals", {})if tot.get("lights", 0) == 0:out.append(_f(gate, Severity.WARN, "scene has no lights (MeshStandardMaterial renders black)", target="src/env.js",diff --git a/harness/runtime_js/lib/scene_host.mjs b/harness/runtime_js/lib/scene_host.mjsindex 782c575b..f794daf6 100644--- a/harness/runtime_js/lib/scene_host.mjs+++ b/harness/runtime_js/lib/scene_host.mjs@@ -24,6 +24,7 @@ import { classifyBackdrop, nonSolid, drawableBox } from './backdrop.mjs';import { installShaderErrorHook } from './host_shader_errors.mjs';import { attributeErrors, captured, captureMaterialSources, materialAudit } from './host_compile.mjs';import { makeRenderer, rendererString } from './browser/renderer.js';+import { observeUpdateHooks } from './update_hooks.mjs';const FIXED_DT = 1 / 30;const LOAD_IDLE_TIMEOUT_MS = 30000;@@ -658,6 +659,20 @@ function census() {return c;}+/** Probe-only observation around the normal deterministic update steps. */+function probeUpdateHooks(t) {+ const start = state.simTime;+ try {+ const report = observeUpdateHooks(state.scene, () => advanceTo(t));+ return { ...report, from_time: start, to_time: state.simTime };+ } catch (error) {+ // Optional instrumentation must not turn an unusual userData descriptor+ // into an agent build failure; the ordinary update error checks still run.+ advanceTo(t);+ return { error: String(error?.message || error).slice(0, 400), from_time: start, to_time: state.simTime };+ }+}+window.__c3v = {boot,renderAt,@@ -666,6 +681,7 @@ window.__c3v = {compileAll,census,placement,+ probeUpdateHooks,fps,post: () => (state.postInfo ? { ...state.postInfo } : null),hostWarnings: () => state.hostWarnings.slice(),diff --git a/harness/runtime_js/lib/update_hooks.mjs b/harness/runtime_js/lib/update_hooks.mjsnew file mode 100644index 00000000..a6529589--- /dev/null+++ b/harness/runtime_js/lib/update_hooks.mjs@@ -0,0 +1,41 @@+/** Observe property-dispatched animation hooks without adding any update calls.+ * A missing observation is a diagnostic, not proof that an animation is static:+ * callbacks captured in closures and delayed callbacks can evade this sample.+ */+export function observeUpdateHooks(scene, exercise) {+ const rows = [], restore = [];+ try {+ scene.traverse((object) => {+ const data = object.userData;+ if (!data) return;+ const descriptor = Object.getOwnPropertyDescriptor(data, 'update');+ if (!descriptor || typeof descriptor.value !== 'function') return;+ const original = descriptor.value;+ const path = [];+ for (let current = object; current && current !== scene; current = current.parent) {+ path.unshift(current.name || current.type || 'Object3D');+ }+ const row = { path: path.join('/') || scene.name || 'Scene', zone: path[0] || '', calls: 0,+ instrumented: !!(descriptor && descriptor.writable && descriptor.value === original) };+ rows.push(row);+ if (!row.instrumented) return;+ function observed(...args) {+ row.calls += 1;+ return Reflect.apply(original, this, args);+ }+ // Preserve aliases such as userData.tick === userData.update.+ for (const key of Object.keys(data)) {+ const property = Object.getOwnPropertyDescriptor(data, key);+ if (property && property.writable && property.value === original) {+ data[key] = observed;+ restore.push(() => { if (data[key] === observed) data[key] = original; });+ }+ }+ });+ exercise();+ } finally {+ for (const undo of restore.reverse()) undo();+ }+ return { hooks: rows, unobserved: rows.filter(row => row.instrumented && row.calls === 0),+ limitation: 'Only property-dispatched hooks during the sampled update interval are observed. Captured callback references and delayed animations can be unobserved; inspect the parent forwarding before changing code.' };+}diff --git a/harness/runtime_js/probe_scene.mjs b/harness/runtime_js/probe_scene.mjsindex 19022f03..a253bca7 100644--- a/harness/runtime_js/probe_scene.mjs+++ b/harness/runtime_js/probe_scene.mjs@@ -86,14 +86,16 @@ async function main() {// exercise update() for a few fixed steps and one tiny render (lazy programs compile)const upd = await page.evaluate((n) => {try {+ const animation_hooks = window.__c3v.probeUpdateHooks(n / 30);window.__c3v.renderAt(window.__c3v.cameras()[0], n / 30);- return { ok: true };+ return { ok: true, animation_hooks };} catch (e) {return { ok: false, error: String((e && e.stack) || e).slice(0, 800) };}}, 10);result.update_ok = upd.ok;result.update_error = upd.error || '';+ if (upd.animation_hooks) result.census.animation_hooks = upd.animation_hooks;// update() exceptions are caught page-side (rendering continues); still a probe failureconst updateErrors = await page.evaluate(() => window.__c3v.updateErrors());if (upd.ok && updateErrors.length) {diff --git a/harness/tests/scene_runtime/test_update_hooks.py b/harness/tests/scene_runtime/test_update_hooks.pynew file mode 100644index 00000000..7f6f2ba7--- /dev/null+++ b/harness/tests/scene_runtime/test_update_hooks.py@@ -0,0 +1,59 @@+"""Detect disconnected animation dispatch without silently driving agent hooks."""+from __future__ import annotations++import json++import pytest++from codeverse3d.contracts.artifacts import Severity+from codeverse3d.spatial.probes import probe_scene+from tests.scene_runtime.conftest import needs_browser, needs_node, run_node_json+++@needs_node+def test_observer_preserves_calls_aliases_context_and_restores_after_throw():+ result = run_node_json("""+import * as T from 'three';+import { observeUpdateHooks } from './lib/update_hooks.mjs';+const scene=new T.Scene(), zone=new T.Group(), moving=new T.Group(), idle=new T.Group();+zone.name='Bay';moving.name='Wing';idle.name='Detached';scene.add(zone);zone.add(moving,idle);+let calls=0;const original=function(t){calls++;this.time=t;};+moving.userData.update=original;moving.userData.tick=original;idle.userData.update=()=>{throw Error('must not invoke missing hook');};+const report=observeUpdateHooks(scene,()=>moving.userData.tick(1.5));+let caught=false;try{observeUpdateHooks(scene,()=>{moving.userData.update(2);throw Error('expected');});}catch(e){caught=e.message==='expected';}+console.log(JSON.stringify({report,calls,time:moving.userData.time,caught,+ restored:moving.userData.update===original&&moving.userData.tick===original}));+""")+ assert result["calls"] == 2 and result["time"] == 2+ assert result["caught"] and result["restored"]+ assert [row["path"] for row in result["report"]["unobserved"]] == ["Bay/Detached"]+ assert result["report"]["hooks"][0]["calls"] == 1+++@needs_browser[email protected]("forward", [False, True])+def test_probe_identifies_disconnected_child_and_does_not_invoke_it(ws, forward):+ call = "wing.userData.update(t);" if forward else ""+ (ws.src / "scene.js").write_text("""+import * as THREE from 'three';+export function createScene() {+ const scene=new THREE.Scene(),zone=new THREE.Group(),wing=new THREE.Group();+ zone.name='CentralPad';wing.name='Shuttle';scene.add(zone);zone.add(wing);+ wing.add(new THREE.Mesh(new THREE.BoxGeometry(),new THREE.MeshBasicMaterial()));+ wing.userData.update=t=>{wing.rotation.y=t;};+ zone.userData.update=t=>{FORWARD};+ return {scene,cameras:[{name:'hero',position:[3,2,3],lookAt:[0,0,0]}],update:t=>zone.userData.update(t)};+}+""".replace("FORWARD", call))+ result = probe_scene(ws)+ assert result.ok and result.gate.passed+ findings = [f for f in result.gate.findings if f.data.get("kind") == "unobserved_animation_hook"]+ assert bool(findings) is not forward+ audit = json.loads((ws.artifacts / "scene_probe.json").read_text())["census"]["animation_hooks"]+ shuttle = next(row for row in audit["hooks"] if row["path"] == "CentralPad/Shuttle")+ assert (shuttle["calls"] > 0) is forward+ if not forward:+ assert findings[0].severity == Severity.WARN and findings[0].target == "CentralPad"+ assert "parent zone" in findings[0].fix_hint