ecs-architecture

ECS Architecture

When to Use

Use this skill when:

• Building a game or simulation with many interactive objects
• Refactoring object-oriented game code for better performance
• Implementing data-oriented design patterns
• Creating scalable game systems with complex interactions

Core Principles

1. Composition over Inheritance: Entities are composed of components, not class hierarchies
2. Data Locality: Components store data; systems process data in contiguous memory
3. Separation of Concerns: Components = data, Systems = logic, Entities = IDs
4. Type Safety: Leverage TypeScript for compile-time guarantees
5. Performance: Cache-friendly iteration over components

Architecture Overview

Entity: Unique ID
    ↓
Components: Pure data (Transform, Velocity, Health, Renderable)
    ↓
Systems: Logic that processes entities with specific component combinations

Implementation

1. Entity Manager

export type EntityId = number & { readonly __brand: 'EntityId' };

export class EntityManager {
  private nextId = 0;
  private readonly entities = new Set<EntityId>();

  create(): EntityId {
    const id = this.nextId++ as EntityId;
    this.entities.add(id);
    return id;
  }

  destroy(id: EntityId): void {
    this.entities.delete(id);
  }

  exists(id: EntityId): boolean {
    return this.entities.has(id);
  }

  getAll(): ReadonlySet<EntityId> {
    return this.entities;
  }

  clear(): void {
    this.entities.clear();
    this.nextId = 0;
  }
}

2. Component System

export interface Component {
  readonly __componentBrand?: never;
}

export interface ComponentClass<T extends Component> {
  new (...args: any[]): T;
}

export class ComponentManager {
  private readonly components = new Map<ComponentClass<any>, Map<EntityId, Component>>();

  register<T extends Component>(type: ComponentClass<T>): void {
    if (!this.components.has(type)) {
      this.components.set(type, new Map());
    }
  }

  add<T extends Component>(entity: EntityId, type: ComponentClass<T>, component: T): void {
    this.register(type);
    this.components.get(type)!.set(entity, component);
  }

  remove<T extends Component>(entity: EntityId, type: ComponentClass<T>): void {
    this.components.get(type)?.delete(entity);
  }

  get<T extends Component>(entity: EntityId, type: ComponentClass<T>): T | undefined {
    return this.components.get(type)?.get(entity) as T | undefined;
  }

  has<T extends Component>(entity: EntityId, type: ComponentClass<T>): boolean {
    return this.components.get(type)?.has(entity) ?? false;
  }

  getAll<T extends Component>(type: ComponentClass<T>): Map<EntityId, T> {
    return (this.components.get(type) as Map<EntityId, T>) ?? new Map();
  }

  removeAllForEntity(entity: EntityId): void {
    for (const componentMap of this.components.values()) {
      componentMap.delete(entity);
    }
  }

  clear(): void {
    this.components.clear();
  }
}