@awesome-ecs/abstract/dist/index-CjNeb3ML.d.cts

A comprehensive Entity-Component-System (ECS) Architecture implementation. Abstract components.

import { EntityProxy, EntityTypeUid, IEntity, IEntityModel, IEntityProxy } from "./identity-component-BDWEtAXA.cjs";
import { Immutable } from "./types-DvzdpbLu.cjs";
import { EntityEventUid, IEntityEvent, IEntityRepository, IEntitySnapshot, IEntityUpdate, IEventData } from "./index-DLm-DKAk.cjs";
import { IMiddleware, IPipeline, IPipelineContext, PipelineResult, PipelineRuntime } from "./index-D81Fo9XN.cjs";
import { IJsonSerializer, ILogger } from "./index-ChV4Q5j6.cjs";

//#region src/systems/module/system-type.d.ts
/**
 * Enum representing the built-in System pipeline types.
 * These types can be extended to introduce more types, and the System Runtime Pipeline should
 * add Middleware to handle the newly added types.
 */
declare enum SystemType {
  /**
   * The initialization phase of the Module pipeline.
   * This phase is typically used for setting up initial state and resources.
   */
  initialize = 0,
  /**
   * The update phase of the Module pipeline.
   * This phase is responsible for updating the game logic and state of entities.
   */
  update = 1,
  /**
   * The render phase of the Module pipeline.
   * This phase is used for rendering the game to the screen.
   */
  render = 2,
  /**
   * The synchronization phase of the Module pipeline.
   * This phase is used for synchronizing game state with external systems or other components.
   */
  sync = 3,
}
//#endregion
//#region src/systems/pipeline/system-context-events.d.ts
/**
 * The ISystemContextEvents is the access point for Event related APIs.
 * The access is made in a SystemMiddleware through the provided ISystemPipelineContext.
 */
interface ISystemContextEvents {
  /**
   * Dispatches and schedules the Event to its Subscribers or provided Entity Targets.
   * @param data - The EventData to dispatch.
   * @param targets - (optional) The Entities to send this event to. Providing this parameter will not broadcast this event.
   */
  dispatchEvent<TEventData extends IEventData>(data: TEventData, ...targets: IEntityProxy[]): void;
  /**
   * Dispatches and schedules the Events to their Subscribers or provided Entity Targets.
   * @param data - The EventData Array to dispatch.
   * @param targets - (optional) The Entities to send this event to. Providing this parameter will not broadcast this event.
   */
  dispatchEvents<TEventData extends IEventData>(data: TEventData[], ...targets: IEntityProxy[]): void;
  /**
   * Retrieves the Event with the given UID if it has been previously set on the current Context.
   * @param uid - The Event UID to retrieve.
   * @returns The Event with the given UID if it exists, otherwise undefined.
   */
  getEvent<TEventData extends IEventData>(uid: EntityEventUid): IEntityEvent<TEventData> | undefined;
  /**
   * Retrieves all the Events currently set on the Context.
   * @returns An array of all the Events currently set on the Context.
   */
  listEvents<TEventData extends IEventData>(): IEntityEvent<TEventData>[];
  /**
   * Returns whether the Event with the given UID has previously been set on the current Context.
   * @param uid - The Event UID to check for existence. If not provided, checks for any events in the context.
   * @returns True if the Event with the given UID exists, otherwise false.
   */
  hasEvent(uid?: EntityEventUid): boolean;
  /**
   * Subscribes to Events with the given UID. When the matching Event is dispatched,
   * the Entity update loop will set this Event on the Pipeline Context.
   * @param uid - The Event UID to subscribe to.
   * @param filter - (optional) Provides a callback function that will be executed on all matching Events.
   * Can be used to filter what Event to schedule through to the current Entity update.
   */
  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
  /**
   * Stops subscribing to Events with the given UID. The Entity will not receive any future Events with this UID.
   * @param uid - The Event UID to stop listening to.
   */
  unsubscribeFrom(uid: EntityEventUid): void;
  /**
   * Adds the given Events into the Context instance.
   * @param events - The Event instances to be set on the Context.
   */
  setContextEvents(events: IEntityEvent<IEventData>[]): void;
  /**
   * Adds the given Event into the Context instance.
   * @param event - The Event instance to be set on the Context.
   */
  setContextEvent(event: IEntityEvent<IEventData>): void;
  /**
   * Removes all the Events currently set on the Context instance.
   */
  clearContextEvents(): void;
  /**
   * Removes all the Event Subscriptions for the current Entity.
   */
  clearSubscriptions(): void;
}
//#endregion
//#region src/systems/pipeline/system-context-proxies.d.ts
/**
 * Provides a context-bound interface for managing proxy relationships for the current entity.
 */
