@forgeax/engine-scene 0.1.20 → 0.1.23

package/src/systems/propagate-transforms.ts

@@ -1,313 +1,443 @@
 import {
   defineSystem,
   defineSystemSet,
+  type EcsError,
   type EntityHandle,
   FixedUpdate,
+  type Query,
   type SystemHandle,
   Update,
   type World,
 } from '@forgeax/engine-ecs';
-import {
-  createWorldProjection,
-  setDerivedComponent,
-  type WorldProjection,
-} from '@forgeax/engine-ecs/projection';
 import { type Mat4, mat4 } from '@forgeax/engine-math';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { ChildOf } from '../components/child-of';
-import { Transform } from '../components/transform';
+import { GlobalTransform, Transform } from '../components/transform';
 import { SceneError } from '../errors';
-import { projectHierarchy, type SceneHierarchySnapshot } from './hierarchy-projection';
 
 export const PROPAGATE_TRANSFORMS_SYSTEM = 'propagateTransforms' as const;
 export const PROPAGATE_TRANSFORMS_FIXED_SYSTEM = 'propagateTransformsFixed' as const;
 export const TransformSet = defineSystemSet({ name: 'transform' });
 export const TransformFixedSet = defineSystemSet({ name: 'transform-fixed' });
 
-interface LocalState {
-  readonly pos: Float32Array;
-  readonly quat: Float32Array;
-  readonly scale: Float32Array;
-}
-
-interface PropagationCache {
-  readonly projection: WorldProjection;
-  readonly hierarchy: SceneHierarchySnapshot;
-  readonly parentOf: ReadonlyMap<EntityHandle, EntityHandle>;
-  readonly childrenOf: ReadonlyMap<EntityHandle, readonly EntityHandle[]>;
-  readonly entities: ReadonlySet<EntityHandle>;
-  readonly locals: Map<EntityHandle, LocalState>;
-  readonly derived: Map<EntityHandle, Float32Array>;
-  result: Result<void, SceneError>;
+interface Scratch {
+  position: Float32Array;
+  rotation: Float32Array;
+  scale: Float32Array;
+  local: Mat4;
+  hierarchyPath: number[];
+  flatQuery?: FlatQuery;
+  outputQuery?: OutputQuery;
+  hierarchyQuery?: HierarchyQuery;
+  missingGlobalQuery?: MissingGlobalQuery;
+  missingTransformQuery?: MissingTransformQuery;
 }
 
-const CACHE = new WeakMap<World, PropagationCache>();
+type OutputQuery = Query<readonly [], readonly [typeof GlobalTransform]>;
+type FlatQuery = Query<readonly [typeof Transform], readonly [typeof GlobalTransform]>;
+type HierarchyQuery = Query<readonly [typeof Transform, typeof ChildOf]>;
+type MissingGlobalQuery = Query<readonly [], readonly [], readonly []>;
+type MissingTransformQuery = Query<readonly [], readonly [], readonly []>;
 
-interface TransformRegistrationLease {
+interface RegistrationLease {
   refs: number;
 }
 
-// A World can be consumed by more than one renderer/view. Keep the schedule
-// registration leased per World so one owner disposing cannot remove the
-// shared transform system from another owner. This is lifecycle bookkeeping,
-// not a second component/system authority; the World schedule remains the
-// source of truth.
-const REGISTRATION_LEASES = new WeakMap<World, TransformRegistrationLease>();
-
-function copyState(value: {
-  readonly pos: ArrayLike<number>;
-  readonly quat: ArrayLike<number>;
-  readonly scale: ArrayLike<number>;
-}): LocalState {
-  return {
-    pos: new Float32Array(value.pos),
-    quat: new Float32Array(value.quat),
-    scale: new Float32Array(value.scale),
-  };
-}
-
-function sameArray(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
-  if (left.length !== right.length) return false;
-  for (let index = 0; index < left.length; index += 1) {
-    if (left[index] !== right[index]) return false;
-  }
-  return true;
-}
+const SCRATCH = new WeakMap<World, Scratch>();
+const REGISTRATION_LEASES = new WeakMap<World, RegistrationLease>();
 
-function sameState(left: LocalState | undefined, right: LocalState): boolean {
-  return (
-    left !== undefined &&
-    sameArray(left.pos, right.pos) &&
-    sameArray(left.quat, right.quat) &&
-    sameArray(left.scale, right.scale)
+function pairError(entity: EntityHandle, expected: string): Result<void, SceneError> {
+  return err(
+    new SceneError({
+      code: 'hierarchy-broken',
+      expected,
+      hint: 'attach both Transform and GlobalTransform at scene authoring or import time, then retry propagation',
+      detail: { entity, parent: entity },
+    }),
   );
 }
 
-function compose(state: LocalState, out: Mat4): void {
-  mat4.compose(out, state.pos, state.quat, state.scale);
+function ensureQueries(world: World, scratch: Scratch): Result<void, SceneError> {
+  if (
+    scratch.flatQuery !== undefined &&
+    scratch.outputQuery !== undefined &&
+    scratch.hierarchyQuery !== undefined &&
+    scratch.missingGlobalQuery !== undefined &&
+    scratch.missingTransformQuery !== undefined
+  ) {
+    return ok(undefined);
+  }
+  const flatOutput = world.query({
+    read: [Transform],
+    write: [GlobalTransform],
+    without: [ChildOf],
+    changed: [Transform],
+  });
+  const output = world.query({ write: [GlobalTransform] });
+  const hierarchy = world.query({ read: [Transform, ChildOf] });
+  const missingGlobal = world.query({ with: [Transform], without: [GlobalTransform] });
+  const missingTransform = world.query({ with: [GlobalTransform], without: [Transform] });
+  if (!flatOutput.ok || !output.ok || !hierarchy.ok || !missingGlobal.ok || !missingTransform.ok) {
+    return pairError(0 as EntityHandle, 'valid Transform and GlobalTransform pair queries');
+  }
+  scratch.flatQuery = flatOutput.value as FlatQuery;
+  scratch.outputQuery = output.value as OutputQuery;
+  scratch.hierarchyQuery = hierarchy.value as HierarchyQuery;
+  scratch.missingGlobalQuery = missingGlobal.value as MissingGlobalQuery;
+  scratch.missingTransformQuery = missingTransform.value as MissingTransformQuery;
+  return ok(undefined);
 }
 
-function indexChildren(
-  hierarchy: SceneHierarchySnapshot,
-): ReadonlyMap<EntityHandle, readonly EntityHandle[]> {
-  const childrenOf = new Map<EntityHandle, EntityHandle[]>();
-  for (const [child, parent] of hierarchy.parentOf) {
-    const children = childrenOf.get(parent);
-    if (children === undefined) childrenOf.set(parent, [child]);
-    else children.push(child);
+function validateTransformPairs(world: World, scratch: Scratch): Result<void, SceneError> {
+  const queryResult = ensureQueries(world, scratch);
+  if (!queryResult.ok) return queryResult;
+  const missingGlobal = scratch.missingGlobalQuery;
+  const missingTransform = scratch.missingTransformQuery;
+  if (missingGlobal === undefined || missingTransform === undefined) {
+    return pairError(0 as EntityHandle, 'valid Transform and GlobalTransform pair queries');
+  }
+  for (const row of missingGlobal) {
+    return pairError(row.entity, 'each Transform entity to carry a GlobalTransform pair');
   }
-  return childrenOf;
+  for (const row of missingTransform) {
+    return pairError(row.entity, 'each GlobalTransform entity to carry a Transform pair');
+  }
+  return ok(undefined);
 }
 
-function descendants(
-  childrenOf: ReadonlyMap<EntityHandle, readonly EntityHandle[]>,
-  roots: ReadonlySet<EntityHandle>,
-): Set<EntityHandle> {
-  const affected = new Set(roots);
-  const pending = [...roots];
-  for (let index = 0; index < pending.length; index += 1) {
-    const parent = pending[index];
-    if (parent === undefined) continue;
-    for (const child of childrenOf.get(parent) ?? []) {
-      if (affected.has(child)) continue;
-      affected.add(child);
-      pending.push(child);
-    }
-  }
-  return affected;
+function scratchFor(world: World): Scratch {
+  const existing = SCRATCH.get(world);
+  if (existing !== undefined) return existing;
+  const created = {
+    position: new Float32Array(3),
+    rotation: new Float32Array(4),
+    scale: new Float32Array(3),
+    local: mat4.create(),
+    hierarchyPath: [] as number[],
+  };
+  SCRATCH.set(world, created);
+  return created;
 }
 
-function hierarchyError(hierarchy: SceneHierarchySnapshot): Result<void, SceneError> {
-  const first = hierarchy.diagnostics[0];
-  if (first === undefined) return ok(undefined);
-  return err(
-    new SceneError({
-      code: first.code,
-      expected: first.expected,
-      hint: first.hint,
-      detail: first.detail,
-    }),
-  );
+function composeColumns(
+  position: ArrayLike<number>,
+  rotation: ArrayLike<number>,
+  scale: ArrayLike<number>,
+  out: Mat4,
+  scratch: Scratch,
+  positionStart = 0,
+  rotationStart = 0,
+): void {
+  scratch.position[0] = position[positionStart] ?? 0;
+  scratch.position[1] = position[positionStart + 1] ?? 0;
+  scratch.position[2] = position[positionStart + 2] ?? 0;
+  scratch.rotation[0] = rotation[rotationStart] ?? 0;
+  scratch.rotation[1] = rotation[rotationStart + 1] ?? 0;
+  scratch.rotation[2] = rotation[rotationStart + 2] ?? 0;
+  scratch.rotation[3] = rotation[rotationStart + 3] ?? 1;
+  scratch.scale[0] = scale[positionStart] ?? 1;
+  scratch.scale[1] = scale[positionStart + 1] ?? 1;
+  scratch.scale[2] = scale[positionStart + 2] ?? 1;
+  mat4.compose(out, scratch.position, scratch.rotation, scratch.scale);
 }
 
-function buildCache(world: World, projection: WorldProjection): PropagationCache {
-  const hierarchy = projectHierarchy(world);
-  const locals = new Map<EntityHandle, LocalState>();
-  const entities = new Set<EntityHandle>();
-  const query = world.query({ read: [Transform], optional: [ChildOf] });
-  if (query.ok) {
-    for (const row of query.value) {
-      const transform = row.get(Transform);
-      if (transform === undefined) continue;
-      entities.add(row.entity);
-      locals.set(row.entity, copyState(transform));
-    }
+function composeFlatColumns(
+  positions: ArrayLike<number>,
+  rotations: ArrayLike<number>,
+  scales: ArrayLike<number>,
+  worlds: Float32Array,
+  count: number,
+): void {
+  for (let row = 0; row < count; row += 1) {
+    const position = row * 3;
+    const rotation = row * 4;
+    const world = row * 16;
+    const x = rotations[rotation] ?? 0;
+    const y = rotations[rotation + 1] ?? 0;
+    const z = rotations[rotation + 2] ?? 0;
+    const w = rotations[rotation + 3] ?? 1;
+    const x2 = x + x;
+    const y2 = y + y;
+    const z2 = z + z;
+    const xx = x * x2;
+    const xy = x * y2;
+    const xz = x * z2;
+    const yy = y * y2;
+    const yz = y * z2;
+    const zz = z * z2;
+    const wx = w * x2;
+    const wy = w * y2;
+    const wz = w * z2;
+    const sx = scales[position] ?? 1;
+    const sy = scales[position + 1] ?? 1;
+    const sz = scales[position + 2] ?? 1;
+
+    worlds[world] = (1 - (yy + zz)) * sx;
+    worlds[world + 1] = (xy + wz) * sx;
+    worlds[world + 2] = (xz - wy) * sx;
+    worlds[world + 3] = 0;
+    worlds[world + 4] = (xy - wz) * sy;
+    worlds[world + 5] = (1 - (xx + zz)) * sy;
+    worlds[world + 6] = (yz + wx) * sy;
+    worlds[world + 7] = 0;
+    worlds[world + 8] = (xz + wy) * sz;
+    worlds[world + 9] = (yz - wx) * sz;
+    worlds[world + 10] = (1 - (xx + yy)) * sz;
+    worlds[world + 11] = 0;
+    worlds[world + 12] = positions[position] ?? 0;
+    worlds[world + 13] = positions[position + 1] ?? 0;
+    worlds[world + 14] = positions[position + 2] ?? 0;
+    worlds[world + 15] = 1;
   }
-  return {
-    projection,
-    hierarchy,
-    parentOf: hierarchy.parentOf,
-    childrenOf: indexChildren(hierarchy),
-    entities,
-    locals,
-    derived: new Map(),
-    result: ok(undefined),
-  };
 }
 
-function deriveEntity(
+function writeWorld(
   world: World,
+  output: ReturnType<World['query']> extends Result<infer Q, unknown> ? Q : never,
   entity: EntityHandle,
-  cache: PropagationCache,
-  affected: ReadonlySet<EntityHandle>,
-  visiting: Set<EntityHandle>,
-  published: Set<EntityHandle>,
+  value: Mat4,
 ): Result<void, SceneError> {
-  if (!affected.has(entity) || cache.derived.has(entity)) return ok(undefined);
-  if (visiting.has(entity)) return ok(undefined);
-  visiting.add(entity);
-  const local = cache.locals.get(entity);
-  if (local === undefined) {
-    visiting.delete(entity);
-    return ok(undefined);
-  }
-  const parent = cache.parentOf.get(entity);
-  if (parent !== undefined && cache.entities.has(parent)) {
-    const parentResult = deriveEntity(world, parent, cache, affected, visiting, published);
-    if (!parentResult.ok) return parentResult;
+  const row = output.at(entity);
+  if (row === undefined) {
+    return err(
+      new SceneError({
+        code: 'hierarchy-broken',
+        expected: 'each Transform entity to carry a GlobalTransform pair',
+        hint: 'attach GlobalTransform at scene authoring or import time, then retry propagation',
+        detail: { entity, parent: entity },
+      }),
+    );
   }
-  const localWorld = mat4.create();
-  compose(local, localWorld);
-  const parentWorld = parent === undefined ? undefined : cache.derived.get(parent);
-  const resolved = mat4.create();
-  if (parentWorld === undefined) resolved.set(localWorld);
-  else mat4.multiply(resolved, parentWorld, localWorld);
-  const write = setDerivedComponent(world, entity, Transform, { world: resolved });
-  if (!write.ok) {
-    visiting.delete(entity);
+  const current = world.get(entity, GlobalTransform);
+  if (!current.ok)
     return err(
       new SceneError({
         code: 'hierarchy-broken',
-        expected: 'the derived Transform.world write to succeed',
-        hint: 'inspect the ECS mutation error before retrying transform propagation',
+        expected: 'each Transform entity to carry a GlobalTransform pair',
+        hint: 'attach GlobalTransform at scene authoring or import time, then retry propagation',
         detail: { entity, parent: entity },
       }),
     );
+  let changed = false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (current.value.world[index] !== value[index]) {
+      changed = true;
+      break;
+    }
   }
-  cache.derived.set(entity, resolved);
-  published.add(entity);
-  visiting.delete(entity);
+  if (!changed) return ok(undefined);
+  row.mut(GlobalTransform).world.set(value);
   return ok(undefined);
 }
 
-function drainPublishedChanges(
-  cache: PropagationCache,
-  published: ReadonlySet<EntityHandle>,
-): boolean {
-  const drained = cache.projection.poll();
-  if (drained.status === 'rebuild') return true;
-  return drained.changes.every(
-    (change) =>
-      change.kind === 'derived-component-changed' &&
-      change.component === Transform &&
-      published.has(change.entity),
-  );
+function propagateFlat(scratch: Scratch): Result<void, SceneError> {
+  const query = scratch.flatQuery;
+  if (query === undefined)
+    return err(
+      new SceneError({
+        code: 'hierarchy-broken',
+        expected: 'a valid changed Transform write query',
+        hint: 'register the scene components before running TransformPropagation',
+      }),
+    );
+  const spans = query.spans();
+  if (!spans.ok) return pairError(0 as EntityHandle, 'dense numeric Transform spans');
+  let bindingIndex = 0;
+  try {
+    for (const span of spans.value) {
+      const local = span.get(Transform);
+      const world = span.mut(GlobalTransform).world;
+      composeFlatColumns(local.pos, local.quat, local.scale, world, span.length);
+      bindingIndex += 1;
+    }
+  } catch (cause) {
+    const error = cause as EcsError;
+    return err(
+      new SceneError({
+        code: 'hierarchy-broken',
+        expected: 'derived GlobalTransform range publication to succeed',
+        hint: error.hint,
+        detail: {
+          kind: 'derived-write',
+          entity: 0 as EntityHandle,
+          parent: 0 as EntityHandle,
+          bindingIndex,
+          base: 0,
+          start: 0,
+          count: 0,
+          cause: error,
+        },
+      }),
+    );
+  }
+  return ok(undefined);
 }
 
-export function propagateTransforms(
+interface HierarchyEntry {
+  readonly entity: EntityHandle;
+  parent: EntityHandle | undefined;
+  readonly position: Float32Array;
+  readonly rotation: Float32Array;
+  readonly scale: Float32Array;
+  readonly world: Mat4;
+  state: 0 | 1 | 2;
+}
+
+function findEntry(entries: readonly HierarchyEntry[], entity: EntityHandle): number {
+  for (let index = 0; index < entries.length; index += 1) {
+    if (entries[index]?.entity === entity) return index;
+  }
+  return -1;
+}
+
+function resolveEntry(
+  index: number,
+  entries: HierarchyEntry[],
   world: World,
-  _hierarchy?: SceneHierarchySnapshot,
+  output: ReturnType<World['query']> extends Result<infer Q, unknown> ? Q : never,
+  scratch: Scratch,
 ): Result<void, SceneError> {
-  let cache = CACHE.get(world);
-  if (cache === undefined) {
-    cache = buildCache(world, createWorldProjection(world, { components: [Transform, ChildOf] }));
-    CACHE.set(world, cache);
-    const initial = new Set(cache.entities);
-    const published = new Set<EntityHandle>();
-    for (const entity of initial) {
-      const result = deriveEntity(world, entity, cache, initial, new Set(), published);
-      if (!result.ok) return result;
-    }
-    if (!drainPublishedChanges(cache, published)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+  const entry = entries[index];
+  if (entry === undefined || entry.state === 2) return ok(undefined);
+  if (entry.state === 1) {
+    // A cycle is an input error, but leaving every member on its previous
+    // GlobalTransform would make the renderer consume stale derived facts.
+    // Cut the complete active cycle segment to roots for this failed frame;
+    // the authored ChildOf values remain untouched and the next repaired
+    // propagation recomputes the normal hierarchy.
+    const cycleParent = entry.parent ?? entry.entity;
+    const cycleStart = scratch.hierarchyPath.indexOf(index);
+    const start = cycleStart < 0 ? 0 : cycleStart;
+    for (let pathIndex = start; pathIndex < scratch.hierarchyPath.length; pathIndex += 1) {
+      const cycleEntry = entries[scratch.hierarchyPath[pathIndex] ?? -1];
+      if (cycleEntry !== undefined) cycleEntry.parent = undefined;
     }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
+    return err(
+      new SceneError({
+        code: 'hierarchy-cycle',
+        expected: 'a parent-before-child Transform hierarchy',
+        hint: 'repair the ChildOf cycle and retry TransformPropagation',
+        detail: { entity: entry.entity, parent: cycleParent },
+      }),
+    );
   }
-
-  const evidence = cache.projection.poll();
-  if (evidence.status === 'rebuild') {
-    cache = buildCache(world, cache.projection);
-    CACHE.set(world, cache);
-    const all = new Set(cache.entities);
-    const published = new Set<EntityHandle>();
-    for (const entity of all) {
-      const result = deriveEntity(world, entity, cache, all, new Set(), published);
-      if (!result.ok) return result;
-    }
-    if (!drainPublishedChanges(cache, published)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+  entry.state = 1;
+  scratch.hierarchyPath.push(index);
+  let parentIndex = entry.parent === undefined ? -1 : findEntry(entries, entry.parent);
+  let failure: SceneError | undefined;
+  if (entry.parent !== undefined && parentIndex < 0) {
+    const local = world.get(entry.parent, Transform);
+    const global = world.get(entry.parent, GlobalTransform);
+    if (!local.ok || !global.ok) {
+      // The edge is invalid for this frame.  Treat the child as a local root
+      // so the output column reflects current authored input instead of the
+      // previous frame's world matrix, while still returning the structured
+      // error to the caller.
+      failure = new SceneError({
+        code: 'hierarchy-broken',
+        expected: 'each ChildOf parent to carry Transform and GlobalTransform',
+        hint: 'repair the missing parent pair before retrying propagation',
+        detail: { entity: entry.entity, parent: entry.parent },
+      });
+      entry.parent = undefined;
+      parentIndex = -1;
+    } else {
+      const relation = world.get(entry.parent, ChildOf);
+      entries.push({
+        entity: entry.parent,
+        parent: relation.ok && relation.value.parent !== null ? relation.value.parent : undefined,
+        position: new Float32Array(local.value.pos),
+        rotation: new Float32Array(local.value.quat),
+        scale: new Float32Array(local.value.scale),
+        world: mat4.create(),
+        state: 0,
+      });
+      parentIndex = entries.length - 1;
     }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
   }
-  if (evidence.changes.length === 0) return cache.result;
-
-  const transformSeeds = new Set<EntityHandle>();
-  let rebuild = false;
-  for (const change of evidence.changes) {
-    if (
-      change.kind === 'entity-removed' ||
-      change.kind === 'component-added' ||
-      change.kind === 'component-removed'
-    ) {
-      rebuild = true;
-      break;
-    }
-    if (change.kind !== 'component-changed') continue;
-    if (change.component === ChildOf) {
-      rebuild = true;
-      break;
-    }
-    // Derived Transform publications are deliberately not dirty seeds. Only
-    // authored component-changed records can invalidate local TRS state.
-    if (change.component === Transform) transformSeeds.add(change.entity);
+  if (parentIndex >= 0) {
+    const parentResult = resolveEntry(parentIndex, entries, world, output, scratch);
+    if (!parentResult.ok) failure = parentResult.error;
+    // A cycle fallback can cut this entry's authored edge while resolving its
+    // parent. Re-read the edge before composing so no cycle member consumes an
+    // uninitialized parent matrix.
+    parentIndex = entry.parent === undefined ? -1 : findEntry(entries, entry.parent);
+    if (parentIndex >= 0 && entries[parentIndex]?.state !== 2) parentIndex = -1;
   }
-  if (rebuild) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
+  composeColumns(entry.position, entry.rotation, entry.scale, scratch.local, scratch);
+  if (parentIndex >= 0) {
+    const parent = entries[parentIndex];
+    if (parent !== undefined) mat4.multiply(entry.world, parent.world, scratch.local);
+  } else {
+    entry.world.set(scratch.local);
   }
-
-  // A World can record several authored writes before this pass. Read each
-  // seed once so the final local state decides whether propagation is needed.
-  const changed = new Set<EntityHandle>();
-  for (const entity of transformSeeds) {
-    const current = world.get(entity, Transform);
-    if (!current.ok) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
-    }
-    const next = copyState(current.value);
-    if (!sameState(cache.locals.get(entity), next)) changed.add(entity);
-    cache.locals.set(entity, next);
+  const write = writeWorld(world, output, entry.entity, entry.world);
+  if (!write.ok) {
+    scratch.hierarchyPath.pop();
+    return write;
   }
-  if (changed.size === 0) return cache.result;
+  entry.state = 2;
+  scratch.hierarchyPath.pop();
+  return failure === undefined ? ok(undefined) : err(failure);
+}
 
-  const affected = descendants(cache.childrenOf, changed);
-  const published = new Set<EntityHandle>();
-  for (const entity of affected) cache.derived.delete(entity);
-  for (const entity of affected) {
-    const result = deriveEntity(world, entity, cache, affected, new Set(), published);
-    if (!result.ok) return result;
+function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneError> {
+  const query = scratch.hierarchyQuery;
+  const output = scratch.outputQuery;
+  if (query === undefined || output === undefined) {
+    return err(
+      new SceneError({
+        code: 'hierarchy-broken',
+        expected: 'paired Transform and GlobalTransform query access',
+        hint: 'register the scene components before running TransformPropagation',
+      }),
+    );
   }
-  if (!drainPublishedChanges(cache, published)) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
+  const entries: HierarchyEntry[] = [];
+  for (const row of query) {
+    if (findEntry(entries, row.entity) >= 0) continue;
+    const local = row.get(Transform);
+    const parentValue = row.get(ChildOf).parent;
+    const parent = parentValue === null ? undefined : parentValue;
+    entries.push({
+      entity: row.entity,
+      parent,
+      position: new Float32Array(local.pos),
+      rotation: new Float32Array(local.quat),
+      scale: new Float32Array(local.scale),
+      world: mat4.create(),
+      state: 0,
+    });
   }
-  cache.result = hierarchyError(cache.hierarchy);
-  return cache.result;
+  scratch.hierarchyPath.length = 0;
+  let firstError: SceneError | undefined;
+  for (let index = 0; index < entries.length; index += 1) {
+    const result = resolveEntry(index, entries, world, output, scratch);
+    if (!result.ok) {
+      const currentEntity = Number(result.error.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+      if (firstError === undefined) {
+        firstError = result.error;
+      } else {
+        const firstEntity = Number(firstError.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+        if (
+          currentEntity < firstEntity ||
+          (currentEntity === firstEntity && result.error.code.localeCompare(firstError.code) < 0)
+        ) {
+          firstError = result.error;
+        }
+      }
+    }
+  }
+  return firstError === undefined ? ok(undefined) : err(firstError);
+}
+
+export function propagateTransforms(world: World): Result<void, SceneError> {
+  const scratch = scratchFor(world);
+  const pairs = validateTransformPairs(world, scratch);
+  if (!pairs.ok) return pairs;
+  const flat = propagateFlat(scratch);
+  if (!flat.ok) return flat;
+  return propagateHierarchy(world, scratch);
 }
 
 export const PropagateTransforms: SystemHandle<readonly []> = defineSystem({
@@ -341,7 +471,7 @@ export function registerPropagateTransforms(
         world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
         world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
         REGISTRATION_LEASES.delete(world);
-        CACHE.delete(world);
+        SCRATCH.delete(world);
       }
     };
   }
@@ -360,17 +490,18 @@ export function registerPropagateTransforms(
       .unwrap();
   }
   world.addSystems(FixedUpdate, TransformFixedSet, [PropagateTransformsFixed]).unwrap();
-  const lease: TransformRegistrationLease = { refs: 1 };
-  REGISTRATION_LEASES.set(world, lease);
+  REGISTRATION_LEASES.set(world, { refs: 1 });
   let active = true;
   return () => {
     if (!active) return;
     active = false;
+    const lease = REGISTRATION_LEASES.get(world);
+    if (lease === undefined) return;
     lease.refs -= 1;
     if (lease.refs !== 0) return;
     world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
     world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
     REGISTRATION_LEASES.delete(world);
-    CACHE.delete(world);
+    SCRATCH.delete(world);
   };
 }