@galfus/engine 0.0.0-stage → 0.31.0-alpha

package/src/collision/components.ts

@@ -0,0 +1,211 @@
+import { assertValidLogicalId } from '@galfus/transport-types';
+import type { Component } from '../ecs/component';
+import { mat2d, mat4, vec2, vec3 } from '../math';
+
+export type ColliderShape2D =
+  | { type: 'rectangle'; halfExtents: [number, number] }
+  | { type: 'circle'; radius: number }
+  | { type: 'polygon'; vertices: [number, number][] };
+
+export type ColliderShape3D =
+  | { type: 'box'; halfExtents: [number, number, number] }
+  | { type: 'sphere'; radius: number }
+  | { type: 'plane'; halfExtents: [number, number] };
+
+export interface ColliderHit2D {
+  entityId: number;
+  colliderId: number;
+  point: [number, number];
+  normal: [number, number];
+  distance: number;
+  sensor: boolean;
+}
+
+export interface ColliderHit3D {
+  entityId: number;
+  colliderId: number;
+  point: [number, number, number];
+  normal: [number, number, number];
+  distance: number;
+  sensor: boolean;
+}
+
+export interface ColliderOptions {
+  /** Local affine matrix, column-major, relative to the entity's Model. */
+  matrix?: readonly number[];
+  active?: boolean;
+  sensor?: boolean;
+  layer?: number;
+  mask?: number;
+}
+export interface ColliderEntry<S> {
+  readonly colliderId: number;
+  readonly shape: S;
+  readonly matrix: readonly number[];
+  readonly boundingRadius?: number;
+  readonly active: boolean;
+  readonly sensor: boolean;
+  readonly layer: number;
+  readonly mask: number;
+}
+const IDENTITY_2D = Array.from(mat2d.create());
+const IDENTITY_3D = Array.from(mat4.create());
+function validPolygon(vertices: [number, number][]): boolean {
+  if (
+    vertices.length < 3 ||
+    vertices.some((p) => p.length !== 2 || p.some((v) => !Number.isFinite(v)))
+  )
+    return false;
+  let area = 0;
+  const cross = (a: [number, number], b: [number, number], c: [number, number]) =>
+    vec2.cross(vec2.subtract([0, 0], b, a), vec2.subtract([0, 0], c, a));
+  for (let i = 0; i < vertices.length; i++) {
+    const a = vertices[i]!;
+    const b = vertices[(i + 1) % vertices.length]!;
+    if (a[0] === b[0] && a[1] === b[1]) return false;
+    area += vec2.cross(a, b);
+    for (let j = i + 1; j < vertices.length; j++) {
+      if (j === i + 1 || (i === 0 && j === vertices.length - 1)) continue;
+      const c = vertices[j]!;
+      const d = vertices[(j + 1) % vertices.length]!;
+      const overlap =
+        Math.min(a[0], b[0]) <= Math.max(c[0], d[0]) &&
+        Math.min(c[0], d[0]) <= Math.max(a[0], b[0]) &&
+        Math.min(a[1], b[1]) <= Math.max(c[1], d[1]) &&
+        Math.min(c[1], d[1]) <= Math.max(a[1], b[1]);
+      if (overlap && cross(a, b, c) * cross(a, b, d) <= 0 && cross(c, d, a) * cross(c, d, b) <= 0)
+        return false;
+    }
+  }
+  return Math.abs(area) > 1e-9;
+}
+function validateShape(shape: ColliderShape2D | ColliderShape3D): void {
+  if (shape.type === 'circle' || shape.type === 'sphere') {
+    if (!Number.isFinite(shape.radius) || shape.radius <= 0)
+      throw new Error('Collider radius must be positive and finite.');
+  } else if (shape.type === 'polygon') {
+    if (!validPolygon(shape.vertices))
+      throw new Error('Collider polygon must be simple, non-degenerate, and finite.');
+  } else if (
+    shape.halfExtents.length !== (shape.type === 'box' ? 3 : 2) ||
+    shape.halfExtents.some((v) => !Number.isFinite(v) || v <= 0)
+  ) {
+    throw new Error('Collider half extents must be positive and finite.');
+  }
+}
+function computeBoundingRadius(shape: ColliderShape2D | ColliderShape3D): number {
+  if (shape.type === 'circle' || shape.type === 'sphere') return shape.radius;
+  if (shape.type === 'rectangle' || shape.type === 'plane')
+    return Math.hypot(shape.halfExtents[0], shape.halfExtents[1]);
+  if (shape.type === 'box')
+    return Math.hypot(shape.halfExtents[0], shape.halfExtents[1], shape.halfExtents[2]);
+  if (shape.type === 'polygon') {
+    let max = 0;
+    for (const [x, y] of shape.vertices) max = Math.max(max, Math.hypot(x, y));
+    return max;
+  }
+  return 0;
+}
+function validateMask(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+
+export function validateRay(
+  origin: readonly number[],
+  direction: readonly number[],
+  distance: number,
+  mask: number,
+  dimensions: 2 | 3
+): void {
+  if (
+    origin.length !== dimensions ||
+    direction.length !== dimensions ||
+    origin.some((v) => !Number.isFinite(v)) ||
+    direction.some((v) => !Number.isFinite(v)) ||
+    direction.every((v) => v === 0) ||
+    !Number.isFinite(
+      dimensions === 2
+        ? vec2.length([direction[0]!, direction[1]!])
+        : vec3.length([direction[0]!, direction[1]!, direction[2]!])
+    ) ||
+    !Number.isFinite(distance) ||
+    distance < 0 ||
+    !validateMask(mask)
+  ) {
+    throw new Error('Invalid collider ray query.');
+  }
+}
+
+export function validatePoint(point: readonly number[], mask: number): void {
+  if (point.length !== 2 || point.some((v) => !Number.isFinite(v)) || !validateMask(mask))
+    throw new Error('Invalid collider point query.');
+}
+const colliderEntries = Symbol('colliderEntries');
+abstract class ColliderComponent<S extends ColliderShape2D | ColliderShape3D> implements Component {
+  abstract readonly type: string;
+  readonly [colliderEntries] = new Map<number, ColliderEntry<S>>();
+  protected constructor(private readonly identity: readonly number[]) {}
+  add(colliderId: number, shape: S, options: ColliderOptions = {}): this {
+    assertValidLogicalId(colliderId, 'ColliderId');
+    if (this[colliderEntries].has(colliderId))
+      throw new Error(`Collider ${colliderId} already exists.`);
+    return this.set(colliderId, shape, options);
+  }
+  set(colliderId: number, shape: S, options: ColliderOptions = {}): this {
+    assertValidLogicalId(colliderId, 'ColliderId');
+    validateShape(shape);
+    const matrix = options.matrix ?? this.identity;
+    if (matrix.length !== this.identity.length || matrix.some((v) => !Number.isFinite(v)))
+      throw new Error('Invalid collider local matrix.');
+    if (
+      matrix.length === 16 &&
+      (matrix[3] !== 0 || matrix[7] !== 0 || matrix[11] !== 0 || matrix[15] !== 1)
+    )
+      throw new Error('Collider 3D matrix must be affine.');
+    const layer = options.layer ?? 0xffffffff;
+    const mask = options.mask ?? 0xffffffff;
+    if (!validateMask(layer) || !validateMask(mask))
+      throw new Error('Collider layer and mask must be unsigned 32-bit integers.');
+    this[colliderEntries].set(colliderId, {
+      colliderId,
+      shape: structuredClone(shape),
+      matrix: [...matrix],
+      boundingRadius: computeBoundingRadius(shape),
+      active: options.active ?? true,
+      sensor: options.sensor ?? false,
+      layer,
+      mask
+    });
+    return this;
+  }
+  remove(colliderId: number): boolean {
+    return this[colliderEntries].delete(colliderId);
+  }
+  getShapes(): readonly ColliderEntry<S>[] {
+    return Array.from(this[colliderEntries].values(), (entry) => structuredClone(entry));
+  }
+}
+/** Internal query path; entries are immutable and may be retained by snapshots. */
+export function getColliderEntries<S extends ColliderShape2D | ColliderShape3D>(
+  component: ColliderComponent<S>
+): IterableIterator<ColliderEntry<S>> {
+  return component[colliderEntries].values();
+}
+export class Collider2DComponent extends ColliderComponent<ColliderShape2D> {
+  readonly type = 'Collider2D';
+  constructor() {
+    super(IDENTITY_2D);
+  }
+}
+export class Collider3DComponent extends ColliderComponent<ColliderShape3D> {
+  readonly type = 'Collider3D';
+  constructor() {
+    super(IDENTITY_3D);
+  }
+}
+export function createCollider2D(): Collider2DComponent {
+  return new Collider2DComponent();
+}
+export function createCollider3D(): Collider3DComponent {
+  return new Collider3DComponent();
+}

package/src/collision/index.ts

@@ -0,0 +1,16 @@
+export {
+  Collider2DComponent,
+  Collider3DComponent,
+  createCollider2D,
+  createCollider3D,
+  validatePoint,
+  validateRay,
+  type ColliderEntry,
+  type ColliderHit2D,
+  type ColliderHit3D,
+  type ColliderOptions,
+  type ColliderShape2D,
+  type ColliderShape3D
+} from './components';
+export * from './query2d';
+export * from './query3d';

package/src/collision/query2d.ts

@@ -0,0 +1,167 @@
+import type { EcsWorld } from '../ecs/world';
+import { mat2d, type Mat2d, type ReadonlyMat2d, vec2 } from '../math';
+import type { Model2DComponent } from '../realm2d/components';
+import {
+  type Collider2DComponent,
+  type ColliderHit2D,
+  type ColliderShape2D,
+  getColliderEntries,
+  validatePoint,
+  validateRay
+} from './components';
+
+type Point = [number, number];
+const EDGE: Point = [0, 0];
+const POINT_A: Point = [0, 0];
+const POINT_B: Point = [0, 0];
+const RECT_VERTICES: Point[] = [
+  [0, 0],
+  [0, 0],
+  [0, 0],
+  [0, 0]
+];
+function vertices(shape: Exclude<ColliderShape2D, { type: 'circle' }>): Point[] {
+  if (shape.type === 'polygon') return shape.vertices;
+  const [x, y] = shape.halfExtents;
+  vec2.set(RECT_VERTICES[0]!, -x, -y);
+  vec2.set(RECT_VERTICES[1]!, x, -y);
+  vec2.set(RECT_VERTICES[2]!, x, y);
+  vec2.set(RECT_VERTICES[3]!, -x, y);
+  return RECT_VERTICES;
+}
+/** @internal Tests a point already transformed to collider-local coordinates. */
+export function containsColliderPoint2D(shape: ColliderShape2D, p: Point): boolean {
+  if (shape.type === 'circle') return vec2.dot(p, p) <= shape.radius ** 2;
+  if (shape.type === 'rectangle')
+    return Math.abs(p[0]) <= shape.halfExtents[0] && Math.abs(p[1]) <= shape.halfExtents[1];
+  const v = shape.vertices;
+  let result = false;
+  for (let i = 0; i < v.length; i++) {
+    const a = v[i]!;
+    const b = v[(i + 1) % v.length]!;
+    if (
+      Math.abs(vec2.cross(vec2.subtract(EDGE, b, a), vec2.subtract(POINT_A, p, a))) <= 1e-7 &&
+      vec2.dot(POINT_A, vec2.subtract(POINT_B, p, b)) <= 1e-7
+    )
+      return true;
+    if (
+      a[1] > p[1] !== b[1] > p[1] &&
+      p[0] < ((b[0] - a[0]) * (p[1] - a[1])) / (b[1] - a[1]) + a[0]
+    )
+      result = !result;
+  }
+  return result;
+}
+function intersect(
+  shape: ColliderShape2D,
+  o: Point,
+  d: Point,
+  max: number
+): { distance: number; normal: Point } | undefined {
+  if (containsColliderPoint2D(shape, o)) return { distance: 0, normal: [0, 0] };
+  if (shape.type === 'circle') {
+    const a = vec2.dot(d, d);
+    const b = vec2.dot(o, d);
+    const disc = b * b - a * (vec2.dot(o, o) - shape.radius ** 2);
+    if (a <= 0 || disc < 0) return undefined;
+    const distance = (-b - Math.sqrt(disc)) / a;
+    if (distance < 0 || distance > max) return undefined;
+    const point: Point = [0, 0];
+    vec2.add(point, o, vec2.scale(point, d, distance));
+    return { distance, normal: vec2.normalize(point, point) };
+  }
+  const v = vertices(shape);
+  let area = 0;
+  let hit: { distance: number; normal: Point } | undefined;
+  for (let i = 0; i < v.length; i++) area += vec2.cross(v[i]!, v[(i + 1) % v.length]!);
+  for (let i = 0; i < v.length; i++) {
+    const a = v[i]!;
+    const edge = vec2.subtract(EDGE, v[(i + 1) % v.length]!, a);
+    const denominator = vec2.cross(d, edge);
+    if (Math.abs(denominator) < 1e-10) continue;
+    const delta = vec2.subtract(POINT_A, a, o);
+    const distance = vec2.cross(delta, edge) / denominator;
+    const along = vec2.cross(delta, d) / denominator;
+    if (
+      distance < 0 ||
+      distance > max ||
+      along < 0 ||
+      along > 1 ||
+      (hit && distance >= hit.distance)
+    )
+      continue;
+    const sign = area > 0 ? 1 : -1;
+    const normal: Point = [sign * edge[1], -sign * edge[0]];
+    hit = { distance, normal: vec2.normalize(normal, normal) };
+  }
+  return hit;
+}
+function eachCollider(
+  world: EcsWorld,
+  mask: number,
+  visit: (
+    entityId: number,
+    id: number,
+    shape: ColliderShape2D,
+    inverse: Mat2d,
+    sensor: boolean
+  ) => void
+): void {
+  const seen = new Set<number>();
+  const combined = mat2d.create();
+  const inverse = mat2d.create();
+  for (const [entityId, component] of world.components.entries<Collider2DComponent>('Collider2D')) {
+    const model = world.getComponent<Model2DComponent>(entityId, 'Model2D');
+    if (!model) continue;
+    for (const entry of getColliderEntries(component)) {
+      if (seen.has(entry.colliderId))
+        throw new Error(`Collider ID ${entry.colliderId} is used by more than one entity.`);
+      seen.add(entry.colliderId);
+      if (!entry.active || (entry.layer & mask) === 0) continue;
+      mat2d.multiply(combined, model.worldMatrix, entry.matrix as unknown as ReadonlyMat2d);
+      if (mat2d.invert(inverse, combined) && inverse.every(Number.isFinite))
+        visit(entityId, entry.colliderId, entry.shape, inverse, entry.sensor);
+    }
+  }
+}
+export function queryPoint2D(world: EcsWorld, point: Point, mask = 0xffffffff): ColliderHit2D[] {
+  validatePoint(point, mask);
+  const hits: ColliderHit2D[] = [];
+  const p: Point = [0, 0];
+  eachCollider(world, mask, (entityId, colliderId, shape, m, sensor) => {
+    vec2.transformMat2d(p, point, m);
+    if (containsColliderPoint2D(shape, p))
+      hits.push({ entityId, colliderId, point: [...point], normal: [0, 0], distance: 0, sensor });
+  });
+  return hits.sort((a, b) => a.colliderId - b.colliderId);
+}
+export function raycast2D(
+  world: EcsWorld,
+  origin: Point,
+  direction: Point,
+  maxDistance: number,
+  mask = 0xffffffff
+): ColliderHit2D[] {
+  validateRay(origin, direction, maxDistance, mask, 2);
+  const d = vec2.normalize([0, 0], direction);
+  const hits: ColliderHit2D[] = [];
+  const o: Point = [0, 0];
+  const local: Point = [0, 0];
+  eachCollider(world, mask, (entityId, colliderId, shape, m, sensor) => {
+    vec2.transformMat2d(o, origin, m);
+    vec2.transformDirectionMat2d(local, d, m);
+    const hit = intersect(shape, o, local, maxDistance);
+    if (!hit) return;
+    const normal = vec2.transformNormalMat2d([0, 0], hit.normal, m);
+    vec2.normalize(normal, normal);
+    hits.push({
+      entityId,
+      colliderId,
+      point: vec2.add([0, 0], origin, vec2.scale([0, 0], d, hit.distance)),
+      normal,
+      distance: hit.distance,
+      sensor
+    });
+  });
+  return hits.sort((a, b) => a.distance - b.distance || a.colliderId - b.colliderId);
+}

package/src/collision/query3d.ts

@@ -0,0 +1,170 @@
+import type { EcsWorld } from '../ecs/world';
+import { mat4, type ReadonlyMat4, type ReadonlyVec3, vec3 } from '../math';
+import type { Model3DComponent } from '../realm3d/components';
+import {
+  type Collider3DComponent,
+  type ColliderHit3D,
+  type ColliderShape3D,
+  getColliderEntries,
+  validateRay
+} from './components';
+
+type Point = [number, number, number];
+export interface LocalRayHit3D {
+  distance: number;
+  normal: Point;
+  uv?: [number, number];
+}
+/** @internal Tests a ray already transformed to collider-local coordinates. */
+export function intersectCollider3D(
+  shape: ColliderShape3D,
+  o: ReadonlyVec3,
+  d: ReadonlyVec3,
+  max: number,
+  out: LocalRayHit3D = { distance: 0, normal: [0, 0, 0] }
+): LocalRayHit3D | undefined {
+  const normal = out.normal;
+  normal[0] = 0;
+  normal[1] = 0;
+  normal[2] = 0;
+  if (shape.type === 'sphere') {
+    const a = vec3.dot(d, d);
+    const b = vec3.dot(o, d);
+    const c = vec3.dot(o, o) - shape.radius ** 2;
+    if (c <= 0) {
+      out.distance = 0;
+      return out;
+    }
+    const discriminant = b * b - a * c;
+    if (a <= 0 || discriminant < 0) return undefined;
+    const distance = (-b - Math.sqrt(discriminant)) / a;
+    if (distance < 0 || distance > max) return undefined;
+    vec3.scaleAndAdd(normal, o, d, distance);
+    vec3.normalize(normal, normal);
+    out.distance = distance;
+    return out;
+  }
+  if (shape.type === 'plane') {
+    if (Math.abs(d[2]) < 1e-10) return undefined;
+    const distance = -o[2] / d[2];
+    vec3.scaleAndAdd(normal, o, d, distance);
+    if (
+      distance < 0 ||
+      distance > max ||
+      Math.abs(normal[0]) > shape.halfExtents[0] ||
+      Math.abs(normal[1]) > shape.halfExtents[1]
+    )
+      return undefined;
+    const u = (normal[0] + shape.halfExtents[0]) / (2 * shape.halfExtents[0]);
+    const v = (shape.halfExtents[1] - normal[1]) / (2 * shape.halfExtents[1]);
+    out.uv = [Math.max(0, Math.min(1, u)), Math.max(0, Math.min(1, v))];
+    normal[0] = 0;
+    normal[1] = 0;
+    normal[2] = d[2] < 0 ? 1 : -1;
+    out.distance = distance;
+    return out;
+  }
+  const h = shape.halfExtents;
+  if (Math.abs(o[0]) <= h[0] && Math.abs(o[1]) <= h[1] && Math.abs(o[2]) <= h[2]) {
+    out.distance = 0;
+    return out;
+  }
+  let near = 0;
+  let far = max;
+  for (let i = 0; i < 3; i++) {
+    const v = d[i]!;
+    const position = o[i]!;
+    const half = h[i]!;
+    if (Math.abs(v) < 1e-10) {
+      if (Math.abs(position) > half) return undefined;
+      continue;
+    }
+    let a = (-half - position) / v;
+    let b = (half - position) / v;
+    let sign = -1;
+    if (a > b) {
+      [a, b] = [b, a];
+      sign = 1;
+    }
+    if (a > near) {
+      near = a;
+      normal[0] = 0;
+      normal[1] = 0;
+      normal[2] = 0;
+      normal[i] = sign;
+    }
+    far = Math.min(far, b);
+    if (near > far) return undefined;
+  }
+  out.distance = near;
+  return out;
+}
+export function raycast3D(
+  world: EcsWorld,
+  origin: Point,
+  direction: Point,
+  maxDistance: number,
+  mask = 0xffffffff
+): ColliderHit3D[] {
+  validateRay(origin, direction, maxDistance, mask, 3);
+  const d = vec3.normalize([0, 0, 0], direction);
+  const hits: ColliderHit3D[] = [];
+  const seen = new Set<number>();
+  const combined = mat4.create();
+  const m = mat4.create();
+  const o: Point = [0, 0, 0];
+  const local: Point = [0, 0, 0];
+  const localCenter: Point = [0, 0, 0];
+  const worldCenter: Point = [0, 0, 0];
+  const intersection: LocalRayHit3D = { distance: 0, normal: [0, 0, 0] };
+  for (const [entityId, component] of world.components.entries<Collider3DComponent>('Collider3D')) {
+    const model = world.getComponent<Model3DComponent>(entityId, 'Model3D');
+    if (!model) continue;
+    for (const entry of getColliderEntries(component)) {
+      if (seen.has(entry.colliderId))
+        throw new Error(`Collider ID ${entry.colliderId} is used by more than one entity.`);
+      seen.add(entry.colliderId);
+      if (!entry.active || (entry.layer & mask) === 0) continue;
+
+      const rLocal = entry.boundingRadius;
+      if (rLocal !== undefined && rLocal > 0) {
+        localCenter[0] = entry.matrix[12]!;
+        localCenter[1] = entry.matrix[13]!;
+        localCenter[2] = entry.matrix[14]!;
+        vec3.transformMat4(worldCenter, localCenter, model.worldMatrix);
+
+        const wm = model.worldMatrix;
+        const sx = wm[0]! * wm[0]! + wm[1]! * wm[1]! + wm[2]! * wm[2]!;
+        const sy = wm[4]! * wm[4]! + wm[5]! * wm[5]! + wm[6]! * wm[6]!;
+        const sz = wm[8]! * wm[8]! + wm[9]! * wm[9]! + wm[10]! * wm[10]!;
+        const rWorld = rLocal * Math.sqrt(Math.max(sx, sy, sz));
+
+        const vx = worldCenter[0] - origin[0]!;
+        const vy = worldCenter[1] - origin[1]!;
+        const vz = worldCenter[2] - origin[2]!;
+        const proj = vx * d[0]! + vy * d[1]! + vz * d[2]!;
+        if (proj < -rWorld || proj > maxDistance + rWorld) continue;
+        const perpSq = vx * vx + vy * vy + vz * vz - proj * proj;
+        if (perpSq > rWorld * rWorld) continue;
+      }
+
+      mat4.multiply(combined, model.worldMatrix, entry.matrix as unknown as ReadonlyMat4);
+      if (!mat4.invert(m, combined) || !m.every(Number.isFinite)) continue;
+      vec3.transformMat4(o, origin, m);
+      vec3.transformDirectionMat4(local, d, m);
+      const hit = intersectCollider3D(entry.shape, o, local, maxDistance, intersection);
+      if (!hit) continue;
+      const normal = vec3.transformNormalMat4([0, 0, 0], hit.normal, m);
+      vec3.normalize(normal, normal);
+      hits.push({
+        entityId,
+        colliderId: entry.colliderId,
+        point: vec3.add([0, 0, 0], origin, vec3.scale([0, 0, 0], d, hit.distance)),
+        normal,
+        distance: hit.distance,
+        sensor: entry.sensor
+      });
+    }
+  }
+  return hits.sort((a, b) => a.distance - b.distance || a.colliderId - b.colliderId);
+}

package/src/ecs/component.ts

@@ -0,0 +1,130 @@
+/**
+ * Component contracts and storage registry.
+ */
+
+import type { EntityId } from './entity';
+
+/**
+ * Base contract for any component attached to an entity.
+ */
+export interface Component {
+  readonly type: string;
+}
+
+/**
+ * High-performance storage managing component instances indexed by entity ID and type.
+ */
+export class ComponentStore {
+  // Map of componentType -> Map of entityId -> Component
+  private readonly _byType = new Map<string, Map<EntityId, Component>>();
+  // Map of entityId -> Map of componentType -> Component
+  private readonly _byEntity = new Map<EntityId, Map<string, Component>>();
+
+  /**
+   * Attaches or replaces a component for the given entity.
+   */
+  set(entityId: EntityId, component: Component): void {
+    const type = component.type;
+
+    let typeMap = this._byType.get(type);
+    if (!typeMap) {
+      typeMap = new Map<EntityId, Component>();
+      this._byType.set(type, typeMap);
+    }
+    typeMap.set(entityId, component);
+
+    let entityMap = this._byEntity.get(entityId);
+    if (!entityMap) {
+      entityMap = new Map<string, Component>();
+      this._byEntity.set(entityId, entityMap);
+    }
+    entityMap.set(type, component);
+  }
+
+  /**
+   * Retrieves a component for the specified entity by type name.
+   */
+  get<T extends Component = Component>(entityId: EntityId, componentType: string): T | undefined {
+    return this._byType.get(componentType)?.get(entityId) as T | undefined;
+  }
+
+  /**
+   * Checks if an entity possesses a component of the specified type.
+   */
+  has(entityId: EntityId, componentType: string): boolean {
+    return this._byType.get(componentType)?.has(entityId) ?? false;
+  }
+
+  /** Iterates existing components without creating an array or copying the index. */
+  *entries<T extends Component = Component>(
+    componentType: string
+  ): IterableIterator<[EntityId, T]> {
+    const entries = this._byType.get(componentType);
+    if (entries) yield* entries as Map<EntityId, T>;
+  }
+
+  /** Iterates entity IDs without copying the component index. */
+  *entityIds(componentType: string): IterableIterator<EntityId> {
+    const entries = this._byType.get(componentType);
+    if (entries) yield* entries.keys();
+  }
+
+  /**
+   * Detaches a component of the specified type from an entity.
+   *
+   * @returns True if the component existed and was removed, false otherwise.
+   */
+  delete(entityId: EntityId, componentType: string): boolean {
+    const typeMap = this._byType.get(componentType);
+    const removedFromType = typeMap ? typeMap.delete(entityId) : false;
+
+    const entityMap = this._byEntity.get(entityId);
+    if (entityMap) {
+      entityMap.delete(componentType);
+      if (entityMap.size === 0) {
+        this._byEntity.delete(entityId);
+      }
+    }
+
+    return removedFromType;
+  }
+
+  /**
+   * Returns all components attached to the specified entity.
+   */
+  getAllForEntity(entityId: EntityId): Component[] {
+    const entityMap = this._byEntity.get(entityId);
+    if (!entityMap) return [];
+    return Array.from(entityMap.values());
+  }
+
+  /**
+   * Detaches and removes all components for a given entity (called on entity destruction).
+   */
+  removeAllForEntity(entityId: EntityId): void {
+    const entityMap = this._byEntity.get(entityId);
+    if (!entityMap) return;
+
+    for (const type of entityMap.keys()) {
+      this._byType.get(type)?.delete(entityId);
+    }
+    this._byEntity.delete(entityId);
+  }
+
+  /**
+   * Returns all EntityIds possessing a component of the specified type.
+   */
+  getEntitiesWith(componentType: string): Set<EntityId> {
+    const typeMap = this._byType.get(componentType);
+    if (!typeMap) return new Set();
+    return new Set(typeMap.keys());
+  }
+
+  /**
+   * Clears all stored components.
+   */
+  clear(): void {
+    this._byType.clear();
+    this._byEntity.clear();
+  }
+}