@antha/entity-2d 0.0.1

package/dist/entity.d.ts

@@ -0,0 +1,436 @@
+import { type Asset, type AssetBulkLoaderLoadOptions, type AssetLoader, type AssetValue } from '@antha/asset';
+import { type PixiApplication } from '@antha/graphics-2d';
+import { ConstructorInstanceMap, type AnyObject, type ExtractKeysWithMatchingValues, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { System as HitboxSystem, type Response as Collision, type Body as Hitbox } from 'detect-collisions';
+import { type Shape } from 'object-shape-tester';
+import { type Container, type ViewContainer } from 'pixi.js';
+import { type AbstractConstructor, type Constructor, type EmptyObject, type IsEqual, type IsNever, type WritableKeysOf } from 'type-fest';
+import { GenericListenTarget } from 'typed-event-target';
+import { type StaticEntity2dParts } from './entity-suite.js';
+export { System as HitboxSystem, type Response as Collision } from 'detect-collisions';
+/**
+ * Definition of entity assets used when defining an entity.
+ *
+ * @category Internal
+ */
+export type BaseEntityAssetDefinitions = Record<string, Omit<Asset, 
+/** Name will be the value's key in this object. */
+'name'>>;
+/**
+ * A record of `Asset` entries.
+ *
+ * @category Internal
+ */
+export type BaseEntityAssets = Record<string, Asset>;
+/**
+ * Maps {@link BaseEntityAssetDefinitions} into full `Asset` instances.
+ *
+ * @category Internal
+ */
+export type MappedEntityAssets<Definitions extends BaseEntityAssetDefinitions | undefined> = Definitions extends undefined ? EmptyObject : {
+    [Key in keyof Definitions]: Definitions[Key] & {
+        name: string;
+    };
+};
+/**
+ * Parameters for {@link EntityStore2d.addEntity}. Flattens itself to an empty array if there are no
+ * entity constructor params.
+ *
+ * @category Internal
+ */
+export type AddEntity2dParams<ThisConstructor extends Entity2dConstructor> = ThisConstructor extends {
+    ConstructorArgsType: infer Args extends Entity2dConstructorParams<any, any>;
+} ? Args['params'] extends undefined ? [] : [Args['params']] : ['ERROR: invalid entity constructor'];
+/**
+ * Parameters for the constructor of {@link EntityStore2d}.
+ *
+ * @category Internal
+ */
+export type EntityStore2dConstructorParams<State extends AnyObject = any> = {
+    /**
+     * A PixiJS [`Application`](https://pixijs.download/release/docs/app.Application.html) instance
+     * from the [`pixi.js`](https://www.npmjs.com/package/pixi.js) package.
+     */
+    pixi: PixiApplication;
+    state: State;
+    assetLoader: AssetLoader;
+} & PartialWithUndefined<{
+    /**
+     * A `System` instance from the
+     * [`detect-collisions`](https://www.npmjs.com/package/detect-collisions) package. If this
+     * property is omitted or `undefined`, the {@link EntityStore2d} instance will create its own.
+     */
+    customHitboxSystem?: HitboxSystem | undefined;
+    /**
+     * An array of all entity constructors that will be pre-registered with this
+     * {@link EntityStore2d} instance.
+     */
+    preregisteredEntities: ReadonlyArray<Entity2dConstructor>;
+}>;
+/**
+ * A constructor that creates an Entity, as well as the static entity data that should be attached
+ * to it.
+ *
+ * @category Internal
+ */
+export type Entity2dConstructor = Constructor<BaseEntity2d> & StaticEntity2dParts;
+/**
+ * The top level storage class of all entities. Add entities with {@link EntityStore2d.addEntity}.
+ *
+ * @category Internal
+ */
+export declare class EntityStore2d<State extends AnyObject = any> {
+    /**
+     * All current child entities.
+     *
+     * Instead of modifying this set, use {@link EntityStore2d.addEntity} or
+     * {@link EntityStore2d.removeEntity}. If you must manually modify this set directly, you'll also
+     * need to modify {@link EntityStore2d.entityInstanceMap}.
+     */
+    readonly currentEntityInstances: Set<BaseEntity2d<any, any, any>>;
+    /** If true, this entity store should no longer be used or operated upon. */
+    readonly isDestroyed: boolean;
+    /** An internal mapping of all entity constructors to their current instances. */
+    readonly entityInstanceMap: ConstructorInstanceMap;
+    /** Original pixi app. */
+    readonly pixi: PixiApplication;
+    /** Collision detection system. */
+    readonly hitboxSystem: HitboxSystem;
+    /** A map of all entity keys to their registered Entity constructors. */
+    entityKeyConstructorMap: Record<string, Entity2dConstructor>;
+    /** Listen target for events emitted from any child entities. */
+    listenTarget: GenericListenTarget;
+    readonly state: State;
+    readonly assetLoader: AssetLoader;
+    constructor(args: Readonly<EntityStore2dConstructorParams>);
+    /**
+     * Load all the assets for all the given entities. Without this, assets will be loaded on demand
+     * only.
+     */
+    loadEntityAssets({ entities, otherAssets, }: Readonly<{
+        entities: ReadonlyArray<Entity2dConstructor>;
+        otherAssets?: ReadonlyArray<Readonly<Asset>> | undefined;
+    }>, options?: Readonly<AssetBulkLoaderLoadOptions> | undefined): Promise<readonly unknown[]>;
+    /**
+     * Register a set of entities so that they can be deserialized (for example, when transferring
+     * game state in across the network for multilayer).
+     */
+    registerEntities({ clearPreviousRegistrations, entities, }: Readonly<{
+        entities: ReadonlyArray<Entity2dConstructor>;
+    } & PartialWithUndefined<{
+        /** If set to true, all previous registrations will be removed. */
+        clearPreviousRegistrations: boolean;
+    }>>): void;
+    /**
+     * Runs `.update()` on all current entities and runs collision detection for all hitboxes. If
+     * any entities get marked as destroyed during their update, then they will be removed from the
+     * set of entities.
+     *
+     * @returns All detected hitbox collisions (if any).
+     */
+    updateAllEntities(updateParams: Readonly<EntityUpdateParams>): Promise<void>;
+    /** Get all current instances of the given entity class constructor. */
+    getEntities<T>(entityClassConstructor: AbstractConstructor<T> | Constructor<T>): Set<T>;
+    /** Remove an entity from the store. */
+    removeEntity(entity: BaseEntity2d): void;
+    /**
+     * Create an entity instance by finding the registered constructor with the given `entityKey`
+     * and then deserializing and passing the given `serializedParams` to that constructor.
+     */
+    deserializeEntity(entityKey: string, serializedParams: string | undefined): Promise<BaseEntity2d>;
+    /** Create a new instance of the given entity class and add it to this entity store. */
+    addEntity<const NewEntityConstructor extends Entity2dConstructor>(entityClass: NewEntityConstructor, ...params: AddEntity2dParams<NoInfer<NewEntityConstructor>>): Promise<InstanceType<NewEntityConstructor>>;
+    /** Destroys the entity store and all entities contained inside it. */
+    destroy(): void;
+}
+/**
+ * Shape definition for {@link EntityPositionParams}.
+ *
+ * @category Util
+ */
+export declare const entityPositionParamsShape: Shape<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Base entity serialization. All entities should at least include these properties.
+ *
+ * @category Internal
+ */
+export type EntityPositionParams = typeof entityPositionParamsShape.runtimeType;
+/**
+ * Parameters for an entity's constructor.
+ *
+ * @category Internal
+ */
+export type Entity2dConstructorParams<State extends AnyObject = any, Params extends Record<string, any> | undefined = undefined> = (IsNever<Extract<Params, undefined | null>> extends true ? {
+    params: Params;
+} : {
+    params?: Params;
+}) & {
+    state: State;
+    paramsMap?: ParamsMap<NoInfer<Params>> | undefined;
+    entityStore: EntityStore2d<State>;
+    pixi: PixiApplication;
+    hitboxSystem: HitboxSystem;
+};
+/**
+ * Finds all keys from `Params` that match the value at the given `Key` in `OriginalObject`.
+ *
+ * @category Internal
+ */
+export type MatchingKeys<Key extends PropertyKey, Params extends Record<string, any> | undefined, OriginalObject extends AnyObject> = Params extends Record<string, any> ? ExtractKeysWithMatchingValues<Params, Extract<OriginalObject, Record<Key, any>>[Key]> : never;
+/**
+ * An object that controls which entity parameter projects get mapped to view and hitbox properties.
+ * Values can be:
+ *
+ * - `true`: indicates that the property is mapped directly from params to that view or hitbox object.
+ * - Omitted: the property is not mapped at all.
+ * - A string: specifies the params key that this view or hitbox property is mapped to.
+ */
+export type ParamsMap<Params extends Record<string, any> | undefined = AnyObject> = IsEqual<Params, undefined> extends true ? undefined : PartialWithUndefined<{
+    view: Partial<{
+        [Key in WritableKeysOf<ViewContainer> as IsNever<MatchingKeys<Key, Params, ViewContainer>> extends true ? never : Key]: (Key extends keyof Params ? Params[Key] extends ViewContainer[Key] ? true : never : never) | MatchingKeys<Key, Params, ViewContainer>;
+    }>;
+    hitbox: Partial<{
+        [Key in WritableKeysOf<Hitbox> as IsNever<MatchingKeys<Key, Params, Hitbox>> extends true ? never : Key]: (Key extends keyof Params ? Params[Key] extends Extract<Hitbox, Record<Key, any>>[Key] ? true : never : never) | MatchingKeys<Key, Params, Hitbox>;
+    }>;
+}>;
+declare const EntityEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: {
+        data?: any;
+        entityInstance: BaseEntity2d;
+    };
+}) => import("typed-event-target").TypedCustomEvent<{
+    data?: any;
+    entityInstance: BaseEntity2d;
+}, "antha-entity-event">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<{
+    data?: any;
+    entityInstance: BaseEntity2d;
+}, "antha-entity-event">, "type">;
+/**
+ * The bse of all entity-specific events.
+ *
+ * @category Internal
+ */
+export declare class EntityEvent<const Data = any> extends EntityEvent_base {
+    readonly detail: Readonly<undefined | void extends Data ? {
+        entityInstance: BaseEntity2d;
+        data?: never;
+    } : {
+        entityInstance: BaseEntity2d;
+        data: Data;
+    }>;
+    constructor(detail: Readonly<undefined | void extends Data ? {
+        entityInstance: BaseEntity2d;
+        data?: never;
+    } : {
+        entityInstance: BaseEntity2d;
+        data: Data;
+    }>);
+}
+/**
+ * Event emitted by all entities when they are destroyed.
+ *
+ * @category Internal
+ */
+export declare class EntityDestroyEvent extends EntityEvent<void> {
+}
+/**
+ * Default params shape for x, y position coordinates.
+ *
+ * Use with {@link position2dParamsMap}, or something similar.
+ *
+ * @category Internal
+ */
+export declare const position2dParamsShape: Shape<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Default value for the optional {@link ParamsMap}. This maps the top level params of `x` and `y` to
+ * both `x` and `y` in the hitbox and view.
+ *
+ * Use with {@link position2dParamsShape}, or something similar.
+ *
+ * @category Internal
+ */
+export declare const position2dParamsMap: {
+    readonly hitbox: {
+        x: true;
+        y: true;
+    };
+    readonly view: {
+        x: true;
+        y: true;
+    };
+};
+/**
+ * Type for {@link BaseEntity2d.reverseParamsMap}.
+ *
+ * @category Internal
+ */
+export type ReverseParamsMap = Record<string, Partial<Record<'hitbox' | 'view', string[]>>>;
+/**
+ * The parameters given to entity update methods.
+ *
+ * @category Internal
+ */
+export type EntityUpdateParams = {
+    msSinceLastUpdate: number;
+};
+/**
+ * Base entity class, types, and functionality.
+ *
+ * @category Internal
+ */
+export declare abstract class BaseEntity2d<State extends AnyObject = any, Params extends Record<string, any> | undefined = any, EntityAssets extends BaseEntityAssetDefinitions | undefined = any> {
+    /**
+     * This key is used for deserialization of entities to track which class needs to be
+     * constructed. You cannot have duplicate keys loaded at the same time.
+     */
+    static readonly entityKey: string;
+    /** Shape definition of this entity's parameters. */
+    static readonly paramsShape: Shape<AnyObject> | undefined;
+    static readonly assets: MappedEntityAssets<BaseEntityAssetDefinitions | undefined> | undefined;
+    /**
+     * Defines which properties from {@link BaseEntity2d.params} will be mapped to hitbox and/or view
+     * properties.
+     */
+    static readonly paramsMap: ParamsMap | undefined;
+    /**
+     * A mapping from params properties to hitbox or view properties, making it easy to map params
+     * values.
+     */
+    static readonly reverseParamsMap: ReverseParamsMap | undefined;
+    /** Parses the serialized params generated by {@link BaseEntity2d.serialize}. */
+    static deserialize(serialized: string | undefined): AnyObject | undefined;
+    /**
+     * Dispatch an event. This will be dispatched through this entity's entity store (so listen for
+     * the event on the store).
+     */
+    dispatch(event: EntityEvent | EntityDestroyEvent): void;
+    /** If true, this entity should no longer be used or operated upon. */
+    readonly isDestroyed: boolean;
+    private readonly abortController;
+    /** An `AbortSignal` that triggers when the entity is destroyed. */
+    readonly abortSignal: AbortSignal;
+    hitbox: Hitbox<this> | undefined;
+    /** The entity store to add all entities to. */
+    readonly entityStore: EntityStore2d<State>;
+    /** Writable entity params. These should be serializable. */
+    readonly params: Params;
+    /** Original pixi app. */
+    readonly pixi: PixiApplication;
+    /** Collision detection system. */
+    readonly hitboxSystem: HitboxSystem;
+    getAsset: EntityAssetAccessor<MappedEntityAssets<EntityAssets>>;
+    constructor(args: Readonly<Entity2dConstructorParams<NoInfer<State>, NoInfer<Params>>>);
+    /**
+     * Called every game tick. Run all entity updates in here. This should be overridden in all
+     * entity definition classes.
+     */
+    abstract update(updateParams: Readonly<EntityUpdateParams>): MaybePromise<void>;
+    /** Called after construction to perform async initialization (e.g. creating views). */
+    initInstance(): MaybePromise<void>;
+    /** The game's current state. */
+    state: State;
+    /** Add a new entity to the entity store. */
+    addEntity<const NewEntityConstructor extends Entity2dConstructor>(entityClass: NewEntityConstructor, ...params: AddEntity2dParams<NoInfer<NewEntityConstructor>>): Promise<InstanceType<NewEntityConstructor>>;
+    /** Marks the entity for destruction in the next entity store update. */
+    destroy(): void;
+    /**
+     * Immediately destroy the current entity, stop its updates.
+     *
+     * This is probably not what you want to use! See {@link BaseEntity2d.destroy} instead.
+     */
+    immediatelyDestroy(): void;
+    /**
+     * This method is call whenever this entity's hitbox (if it has one) collides with another
+     * hitbox. It will be called for each individual collision. Override this to do something about
+     * it.
+     */
+    collide(otherEntity: BaseEntity2d, collision: Readonly<Collision>): MaybePromise<void>;
+    /**
+     * Serialize the entity params for sharing across the network (for multiplayer play). By default
+     * this simply calls `JSON.stringify` on `this.params`. This method must be overridden if your
+     * entity has params that are not JSON compatible.
+     */
+    serialize(): string | undefined;
+}
+/**
+ * Output of {@link ViewEntity2d.createView}.
+ *
+ * @category Internal
+ */
+export type ViewCreation2d = {
+    /**
+     * A view for rendering. Create with, for example, [`new
+     * AnimatedSprite`](https://pixijs.download/release/docs/scene.AnimatedSprite.html) or [`new
+     * Graphics`](https://pixijs.download/release/docs/scene.Graphics.html), etc. imported from the
+     * [`pixi.js`](https://www.npmjs.com/package/pixi.js) package.
+     */
+    view?: Container | undefined;
+    /**
+     * A Body instance for hitbox collision detection. Create one with, for example,
+     * `this.hitboxSystem.createBox()` or import directly from the
+     * [`detect-collisions`](https://www.npmjs.com/package/detect-collisions) package, like with
+     * [`new Circle`](https://prozi.github.io/detect-collisions/classes/Circle.html#constructor).
+     *
+     * This property optional, if a hitbox is not provided, collision detection will not be
+     * calculated for this entity.
+     */
+    hitbox?: Hitbox | undefined;
+};
+/**
+ * Creates async accessors for all entity assets.
+ *
+ * @category Internal
+ */
+export type EntityAssetAccessor<EntityAssets extends BaseEntityAssetDefinitions | undefined> = EntityAssets extends undefined ? EmptyObject : {
+    [Key in keyof EntityAssets]: () => Promise<AssetValue<NonNullable<EntityAssets>[Key]>>;
+};
+/**
+ * Base view entity class, types, and functionality.
+ *
+ * @category Internal
+ */
+export declare abstract class ViewEntity2d<State extends AnyObject = any, Params extends Record<string, any> | undefined = any, EntityAssets extends BaseEntityAssetDefinitions | undefined = any> extends BaseEntity2d<State, Params, EntityAssets> {
+    /** The entity's PixiJS view. */
+    view: Container;
+    /** Creates the view and hitbox, adds the view to the stage, and sets up the params proxy. */
+    initInstance(): Promise<void>;
+    constructor(args: Readonly<Entity2dConstructorParams<NoInfer<State>, NoInfer<Params>>>);
+    private wrapParamsInProxy;
+    /**
+     * Creates the entity's PixiJS view. This will be called on entity construction and added to the
+     * PixiJS application stage.
+     */
+    abstract createView(): MaybePromise<ViewCreation2d>;
+    /** Detects if the current entity is still within the bounds of the render canvas. */
+    isInBounds(options?: PartialWithUndefined<{
+        /**
+         * If `true`, the entire entity's bounds must be within the canvas's bounds. If `false`,
+         * any portion of the entity being within the canvas bounds is counted.
+         *
+         * @default false
+         */
+        entirely?: boolean;
+    }>): boolean;
+    /**
+     * Immediately destroy the current entity, stop its updates, and remove it from the view.
+     *
+     * This is probably not what you want to use! See {@link BaseEntity2d.destroy} instead.
+     */
+    immediatelyDestroy(): void;
+}