# 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**: Container contracts for components and relationships
- **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.

```typescript
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 **containers of components** and **proxies to other entities**. They never directly reference other entities—they use proxies for loose coupling.

```typescript
export class GridEntity extends EntityBase<GridModel> {
  // Strongly-typed component getters
  get coordinates(): CoordinatesComponent {
    return this.getComponent(ComponentType.coordinates);
  }

  // Entity proxies for relationships (not direct references)
  get sceneProxy(): EntityProxy<SceneEntity> {
    return this.getProxy(EntityType.scene);
  }
}
```

**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-queue.ts`: `IEntityUpdate` and `IEntityUpdateQueue` for batching changes
- `entity-repository.ts`: `IEntityRepository` for entity lookups
- `entity-scheduler.ts`: `IEntityScheduler` for deferred updates
- `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

```typescript
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 use proxies** - loose coupling between entities
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)