ecs-performance

ECS Performance Optimization

When to Use

Use this skill when:

• Scaling to thousands of entities
• Optimizing frame time
• Reducing memory allocations
• Improving cache coherency
• Debugging performance issues
• Targeting mobile devices

Core Principles

1. Data-Oriented: Organize data for cache efficiency
2. Minimize Allocations: Pool and reuse objects
3. Batch Operations: Process similar entities together
4. Profile First: Measure before optimizing
5. Lazy Evaluation: Compute only when needed
6. Archetype-Based: Group entities by components

Performance Optimization Techniques

1. Archetype Optimization

// core/Archetype.ts
export interface Archetype {
  signature: string;
  entities: Entity[];
  componentData: Map<ComponentConstructor<any>, any[]>;
}

export class ArchetypeStorage {
  private archetypes = new Map<string, Archetype>();

  getArchetype(componentTypes: ComponentConstructor<any>[]): Archetype {
    const signature = this.getSignature(componentTypes);
    let archetype = this.archetypes.get(signature);

    if (!archetype) {
      archetype = {
        signature,
        entities: [],
        componentData: new Map(),
      };

      // Pre-allocate component arrays
      for (const type of componentTypes) {
        archetype.componentData.set(type, []);
      }

      this.archetypes.set(signature, archetype);
    }

    return archetype;
  }

  addEntity(entity: Entity, componentTypes: ComponentConstructor<any>[]): void {
    const archetype = this.getArchetype(componentTypes);
    archetype.entities.push(entity);

    // Add component data to arrays
    for (const type of componentTypes) {
      const component = entity.getComponent(type);
      const array = archetype.componentData.get(type)!;
      array.push(component);
    }
  }

  removeEntity(entity: Entity, componentTypes: ComponentConstructor<any>[]): void {
    const archetype = this.getArchetype(componentTypes);
    const index = archetype.entities.indexOf(entity);

    if (index !== -1) {
      // Remove from entity array
      archetype.entities.splice(index, 1);

      // Remove from component arrays
      for (const [type, array] of archetype.componentData) {
        array.splice(index, 1);
      }
    }
  }

  // Iterate cache-friendly
  iterateArchetype<T extends any[]>(
    componentTypes: ComponentConstructor<any>[],
    callback: (components: T, entity: Entity) => void
  ): void {
    const archetype = this.getArchetype(componentTypes);
    const componentArrays = componentTypes.map((type) =>
      archetype.componentData.get(type)
    );

    const length = archetype.entities.length;

    for (let i = 0; i < length; i++) {
      const components = componentArrays.map((arr) => arr![i]) as T;
      callback(components, archetype.entities[i]);
    }
  }

  private getSignature(componentTypes: ComponentConstructor<any>[]): string {
    return componentTypes
      .map((t) => t.name)
      .sort()
      .join(':');
  }
}