@awesome-ecs/abstract 0.20.0 → 0.20.2

package/dist/systems/index.d.ts

@@ -1,21 +1,27 @@
-import { I as ISystemsRuntimeContext, a as ISystemContext, S as SystemType } from '../systems-runtime-context-B2ch9kB3.js';
-export { b as ISystemContextEntity, c as ISystemContextEvents, d as ISystemContextProxies, e as ISystemContextRepository, f as ISystemContextScheduler, g as ISystemContextSnapshot } from '../systems-runtime-context-B2ch9kB3.js';
-import { c as IEntity, E as EntityTypeUid } from '../index-BPDsRt_F.js';
-import { b as IMiddleware, P as PipelineResult } from '../pipeline-D43CXxWG.js';
-import { f as IEntityUpdate } from '../entity-repository-BASmOrq7.js';
-import { I as Immutable } from '../types-BNwBqRWY.js';
+import { I as ISystemsRuntimeContext, a as ISystemContext, S as SystemType } from '../systems-runtime-context-BTNdV8Z-.js';
+export { b as ISystemContextEntity, c as ISystemContextEvents, d as ISystemContextProxies, e as ISystemContextRepository, f as ISystemContextScheduler, g as ISystemContextSnapshot } from '../systems-runtime-context-BTNdV8Z-.js';
+import { c as IEntity, E as EntityTypeUid } from '../index-B1KXekZD.js';
+import { b as IMiddleware, P as PipelineResult } from '../pipeline-BGsQiSer.js';
+import { f as IEntityUpdate } from '../entity-repository-BlSpo-x2.js';
+import { I as Immutable } from '../types-cZ-1lGPD.js';
 import '../utils/index.js';
-import '../performance-timer-XvdCbcAE.js';
+import '../performance-timer-BVyl0SRs.js';
 
 /**
- * The ISystemsRuntimeMiddleware represents the building blocks of executing SystemsModule's registered Pipelines.
+ * 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>>;
 
 /**
- * The SystemMiddleware is the basic System implementation that can be registered as a Middleware in a SystemPipeline.
- * It provides a SystemPipelineContext to it's exposed methods.
+ * 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>>;
 
@@ -25,36 +31,69 @@ type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEn
  */
 interface ISystemsModule<TEntity extends IEntity> {
     /**
-     * @param type The SystemPipelineType to append the provided SystemMiddlewares to.
-     * @param systems The SystemMiddlewares will be registered in the provided SystemPipelineType in the same order as the provided array.
+     * 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: ISystemMiddleware<TEntity>[]): void;
+    registerSystems?(type: SystemType, systems: ISystemMiddleware<TEntity>[]): void;
     /**
-     * Trigger 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.
+     * 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 A PipelineResult indicating the success or failure of the triggered SystemPipelines.
      */
     triggerSystems(update: IEntityUpdate): PipelineResult;
 }
 
+/**
+ * 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>>>;
 }
 
 /**
  * The System Runtime allows running a loop of Ticks.
  *
- * Each RunTick can process one or more Entity Updates, from the EntityQueue.
- * We can have multiple implementations of a SystemRuntime, based on the use-case.
+ * 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.
+     * 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;
 }

package/dist/systems/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/systems/module/system-type.ts"],"sourcesContent":["/**\n * The built-in ECS pipeline types. They can be extended to introduce more types, and the System Runtime Pipeline should\n * add Middleware to handle the newly added types.\n */\nexport enum SystemType {\n  initialize = 'initialize',\n  update = 'update',\n  render = 'render',\n  sync = 'sync',\n}\n"],"mappings":";AAIO,IAAK,aAAL,kBAAKA,gBAAL;AACL,EAAAA,YAAA,gBAAa;AACb,EAAAA,YAAA,YAAS;AACT,EAAAA,YAAA,YAAS;AACT,EAAAA,YAAA,UAAO;AAJG,SAAAA;AAAA,GAAA;","names":["SystemType"]}
+{"version":3,"sources":["../../src/systems/module/system-type.ts"],"sourcesContent":["/**\n * Enum representing the built-in System pipeline types.\n * These types can be extended to introduce more types, and the System Runtime Pipeline should\n * add Middleware to handle the newly added types.\n */\nexport enum SystemType {\n  /**\n   * The initialization phase of the Module pipeline.\n   * This phase is typically used for setting up initial state and resources.\n   */\n  initialize = 'initialize',\n\n  /**\n   * The update phase of the Module pipeline.\n   * This phase is responsible for updating the game logic and state of entities.\n   */\n  update = 'update',\n\n  /**\n   * The render phase of the Module pipeline.\n   * This phase is used for rendering the game to the screen.\n   */\n  render = 'render',\n\n  /**\n   * The synchronization phase of the Module pipeline.\n   * This phase is used for synchronizing game state with external systems or other components.\n   */\n  sync = 'sync'\n}\n"],"mappings":";AAKO,IAAK,aAAL,kBAAKA,gBAAL;AAKL,EAAAA,YAAA,gBAAa;AAMb,EAAAA,YAAA,YAAS;AAMT,EAAAA,YAAA,YAAS;AAMT,EAAAA,YAAA,UAAO;AAvBG,SAAAA;AAAA,GAAA;","names":["SystemType"]}