interface ISystemContextProxies {
  /**
   * Registers a proxy for the current entity, establishing a bi-directional link.
   * @param proxy The proxy to register for the current entity.
   * @param cleanup If true, removes all existing proxies of the same type before adding the new one.
   */
  register(proxy: IEntityProxy, cleanup?: boolean): void;
  /**
   * Registers multiple proxies for the current entity.
   * @param proxies The proxies to register.
   * @param cleanup If true, removes existing proxies of the same types as the new ones before adding.
   */
  registerMany(proxies: readonly IEntityProxy[], cleanup?: boolean): void;
  /**
   * Removes a proxy from the current entity, breaking the bi-directional link.
   * @param proxy The proxy to remove from the current entity.
   */
  remove(proxy: IEntityProxy): void;
  /**
   * Removes all proxies for the current entity, optionally filtered by a target entity type.
   * @param targetType The optional entity type to remove. If not provided, all proxies are removed.
   */
  removeAll(targetType?: EntityTypeUid): void;
  /**
   * Gets a single proxy for the current entity by its target type.
   * If multiple proxies of the same type exist, the first one found is returned.
   * @param targetType The entity type of the proxy to retrieve.
   * @returns The entity proxy, or null if not found.
   */
  get(targetType: EntityTypeUid): IEntityProxy | null;
  /**
   * Gets all proxies for the current entity that match a given target type.
   * @param targetType The entity type of the proxies to retrieve.
   * @returns A readonly array of entity proxies.
   */
  getMany(targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
  /**
   * Gets all proxies associated with the current entity.
   * @returns A readonly map of entity type UIDs to an array of their proxies.
   */
  getAll(): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
}
//#endregion
//#region src/systems/pipeline/system-context-repository.d.ts
/**
 * The `ISystemContextRepository` is the access point for the `IEntityRepository` related APIs.
 *
 * The access is made in an `ISystemMiddleware` through the provided `ISystemPipelineContext`.
 */
interface ISystemContextRepository {
  /**
   * Schedule adding a new entity to the repository.
   *
   * @param entityType - The type of the entity.
   * @param model - The model of the entity.
   * @param snapshot - Optional initial snapshot of the entity.
   */
  addEntity(entityType: EntityTypeUid, model: IEntityModel, snapshot?: IEntitySnapshot): void;
  /**
   * Retrieves an entity from the repository.
   *
   * @template TEntity - The type of the entity.
   * @param proxy - The proxy of the entity.
   * @returns An immutable representation of the entity.
   */
  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
  /**
   * Schedule updating an entity in the repository.
   *
   * @param target - Optional target entity proxy. If not provided, updates the current entity set on the system context.
   */
  updateEntity(target?: IEntityProxy): void;
  /**
   * Removes an entity from the repository.
   *
   * @param target - The entity proxy to be removed.
   */
  removeEntity(target: IEntityProxy): void;
}
//#endregion
//#region src/systems/pipeline/system-context-scheduler.d.ts
/**
 * The `ISystemContextScheduler` interface represents the access point for Scheduler related APIs.
 * The access is made in a `SystemMiddleware` through the provided `ISystemPipelineContext`.
 */
interface ISystemContextScheduler {
  /**
   * Schedules an update for the specified `target` entity proxy at a given `intervalMs`.
   * If no `target` is provided, update will be scheduled for the current entity set on the system context.
   * If no `intervalMs` is provided, the default update interval will be used.
   *
   * @param target - The entity proxy for which the update is scheduled.
   * @param intervalMs - The interval in milliseconds at which the update should be triggered.
   */
  scheduleUpdate(target?: IEntityProxy, intervalMs?: number): void;
  /**
   * Removes the scheduled update for the specified `target` entity proxy.
   * If no `target` is provided, schedule is removed for the current entity set on the system context.
   *
   * @param target - The entity proxy for which the scheduled update should be removed.
   */
  removeSchedule(target?: IEntityProxy): void;
}
//#endregion
//#region src/systems/pipeline/system-context-snapshot.d.ts
/**
 * The ISystemContextSnapshot is the access point for Snapshot related APIs.
 * The access is made in a SystemMiddleware through the provided ISystemPipelineContext.
 */
interface ISystemContextSnapshot {
  /**
   * A read-only reference to the JSON serializer used for snapshot serialization.
   */
  readonly serializer: Immutable<IJsonSerializer>;
  /**
   * Applies the provided entity snapshot to the current entity set on the system context.
   *
   * @param snapshot - The entity snapshot to apply.
   */
  applyToEntity(snapshot: IEntitySnapshot): void;
  /**
   * Creates a new entity snapshot from the provided entity.
   *
   * @param entity - The entity to create a snapshot from. If not provided, a snapshot for the current entity set on the system context will be created.
   * @returns A new entity snapshot.
   */
  createFromEntity(entity?: IEntity): IEntitySnapshot;
  /**
   * Dispatches an update to the entity using the provided snapshot and entity proxy.
   *
   * @param snapshot - The entity snapshot to use for the update.
   * @param proxy - The entity proxy to use for the update.
   */
  dispatchToUpdate(snapshot: IEntitySnapshot, proxy: IEntityProxy): void;
}
//#endregion
//#region src/systems/pipeline/system-context.d.ts
type SystemRuntime = PipelineRuntime & {
  enabledSteps: ReadonlySet<SystemType>;
};
/**
 * The ISystemContext is the Context passed to a SystemMiddleware as part of the Pipeline Dispatch.
 * It's an abstraction layer so that the Middleware code won't have explicit dependencies on other parts of the ECS.
 *
 * Any State changes done by the SystemMiddleware are executed using the APIs provided by the ISystemContext.
 *
 * @template TEntity - The type of entity that the SystemMiddleware operates on.
 * @extends IPipelineContext - The ISystemContext extends the IPipelineContext interface.
 */
interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
  /**
   * The time in milliseconds since the last entity update.
   */
  readonly deltaTimeMs: Immutable<number>;
  /**
   * The entity that the SystemMiddleware is operating on.
   */
  readonly entity: Immutable<TEntity>;
  /**
   * The update object containing information about the entity's changes.
   */
  readonly update: Immutable<IEntityUpdate>;
  /**
   * The events API for the SystemMiddleware to interact with the ECS events system.
   */
  readonly events: Immutable<ISystemContextEvents>;
  /**
   * The proxies API for the SystemMiddleware to interact with the ECS proxies system.
   */
  readonly proxies: Immutable<ISystemContextProxies>;
  /**
   * The repository API for the SystemMiddleware to interact with the ECS repository system.
   */
  readonly repository: Immutable<ISystemContextRepository>;
  /**
   * The scheduler API for the SystemMiddleware to interact with the ECS scheduler system.
   */
  readonly scheduler: Immutable<ISystemContextScheduler>;
  /**
   * The snapshot API for the SystemMiddleware to interact with the ECS snapshot system.
   */
  readonly snapshot: Immutable<ISystemContextSnapshot>;
  /**
   * The logger API for the SystemMiddleware to log messages.
   */
  readonly logger: Immutable<ILogger>;
  /**
   * The runtime API for the SystemMiddleware to interact with the ECS runtime system.
   */
  readonly runtime: SystemRuntime;
}
//#endregion
//#region src/systems/pipeline/system-context-entity.d.ts
/**
 * Interface representing a system context entity.
 * This interface provides methods to manipulate and access entity and update data.
 */
