@forgeax/engine-scene 0.1.33 → 0.1.34

package/dist/systems/propagate-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"propagate-transforms.d.ts","sourceRoot":"","sources":["../../src/systems/propagate-transforms.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,YAAY,EAEjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAS7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,eAAO,MAAM,2BAA2B,EAAG,qBAA8B,CAAC;AAC1E,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AACrF,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,iBAAiB,yCAA+C,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;IAClC,8BAA8B,EAAE,MAAM,CAAC;IACvC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,6BAA6B,EAAE,MAAM,CAAC;IACtC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAWD,wBAAgB,8BAA8B,IAAI,IAAI,CAcrD;AAED,wBAAgB,4BAA4B,IAAI,yBAAyB,CAsBxE;AAklCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAO1E;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,SAAS,EAAE,CAOxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,SAAS,EAAE,CAI7D,CAAC;AAEH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,IAAI,CA8CZ"}
+{"version":3,"file":"propagate-transforms.d.ts","sourceRoot":"","sources":["../../src/systems/propagate-transforms.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,YAAY,EAEjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAS7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,eAAO,MAAM,2BAA2B,EAAG,qBAA8B,CAAC;AAC1E,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AACrF,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,iBAAiB,yCAA+C,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;IAClC,8BAA8B,EAAE,MAAM,CAAC;IACvC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,6BAA6B,EAAE,MAAM,CAAC;IACtC,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAWD,wBAAgB,8BAA8B,IAAI,IAAI,CAcrD;AAED,wBAAgB,4BAA4B,IAAI,yBAAyB,CAsBxE;AA2oCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAc1E;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,SAAS,EAAE,CAOxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,SAAS,EAAE,CAI7D,CAAC;AAEH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,IAAI,CA8CZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-scene",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,10 +22,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.33",
-    "@forgeax/engine-math": "0.1.33",
-    "@forgeax/engine-plugin": "0.1.33",
-    "@forgeax/engine-types": "0.1.33"
+    "@forgeax/engine-ecs": "0.1.34",
+    "@forgeax/engine-math": "0.1.34",
+    "@forgeax/engine-plugin": "0.1.34",
+    "@forgeax/engine-types": "0.1.34"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/flat-propagation.contract.test.ts

@@ -100,7 +100,9 @@ describe('flat Transform propagation contract', () => {
 
   it('does not retain an entity collection or a second lane in the flat owner', async () => {
     const source = readFileSync('packages/scene/src/systems/propagate-transforms.ts', 'utf8');
-    expect(source).not.toMatch(/new (Map|Set)|\b(Map|Set)</);
+    expect(source.slice(0, source.indexOf('function walkChildren('))).not.toMatch(
+      /new (Map|Set)|\b(Map|Set)</,
+    );
     expect(source).not.toMatch(/PropagationCache/);
     expect(source).toContain('changed: [Transform]');
     expect(source).toContain('composeFlatColumns');

package/src/__tests__/flat-propagation.perf.test.ts

@@ -332,6 +332,8 @@ describe('real ECS flat Transform propagation benchmark', () => {
     ).toBe(true);
 
     const source = readFileSync('packages/scene/src/systems/propagate-transforms.ts', 'utf8');
-    expect(source).not.toMatch(/new (Map|Set)|\\b(Map|Set)</);
+    expect(source.slice(0, source.indexOf('function walkChildren('))).not.toMatch(
+      /new (Map|Set)|\\b(Map|Set)</,
+    );
   }, 120_000);
 });

package/src/__tests__/hierarchy-dirty.unit.test.ts

@@ -0,0 +1,68 @@
+import { FixedUpdate, World } from '@forgeax/engine-ecs';
+import { expect, it } from 'vitest';
+import { ChildOf } from '../components/child-of';
+import { GlobalTransform, Transform } from '../components/transform';
+import {
+  beginTransformPropagationTrace,
+  endTransformPropagationTrace,
+  propagateTransforms,
+  registerPropagateTransforms,
+} from '../systems/propagate-transforms';
+
+it('skips clean hierarchies and evaluates only the highest dirty subtrees', () => {
+  const world = new World();
+  const root = world.spawn({ component: Transform, data: { pos: [1, 0, 0] } }).unwrap();
+  const child = world
+    .spawn(
+      { component: Transform, data: { pos: [2, 0, 0] } },
+      { component: ChildOf, data: { parent: root } },
+    )
+    .unwrap();
+  const leaf = world
+    .spawn(
+      { component: Transform, data: { pos: [3, 0, 0] } },
+      { component: ChildOf, data: { parent: child } },
+    )
+    .unwrap();
+  const sibling = world
+    .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: root } })
+    .unwrap();
+  propagateTransforms(world).unwrap();
+  beginTransformPropagationTrace();
+  propagateTransforms(world).unwrap();
+  expect(endTransformPropagationTrace().hierarchyEntityLookups).toBe(0);
+  world.set(child, Transform, { pos: [4, 0, 0] }).unwrap();
+  world.set(leaf, Transform, { pos: [5, 0, 0] }).unwrap();
+  beginTransformPropagationTrace();
+  propagateTransforms(world).unwrap();
+  expect(endTransformPropagationTrace().hierarchyRowsEvaluated).toBe(2);
+  expect(world.get(leaf, GlobalTransform).unwrap().world[12]).toBe(10);
+  world.set(child, ChildOf, { parent: sibling }).unwrap();
+  propagateTransforms(world).unwrap();
+  expect(world.get(leaf, GlobalTransform).unwrap().world[12]).toBe(10);
+});
+
+it('does not repeat FixedUpdate propagation in Update without another local write', () => {
+  const world = new World({ time: { fixedDeltaSeconds: 1 / 60 } });
+  const root = world.spawn({ component: Transform, data: {} }).unwrap();
+  const child = world
+    .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: root } })
+    .unwrap();
+  registerPropagateTransforms(world);
+  world.update(0).unwrap();
+  world
+    .addSystem(FixedUpdate, {
+      name: 'write-local',
+      queries: [],
+      before: ['propagateTransformsFixed'],
+      fn: () => {
+        world.set(root, Transform, { pos: [3, 0, 0] }).unwrap();
+      },
+    })
+    .unwrap();
+  beginTransformPropagationTrace();
+  world.update(1 / 60).unwrap();
+  const trace = endTransformPropagationTrace();
+  expect(trace.hierarchyRowsEvaluated).toBe(1);
+  expect(world.get(child, GlobalTransform).unwrap().world[12]).toBe(3);
+});

