@awesome-ecs/abstract/dist/identity-component-BDWEtAXA.d.cts

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

import { BooleanProps, Immutable } from "./types-DvzdpbLu.cjs";

//#region src/components/component.d.ts
type ComponentTypeUid = string | number;
/**
 * The `IComponent` interface provides the main storage mechanism of `IEntity` state, and can be accessed and modified by `Systems`.
 *
 * The `IComponent` implementations should not contain any logic methods, apart from quick-access functionality.
 */
interface IComponent {
  /**
   * The `ComponentTypeUid` is a unique identifier for each Component type.
   * @type {ComponentTypeUid}
   */
  readonly componentType: ComponentTypeUid;
  /**
   * Specifies whether the Component state should be serialized as part of an `IEntitySnapshot`.
   * This is useful if the state needs to be replicated or updated through remote updates (e.g., coming from the server or peers).
   * @type {boolean}
   */
  readonly isSerializable: boolean;
  /**
   * @optional
   * Specifies the current version of the component.
   * This is useful for keeping backwards-compatibility when the stored state might be of a different version.
   * @type {number}
   */
  readonly version?: number;
  /**
   * @optional
   * The custom serialization function of this Component, used to transfer it into a Snapshot, or used for logging the Component stored state.
   * If not provided, the standard `JSON.stringify()` functionality applies.
   * @returns {string | object} The serialized form of the Component.
   */
  toJSON?(): string | object;
  /**
   * Allows for custom logic when loading the current from an `IEntitySnapshot`.
   * The default behavior simply overwrites the fields with the target state.
   * @param {this} targetState The target state to load from.
   */
  load?(targetState: this): void;
}
//#endregion
//#region src/entities/entity-proxies.d.ts
/**
 * The `IEntityProxy` represents a pointer to another `Entity`.
 */
interface IEntityProxy {
  /**
   * The type of the entity that the proxy points to.
   */
  readonly entityType: EntityTypeUid;
  /**
   * The unique identifier of the entity that the proxy points to.
   */
  readonly entityUid: EntityUid;
}
/**
 * A utility extension of `IEntityProxy`.
 * Useful for providing strong `Type` information when using the IEntityProxy.
 *
 * @template TEntity - The type of the entity that the proxy points to.
 */
interface EntityProxy<TEntity extends IEntity> extends IEntityProxy {}
/**
 * A helper type to create a typed entity proxy.
 */
type TypedEntityProxy<T extends EntityTypeUid> = {
  entityType: T;
  entityUid: EntityUid;
};
/**
 * A mapped type that transforms an array of EntityType into an array of TypedEntityProxy.
 */
type RequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> = [...{ [I in keyof TProxyTypes]: TypedEntityProxy<TProxyTypes[I]> }, ...IEntityProxy[]];
/**
 * A repository for managing entity-to-entity relationships (proxies).
 * This centralized repository is the single source of truth for all proxy data.
 */
