archetype-ecs-lib 0.5.0 → 0.6.1

package/lib/ecs/World.js

@@ -1,4 +1,19 @@
 "use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
 var __generator = (this && this.__generator) || function (thisArg, body) {
     var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
     return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
@@ -53,6 +68,15 @@ var __read = (this && this.__read) || function (o, n) {
     }
     return ar;
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.World = void 0;
 var Archetype_1 = require("./Archetype");
@@ -61,21 +85,154 @@ var EntityManager_1 = require("./EntityManager");
 var Events_1 = require("./Events");
 var Signature_1 = require("./Signature");
 var TypeRegistry_1 = require("./TypeRegistry");
-var World = /** @class */ (function () {
-    function World() {
-        this.entities = new EntityManager_1.EntityManager();
-        this.archetypes = [];
-        this.archByKey = new Map();
-        this.systems = [];
-        this.commands = new Commands_1.Commands();
-        this._iterateDepth = 0;
-        this.resources = new Map();
-        this.eventChannels = new Map();
-        // Archetype 0: empty signature
-        var archetype0 = new Archetype_1.Archetype(0, []);
-        this.archetypes[0] = archetype0;
-        this.archByKey.set("", archetype0);
+var WorldSnapshotStore_1 = require("./WorldSnapshotStore");
+var StatsOverlay_1 = require("./stats/StatsOverlay");
+var World = /** @class */ (function (_super) {
+    __extends(World, _super);
+    function World(options) {
+        var _this = _super.call(this, options === null || options === void 0 ? void 0 : options.statsOverlayOptions) || this;
+        _this.entities = new EntityManager_1.EntityManager();
+        _this.archetypes = [];
+        _this.archByKey = new Map();
+        _this.systems = [];
+        _this.commands = new Commands_1.Commands();
+        _this._iterateDepth = 0;
+        _this.resources = new Map();
+        _this.eventChannels = new Map();
+        _this.snapshotStore = new WorldSnapshotStore_1.WorldSnapshotStore();
+        /** @internal Phase -> systems mapping for Schedule */
+        _this._scheduleSystems = new Map();
+        _this._resetArchetypes();
+        return _this;
     }
+    World.prototype.statsHistory = function () {
+        var e_1, _a, e_2, _b;
+        var phaseMs = Object.create(null);
+        try {
+            for (var _c = __values(this._histPhaseMs), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var _e = __read(_d.value, 2), k = _e[0], v = _e[1];
+                phaseMs[k] = v;
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        var systemMs = Object.create(null);
+        try {
+            for (var _f = __values(this._histSystemMs), _g = _f.next(); !_g.done; _g = _f.next()) {
+                var _h = __read(_g.value, 2), k = _h[0], v = _h[1];
+                systemMs[k] = v;
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return {
+            capacity: this._historyCapacity,
+            size: this._histFrameMs.length,
+            dt: this._histDt,
+            frameMs: this._histFrameMs,
+            phaseMs: phaseMs,
+            systemMs: systemMs
+        };
+    };
+    /**
+     * Rich runtime statistics (counts + last-frame timings).
+     * Note: `aliveEntities` is computed on demand (O(n) over entity meta).
+     */
+    World.prototype.stats = function () {
+        var e_3, _a, e_4, _b, e_5, _c, e_6, _d;
+        var alive = 0;
+        for (var id = 1; id < this.entities.meta.length; id++) {
+            var m = this.entities.meta[id];
+            if (m && m.alive)
+                alive++;
+        }
+        var archCount = 0;
+        var rows = 0;
+        try {
+            for (var _e = __values(this.archetypes), _f = _e.next(); !_f.done; _f = _e.next()) {
+                var a = _f.value;
+                if (!a)
+                    continue;
+                archCount++;
+                rows += a.entities.length;
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        var phaseMs = Object.create(null);
+        try {
+            for (var _g = __values(this._phaseMs), _h = _g.next(); !_h.done; _h = _g.next()) {
+                var _j = __read(_h.value, 2), k = _j[0], v = _j[1];
+                phaseMs[k] = v;
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_h && !_h.done && (_b = _g.return)) _b.call(_g);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+        var systemMs = Object.create(null);
+        try {
+            for (var _k = __values(this._systemMs), _l = _k.next(); !_l.done; _l = _k.next()) {
+                var _m = __read(_l.value, 2), k = _m[0], v = _m[1];
+                systemMs[k] = v;
+            }
+        }
+        catch (e_5_1) { e_5 = { error: e_5_1 }; }
+        finally {
+            try {
+                if (_l && !_l.done && (_c = _k.return)) _c.call(_k);
+            }
+            finally { if (e_5) throw e_5.error; }
+        }
+        var systemCount = this.systems.length;
+        if (this._scheduleSystems.size > 0) {
+            try {
+                for (var _o = __values(this._scheduleSystems.values()), _p = _o.next(); !_p.done; _p = _o.next()) {
+                    var list = _p.value;
+                    systemCount += list.length;
+                }
+            }
+            catch (e_6_1) { e_6 = { error: e_6_1 }; }
+            finally {
+                try {
+                    if (_p && !_p.done && (_d = _o.return)) _d.call(_o);
+                }
+                finally { if (e_6) throw e_6.error; }
+            }
+        }
+        return {
+            aliveEntities: alive,
+            archetypes: archCount,
+            rows: rows,
+            systems: systemCount,
+            resources: this.resources.size,
+            eventChannels: this.eventChannels.size,
+            pendingCommands: this.commands.hasPending(),
+            frame: this._frameCounter,
+            dt: this._lastDt,
+            frameMs: this._lastFrameMs,
+            phaseMs: phaseMs,
+            systemMs: systemMs
+        };
+    };
     /** Queue structural changes to apply safely after systems run. */
     World.prototype.cmd = function () {
         return this.commands;
@@ -85,57 +242,127 @@ var World = /** @class */ (function () {
         return this;
     };
     /**
-     * Run a frame:
-     * - run systems in order
-     * - flush queued commands (structural changes)
+     * Simple single-phase update.
+     * Runs all systems added via `addSystem()`, flushes commands, and swaps events once.
+     *
+     * This is the recommended approach for:
+     * - Simple applications with basic game loops
+     * - Single-phase system execution
+     * - Rapid prototyping
+     *
+     * @example
+     * ```TypeScript
+     * // Simple game loop
+     * function gameLoop(dt: number) {
+     *   world.update(dt);
+     * }
+     * ```
+     *
+     * @note If you are using `Schedule` for multiphase updates, do NOT use this method.
+     *  Use `schedule.run(world, dt, phases)` instead.
+     *
+     * @throws {Error} If both World.update() and Schedule.run() are used on the same World instance
      */
     World.prototype.update = function (dt) {
-        var e_1, _a;
+        var e_7, _a;
+        // 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()) {
                     var s = _c.value;
-                    s(this, dt);
+                    if (this._profilingEnabled) {
+                        var t0 = performance.now();
+                        s(this, dt);
+                        var name_1 = s.name && s.name.length > 0 ? s.name : "<anonymous>";
+                        this._profAddSystem(name_1, performance.now() - t0);
+                    }
+                    else {
+                        s(this, dt);
+                    }
                 }
             }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            catch (e_7_1) { e_7 = { error: e_7_1 }; }
             finally {
                 try {
                     if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
                 }
-                finally { if (e_1) throw e_1.error; }
+                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_2, _a;
+        var e_8, _a;
         this._ensureNotIterating("flush");
-        // Apply commands until queue is empty. This allows spawn(init) to enqueue add/remove
+        // Apply commands until the queue is empty. This allows spawn(init) to enqueue add/remove
         // operations that will be applied during the same flush.
         while (true) {
             var ops = this.commands.drain();
             if (ops.length === 0)
                 break;
             try {
-                for (var ops_1 = (e_2 = void 0, __values(ops)), ops_1_1 = ops_1.next(); !ops_1_1.done; ops_1_1 = ops_1.next()) {
+                for (var ops_1 = (e_8 = void 0, __values(ops)), ops_1_1 = ops_1.next(); !ops_1_1.done; ops_1_1 = ops_1.next()) {
                     var op = ops_1_1.value;
                     this._apply(op);
                 }
             }
-            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            catch (e_8_1) { e_8 = { error: e_8_1 }; }
             finally {
                 try {
                     if (ops_1_1 && !ops_1_1.done && (_a = ops_1.return)) _a.call(ops_1);
                 }
-                finally { if (e_2) throw e_2.error; }
+                finally { if (e_8) throw e_8.error; }
             }
         }
     };
+    //#region ---------- Snapshot / Restore ----------
+    World.prototype.registerComponentSnapshot = function (key, codec) {
+        this.snapshotStore.registerComponentSnapshot(this._snapshotRuntime(), key, codec);
+        return this;
+    };
+    World.prototype.unregisterComponentSnapshot = function (key) {
+        return this.snapshotStore.unregisterComponentSnapshot(key);
+    };
+    World.prototype.registerResourceSnapshot = function (key, codec) {
+        this.snapshotStore.registerResourceSnapshot(this._snapshotRuntime(), key, codec);
+        return this;
+    };
+    World.prototype.unregisterResourceSnapshot = function (key) {
+        return this.snapshotStore.unregisterResourceSnapshot(key);
+    };
+    World.prototype.snapshot = function () {
+        return this.snapshotStore.snapshot(this._snapshotRuntime());
+    };
+    World.prototype.restore = function (snapshot) {
+        this.snapshotStore.restore(this._snapshotRuntime(), snapshot);
+        this.updateOverlay(this.stats(), this.statsHistory());
+    };
+    //#endregion
     //#region ---------- Resources (singletons) ----------
     World.prototype.setResource = function (key, value) {
         this.resources.set(key, value);
@@ -147,9 +374,9 @@ var World = /** @class */ (function () {
     };
     World.prototype.requireResource = function (key) {
         if (!this.resources.has(key)) {
-            var name = this._formatCtor(key);
-            throw new Error("Missing resource ".concat(name, ". ") +
-                "Insert it via world.setResource(".concat(name, ", value) or world.initResource(").concat(name, ", () => value)."));
+            var name_2 = this._formatCtor(key);
+            throw new Error("requireResource(".concat(name_2, ") failed: resource missing. ") +
+                "Insert it via world.setResource(".concat(name_2, ", value) or world.initResource(").concat(name_2, ", () => value)."));
         }
         return this.resources.get(key);
     };
@@ -181,7 +408,7 @@ var World = /** @class */ (function () {
         ch.drain(fn);
     };
     World.prototype.clearEvents = function (key) {
-        var e_3, _a;
+        var e_9, _a;
         if (key) {
             var ch = this.eventChannels.get(key);
             if (!ch)
@@ -196,34 +423,35 @@ var World = /** @class */ (function () {
                 ch.clear();
             }
         }
-        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        catch (e_9_1) { e_9 = { error: e_9_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_3) throw e_3.error; }
+            finally { if (e_9) throw e_9.error; }
         }
     };
     /** @internal Called by Schedule at phase boundaries */
     World.prototype.swapEvents = function () {
-        var e_4, _a;
+        var e_10, _a;
         try {
             for (var _b = __values(this.eventChannels.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
                 var ch = _c.value;
                 ch.swapBuffers();
             }
         }
-        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        catch (e_10_1) { e_10 = { error: e_10_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_4) throw e_4.error; }
+            finally { if (e_10) throw e_10.error; }
         }
     };
     //#endregion
     //#region ---------- Entity lifecycle ----------
     World.prototype.spawn = function () {
+        this._ensureNotIterating("spawn");
         var entity = this.entities.create();
         // place in archetype 0
         var archetype0 = this.archetypes[0];
@@ -234,7 +462,7 @@ var World = /** @class */ (function () {
         return entity;
     };
     World.prototype.spawnMany = function () {
-        var e_5, _a;
+        var e_11, _a;
         var items = [];
         for (var _i = 0; _i < arguments.length; _i++) {
             items[_i] = arguments[_i];
@@ -246,12 +474,12 @@ var World = /** @class */ (function () {
                 this.add(e, ctor, value);
             }
         }
-        catch (e_5_1) { e_5 = { error: e_5_1 }; }
+        catch (e_11_1) { e_11 = { error: e_11_1 }; }
         finally {
             try {
                 if (items_1_1 && !items_1_1.done && (_a = items_1.return)) _a.call(items_1);
             }
-            finally { if (e_5) throw e_5.error; }
+            finally { if (e_11) throw e_11.error; }
         }
         return e;
     };
@@ -265,19 +493,19 @@ var World = /** @class */ (function () {
         this.entities.kill(e);
     };
     World.prototype.despawnMany = function (entities) {
-        var e_6, _a;
+        var e_12, _a;
         try {
             for (var entities_1 = __values(entities), entities_1_1 = entities_1.next(); !entities_1_1.done; entities_1_1 = entities_1.next()) {
                 var e = entities_1_1.value;
                 this.despawn(e);
             }
         }
-        catch (e_6_1) { e_6 = { error: e_6_1 }; }
+        catch (e_12_1) { e_12 = { error: e_12_1 }; }
         finally {
             try {
                 if (entities_1_1 && !entities_1_1.done && (_a = entities_1.return)) _a.call(entities_1);
             }
-            finally { if (e_6) throw e_6.error; }
+            finally { if (e_12) throw e_12.error; }
         }
     };
     //#endregion
@@ -300,7 +528,8 @@ var World = /** @class */ (function () {
         return a.column(tid)[meta.row];
     };
     World.prototype.set = function (e, ctor, value) {
-        var meta = this._assertAlive(e, "set(".concat(this._formatCtor(ctor), ")"));
+        var op = "set(".concat(this._formatCtor(ctor), ")");
+        var meta = this._assertAlive(e, op);
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var a = this.archetypes[meta.arch];
         if (!a.has(tid))
@@ -308,8 +537,9 @@ var World = /** @class */ (function () {
         a.column(tid)[meta.row] = value;
     };
     World.prototype.add = function (e, ctor, value) {
-        this._assertAlive(e, "add(".concat(this._formatCtor(ctor), ")"));
-        this._ensureNotIterating("add");
+        var op = "add(".concat(this._formatCtor(ctor), ")");
+        this._assertAlive(e, op);
+        this._ensureNotIterating(op);
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var srcMeta = this.entities.meta[e.id];
         var src = this.archetypes[srcMeta.arch];
@@ -327,28 +557,75 @@ var World = /** @class */ (function () {
         });
     };
     World.prototype.addMany = function (e) {
-        var e_7, _a;
+        var e_13, _a, e_14, _b;
         var items = [];
         for (var _i = 1; _i < arguments.length; _i++) {
             items[_i - 1] = arguments[_i];
         }
+        if (items.length === 0)
+            return;
+        this._assertAlive(e, "addMany");
+        this._ensureNotIterating("addMany");
+        var srcMeta = this.entities.meta[e.id];
+        var src = this.archetypes[srcMeta.arch];
+        // Build component map: TypeId -> value
+        var newComps = new Map();
         try {
             for (var items_2 = __values(items), items_2_1 = items_2.next(); !items_2_1.done; items_2_1 = items_2.next()) {
-                var _b = __read(items_2_1.value, 2), ctor = _b[0], value = _b[1];
-                this.add(e, ctor, value);
+                var _c = __read(items_2_1.value, 2), ctor = _c[0], value = _c[1];
+                var tid = (0, TypeRegistry_1.typeId)(ctor);
+                newComps.set(tid, value);
             }
         }
-        catch (e_7_1) { e_7 = { error: e_7_1 }; }
+        catch (e_13_1) { e_13 = { error: e_13_1 }; }
         finally {
             try {
                 if (items_2_1 && !items_2_1.done && (_a = items_2.return)) _a.call(items_2);
             }
-            finally { if (e_7) throw e_7.error; }
+            finally { if (e_13) throw e_13.error; }
         }
+        // Compute final signature: src.sig + new components
+        var dstSig = src.sig.slice();
+        try {
+            for (var _d = __values(newComps.keys()), _e = _d.next(); !_e.done; _e = _d.next()) {
+                var tid = _e.value;
+                if (!src.has(tid)) {
+                    // Insert in sorted order
+                    var i = 0;
+                    while (i < dstSig.length && dstSig[i] < tid)
+                        i++;
+                    if (dstSig[i] !== tid) {
+                        dstSig.splice(i, 0, tid);
+                    }
+                }
+                else {
+                    // Component already exists, update in-place
+                    src.column(tid)[srcMeta.row] = newComps.get(tid);
+                    newComps.delete(tid);
+                }
+            }
+        }
+        catch (e_14_1) { e_14 = { error: e_14_1 }; }
+        finally {
+            try {
+                if (_e && !_e.done && (_b = _d.return)) _b.call(_d);
+            }
+            finally { if (e_14) throw e_14.error; }
+        }
+        // If all components were in-place updates, no move needed
+        if (newComps.size === 0)
+            return;
+        // Single move to final archetype
+        var dst = this._getOrCreateArchetype(dstSig);
+        this._moveEntity(e, src, srcMeta.row, dst, function (t) {
+            // Use new value if adding this component, otherwise copy from src
+            return newComps.has(t) ? newComps.get(t) : src.column(t)[srcMeta.row];
+        });
     };
     World.prototype.remove = function (e, ctor) {
-        this._assertAlive(e, "remove(".concat(this._formatCtor(ctor), ")"));
-        this._ensureNotIterating("remove");
+        var op = "remove(".concat(this._formatCtor(ctor), ")");
+        this._assertAlive(e, op);
+        this._ensureNotIterating(op);
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var srcMeta = this.entities.meta[e.id];
         var src = this.archetypes[srcMeta.arch];
@@ -362,47 +639,57 @@ var World = /** @class */ (function () {
         });
     };
     World.prototype.removeMany = function (e) {
-        var e_8, _a;
+        var e_15, _a;
         var ctors = [];
         for (var _i = 1; _i < arguments.length; _i++) {
             ctors[_i - 1] = arguments[_i];
         }
+        if (ctors.length === 0)
+            return;
+        this._assertAlive(e, "removeMany");
+        this._ensureNotIterating("removeMany");
+        var srcMeta = this.entities.meta[e.id];
+        var src = this.archetypes[srcMeta.arch];
+        // Collect TypeIds to remove
+        var toRemove = new Set();
         try {
             for (var ctors_1 = __values(ctors), ctors_1_1 = ctors_1.next(); !ctors_1_1.done; ctors_1_1 = ctors_1.next()) {
                 var ctor = ctors_1_1.value;
-                this.remove(e, ctor);
+                var tid = (0, TypeRegistry_1.typeId)(ctor);
+                if (src.has(tid)) {
+                    toRemove.add(tid);
+                }
             }
         }
-        catch (e_8_1) { e_8 = { error: e_8_1 }; }
+        catch (e_15_1) { e_15 = { error: e_15_1 }; }
         finally {
             try {
                 if (ctors_1_1 && !ctors_1_1.done && (_a = ctors_1.return)) _a.call(ctors_1);
             }
-            finally { if (e_8) throw e_8.error; }
+            finally { if (e_15) throw e_15.error; }
         }
+        // If nothing to remove, no-op
+        if (toRemove.size === 0)
+            return;
+        // Compute final signature: src.sig - removed components
+        var dstSig = src.sig.filter(function (tid) { return !toRemove.has(tid); });
+        // Single move to final archetype
+        var dst = this._getOrCreateArchetype(dstSig);
+        this._moveEntity(e, src, srcMeta.row, dst, function (t) {
+            // Copy all components except removed ones (dstSig guarantees t is not removed)
+            return src.column(t)[srcMeta.row];
+        });
     };
     World.prototype.query = function () {
+        var _a;
         var ctors = [];
         for (var _i = 0; _i < arguments.length; _i++) {
             ctors[_i] = arguments[_i];
         }
-        // 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; });
-        var w = 0;
-        for (var i = 0; i < needSorted.length; i++) {
-            var v = needSorted[i];
-            if (i === 0 || v !== needSorted[w - 1])
-                needSorted[w++] = v;
-        }
-        needSorted.length = w;
+        var _b = World._buildQueryTypeIds(ctors), requested = _b.requested, needSorted = _b.needSorted;
         function gen(world) {
-            var _a, _b, a, cols, i, row, e, out, i, e_9_1;
-            var e_9, _c;
+            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) {
                     case 0:
@@ -445,14 +732,14 @@ var World = /** @class */ (function () {
                         return [3 /*break*/, 3];
                     case 8: return [3 /*break*/, 11];
                     case 9:
-                        e_9_1 = _d.sent();
-                        e_9 = { error: e_9_1 };
+                        e_16_1 = _d.sent();
+                        e_16 = { error: e_16_1 };
                         return [3 /*break*/, 11];
                     case 10:
                         try {
                             if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
                         }
-                        finally { if (e_9) throw e_9.error; }
+                        finally { if (e_16) throw e_16.error; }
                         return [7 /*endfinally*/];
                     case 11: return [3 /*break*/, 13];
                     case 12:
@@ -462,10 +749,179 @@ var World = /** @class */ (function () {
                 }
             });
         }
-        return gen(this);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        var self = this;
+        return _a = {}, _a[Symbol.iterator] = function () { return gen(self); }, _a;
+    };
+    World.prototype.queryTables = function () {
+        var _a;
+        var ctors = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            ctors[_i] = arguments[_i];
+        }
+        var _b = World._buildQueryTypeIds(ctors), requested = _b.requested, needSorted = _b.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) {
+                    case 0:
+                        world._iterateDepth++;
+                        _d.label = 1;
+                    case 1:
+                        _d.trys.push([1, , 10, 11]);
+                        _d.label = 2;
+                    case 2:
+                        _d.trys.push([2, 7, 8, 9]);
+                        _a = __values(world.archetypes), _b = _a.next();
+                        _d.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))
+                            return [3 /*break*/, 5];
+                        out = { entities: a.entities };
+                        for (i = 0; i < requested.length; i++) {
+                            out["c".concat(i + 1)] = a.column(requested[i]);
+                        }
+                        return [4 /*yield*/, out];
+                    case 4:
+                        _d.sent();
+                        _d.label = 5;
+                    case 5:
+                        _b = _a.next();
+                        return [3 /*break*/, 3];
+                    case 6: return [3 /*break*/, 9];
+                    case 7:
+                        e_17_1 = _d.sent();
+                        e_17 = { error: e_17_1 };
+                        return [3 /*break*/, 9];
+                    case 8:
+                        try {
+                            if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                        }
+                        finally { if (e_17) throw e_17.error; }
+                        return [7 /*endfinally*/];
+                    case 9: return [3 /*break*/, 11];
+                    case 10:
+                        world._iterateDepth--;
+                        return [7 /*endfinally*/];
+                    case 11: return [2 /*return*/];
+                }
+            });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        var self = this;
+        return _a = {}, _a[Symbol.iterator] = function () { return gen(self); }, _a;
+    };
+    World.prototype.queryEach = function () {
+        var e_18, _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        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;
+        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))
+                        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;
+                        }
+                    };
+                    for (var row = 0; row < a.entities.length; row++) {
+                        _loop_1(row);
+                    }
+                }
+            }
+            catch (e_18_1) { e_18 = { error: e_18_1 }; }
+            finally {
+                try {
+                    if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+                }
+                finally { if (e_18) throw e_18.error; }
+            }
+        }
+        finally {
+            this._iterateDepth--;
+        }
     };
     //#endregion
     //#region ---------- Internals ----------
+    World.prototype._snapshotRuntime = function () {
+        var _this = this;
+        return {
+            ensureNotIterating: function (op) { return _this._ensureNotIterating(op); },
+            formatCtor: function (ctor) { return _this._formatCtor(ctor); },
+            flush: function () { return _this.flush(); },
+            resetArchetypes: function () { return _this._resetArchetypes(); },
+            getOrCreateArchetype: function (sig) { return _this._getOrCreateArchetype(sig); },
+            commands: this.commands,
+            entities: this.entities,
+            archetypes: this.archetypes,
+            resources: this.resources,
+            eventChannels: this.eventChannels
+        };
+    };
+    World.prototype._resetArchetypes = function () {
+        this.archetypes.length = 0;
+        this.archByKey.clear();
+        // Archetype 0: empty signature
+        var archetype0 = new Archetype_1.Archetype(0, []);
+        this.archetypes[0] = archetype0;
+        this.archByKey.set("", archetype0);
+    };
+    World._buildQueryTypeIds = function (ctors) {
+        // 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; });
+        var w = 0;
+        for (var i = 0; i < needSorted.length; i++) {
+            var v = needSorted[i];
+            if (i === 0 || v !== needSorted[w - 1])
+                needSorted[w++] = v;
+        }
+        needSorted.length = w;
+        return { requested: requested, needSorted: needSorted };
+    };
     World.prototype._ensureNotIterating = function (op) {
         if (this._iterateDepth > 0) {
             throw new Error("Cannot do structural change (".concat(op, ") while iterating. Use world.cmd() and flush at end of frame."));
@@ -497,7 +953,7 @@ var World = /** @class */ (function () {
      * Then swap-remove from src.
      */
     World.prototype._moveEntity = function (e, src, srcRow, dst, pick) {
-        var e_10, _a;
+        var e_19, _a;
         // add row in dst
         var dstRow = dst.addRow(e);
         try {
@@ -506,12 +962,12 @@ var World = /** @class */ (function () {
                 dst.column(t).push(pick(t));
             }
         }
-        catch (e_10_1) { e_10 = { error: e_10_1 }; }
+        catch (e_19_1) { e_19 = { error: e_19_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_10) throw e_10.error; }
+            finally { if (e_19) throw e_19.error; }
         }
         // update meta to dst before removing from src (in case src==dst should never happen here)
         var m = this.entities.meta[e.id];
@@ -552,10 +1008,10 @@ var World = /** @class */ (function () {
      * Throws an error if the entity is not alive
      */
     World.prototype._assertAlive = function (e, op) {
-        var _a, _b;
         var meta = this.entities.meta[e.id];
         if (!this.entities.isAlive(e)) {
-            throw new Error("".concat(op, " on stale entity ").concat(this._formatEntity(e), " (alive=").concat((_a = meta === null || meta === void 0 ? void 0 : meta.alive) !== null && _a !== void 0 ? _a : false, ", gen=").concat((_b = meta === null || meta === void 0 ? void 0 : meta.gen) !== null && _b !== void 0 ? _b : "n/a", ")"));
+            var status_1 = meta ? "alive=".concat(meta.alive, ", gen=").concat(meta.gen) : "not found";
+            throw new Error("".concat(op, " failed: stale entity ").concat(this._formatEntity(e), " (").concat(status_1, ")"));
         }
         return meta;
     };
@@ -567,6 +1023,30 @@ var World = /** @class */ (function () {
         }
         return ch;
     };
+    /**
+     * @internal Warns about lifecycle method conflicts in development mode
+     */
+    World.prototype._warnAboutLifecycleConflict = function (method) {
+        var hint = method === "World.update"
+            ? "You have systems registered via schedule.add() but are calling world.update()."
+            : "You have systems registered via world.addSystem() but are calling schedule.run().";
+        throw new Error("\u26A0\uFE0F  ECS Lifecycle Conflict Detected!\n" +
+            "".concat(hint, "\n") +
+            "This can cause:\n" +
+            "- Double command flushes\n" +
+            "- Confusing event visibility\n" +
+            "- Unclear lifecycle semantics\n\n" +
+            "Recommended fix:\n" +
+            "- Use World.update() for simple single-phase applications (with world.addSystem())\n" +
+            "- Use Schedule.run() for multi-phase applications (with schedule.add())\n\n" +
+            "Choose ONE approach and stick with it.");
+    };
+    /**
+     * @internal Returns the number of systems registered via addSystem()
+     */
+    World.prototype._getSystemCount = function () {
+        return this.systems.length;
+    };
     return World;
-}());
+}(StatsOverlay_1.StatsOverlay));
 exports.World = World;