package/dist/systems-runtime-context-BTNdV8Z-.d.ts

@@ -0,0 +1,330 @@
+import { I as IEntityProxy, E as EntityTypeUid, b as IEntityModel, c as IEntity, d as EntityProxy } from './index-B1KXekZD.js';
+import { I as IEventData, E as EntityEventUid, b as IEntityEvent, i as IEntitySnapshot, f as IEntityUpdate, h as IEntityRepository } from './entity-repository-BlSpo-x2.js';
+import { I as IPipelineContext, a as IPipeline } from './pipeline-BGsQiSer.js';
+import { IJsonSerializer, ILogger } from './utils/index.js';
+import { I as Immutable } from './types-cZ-1lGPD.js';
+
+/**
+ * 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 = "initialize",
+    /**
+     * The update phase of the Module pipeline.
+     * This phase is responsible for updating the game logic and state of entities.
+     */
+    update = "update",
+    /**
+     * The render phase of the Module pipeline.
+     * This phase is used for rendering the game to the screen.
+     */
+    render = "render",
+    /**
+     * The synchronization phase of the Module pipeline.
+     * This phase is used for synchronizing game state with external systems or other components.
+     */
+    sync = "sync"
+}
+
+/**
+ * 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;
+}
+
+/**
+ * The ISystemContextProxies interface provides access to EntityProxy related APIs.
+ * These APIs are accessed within a SystemMiddleware through the provided ISystemPipelineContext.
+ */
+interface ISystemContextProxies {
+    /**
+     * Registers a single EntityProxy instance.
+     *
+     * @param proxy - The EntityProxy instance to register.
+     * @param cleanup - Optional flag indicating whether all existing proxies should be removed.
+     *                  Default is false.
+     */
+    registerProxy(proxy: IEntityProxy, cleanup?: boolean): void;
+    /**
+     * Registers multiple EntityProxy instances.
+     *
+     * @param proxies - An array of EntityProxy instances to register.
+     * @param cleanup - Optional flag indicating whether all existing proxies should be removed.
+     *                  Default is false.
+     */
+    registerProxies(proxies: IEntityProxy[], cleanup?: boolean): void;
+    /**
+     * Removes a single EntityProxy instance.
+     *
+     * @param proxy - The EntityProxy instance to remove.
+     */
+    removeProxy(proxy: IEntityProxy): void;
+    /**
+     * Removes all EntityProxy instances associated with a specific entity type.
+     * If no entity type is provided, all registered proxies will be removed.
+     *
+     * @param proxyEntityType - Optional entity type UID.
+     */
+    removeProxies(proxyEntityType?: EntityTypeUid): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 allowed steps for the SystemPipelines.
+     */
+    readonly allowedSteps: 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>;
+}
+
+export { type ISystemsRuntimeContext as I, SystemType as S, type ISystemContext as a, type ISystemContextEntity as b, type ISystemContextEvents as c, type ISystemContextProxies as d, type ISystemContextRepository as e, type ISystemContextScheduler as f, type ISystemContextSnapshot as g };