package/src/__tests__/propagation.unit.test.ts

@@ -230,6 +230,10 @@ describe('scene propagation', () => {
     }
     propagateTransforms(world).unwrap();
 
+    for (const row of world.query({ write: [Transform] }).unwrap()) {
+      const pos = row.mut(Transform).pos;
+      pos[0] = (pos[0] ?? 0) + 1;
+    }
     beginTransformPropagationTrace();
     propagateTransforms(world).unwrap();
     const trace = endTransformPropagationTrace();

package/src/__tests__/transform-carrier-prototype.bench.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 const SEED = 20260901;
-const FRAME_COUNT = 300;
+const FRAME_COUNT = 60;
 const processLike = (
   globalThis as typeof globalThis & {
     process?: { memoryUsage(): { heapUsed: number }; env?: Record<string, string | undefined> };
@@ -86,7 +86,7 @@ function runCandidate(candidateId: CandidateId, workload: Workload): CandidateRe
     checksum = (checksum + Math.round(frameChecksum * 1000) + SEED + frame) >>> 0;
     queryMs += performance.now() - queryStart;
 
-    if (workload.workloadId === 'structural-churn' && frame % 30 === 0) {
+    if (workload.workloadId === 'structural-churn' && frame % (FRAME_COUNT / 10) === 0) {
       const recycled = (frame * 97) % workload.rows;
       local[recycled] = frame + 1;
       world[recycled] = local[recycled] * 2;

package/src/__tests__/transform-carrier-prototype.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { ChildOf } from '../index';
 
 const SEED = 20260901;
-const FRAME_COUNT = 300;
+const FRAME_COUNT = 60;
 const PROTOTYPE_ROWS = 64;
 
 const BCarrier = defineComponent('PrototypeBCarrier', { local: 'f32', world: 'f32' });

package/src/systems/propagate-transforms.ts

@@ -127,6 +127,10 @@ interface Scratch {
   flatBindingTables: number[];
   flatBindingRows: number[];
   flatStructureEpoch: number;
+  hierarchyStructureEpoch: number;
+  dirtyTransforms?: Query<readonly [typeof Transform]>;
+  dirtyParents?: Query<readonly [typeof ChildOf]>;
+  dirtyGlobals?: Query<readonly [typeof GlobalTransform]>;
   flatQuery?: FlatQuery;
   hierarchyQuery?: HierarchyQuery;
   transformQuery?: TransformQuery;
@@ -191,6 +195,11 @@ function ensureQueries(world: World, scratch: Scratch): Result<void, SceneError>
     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] });
@@ -263,6 +272,7 @@ function scratchFor(world: World): Scratch {
     flatBindingTables: [],
     flatBindingRows: [],
     flatStructureEpoch: -1,
+    hierarchyStructureEpoch: -1,
   };
   SCRATCH.set(world, created);
   return created;
@@ -679,6 +689,7 @@ function walkChildren(
   scratch: Scratch,
   report: (error: SceneError) => void,
   allowCompletedRoot: boolean,
+  refresh = false,
 ): void {
   countPropagation('hierarchyRootInvocations');
   const stackEntities = scratch.hierarchyStackEntities;
@@ -706,7 +717,7 @@ function walkChildren(
     const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
     if (rootBinding !== undefined) {
       const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
-      if (state !== 0) return;
+      if (state !== 0 && !refresh) return;
     }
   }
   stackEntities.push(root);
@@ -727,6 +738,10 @@ function walkChildren(
     const nextChild = stackChildren[top] ?? -1;
     if (nextChild < 0) {
       if (hierarchyBinding !== undefined) {
+        if (refresh) {
+          const states = scratch.hierarchyStates[currentCursor.bindingIndex];
+          if (states !== undefined) states[currentCursor.row] = 0;
+        }
         const state = scratch.hierarchyStates[currentCursor.bindingIndex]?.[currentCursor.row] ?? 0;
         if (state === 0) {
           const states = scratch.hierarchyStates[currentCursor.bindingIndex];
@@ -914,7 +929,7 @@ function walkChildren(
         scratch.hierarchyChanged,
         report,
       );
-    } else if (childState === 0) {
+    } else if (childState === 0 || refresh) {
       stackEntities.push(child);
       stackChildren.push(-1);
     }
@@ -1106,7 +1121,11 @@ function resolveResidualPath(
   }
 }
 
-function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneError> {
+function propagateHierarchy(
+  world: World,
+  scratch: Scratch,
+  globalEdited: boolean,
+): Result<void, SceneError> {
   const hierarchyWriter = scratch.hierarchyWriter;
   const transformWriter = scratch.transformWriter;
   if (hierarchyWriter === undefined || transformWriter === undefined) {
@@ -1128,25 +1147,37 @@ function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneE
     scratch.hierarchyBindingRows.length = 0;
     scratch.hierarchyStates.length = 0;
     scratch.hierarchyChanged.length = 0;
+    scratch.hierarchyStructureEpoch = world.getStructureEpoch();
     return ok(undefined);
   }
+  const dirty = new Set<EntityHandle>();
+  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 ok(undefined);
   ensureHierarchyBuffers(scratch, hierarchyBindings);
-  resetHierarchyBuffers(scratch);
+  if (rebuild) resetHierarchyBuffers(scratch);
+  else for (const changed of scratch.hierarchyChanged) changed.fill(0);
   let firstError: SceneError | undefined;
   const report = (error: SceneError): void => {
     firstError = noteHierarchyError(firstError, error);
   };
 
-  // Start only at actual roots (flat Transform rows and null-parent
-  // ChildOf rows). Descendants are discovered exclusively through the ECS
-  // materialized Children lists, so every normal frame is parent-first and
-  // linear in rows plus relationship edges.
-  for (const binding of transformBindings) {
-    const entities = binding.entities;
-    for (let row = 0; row < binding.rowCapacity; row += 1) {
-      const entity = (entities[row] ?? 0) as EntityHandle;
-      const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, 'parent');
-      if (parentRaw === undefined || parentRaw === ENTITY_NULL_RAW) {
+  if (!rebuild) {
+    // The previous successful structural pass proved the parent graph. Only
+    // highest dirty ancestors need execution; clean parents retain valid worlds.
+    for (const entity of dirty) {
+      let parent = world[worldRead].getFieldValue(entity, ChildOf, 'parent');
+      let covered = false;
+      while (parent !== undefined && parent !== ENTITY_NULL_RAW) {
+        if (dirty.has(parent as EntityHandle)) {
+          covered = true;
+          break;
+        }
+        parent = world[worldRead].getFieldValue(parent as EntityHandle, ChildOf, 'parent');
+      }
+      if (!covered)
         walkChildren(
           world,
           entity,
@@ -1157,35 +1188,60 @@ function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneE
           scratch,
           report,
           false,
+          true,
         );
+    }
+  } else {
+    // Start only at actual roots (flat Transform rows and null-parent
+    // ChildOf rows). Descendants are discovered exclusively through the ECS
+    // materialized Children lists, so every normal frame is parent-first and
+    // linear in rows plus relationship edges.
+    for (const binding of transformBindings) {
+      const entities = binding.entities;
+      for (let row = 0; row < binding.rowCapacity; row += 1) {
+        const entity = (entities[row] ?? 0) as EntityHandle;
+        const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, 'parent');
+        if (parentRaw === undefined || parentRaw === ENTITY_NULL_RAW) {
+          walkChildren(
+            world,
+            entity,
+            hierarchyWriter,
+            hierarchyBindings,
+            transformWriter,
+            transformBindings,
+            scratch,
+            report,
+            false,
+          );
+        }
       }
     }
-  }
 
-  // Any remaining hierarchy row is either behind a malformed/missing mirror
-  // edge or belongs to a rootless cycle. Follow each residual parent chain
-  // once with the same row-state machine (not a per-node parent search), then
-  // cut that complete residual path to local space. This keeps malformed
-  // coverage linear in residual rows and edges while normal frames remain
-  // exclusively Children-driven.
-  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
-    const binding = hierarchyBindings[bindingIndex];
-    if (binding === undefined) 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) as EntityHandle;
-      resolveResidualPath(
-        world,
-        entity,
-        hierarchyWriter,
-        hierarchyBindings,
-        transformWriter,
-        transformBindings,
-        scratch,
-        report,
-      );
+    // Any remaining hierarchy row is either behind a malformed/missing mirror
+    // edge or belongs to a rootless cycle. Follow each residual parent chain
+    // once with the same row-state machine (not a per-node parent search), then
+    // cut that complete residual path to local space. This keeps malformed
+    // coverage linear in residual rows and edges while normal frames remain
+    // exclusively Children-driven.
+    for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+      const binding = hierarchyBindings[bindingIndex];
+      if (binding === undefined) 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) as EntityHandle;
+        resolveResidualPath(
+          world,
+          entity,
+          hierarchyWriter,
+          hierarchyBindings,
+          transformWriter,
+          transformBindings,
+          scratch,
+          report,
+        );
+      }
     }
   }
 
@@ -1199,6 +1255,7 @@ function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneE
       report(derivedWriteError(cause, bindingIndex));
     }
   }
+  scratch.hierarchyStructureEpoch = firstError === undefined ? world.getStructureEpoch() : -1;
   return firstError === undefined ? ok(undefined) : err(firstError);
 }
 
@@ -1206,9 +1263,16 @@ export function propagateTransforms(world: World): Result<void, SceneError> {
   const scratch = scratchFor(world);
   const pairs = validateTransformPairs(world, scratch);
   if (!pairs.ok) return pairs;
+  let globalEdited = false;
+  for (const _row of scratch.dirtyGlobals ?? []) globalEdited = true;
   const flat = propagateFlat(world, scratch);
   if (!flat.ok) return flat;
-  return propagateHierarchy(world, scratch);
+  const hierarchy = propagateHierarchy(world, scratch, globalEdited);
+  // Consume our own derived publications, while preserving later external edits.
+  for (const _row of scratch.dirtyGlobals ?? []) {
+    /* observation only */
+  }
+  return hierarchy;
 }
 
 export const PropagateTransforms: SystemHandle<readonly []> = defineSystem({