ecs-queries

ECS Queries

When to Use

Use this skill when:

• Querying entities by component type
• Filtering entities based on criteria
• Optimizing system performance
• Implementing spatial queries
• Building complex entity searches
• Managing large numbers of entities

Core Principles

1. Cache Queries: Create queries once, reuse many times
2. Archetype-Based: Group entities by component signature
3. Lazy Evaluation: Only iterate when needed
4. Minimal Allocations: Reuse arrays and iterators
5. Type-Safe: Leverage TypeScript for component access
6. Performance-First: O(1) or O(n) operations, never O(n²)

Query System Implementation

1. Basic Query Interface

// core/Query.ts
import { Entity } from './Entity';
import { ComponentConstructor } from './Component';

export interface QueryResult<T extends any[]> {
  entities: Entity[];
  iterate(callback: (entity: Entity, components: T) => void): void;
  filter(predicate: (entity: Entity, components: T) => boolean): QueryResult<T>;
  first(): Entity | undefined;
  count(): number;
}

export class Query<T extends any[]> implements QueryResult<T> {
  private componentTypes: ComponentConstructor<any>[];
  private cachedEntities: Entity[] = [];
  private dirty = true;

  constructor(
    componentTypes: ComponentConstructor<any>[],
    private world: World
  ) {
    this.componentTypes = componentTypes;
  }

  get entities(): Entity[] {
    if (this.dirty) {
      this.refresh();
    }
    return this.cachedEntities;
  }

  private refresh(): void {
    this.cachedEntities = this.world
      .getAllEntities()
      .filter((entity) => this.matches(entity));
    this.dirty = false;
  }

  private matches(entity: Entity): boolean {
    return this.componentTypes.every((type) => entity.hasComponent(type));
  }

  iterate(callback: (entity: Entity, components: T) => void): void {
    for (const entity of this.entities) {
      const components = entity.getComponents(...this.componentTypes) as T;
      callback(entity, components);
    }
  }

  filter(predicate: (entity: Entity, components: T) => boolean): QueryResult<T> {
    const filtered = new FilteredQuery<T>(this, predicate);
    return filtered;
  }

  first(): Entity | undefined {
    return this.entities[0];
  }

  count(): number {
    return this.entities.length;
  }

  markDirty(): void {
    this.dirty = true;
  }
}