ecs-component-patterns

ECS Component Patterns

When to Use

Use this skill when:

• Designing components for game entities
• Optimizing component memory layout
• Implementing special component types
• Managing shared game data
• Creating reusable component libraries

Core Principles

1. Data-Only Components: No logic, only data
2. Small Components: Single responsibility principle
3. Composition: Combine simple components for complex behavior
4. Tag Components: Empty components as flags
5. Shared Data: Singleton components for global state
6. Type Safety: TypeScript for all component definitions

Implementation

1. Basic Component Types

// components/Transform.ts
import { Component } from '../core/Component';

export class Transform implements Component {
  constructor(
    public x: number = 0,
    public y: number = 0,
    public z: number = 0,
    public rotationX: number = 0,
    public rotationY: number = 0,
    public rotationZ: number = 0,
    public scaleX: number = 1,
    public scaleY: number = 1,
    public scaleZ: number = 1
  ) {}

  setPosition(x: number, y: number, z: number): this {
    this.x = x;
    this.y = y;
    this.z = z;
    return this;
  }

  setRotation(x: number, y: number, z: number): this {
    this.rotationX = x;
    this.rotationY = y;
    this.rotationZ = z;
    return this;
  }

  setScale(x: number, y: number, z: number): this {
    this.scaleX = x;
    this.scaleY = y;
    this.scaleZ = z;
    return this;
  }

  clone(): Transform {
    return new Transform(
      this.x, this.y, this.z,
      this.rotationX, this.rotationY, this.rotationZ,
      this.scaleX, this.scaleY, this.scaleZ
    );
  }
}

// components/Velocity.ts
export class Velocity implements Component {
  constructor(
    public vx: number = 0,
    public vy: number = 0,
    public vz: number = 0
  ) {}

  get magnitude(): number {
    return Math.sqrt(this.vx * this.vx + this.vy * this.vy + this.vz * this.vz);
  }

  set(x: number, y: number, z: number): this {
    this.vx = x;
    this.vy = y;
    this.vz = z;
    return this;
  }

  add(x: number, y: number, z: number): this {
    this.vx += x;
    this.vy += y;
    this.vz += z;
    return this;
  }

  scale(factor: number): this {
    this.vx *= factor;
    this.vy *= factor;
    this.vz *= factor;
    return this;
  }

  normalize(): this {
    const mag = this.magnitude;
    if (mag > 0) {
      this.scale(1 / mag);
    }
    return this;
  }
}