interface IEntityProxyRepository {
  /**
   * Registers a bi-directional proxy relationship between a source and a target.
   * @param source - The proxy of the source entity.
   * @param target - The proxy of the target entity.
   * @param cleanup - If true, any existing proxies of the same type on the source and target will be removed before registering the new one.
   */
  register(source: IEntityProxy, target: IEntityProxy, cleanup?: boolean): void;
  /**
   * Registers multiple bi-directional proxy relationships for a source entity.
   * @param source - The proxy of the source entity.
   * @param targets - The proxies of the target entities.
   * @param cleanup - If true, any existing proxies of the same types as the new targets will be removed from the source before registering.
   */
  registerMany(source: IEntityProxy, targets: readonly IEntityProxy[], cleanup?: boolean): void;
  /**
   * Removes a bi-directional proxy relationship between a source and a target.
   * @param source - The proxy of the source entity.
   * @param target - The proxy of the target entity.
   */
  remove(source: IEntityProxy, target: IEntityProxy): void;
  /**
   * Removes all proxies from a source entity, optionally filtered by the target entity type.
   * This will also remove the corresponding back-references from the target entities.
   * @param source - The proxy of the source entity.
   * @param targetType - The optional entity type of the targets to remove. If not provided, all proxies for the source are removed.
   */
  removeAllFor(source: IEntityProxy, targetType?: EntityTypeUid): void;
  /**
   * Retrieves a single proxy of a specific type for a source entity.
   * If multiple proxies of the same type exist, it returns the first one found.
   * @param source - The proxy of the source entity.
   * @param targetType - The entity type of the target proxy to retrieve.
   * @returns The entity proxy, or null if not found.
   */
  get(source: IEntityProxy, targetType: EntityTypeUid): IEntityProxy | null;
  /**
   * Retrieves all proxies of a specific type for a source entity.
   * @param source - The proxy of the source entity.
   * @param targetType - The entity type of the target proxies to retrieve.
   * @returns A readonly array of entity proxies.
   */
  getMany(source: IEntityProxy, targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
  /**
   * Retrieves all proxies for a source entity.
   * @param source - The proxy of the source entity.
   * @returns A readonly map of entity type UIDs to an array of their proxies.
   */
  getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
}
//#endregion
//#region src/entities/entity.d.ts
/**
 * Represents the unique identifier for an entity type.
 * Can be either a string or a number.
 */
type EntityTypeUid = string | number;
/**
 * Represents the unique identifier for an entity.
 * Can be either a string or a number.
 */
type EntityUid = string | number;
/**
 * The `IEntityModel` represents the basic identity information about the current `IEntity`.
 * It's mandatory for each Entity, and it contains the minimal-required information needed for instantiating the Entity.
 *
 * The Features property can be used to toggle Entity features on and off.
 *
 * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
 *                      Defaults to `unknown` if not provided.
 */
interface IEntityModel {
  /**
   * The unique identifier of the entity.
   */
  readonly uid: EntityUid;
  /**
   * Optional proxies of the entity.
   */
  readonly proxies?: readonly IEntityProxy[];
}
/**
 * Base interface for entity models that require feature flags.
 * @template TFeatures - A type that extends `BooleanProps<TFeatures>` to represent the features of the entity.
 */
interface IEntityModelWithFeatures<TFeatures extends BooleanProps<TFeatures> = unknown> extends IEntityModel {
  readonly features: TFeatures;
}
/**
 * Base interface for entity models that require specific proxies.
 * @template TProxyTypes An array of EntityType that are required as proxies.
 */
interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends Omit<IEntityModel, 'proxies'> {
  readonly proxies: RequiredProxies<TProxyTypes>;
}
/**
 * The `IEntity` interface represents a container of Components and Entity Proxies.
 * It is designed to be immutable and only modifiable through System operations.
 *
 * Implementations of `IEntity` can contain quick-access methods for `Components` or `Proxies`,
 * but should not contain any state-changing logic apart from quick-access functionality.
 */
interface IEntity {
  /**
   * A Map of Components associated with this Entity.
   * The keys are ComponentTypeUid, and the values are IComponent instances.
   */
  readonly components: ReadonlyMap<ComponentTypeUid, IComponent>;
  /**
   * The IdentityComponent represents mandatory state any Entity needs to have.
   * It is a readonly reference to an IdentityComponent instance, which contains the minimal-required information
   * needed for instantiating the Entity.
   */
  readonly identity: Readonly<IdentityComponent<IEntityModel>>;
  /**
   * A reference to the own Proxy of this Entity.
   * It is a readonly reference to an IEntityProxy instance, which points to this Entity.
   * This is useful for quick access of Proxy data.
   */
  readonly myProxy: Readonly<EntityProxy<this>>;
}
//#endregion
//#region src/components/identity-component.d.ts
/**
 * The `BasicComponentType` enum defines the types of basic components available.
 */
declare enum BasicComponentType {
  identity = "identity",
}
/**
 * IdentityComponent interface represents the basic information regarding what makes the current Entity unique.
 * It extends the IComponent interface.
 *
 * @template TModel - The type of the model that extends IEntityModel.
 */
interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
  /**
   * The Entity Type that defines what Category type the Entity is part of.
   * There can be multiple Entities sharing the same EntityType.
   */
  readonly entityType: EntityTypeUid;
  /**
   * The Model is the basic information needed to create an `IEntity` when it's first initialized.
   * It provides a first snapshot of information needed for the successful creation of an Entity instance.
   *
   * @type {Immutable<TModel>}
   */
  readonly model: Immutable<TModel>;
  /**
   * Keeps track when the Entity's systems have ran last.
   * Useful to calculate the `DeltaTime` between runs.
   *
   * @type {Date | undefined}
   */
  readonly lastUpdated?: Date;
}
//#endregion
export { BasicComponentType, ComponentTypeUid, EntityProxy, EntityTypeUid, EntityUid, IComponent, IEntity, IEntityModel, IEntityModelWithFeatures, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IdentityComponent, RequiredProxies, TypedEntityProxy };
//# sourceMappingURL=identity-component-BDWEtAXA.d.cts.map