@forgeax/engine-scene 0.1.33 → 0.1.35

package/README.md

@@ -101,12 +101,14 @@ subtree is exposed as contiguous spans without a parallel event journal.
 `Transform` remains authored local TRS; `GlobalTransform` is the resolved
 world-space authority.
 
-For a valid hierarchy, propagation expands the ECS-maintained `Children`
-buffer from each root in parent-first order. `ChildOf` is the writable source
-fact; `Children` is a read-only materialized target, so source mutations and
-their reverse lists converge before the frame pass. The numeric traversal
-borrows ECS columns and uses only constant matrix scratch plus depth/row
-markers; it does not build a Scene graph or per-node matrix cache.
+A structural or parent-relation change validates the full hierarchy through
+ECS-maintained `Children` lists. Between those changes, independent `changed`
+queries select the highest edited Transform ancestors and only their subtrees
+are expanded in parent-first order. A second FixedUpdate/Update propagation
+without intervening writes performs no hierarchy traversal. External writes to
+`GlobalTransform` trigger reconciliation; the owner's own publications are
+consumed before returning. `Children` remains a read-only relationship projection;
+there is no duplicate Scene graph or per-node matrix cache.
 
 Removing `ChildOf` is a structural root transition. Even when the authored
 `Transform` is unchanged, the next propagation composes and publishes that

package/dist/__tests__/hierarchy-dirty.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hierarchy-dirty.unit.test.d.ts.map

package/dist/__tests__/hierarchy-dirty.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-dirty.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/hierarchy-dirty.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/sparse-global-observation.contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sparse-global-observation.contract.test.d.ts.map

package/dist/__tests__/sparse-global-observation.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparse-global-observation.contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/sparse-global-observation.contract.test.ts"],"names":[],"mappings":""}

package/dist/index.mjs

@@ -1897,6 +1897,9 @@ function ensureQueries(world, scratch) {
     without: [ChildOf],
     changed: [Transform]
   });
+  scratch.dirtyTransforms ??= world.query({ read: [Transform], changed: [Transform] }).unwrap();
+  scratch.dirtyParents ??= world.query({ read: [ChildOf], changed: [ChildOf] }).unwrap();
+  scratch.dirtyGlobals ??= world.query({ read: [GlobalTransform], changed: [GlobalTransform] }).unwrap();
   const hierarchy = world.query({ read: [Transform, ChildOf], write: [GlobalTransform] });
   const transform = world.query({ read: [Transform], write: [GlobalTransform] });
   const missingGlobal = world.query({ with: [Transform], without: [GlobalTransform] });
@@ -1960,7 +1963,8 @@ function scratchFor(world) {
     flatChanged: [],
     flatBindingTables: [],
     flatBindingRows: [],
-    flatStructureEpoch: -1
+    flatStructureEpoch: -1,
+    hierarchyStructureEpoch: -1
   };
   SCRATCH.set(world, created);
   return created;
@@ -2249,7 +2253,7 @@ function handleActiveCycle(repeated, stackEntities, stackChildren, writer, bindi
     stackChildren[index] = 0;
   }
 }