interface ISystemContextEntity {
  /**
   * The immutable entity associated with the system context.
   */
  readonly entity: Immutable<IEntity>;
  /**
   * The immutable entity update associated with the system context.
   */
  readonly update: Immutable<IEntityUpdate>;
  /**
   * Sets the entity associated with the system context entity.
   *
   * @param entity - The new entity to be associated with the system context.
   */
  setEntity(entity: IEntity): void;
  /**
   * Sets the entity update associated with the system context.
   *
   * @param update - The new entity update to be associated with the system context.
   */
  setUpdate(update: IEntityUpdate): void;
}
//#endregion
//#region src/systems/runtime/systems-runtime-context.d.ts
/**
 * The ISystemsRuntimeContext is the Context passed by a SystemsRuntimePipeline.
 * It helps orchestrate the execution of SystemPipelines registered in the SystemsModule.
 */
interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineContext {
  /**
   * A Set of enabled steps for the SystemPipelines.
   */
  readonly enabledSteps: Set<SystemType>;
  /**
   * An entity provider for the SystemPipelines.
   */
  readonly entityProvider: ISystemContextEntity;
  /**
   * An entity repository for the SystemPipelines.
   */
  readonly entityRepository: IEntityRepository;
  /**
   * A Map of SystemPipelines registered in the SystemsModule.
   */
  readonly systemPipelines: Map<SystemType, IPipeline<ISystemContext<TEntity>>>;
  /**
   * The SystemContext for the SystemPipelines.
   */
  readonly systemContext: ISystemContext<TEntity>;
}
//#endregion
//#region src/systems/runtime/systems-runtime-middleware.d.ts
/**
 * The `ISystemsRuntimeMiddleware` represents the building blocks of executing SystemsModule's registered Pipelines.
 * It receives the current State in the Context, and can decide which SystemPipelines to execute.
 *
 * @typeParam TEntity - The type of entity that the middleware operates on.
 * @extends {IMiddleware<ISystemsRuntimeContext<TEntity>>} - Extends the base `IMiddleware` interface, which is used for defining middleware functions.
 */
