@antha/entity-2d 0.19.0 → 0.21.0

package/dist/entity.d.ts

@@ -182,6 +182,25 @@ export declare class EntityStore2d<State extends AnyObject = any> {
      * and then deserializing and passing the given `serializedParams` to that constructor.
      */
     deserializeEntity(entityKey: string, serializedParams: string | undefined): Promise<BaseEntity2d>;
+    /**
+     * Serializes every current entity, in update order, for {@link EntityStore2d.loadSnapshot}.
+     * Entities that are marked destroyed but not yet removed are skipped.
+     */
+    createSnapshot(): SerializedEntity2d[];
+    /**
+     * Hashes {@link EntityStore2d.createSnapshot} with `hashObject` from `@antha/util`, so it covers
+     * exactly what {@link BaseEntity2d.serialize} covers. Compare this across lock-step peers to
+     * detect desyncs.
+     */
+    hashEntities(): number;
+    /**
+     * Immediately destroys every current entity and recreates the entities from a snapshot made by
+     * {@link EntityStore2d.createSnapshot}, in the same order. Only entity params are restored: any
+     * state an entity keeps outside of its params is lost, so lock-step peers must all load the
+     * snapshot on the same frame to stay in sync. Every entity class in the snapshot must be
+     * registered in this store (see `preregisteredEntities`).
+     */
+    loadSnapshot(snapshot: ReadonlyArray<Readonly<SerializedEntity2d>>): Promise<BaseEntity2d<any, any, any>[]>;
     /** 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>>;
     /** Immediately destroys every current entity while leaving the entity store usable. */
@@ -189,6 +208,21 @@ export declare class EntityStore2d<State extends AnyObject = any> {
     /** Destroys the entity store and all entities contained inside it. */
     destroy(): void;
 }
+/**
+ * Shape definition for {@link SerializedEntity2d}.
+ *
+ * @category Internal
+ */
+export declare const serializedEntity2dShape: Shape<{
+    entityKey: string;
+    serializedParams: Shape<import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUndefined, import("@sinclair/typebox").TString]>>>;
+}>;
+/**
+ * One entity in a snapshot from {@link EntityStore2d.createSnapshot}.
+ *
+ * @category Internal
+ */
+export type SerializedEntity2d = typeof serializedEntity2dShape.runtimeType;
 /**
  * Shape definition for {@link EntityPositionParams}.
  *

package/dist/entity.js

@@ -1,7 +1,8 @@
+import { hashObject } from '@antha/util';
 import { assert, check } from '@augment-vir/assert';
-import { ConstructorInstanceMap, getObjectTypedEntries, getOrSet, makeWritable, mapObjectValues, } from '@augment-vir/common';
+import { awaitedBlockingMap, ConstructorInstanceMap, getObjectTypedEntries, getOrSet, makeWritable, mapObjectValues, } from '@augment-vir/common';
 import { System as HitboxSystem, Response, } from 'detect-collisions';
-import { assertValidShape, defineShape } from 'object-shape-tester';
+import { assertValidShape, defineShape, optionalShape } from 'object-shape-tester';
 import { ParticleContainer } from 'pixi.js';
 import { defineTypedCustomEvent, GenericListenTarget } from 'typed-event-target';
 export { System as HitboxSystem } from 'detect-collisions';
@@ -272,6 +273,48 @@ export class EntityStore2d {
         }
         return await this.addEntity(entityConstructor, entityConstructor.deserialize(serializedParams));
     }
+    /**
+     * Serializes every current entity, in update order, for {@link EntityStore2d.loadSnapshot}.
+     * Entities that are marked destroyed but not yet removed are skipped.
+     */
+    createSnapshot() {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on a destroyed entity store.');
+        }
+        return [...this.currentEntityInstances]
+            .filter((entity) => !entity.isDestroyed)
+            .map((entity) => {
+            return {
+                entityKey: entity.entityDefinition.entityKey,
+                serializedParams: entity.serialize(),
+            };
+        });
+    }
+    /**
+     * Hashes {@link EntityStore2d.createSnapshot} with `hashObject` from `@antha/util`, so it covers
+     * exactly what {@link BaseEntity2d.serialize} covers. Compare this across lock-step peers to
+     * detect desyncs.
+     */
+    hashEntities() {
+        return hashObject(this.createSnapshot());
+    }
+    /**
+     * Immediately destroys every current entity and recreates the entities from a snapshot made by
+     * {@link EntityStore2d.createSnapshot}, in the same order. Only entity params are restored: any
+     * state an entity keeps outside of its params is lost, so lock-step peers must all load the
+     * snapshot on the same frame to stay in sync. Every entity class in the snapshot must be
+     * registered in this store (see `preregisteredEntities`).
+     */
+    async loadSnapshot(snapshot) {
+        this.destroyAllEntities();
+        /**
+         * `addEntity` inserts each entity only after its async init finishes, so creating them in
+         * parallel could order the store differently on each peer.
+         */
+        return await awaitedBlockingMap(snapshot, async (serializedEntity) => {
+            return await this.deserializeEntity(serializedEntity.entityKey, serializedEntity.serializedParams);
+        });
+    }
     /** Create a new instance of the given entity class and add it to this entity store. */
     async addEntity(entityClass, ...params) {
         if (this.isDestroyed) {
@@ -314,6 +357,17 @@ export class EntityStore2d {
         delete this.listenTarget;
     }
 }
+/**
+ * Shape definition for {@link SerializedEntity2d}.
+ *
+ * @category Internal
+ */
+export const serializedEntity2dShape = defineShape({
+    entityKey: '',
+    serializedParams: optionalShape('', {
+        alsoUndefined: true,
+    }),
+});
 /**
  * Shape definition for {@link EntityPositionParams}.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/entity-2d",
-    "version": "0.19.0",
+    "version": "0.21.0",
     "description": "An Antha mod for handling 2D entities.",
     "keywords": [
         "vir",
@@ -39,11 +39,12 @@
         "@augment-vir/common": "^32.3.0"
     },
     "devDependencies": {
-        "@antha/asset": "^0.19.0",
-        "@antha/audio": "^0.19.0",
-        "@antha/engine": "^0.19.0",
-        "@antha/graphics-2d": "^0.19.0",
-        "@antha/web-test-runner-plugin-pixi": "^0.19.0",
+        "@antha/asset": "^0.21.0",
+        "@antha/audio": "^0.21.0",
+        "@antha/engine": "^0.21.0",
+        "@antha/graphics-2d": "^0.21.0",
+        "@antha/util": "^0.21.0",
+        "@antha/web-test-runner-plugin-pixi": "^0.21.0",
         "@augment-vir/test": "^32.3.0",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
@@ -55,10 +56,11 @@
         "typed-event-target": "^4.3.3"
     },
     "peerDependencies": {
-        "@antha/asset": "^0.19.0",
-        "@antha/audio": "^0.19.0",
-        "@antha/engine": "^0.19.0",
-        "@antha/graphics-2d": "^0.19.0",
+        "@antha/asset": "^0.21.0",
+        "@antha/audio": "^0.21.0",
+        "@antha/engine": "^0.21.0",
+        "@antha/graphics-2d": "^0.21.0",
+        "@antha/util": "^0.21.0",
         "detect-collisions": "^10",
         "element-vir": "^27",
         "object-shape-tester": "^6",