ecs-system-patterns

ECS System Patterns

When to Use

Use this skill when:

• Implementing game logic systems
• Designing system execution order
• Optimizing system performance
• Creating reactive or event-driven systems
• Managing system dependencies
• Building modular game mechanics

Core Principles

1. Single Responsibility: Each system does one thing well
2. Component-Driven: Systems operate on components, not entities directly
3. Stateless When Possible: Systems should be stateless or minimally stateful
4. Efficient Queries: Cache queries and iterate efficiently
5. Priority-Based Execution: Control system execution order
6. Performance-Aware: Profile and optimize hot paths

System Types

1. Update Systems (Every Frame)

// systems/UpdateSystemBase.ts
import { Entity } from '../core/Entity';
import { World } from '../core/World';

export interface System {
  priority: number;
  enabled: boolean;
  update(world: World, deltaTime: number): void;
  cleanup?(): void;
}

export abstract class UpdateSystem implements System {
  public priority = 0;
  public enabled = true;

  abstract update(world: World, deltaTime: number): void;

  cleanup?(): void {
    // Override if needed
  }
}

// Example: Movement system
import { Transform } from '../components/Transform';
import { Velocity } from '../components/Velocity';

export class MovementSystem extends UpdateSystem {
  priority = 10; // Run early

  update(world: World, deltaTime: number): void {
    const entities = world.query<[Transform, Velocity]>([Transform, Velocity]);

    for (const entity of entities) {
      const [transform, velocity] = entity.getComponents(Transform, Velocity);

      transform.position.x += velocity.x * deltaTime;
      transform.position.y += velocity.y * deltaTime;
      transform.position.z += velocity.z * deltaTime;

      // Apply drag
      velocity.x *= 0.98;
      velocity.y *= 0.98;
      velocity.z *= 0.98;
    }
  }
}

2. Reactive Systems (Event-Driven)