-function walkChildren(world, root, writer, bindings, transformWriter, transformBindings, scratch, report, allowCompletedRoot) {
+function walkChildren(world, root, writer, bindings, transformWriter, transformBindings, scratch, report, allowCompletedRoot, refresh = false) {
   countPropagation("hierarchyRootInvocations");
   const stackEntities = scratch.hierarchyStackEntities;
   const stackChildren = scratch.hierarchyStackChildren;
@@ -2268,7 +2272,7 @@ function walkChildren(world, root, writer, bindings, transformWriter, transformB
     const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
     if (rootBinding !== void 0) {
       const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
-      if (state !== 0) return;
+      if (state !== 0 && !refresh) return;
     }
   }
   stackEntities.push(root);
@@ -2288,6 +2292,10 @@ function walkChildren(world, root, writer, bindings, transformWriter, transformB
     const nextChild = stackChildren[top] ?? -1;
     if (nextChild < 0) {
       if (hierarchyBinding !== void 0) {
+        if (refresh) {
+          const states = scratch.hierarchyStates[currentCursor.bindingIndex];
+          if (states !== void 0) states[currentCursor.row] = 0;
+        }
         const state = scratch.hierarchyStates[currentCursor.bindingIndex]?.[currentCursor.row] ?? 0;
         if (state === 0) {
           const states = scratch.hierarchyStates[currentCursor.bindingIndex];
@@ -2465,7 +2473,7 @@ function walkChildren(world, root, writer, bindings, transformWriter, transformB
         scratch.hierarchyChanged,
         report
       );
-    } else if (childState === 0) {
+    } else if (childState === 0 || refresh) {
       stackEntities.push(child);
       stackChildren.push(-1);
     }
@@ -2620,7 +2628,7 @@ function resolveResidualPath(world, entity, writer, bindings, transformWriter, t
     return;
   }
 }
-function propagateHierarchy(world, scratch) {
+function propagateHierarchy(world, scratch, globalEdited) {
   const hierarchyWriter = scratch.hierarchyWriter;
   const transformWriter = scratch.transformWriter;
   if (hierarchyWriter === void 0 || transformWriter === void 0) {
@@ -2639,20 +2647,34 @@ function propagateHierarchy(world, scratch) {
     scratch.hierarchyBindingRows.length = 0;
     scratch.hierarchyStates.length = 0;
     scratch.hierarchyChanged.length = 0;
+    scratch.hierarchyStructureEpoch = world.getStructureEpoch();
     return ok6(void 0);
   }
+  const dirty = /* @__PURE__ */ new Set();
+  for (const row of scratch.dirtyTransforms ?? []) dirty.add(row.entity);
+  let rebuild = scratch.hierarchyStructureEpoch !== world.getStructureEpoch();
+  for (const _row of scratch.dirtyParents ?? []) rebuild = true;
+  rebuild ||= globalEdited;
+  if (!rebuild && dirty.size === 0) return ok6(void 0);
   ensureHierarchyBuffers(scratch, hierarchyBindings);
-  resetHierarchyBuffers(scratch);
+  if (rebuild) resetHierarchyBuffers(scratch);
+  else for (const changed of scratch.hierarchyChanged) changed.fill(0);
   let firstError;
   const report = (error) => {
     firstError = noteHierarchyError(firstError, error);
   };
-  for (const binding of transformBindings) {
-    const entities = binding.entities;
-    for (let row = 0; row < binding.rowCapacity; row += 1) {
-      const entity = entities[row] ?? 0;
-      const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, "parent");
-      if (parentRaw === void 0 || parentRaw === ENTITY_NULL_RAW2) {
+  if (!rebuild) {
+    for (const entity of dirty) {
+      let parent = world[worldRead].getFieldValue(entity, ChildOf, "parent");
+      let covered = false;
+      while (parent !== void 0 && parent !== ENTITY_NULL_RAW2) {
+        if (dirty.has(parent)) {
+          covered = true;
+          break;
+        }
+        parent = world[worldRead].getFieldValue(parent, ChildOf, "parent");
+      }
+      if (!covered)
         walkChildren(
           world,
           entity,
@@ -2662,29 +2684,50 @@ function propagateHierarchy(world, scratch) {
           transformBindings,
           scratch,
           report,
-          false
+          false,
+          true
         );
+    }
+  } else {
+    for (const binding of transformBindings) {
+      const entities = binding.entities;
+      for (let row = 0; row < binding.rowCapacity; row += 1) {
+        const entity = entities[row] ?? 0;
+        const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, "parent");
+        if (parentRaw === void 0 || parentRaw === ENTITY_NULL_RAW2) {
+          walkChildren(
+            world,
+            entity,
+            hierarchyWriter,
+            hierarchyBindings,
+            transformWriter,
+            transformBindings,
+            scratch,
+            report,
+            false
+          );
+        }
       }
     }
-  }
-  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
-    const binding = hierarchyBindings[bindingIndex];
-    if (binding === void 0) continue;
-    const entities = binding.entities;
-    const states = scratch.hierarchyStates[bindingIndex];
-    for (let row = 0; row < binding.rowCapacity; row += 1) {
-      if ((states?.[row] ?? 0) !== 0) continue;
-      const entity = entities[row] ?? 0;
-      resolveResidualPath(
-        world,
-        entity,
-        hierarchyWriter,
-        hierarchyBindings,
-        transformWriter,
-        transformBindings,
-        scratch,
-        report
-      );
+    for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+      const binding = hierarchyBindings[bindingIndex];
+      if (binding === void 0) continue;
+      const entities = binding.entities;
+      const states = scratch.hierarchyStates[bindingIndex];
+      for (let row = 0; row < binding.rowCapacity; row += 1) {
+        if ((states?.[row] ?? 0) !== 0) continue;
+        const entity = entities[row] ?? 0;
+        resolveResidualPath(
+          world,
+          entity,
+          hierarchyWriter,
+          hierarchyBindings,
+          transformWriter,
+          transformBindings,
+          scratch,
+          report
+        );
+      }
     }
   }
   for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
@@ -2697,15 +2740,21 @@ function propagateHierarchy(world, scratch) {
       report(derivedWriteError(cause, bindingIndex));
     }
   }
+  scratch.hierarchyStructureEpoch = firstError === void 0 ? world.getStructureEpoch() : -1;
   return firstError === void 0 ? ok6(void 0) : err6(firstError);
 }
 function propagateTransforms(world) {
   const scratch = scratchFor(world);
   const pairs = validateTransformPairs(world, scratch);
   if (!pairs.ok) return pairs;
+  let globalEdited = false;
+  for (const _span of scratch.dirtyGlobals?.spans().unwrap() ?? []) globalEdited = true;
   const flat = propagateFlat(world, scratch);
   if (!flat.ok) return flat;
-  return propagateHierarchy(world, scratch);
+  const hierarchy = propagateHierarchy(world, scratch, globalEdited);
+  for (const _span of scratch.dirtyGlobals?.spans().unwrap() ?? []) {
+  }
+  return hierarchy;
 }
 var PropagateTransforms = defineSystem({
   name: PROPAGATE_TRANSFORMS_SYSTEM,