Skip to content

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.py
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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 failure
const 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.py
new file mode 100644
index 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