@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/dist/projection/index.mjs

@@ -0,0 +1,615 @@
+import '@forgeax/engine-types';
+
+// src/component.ts
+
+// src/component-schema.ts
+var COMPONENT_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentRegistry");
+var globalSymbols = globalThis;
+var definitions = globalSymbols[COMPONENT_REGISTRY] ?? (() => {
+  const registry = { definitions: /* @__PURE__ */ new WeakMap() };
+  globalSymbols[COMPONENT_REGISTRY] = registry;
+  return registry;
+})();
+function componentDefinition(component) {
+  const definition = definitions.definitions.get(component);
+  if (definition === void 0) {
+    throw new Error(`Component definition missing for '${component.name}'.`);
+  }
+  return definition;
+}
+
+// src/errors/query-and-component-errors.ts
+var ComponentNotDefinedError = class extends Error {
+  name = "ComponentNotDefinedError";
+  code = "component-not-defined";
+  hint;
+  expected;
+  detail;
+  constructor(componentName, opts) {
+    const expected = opts?.expected ?? `component '${componentName}' defined before instantiate`;
+    const hint = opts?.hint ?? `define the component via defineComponent('${componentName}', ...) before instantiating this SceneAsset`;
+    super(
+      `instantiate: component not defined.
+  code: component-not-defined
+  component: ${componentName}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { name: componentName };
+  }
+};
+
+// src/errors/sprite-and-shared-errors.ts
+var SpriteInstancesCountMismatchError = class extends Error {
+  name = "SpriteInstancesCountMismatchError";
+  code = "sprite-instances-count-mismatch";
+  hint;
+  expected;
+  detail;
+  constructor(transformsLength, regionsLength) {
+    const hint = "SpriteInstances.transforms (stride 16) and SpriteInstances.regions (stride 4) must describe the same instance count: ensure transforms.length / 16 === regions.length / 4 at the spawn / set site (resize both arrays together).";
+    const expected = "transforms.length / 16 === regions.length / 4";
+    super(
+      `SpriteInstances: per-instance count mismatch between transforms and regions.
+  code: sprite-instances-count-mismatch
+  transformsLength: ${transformsLength} (count = ${transformsLength / 16})
+  regionsLength: ${regionsLength} (count = ${regionsLength / 4})
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: "sprite-instances-count-mismatch",
+      transformsLength,
+      regionsLength,
+      expectedStride: { transforms: 16, regions: 4 }
+    };
+  }
+};
+var SpriteInstancesRequiresSpriteShaderError = class extends Error {
+  name = "SpriteInstancesRequiresSpriteShaderError";
+  code = "sprite-instances-requires-sprite-shader";
+  hint;
+  expected;
+  detail;
+  constructor(entityId, observedMaterialShaderId) {
+    const hint = "bind a MaterialAsset whose first pass `shader` is 'forgeax::sprite' or 'forgeax::sprite-lit' to this entity's MeshRenderer (SpriteInstances requires a sprite-family shader so the per-instance UV region is consumed by the sprite vertex shader path).";
+    const expected = "MaterialAsset.passes[0].shader === 'forgeax::sprite' || 'forgeax::sprite-lit'";
+    super(
+      `SpriteInstances: entity ${entityId} requires a sprite-shaded MaterialAsset.
+  code: sprite-instances-requires-sprite-shader
+  entityId: ${entityId}
+  observedMaterialShaderId: ${observedMaterialShaderId}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: "sprite-instances-requires-sprite-shader",
+      entityId,
+      observedMaterialShaderId
+    };
+  }
+};
+var SpriteInstancesMutuallyExclusiveWithInstancesError = class extends Error {
+  name = "SpriteInstancesMutuallyExclusiveWithInstancesError";
+  code = "sprite-instances-mutually-exclusive-with-instances";
+  hint;
+  expected;
+  detail;
+  constructor(entityId) {
+    const hint = "remove Instances or replace with SpriteInstances; SpriteInstances supersedes Instances when per-instance region is needed.";
+    const expected = "entity carries Instances XOR SpriteInstances (not both)";
+    super(
+      `SpriteInstances: entity ${entityId} carries both Instances and SpriteInstances.
+  code: sprite-instances-mutually-exclusive-with-instances
+  entityId: ${entityId}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: "sprite-instances-mutually-exclusive-with-instances",
+      entityId
+    };
+  }
+};
+
+// src/errors/validation-errors.ts
+var SPAWN_LIGHT_INVALID_BOUNDS_POLICY = {
+  range: {
+    expected: "range >= 0 or Number.POSITIVE_INFINITY",
+    hint: (componentName, got) => `${componentName}.range = ${got} is invalid; use Number.POSITIVE_INFINITY for unlimited range, or a non-negative meter value`
+  },
+  innerOuter: {
+    expected: "outerConeDeg > innerConeDeg",
+    hint: (componentName, got) => `${componentName}.outerConeDeg <= innerConeDeg (got ${got}); inner cone is the saturated bright region, outer cone is the falloff edge; outerConeDeg > innerConeDeg required`
+  },
+  outerNinety: {
+    expected: "outerConeDeg <= 90 (KHR_lights_punctual upper bound)",
+    hint: (componentName, got) => `${componentName}.outerConeDeg = ${got} > 90; a spot light cone wider than 90 degrees becomes a point light; use PointLight instead`
+  },
+  direction: {
+    expected: "direction is a non-zero [x, y, z] vector",
+    hint: (componentName, got) => `${componentName}.direction is missing or a zero vector (got ${JSON.stringify(got)}); direction has no default, provide a non-zero direction, e.g. [-0.5, -1, -0.3]`
+  }
+};
+var SpawnLightInvalidBoundsError = class extends Error {
+  name = "SpawnLightInvalidBoundsError";
+  code = "spawn-light-invalid-bounds";
+  hint;
+  expected;
+  detail;
+  constructor(componentName, field, got) {
+    const policy = SPAWN_LIGHT_INVALID_BOUNDS_POLICY[field];
+    const hint = policy.hint(componentName, got);
+    const expectedStr = policy.expected;
+    super(
+      `${componentName}: spawn payload bound violation.
+  code: spawn-light-invalid-bounds
+  component: ${componentName}
+  field: ${field}
+  got: ${got}
+  expected: ${expectedStr}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expectedStr;
+    this.detail = { field, got };
+  }
+};
+var ResourceInvalidValueError = class extends Error {
+  name = "ResourceInvalidValueError";
+  code = "resource-invalid-value";
+  hint;
+  expected;
+  detail;
+  constructor(expected, hint, detail) {
+    const keyClause = detail.receivedKey === void 0 ? "" : `  key: ${detail.receivedKey}
+`;
+    super(
+      `resource: invalid value.
+  code: resource-invalid-value
+` + keyClause + `  receivedMode: ${detail.receivedMode}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = detail;
+  }
+};
+var SpriteAnimationInvalidError = class _SpriteAnimationInvalidError extends Error {
+  name = "SpriteAnimationInvalidError";
+  code = "sprite-animation-invalid";
+  hint;
+  expected;
+  detail;
+  static resolvePolicy(detail) {
+    switch (detail.field) {
+      case "regions-length":
+        return {
+          expected: "SpriteAnimation.regions.length === frameCount * 4",
+          hint: `SpriteAnimation.regions.length = ${detail.regionsLength} does not match frameCount * 4 = ${detail.frameCount * 4}; pack 4 floats [uMin, vMin, uW, vH] per frame (see <name>.atlas.meta.json sidecar 'regions' map)`
+        };
+      case "frame-duration":
+        return {
+          expected: "SpriteAnimation.frameDuration > 0",
+          hint: `SpriteAnimation.frameDuration = ${detail.frameDuration} is invalid; use a positive seconds-per-frame value (e.g. 0.1 = 10 fps)`
+        };
+    }
+  }
+  constructor(detail) {
+    const policy = _SpriteAnimationInvalidError.resolvePolicy(detail);
+    super(
+      `SpriteAnimation: invariant violated.
+  code: sprite-animation-invalid
+  field: ${detail.field}
+  expected: ${policy.expected}
+  hint: ${policy.hint}`
+    );
+    this.hint = policy.hint;
+    this.expected = policy.expected;
+    this.detail = detail;
+  }
+};
+
+// src/world-internal.ts
+var worldInternal = /* @__PURE__ */ Symbol.for(
+  "forgeax.ecs.worldInternal"
+);
+
+// src/errors.ts
+var StaleEntityError = class extends Error {
+  name = "StaleEntityError";
+  code = "stale-entity";
+  hint;
+  /** Component name involved in the operation (undefined when the operation does not target a specific component). */
+  component;
+  /** The component-level operation that triggered this error (e.g. 'get' / 'set' / 'add' / 'remove'). Entity-level operations like `despawn` are not surfaced here — see `EntityHandle` lifecycle errors. */
+  operation;
+  /** The generation the caller expected (from the entity handle). */
+  expectedGeneration;
+  /**
+   * The actual generation found in the entity pool. `-1` is the sentinel
+   * value for entities never allocated (slot was never occupied), as opposed
+   * to allocated-then-despawned entities which carry a real (incremented)
+   * generation number.
+   */
+  actualGeneration;
+  constructor(entityId, index, generation, enhanced) {
+    const hint = enhanced ? `Entity was despawned. Operation "${enhanced.operation}" on entity ${entityId}` + (enhanced.component ? ` (component: ${enhanced.component})` : "") + ` expected generation ${enhanced.expectedGeneration}, found ${enhanced.actualGeneration}. Check entity lifecycle before access.` : "Entity was despawned. Check entity lifecycle before access.";
+    super(
+      `Operation on stale entity handle.
+  entity: ${entityId} (index=${index}, generation=${generation})
+` + (enhanced ? `  operation: ${enhanced.operation}
+` : "") + (enhanced?.component ? `  component: ${enhanced.component}
+` : "") + `  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.component = enhanced?.component;
+    this.operation = enhanced?.operation;
+    this.expectedGeneration = enhanced?.expectedGeneration;
+    this.actualGeneration = enhanced?.actualGeneration;
+  }
+};
+var ManagedBufferOutOfBoundsError = class extends RangeError {
+  name = "ManagedBufferOutOfBoundsError";
+  code = "managed-buffer-out-of-bounds";
+  hint;
+  expected;
+  detail;
+  constructor(index, size) {
+    const hint = `Index ${index} is outside [0, ${size}). Check the field's 'buffer' / 'buffer<N>' declaration matches the access pattern.`;
+    const expected = `index in [0, ${size})`;
+    super(
+      `BufferPool: index out of bounds.
+  code: managed-buffer-out-of-bounds
+  index: ${index}
+  size: ${size}
+  expected: ${expected}
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { index, size };
+  }
+};
+var InstanceTransformsStrideMismatchError = class extends Error {
+  name = "InstanceTransformsStrideMismatchError";
+  code = "instance-transforms-stride-mismatch";
+  hint;
+  expected;
+  detail;
+  constructor(actualLength) {
+    const hint = `Instances.transforms length ${actualLength} violates stride 16 (mat4); ensure transforms.length % 16 === 0 before render frame; verify world.set / world.push call sites`;
+    const expectedStr = "actualLength % 16 === 0";
+    super(
+      `Instances.transforms: stride mismatch.
+  code: instance-transforms-stride-mismatch
+  actualLength: ${actualLength}
+  expectedStride: 16
+  hint: ${hint}`
+    );
+    this.hint = hint;
+    this.expected = expectedStr;
+    this.detail = { actualLength, expectedStride: 16 };
+  }
+};
+
+// src/component.ts
+var FIELD_SIZE_BYTES = {
+  f32: 4,
+  f64: 8,
+  i32: 4,
+  u32: 4,
+  i16: 2,
+  u16: 2,
+  i8: 1,
+  u8: 1,
+  bool: 1,
+  enum: 4,
+  ref: 4
+};
+var COMPONENT_OWNER_REGISTRY = /* @__PURE__ */ Symbol.for("forgeax.ecs.componentOwnerRegistry");
+var ownerSymbols = globalThis;
+var ownerRegistry = ownerSymbols[COMPONENT_OWNER_REGISTRY] ?? (() => {
+  const registry = {
+    nextId: 1,
+    ids: /* @__PURE__ */ new WeakMap(),
+    schemas: /* @__PURE__ */ new WeakMap()
+  };
+  ownerSymbols[COMPONENT_OWNER_REGISTRY] = registry;
+  return registry;
+})();
+function componentId(component) {
+  const id = ownerRegistry.ids.get(component);
+  if (id === void 0) throw new Error(`Component identity missing for '${component.name}'.`);
+  return id;
+}
+function componentSchema(component) {
+  const schema = ownerRegistry.schemas.get(component);
+  if (schema === void 0) throw new Error(`Component schema missing for '${component.name}'.`);
+  return schema;
+}
+var VIEW_CTORS = {
+  f32: Float32Array,
+  f64: Float64Array,
+  i32: Int32Array,
+  u32: Uint32Array,
+  i16: Int16Array,
+  u16: Uint16Array,
+  i8: Int8Array,
+  u8: Uint8Array,
+  bool: Uint8Array,
+  enum: Uint32Array,
+  ref: Uint32Array
+};
+function scalarRow(t) {
+  return {
+    byteSize: FIELD_SIZE_BYTES[t],
+    viewCtor: VIEW_CTORS[t],
+    storage: t,
+    isScalar: true,
+    // The scalar `ref` shares its key with the vocab `ref<T>` family; mark
+    // it as managed so the single row covers both.
+    isManaged: t === "ref",
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  };
+}
+Object.freeze({
+  f32: scalarRow("f32"),
+  f64: scalarRow("f64"),
+  i32: scalarRow("i32"),
+  u32: scalarRow("u32"),
+  i16: scalarRow("i16"),
+  u16: scalarRow("u16"),
+  i8: scalarRow("i8"),
+  u8: scalarRow("u8"),
+  bool: scalarRow("bool"),
+  enum: scalarRow("enum"),
+  ref: scalarRow("ref"),
+  entity: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: true,
+    isArray: false
+  },
+  string: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  buffer: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: true,
+    isEntityRef: false,
+    isArray: false
+  },
+  // feat-20260614-ecs-shared-component-and-unique-rename M3 (plan-strategy
+  // D-3): independent `'shared'` row, NOT a reuse of the `'ref'` (post-M2:
+  // `'unique<T>'` family) row. `isManaged: true` so write-barrier dispatch
+  // routes shared<T> fields through release on despawn / removeComponent /
+  // set-overwrite, but the M4 sub-dispatch in releaseManagedFieldOnRow will
+  // separate shared (rc--) from unique (direct slot drop) using the
+  // fieldType.startsWith('shared<') predicate. Keeping the meta key
+  // independent preserves the "meta key = release semantics" invariant
+  // (architecture-principles.md #1 SSOT).
+  shared: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: true,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: false
+  },
+  array: {
+    byteSize: 4,
+    viewCtor: Uint32Array,
+    storage: "u32",
+    isScalar: false,
+    isManaged: false,
+    isBuffer: false,
+    isEntityRef: false,
+    isArray: true
+  }
+});
+var ENTITY_NULL_RAW = 4294967295;
+
+// src/component-default-fallback.ts
+function typeDefault(fieldType) {
+  if (fieldType === "bool") return false;
+  if (fieldType === "entity") return ENTITY_NULL_RAW;
+  if (fieldType === "array<entity>") return [];
+  return 0;
+}
+function fillComponentDefaults(token, raw) {
+  const schema = componentSchema(token);
+  const layer2 = componentDefinition(token).defaults;
+  const out = /* @__PURE__ */ Object.create(null);
+  const rawObj = raw ?? void 0;
+  for (const fieldName of Object.keys(schema)) {
+    const fieldType = schema[fieldName];
+    if (fieldType === void 0) continue;
+    if (rawObj !== void 0 && fieldName in rawObj) {
+      out[fieldName] = rawObj[fieldName];
+      continue;
+    }
+    if (layer2 !== void 0 && fieldName in layer2) {
+      out[fieldName] = layer2[fieldName];
+      continue;
+    }
+    out[fieldName] = typeDefault(fieldType);
+  }
+  return out;
+}
+
+// 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;
+  world[worldInternal].markDerivedComponentChanges(componentId(component), [entity]);
+  return result;
+}
+function routeWorldError(world, error, context) {
+  world[worldInternal].routeError(error, context);
+}
+function createWorldProjection(world, options = {}) {
+  const componentById = options.components === void 0 ? void 0 : new Map(options.components.map((component) => [componentId(component), component]));
+  const componentIds = componentById === void 0 ? void 0 : new Set(componentById.keys());
+  let cursor = world[worldInternal].getChangeCursor();
+  const pollSince = (requestedCursor) => {
+    const result = world[worldInternal].readChangesSince(requestedCursor);
+    if (result.status === "overflow") {
+      cursor = result.cursor;
+      return { status: "rebuild", cursor, reason: "journal-overflow" };
+    }
+    cursor = result.cursor;
+    const changes = [];
+    for (const record of result.records) {
+      if (componentIds !== void 0 && record.kind !== "entity-removed" && (record.componentId === void 0 || !componentIds.has(record.componentId))) {
+        continue;
+      }
+      const component = record.componentId === void 0 ? void 0 : componentById?.get(record.componentId);
+      changes.push({
+        entity: record.entity,
+        kind: record.kind,
+        ...component === void 0 ? {} : { component },
+        ...record.componentId === void 0 ? {} : { componentId: record.componentId }
+      });
+    }
+    return { status: "delta", cursor, changes };
+  };
+  return {
+    get cursor() {
+      return cursor;
+    },
+    poll() {
+      return pollSince(cursor);
+    }
+  };
+}
+
+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