@forgeax/engine-ecs 0.1.4 → 0.1.6

package/src/projection/index.ts

@@ -2,6 +2,8 @@ import type { Result } from '@forgeax/engine-types';
 import type { Component } from '../component';
 import { componentId } from '../component';
 import type { EntityHandle } from '../entity-handle';
+import type { SharedRefMutationRead } from '../shared-ref-store';
+import type { WorldChangeRead } from '../storage/change-detection';
 import type { EcsError, World } from '../world';
 import { worldInternal } from '../world-internal';
 
@@ -59,6 +61,180 @@ export interface WorldProjectionOptions {
   readonly components?: readonly Component[];
 }
 
+export interface RenderProjectionComponentRequest {
+  readonly component: Component;
+  readonly fields: readonly string[];
+}
+
+export interface RenderProjectionRequest {
+  readonly components: readonly RenderProjectionComponentRequest[];
+}
+
+export interface RenderProjectionSpan {
+  readonly length: number;
+  readonly fields: Readonly<Record<string, ArrayLike<number>>>;
+}
+
+export interface RenderProjectionSpans {
+  readonly generation: number;
+  readonly sharedRefEpoch: number;
+  readonly spans: readonly RenderProjectionSpan[];
+}
+
+export interface RenderChangeBatchOk {
+  readonly status: 'ok';
+  readonly cursor: number;
+  readonly world: Extract<WorldChangeRead, { readonly status: 'ok' }>;
+  readonly sharedRefs: Extract<SharedRefMutationRead, { readonly status: 'ok' }>;
+}
+
+export interface RenderChangeBatchOverflow {
+  readonly status: 'overflow';
+  readonly cursor: number;
+  readonly resync: true;
+  readonly oldestAvailable: number;
+  readonly world: WorldChangeRead;
+  readonly sharedRefs: SharedRefMutationRead;
+}
+
+export type RenderChangeBatch = RenderChangeBatchOk | RenderChangeBatchOverflow;
+
+export interface RenderReadLease {
+  readonly worldIdentity: string;
+  readonly generation: number;
+  readChanges(cursor: number): RenderChangeBatch;
+  querySpans(request: RenderProjectionRequest): RenderProjectionSpans;
+  inspectCursor(): number;
+  dispose(): void;
+}
+
+/**
+ * Read one array field through the render projection boundary without
+ * materialising the component object. Render extraction uses this for hot
+ * transform/instance columns; the World internals remain owned by ECS.
+ */
+export function readRenderArrayView(
+  world: World,
+  entity: EntityHandle,
+  component: Component,
+  fieldName: string,
+): ArrayLike<number> | undefined {
+  return world[worldInternal].getArrayView(entity, component, fieldName) as
+    | ArrayLike<number>
+    | undefined;
+}
+
+interface ProjectionCursor {
+  readonly world: number;
+  readonly sharedRefs: number;
+}
+
+function readProjectionSpans(
+  world: World,
+  generation: number,
+  request: RenderProjectionRequest,
+): RenderProjectionSpans {
+  const queryResult = world.query({ read: request.components.map((entry) => entry.component) });
+  if (!queryResult.ok) throw new Error(queryResult.error.message);
+  const spansResult = queryResult.value.spans();
+  if (!spansResult.ok) throw new Error(spansResult.error.message);
+  const spans: RenderProjectionSpan[] = [];
+  for (const span of spansResult.value) {
+    const fields: Record<string, ArrayLike<number>> = {};
+    for (const entry of request.components) {
+      const shape = span.get(entry.component) as unknown as Record<string, ArrayLike<number>>;
+      for (const fieldName of entry.fields) {
+        const field = shape[fieldName];
+        if (field === undefined) {
+          throw new Error(
+            `Render projection field '${entry.component.name}.${fieldName}' is unavailable.`,
+          );
+        }
+        fields[`${entry.component.name}.${fieldName}`] = field;
+        if (request.components.length === 1) fields[fieldName] = field;
+      }
+    }
+    spans.push({ length: span.length, fields: Object.freeze(fields) });
+  }
+  return {
+    generation,
+    sharedRefEpoch: world[worldInternal].getSharedRefs().getMutationEpoch(),
+    spans: Object.freeze(spans),
+  };
+}
+
+/** Create the render-owned lease from the ECS projection boundary. */
+export function createRenderReadLease(world: World, token: object = {}): RenderReadLease {
+  void token;
+  const sharedRefs = world[worldInternal].getSharedRefs();
+  const generation = Math.max(1, world[worldInternal].getStructureEpoch());
+  let disposed = false;
+  let nextCursor = 1;
+  const cursors = new Map<number, ProjectionCursor>([
+    [
+      0,
+      { world: world[worldInternal].getChangeCursor(), sharedRefs: sharedRefs.getMutationEpoch() },
+    ],
+  ]);
+
+  const assertLive = (): void => {
+    if (disposed) throw new Error('RenderReadLease is disposed.');
+  };
+
+  const captureCursor = (): number => {
+    const cursor = nextCursor++;
+    cursors.set(cursor, {
+      world: world[worldInternal].getChangeCursor(),
+      sharedRefs: sharedRefs.getMutationEpoch(),
+    });
+    if (cursors.size > 8) {
+      const oldest = cursors.keys().next().value;
+      if (typeof oldest === 'number' && oldest !== cursor) cursors.delete(oldest);
+    }
+    return cursor;
+  };
+
+  return {
+    worldIdentity: world.identity,
+    generation,
+    inspectCursor(): number {
+      assertLive();
+      return captureCursor();
+    },
+    readChanges(cursor: number): RenderChangeBatch {
+      assertLive();
+      const start = cursors.get(cursor);
+      if (start === undefined) throw new RangeError(`Unknown RenderReadLease cursor ${cursor}.`);
+      const worldRead = world[worldInternal].readChangesSince(start.world) as WorldChangeRead;
+      const sharedRead = sharedRefs.readChangesSince(start.sharedRefs);
+      const next = captureCursor();
+      if (worldRead.status === 'overflow' || sharedRead.status === 'overflow') {
+        const oldestAvailable = Math.min(
+          worldRead.status === 'overflow' ? worldRead.oldestAvailable : Number.MAX_SAFE_INTEGER,
+          sharedRead.status === 'overflow' ? sharedRead.oldestAvailable : Number.MAX_SAFE_INTEGER,
+        );
+        return {
+          status: 'overflow',
+          cursor: next,
+          resync: true,
+          oldestAvailable,
+          world: worldRead,
+          sharedRefs: sharedRead,
+        };
+      }
+      return { status: 'ok', cursor: next, world: worldRead, sharedRefs: sharedRead };
+    },
+    querySpans(request: RenderProjectionRequest): RenderProjectionSpans {
+      assertLive();
+      return readProjectionSpans(world, generation, request);
+    },
+    dispose(): void {
+      disposed = true;
+      cursors.clear();
+    },
+  };
+}
+
 /**
  * Publish one owner-derived component value without confusing it with an
  * authored mutation. Owner packages use this narrow seam for fields such as

package/src/world-component-access.ts

@@ -44,6 +44,7 @@ import {
   RemoveEssentialComponentError,
   StaleEntityError,
   validateEnumFieldValues,
+  validateNumericFieldValues,
 } from './errors';
 import {
   isRelationshipTarget,
@@ -199,6 +200,24 @@ export class WorldComponentAccess {
     return null;
   }
 
+  private preflightComponentFieldValues(
+    holder: EntityHandle | null,
+    componentData: ComponentData,
+  ): Result<void, EcsError> {
+    const data = componentData.data as Record<string, unknown>;
+    const arrayError = validateManagedArrayValues(componentData.component, data);
+    if (arrayError !== null) return err(arrayError as unknown as EcsError);
+    const sharedError = validateSharedFieldValues(componentData.component, data);
+    if (sharedError !== null) return err(sharedError as unknown as EcsError);
+    const numericError = validateNumericFieldValues(
+      componentData.component,
+      data,
+      holder === null ? undefined : (holder as number),
+    );
+    if (numericError !== null) return err(numericError as unknown as EcsError);
+    return ok(undefined);
+  }
+
   /**
    * Validate one structural component payload without touching archetypes,
    * columns, relationship mirrors, epochs, or managed-reference stores.
@@ -215,10 +234,8 @@ export class WorldComponentAccess {
     const data = componentData.data as Record<string, unknown>;
     const keyError = validateComponentDataKeys(componentData.component, data);
     if (keyError !== null) return err(keyError as unknown as EcsError);
-    const arrayError = validateManagedArrayValues(componentData.component, data);
-    if (arrayError !== null) return err(arrayError as unknown as EcsError);
-    const sharedError = validateSharedFieldValues(componentData.component, data);
-    if (sharedError !== null) return err(sharedError as unknown as EcsError);
+    const valuePreflight = this.preflightComponentFieldValues(holder, componentData);
+    if (!valuePreflight.ok) return valuePreflight;
     if (isRelationshipTarget(componentData.component) && relationshipPayloadWrites(data)) {
       return err(new RelationshipTargetReadonlyError(componentData.component.name, 'command'));
     }
@@ -614,29 +631,21 @@ export class WorldComponentAccess {
       // F-02: set on missing component returns err instead of silent ignore
       return err(new ComponentNotPresentError(entity as number, component.name));
     }
-    // feat-20260713 M2 / w9: P3 shared-field value gate (see _spawnCore). Runs
-    // before any column write so a mis-bound GUID aborts before the scalar /
-    // array packer would zero the field — the set never partially lands.
-    const arrayErr = validateManagedArrayValues(component, value as Record<string, unknown>);
-    if (arrayErr !== null) {
-      return err(arrayErr as unknown as EcsError);
-    }
-    const sharedErr = validateSharedFieldValues(component, value as Record<string, unknown>);
-    if (sharedErr !== null) {
-      return err(sharedErr as unknown as EcsError);
-    }
+    const valuePreflight = this.preflightComponentFieldValues(entity, {
+      component,
+      data: value,
+    });
+    if (!valuePreflight.ok) return valuePreflight;
     const currentValue = this.storage.readRow(arch, component, this.tableRow(rec)) as Record<
       string,
       unknown
     >;
-    const enumErr = validateEnumFieldValues(
+    const enumError = validateEnumFieldValues(
       component,
       { ...currentValue, ...(value as Record<string, unknown>) },
       entity as number,
     );
-    if (enumErr !== null) {
-      return err(enumErr as unknown as EcsError);
-    }
+    if (enumError !== null) return err(enumError as unknown as EcsError);
     if (component.storage === 'sparse') {
       if (markChanged) this.markComponentChanged(entity, component);
       return ok(undefined);

package/src/world.ts

@@ -27,6 +27,7 @@ import type {
   ComponentFieldInvalidValueError,
   ComponentNotDefinedError,
   ComponentNotPresentError,
+  ComponentNumericValueInvalidError,
   FixedSizeMismatchError,
   ManagedArrayInvalidValueError,
   ManagedBufferOutOfBoundsError,
@@ -122,6 +123,7 @@ export type EcsError =
   | ComponentNotPresentError
   | ComponentAlreadyPresentError
   | ComponentFieldInvalidValueError
+  | ComponentNumericValueInvalidError
   | ManagedArrayInvalidValueError
   | UniqueRefReleasedError
   | UniqueRefDoubleReleaseError