Skip to content

Official Codebase of 3DCodeVerse

Python

scene probe: a hook is unobserved only when nothing under it moved — cached hooks, tickShaders and empty stubs are not warnings

gaoypeng3a4eeacce819
diff --git a/harness/runtime_js/lib/update_hooks.mjs b/harness/runtime_js/lib/update_hooks.mjs
index a6529589..b93620af 100644
--- a/harness/runtime_js/lib/update_hooks.mjs
+++ b/harness/runtime_js/lib/update_hooks.mjs
@@ -1,9 +1,38 @@
/** 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.
+ * A hook counts as unobserved only when it was never called through userData AND
+ * nothing under its object moved during the sample: a zone that calls a cached
+ * reference (what prompts/tracks/scene_asset.j2 teaches) or one tickShaders() for
+ * every uTime still animates it. An empty stub (`() => {}`) has nothing to forward.
*/
+const EMPTY_FN_RE = /^(?:function\s*\w*)?\s*\([^)]*\)\s*(?:=>)?\s*\{\s*\}$|^\(?[\w\s,]*\)?\s*=>\s*(?:undefined|void 0|\{\s*\})$/;
+
+function uniformValue(v) {
+ if (v === null || v === undefined) return null;
+ if (typeof v === 'number' || typeof v === 'boolean') return v;
+ if (v.isTexture) return null;
+ if (typeof v.toArray === 'function') return v.toArray();
+ return null;
+}
+
+/** Everything under `object` an update() can visibly change, as one string. */
+function stateOf(object) {
+ const parts = [];
+ object.traverse((o) => {
+ parts.push(o.visible, o.position.toArray(), o.quaternion.toArray(), o.scale.toArray());
+ if (o.morphTargetInfluences) parts.push(o.morphTargetInfluences.slice());
+ if (o.instanceMatrix) parts.push(o.instanceMatrix.version);
+ const attrs = o.geometry && o.geometry.attributes;
+ if (attrs) for (const k of Object.keys(attrs)) parts.push(attrs[k].version);
+ for (const m of [].concat(o.material || [])) {
+ parts.push(m.opacity);
+ for (const [k, u] of Object.entries(m.uniforms || {})) parts.push(k, uniformValue(u && u.value));
+ }
+ });
+ return JSON.stringify(parts);
+}
+
export function observeUpdateHooks(scene, exercise) {
- const rows = [], restore = [];
+ const rows = [], restore = [], before = new Map();
try {
scene.traverse((object) => {
const data = object.userData;
@@ -17,8 +46,10 @@ export function observeUpdateHooks(scene, exercise) {
}
const row = { path: path.join('/') || scene.name || 'Scene', zone: path[0] || '', calls: 0,
instrumented: !!(descriptor && descriptor.writable && descriptor.value === original) };
+ row.empty = EMPTY_FN_RE.test(String(original).trim());
rows.push(row);
if (!row.instrumented) return;
+ before.set(row, [object, stateOf(object)]);
function observed(...args) {
row.calls += 1;
return Reflect.apply(original, this, args);
@@ -36,6 +67,7 @@ export function observeUpdateHooks(scene, exercise) {
} finally {
for (const undo of restore.reverse()) undo();
}
- return { hooks: rows, unobserved: rows.filter(row => row.instrumented && row.calls === 0),
+ for (const [row, [object, state]] of before) row.moved = stateOf(object) !== state;
+ return { hooks: rows, unobserved: rows.filter(row => row.instrumented && row.calls === 0 && !row.moved && !row.empty),
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/tests/scene_runtime/test_update_hooks.py b/harness/tests/scene_runtime/test_update_hooks.py
index 7f6f2ba7..2ae98075 100644
--- a/harness/tests/scene_runtime/test_update_hooks.py
+++ b/harness/tests/scene_runtime/test_update_hooks.py
@@ -57,3 +57,26 @@ export function createScene() {
if not forward:
assert findings[0].severity == Severity.WARN and findings[0].target == "CentralPad"
assert "parent zone" in findings[0].fix_hint
+
+
+@needs_node
+def test_cached_hooks_shader_ticks_and_empty_stubs_are_not_reported():
+ """The zone that places an asset may cache its hook (prompts/tracks/scene_asset.j2), one tickShaders()
+ may drive every uTime, and a library stub `() => {}` has nothing to forward: none is 'unobserved'."""
+ 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(); zone.name='Farm'; scene.add(zone);
+const mill=new T.Group(); mill.name='Windmill'; zone.add(mill);
+mill.userData.update=t=>{mill.rotation.z=t;}; const hook=mill.userData.update;
+const mat=new T.ShaderMaterial({uniforms:{uTime:{value:0}}});
+const rain=new T.Mesh(new T.BoxGeometry(),mat); rain.name='Rain'; zone.add(rain);
+rain.userData.update=t=>{mat.uniforms.uTime.value=t;};
+const ice=new T.Group(); ice.name='Ice'; zone.add(ice); ice.userData.update=()=>{};
+const still=new T.Group(); still.name='Still'; zone.add(still); still.userData.update=t=>{still.position.x=t;};
+const report=observeUpdateHooks(scene,()=>{for(let i=1;i<=3;i++){hook(i/30);
+ scene.traverse(o=>{if(o.material?.uniforms?.uTime)o.material.uniforms.uTime.value=i/30;});}});
+console.log(JSON.stringify(report.unobserved.map(r=>r.path)));
+""")
+ assert result == ["Farm/Still"]