@antha/entity-2d 0.0.1

package/dist/entity.js

@@ -0,0 +1,464 @@
+import { assert, check } from '@augment-vir/assert';
+import { ConstructorInstanceMap, getObjectTypedEntries, makeWritable, mapObjectValues, } from '@augment-vir/common';
+import { System as HitboxSystem, } from 'detect-collisions';
+import { assertValidShape, defineShape } from 'object-shape-tester';
+import { ParticleContainer } from 'pixi.js';
+import { defineTypedCustomEvent, GenericListenTarget } from 'typed-event-target';
+export { System as HitboxSystem } from 'detect-collisions';
+/**
+ * The top level storage class of all entities. Add entities with {@link EntityStore2d.addEntity}.
+ *
+ * @category Internal
+ */
+export class EntityStore2d {
+    /**
+     * 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}.
+     */
+    currentEntityInstances = new Set();
+    /** If true, this entity store should no longer be used or operated upon. */
+    isDestroyed = false;
+    /** An internal mapping of all entity constructors to their current instances. */
+    entityInstanceMap = new ConstructorInstanceMap();
+    /** Original pixi app. */
+    pixi;
+    /** Collision detection system. */
+    hitboxSystem;
+    /** A map of all entity keys to their registered Entity constructors. */
+    entityKeyConstructorMap = {};
+    /** Listen target for events emitted from any child entities. */
+    listenTarget = new GenericListenTarget();
+    state;
+    assetLoader;
+    constructor(args) {
+        this.pixi = args.pixi;
+        this.assetLoader = args.assetLoader;
+        this.hitboxSystem = args.customHitboxSystem || new HitboxSystem();
+        this.state = args.state;
+        if (args.preregisteredEntities) {
+            this.registerEntities({
+                entities: args.preregisteredEntities,
+                clearPreviousRegistrations: true,
+            });
+        }
+    }
+    /**
+     * Load all the assets for all the given entities. Without this, assets will be loaded on demand
+     * only.
+     */
+    async loadEntityAssets({ entities, otherAssets, }, options) {
+        const assets = [
+            ...(otherAssets || []),
+            ...entities.flatMap((entity) => {
+                return Object.values(entity.assets).map((asset) => {
+                    return asset;
+                });
+            }),
+        ];
+        return await this.assetLoader.bulkLoadAssets(assets, options);
+    }
+    /**
+     * 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, }) {
+        if (clearPreviousRegistrations) {
+            this.entityKeyConstructorMap = {};
+        }
+        entities.forEach((entity) => {
+            this.entityKeyConstructorMap[entity.entityKey] = entity;
+        });
+    }
+    /**
+     * 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).
+     */
+    async updateAllEntities(updateParams) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on a destroyed entity store.');
+        }
+        for (const entity of this.currentEntityInstances) {
+            /** Check if the entity was destroyed outside of an update cycle. */
+            if (entity.isDestroyed) {
+                entity.immediatelyDestroy();
+                return;
+            }
+            await entity.update(updateParams);
+            /** Check if the entity was destroyed while updating. */
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (entity.isDestroyed) {
+                entity.immediatelyDestroy();
+            }
+        }
+        this.hitboxSystem.update();
+        const collisionPromises = [];
+        /**
+         * This `checkAll` method is synchronous, so even though its using a callback it'll still
+         * finish before this `updateAllEntities` method exits.
+         */
+        this.hitboxSystem.checkAll((response) => {
+            const primaryEntity = response.a.userData instanceof BaseEntity2d ? response.a.userData : undefined;
+            const secondaryEntity = response.b.userData instanceof BaseEntity2d ? response.b.userData : undefined;
+            if (!primaryEntity ||
+                !secondaryEntity ||
+                primaryEntity.isDestroyed ||
+                secondaryEntity.isDestroyed) {
+                return;
+            }
+            const result = primaryEntity.collide(secondaryEntity, response);
+            if (result instanceof Promise) {
+                collisionPromises.push(result);
+            }
+        });
+        await Promise.all(collisionPromises);
+    }
+    /** Get all current instances of the given entity class constructor. */
+    getEntities(entityClassConstructor) {
+        return this.entityInstanceMap.getInstances(entityClassConstructor);
+    }
+    /** Remove an entity from the store. */
+    removeEntity(entity) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on a destroyed entity store.');
+        }
+        this.currentEntityInstances.delete(entity);
+        this.entityInstanceMap.remove(entity);
+        if (entity instanceof ViewEntity2d && !entity.isDestroyed) {
+            // eslint-disable-next-line unicorn/prefer-dom-node-remove
+            this.pixi.stage.removeChild(entity.view);
+            if (entity.hitbox) {
+                this.hitboxSystem.remove(entity.hitbox);
+            }
+        }
+    }
+    /**
+     * Create an entity instance by finding the registered constructor with the given `entityKey`
+     * and then deserializing and passing the given `serializedParams` to that constructor.
+     */
+    async deserializeEntity(entityKey, serializedParams) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on a destroyed entity store.');
+        }
+        const entityConstructor = this.entityKeyConstructorMap[entityKey];
+        if (!entityConstructor) {
+            throw new Error(`No entity registered for key '${entityKey}'`);
+        }
+        return await this.addEntity(entityConstructor, entityConstructor.deserialize(serializedParams));
+    }
+    /** Create a new instance of the given entity class and add it to this entity store. */
+    async addEntity(entityClass, ...params) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on a destroyed entity store.');
+        }
+        if (!(entityClass.entityKey in this.entityKeyConstructorMap)) {
+            this.entityKeyConstructorMap[entityClass.entityKey] = entityClass;
+        }
+        const child = new entityClass({
+            entityStore: this,
+            pixi: this.pixi,
+            state: this.state,
+            params: params[0],
+            hitboxSystem: this.hitboxSystem,
+        });
+        await child.initInstance();
+        this.currentEntityInstances.add(child);
+        this.entityInstanceMap.add(child);
+        return child;
+    }
+    /** Destroys the entity store and all entities contained inside it. */
+    destroy() {
+        if (this.isDestroyed) {
+            throw new Error('Entity store is already destroyed.');
+        }
+        this.currentEntityInstances.forEach((entity) => entity.destroy());
+        makeWritable(this).isDestroyed = true;
+        this.listenTarget.destroy();
+        this.currentEntityInstances.clear();
+        this.entityInstanceMap.destroy();
+        delete this.pixi;
+        delete this.hitboxSystem;
+        delete this.listenTarget;
+    }
+}
+/**
+ * Shape definition for {@link EntityPositionParams}.
+ *
+ * @category Util
+ */
+export const entityPositionParamsShape = defineShape({
+    x: -1,
+    y: -1,
+});
+/**
+ * The bse of all entity-specific events.
+ *
+ * @category Internal
+ */
+export class EntityEvent extends defineTypedCustomEvent()('antha-entity-event') {
+    constructor(detail) {
+        super({
+            detail,
+        });
+    }
+}
+/**
+ * Event emitted by all entities when they are destroyed.
+ *
+ * @category Internal
+ */
+export class EntityDestroyEvent extends EntityEvent {
+}
+/**
+ * Default params shape for x, y position coordinates.
+ *
+ * Use with {@link position2dParamsMap}, or something similar.
+ *
+ * @category Internal
+ */
+export const position2dParamsShape = defineShape({
+    x: -1,
+    y: -1,
+});
+/**
+ * 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 const position2dParamsMap = {
+    hitbox: {
+        x: true,
+        y: true,
+    },
+    view: {
+        x: true,
+        y: true,
+    },
+};
+/**
+ * Base entity class, types, and functionality.
+ *
+ * @category Internal
+ */
+export class BaseEntity2d {
+    /**
+     * 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 entityKey = 'BaseEntity';
+    /** Shape definition of this entity's parameters. */
+    static paramsShape;
+    static assets;
+    /**
+     * Defines which properties from {@link BaseEntity2d.params} will be mapped to hitbox and/or view
+     * properties.
+     */
+    static paramsMap;
+    /**
+     * A mapping from params properties to hitbox or view properties, making it easy to map params
+     * values.
+     */
+    static reverseParamsMap;
+    /** Parses the serialized params generated by {@link BaseEntity2d.serialize}. */
+    static deserialize(serialized) {
+        const deserialized = serialized ? JSON.parse(serialized) : undefined;
+        if (this.paramsShape) {
+            assertValidShape(deserialized, this.paramsShape);
+        }
+        else {
+            assert.isUndefined(deserialized);
+        }
+        return deserialized;
+    }
+    /**
+     * Dispatch an event. This will be dispatched through this entity's entity store (so listen for
+     * the event on the store).
+     */
+    dispatch(event) {
+        /** Cast to optionally undefined to account for destruction. */
+        this.entityStore?.listenTarget.dispatch(event);
+    }
+    /** If true, this entity should no longer be used or operated upon. */
+    isDestroyed = false;
+    abortController = new AbortController();
+    /** An `AbortSignal` that triggers when the entity is destroyed. */
+    abortSignal = this.abortController.signal;
+    hitbox;
+    /** The entity store to add all entities to. */
+    entityStore;
+    /** Writable entity params. These should be serializable. */
+    params;
+    /** Original pixi app. */
+    pixi;
+    /** Collision detection system. */
+    hitboxSystem;
+    getAsset;
+    constructor(args) {
+        this.entityStore = args.entityStore;
+        this.params = args.params;
+        this.pixi = args.pixi;
+        this.hitboxSystem = args.hitboxSystem;
+        this.state = args.state;
+        const assets = this.constructor.assets;
+        this.getAsset = createEntityAssetAccessor({
+            assetLoader: args.entityStore.assetLoader,
+            entityAssets: assets,
+        });
+    }
+    /** Called after construction to perform async initialization (e.g. creating views). */
+    initInstance() {
+        return;
+    }
+    /** The game's current state. */
+    state;
+    /** Add a new entity to the entity store. */
+    async addEntity(entityClass, ...params) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot add entity through destroyed entity.');
+        }
+        return await this.entityStore.addEntity(entityClass, ...params);
+    }
+    /** Marks the entity for destruction in the next entity store update. */
+    destroy() {
+        this.abortController.abort();
+        makeWritable(this).isDestroyed = true;
+    }
+    /**
+     * Immediately destroy the current entity, stop its updates.
+     *
+     * This is probably not what you want to use! See {@link BaseEntity2d.destroy} instead.
+     */
+    immediatelyDestroy() {
+        this.abortController.abort();
+        makeWritable(this).isDestroyed = true;
+        this.entityStore?.removeEntity(this);
+        this.dispatch(new EntityDestroyEvent({
+            entityInstance: this,
+        }));
+        delete this.entityStore;
+        delete this.hitboxSystem;
+        delete this.params;
+    }
+    /**
+     * 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.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    collide(otherEntity, collision) { }
+    /**
+     * 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() {
+        return this.params ? JSON.stringify(this.params) : undefined;
+    }
+}
+function createEntityAssetAccessor({ assetLoader, entityAssets, }) {
+    if (!entityAssets || check.isEmpty(entityAssets)) {
+        return {};
+    }
+    return mapObjectValues(entityAssets, (key, asset) => {
+        return async () => {
+            return assetLoader.loadIndividualAsset({
+                asset,
+            });
+        };
+    });
+}
+/**
+ * Base view entity class, types, and functionality.
+ *
+ * @category Internal
+ */
+export class ViewEntity2d extends BaseEntity2d {
+    /** The entity's PixiJS view. */
+    view;
+    /** Creates the view and hitbox, adds the view to the stage, and sets up the params proxy. */
+    async initInstance() {
+        const { view, hitbox } = await this.createView();
+        if (view) {
+            this.view = view;
+            this.pixi.stage.addChild(this.view);
+        }
+        else {
+            this.view = new ParticleContainer();
+            this.view.visible = false;
+        }
+        if (hitbox) {
+            this.hitbox = hitbox;
+            this.hitbox.userData = this;
+            this.hitboxSystem.insert(this.hitbox);
+        }
+        this.wrapParamsInProxy();
+    }
+    constructor(args) {
+        super(args);
+    }
+    wrapParamsInProxy() {
+        const paramsMap = this.constructor.paramsMap;
+        const reverseParamsMap = this.constructor.reverseParamsMap;
+        const params = this.params;
+        if (!params || !paramsMap || !reverseParamsMap) {
+            return;
+        }
+        makeWritable(this).params = new Proxy(params, {
+            set: (target, propertyKey, value, receiver) => {
+                if (propertyKey in params && check.hasKey(reverseParamsMap, propertyKey)) {
+                    const mappings = reverseParamsMap[propertyKey];
+                    if (this.hitbox && mappings?.hitbox) {
+                        mappings.hitbox.forEach((mapToKey) => {
+                            this.hitbox[mapToKey] = value;
+                        });
+                    }
+                    if (mappings?.view) {
+                        mappings.view.forEach((mapToKey) => {
+                            this.view[mapToKey] = value;
+                        });
+                    }
+                }
+                return Reflect.set(target, propertyKey, value, receiver);
+            },
+        });
+        /** Propagate initial params. */
+        getObjectTypedEntries(this.params).forEach(([key, value,]) => {
+            this.params[key] = value;
+        });
+    }
+    /** Detects if the current entity is still within the bounds of the render canvas. */
+    isInBounds(options = {}) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot check bounds on destroyed entity.');
+        }
+        else if (options.entirely) {
+            return this.pixi.screen.containsRect(this.view.getBounds().rectangle);
+        }
+        else {
+            return this.pixi.screen.intersects(this.view.getBounds().rectangle);
+        }
+    }
+    /**
+     * 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() {
+        this.view?.destroy({
+            children: true,
+        });
+        if (this.hitbox) {
+            this.hitboxSystem.remove(this.hitbox);
+        }
+        super.immediatelyDestroy();
+        delete this.view;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './antha-entity.mod.js';
+export * from './entity-suite.js';
+export * from './entity.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './antha-entity.mod.js';
+export * from './entity-suite.js';
+export * from './entity.js';

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "@antha/entity-2d",
+    "version": "0.0.1",
+    "description": "An Antha mod for handling 2D entities.",
+    "keywords": [
+        "vir",
+        "antha",
+        "render",
+        "entity",
+        "2d"
+    ],
+    "homepage": "https://github.com/electrovir/antha",
+    "bugs": {
+        "url": "https://github.com/electrovir/antha/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/antha.git"
+    },
+    "license": "(MIT OR CC0-1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "test": "virmator test web",
+        "test:coverage": "npm test coverage",
+        "test:docs": "virmator docs check"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^31.73.1",
+        "@augment-vir/common": "^31.73.1",
+        "type-fest": "^5.7.0"
+    },
+    "devDependencies": {
+        "@antha/engine": "*",
+        "@augment-vir/test": "^31.73.1",
+        "@web/dev-server-esbuild": "^1.0.5",
+        "@web/test-runner": "^0.20.2",
+        "@web/test-runner-playwright": "^0.11.1",
+        "detect-collisions": "^10.10.2025",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "object-shape-tester": "^6.14.0",
+        "pixi.js": "^8.19.0",
+        "typed-event-target": "^4.3.1",
+        "web-test-runner-plugin-pixi": "^0.0.2"
+    },
+    "peerDependencies": {
+        "@antha/asset": "*",
+        "@antha/engine": "*",
+        "@antha/graphics-2d": "*",
+        "detect-collisions": ">=10",
+        "element-vir": ">=26",
+        "object-shape-tester": ">=6",
+        "pixi.js": ">=8",
+        "typed-event-target": ">=4.3"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}