@awesome-ecs/abstract 0.21.1 → 0.23.0

package/dist/index-CQpE-5sx.d.mts

@@ -0,0 +1,309 @@
+import { a as IEntity, l as IEntityProxy, m as IComponent, n as IdentityComponent, o as IEntityModel, r as EntityTypeUid } from "./identity-component-BCmEilvk.mjs";
+
+//#region src/entities/entity-events.d.ts
+/**
+ * Represents a unique identifier for an entity event.
+ * Can be either a string or a number.
+ */
+type EntityEventUid = string | number;
+/**
+ * A filter function for entity event subscriptions.
+ * Returns true if the event should be processed, false otherwise.
+ */
+type EntityEventSubscriptionFilter = (event: IEntityEvent<IEventData>) => boolean;
+/**
+ * The `IEventData` interface represents the data associated with an entity event.
+ * It contains at least the `Event Unique Identifier`.
+ */
+interface IEventData {
+  uid: EntityEventUid;
+}
+/**
+ * Represents a publishable event in the entity system.
+ * Enables loosely-coupled communication between entities through an Observer pattern.
+ * Events include origin, optional target, and typed data payload.
+ *
+ * @template TEventData - The type of data carried by this event.
+ */
+interface IEntityEvent<TEventData extends IEventData> {
+  /**
+   * The entity that originated this event.
+   */
+  origin: IEntityProxy;
+  /**
+   * Optional target entity for this event.
+   * If omitted, the event is broadcast to all subscribers.
+   */
+  target?: IEntityProxy;
+  /**
+   * The event payload containing type-specific data.
+   */
+  data: TEventData;
+}
+/**
+ * Manages subscriptions and dispatching for entity events.
+ * Implements the Observer pattern to decouple event producers from consumers.
+ * Tracks which entities are interested in which event types and maintains subscription state.
+ */
+interface IEntityEventsManager {
+  /**
+   * Subscribes an entity to a specific event type.
+   * The entity will be notified when events of that type are dispatched.
+   * @param uid - The event type to subscribe to.
+   * @param entity - The entity registering for this event type.
+   * @param filter - Optional function to determine which specific events are processed.
+   */
+  subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+  /**
+   * Unsubscribes an entity from a specific event type.
+   * The entity will no longer receive notifications for this event type.
+   * @param uid - The event type to unsubscribe from.
+   * @param entity - The entity unregistering from this event type.
+   */
+  unsubscribe(uid: EntityEventUid, entity: IEntityProxy): void;
+  /**
+   * Retrieves all entities subscribed to a specific event.
+   * @param event - The event to get subscriptions for.
+   * @returns Array of entities subscribed to this event.
+   */
+  getSubscriptions(event: IEntityEvent<IEventData>): IEntityProxy[];
+  /**
+   * Retrieves all event types an entity is subscribed to.
+   * @param entity - The entity to query.
+   * @returns Array of event type identifiers this entity is listening to.
+   */
+  getSubscriptionsForEntity(entity: IEntityProxy): EntityEventUid[];
+  /**
+   * Removes all subscriptions system-wide.
+   */
+  clearSubscriptions(): void;
+  /**
+   * Removes all subscriptions for a specific event type.
+   * @param uid - The event type to remove subscriptions from.
+   */
+  clearSubscriptionsForEvent(uid: EntityEventUid): void;
+  /**
+   * Removes all subscriptions for a specific entity.
+   * @param entity - The entity to remove all subscriptions for.
+   */
+  clearSubscriptionsForEntity(entity: IEntityProxy): void;
+}
+/**
+ * Event dispatcher for publishing events to interested entities.
+ * Responsible for routing events to their subscribers through the update queue.
+ */
+interface IEntityEventsDispatcher {
+  /**
+   * Publishes a single event to subscribers.
+   * The event is routed based on subscriptions or explicit target(s).
+   * @param event - The event to dispatch.
+   * @param targets - Optional specific entities to send to. If provided, event is only sent to these targets.
+   */
+  dispatchEvent(event: IEntityEvent<IEventData>, ...targets: IEntityProxy[]): void;
+  /**
+   * Publishes multiple events to subscribers.
+   * Efficiently dispatches an array of events in bulk.
+   * @param events - The events to dispatch.
+   * @param targets - Optional specific entities to send to. If provided, events are only sent to these targets.
+   */
+  dispatchEvents(events: IEntityEvent<IEventData>[], ...targets: IEntityProxy[]): void;
+}
+//#endregion
+//#region src/entities/entity-snapshot.d.ts
+/**
+ * A serializable representation of entity state.
+ * Captures full or partial entity state including components, relationships, and events.
+ * Snapshots enable state replication, persistence, and delta updates from external sources.
+ */
+interface IEntitySnapshot {
+  /**
+   * The entity's identity information if included in the snapshot.
+   */
+  readonly identity?: Readonly<IdentityComponent<IEntityModel>>;
+  /**
+   * Entity components to be included in the snapshot.
+   * Only components marked as serializable are typically included.
+   */
+  readonly components?: IComponent[];
+  /**
+   * Entity relationships (proxies) to include in the snapshot.
+   */
+  readonly proxies?: IEntityProxy[];
+  /**
+   * Events associated with the entity to include in the snapshot.
+   */
+  readonly events?: IEntityEvent<IEventData>[];
+}
+/**
+ * Handles snapshot creation and application.
+ * Provides abstraction for converting between entities and their serializable snapshots.
+ * Used for state persistence, synchronization, and entity updates from external sources.
+ */
+interface IEntitySnapshotProvider {
+  /**
+   * Applies a snapshot state to an entity.
+   * Updates the entity's components, relationships, and events based on the snapshot.
+   * @param entity - The entity to update.
+   * @param snapshot - The state to apply.
+   */
+  applySnapshot(entity: IEntity, snapshot: IEntitySnapshot): void;
+  /**
+   * Creates a snapshot capturing the current state of an entity.
+   * Serializes all or specified parts of the entity for storage or transmission.
+   * @param entity - The entity to snapshot.
+   * @returns A serializable representation of the entity state.
+   */
+  createSnapshot(entity: IEntity): IEntitySnapshot;
+}
+//#endregion
+//#region src/entities/entity-queue.d.ts
+/**
+ * Specifies the action to be performed on an entity.
+ * Updates are categorized to enable different processing paths in the runtime.
+ */
+declare enum EntityUpdateType {
+  /**
+   * Indicates the entity should be updated with new data.
+   */
+  update = "update",
+  /**
+   * Indicates the entity should be removed from the system.
+   */
+  remove = "remove"
+}
+/**
+ * Represents a queued entity state change or removal.
+ * Updates flow through the system to be processed by entity update handlers.
+ */
+interface IEntityUpdate {
+  /**
+   * The type of operation: update or remove.
+   */
+  readonly type: EntityUpdateType;
+  /**
+   * The entity being affected by this update.
+   */
+  readonly entity: IEntityProxy;
+  /**
+   * Optional model data for initialization or reconfiguration.
+   */
+  readonly model?: IEntityModel;
+  /**
+   * Optional serialized state to apply to the entity.
+   */
+  readonly snapshot?: IEntitySnapshot;
+}
+/**
+ * Queue interface for managing pending entity updates.
+ * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).
+ * Updates are consumed by the runtime and dispatched to appropriate entity systems.
+ */
+interface IEntityUpdateQueue {
+  /**
+   * The current number of updates in the queue.
+   */
+  readonly size: number;
+  /**
+   * Adds an update to the queue for processing.
+   * @param change - The update to queue.
+   */
+  enqueue(change: IEntityUpdate): void;
+  /**
+   * Removes and returns the next update from the queue.
+   * The specific update returned depends on the queue's prioritization strategy.
+   * @returns The next queued update.
+   */
+  dequeue(): IEntityUpdate;
+  /**
+   * Views the next update without removing it.
+   * Useful for inspection before dequeuing.
+   * @returns The next update in the queue.
+   */
+  peek(): IEntityUpdate;
+  /**
+   * Removes all updates from the queue.
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/entities/entity-repository.d.ts
+/**
+ * Central storage for all active entities in the system.
+ * The repository provides CRUD operations and is the source of truth for entity existence and state.
+ * All entity access and modifications go through this repository.
+ */
+interface IEntityRepository {
+  /**
+   * The total number of entities currently stored.
+   */
+  readonly size: number;
+  /**
+   * Checks if an entity exists in storage.
+   * @param proxy - Reference to the entity to check.
+   * @returns True if the entity exists, false otherwise.
+   */
+  has(proxy: IEntityProxy): boolean;
+  /**
+   * Retrieves an entity from storage by proxy.
+   * @template TEntity - The expected entity type.
+   * @param proxy - Reference to the entity to retrieve.
+   * @returns The requested entity.
+   */
+  get<TEntity extends IEntity>(proxy: IEntityProxy): TEntity;
+  /**
+   * Retrieves all entities of a specific type.
+   * @template TEntity - The entity type to retrieve.
+   * @param entityType - The type identifier to filter by.
+   * @returns Array of all entities matching the type.
+   */
+  getAll<TEntity extends IEntity>(entityType: EntityTypeUid): TEntity[];
+  /**
+   * Iterates over all entities regardless of type.
+   * @returns An iterator over all stored entities.
+   */
+  listAll(): IterableIterator<IEntity>;
+  /**
+   * Stores or updates an entity.
+   * @param entity - The entity to store.
+   */
+  set(entity: IEntity): void;
+  /**
+   * Removes an entity from storage.
+   * @param proxy - Reference to the entity to remove.
+   */
+  delete(proxy: IEntityProxy): void;
+  /**
+   * Removes all entities of a specific type from storage.
+   * @param entityType - The type identifier for entities to remove.
+   */
+  clear(entityType: EntityTypeUid): void;
+}
+//#endregion
+//#region src/entities/entity-scheduler.d.ts
+/**
+ * Manages time-based scheduling of entity updates.
+ * Entities are registered with intervals and receive updates at the specified cadence, or on the next frame (engine-dependent).
+ */
+interface IEntityScheduler {
+  /**
+   * Registers an entity for periodic updates.
+   * @param entityProxy - The entity to schedule.
+   * @param intervalMs - Update frequency in milliseconds. If omitted, a default interval is used.
+   */
+  schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
+  /**
+   * Unregisters an entity from the scheduler.
+   * The entity will no longer receive periodic updates.
+   * @param entityProxy - The entity to unschedule.
+   */
+  remove(entityProxy: IEntityProxy): void;
+  /**
+   * Checks if an entity is currently scheduled for updates.
+   * @param entityProxy - The entity to check.
+   * @returns True if the entity is scheduled, false otherwise.
+   */
+  has(entityProxy: IEntityProxy): boolean;
+}
+//#endregion
+export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEventsDispatcher as d, IEntityEventsManager as f, IEntityUpdate as i, EntityEventUid as l, IEntityRepository as n, IEntitySnapshot as o, IEventData as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, IEntityEvent as u };
+//# sourceMappingURL=index-CQpE-5sx.d.mts.map