archetype-ecs-lib 0.5.0 → 0.6.1

package/lib/ecs/Schedule.js

@@ -10,68 +10,426 @@ var __values = (this && this.__values) || function(o) {
     };
     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
 };
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    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.Schedule = void 0;
 /**
- * Minimal scheduler that supports phases, without borrow-checking.
- * (Add conflict detection later if you want parallelism.)
+ * Minimal multiphase scheduler for running ECS systems in named "phases".
+ *
+ * ## What it does
+ * - Group systems by phase name (e.g. `"input"`, `"update"`, `"render"`).
+ * - Executes phases in a chosen order.
+ * - Optionally performs **phase-boundary work** (flush commands and swap events).
+ * - Supports **ordering constraints** between phases via `.after()` / `.before()`.
+ *
+ * ## Phase boundaries
+ * By default (`boundaryMode = "auto"`), after each phase:
+ * - if `world.cmd().hasPending()` → `world.flush()`
+ * - `world.swapEvents()` so events emitted in this phase become visible to the next phase
+ *
+ * Use `"manual"` boundary mode if you want to control flush/event delivery yourself.
+ *
+ * @example
+ * ```ts
+ * const schedule = new Schedule();
+ *
+ * schedule
+ *   .add(world, "input", inputSystem)
+ *   .add(world, "sim", simSystem).after("input")
+ *   .add(world, "render", renderSystem).after("sim");
+ *
+ * // Either pass an explicit phase list...
+ * schedule.run(world, dt, ["input", "sim", "render"]);
+ *
+ * // ...or omit it and let constraints drive the order:
+ * // schedule.run(world, dt);
+ * ```
  */
 var Schedule = /** @class */ (function () {
     function Schedule() {
-        this.phases = new Map();
+        this.phaseOrder = undefined;
+        this.boundaryMode = "auto";
+        /**
+         * Phase ordering constraints stored as edges `before -> after`.
+         * Example: calling `after("input")` for phase `"sim"` records `input -> sim`.
+         */
+        this.phaseEdges = new Map();
+        /**
+         * Tracks the most recently modified phase (via add()) so `.after()`/`.before()` can be chained.
+         */
+        this._lastPhase = undefined;
     }
-    Schedule.prototype.add = function (phase, fn) {
+    /**
+     * Set a default phase order used when calling `run(world, dt)` without passing `phaseOrder`.
+     *
+     * @param phases Ordered list of phase names to execute.
+     */
+    Schedule.prototype.setOrder = function (phases) {
+        this.phaseOrder = phases.slice();
+        return this;
+    };
+    /**
+     * Control what happens at phase boundaries.
+     *
+     * - `"auto"` (default): flush deferred commands (if pending) and swap event buffers after each phase.
+     * - `"manual"`: do nothing automatically; the caller is responsible for `world.flush()` / `world.swapEvents()`.
+     *
+     * @param mode Boundary behavior.
+     */
+    Schedule.prototype.setBoundaryMode = function (mode) {
+        this.boundaryMode = mode;
+        return this;
+    };
+    /**
+     * Add a system function to a phase in the given world.
+     *
+     * The returned object allows you to attach **phase ordering constraints**:
+     * - `.after("input")` means this phase must run after `"input"`.
+     * - `.before("render")` means this phase must run before `"render"`.
+     *
+     * Constraints are **phase-level**, not system-level: they affect the relative order of phases, not
+     * the order of systems within the same phase.
+     *
+     * @param world World instance to add the system to.
+     * @param phase Phase name.
+     * @param fn System function `(world, dt) => void`.
+     */
+    Schedule.prototype.add = function (world, phase, fn) {
         var _a;
-        var list = (_a = this.phases.get(phase)) !== null && _a !== void 0 ? _a : [];
+        var phases = world._scheduleSystems;
+        var list = (_a = phases.get(phase)) !== null && _a !== void 0 ? _a : [];
         list.push(fn);
-        this.phases.set(phase, list);
+        phases.set(phase, list);
+        this._lastPhase = phase;
         return this;
     };
+    /**
+     * Constrain the last added phase to run after `otherPhase`.
+     *
+     * Must be called after `add(...)`.
+     */
+    Schedule.prototype.after = function (otherPhase) {
+        if (!this._lastPhase) {
+            throw new Error("Schedule.after(\"".concat(otherPhase, "\") must be called after schedule.add(world, phase, fn)."));
+        }
+        this._addPhaseConstraint(otherPhase, this._lastPhase);
+        return this;
+    };
+    /**
+     * Constrain the last added phase to run before `otherPhase`.
+     *
+     * Must be called after `add(...)`.
+     */
+    Schedule.prototype.before = function (otherPhase) {
+        if (!this._lastPhase) {
+            throw new Error("Schedule.before(\"".concat(otherPhase, "\") must be called after schedule.add(world, phase, fn)."));
+        }
+        this._addPhaseConstraint(this._lastPhase, otherPhase);
+        return this;
+    };
+    /**
+     * Execute all scheduled systems for the given frame.
+     *
+     * Phase order selection:
+     * 1) If `phaseOrder` is provided, it is used as-is.
+     * 2) Else if `setOrder()` was called, the stored order is used.
+     * 3) Else an order is computed from `.after()`/`.before()` constraints.
+     *
+     * @param world World instance (API) passed to each system.
+     * @param dt Delta time in seconds.
+     * @param phaseOrder Optional explicit phase order for this run.
+     *
+     * @throws If both `Schedule.run()` and `World.update()` are used on the same World instance.
+     * @throws If phase constraints contain a cycle and no explicit order is provided.
+     * @throws Re-throws system errors, wrapped with `[phase=... system=...]` context.
+     *
+     * @note When using `Schedule`, avoid calling `world.update()` on the same World instance.
+     */
     Schedule.prototype.run = function (world, dt, phaseOrder) {
         var e_1, _a, e_2, _b;
+        var _c;
+        // Runtime conflict detection (cast to access private fields)
+        var worldInstance = world;
+        if (worldInstance._getSystemCount() > 0) {
+            worldInstance._warnAboutLifecycleConflict("Schedule.run");
+        }
+        var phases = (_c = phaseOrder !== null && phaseOrder !== void 0 ? phaseOrder : this.phaseOrder) !== null && _c !== void 0 ? _c : this._computePhaseOrder(world);
+        if (!phases || phases.length === 0) {
+            throw new Error('Schedule.run requires a phase order (pass it as an argument or call schedule.setOrder([...]))');
+        }
+        var frameStart = worldInstance._profBeginFrame(dt);
         try {
-            for (var phaseOrder_1 = __values(phaseOrder), phaseOrder_1_1 = phaseOrder_1.next(); !phaseOrder_1_1.done; phaseOrder_1_1 = phaseOrder_1.next()) {
-                var phase = phaseOrder_1_1.value;
-                var list = this.phases.get(phase);
-                if (!list)
-                    continue;
-                try {
-                    for (var list_1 = (e_2 = void 0, __values(list)), list_1_1 = list_1.next(); !list_1_1.done; list_1_1 = list_1.next()) {
-                        var fn = list_1_1.value;
+            try {
+                for (var phases_1 = __values(phases), phases_1_1 = phases_1.next(); !phases_1_1.done; phases_1_1 = phases_1.next()) {
+                    var phase = phases_1_1.value;
+                    var phaseStart = performance.now();
+                    var list = world._scheduleSystems.get(phase);
+                    // Run systems only if they exist for this phase
+                    if (list) {
                         try {
-                            fn(world, dt);
+                            for (var list_1 = (e_2 = void 0, __values(list)), list_1_1 = list_1.next(); !list_1_1.done; list_1_1 = list_1.next()) {
+                                var fn = list_1_1.value;
+                                var sysStart = performance.now();
+                                try {
+                                    fn(world, dt);
+                                }
+                                catch (error) {
+                                    var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
+                                    var msg = error.message !== undefined && typeof error.message === 'string' ?
+                                        error.message : JSON.stringify(error);
+                                    var e = new Error("[phase=".concat(phase, " system=").concat(sysName, "] ").concat(msg));
+                                    e.cause = error;
+                                    throw e;
+                                }
+                                finally {
+                                    var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
+                                    worldInstance._profAddSystem("".concat(phase, ":").concat(sysName), performance.now() - sysStart);
+                                }
+                            }
                         }
-                        catch (error) {
-                            var sysName = fn.name && fn.name.length > 0 ? fn.name : "<anonymous>";
-                            var msg = error.message !== undefined && typeof 'string' ? error.message : JSON.stringify(error);
-                            var e = new Error("[phase=".concat(phase, " system=").concat(sysName, "] ").concat(msg));
-                            e.cause = error;
-                            throw e;
+                        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                        finally {
+                            try {
+                                if (list_1_1 && !list_1_1.done && (_b = list_1.return)) _b.call(list_1);
+                            }
+                            finally { if (e_2) throw e_2.error; }
                         }
                     }
+                    if (this.boundaryMode !== "manual") {
+                        // apply deferred commands between phases
+                        if (world.cmd().hasPending()) {
+                            world.flush();
+                        }
+                        // deliver events emitted in this phase to the next phase
+                        world.swapEvents();
+                    }
+                    worldInstance._profAddPhase(phase, performance.now() - phaseStart);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (phases_1_1 && !phases_1_1.done && (_a = phases_1.return)) _a.call(phases_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        finally {
+            worldInstance._profEndFrame(frameStart);
+            worldInstance.updateOverlay(worldInstance.stats(), worldInstance.statsHistory());
+        }
+    };
+    /**
+     * Record a phase ordering constraint `before -> after`.
+     *
+     * @param before Phase that must execute first.
+     * @param after Phase that must execute later.
+     *
+     * @throws If `before === after`.
+     * @internal
+     */
+    Schedule.prototype._addPhaseConstraint = function (before, after) {
+        if (before === after) {
+            throw new Error("Invalid phase constraint: \"".concat(before, "\" cannot be before/after itself."));
+        }
+        var outs = this.phaseEdges.get(before);
+        if (!outs) {
+            outs = new Set();
+            this.phaseEdges.set(before, outs);
+        }
+        outs.add(after);
+    };
+    /**
+     * Compute a phase order from the currently registered constraints.
+     *
+     * Uses a stable topological sort:
+     * - phases explicitly registered via `add()` keep insertion order when unconstrained
+     * - remaining ties fall back to lexicographic order
+     *
+     * @param world World instance to get phases from.
+     * @returns A valid phase order that satisfies all constraints.
+     * @throws If constraints contain a cycle.
+     * @internal
+     */
+    Schedule.prototype._computePhaseOrder = function (world) {
+        var e_3, _a, e_4, _b, e_5, _c, e_6, _d, e_7, _e, e_8, _f, e_9, _g, e_10, _h, e_11, _j;
+        var _k, _l;
+        var phases = world._scheduleSystems;
+        // Collect all known phases (defined or referenced by constraints)
+        var all = new Set();
+        try {
+            for (var _m = __values(phases.keys()), _o = _m.next(); !_o.done; _o = _m.next()) {
+                var k = _o.value;
+                all.add(k);
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_o && !_o.done && (_a = _m.return)) _a.call(_m);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        try {
+            for (var _p = __values(this.phaseEdges), _q = _p.next(); !_q.done; _q = _p.next()) {
+                var _r = __read(_q.value, 2), a = _r[0], bs = _r[1];
+                all.add(a);
+                try {
+                    for (var bs_1 = (e_5 = void 0, __values(bs)), bs_1_1 = bs_1.next(); !bs_1_1.done; bs_1_1 = bs_1.next()) {
+                        var b = bs_1_1.value;
+                        all.add(b);
+                    }
                 }
-                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                catch (e_5_1) { e_5 = { error: e_5_1 }; }
                 finally {
                     try {
-                        if (list_1_1 && !list_1_1.done && (_b = list_1.return)) _b.call(list_1);
+                        if (bs_1_1 && !bs_1_1.done && (_c = bs_1.return)) _c.call(bs_1);
                     }
-                    finally { if (e_2) throw e_2.error; }
+                    finally { if (e_5) throw e_5.error; }
                 }
-                // apply deferred commands between phases
-                if (world.cmd().hasPending()) {
-                    world.flush();
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_q && !_q.done && (_b = _p.return)) _b.call(_p);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+        // Stable tie-breaker: insertion order of phase registration (then lexicographic fallback)
+        var stableRank = new Map();
+        var r = 0;
+        try {
+            for (var _s = __values(phases.keys()), _t = _s.next(); !_t.done; _t = _s.next()) {
+                var k = _t.value;
+                stableRank.set(k, r++);
+            }
+        }
+        catch (e_6_1) { e_6 = { error: e_6_1 }; }
+        finally {
+            try {
+                if (_t && !_t.done && (_d = _s.return)) _d.call(_s);
+            }
+            finally { if (e_6) throw e_6.error; }
+        }
+        var rank = function (p) { var _a; return (_a = stableRank.get(p)) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER; };
+        // Build indegree + adjacency
+        var indeg = new Map();
+        var adj = new Map();
+        try {
+            for (var all_1 = __values(all), all_1_1 = all_1.next(); !all_1_1.done; all_1_1 = all_1.next()) {
+                var p = all_1_1.value;
+                indeg.set(p, 0);
+                adj.set(p, new Set());
+            }
+        }
+        catch (e_7_1) { e_7 = { error: e_7_1 }; }
+        finally {
+            try {
+                if (all_1_1 && !all_1_1.done && (_e = all_1.return)) _e.call(all_1);
+            }
+            finally { if (e_7) throw e_7.error; }
+        }
+        try {
+            for (var _u = __values(this.phaseEdges), _v = _u.next(); !_v.done; _v = _u.next()) {
+                var _w = __read(_v.value, 2), a = _w[0], bs = _w[1];
+                var _out = adj.get(a);
+                try {
+                    for (var bs_2 = (e_9 = void 0, __values(bs)), bs_2_1 = bs_2.next(); !bs_2_1.done; bs_2_1 = bs_2.next()) {
+                        var b = bs_2_1.value;
+                        if (!_out.has(b)) {
+                            _out.add(b);
+                            indeg.set(b, ((_k = indeg.get(b)) !== null && _k !== void 0 ? _k : 0) + 1);
+                        }
+                    }
+                }
+                catch (e_9_1) { e_9 = { error: e_9_1 }; }
+                finally {
+                    try {
+                        if (bs_2_1 && !bs_2_1.done && (_g = bs_2.return)) _g.call(bs_2);
+                    }
+                    finally { if (e_9) throw e_9.error; }
                 }
-                // deliver events emitted in this phase to the next phase
-                world.swapEvents();
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        catch (e_8_1) { e_8 = { error: e_8_1 }; }
+        finally {
+            try {
+                if (_v && !_v.done && (_f = _u.return)) _f.call(_u);
+            }
+            finally { if (e_8) throw e_8.error; }
+        }
+        // Kahn's algorithm with stable ordering
+        var ready = [];
+        try {
+            for (var indeg_1 = __values(indeg), indeg_1_1 = indeg_1.next(); !indeg_1_1.done; indeg_1_1 = indeg_1.next()) {
+                var _x = __read(indeg_1_1.value, 2), p = _x[0], d = _x[1];
+                if (d === 0)
+                    ready.push(p);
+            }
+        }
+        catch (e_10_1) { e_10 = { error: e_10_1 }; }
         finally {
             try {
-                if (phaseOrder_1_1 && !phaseOrder_1_1.done && (_a = phaseOrder_1.return)) _a.call(phaseOrder_1);
+                if (indeg_1_1 && !indeg_1_1.done && (_h = indeg_1.return)) _h.call(indeg_1);
             }
-            finally { if (e_1) throw e_1.error; }
+            finally { if (e_10) throw e_10.error; }
+        }
+        ready.sort(function (x, y) { return rank(x) - rank(y) || x.localeCompare(y); });
+        var out = [];
+        while (ready.length > 0) {
+            var p = ready.shift();
+            out.push(p);
+            try {
+                for (var _y = (e_11 = void 0, __values(adj.get(p))), _z = _y.next(); !_z.done; _z = _y.next()) {
+                    var q = _z.value;
+                    var nd = ((_l = indeg.get(q)) !== null && _l !== void 0 ? _l : 0) - 1;
+                    indeg.set(q, nd);
+                    if (nd === 0) {
+                        ready.push(q);
+                        ready.sort(function (x, y) { return rank(x) - rank(y) || x.localeCompare(y); });
+                    }
+                }
+            }
+            catch (e_11_1) { e_11 = { error: e_11_1 }; }
+            finally {
+                try {
+                    if (_z && !_z.done && (_j = _y.return)) _j.call(_y);
+                }
+                finally { if (e_11) throw e_11.error; }
+            }
+        }
+        if (out.length !== all.size) {
+            // Find a cycle-friendly message
+            var stuck = __spreadArray([], __read(all), false).filter(function (p) { var _a; return ((_a = indeg.get(p)) !== null && _a !== void 0 ? _a : 0) > 0; }).sort();
+            throw new Error("Schedule phase constraints contain a cycle (cannot compute order). " +
+                "Phases involved: ".concat(stuck.join(", ")));
         }
+        return out;
     };
     return Schedule;
 }());

package/lib/ecs/Types.d.ts

@@ -10,9 +10,13 @@ export type EntityMeta = {
     arch: number;
     row: number;
 };
-export type Column<T = unknown> = T[];
+export type Column<T = any> = T[];
 export type Signature = ReadonlyArray<TypeId>;
-export type ComponentCtor<T> = new (...args: any[]) => T;
+/**
+ * Component/resource token used as an identity key.
+ * Supports class constructors and plain function tokens.
+ */
+export type ComponentCtor<T> = (new (...args: any[]) => T) | ((...args: any[]) => T);
 export type ComponentCtorBundleItem<T = any> = readonly [ComponentCtor<T>, T];
 /**
  * Internal numeric id for a component "type".
@@ -20,6 +24,39 @@ export type ComponentCtorBundleItem<T = any> = readonly [ComponentCtor<T>, T];
  */
 export type TypeId = number;
 export type SystemFn = (world: WorldApi, dt: number) => void;
+export type SnapshotCodec<T, D = unknown> = Readonly<{
+    /**
+     * Stable key written into the snapshot payload.
+     * Keep this string stable across versions for backward compatibility.
+     */
+    key: string;
+    serialize(value: T): D;
+    deserialize(data: D): T;
+}>;
+export type WorldSnapshotComponent = Readonly<{
+    type: string;
+    data: unknown;
+}>;
+export type WorldSnapshotEntity = Readonly<{
+    id: EntityId;
+    gen: number;
+    components: ReadonlyArray<WorldSnapshotComponent>;
+}>;
+export type WorldSnapshotResource = Readonly<{
+    type: string;
+    data: unknown;
+}>;
+export type WorldSnapshotAllocator = Readonly<{
+    nextId: EntityId;
+    free: ReadonlyArray<EntityId>;
+    generations: ReadonlyArray<readonly [EntityId, number]>;
+}>;
+export type WorldSnapshot = Readonly<{
+    format: "archetype-ecs/world-snapshot@1";
+    allocator: WorldSnapshotAllocator;
+    entities: ReadonlyArray<WorldSnapshotEntity>;
+    resources: ReadonlyArray<WorldSnapshotResource>;
+}>;
 /**
  * Commands API exposed to systems.
  * > Hides internal stuff like `drain()`
@@ -74,13 +111,99 @@ export type QueryRow6<A, B, C, D, E, F> = {
     c5: E;
     c6: F;
 };
+export type QueryTable1<A> = {
+    entities: Entity[];
+    c1: Column<A>;
+};
+export type QueryTable2<A, B> = {
+    entities: Entity[];
+    c1: Column<A>;
+    c2: Column<B>;
+};
+export type QueryTable3<A, B, C> = {
+    entities: Entity[];
+    c1: Column<A>;
+    c2: Column<B>;
+    c3: Column<C>;
+};
+export type QueryTable4<A, B, C, D> = {
+    entities: Entity[];
+    c1: Column<A>;
+    c2: Column<B>;
+    c3: Column<C>;
+    c4: Column<D>;
+};
+export type QueryTable5<A, B, C, D, E> = {
+    entities: Entity[];
+    c1: Column<A>;
+    c2: Column<B>;
+    c3: Column<C>;
+    c4: Column<D>;
+    c5: Column<E>;
+};
+export type QueryTable6<A, B, C, D, E, F> = {
+    entities: Entity[];
+    c1: Column<A>;
+    c2: Column<B>;
+    c3: Column<C>;
+    c4: Column<D>;
+    c5: Column<E>;
+    c6: Column<F>;
+};
+export type WorldStats = Readonly<{
+    aliveEntities: number;
+    archetypes: number;
+    rows: number;
+    systems: number;
+    resources: number;
+    eventChannels: number;
+    pendingCommands: boolean;
+    frame: number;
+    dt: number;
+    frameMs: number;
+    phaseMs: Readonly<Record<string, number>>;
+    systemMs: Readonly<Record<string, number>>;
+}>;
+export type WorldStatsHistory = Readonly<{
+    /** Max frames kept in history (ring-buffer window). */
+    capacity: number;
+    /** How many samples are currently stored (<= capacity). */
+    size: number;
+    /** Rolling history for overall timing. */
+    dt: ReadonlyArray<number>;
+    frameMs: ReadonlyArray<number>;
+    /**
+     * Rolling history per phase/system.
+     * Arrays align with dt/frameMs indices (same `size`).
+     */
+    phaseMs: Readonly<Record<string, ReadonlyArray<number>>>;
+    systemMs: Readonly<Record<string, ReadonlyArray<number>>>;
+}>;
 /**
  * Public World API visible from system functions.
  * Structural typing keeps typings fast and avoids generic plumbing across the whole library.
  */
 export interface WorldApi {
+    stats(): WorldStats;
+    statsHistory(): WorldStatsHistory;
+    /** @internal Phase -> systems mapping for Schedule */
+    readonly _scheduleSystems: Map<string, SystemFn[]>;
+    /** @internal Returns the number of systems registered via addSystem() */
+    _getSystemCount(): number;
+    /** Enables/disables profiling (system/phase timing). */
+    setProfilingEnabled(enabled: boolean): void;
+    /** Set how many frames of the profiling history to keep (default: 120). */
+    setProfilingHistorySize(frames: number): void;
     cmd(): CommandsApi;
+    addSystem(fn: SystemFn): this;
+    update(dt: number): void;
     flush(): void;
+    registerComponentSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
+    unregisterComponentSnapshot<T>(key: ComponentCtor<T>): boolean;
+    registerResourceSnapshot<T, D = unknown>(key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): this;
+    unregisterResourceSnapshot<T>(key: ComponentCtor<T>): boolean;
+    snapshot(): WorldSnapshot;
+    restore(snapshot: WorldSnapshot): void;
     /**
      * Insert or replace a resource (singleton) stored on the World, keyed by ctor.
      * This is NOT a structural change (safe during iteration).
@@ -131,7 +254,7 @@ export interface WorldApi {
      */
     swapEvents(): void;
     spawn(): Entity;
-    spawnMany(...items: ComponentCtorBundleItem[]): void;
+    spawnMany(...items: ComponentCtorBundleItem[]): Entity;
     despawn(e: Entity): void;
     despawnMany(entities: Entity[]): void;
     isAlive(e: Entity): boolean;
@@ -149,4 +272,18 @@ export interface WorldApi {
     query<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryRow5<A, B, C, D, E>>;
     query<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryRow6<A, B, C, D, E, F>>;
     query(...ctors: ComponentCtor<any>[]): Iterable<any>;
+    queryTables<A>(c1: ComponentCtor<A>): Iterable<QueryTable1<A>>;
+    queryTables<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>): Iterable<QueryTable2<A, B>>;
+    queryTables<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>): Iterable<QueryTable3<A, B, C>>;
+    queryTables<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>): Iterable<QueryTable4<A, B, C, D>>;
+    queryTables<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>): Iterable<QueryTable5<A, B, C, D, E>>;
+    queryTables<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>): Iterable<QueryTable6<A, B, C, D, E, F>>;
+    queryTables(...ctors: ComponentCtor<any>[]): Iterable<any>;
+    queryEach<A>(c1: ComponentCtor<A>, fn: (e: Entity, c1: A) => void): void;
+    queryEach<A, B>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, fn: (e: Entity, c1: A, c2: B) => void): void;
+    queryEach<A, B, C>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, fn: (e: Entity, c1: A, c2: B, c3: C) => void): void;
+    queryEach<A, B, C, D>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D) => void): void;
+    queryEach<A, B, C, D, E>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E) => void): void;
+    queryEach<A, B, C, D, E, F>(c1: ComponentCtor<A>, c2: ComponentCtor<B>, c3: ComponentCtor<C>, c4: ComponentCtor<D>, c5: ComponentCtor<E>, c6: ComponentCtor<F>, fn: (e: Entity, c1: A, c2: B, c3: C, c4: D, c5: E, c6: F) => void): void;
+    queryEach(...args: any[]): void;
 }