archetype-ecs-lib 0.5.0 → 0.6.0

package/lib/ecs/Archetype.js

@@ -74,7 +74,7 @@ var Archetype = /** @class */ (function () {
             this.entities.pop();
             try {
                 for (var _c = __values(this.cols), _d = _c.next(); !_d.done; _d = _c.next()) {
-                    var _e = __read(_d.value, 2), _ = _e[0], col = _e[1];
+                    var _e = __read(_d.value, 2), col = _e[1];
                     col[row] = col[last];
                     col.pop();
                 }

package/lib/ecs/EntityManager.d.ts

@@ -1,4 +1,4 @@
-import type { Entity, EntityMeta } from "./Types";
+import type { Entity, EntityMeta, WorldSnapshotAllocator } from "./Types";
 export declare class EntityManager {
     private _nextId;
     private _free;
@@ -6,4 +6,6 @@ export declare class EntityManager {
     create(): Entity;
     isAlive(e: Entity): boolean;
     kill(e: Entity): void;
+    snapshotAllocator(): WorldSnapshotAllocator;
+    restoreAllocator(snapshot: WorldSnapshotAllocator): void;
 }

package/lib/ecs/EntityManager.js

@@ -1,4 +1,15 @@
 "use strict";
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityManager = void 0;
 var EntityManager = /** @class */ (function () {
@@ -33,6 +44,84 @@ var EntityManager = /** @class */ (function () {
         m.alive = false;
         this._free.push(e.id);
     };
+    EntityManager.prototype.snapshotAllocator = function () {
+        var generations = [];
+        for (var id = 1; id < this.meta.length; id++) {
+            var m = this.meta[id];
+            if (!m)
+                continue;
+            generations.push([id, m.gen]);
+        }
+        return {
+            nextId: this._nextId,
+            free: this._free.slice(),
+            generations: generations
+        };
+    };
+    EntityManager.prototype.restoreAllocator = function (snapshot) {
+        var e_1, _a, e_2, _b;
+        if (!Number.isInteger(snapshot.nextId) || snapshot.nextId < 1) {
+            throw new Error("Invalid snapshot allocator.nextId: ".concat(snapshot.nextId));
+        }
+        var seenGenerations = new Set();
+        this.meta.length = 0;
+        try {
+            for (var _c = __values(snapshot.generations), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var entry = _d.value;
+                var id = entry[0];
+                var gen = entry[1];
+                if (!Number.isInteger(id) || id <= 0) {
+                    throw new Error("Invalid snapshot allocator generations id: ".concat(id));
+                }
+                if (!Number.isInteger(gen) || gen <= 0) {
+                    throw new Error("Invalid snapshot allocator generation for id ".concat(id, ": ").concat(gen));
+                }
+                if (id >= snapshot.nextId) {
+                    throw new Error("Invalid snapshot allocator generation id ".concat(id, ": must be < nextId (").concat(snapshot.nextId, ")"));
+                }
+                if (seenGenerations.has(id)) {
+                    throw new Error("Duplicate snapshot allocator generation entry for id ".concat(id));
+                }
+                seenGenerations.add(id);
+                this.meta[id] = { gen: gen, alive: false, arch: 0, row: 0 };
+            }
+        }
+        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 seenFree = new Set();
+        try {
+            for (var _e = __values(snapshot.free), _f = _e.next(); !_f.done; _f = _e.next()) {
+                var id = _f.value;
+                if (!Number.isInteger(id) || id <= 0) {
+                    throw new Error("Invalid snapshot allocator free id: ".concat(id));
+                }
+                if (id >= snapshot.nextId) {
+                    throw new Error("Invalid snapshot allocator free id ".concat(id, ": must be < nextId (").concat(snapshot.nextId, ")"));
+                }
+                if (!seenGenerations.has(id)) {
+                    throw new Error("Invalid snapshot allocator free id ".concat(id, ": missing generation entry"));
+                }
+                if (seenFree.has(id)) {
+                    throw new Error("Duplicate snapshot allocator free id ".concat(id));
+                }
+                seenFree.add(id);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        this._nextId = snapshot.nextId;
+        this._free = snapshot.free.slice();
+    };
     return EntityManager;
 }());
 exports.EntityManager = EntityManager;

package/lib/ecs/Schedule.d.ts

@@ -1,10 +1,133 @@
 import type { SystemFn, WorldApi } from "./Types";
 /**
- * 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);
+ * ```
  */
 export declare class Schedule {
-    private readonly phases;
-    add(phase: string, fn: SystemFn): this;
-    run(world: WorldApi, dt: number, phaseOrder: string[]): void;
+    private phaseOrder;
+    private boundaryMode;
+    /**
+     * Phase ordering constraints stored as edges `before -> after`.
+     * Example: calling `after("input")` for phase `"sim"` records `input -> sim`.
+     */
+    private readonly phaseEdges;
+    /**
+     * Tracks the most recently modified phase (via add()) so `.after()`/`.before()` can be chained.
+     */
+    private _lastPhase;
+    /**
+     * Set a default phase order used when calling `run(world, dt)` without passing `phaseOrder`.
+     *
+     * @param phases Ordered list of phase names to execute.
+     */
+    setOrder(phases: string[]): 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.
+     */
+    setBoundaryMode(mode: "auto" | "manual"): 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`.
+     */
+    add(world: WorldApi, phase: string, fn: SystemFn): {
+        after: (otherPhase: string) => Schedule;
+        before: (otherPhase: string) => Schedule;
+    };
+    /**
+     * Constrain the last added phase to run after `otherPhase`.
+     *
+     * Must be called after `add(...)`.
+     */
+    after(otherPhase: string): this;
+    /**
+     * Constrain the last added phase to run before `otherPhase`.
+     *
+     * Must be called after `add(...)`.
+     */
+    before(otherPhase: string): 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.
+     */
+    run(world: WorldApi, dt: number, phaseOrder?: string[]): void;
+    /**
+     * 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
+     */
+    private _addPhaseConstraint;
+    /**
+     * 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
+     */
+    private _computePhaseOrder;
 }