type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
//#endregion
//#region src/systems/pipeline/system-middleware.d.ts
/**
 * The `ISystemMiddleware` is a basic System implementation that can be registered as a Middleware in a SystemPipeline.
 * It provides a `SystemPipelineContext` to its exposed methods.
 *
 * @template TEntity - The type of entity that this middleware operates on.
 * @extends {IMiddleware<ISystemContext<TEntity>>} - Extends the base `IMiddleware` interface, which requires a `SystemPipelineContext` to be provided.
 */
type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEntity>>;
//#endregion
//#region src/systems/module/systems-module-definition.d.ts
/**
 * The SystemModuleDefinition is the main way of composing SystemsModules for an Entity.
 * It can be used as building blocks for SystemsModules as a way to register common SystemMiddlewares and share across different Entities.
 */
interface ISystemsModuleDefinition<TEntity extends IEntity> {
  /**
   * Registers SystemMiddlewares to the specified SystemPipelineType.
   *
   * @param type - The SystemPipelineType to append the provided SystemMiddlewares to.
   * @param systems - The SystemMiddlewares to be registered in the provided SystemPipelineType in the same order as the provided array.
   * The SystemMiddlewares will be appended to existing Pipelines to allow easy extension of existing behaviors.
   */
  registerSystems?(type: SystemType, systems: Immutable<ISystemMiddleware<TEntity>[]>): void;
  /**
   * Registers the middleware of the provided SystemsModule in the current SystemsModule.
   * Keeps the same system types and order.
   * Systems will be appended to the current SystemsModule steps.
   *
   * Use multiple calls to `registerModule` using the `type` parameter to register only a step of the SystemsModule.
   *
   * @param module - The SystemsModule to be registered.
   * @template TModuleEntity - The entity type that the module works on.
   */
  registerModule?<TModuleEntity extends IEntity>(module: TEntity extends TModuleEntity ? Immutable<ISystemsModuleDefinition<TModuleEntity>> : TModuleEntity, type?: SystemType): void;
}
//#endregion
//#region src/systems/module/systems-module.d.ts
/**
 * The SystemModule is the main way of registering and triggering the SystemMiddlewares registered for an Entity.
 * It can handle EntityUpdate objects and decides which SystemPipelines to trigger based on the information in the EntityUpdate.
 */
interface ISystemsModule<TEntity extends IEntity> extends ISystemsModuleDefinition<TEntity> {
  /**
   * Triggers all registered SystemPipelines to apply the changes from the provided EntityUpdate to an Entity instance.
   *
   * @param update - The EntityUpdate containing the desired changes to be applied on an Entity instance.
   * @returns An optional PipelineResult indicating the success or failure of the triggered SystemPipelines.
   */
  triggerSystems(update: Immutable<IEntityUpdate>): void | PipelineResult;
}
//#endregion
//#region src/systems/module/systems-module-repository.d.ts
/**
 * Interface for managing systems modules.
 *
 * @template TEntity - The type of entity that the systems module operates on.
 */
interface ISystemsModuleRepository {
  /**
   * The number of systems modules in the repository.
   */
  readonly size: number;
  /**
   * Retrieves a systems module for a specific entity type.
   *
   * @param type - The unique identifier of the entity type.
   * @returns The systems module for the specified entity type.
   */
  get<TEntity extends IEntity>(type: EntityTypeUid): ISystemsModule<TEntity>;
  /**
   * Adds or updates a systems module for a specific entity type.
   *
   * @param type - The unique identifier of the entity type.
   * @param module - The systems module to add or update.
   */
  set(type: EntityTypeUid, module: ISystemsModule<IEntity>): void;
  /**
   * Retrieves a read-only map of all systems modules in the repository.
   *
   * @returns A read-only map of entity type unique identifiers to systems modules.
   */
  list(): ReadonlyMap<EntityTypeUid, Immutable<ISystemsModule<IEntity>>>;
}
//#endregion
//#region src/systems/runtime/systems-runtime.d.ts
/**
 * The System Runtime allows running a loop of Ticks.
 *
 * Each `runTick` method can process one or more Entity Updates.
 *
 * We can have multiple implementations of a `SystemsRuntime`, based on the use-case.
 * A different implementation can be chosen at runtime, based for example on performance.
 */
interface ISystemsRuntime {
  /**
   * The method should trigger the SystemsModule logic for the provided `IEntityUpdate`.
   * If no EntityUpdate is given, the `SystemRuntime` implementation can choose to dequeue one from the `IEntityUpdateQueue`.
   *
   * @param update - An optional `IEntityUpdate` to process. If not provided, the method will dequeue one from the `IEntityUpdateQueue`.
   * @returns A `PipelineResult` representing the outcome of the SystemsModule logic execution.
   */
  runTick(update?: IEntityUpdate): PipelineResult;
}
//#endregion
export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleDefinition, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemRuntime, SystemType };
//# sourceMappingURL=index-CjNeb3ML.d.cts.map