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

package/src/query/query.ts

@@ -0,0 +1,606 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type Component,
+  type ComponentId,
+  type ComponentSchema,
+  componentId,
+  componentSchema,
+  isManagedField,
+  type ShapeOf,
+  type TypedArrayFor,
+} from '../component';
+import { Disabled, Entity } from '../entity';
+import type { EntityHandle } from '../entity-handle';
+import {
+  QueryDataRequiresFieldsError,
+  QueryDescriptorConflictError,
+  QueryIterationActiveError,
+  QueryIterationInvalidatedError,
+  QuerySpanUnavailableError,
+  type QuerySpanUnavailableReason,
+} from '../errors';
+import type { Archetype, ArchetypeId } from '../storage/archetype';
+import type { ArchetypeGraph } from '../storage/archetype-graph';
+import { sparseTagIndex } from '../storage/change-detection';
+import type { FieldView, ManagedColumnReader } from '../storage/column';
+import type { Table } from '../storage/table';
+import { type WorldInternal, worldInternal } from '../world-internal';
+
+export interface QueryDescriptor<
+  R extends readonly Component[] = readonly Component[],
+  W extends readonly Component[] = readonly Component[],
+  O extends readonly Component[] = readonly Component[],
+> {
+  readonly read?: R;
+  readonly write?: W;
+  readonly optional?: O;
+  readonly with?: readonly Component[];
+  readonly without?: readonly Component[];
+  readonly changed?: readonly Component[];
+  readonly added?: readonly Component[];
+}
+
+export type ReadonlyRowShape<C> =
+  C extends Component<string, infer S> ? Readonly<ShapeOf<S>> : never;
+export type MutableRowShape<C> =
+  C extends Component<string, infer S>
+    ? { -readonly [K in keyof ShapeOf<S>]: ShapeOf<S>[K] }
+    : never;
+
+type ColumnShapeForSchema<S extends ComponentSchema> = {
+  [K in keyof S]: TypedArrayFor<S[K]>;
+};
+
+export type ReadonlyColumnShape<C> =
+  C extends Component<string, infer S> ? Readonly<ColumnShapeForSchema<S>> : never;
+export type MutableColumnShape<C> =
+  C extends Component<string, infer S>
+    ? { -readonly [K in keyof ColumnShapeForSchema<S>]: ColumnShapeForSchema<S>[K] }
+    : never;
+
+export interface QueryRow<
+  R extends readonly Component[] = readonly Component[],
+  W extends readonly Component[] = readonly Component[],
+  O extends readonly Component[] = readonly Component[],
+> {
+  readonly entity: EntityHandle;
+  /** Test component presence without materialising its row object. */
+  has(component: R[number] | W[number] | O[number]): boolean;
+  get<C extends R[number]>(component: C): ReadonlyRowShape<C>;
+  get<C extends O[number]>(component: C): ReadonlyRowShape<C> | undefined;
+  mut<C extends W[number]>(component: C): MutableRowShape<C>;
+}
+
+export interface QuerySpan<
+  R extends readonly Component[] = readonly Component[],
+  W extends readonly Component[] = readonly Component[],
+> {
+  /** Packed entity identities for this contiguous table range. */
+  readonly entities: Readonly<Uint32Array>;
+  readonly length: number;
+  get<C extends R[number]>(component: C): ReadonlyColumnShape<C>;
+  mut<C extends W[number]>(component: C): MutableColumnShape<C>;
+}
+
+export interface Query<
+  R extends readonly Component[] = readonly Component[],
+  W extends readonly Component[] = readonly Component[],
+  O extends readonly Component[] = readonly Component[],
+> extends Iterable<QueryRow<R, W, O>> {
+  /**
+   * Read one known entity without iterating the query's matching tables.
+   * Structural descriptor constraints are applied; temporal `changed` and
+   * `added` filters are intentionally not evaluated because this is an
+   * identity-addressed read, not a journal drain.
+   */
+  at(entity: EntityHandle): QueryRow<R, W, O> | undefined;
+  spans(): Result<Iterable<QuerySpan<R, W>>, QuerySpanUnavailableError>;
+  combinations(k?: number): Iterable<readonly QueryRow<R, W, O>[]>;
+}
+
+export type QueryCreationError = QueryDescriptorConflictError | QueryDataRequiresFieldsError;
+
+interface WorldQueryAccess {
+  readonly [worldInternal]: WorldInternal;
+}
+
+interface CompiledDescriptor<
+  R extends readonly Component[],
+  W extends readonly Component[],
+  O extends readonly Component[],
+> {
+  readonly descriptor: QueryDescriptor<R, W, O>;
+  readonly requiredIds: readonly ComponentId[];
+  readonly withoutIds: readonly ComponentId[];
+  readonly changedIds: readonly ComponentId[];
+  readonly addedIds: readonly ComponentId[];
+  readonly sparseRoute: boolean;
+}
+
+type Role = 'read' | 'write' | 'optional' | 'with' | 'without';
+
+function compileDescriptor<
+  const R extends readonly Component[],
+  const W extends readonly Component[],
+  const O extends readonly Component[],
+>(descriptor: QueryDescriptor<R, W, O>): Result<CompiledDescriptor<R, W, O>, QueryCreationError> {
+  const read = descriptor.read ?? ([] as unknown as R);
+  const write = descriptor.write ?? ([] as unknown as W);
+  const optional = descriptor.optional ?? ([] as unknown as O);
+  const withComponents = descriptor.with ?? [];
+  const withoutComponents = [...(descriptor.without ?? [])];
+  const roles = new Map<Component, Role[]>();
+  const addRole = (component: Component, role: Role): void => {
+    const current = roles.get(component);
+    if (current === undefined) roles.set(component, [role]);
+    else current.push(role);
+  };
+  for (const component of read) addRole(component, 'read');
+  for (const component of write) addRole(component, 'write');
+  for (const component of optional) addRole(component, 'optional');
+  for (const component of withComponents) addRole(component, 'with');
+  for (const component of withoutComponents) addRole(component, 'without');
+
+  for (const [component, componentRoles] of roles) {
+    if (componentRoles.length > 1) {
+      return err(new QueryDescriptorConflictError(component.name, componentRoles));
+    }
+  }
+  for (const component of [...read, ...write, ...optional]) {
+    if (Object.keys(componentSchema(component)).length === 0) {
+      return err(new QueryDataRequiresFieldsError(component.name));
+    }
+  }
+
+  const required = [
+    ...read,
+    ...write,
+    ...withComponents,
+    ...(descriptor.changed ?? []),
+    ...(descriptor.added ?? []),
+  ];
+  const requiredIds = [...new Set(required.map((component) => componentId(component)))];
+  const withoutIds = [...new Set(withoutComponents.map((component) => componentId(component)))];
+  if (!requiredIds.includes(componentId(Disabled)) && !withoutIds.includes(componentId(Disabled))) {
+    withoutIds.push(componentId(Disabled));
+  }
+  return ok({
+    descriptor,
+    requiredIds,
+    withoutIds,
+    changedIds: [...new Set((descriptor.changed ?? []).map((component) => componentId(component)))],
+    addedIds: [...new Set((descriptor.added ?? []).map((component) => componentId(component)))],
+    sparseRoute: [
+      ...required,
+      ...withoutComponents,
+      ...(descriptor.changed ?? []),
+      ...(descriptor.added ?? []),
+    ].some((component) => component.storage === 'sparse'),
+  });
+}
+
+class QueryRowFacade<
+  R extends readonly Component[],
+  W extends readonly Component[],
+  O extends readonly Component[],
+> implements QueryRow<R, W, O>
+{
+  entity = 0 as EntityHandle;
+  private archetype: Archetype | undefined;
+
+  constructor(private readonly world: WorldQueryAccess) {}
+
+  bind(entity: EntityHandle, archetype: Archetype): this {
+    this.entity = entity;
+    this.archetype = archetype;
+    return this;
+  }
+
+  snapshot(): QueryRowFacade<R, W, O> {
+    if (this.archetype === undefined) throw new Error('Query row is not bound.');
+    return new QueryRowFacade<R, W, O>(this.world).bind(this.entity, this.archetype);
+  }
+
+  has(component: R[number] | W[number] | O[number]): boolean {
+    return (
+      this.archetype?.components.some(
+        (candidate) => componentId(candidate) === componentId(component),
+      ) === true
+    );
+  }
+
+  get<C extends R[number]>(component: C): ReadonlyRowShape<C>;
+  get<C extends O[number]>(component: C): ReadonlyRowShape<C> | undefined;
+  get(component: Component): Record<string, unknown> | undefined {
+    if (
+      !this.archetype?.components.some(
+        (candidate) => componentId(candidate) === componentId(component),
+      )
+    ) {
+      return undefined;
+    }
+    const result = this.world[worldInternal].getQueryRow(this.entity, component);
+    if (!result.ok) throw result.error;
+    return result.value;
+  }
+
+  mut<C extends W[number]>(component: C): MutableRowShape<C> {
+    const current = this.get(component);
+    if (current === undefined) throw new Error(`Query row lacks ${component.name}.`);
+    this.world[worldInternal].markComponentChanged(this.entity, componentId(component));
+    return new Proxy(current, {
+      set: (target, property, value) => {
+        if (typeof property !== 'string') return false;
+        const result = this.world[worldInternal].setQueryRow(this.entity, component, {
+          [property]: value,
+        });
+        if (!result.ok) throw result.error;
+        (target as Record<string, unknown>)[property] = value;
+        return true;
+      },
+    }) as MutableRowShape<C>;
+  }
+}
+
+class QuerySpanFacade<R extends readonly Component[], W extends readonly Component[]>
+  implements QuerySpan<R, W>
+{
+  readonly entities: Readonly<Uint32Array>;
+
+  constructor(
+    private readonly world: WorldQueryAccess,
+    private readonly table: Table,
+    private readonly rowStart: number,
+    readonly length: number,
+  ) {
+    const entityColumn = table.storage.get(componentId(Entity))?.fields.get('self');
+    this.entities = (entityColumn?.view.subarray(rowStart, rowStart + length) ??
+      new Uint32Array(0)) as Readonly<Uint32Array>;
+  }
+
+  get<C extends R[number]>(component: C): ReadonlyColumnShape<C> {
+    return buildColumnShape(
+      this.table,
+      component,
+      this.rowStart,
+      this.length,
+    ) as ReadonlyColumnShape<C>;
+  }
+
+  mut<C extends W[number]>(component: C): MutableColumnShape<C> {
+    this.world[worldInternal].markComponentRangeChanged(
+      this.table,
+      componentId(component),
+      this.rowStart,
+      this.length,
+    );
+    return buildColumnShape(
+      this.table,
+      component,
+      this.rowStart,
+      this.length,
+    ) as MutableColumnShape<C>;
+  }
+}
+
+function makeManagedColumnReader(
+  view: FieldView,
+  length: number,
+  fieldType: string,
+): ManagedColumnReader<string> {
+  const slots = view.subarray(0, length);
+  return Object.freeze({
+    length,
+    get(i: number): number {
+      return slots[i] ?? 0;
+    },
+    __managed: fieldType,
+  });
+}
+
+function buildColumnShape(
+  table: Table,
+  component: Component,
+  rowStart: number,
+  rowCount: number,
+): Record<string, FieldView | ManagedColumnReader<string>> {
+  const shape: Record<string, FieldView | ManagedColumnReader<string>> = {};
+  const fields = table.storage.get(componentId(component))?.fields;
+  if (fields === undefined) return shape;
+  for (const [fieldName, column] of fields) {
+    const start = rowStart * column.arity;
+    const end = start + rowCount * column.arity;
+    const view = column.view.subarray(start, end);
+    const fieldType = componentSchema(component)[fieldName];
+    shape[fieldName] =
+      fieldType !== undefined && isManagedField(fieldType)
+        ? makeManagedColumnReader(view, view.length, fieldType)
+        : view;
+  }
+  return shape;
+}
+
+class ExecutableQuery<
+  R extends readonly Component[],
+  W extends readonly Component[],
+  O extends readonly Component[],
+> implements Query<R, W, O>
+{
+  private matchedArchetypes: ArchetypeId[] = [];
+  private matchedTables: number[] = [];
+  private lastGraphGeneration = -1;
+  private lastObservedEpoch = 0;
+  private active = false;
+
+  constructor(
+    private readonly world: WorldQueryAccess,
+    private readonly compiled: CompiledDescriptor<R, W, O>,
+  ) {}
+
+  [Symbol.iterator](): Iterator<QueryRow<R, W, O>> {
+    this.beginIteration();
+    this.refreshMatches();
+    const structureEpoch = this.world[worldInternal].getStructureEpoch();
+    const upperBound = this.world[worldInternal].getMutationEpoch();
+    const row = new QueryRowFacade<R, W, O>(this.world);
+    let archetypeIndex = 0;
+    let tableIndex = 0;
+    let rowIndex = 0;
+    let finished = false;
+
+    const close = (commit: boolean): void => {
+      if (finished) return;
+      finished = true;
+      this.active = false;
+      if (commit) this.lastObservedEpoch = upperBound;
+    };
+
+    return {
+      next: (): IteratorResult<QueryRow<R, W, O>> => {
+        if (finished) return { done: true, value: undefined };
+        if (this.world[worldInternal].getStructureEpoch() !== structureEpoch) {
+          close(false);
+          throw new QueryIterationInvalidatedError(
+            structureEpoch,
+            this.world[worldInternal].getStructureEpoch(),
+          );
+        }
+        if (!this.compiled.sparseRoute) {
+          while (tableIndex < this.matchedTables.length) {
+            const table =
+              this.world[worldInternal].getGraph().tables[this.matchedTables[tableIndex] ?? -1];
+            if (table === undefined || rowIndex >= table.size) {
+              tableIndex += 1;
+              rowIndex = 0;
+              continue;
+            }
+            const currentTableRow = rowIndex++;
+            const entityColumn = table.storage.get(componentId(Entity))?.fields.get('self');
+            if (entityColumn === undefined) continue;
+            const entity = (entityColumn.view[currentTableRow] ?? 0) as EntityHandle;
+            if (!this.changeMatches(entity, table, currentTableRow, upperBound)) continue;
+            const recordArchetype = this.world[worldInternal].getEntityArchetype(entity);
+            if (recordArchetype === undefined) continue;
+            return { done: false, value: row.bind(entity, recordArchetype) };
+          }
+          close(true);
+          return { done: true, value: undefined };
+        }
+        while (archetypeIndex < this.matchedArchetypes.length) {
+          const archetype =
+            this.world[worldInternal].getGraph().archetypes[
+              this.matchedArchetypes[archetypeIndex] ?? -1
+            ];
+          if (archetype === undefined || rowIndex >= archetype.size) {
+            archetypeIndex += 1;
+            rowIndex = 0;
+            continue;
+          }
+          const currentArchetypeRow = rowIndex++;
+          const currentTableRow = archetype.rows[currentArchetypeRow] ?? 0;
+          const table = this.world[worldInternal].getGraph().tables[archetype.tableId];
+          if (table === undefined) continue;
+          const entityColumn = table.storage.get(componentId(Entity))?.fields.get('self');
+          if (entityColumn === undefined) continue;
+          const entity = (entityColumn.view[currentTableRow] ?? 0) as EntityHandle;
+          if (!this.changeMatches(entity, table, currentTableRow, upperBound)) continue;
+          return { done: false, value: row.bind(entity, archetype) };
+        }
+        close(true);
+        return { done: true, value: undefined };
+      },
+      return: (): IteratorResult<QueryRow<R, W, O>> => {
+        close(false);
+        return { done: true, value: undefined };
+      },
+    };
+  }
+
+  at(entity: EntityHandle): QueryRow<R, W, O> | undefined {
+    const archetype = this.world[worldInternal].getEntityArchetype(entity);
+    if (archetype === undefined || !this.archetypeMatches(archetype)) return undefined;
+    return new QueryRowFacade<R, W, O>(this.world).bind(entity, archetype).snapshot();
+  }
+
+  spans(): Result<Iterable<QuerySpan<R, W>>, QuerySpanUnavailableError> {
+    const reason = this.spanUnavailableReason();
+    if (reason !== undefined) return err(new QuerySpanUnavailableError(reason));
+    const query = this;
+    return ok({
+      [Symbol.iterator](): Iterator<QuerySpan<R, W>> {
+        query.beginIteration();
+        query.refreshMatches();
+        const structureEpoch = query.world[worldInternal].getStructureEpoch();
+        const upperBound = query.world[worldInternal].getMutationEpoch();
+        let index = 0;
+        let finished = false;
+        const close = (commit: boolean): void => {
+          if (finished) return;
+          finished = true;
+          query.active = false;
+          if (commit) query.lastObservedEpoch = upperBound;
+        };
+        return {
+          next(): IteratorResult<QuerySpan<R, W>> {
+            if (finished) return { done: true, value: undefined };
+            if (query.world[worldInternal].getStructureEpoch() !== structureEpoch) {
+              close(false);
+              throw new QueryIterationInvalidatedError(
+                structureEpoch,
+                query.world[worldInternal].getStructureEpoch(),
+              );
+            }
+            while (index < query.matchedTables.length) {
+              const table =
+                query.world[worldInternal].getGraph().tables[query.matchedTables[index++] ?? -1];
+              if (table === undefined || table.size === 0) continue;
+              return {
+                done: false,
+                value: new QuerySpanFacade<R, W>(query.world, table, 0, table.size),
+              };
+            }
+            close(true);
+            return { done: true, value: undefined };
+          },
+          return(): IteratorResult<QuerySpan<R, W>> {
+            close(false);
+            return { done: true, value: undefined };
+          },
+        };
+      },
+    });
+  }
+
+  combinations(k = 2): Iterable<readonly QueryRow<R, W, O>[]> {
+    const query = this;
+    return {
+      *[Symbol.iterator](): Iterator<readonly QueryRow<R, W, O>[]> {
+        if (!Number.isInteger(k) || k < 1) return;
+        const previousObservedEpoch = query.lastObservedEpoch;
+        const structureEpoch = query.world[worldInternal].getStructureEpoch();
+        const rows: QueryRow<R, W, O>[] = [];
+        for (const row of query) {
+          rows.push((row as QueryRowFacade<R, W, O>).snapshot());
+        }
+        query.active = true;
+        let completed = false;
+        try {
+          if (k <= rows.length) {
+            const indices = Array.from({ length: k }, (_, index) => index);
+            while (true) {
+              if (query.world[worldInternal].getStructureEpoch() !== structureEpoch) {
+                throw new QueryIterationInvalidatedError(
+                  structureEpoch,
+                  query.world[worldInternal].getStructureEpoch(),
+                );
+              }
+              yield indices.map((index) => rows[index] as QueryRow<R, W, O>);
+              let pivot = k - 1;
+              while (pivot >= 0 && (indices[pivot] ?? 0) === rows.length - k + pivot) pivot -= 1;
+              if (pivot < 0) break;
+              indices[pivot] = (indices[pivot] ?? 0) + 1;
+              for (let index = pivot + 1; index < k; index++) {
+                indices[index] = (indices[index - 1] ?? 0) + 1;
+              }
+            }
+          }
+          completed = true;
+        } finally {
+          query.active = false;
+          if (!completed) query.lastObservedEpoch = previousObservedEpoch;
+        }
+      },
+    };
+  }
+
+  private beginIteration(): void {
+    if (this.active) throw new QueryIterationActiveError();
+    this.active = true;
+  }
+
+  private refreshMatches(): void {
+    const graph = this.world[worldInternal].getGraph() as ArchetypeGraph;
+    if (this.lastGraphGeneration === graph.generation) return;
+    this.matchedArchetypes = graph.archetypes
+      .filter((archetype) => this.archetypeMatches(archetype))
+      .map((archetype) => archetype.id);
+    this.matchedTables = graph.tables
+      .filter((table) => this.tableMatches(table))
+      .map((table) => table.id);
+    this.lastGraphGeneration = graph.generation;
+  }
+
+  private archetypeMatches(archetype: Archetype): boolean {
+    for (const requiredId of this.compiled.requiredIds) {
+      if (!archetype.components.some((component) => componentId(component) === requiredId))
+        return false;
+    }
+    for (const excludedId of this.compiled.withoutIds) {
+      if (archetype.components.some((component) => componentId(component) === excludedId))
+        return false;
+    }
+    return true;
+  }
+
+  private tableMatches(table: Table): boolean {
+    for (const componentId of this.compiled.requiredIds) {
+      if (!table.storage.has(componentId)) return false;
+    }
+    for (const componentId of this.compiled.withoutIds) {
+      if (table.storage.has(componentId)) return false;
+    }
+    return true;
+  }
+
+  private changeMatches(
+    entity: EntityHandle,
+    table: Table,
+    row: number,
+    upperBound: number,
+  ): boolean {
+    const graph = this.world[worldInternal].getGraph();
+    for (const componentId of this.compiled.changedIds) {
+      const sparseSet = graph.sparseTags.get(componentId);
+      const denseIndex = sparseSet === undefined ? -1 : sparseTagIndex(sparseSet, entity);
+      const epoch =
+        denseIndex >= 0
+          ? (sparseSet?.changed[denseIndex] ?? 0)
+          : (table.storage.get(componentId)?.epochs.changed[row] ?? 0);
+      if (epoch <= this.lastObservedEpoch || epoch > upperBound) return false;
+    }
+    for (const componentId of this.compiled.addedIds) {
+      const sparseSet = graph.sparseTags.get(componentId);
+      const denseIndex = sparseSet === undefined ? -1 : sparseTagIndex(sparseSet, entity);
+      const epoch =
+        denseIndex >= 0
+          ? (sparseSet?.added[denseIndex] ?? 0)
+          : (table.storage.get(componentId)?.epochs.added[row] ?? 0);
+      if (epoch <= this.lastObservedEpoch || epoch > upperBound) return false;
+    }
+    return true;
+  }
+
+  private spanUnavailableReason(): QuerySpanUnavailableReason | undefined {
+    if (this.compiled.sparseRoute) return 'sparse-component';
+    if ((this.compiled.descriptor.optional?.length ?? 0) > 0) return 'optional-data';
+    if (
+      (this.compiled.descriptor.changed?.length ?? 0) > 0 ||
+      (this.compiled.descriptor.added?.length ?? 0) > 0
+    )
+      return 'row-change-filter';
+    return undefined;
+  }
+}
+
+export function createQuery<
+  const R extends readonly Component[] = readonly [],
+  const W extends readonly Component[] = readonly [],
+  const O extends readonly Component[] = readonly [],
+>(
+  world: WorldQueryAccess,
+  descriptor: QueryDescriptor<R, W, O>,
+): Result<Query<R, W, O>, QueryCreationError> {
+  const compiled = compileDescriptor(descriptor);
+  if (!compiled.ok) return compiled;
+  return ok(new ExecutableQuery(world, compiled.value));
+}