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.mjsindex 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.pyindex 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"]