archetype-ecs-lib 0.6.0 → 1.0.0

package/lib/ecs/World.js

@@ -100,8 +100,15 @@ var World = /** @class */ (function (_super) {
         _this.resources = new Map();
         _this.eventChannels = new Map();
         _this.snapshotStore = new WorldSnapshotStore_1.WorldSnapshotStore();
+        /**
+         * Query result cache: maps a sorted query signature key → matching archetypes.
+         * `checked` tracks how many archetypes were scanned when the entry was last updated.
+         * Because archetypes are append-only, new ones are scanned incrementally on next use.
+         */
+        _this._queryCache = new Map();
         /** @internal Phase -> systems mapping for Schedule */
         _this._scheduleSystems = new Map();
+        _this._destroyed = false;
         _this._resetArchetypes();
         return _this;
     }
@@ -235,9 +242,11 @@ var World = /** @class */ (function (_super) {
     };
     /** Queue structural changes to apply safely after systems run. */
     World.prototype.cmd = function () {
+        this._ensureNotDestroyed();
         return this.commands;
     };
     World.prototype.addSystem = function (fn) {
+        this._ensureNotDestroyed();
         this.systems.push(fn);
         return this;
     };
@@ -265,12 +274,14 @@ var World = /** @class */ (function (_super) {
      */
     World.prototype.update = function (dt) {
         var e_7, _a;
+        this._ensureNotDestroyed();
         // Runtime conflict detection
         if (this._scheduleSystems.size > 0) {
             this._warnAboutLifecycleConflict("World.update");
         }
         var frameStart = this._profBeginFrame(dt);
         this._iterateDepth++;
+        var caughtError;
         try {
             try {
                 for (var _b = __values(this.systems), _c = _b.next(); !_c.done; _c = _b.next()) {
@@ -294,17 +305,30 @@ var World = /** @class */ (function (_super) {
                 finally { if (e_7) throw e_7.error; }
             }
         }
+        catch (e) {
+            caughtError = e;
+        }
         finally {
             this._iterateDepth--;
-            this.flush();
+            try {
+                this.flush();
+            }
+            catch (e) {
+                // System error takes priority; flush error only surfaced when no system threw.
+                if (caughtError === undefined)
+                    caughtError = e;
+            }
             this.swapEvents();
             this._profAddPhase("update", this._profilingEnabled ? (performance.now() - frameStart) : 0);
             this._profEndFrame(frameStart);
         }
+        if (caughtError !== undefined)
+            throw caughtError;
         this.updateOverlay(this.stats(), this.statsHistory());
     };
     World.prototype.flush = function () {
         var e_8, _a;
+        this._ensureNotDestroyed();
         this._ensureNotIterating("flush");
         // Apply commands until the queue is empty. This allows spawn(init) to enqueue add/remove
         // operations that will be applied during the same flush.
@@ -327,39 +351,61 @@ var World = /** @class */ (function (_super) {
             }
         }
     };
+    World.prototype.destroy = function () {
+        if (this._destroyed)
+            throw new Error("World.destroy() called on an already-destroyed world.");
+        this._destroyed = true;
+        this.archetypes.length = 0;
+        this.archByKey.clear();
+        this._queryCache.clear();
+        this.systems.length = 0;
+        this._scheduleSystems.clear();
+        this.resources.clear();
+        this.eventChannels.clear();
+        this.entities.meta.length = 0;
+    };
     //#region ---------- Snapshot / Restore ----------
     World.prototype.registerComponentSnapshot = function (key, codec) {
+        this._ensureNotDestroyed();
         this.snapshotStore.registerComponentSnapshot(this._snapshotRuntime(), key, codec);
         return this;
     };
     World.prototype.unregisterComponentSnapshot = function (key) {
+        this._ensureNotDestroyed();
         return this.snapshotStore.unregisterComponentSnapshot(key);
     };
     World.prototype.registerResourceSnapshot = function (key, codec) {
+        this._ensureNotDestroyed();
         this.snapshotStore.registerResourceSnapshot(this._snapshotRuntime(), key, codec);
         return this;
     };
     World.prototype.unregisterResourceSnapshot = function (key) {
+        this._ensureNotDestroyed();
         return this.snapshotStore.unregisterResourceSnapshot(key);
     };
     World.prototype.snapshot = function () {
+        this._ensureNotDestroyed();
         return this.snapshotStore.snapshot(this._snapshotRuntime());
     };
     World.prototype.restore = function (snapshot) {
+        this._ensureNotDestroyed();
         this.snapshotStore.restore(this._snapshotRuntime(), snapshot);
         this.updateOverlay(this.stats(), this.statsHistory());
     };
     //#endregion
     //#region ---------- Resources (singletons) ----------
     World.prototype.setResource = function (key, value) {
+        this._ensureNotDestroyed();
         this.resources.set(key, value);
     };
     World.prototype.getResource = function (key) {
+        this._ensureNotDestroyed();
         if (!this.resources.has(key))
             return undefined;
         return this.resources.get(key);
     };
     World.prototype.requireResource = function (key) {
+        this._ensureNotDestroyed();
         if (!this.resources.has(key)) {
             var name_2 = this._formatCtor(key);
             throw new Error("requireResource(".concat(name_2, ") failed: resource missing. ") +
@@ -368,12 +414,15 @@ var World = /** @class */ (function (_super) {
         return this.resources.get(key);
     };
     World.prototype.hasResource = function (key) {
+        this._ensureNotDestroyed();
         return this.resources.has(key);
     };
     World.prototype.removeResource = function (key) {
+        this._ensureNotDestroyed();
         return this.resources.delete(key);
     };
     World.prototype.initResource = function (key, factory) {
+        this._ensureNotDestroyed();
         if (this.resources.has(key))
             return this.resources.get(key);
         var value = factory();
@@ -383,12 +432,15 @@ var World = /** @class */ (function (_super) {
     //#endregion
     //#region ---------- Events (phase-scoped) ----------
     World.prototype.emit = function (key, ev) {
+        this._ensureNotDestroyed();
         this._events(key).emit(ev);
     };
     World.prototype.events = function (key) {
+        this._ensureNotDestroyed();
         return this._events(key);
     };
     World.prototype.drainEvents = function (key, fn) {
+        this._ensureNotDestroyed();
         var ch = this.eventChannels.get(key);
         if (!ch)
             return;
@@ -396,6 +448,7 @@ var World = /** @class */ (function (_super) {
     };
     World.prototype.clearEvents = function (key) {
         var e_9, _a;
+        this._ensureNotDestroyed();
         if (key) {
             var ch = this.eventChannels.get(key);
             if (!ch)
@@ -421,6 +474,7 @@ var World = /** @class */ (function (_super) {
     /** @internal Called by Schedule at phase boundaries */
     World.prototype.swapEvents = function () {
         var e_10, _a;
+        this._ensureNotDestroyed();
         try {
             for (var _b = __values(this.eventChannels.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
                 var ch = _c.value;
@@ -438,6 +492,7 @@ var World = /** @class */ (function (_super) {
     //#endregion
     //#region ---------- Entity lifecycle ----------
     World.prototype.spawn = function () {
+        this._ensureNotDestroyed();
         this._ensureNotIterating("spawn");
         var entity = this.entities.create();
         // place in archetype 0
@@ -448,7 +503,7 @@ var World = /** @class */ (function (_super) {
         entityMeta.row = row;
         return entity;
     };
-    World.prototype.spawnMany = function () {
+    World.prototype.spawnWith = function () {
         var e_11, _a;
         var items = [];
         for (var _i = 0; _i < arguments.length; _i++) {
@@ -471,9 +526,11 @@ var World = /** @class */ (function (_super) {
         return e;
     };
     World.prototype.isAlive = function (e) {
+        this._ensureNotDestroyed();
         return this.entities.isAlive(e);
     };
     World.prototype.despawn = function (e) {
+        this._ensureNotDestroyed();
         this._assertAlive(e, 'despawn');
         this._ensureNotIterating("despawn");
         this._removeFromArchetype(e);
@@ -498,6 +555,7 @@ var World = /** @class */ (function (_super) {
     //#endregion
     //#region ---------- Components ----------
     World.prototype.has = function (e, ctor) {
+        this._ensureNotDestroyed();
         var meta = this.entities.meta[e.id];
         if (!meta || !meta.alive || meta.gen !== e.gen)
             return false;
@@ -505,6 +563,7 @@ var World = /** @class */ (function (_super) {
         return this.archetypes[meta.arch].has(tid);
     };
     World.prototype.get = function (e, ctor) {
+        this._ensureNotDestroyed();
         var meta = this.entities.meta[e.id];
         if (!meta || !meta.alive || meta.gen !== e.gen)
             return undefined;
@@ -515,6 +574,7 @@ var World = /** @class */ (function (_super) {
         return a.column(tid)[meta.row];
     };
     World.prototype.set = function (e, ctor, value) {
+        this._ensureNotDestroyed();
         var op = "set(".concat(this._formatCtor(ctor), ")");
         var meta = this._assertAlive(e, op);
         var tid = (0, TypeRegistry_1.typeId)(ctor);
@@ -524,6 +584,7 @@ var World = /** @class */ (function (_super) {
         a.column(tid)[meta.row] = value;
     };
     World.prototype.add = function (e, ctor, value) {
+        this._ensureNotDestroyed();
         var op = "add(".concat(this._formatCtor(ctor), ")");
         this._assertAlive(e, op);
         this._ensureNotIterating(op);
@@ -535,8 +596,11 @@ var World = /** @class */ (function (_super) {
             src.column(tid)[srcMeta.row] = value;
             return;
         }
-        var dstSig = (0, Signature_1.mergeSignature)(src.sig, tid);
-        var dst = this._getOrCreateArchetype(dstSig);
+        var dst = src.addEdges.get(tid);
+        if (!dst) {
+            dst = this._getOrCreateArchetype((0, Signature_1.mergeSignature)(src.sig, tid));
+            src.addEdges.set(tid, dst);
+        }
         this._moveEntity(e, src, srcMeta.row, dst, function (t) {
             if (t === tid)
                 return value;
@@ -551,6 +615,7 @@ var World = /** @class */ (function (_super) {
         }
         if (items.length === 0)
             return;
+        this._ensureNotDestroyed();
         this._assertAlive(e, "addMany");
         this._ensureNotIterating("addMany");
         var srcMeta = this.entities.meta[e.id];
@@ -610,6 +675,7 @@ var World = /** @class */ (function (_super) {
         });
     };
     World.prototype.remove = function (e, ctor) {
+        this._ensureNotDestroyed();
         var op = "remove(".concat(this._formatCtor(ctor), ")");
         this._assertAlive(e, op);
         this._ensureNotIterating(op);
@@ -618,8 +684,11 @@ var World = /** @class */ (function (_super) {
         var src = this.archetypes[srcMeta.arch];
         if (!src.has(tid))
             return;
-        var dstSig = (0, Signature_1.subtractSignature)(src.sig, tid);
-        var dst = this._getOrCreateArchetype(dstSig);
+        var dst = src.removeEdges.get(tid);
+        if (!dst) {
+            dst = this._getOrCreateArchetype((0, Signature_1.subtractSignature)(src.sig, tid));
+            src.removeEdges.set(tid, dst);
+        }
         this._moveEntity(e, src, srcMeta.row, dst, function (t) {
             // copy all but removed, but dstSig guarantees t != tid
             return src.column(t)[srcMeta.row];
@@ -633,6 +702,7 @@ var World = /** @class */ (function (_super) {
         }
         if (ctors.length === 0)
             return;
+        this._ensureNotDestroyed();
         this._assertAlive(e, "removeMany");
         this._ensureNotIterating("removeMany");
         var srcMeta = this.entities.meta[e.id];
@@ -668,102 +738,206 @@ var World = /** @class */ (function (_super) {
         });
     };
     World.prototype.query = function () {
-        var ctors = [];
+        var _a;
+        var args = [];
         for (var _i = 0; _i < arguments.length; _i++) {
-            ctors[_i] = arguments[_i];
+            args[_i] = arguments[_i];
         }
-        var _a = World._buildQueryTypeIds(ctors), requested = _a.requested, needSorted = _a.needSorted;
-        function gen(world) {
-            var _a, _b, a, cols, i, row, e, out, i, e_16_1;
-            var e_16, _c;
-            return __generator(this, function (_d) {
-                switch (_d.label) {
+        var _b = World._splitArgs(args), ctors = _b.ctors, filter = _b.filter;
+        var _c = World._buildQueryTypeIds(ctors, filter), requested = _c.requested, needSorted = _c.needSorted, withoutSorted = _c.withoutSorted;
+        function gen(world, archs) {
+            var archs_1, archs_1_1, a, cols, i, ents, len, _a, a0, r, a0, a1, r, a0, a1, a2, r, a0, a1, a2, a3, r, a0, a1, a2, a3, a4, r, a0, a1, a2, a3, a4, a5, r, r, out, i, e_16_1;
+            var e_16, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         world._iterateDepth++;
-                        _d.label = 1;
+                        _c.label = 1;
                     case 1:
-                        _d.trys.push([1, , 12, 13]);
-                        _d.label = 2;
+                        _c.trys.push([1, , 44, 45]);
+                        _c.label = 2;
                     case 2:
-                        _d.trys.push([2, 9, 10, 11]);
-                        _a = __values(world.archetypes), _b = _a.next();
-                        _d.label = 3;
+                        _c.trys.push([2, 41, 42, 43]);
+                        archs_1 = __values(archs), archs_1_1 = archs_1.next();
+                        _c.label = 3;
                     case 3:
-                        if (!!_b.done) return [3 /*break*/, 8];
-                        a = _b.value;
-                        if (!a)
-                            return [3 /*break*/, 7];
-                        if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
-                            return [3 /*break*/, 7];
+                        if (!!archs_1_1.done) return [3 /*break*/, 40];
+                        a = archs_1_1.value;
+                        if (withoutSorted.length > 0 && (0, Signature_1.signatureHasAny)(a.sig, withoutSorted))
+                            return [3 /*break*/, 39];
                         cols = new Array(requested.length);
                         for (i = 0; i < requested.length; i++)
                             cols[i] = a.column(requested[i]);
-                        row = 0;
-                        _d.label = 4;
+                        ents = a.entities;
+                        len = ents.length;
+                        _a = cols.length;
+                        switch (_a) {
+                            case 1: return [3 /*break*/, 4];
+                            case 2: return [3 /*break*/, 9];
+                            case 3: return [3 /*break*/, 14];
+                            case 4: return [3 /*break*/, 19];
+                            case 5: return [3 /*break*/, 24];
+                            case 6: return [3 /*break*/, 29];
+                        }
+                        return [3 /*break*/, 34];
                     case 4:
-                        if (!(row < a.entities.length)) return [3 /*break*/, 7];
-                        e = a.entities[row];
-                        out = { e: e };
-                        for (i = 0; i < cols.length; i++)
-                            out["c".concat(i + 1)] = cols[i][row];
-                        return [4 /*yield*/, out];
+                        a0 = cols[0];
+                        r = 0;
+                        _c.label = 5;
                     case 5:
-                        _d.sent();
-                        _d.label = 6;
+                        if (!(r < len)) return [3 /*break*/, 8];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r] }];
                     case 6:
-                        row++;
-                        return [3 /*break*/, 4];
+                        _c.sent();
+                        _c.label = 7;
                     case 7:
-                        _b = _a.next();
-                        return [3 /*break*/, 3];
-                    case 8: return [3 /*break*/, 11];
+                        r++;
+                        return [3 /*break*/, 5];
+                    case 8: return [3 /*break*/, 39];
                     case 9:
-                        e_16_1 = _d.sent();
-                        e_16 = { error: e_16_1 };
-                        return [3 /*break*/, 11];
+                        a0 = cols[0], a1 = cols[1];
+                        r = 0;
+                        _c.label = 10;
                     case 10:
+                        if (!(r < len)) return [3 /*break*/, 13];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r], c2: a1[r] }];
+                    case 11:
+                        _c.sent();
+                        _c.label = 12;
+                    case 12:
+                        r++;
+                        return [3 /*break*/, 10];
+                    case 13: return [3 /*break*/, 39];
+                    case 14:
+                        a0 = cols[0], a1 = cols[1], a2 = cols[2];
+                        r = 0;
+                        _c.label = 15;
+                    case 15:
+                        if (!(r < len)) return [3 /*break*/, 18];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r], c2: a1[r], c3: a2[r] }];
+                    case 16:
+                        _c.sent();
+                        _c.label = 17;
+                    case 17:
+                        r++;
+                        return [3 /*break*/, 15];
+                    case 18: return [3 /*break*/, 39];
+                    case 19:
+                        a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3];
+                        r = 0;
+                        _c.label = 20;
+                    case 20:
+                        if (!(r < len)) return [3 /*break*/, 23];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r], c2: a1[r], c3: a2[r], c4: a3[r] }];
+                    case 21:
+                        _c.sent();
+                        _c.label = 22;
+                    case 22:
+                        r++;
+                        return [3 /*break*/, 20];
+                    case 23: return [3 /*break*/, 39];
+                    case 24:
+                        a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3], a4 = cols[4];
+                        r = 0;
+                        _c.label = 25;
+                    case 25:
+                        if (!(r < len)) return [3 /*break*/, 28];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r], c2: a1[r], c3: a2[r], c4: a3[r], c5: a4[r] }];
+                    case 26:
+                        _c.sent();
+                        _c.label = 27;
+                    case 27:
+                        r++;
+                        return [3 /*break*/, 25];
+                    case 28: return [3 /*break*/, 39];
+                    case 29:
+                        a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3], a4 = cols[4], a5 = cols[5];
+                        r = 0;
+                        _c.label = 30;
+                    case 30:
+                        if (!(r < len)) return [3 /*break*/, 33];
+                        return [4 /*yield*/, { e: ents[r], c1: a0[r], c2: a1[r], c3: a2[r], c4: a3[r], c5: a4[r], c6: a5[r] }];
+                    case 31:
+                        _c.sent();
+                        _c.label = 32;
+                    case 32:
+                        r++;
+                        return [3 /*break*/, 30];
+                    case 33: return [3 /*break*/, 39];
+                    case 34:
+                        r = 0;
+                        _c.label = 35;
+                    case 35:
+                        if (!(r < len)) return [3 /*break*/, 38];
+                        out = { e: ents[r] };
+                        for (i = 0; i < cols.length; i++)
+                            out["c".concat(i + 1)] = cols[i][r];
+                        return [4 /*yield*/, out];
+                    case 36:
+                        _c.sent();
+                        _c.label = 37;
+                    case 37:
+                        r++;
+                        return [3 /*break*/, 35];
+                    case 38: return [3 /*break*/, 39];
+                    case 39:
+                        archs_1_1 = archs_1.next();
+                        return [3 /*break*/, 3];
+                    case 40: return [3 /*break*/, 43];
+                    case 41:
+                        e_16_1 = _c.sent();
+                        e_16 = { error: e_16_1 };
+                        return [3 /*break*/, 43];
+                    case 42:
                         try {
-                            if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                            if (archs_1_1 && !archs_1_1.done && (_b = archs_1.return)) _b.call(archs_1);
                         }
                         finally { if (e_16) throw e_16.error; }
                         return [7 /*endfinally*/];
-                    case 11: return [3 /*break*/, 13];
-                    case 12:
+                    case 43: return [3 /*break*/, 45];
+                    case 44:
                         world._iterateDepth--;
                         return [7 /*endfinally*/];
-                    case 13: return [2 /*return*/];
+                    case 45: return [2 /*return*/];
                 }
             });
         }
-        return gen(this);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        var self = this;
+        return _a = {},
+            _a[Symbol.iterator] = function () {
+                self._ensureNotDestroyed();
+                return gen(self, self._matchingArchetypes(needSorted));
+            },
+            _a;
     };
     World.prototype.queryTables = function () {
-        var ctors = [];
+        var _a;
+        var args = [];
         for (var _i = 0; _i < arguments.length; _i++) {
-            ctors[_i] = arguments[_i];
+            args[_i] = arguments[_i];
         }
-        var _a = World._buildQueryTypeIds(ctors), requested = _a.requested, needSorted = _a.needSorted;
-        function gen(world) {
-            var _a, _b, a, out, i, e_17_1;
-            var e_17, _c;
-            return __generator(this, function (_d) {
-                switch (_d.label) {
+        var _b = World._splitArgs(args), ctors = _b.ctors, filter = _b.filter;
+        var _c = World._buildQueryTypeIds(ctors, filter), requested = _c.requested, needSorted = _c.needSorted, withoutSorted = _c.withoutSorted;
+        function gen(world, archs) {
+            var archs_2, archs_2_1, a, out, i, e_17_1;
+            var e_17, _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
                     case 0:
                         world._iterateDepth++;
-                        _d.label = 1;
+                        _b.label = 1;
                     case 1:
-                        _d.trys.push([1, , 10, 11]);
-                        _d.label = 2;
+                        _b.trys.push([1, , 10, 11]);
+                        _b.label = 2;
                     case 2:
-                        _d.trys.push([2, 7, 8, 9]);
-                        _a = __values(world.archetypes), _b = _a.next();
-                        _d.label = 3;
+                        _b.trys.push([2, 7, 8, 9]);
+                        archs_2 = __values(archs), archs_2_1 = archs_2.next();
+                        _b.label = 3;
                     case 3:
-                        if (!!_b.done) return [3 /*break*/, 6];
-                        a = _b.value;
-                        if (!a)
-                            return [3 /*break*/, 5];
-                        if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
+                        if (!!archs_2_1.done) return [3 /*break*/, 6];
+                        a = archs_2_1.value;
+                        if (withoutSorted.length > 0 && (0, Signature_1.signatureHasAny)(a.sig, withoutSorted))
                             return [3 /*break*/, 5];
                         out = { entities: a.entities };
                         for (i = 0; i < requested.length; i++) {
@@ -771,19 +945,19 @@ var World = /** @class */ (function (_super) {
                         }
                         return [4 /*yield*/, out];
                     case 4:
-                        _d.sent();
-                        _d.label = 5;
+                        _b.sent();
+                        _b.label = 5;
                     case 5:
-                        _b = _a.next();
+                        archs_2_1 = archs_2.next();
                         return [3 /*break*/, 3];
                     case 6: return [3 /*break*/, 9];
                     case 7:
-                        e_17_1 = _d.sent();
+                        e_17_1 = _b.sent();
                         e_17 = { error: e_17_1 };
                         return [3 /*break*/, 9];
                     case 8:
                         try {
-                            if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                            if (archs_2_1 && !archs_2_1.done && (_a = archs_2.return)) _a.call(archs_2);
                         }
                         finally { if (e_17) throw e_17.error; }
                         return [7 /*endfinally*/];
@@ -795,7 +969,14 @@ var World = /** @class */ (function (_super) {
                 }
             });
         }
-        return gen(this);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        var self = this;
+        return _a = {},
+            _a[Symbol.iterator] = function () {
+                self._ensureNotDestroyed();
+                return gen(self, self._matchingArchetypes(needSorted));
+            },
+            _a;
     };
     World.prototype.queryEach = function () {
         var e_18, _a;
@@ -803,56 +984,77 @@ var World = /** @class */ (function (_super) {
         for (var _i = 0; _i < arguments.length; _i++) {
             args[_i] = arguments[_i];
         }
+        this._ensureNotDestroyed();
         var fn = args[args.length - 1];
-        var ctors = args.slice(0, args.length - 1);
-        var _b = World._buildQueryTypeIds(ctors), requested = _b.requested, needSorted = _b.needSorted;
+        var rest = args.slice(0, args.length - 1);
+        var filter = World._isQueryFilter(rest[rest.length - 1]) ? rest.pop() : undefined;
+        var ctors = rest;
+        var _b = World._buildQueryTypeIds(ctors, filter), requested = _b.requested, needSorted = _b.needSorted, withoutSorted = _b.withoutSorted;
+        var archs = this._matchingArchetypes(needSorted);
         this._iterateDepth++;
         try {
             try {
-                for (var _c = __values(this.archetypes), _d = _c.next(); !_d.done; _d = _c.next()) {
-                    var a = _d.value;
-                    if (!a)
-                        continue;
-                    if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
+                for (var archs_3 = __values(archs), archs_3_1 = archs_3.next(); !archs_3_1.done; archs_3_1 = archs_3.next()) {
+                    var a = archs_3_1.value;
+                    if (withoutSorted.length > 0 && (0, Signature_1.signatureHasAny)(a.sig, withoutSorted))
                         continue;
                     var cols = new Array(requested.length);
                     for (var i = 0; i < requested.length; i++)
                         cols[i] = a.column(requested[i]);
-                    var _loop_1 = function (row) {
-                        var e = a.entities[row];
-                        switch (cols.length) {
-                            case 1:
-                                fn(e, cols[0][row]);
-                                break;
-                            case 2:
-                                fn(e, cols[0][row], cols[1][row]);
-                                break;
-                            case 3:
-                                fn(e, cols[0][row], cols[1][row], cols[2][row]);
-                                break;
-                            case 4:
-                                fn(e, cols[0][row], cols[1][row], cols[2][row], cols[3][row]);
-                                break;
-                            case 5:
-                                fn(e, cols[0][row], cols[1][row], cols[2][row], cols[3][row], cols[4][row]);
-                                break;
-                            case 6:
-                                fn(e, cols[0][row], cols[1][row], cols[2][row], cols[3][row], cols[4][row], cols[5][row]);
-                                break;
-                            default:
-                                fn.apply(void 0, __spreadArray([e], __read(cols.map(function (c) { return c[row]; })), false));
-                                break;
+                    var ents = a.entities;
+                    var len = ents.length;
+                    switch (cols.length) {
+                        case 1: {
+                            var a0 = cols[0];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r]);
+                            break;
+                        }
+                        case 2: {
+                            var a0 = cols[0], a1 = cols[1];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r], a1[r]);
+                            break;
+                        }
+                        case 3: {
+                            var a0 = cols[0], a1 = cols[1], a2 = cols[2];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r], a1[r], a2[r]);
+                            break;
+                        }
+                        case 4: {
+                            var a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r], a1[r], a2[r], a3[r]);
+                            break;
                         }
-                    };
-                    for (var row = 0; row < a.entities.length; row++) {
-                        _loop_1(row);
+                        case 5: {
+                            var a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3], a4 = cols[4];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r], a1[r], a2[r], a3[r], a4[r]);
+                            break;
+                        }
+                        case 6: {
+                            var a0 = cols[0], a1 = cols[1], a2 = cols[2], a3 = cols[3], a4 = cols[4], a5 = cols[5];
+                            for (var r = 0; r < len; r++)
+                                fn(ents[r], a0[r], a1[r], a2[r], a3[r], a4[r], a5[r]);
+                            break;
+                        }
+                        default:
+                            var _loop_1 = function (r) {
+                                fn.apply(void 0, __spreadArray([ents[r]], __read(cols.map(function (c) { return c[r]; })), false));
+                            };
+                            for (var r = 0; r < len; r++) {
+                                _loop_1(r);
+                            }
+                            break;
                     }
                 }
             }
             catch (e_18_1) { e_18 = { error: e_18_1 }; }
             finally {
                 try {
-                    if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+                    if (archs_3_1 && !archs_3_1.done && (_a = archs_3.return)) _a.call(archs_3);
                 }
                 finally { if (e_18) throw e_18.error; }
             }
@@ -881,19 +1083,52 @@ var World = /** @class */ (function (_super) {
     World.prototype._resetArchetypes = function () {
         this.archetypes.length = 0;
         this.archByKey.clear();
+        this._queryCache.clear();
         // Archetype 0: empty signature
         var archetype0 = new Archetype_1.Archetype(0, []);
         this.archetypes[0] = archetype0;
         this.archByKey.set("", archetype0);
     };
-    World._buildQueryTypeIds = function (ctors) {
+    World._isQueryFilter = function (v) {
+        return typeof v === 'object' && v !== null && !Array.isArray(v);
+    };
+    World._splitArgs = function (args) {
+        var last = args[args.length - 1];
+        if (World._isQueryFilter(last)) {
+            return { ctors: args.slice(0, args.length - 1), filter: last };
+        }
+        return { ctors: args, filter: undefined };
+    };
+    /**
+     * Returns the list of archetypes matching `needSorted` (a sorted, deduped TypeId array).
+     * Results are cached per query signature. Because archetypes are append-only, stale entries
+     * are extended incrementally — only newly-added archetypes are re-scanned.
+     */
+    World.prototype._matchingArchetypes = function (needSorted) {
+        var key = (0, Signature_1.signatureKey)(needSorted);
+        var entry = this._queryCache.get(key);
+        if (!entry) {
+            entry = { archs: [], checked: 0 };
+            this._queryCache.set(key, entry);
+        }
+        var total = this.archetypes.length;
+        for (var i = entry.checked; i < total; i++) {
+            var a = this.archetypes[i];
+            if (a && (0, Signature_1.signatureHasAll)(a.sig, needSorted))
+                entry.archs.push(a);
+        }
+        entry.checked = total;
+        return entry.archs;
+    };
+    World._buildQueryTypeIds = function (ctors, filter) {
+        var _a, _b, _c, _d;
         // Preserve caller order for (c1,c2,c3,...) mapping.
         var requested = new Array(ctors.length);
         for (var i = 0; i < ctors.length; i++)
             requested[i] = (0, TypeRegistry_1.typeId)(ctors[i]);
-        // Same ids, but sorted + deduped for signatureHasAll().
-        var needSorted = requested.slice();
-        needSorted.sort(function (a, b) { return a - b; });
+        // needSorted = requested ids + any "with-only" ids (present but not returned), sorted + deduped.
+        var withOnlyIds = (_b = (_a = filter === null || filter === void 0 ? void 0 : filter.with) === null || _a === void 0 ? void 0 : _a.map(function (c) { return (0, TypeRegistry_1.typeId)(c); })) !== null && _b !== void 0 ? _b : [];
+        var needSorted = __spreadArray(__spreadArray([], __read(requested), false), __read(withOnlyIds), false).sort(function (a, b) { return a - b; });
         var w = 0;
         for (var i = 0; i < needSorted.length; i++) {
             var v = needSorted[i];
@@ -901,7 +1136,13 @@ var World = /** @class */ (function (_super) {
                 needSorted[w++] = v;
         }
         needSorted.length = w;
-        return { requested: requested, needSorted: needSorted };
+        // withoutSorted: archetypes that have ANY of these are excluded.
+        var withoutSorted = ((_d = (_c = filter === null || filter === void 0 ? void 0 : filter.without) === null || _c === void 0 ? void 0 : _c.map(function (c) { return (0, TypeRegistry_1.typeId)(c); })) !== null && _d !== void 0 ? _d : []).sort(function (a, b) { return a - b; });
+        return { requested: requested, needSorted: needSorted, withoutSorted: withoutSorted };
+    };
+    World.prototype._ensureNotDestroyed = function () {
+        if (this._destroyed)
+            throw new Error("Cannot use a destroyed World.");
     };
     World.prototype._ensureNotIterating = function (op) {
         if (this._iterateDepth > 0) {
@@ -974,8 +1215,12 @@ var World = /** @class */ (function (_super) {
                 return this.despawn(op.e);
             case "add":
                 return this.add(op.e, op.ctor, op.value);
+            case "addMany":
+                return this.addMany.apply(this, __spreadArray([op.e], __read(op.items), false));
             case "remove":
                 return this.remove(op.e, op.ctor);
+            case "removeMany":
+                return this.removeMany.apply(this, __spreadArray([op.e], __read(op.ctors), false));
         }
     };
     World.prototype._formatEntity = function (e) {