@vworlds/vecs 1.0.45 → 1.0.46

package/dist/world/world.entities.js

@@ -36,7 +36,14 @@ export class Entities extends Deferred {
         }
         return e;
     }
-    /** Look up an entity by component ref or identity name. */
+    /**
+     * Look up an entity by component ref or identity name.
+     *
+     * A foreign `Entity` (one whose `world` is not this world) throws: passing an
+     * entity from another world is a programming error, not a miss. An `Entity`
+     * whose world matches but whose eid is unknown (e.g. after destruction)
+     * returns `undefined`.
+     */
     getEntity(ref) {
         if (typeof ref === "string") {
             return this._identityNameIndex.get(ref);
@@ -51,7 +58,14 @@ export class Entities extends Deferred {
             const entity = this._entities.get(ref);
             return entity ?? (this.deferred ? this._deferredEntities.get(ref) : undefined);
         }
-        return ref.world === this && this._entities.get(ref.eid) === ref ? ref : undefined;
+        if (ref.world !== this) {
+            throw new Error("Entity belongs to a different World");
+        }
+        return this._entities.get(ref.eid) === ref
+            ? ref
+            : this.deferred
+                ? this._deferredEntities.get(ref.eid)
+                : undefined;
     }
     entity(ref) {
         if (ref === undefined) {

package/dist/world/world.entities.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.entities.js","sourceRoot":"","sources":["../../src/world/world.entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"world.entities.js","sourceRoot":"","sources":["../../src/world/world.entities.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAA8B,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpC;;;;;;;OAOG;IACI,iBAAiB,CAAc,GAAQ,EAAE,gBAAsC;QACpF,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxB,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC1B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,qEAAqE;gBACrE,wEAAwE;gBACxE,wEAAwE;gBACxE,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACnC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,kCAA0B,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC;YAC3F,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC3B,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;gBAC7B,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACI,SAAS,CAAc,GAA0B;QACtD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC;YACnD,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACvC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG;YACxC,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,IAAI,CAAC,QAAQ;gBACb,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;gBACrC,CAAC,CAAC,SAAS,CAAC;IAClB,CAAC;IAYM,MAAM,CAAc,GAA2B;QACpD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YACpC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,sDAAsD,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,2DAA2D;IACpD,gBAAgB;QACrB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;gBAClC,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC7C,IAAI,aAAa,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtD,SAAS;gBACX,CAAC;gBACD,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACvB,SAAS,EAAE,CAAC;YACd,CAAC;YACD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED,kEAAkE;IACxD,OAAO,CAAgC,WAA2B;QAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,kCAA0B,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}

package/dist/world/world.js

@@ -4,6 +4,7 @@ import { ImplementsModule } from "../modules/implements.js";
 import { PipelineModule } from "../modules/pipeline.js";
 import { RelationshipsModule } from "../modules/relationships.js";
 import { SingletonModule } from "../modules/singleton.js";
+import { SnapshotModule } from "../modules/snapshot.js";
 import { Query } from "../query/index.js";
 import { System } from "../system.js";
 import { Pipeline } from "./world.pipeline.js";
@@ -27,18 +28,29 @@ import { Pipeline } from "./world.pipeline.js";
  * deferred scope; user code can wrap arbitrary blocks with
  * {@link beginDefer} / {@link endDefer} or {@link defer}. {@link flush}
  * drains the queue at top level.
+ *
+ * ## Cross-world transfer
+ *
+ * {@link snapshotSubtree}, {@link restoreSubtree}, and {@link moveSubtree}
+ * capture and recreate an entity forest in a second world. They reject calls
+ * while either world is deferred, because cross-world scheduling is the
+ * application's job.
  */
 export class World extends Pipeline {
     constructor(options = {}) {
         super(options);
-        this.component(SilenceSource).onRemove((entity) => entity.get(Query)?._clearSilence());
-        this.component(Query).onRemove((_entity, query) => query.destroy());
-        this.component(System).onRemove((_entity, system) => system.destroy());
+        this.component(SilenceSource).on("remove", (entity) => entity.get(Query)?._clearSilence());
+        this.component(Query).on("remove", (_entity, query) => query.destroy());
+        this.component(System).on("remove", (_entity, system) => system.destroy());
         [
             IdentityModule,
             ImplementsModule,
             SingletonModule,
             RelationshipsModule,
+            // Registration order is not load-bearing: a capture binds the materializer
+            // its policy resolved to, so `SnapshotModule` may install or change a
+            // policy after entities already carry the component.
+            SnapshotModule,
             PipelineModule,
         ].forEach((mod) => this.module(mod));
     }

package/dist/world/world.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/world/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE;YACE,cAAc;YACd,gBAAgB;YAChB,eAAe;YACf,mBAAmB;YACnB,cAAc;SACf,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/world/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3E;YACE,cAAc;YACd,gBAAgB;YAChB,eAAe;YACf,mBAAmB;YACnB,2EAA2E;YAC3E,sEAAsE;YACtE,qDAAqD;YACrD,cAAc;YACd,cAAc;SACf,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/world/world.pipeline.d.ts

@@ -2,8 +2,8 @@ import { type QuerySpec } from "../dsl.js";
 import { Query } from "../query/index.js";
 import { System } from "../system.js";
 import type { WorldOptions } from "./world.base.js";
-import { Modules } from "./world.modules.js";
-export declare class Pipeline extends Modules {
+import { Transfers } from "./world.transfers.js";
+export declare class Pipeline extends Transfers {
     constructor(options?: WorldOptions);
     /** Open a new frame and evaluate every registered tick source once. */
     beginFrame(delta: number): void;

package/dist/world/world.pipeline.js

@@ -1,11 +1,13 @@
 import { System } from "../system.js";
 import { ALWAYS_TICK_SOURCE } from "../timer.js";
-import { Modules } from "./world.modules.js";
-export class Pipeline extends Modules {
+import { Transfers } from "./world.transfers.js";
+export class Pipeline extends Transfers {
     constructor(options = {}) {
         super(options);
         /** @internal Flat system execution pipeline, rebuilt from `_pipelineQuery`. */
         this._pipeline = [];
+        /** @internal Query whose ordered result defines the system pipeline. */
+        this._pipelineQuery = undefined;
         /** @internal World-owned tick sources evaluated once per frame. */
         this._tickSources = new Set();
         /** @internal Monotonic frame id used to memoize tick-source evaluation. */

package/dist/world/world.pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.pipeline.js","sourceRoot":"","sources":["../../src/world/world.pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"world.pipeline.js","sourceRoot":"","sources":["../../src/world/world.pipeline.ts"],"names":[],"mappings":"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"}

package/dist/world/world.queries.d.ts

@@ -13,4 +13,11 @@ export declare class Queries extends Storage {
     query(this: World, name: string): Query;
     /** Return the shared materialized term for a reactive query DSL expression. */
     getTerm(this: World, q: QueryDSL): Term;
+    /**
+     * Index a built query under every component eid it watches. Only queries that
+     * watch updates join entity membership sets, so only those are indexed.
+     */
+    private _addUpdateWatcher;
+    /** Drop a query from the watcher index; the inverse of {@link _addUpdateWatcher}. */
+    private _removeUpdateWatcher;
 }

package/dist/world/world.queries.js

@@ -15,6 +15,22 @@ export class Queries extends Storage {
         this._termCache = new Map();
         /** @internal Component eid -> pinned component leaf term. */
         this._componentTerms = new ArrayMap();
+        /** @internal Pinned false term. */
+        this._emptyTerm = undefined;
+        /** @internal Pinned world term. */
+        this._worldTerm = undefined;
+        /**
+         * @internal Term membership events currently being delivered (see
+         * `Term._add` / `Term._delete`). While it is zero, every composite term agrees
+         * with its children's membership.
+         */
+        this._termEmitDepth = 0;
+        /**
+         * @internal Component eid -> built queries that watch it for updates. Read by
+         * `Entity._routeModified`; maintained by {@link _addQuery} and
+         * {@link _removeQuery}.
+         */
+        this._updateWatchers = [];
         /** @internal True while the world is driving one logical frame. */
         this._frameInProgress = false;
         /** @internal True while the world is auto-building pending queries. */
@@ -31,6 +47,7 @@ export class Queries extends Storage {
         }
         this._removeUnbuiltQuery(q);
         this._queries.push(q);
+        this._addUpdateWatcher(q);
     }
     /** @internal Track a newly-created query until it is explicitly or automatically built. */
     _addUnbuiltQuery(q) {
@@ -42,6 +59,7 @@ export class Queries extends Storage {
         const idx = this._queries.indexOf(q);
         if (idx !== -1) {
             this._queries.splice(idx, 1);
+            this._removeUpdateWatcher(q);
         }
         q._unsubscribeRootTerm();
         this._entities.forEach((e) => e._purgeQuery(q));
@@ -105,5 +123,39 @@ export class Queries extends Storage {
             this._buildingPendingQueries = false;
         }
     }
+    /**
+     * Index a built query under every component eid it watches. Only queries that
+     * watch updates join entity membership sets, so only those are indexed.
+     */
+    _addUpdateWatcher(q) {
+        if (!q._watchesUpdates()) {
+            return;
+        }
+        q._watchlistBitmask.forEach((ceid) => {
+            let watchers = this._updateWatchers[ceid];
+            if (watchers === undefined) {
+                watchers = { queries: [], synchronous: 0 };
+                this._updateWatchers[ceid] = watchers;
+            }
+            watchers.queries.push(q);
+            if (!q._queuesUpdates) {
+                watchers.synchronous++;
+            }
+        });
+    }
+    /** Drop a query from the watcher index; the inverse of {@link _addUpdateWatcher}. */
+    _removeUpdateWatcher(q) {
+        q._watchlistBitmask.forEach((ceid) => {
+            const watchers = this._updateWatchers[ceid];
+            const index = watchers?.queries.indexOf(q) ?? -1;
+            if (index === -1) {
+                return;
+            }
+            watchers.queries.splice(index, 1);
+            if (!q._queuesUpdates) {
+                watchers.synchronous--;
+            }
+        });
+    }
 }
 //# sourceMappingURL=world.queries.js.map

package/dist/world/world.queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.queries.js","sourceRoot":"","sources":["../../src/world/world.queries.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"world.queries.js","sourceRoot":"","sources":["../../src/world/world.queries.ts"],"names":[],"mappings":"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"}

package/dist/world/world.transfers.d.ts

@@ -0,0 +1,137 @@
+import { type EID, type Entity } from "../entity/index.js";
+import { type EntitySubtreeSnapshot, type MoveSubtreeResult, type RestoreSubtreeResult, type SubtreeSnapshotOptions } from "../snapshot/types.js";
+import { Modules } from "./world.modules.js";
+import { type World } from "./world.js";
+/**
+ * Thrown by {@link World.moveSubtree} when the destination restore fails after
+ * the source roots have already been destroyed.
+ *
+ * Everything the destination restore created is destroyed, the source snapshot
+ * is restored back into the source world, and the destination's original error
+ * becomes this error's `cause`. The rollback rebuilds equivalent state with
+ * freshly allocated ids, so callers that held `Entity` references across the
+ * failed move must rebind them — {@link restored} is the mapping that does it:
+ * old source id to the restored entity that replaced it.
+ *
+ * Inbound edges — edges pointing *into* the moved subtree from an entity outside
+ * it — are not part of the snapshot and are not carried by the rollback either.
+ * They belonged to the state left behind in the source world.
+ */
+export declare class MoveSubtreeError extends Error {
+    /** The destination failure that triggered the rollback. */
+    readonly cause: unknown;
+    /** Old source id to the entity that replaced it in the source world. */
+    readonly restored: ReadonlyMap<EID, Entity>;
+    /** Whether the rollback itself failed, leaving the source world incomplete. */
+    readonly rollbackFailed: boolean;
+    constructor(operation: string, cause: unknown, restored: ReadonlyMap<EID, Entity>, rollbackFailed: boolean);
+}
+export declare class Transfers extends Modules {
+    /**
+     * Capture one entity's subtree, or several roots as one atomic forest, into
+     * detached records.
+     *
+     * Nothing in the source world changes: the forest is walked and every selected
+     * component and edge is copied before this returns. Entity ids and
+     * relationship edges are world-local, so the result carries *data* — its
+     * component classes and payloads, plus internal edges keyed by snapshot key —
+     * and never a live instance.
+     *
+     * Per component type, capture follows the type's `OnSnapshot` declaration, set
+     * by the module that owns it: plain data clones its own enumerable fields
+     * (`ClonePublic`), `DontSnapshot` types are left behind, and
+     * `CustomSnapshot` types call the owner's `capture`. Relationship targets
+     * inside the forest are stored as snapshot keys; targets outside it follow
+     * the `externalTargets` policy.
+     *
+     * @param rootOrRoots - A single root entity, or an array of roots captured as
+     *   one forest.
+     * @param options - Traversal relationship, component and relationship
+     *   allowlists, and the external-target policy.
+     * @returns A snapshot bound to this world.
+     * @throws If the world is deferred, a root is destroyed or is a
+     *   component-definition entity, the traversal relationship is unregistered,
+     *   the forest contains a cycle or a repeated member, a selected type is
+     *   `DontSnapshot`, or an external target is found under the `"error"` policy.
+     *
+     * @example
+     * ```ts
+     * const snapshot = world.snapshotSubtree(ship, {
+     *   components: [Position, LinearVelocity, Hull],
+     *   relationships: [ChildOf, Carries],
+     *   externalTargets: "error",
+     * });
+     * ```
+     */
+    snapshotSubtree(this: World, rootOrRoots: Entity | readonly Entity[], options?: SubtreeSnapshotOptions): EntitySubtreeSnapshot;
+    /**
+     * Recreate a captured snapshot inside `destination` with fresh entity ids.
+     *
+     * Every destination component is built by the canonical materializer, so
+     * exclusivity, interface aliases, `add` hooks, and query entry fire exactly
+     * as they would for an ordinary `set`. Source instances are never attached:
+     * the snapshot holds data only.
+     *
+     * Edges are rebuilt through the public relationship API, in two passes — the
+     * traversal relationship first, then everything else — so
+     * hierarchy-sensitive policies see a complete tree. Internal targets are
+     * remapped onto the freshly allocated ids; targets left behind at capture time
+     * stay left behind.
+     *
+     * The source entities are untouched. Use {@link moveSubtree} to transfer
+     * ownership as well.
+     *
+     * @param destination - World that receives the snapshot.
+     * @param snapshot - A snapshot from {@link snapshotSubtree}.
+     * @returns The destination entities, keyed by snapshot key and by source
+     *   entity.
+     * @throws If either world is deferred, a captured class is unregistered or
+     *   excluded in `destination`, or materialization fails. A failure after
+     *   creation destroys everything the attempt created.
+     */
+    restoreSubtree(this: World, destination: World, snapshot: EntitySubtreeSnapshot): RestoreSubtreeResult;
+    /**
+     * Move one entity's subtree, or several roots as one atomic forest, into
+     * `destination`.
+     *
+     * Capture and preflight both complete before the source is touched, so a
+     * snapshot that cannot be restored — an unregistered class, an excluded type —
+     * leaves the source world exactly as it was. Only then are the source roots
+     * destroyed, and the snapshot is restored into `destination`.
+     *
+     * If the destination restore fails, everything that restore created is
+     * destroyed, the source snapshot is restored back into this world, and a
+     * {@link MoveSubtreeError} is thrown carrying the original error as its `cause`.
+     *
+     * The rollback rebuilds equivalent state with freshly allocated ids, so
+     * `Entity` references held before the move are stale afterwards. Rebind them
+     * through the thrown error's `restored` map, which is keyed by the old source
+     * id. An edge pointing *into* the subtree from an entity outside it is never
+     * carried — not by a successful move, and not by the rollback.
+     *
+     * Destroying a root applies its component `remove` hooks and its relationship
+     * cleanup policies, which can reach outside the captured forest. Select
+     * transferable data accordingly.
+     *
+     * @param rootOrRoots - A single root entity, or an array of roots moved as one
+     *   atomic forest.
+     * @param destination - World that receives the forest.
+     * @param options - Traversal relationship, component and relationship
+     *   allowlists, and the external-target policy.
+     * @returns The destination entities, keyed by snapshot key and by source
+     *   entity.
+     * @throws {@link MoveSubtreeError} If the destination restore fails after the
+     *   source was destroyed, with `restored` mapping old source ids to the
+     *   entities that replaced them. The source forest survives unchanged when
+     *   capture or preflight fails, in which case the original error is thrown.
+     *
+     * @example
+     * ```ts
+     * const result = world.moveSubtree([ship, ...escorts], nextSectorWorld, {
+     *   components: [Position, LinearVelocity, Hull, Cargo],
+     *   relationships: [ChildOf, Carries, TetheredTo],
+     * });
+     * ```
+     */
+    moveSubtree(this: World, rootOrRoots: Entity | readonly Entity[], destination: World, options?: SubtreeSnapshotOptions): MoveSubtreeResult;
+}

package/dist/world/world.transfers.js

@@ -0,0 +1,188 @@
+// The `World` half of cross-world subtree transfer: `snapshotSubtree`,
+// `restoreSubtree`, and `moveSubtree`. The capture, preflight, and restore
+// mechanics live in `../snapshot/`.
+import { _captureSubtree, _preflightRestore, _restoreSubtree } from "../snapshot/index.js";
+import { Modules } from "./world.modules.js";
+/**
+ * Thrown by {@link World.moveSubtree} when the destination restore fails after
+ * the source roots have already been destroyed.
+ *
+ * Everything the destination restore created is destroyed, the source snapshot
+ * is restored back into the source world, and the destination's original error
+ * becomes this error's `cause`. The rollback rebuilds equivalent state with
+ * freshly allocated ids, so callers that held `Entity` references across the
+ * failed move must rebind them — {@link restored} is the mapping that does it:
+ * old source id to the restored entity that replaced it.
+ *
+ * Inbound edges — edges pointing *into* the moved subtree from an entity outside
+ * it — are not part of the snapshot and are not carried by the rollback either.
+ * They belonged to the state left behind in the source world.
+ */
+export class MoveSubtreeError extends Error {
+    constructor(operation, cause, restored, rollbackFailed) {
+        super(`${operation} failed and the source forest was restored with new entity ids` +
+            (rollbackFailed ? "; the rollback itself did not complete" : ""));
+        this.name = "MoveSubtreeError";
+        this.cause = cause;
+        this.restored = restored;
+        this.rollbackFailed = rollbackFailed;
+    }
+}
+export class Transfers extends Modules {
+    /**
+     * Capture one entity's subtree, or several roots as one atomic forest, into
+     * detached records.
+     *
+     * Nothing in the source world changes: the forest is walked and every selected
+     * component and edge is copied before this returns. Entity ids and
+     * relationship edges are world-local, so the result carries *data* — its
+     * component classes and payloads, plus internal edges keyed by snapshot key —
+     * and never a live instance.
+     *
+     * Per component type, capture follows the type's `OnSnapshot` declaration, set
+     * by the module that owns it: plain data clones its own enumerable fields
+     * (`ClonePublic`), `DontSnapshot` types are left behind, and
+     * `CustomSnapshot` types call the owner's `capture`. Relationship targets
+     * inside the forest are stored as snapshot keys; targets outside it follow
+     * the `externalTargets` policy.
+     *
+     * @param rootOrRoots - A single root entity, or an array of roots captured as
+     *   one forest.
+     * @param options - Traversal relationship, component and relationship
+     *   allowlists, and the external-target policy.
+     * @returns A snapshot bound to this world.
+     * @throws If the world is deferred, a root is destroyed or is a
+     *   component-definition entity, the traversal relationship is unregistered,
+     *   the forest contains a cycle or a repeated member, a selected type is
+     *   `DontSnapshot`, or an external target is found under the `"error"` policy.
+     *
+     * @example
+     * ```ts
+     * const snapshot = world.snapshotSubtree(ship, {
+     *   components: [Position, LinearVelocity, Hull],
+     *   relationships: [ChildOf, Carries],
+     *   externalTargets: "error",
+     * });
+     * ```
+     */
+    snapshotSubtree(rootOrRoots, options = {}) {
+        this._assertNotDeferred("snapshotSubtree");
+        return _captureSubtree(this, rootOrRoots, options);
+    }
+    /**
+     * Recreate a captured snapshot inside `destination` with fresh entity ids.
+     *
+     * Every destination component is built by the canonical materializer, so
+     * exclusivity, interface aliases, `add` hooks, and query entry fire exactly
+     * as they would for an ordinary `set`. Source instances are never attached:
+     * the snapshot holds data only.
+     *
+     * Edges are rebuilt through the public relationship API, in two passes — the
+     * traversal relationship first, then everything else — so
+     * hierarchy-sensitive policies see a complete tree. Internal targets are
+     * remapped onto the freshly allocated ids; targets left behind at capture time
+     * stay left behind.
+     *
+     * The source entities are untouched. Use {@link moveSubtree} to transfer
+     * ownership as well.
+     *
+     * @param destination - World that receives the snapshot.
+     * @param snapshot - A snapshot from {@link snapshotSubtree}.
+     * @returns The destination entities, keyed by snapshot key and by source
+     *   entity.
+     * @throws If either world is deferred, a captured class is unregistered or
+     *   excluded in `destination`, or materialization fails. A failure after
+     *   creation destroys everything the attempt created.
+     */
+    restoreSubtree(destination, snapshot) {
+        this._assertNotDeferred("restoreSubtree");
+        destination._assertNotDeferred("restoreSubtree");
+        return _restoreSubtree(destination, snapshot);
+    }
+    /**
+     * Move one entity's subtree, or several roots as one atomic forest, into
+     * `destination`.
+     *
+     * Capture and preflight both complete before the source is touched, so a
+     * snapshot that cannot be restored — an unregistered class, an excluded type —
+     * leaves the source world exactly as it was. Only then are the source roots
+     * destroyed, and the snapshot is restored into `destination`.
+     *
+     * If the destination restore fails, everything that restore created is
+     * destroyed, the source snapshot is restored back into this world, and a
+     * {@link MoveSubtreeError} is thrown carrying the original error as its `cause`.
+     *
+     * The rollback rebuilds equivalent state with freshly allocated ids, so
+     * `Entity` references held before the move are stale afterwards. Rebind them
+     * through the thrown error's `restored` map, which is keyed by the old source
+     * id. An edge pointing *into* the subtree from an entity outside it is never
+     * carried — not by a successful move, and not by the rollback.
+     *
+     * Destroying a root applies its component `remove` hooks and its relationship
+     * cleanup policies, which can reach outside the captured forest. Select
+     * transferable data accordingly.
+     *
+     * @param rootOrRoots - A single root entity, or an array of roots moved as one
+     *   atomic forest.
+     * @param destination - World that receives the forest.
+     * @param options - Traversal relationship, component and relationship
+     *   allowlists, and the external-target policy.
+     * @returns The destination entities, keyed by snapshot key and by source
+     *   entity.
+     * @throws {@link MoveSubtreeError} If the destination restore fails after the
+     *   source was destroyed, with `restored` mapping old source ids to the
+     *   entities that replaced them. The source forest survives unchanged when
+     *   capture or preflight fails, in which case the original error is thrown.
+     *
+     * @example
+     * ```ts
+     * const result = world.moveSubtree([ship, ...escorts], nextSectorWorld, {
+     *   components: [Position, LinearVelocity, Hull, Cargo],
+     *   relationships: [ChildOf, Carries, TetheredTo],
+     * });
+     * ```
+     */
+    moveSubtree(rootOrRoots, destination, options = {}) {
+        this._assertNotDeferred("moveSubtree");
+        if (destination === this) {
+            throw new Error("moveSubtree requires a destination world other than the source");
+        }
+        destination._assertNotDeferred("moveSubtree");
+        const snapshot = _captureSubtree(this, rootOrRoots, options);
+        _preflightRestore(destination, snapshot);
+        for (const record of snapshot.entities) {
+            if (!record.source.destroyed) {
+                record.source.destroy();
+            }
+        }
+        try {
+            return _restoreSubtree(destination, snapshot);
+        }
+        catch (error) {
+            const [cause, restored, rollbackFailed] = this._rollback(error, snapshot);
+            throw new MoveSubtreeError("moveSubtree", cause, restored, rollbackFailed);
+        }
+    }
+    /** @internal Reject cross-world scheduling while a world is queueing mutations. */
+    _assertNotDeferred(operation) {
+        if (this.deferred) {
+            throw new Error(`${operation} cannot run while the world is deferred; cross-world scheduling is the application's job`);
+        }
+    }
+    /**
+     * @internal Best-effort restore of the source forest after a failed transfer.
+     *
+     * A failed rollback is a consequence of the destination failure, not an
+     * independent problem, so it must not mask the original error; it is reported
+     * as a flag on the {@link MoveSubtreeError} instead.
+     */
+    _rollback(cause, snapshot) {
+        try {
+            return [cause, _restoreSubtree(this, snapshot).entities, false];
+        }
+        catch {
+            return [cause, new Map(), true];
+        }
+    }
+}
+//# sourceMappingURL=world.transfers.js.map

package/dist/world/world.transfers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.transfers.js","sourceRoot":"","sources":["../../src/world/world.transfers.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -17,11 +17,15 @@ Read in this order the first time through:
    - [Components](./components.md) — registration, hooks, traits, exclusivity, cleanup policies,
      interfaces, singletons.
    - [Entities](./entities.md) — creation, lookup, the component API, relationship targets, lifecycle.
-   - [Systems](./systems.md) — membership, reactive callbacks, callback options, `each`/`run`, cadence, injection.
+   - [Systems](./systems.md) — membership, reactive callbacks, callback options, `each`/`run`, cadence,
+     component and relationship injection.
    - [Queries and filters](./queries-and-filters.md) — the query DSL, live queries, one-shot
      filters, grouped queries, `Bitset`.
-   - [Relationships](./relationships.md) — links, target creation and ownership, hierarchy, cleanup cascades.
+   - [Relationships](./relationships.md) — links, target creation and projection, ownership, hierarchy,
+     cleanup cascades.
    - [Modules](./modules.md) — packaging features, composition, the built-in modules.
+   - [Subtree snapshots](./snapshots.md) — capturing, restoring, and moving an entity forest
+     between two worlds.
 5. [Design guide](./design-guide.md) — opinionated patterns and anti-patterns distilled from real
    designs. Read it once you know the machinery.
 6. [Utilities](./utilities.md) — helper classes exported by `@vworlds/vecs` but not part of the ECS
@@ -38,13 +42,21 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 | [execution-model.md](./execution-model.md)         | `world.progress`, the 8 built-in phases, deferred commands, flush boundaries, event routing. |
 | [components.md](./components.md)                   | Component registration, hooks, traits, exclusivity, cleanup, aliases, and singletons.        |
 | [entities.md](./entities.md)                       | Entity creation, component mutation, relationship targets, lifecycle, deferred reads.        |
-| [systems.md](./systems.md)                         | `world.system`, `with`/`without`, `enter`/`update`/`exit`, callback options, tick sources.   |
+| [systems.md](./systems.md)                         | `world.system`, callbacks, injection, ordering, cadence, and tick sources.                   |
 | [queries-and-filters.md](./queries-and-filters.md) | `QueryDSL`, `Query`, `Filter`, `groupBy`, `ignoreSource`.                                    |
-| [relationships.md](./relationships.md)             | Relationships, target creation and ownership, hierarchy, traversal, and cleanup cascades.    |
+| [relationships.md](./relationships.md)             | Relationships, target creation, projection and ownership, hierarchy, traversal, and cleanup. |
 | [modules.md](./modules.md)                         | `Module<Config>`, `world.module`, composition, built-in modules.                             |
+| [snapshots.md](./snapshots.md)                     | `snapshotSubtree`, `restoreSubtree`, `moveSubtree`, and `OnSnapshot` capture policies.       |
 | [design-guide.md](./design-guide.md)               | Patterns, anti-patterns, and a Phaser render-layer case study.                               |
 | [utilities.md](./utilities.md)                     | Public helper classes: `Events`, `ArrayMap`, `IterableArrayMap`, plus `Bitset` cross-ref.    |
 | [glossary.md](./glossary.md)                       | ECS and vecs terminology.                                                                    |
 
-Networking (wire encoding with `@wireType`, protocol component ordering, replication) lives in the
-`@vworlds/vecs-wire` and `@vworlds/vecs-protocol` packages and is only cross-referenced here.
+Networking (wire encoding with `@wireType`, protocol component ordering, replication, RPCs, server
+sessions, and the client world) lives in the `@vworlds/vecs-wire`, `@vworlds/vecs-protocol`,
+`@vworlds/vecs-server`, and `@vworlds/vecs-client` packages:
+
+- [Remote procedure calls](../../vecs-protocol/docs/rpc.md) — the call channel and typed errors.
+- [Sessions and caller context](../../vecs-server/docs/sessions.md) — per-connection RPC context,
+  `closeSession`, and exactly-once teardown.
+- [Client world](../../vecs-client/docs/client-world.md) — replication, `invoke`/`listen`, and
+  disposal.