@forgeax/engine-ecs 0.1.4 → 0.1.6

package/dist/projection/index.d.ts

@@ -1,6 +1,8 @@
 import type { Result } from '@forgeax/engine-types';
 import type { Component } 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';
 export { fillComponentDefaults } from '../component-default-fallback';
 export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, } from '../errors';
@@ -29,6 +31,57 @@ export interface WorldProjection {
 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 declare function readRenderArrayView(world: World, entity: EntityHandle, component: Component, fieldName: string): ArrayLike<number> | undefined;
+/** Create the render-owned lease from the ECS projection boundary. */
+export declare function createRenderReadLease(world: World, token?: object): RenderReadLease;
 /**
  * Publish one owner-derived component value without confusing it with an
  * authored mutation. Owner packages use this narrow seam for fields such as

package/dist/projection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/projection/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAMhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,wBAAwB,EACxB,qCAAqC,EACrC,6BAA6B,EAC7B,yBAAyB,EACzB,4BAA4B,EAC5B,2BAA2B,EAC3B,iCAAiC,EACjC,kDAAkD,EAClD,wCAAwC,EACxC,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,2BAA2B,GAC3B,gBAAgB,CAAC;AAErB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC,CAAC;AAEN,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAKxB;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,sBAA2B,GACnC,eAAe,CA4CjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/projection/index.ts"],"names":[],"mappings":"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"}

package/dist/projection/index.mjs

@@ -467,6 +467,104 @@ function fillComponentDefaults(token, raw) {
 }
 
 // src/projection/index.ts
+function readRenderArrayView(world, entity, component, fieldName) {
+  return world[worldInternal].getArrayView(entity, component, fieldName);
+}
+function readProjectionSpans(world, generation, request) {
+  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 = [];
+  for (const span of spansResult.value) {
+    const fields = {};
+    for (const entry of request.components) {
+      const shape = span.get(entry.component);
+      for (const fieldName of entry.fields) {
+        const field = shape[fieldName];
+        if (field === void 0) {
+          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)
+  };
+}
+function createRenderReadLease(world, token = {}) {
+  const sharedRefs = world[worldInternal].getSharedRefs();
+  const generation = Math.max(1, world[worldInternal].getStructureEpoch());
+  let disposed = false;
+  let nextCursor = 1;
+  const cursors = /* @__PURE__ */ new Map([
+    [
+      0,
+      { world: world[worldInternal].getChangeCursor(), sharedRefs: sharedRefs.getMutationEpoch() }
+    ]
+  ]);
+  const assertLive = () => {
+    if (disposed) throw new Error("RenderReadLease is disposed.");
+  };
+  const captureCursor = () => {
+    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() {
+      assertLive();
+      return captureCursor();
+    },
+    readChanges(cursor) {
+      assertLive();
+      const start = cursors.get(cursor);
+      if (start === void 0) throw new RangeError(`Unknown RenderReadLease cursor ${cursor}.`);
+      const worldRead = world[worldInternal].readChangesSince(start.world);
+      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) {
+      assertLive();
+      return readProjectionSpans(world, generation, request);
+    },
+    dispose() {
+      disposed = true;
+      cursors.clear();
+    }
+  };
+}
 function setDerivedComponent(world, entity, component, value) {
   const result = world[worldInternal].setQueryRow(entity, component, value);
   if (!result.ok) return result;
@@ -512,6 +610,6 @@ function createWorldProjection(world, options = {}) {
   };
 }
 
-export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, createWorldProjection, fillComponentDefaults, routeWorldError, setDerivedComponent };
+export { ComponentNotDefinedError, InstanceTransformsStrideMismatchError, ManagedBufferOutOfBoundsError, ResourceInvalidValueError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, StaleEntityError, createRenderReadLease, createWorldProjection, fillComponentDefaults, readRenderArrayView, routeWorldError, setDerivedComponent };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map