Awesome ECS - Abstract Package

Overview

The Abstract package defines all core interfaces and abstractions for the Entity-Component-System (ECS) framework. It provides the foundational contracts that all other packages implement, including:

• Components: Data-storage contracts
• Entities: Materialized view contracts for components and proxy references
• Pipelines: Middleware-based execution chains
• Systems: Modular logic execution patterns
• Utilities: Serialization, events, and scheduling

This package has zero external dependencies and serves as the contract layer for the entire ECS framework.

Core Concepts

Components (src/components/)

Components are data-only containers. They should never contain business logic.

import { IComponent } from "@awesome-ecs/abstract";

export class HealthComponent implements IComponent {
  readonly componentType = ComponentType.health;
  readonly isSerializable = true;  // Include in snapshots
  
  current: number = 100;
  max: number = 100;
}

Key interfaces:

• IComponent: Base component interface with componentType and isSerializable
• IdentityComponent: Mandatory component tracking entity UID and model

Entities (src/entities/)

Entities are immutable contracts over identity, components, and explicit typed proxy fields.

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

export interface GridEntity extends IEntityWith<GridModel> {
  readonly coordinates: CoordinatesComponent;
  readonly sceneProxy: EntityProxy<SceneEntity>;
}

Key files:

• entity.ts: Base IEntity interface and EntityTypeUid types
• entity-proxies.ts: EntityProxy for loose-coupling relationships
• entity-snapshot.ts: IEntitySnapshot for serialization
• entity-runtime-scheduler.ts: IEntityUpdate, the lean IEntityRuntimeScheduler runtime contract, and IEntityRuntimeSchedulerInspector for tooling/debug surfaces that need mailbox and schedule snapshots
• entity-repository.ts: IEntityRepository for entity lookups
• entity-events.ts: IEntityEvents for reactive patterns

Pipelines (src/pipelines/)

Pipelines execute middleware chains with two phases:

1. dispatch(context): Main execution phase
2. cleanup(context): Resource cleanup phase

export interface IPipeline<TContext extends IPipelineContext> {
  use(middleware: IMiddleware<TContext>): this;
  dispatch(context: Partial<TContext>): void | Promise<void>;
  cleanup(context: Partial<TContext>): void | Promise<void>;
}

Key files:

• pipeline.ts: Core IPipeline interface
• middleware.ts: IMiddleware contract (action + optional cleanup)
• middleware-runner.ts: Middleware execution engine
• pipeline-context.ts: Context passed to middleware
• pipeline-runner.ts: Pipeline execution orchestration

Systems (src/systems/)

Systems are modular logic units that operate on entities. They implement the middleware pattern.

Pipeline-based systems:

• system-middleware.ts: ISystemMiddleware<TEntity> - middleware for a specific entity type
• system-context.ts: Context passed to system middleware (entity, events, repository, etc.)

Module-based organization:

• systems-module.ts: ISystemsModule<TEntity> - groups related systems targeting an entity type
• systems-module-builder.ts: ISystemsModuleBuilder<TEntity> - fluent builder for pipeline registration
• systems-module-repository.ts: Module lifecycle and registration

Runtime execution:

• systems-runtime.ts: ISystemsRuntime - core tick-based execution loop
• systems-runtime-context.ts: Context for runtime execution
• systems-runtime-middleware.ts: Middleware for runtime operations

Utilities (src/utils/)

• types.ts: Common types (Immutable, BooleanProps, Readonly)
• json-serializer.ts: JSON serialization contracts
• logger.ts: Logging interface
• performance-timer.ts: Performance measurement

Key Design Principles

1. Components are data-only - no behavior, just properties
2. Entities are immutable - modifications through systems only
3. Relationships are backed by proxies - proxy fields expose typed lookup refs; systems resolve proxy handles or full entities explicitly when needed
4. Systems are middleware - pluggable into pipelines
5. Pipelines are composable - middleware chains with dispatch + cleanup

What's NOT in Abstract

• Concrete entity implementations (→ @awesome-ecs/core)
• System module base classes (→ @awesome-ecs/core)
• Component factories (→ @awesome-ecs/core)
• Multi-threading (→ @awesome-ecs/workers)
• AI patterns (→ @awesome-ecs/ai)