Awesome ECS - Core Package

Overview

The Core package provides concrete implementations of the abstract interfaces defined in @awesome-ecs/abstract. It includes:

• EntityRepository: Stores concrete entity views
• SystemsModuleBase: Base class for grouping related systems via a fluent builder
• PipelineFactory variants: PipelineFactoryBasic (production), PipelineFactoryTelemetry / PipelineFactoryTelemetryDeep (dev/debug)
• SystemsFactory: Creates module builders and wires them to the pipeline factory
• Runtime orchestration lives in @awesome-ecs/runtime, which composes these core building blocks into runnable dispatchers.

Typical Usage Pattern

1. Define Components

class HealthComponent implements IComponent {
  readonly componentType = ComponentType.health;
  readonly isSerializable = true;
  current = 100;
  max = 100;
}

2. Define Entity Contract

import { IEntityWith } from '@awesome-ecs/abstract/entities';

interface CreatureEntity extends IEntityWith<CreatureModel> {
  readonly health: HealthComponent;
}

3. Define Systems

class HealthSystem implements ISystemMiddleware<CreatureEntity> {
  action(context: ISystemContext<CreatureEntity>): void {
    const health = context.entity.health;
    if (health.current <= 0) {
      context.repository.remove(context.entity.identity.proxy);
    }
  }
}

4. Create System Module

class CreatureModule extends SystemsModuleBase<CreatureEntity> {
  constructor(factory: ISystemsFactory) {
    super(factory);
    this.builder
      .addSystems(SystemType.initialize, [new InitCreatureSystem()])
      .addSystems(SystemType.update,     [new HealthSystem()])
      .addSystems(SystemType.render,     [new RenderCreatureSystem()]);
  }
}

5. Wire up and run

import { ConsoleLogger } from '@awesome-ecs/core/utils';
import { PipelineFactoryBasic, SystemsFactory } from '@awesome-ecs/core/factories';

const logger = new ConsoleLogger();
const pipelineFactory = new PipelineFactoryBasic(logger);
const systemsFactory = new SystemsFactory(pipelineFactory);

const creatureModule = new CreatureModule(systemsFactory);
// creatureModule.pipelines → ReadonlyMap<SystemType, IPipeline<ISystemContext<CreatureEntity>>>
// Feed to @awesome-ecs/runtime for per-entity or batch dispatch.

Key Abstractions

• EntityRepository (src/entities/) — Stores entity views
• SystemsModuleBase<TEntity> (src/systems/) — Groups systems via this.builder (fluent API)
• PipelineFactoryBasic / PipelineFactoryTelemetry (src/factories/) — Creates pipelines
• SystemsFactory (src/factories/) — Creates module builders
• EntityProxyRepository (src/entities/) — Manages direct proxy relationships and scoped proxies

Scope Management

Use .setScopeRoot() and .setScopedProxy() on the module builder to share entity references within a logical scope without hard-coded UIDs:

// Scope root — generates a UUID scope on first initialize
class SceneModule extends SystemsModuleBase<SceneEntity> {
  constructor(factory: ISystemsFactory) {
    super(factory);
    this.builder.setScopeRoot().addSystems(SystemType.initialize, [...]);
  }
}

// Scoped proxy — joins the scope inherited from the model
class GridModule extends SystemsModuleBase<GridEntity> {
  constructor(factory: ISystemsFactory) {
    super(factory);
    this.builder.setScopedProxy().addSystems(SystemType.initialize, [...]);
  }
}

Siblings in the same scope are resolvable via context.proxies.getProxy(entityType).

Package Structure

src/
├── entities/     # EntityRepository, EntityProxyRepository, EntitySnapshotProvider
├── factories/    # PipelineFactory variants, SystemsFactory
├── pipelines/    # PipelineComposable, MiddlewareRunnerBreaker, PipelineRunnerIterative
├── systems/      # SystemsModuleBase, SystemsModuleBuilder, runtime middleware
└── utils/        # ConsoleLogger, performance helpers

Relationship to Other Packages

• Uses: @awesome-ecs/abstract (interfaces)
• Used by: @awesome-ecs/workers, @awesome-ecs/ai