@forgeax/engine-scene 0.1.26 → 0.1.27

package/package.json

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

package/src/__tests__/fixtures/malformed-hierarchy-edge.ts

@@ -1,9 +1,57 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { componentId } from '../../../../ecs/src/component';
 import { entityIndex } from '../../../../ecs/src/entity-handle';
-import { worldInternal } from '../../../../ecs/src/world-internal';
 import { ChildOf } from '../../index';
 
+const WORLD_INTERNAL_KEY: unique symbol = Symbol.for(
+  'forgeax.ecs.worldInternal',
+) as unknown as typeof WORLD_INTERNAL_KEY;
+
+interface MalformedRecord {
+  readonly archetypeId: number;
+  readonly archetypeRow: number;
+}
+
+interface MalformedColumn {
+  readonly view: { [index: number]: number };
+}
+
+interface MalformedComponentStorage {
+  readonly fields: Map<string, MalformedColumn>;
+}
+
+interface MalformedTable {
+  readonly storage: Map<number, MalformedComponentStorage>;
+}
+
+interface MalformedArchetype {
+  readonly tableId: number;
+  readonly rows: readonly number[];
+}
+
+interface MalformedGraph {
+  readonly archetypes: readonly (MalformedArchetype | undefined)[];
+  readonly tables: readonly (MalformedTable | undefined)[];
+}
+
+interface MalformedWorldInternal {
+  readonly getRecords: () => readonly (MalformedRecord | undefined)[];
+  readonly getGraph: () => MalformedGraph;
+  readonly markComponentChanged: (entity: EntityHandle, componentId: number) => void;
+}
+
+interface WorldWithMalformedInjection {
+  readonly [WORLD_INTERNAL_KEY]: MalformedWorldInternal;
+}
+
+function malformedInjection(world: World): MalformedWorldInternal {
+  const internal = (world as unknown as WorldWithMalformedInjection)[WORLD_INTERNAL_KEY];
+  if (internal === undefined) {
+    throw new Error('Malformed hierarchy fixture requires the ECS test injection seam.');
+  }
+  return internal;
+}
+
 /**
  * Scene-owned malformed-edge fixture. Production relationship writes reject
  * stale targets and cycles before touching either side of the relationship.
@@ -16,11 +64,12 @@ export function setMalformedParentEdge(
   child: EntityHandle,
   parent: EntityHandle,
 ): void {
-  const record = world[worldInternal].getRecords()[entityIndex(child)];
+  const internal = malformedInjection(world);
+  const record = internal.getRecords()[entityIndex(child)];
   if (record === undefined || record.archetypeId < 0) {
     throw new Error(`Malformed hierarchy fixture child ${child} is not live.`);
   }
-  const graph = world[worldInternal].getGraph();
+  const graph = internal.getGraph();
   const archetype = graph.archetypes[record.archetypeId];
   if (archetype === undefined) throw new Error(`Missing archetype ${record.archetypeId}.`);
   const table = graph.tables[archetype.tableId];
@@ -33,5 +82,5 @@ export function setMalformedParentEdge(
   // Keep the corruption internal, but make the source mutation observable to
   // the normal change-token consumers so an already-built projection cannot
   // mask the deliberately malformed value.
-  world[worldInternal].markComponentChanged(child, componentId(ChildOf));
+  internal.markComponentChanged(child, componentId(ChildOf));
 }

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

@@ -1,7 +1,6 @@
 import { type EntityHandle, FixedUpdate, Update, World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
 import { ChangeEpochExhaustedError } from '../../../ecs/src/errors';
-import { worldInternal } from '../../../ecs/src/world-internal';
 import { ChildOf, GlobalTransform, propagateTransforms, Transform } from '../index';
 import { registerPropagateTransforms } from '../systems';
 import {
@@ -10,6 +9,18 @@ import {
 } from '../systems/propagate-transforms';
 import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
 
+const WORLD_INTERNAL_KEY: unique symbol = Symbol.for(
+  'forgeax.ecs.worldInternal',
+) as unknown as typeof WORLD_INTERNAL_KEY;
+
+interface RangePublicationInjection {
+  readonly markComponentRangeChanged: (...args: never[]) => void;
+}
+
+interface WorldWithRangePublicationInjection {
+  readonly [WORLD_INTERNAL_KEY]: RangePublicationInjection;
+}
+
 function spawnTransform(world: World, pos: number[], parent?: EntityHandle) {
   const components = [{ component: Transform, data: { pos } }];
   if (parent === undefined) return world.spawn(...components).unwrap();
@@ -67,7 +78,7 @@ describe('scene propagation', () => {
   it('preserves the ECS range-publication error in flat propagation diagnostics', () => {
     const world = new World();
     spawnTransform(world, [2, 0, 0]);
-    const internal = world[worldInternal];
+    const internal = (world as unknown as WorldWithRangePublicationInjection)[WORLD_INTERNAL_KEY];
     const originalMarkRange = internal.markComponentRangeChanged;
     Object.defineProperty(internal, 'markComponentRangeChanged', {
       configurable: true,

package/src/systems/propagate-transforms.ts

@@ -15,8 +15,8 @@ import {
   type DerivedRangeCursor,
   type DerivedRangeWriter,
   getDerivedWriter,
-  worldInternal,
 } from '@forgeax/engine-ecs/internal';
+import { worldRead } from '@forgeax/engine-ecs/world-read';
 import { type Mat4, mat4 } from '@forgeax/engine-math';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { ChildOf } from '../components/child-of';
@@ -374,7 +374,7 @@ function propagateFlat(world: World, scratch: Scratch): Result<void, SceneError>
     return pairError(0 as EntityHandle, 'dense Transform and GlobalTransform derived bindings');
   }
   const transformBindings = transformWriter.bindings as readonly TransformBinding[];
-  const structureEpoch = world[worldInternal].getStructureEpoch();
+  const structureEpoch = world.getStructureEpoch();
   if (scratch.flatStructureEpoch === structureEpoch) return ok(undefined);
 
   ensureFlatBuffers(scratch, transformBindings);
@@ -385,7 +385,7 @@ function propagateFlat(world: World, scratch: Scratch): Result<void, SceneError>
     if (binding === undefined || changed === undefined) continue;
     for (let row = 0; row < binding.rowCapacity; row += 1) {
       const entity = (binding.entities[row] ?? 0) as EntityHandle;
-      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, 'parent');
+      const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, 'parent');
       if (parentRaw !== undefined && parentRaw !== ENTITY_NULL_RAW) continue;
       countPropagation('flatStructuralRootRows');
       composeBindingRow(binding, row, undefined, 0, scratch, changed);
@@ -838,7 +838,7 @@ function walkChildren(
       continue;
     }
 
-    const childrenLength = world[worldInternal].getArrayLength(current, Children, 'entities') ?? 0;
+    const childrenLength = world[worldRead].getArrayLength(current, Children, 'entities') ?? 0;
     if (nextChild >= childrenLength) {
       stackEntities.pop();
       stackChildren.pop();
@@ -857,7 +857,7 @@ function walkChildren(
     }
     stackChildren[top] = nextChild + 1;
     countPropagation('hierarchyEdgesVisited');
-    const childRaw = world[worldInternal].getArrayElement(current, Children, 'entities', nextChild);
+    const childRaw = world[worldRead].getArrayElement(current, Children, 'entities', nextChild);
     if (childRaw === undefined || childRaw === ENTITY_NULL_RAW) {
       report(
         hierarchyError(
@@ -1145,7 +1145,7 @@ function propagateHierarchy(world: World, scratch: Scratch): Result<void, SceneE
     const entities = binding.entities;
     for (let row = 0; row < binding.rowCapacity; row += 1) {
       const entity = (entities[row] ?? 0) as EntityHandle;
-      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, 'parent');
+      const parentRaw = world[worldRead].getFieldValue(entity, ChildOf, 'parent');
       if (parentRaw === undefined || parentRaw === ENTITY_NULL_RAW) {
         walkChildren(
           world,