archetype-ecs-lib 0.5.0 → 0.6.1

package/lib/ecs/WorldSnapshotStore.d.ts

@@ -0,0 +1,30 @@
+import { Archetype } from "./Archetype";
+import { Commands } from "./Commands";
+import { EntityManager } from "./EntityManager";
+import { EventChannel } from "./Events";
+import type { ComponentCtor, Signature, SnapshotCodec, WorldSnapshot } from "./Types";
+export type WorldSnapshotRuntime = Readonly<{
+    ensureNotIterating(op: string): void;
+    formatCtor(ctor: ComponentCtor<any>): string;
+    flush(): void;
+    resetArchetypes(): void;
+    getOrCreateArchetype(sig: Signature): Archetype;
+    commands: Commands;
+    entities: EntityManager;
+    archetypes: Archetype[];
+    resources: Map<ComponentCtor<any>, any>;
+    eventChannels: Map<ComponentCtor<any>, EventChannel<any>>;
+}>;
+export declare class WorldSnapshotStore {
+    private readonly componentSnapshotByCtor;
+    private readonly componentSnapshotCtorByKey;
+    private readonly resourceSnapshotByCtor;
+    private readonly resourceSnapshotCtorByKey;
+    registerComponentSnapshot<T, D = unknown>(runtime: Pick<WorldSnapshotRuntime, "formatCtor">, key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): void;
+    unregisterComponentSnapshot<T>(key: ComponentCtor<T>): boolean;
+    registerResourceSnapshot<T, D = unknown>(runtime: Pick<WorldSnapshotRuntime, "formatCtor">, key: ComponentCtor<T>, codec: SnapshotCodec<T, D>): void;
+    unregisterResourceSnapshot<T>(key: ComponentCtor<T>): boolean;
+    snapshot(runtime: Pick<WorldSnapshotRuntime, "ensureNotIterating" | "flush" | "commands" | "archetypes" | "entities" | "resources">): WorldSnapshot;
+    restore(runtime: Pick<WorldSnapshotRuntime, "ensureNotIterating" | "commands" | "eventChannels" | "resources" | "entities" | "resetArchetypes" | "getOrCreateArchetype">, snapshot: WorldSnapshot): void;
+    private _normalizeSnapshotKey;
+}

package/lib/ecs/WorldSnapshotStore.js

@@ -0,0 +1,339 @@
+"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.");
+};
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorldSnapshotStore = void 0;
+var TypeRegistry_1 = require("./TypeRegistry");
+var WORLD_SNAPSHOT_FORMAT = "archetype-ecs/world-snapshot@1";
+var WorldSnapshotStore = /** @class */ (function () {
+    function WorldSnapshotStore() {
+        this.componentSnapshotByCtor = new Map();
+        this.componentSnapshotCtorByKey = new Map();
+        this.resourceSnapshotByCtor = new Map();
+        this.resourceSnapshotCtorByKey = new Map();
+    }
+    WorldSnapshotStore.prototype.registerComponentSnapshot = function (runtime, key, codec) {
+        var snapshotKey = this._normalizeSnapshotKey(codec.key, "component");
+        var existingCtor = this.componentSnapshotCtorByKey.get(snapshotKey);
+        if (existingCtor && existingCtor !== key) {
+            throw new Error("registerComponentSnapshot(".concat(snapshotKey, ") failed: key already used by ").concat(runtime.formatCtor(existingCtor)));
+        }
+        var prev = this.componentSnapshotByCtor.get(key);
+        if (prev && prev.key !== snapshotKey)
+            this.componentSnapshotCtorByKey.delete(prev.key);
+        this.componentSnapshotByCtor.set(key, {
+            key: snapshotKey,
+            tid: (0, TypeRegistry_1.typeId)(key),
+            serialize: function (value) { return codec.serialize(value); },
+            deserialize: function (data) { return codec.deserialize(data); }
+        });
+        this.componentSnapshotCtorByKey.set(snapshotKey, key);
+    };
+    WorldSnapshotStore.prototype.unregisterComponentSnapshot = function (key) {
+        var prev = this.componentSnapshotByCtor.get(key);
+        if (!prev)
+            return false;
+        this.componentSnapshotByCtor.delete(key);
+        this.componentSnapshotCtorByKey.delete(prev.key);
+        return true;
+    };
+    WorldSnapshotStore.prototype.registerResourceSnapshot = function (runtime, key, codec) {
+        var snapshotKey = this._normalizeSnapshotKey(codec.key, "resource");
+        var existingCtor = this.resourceSnapshotCtorByKey.get(snapshotKey);
+        if (existingCtor && existingCtor !== key) {
+            throw new Error("registerResourceSnapshot(".concat(snapshotKey, ") failed: key already used by ").concat(runtime.formatCtor(existingCtor)));
+        }
+        var prev = this.resourceSnapshotByCtor.get(key);
+        if (prev && prev.key !== snapshotKey)
+            this.resourceSnapshotCtorByKey.delete(prev.key);
+        this.resourceSnapshotByCtor.set(key, {
+            key: snapshotKey,
+            serialize: function (value) { return codec.serialize(value); },
+            deserialize: function (data) { return codec.deserialize(data); }
+        });
+        this.resourceSnapshotCtorByKey.set(snapshotKey, key);
+    };
+    WorldSnapshotStore.prototype.unregisterResourceSnapshot = function (key) {
+        var prev = this.resourceSnapshotByCtor.get(key);
+        if (!prev)
+            return false;
+        this.resourceSnapshotByCtor.delete(key);
+        this.resourceSnapshotCtorByKey.delete(prev.key);
+        return true;
+    };
+    WorldSnapshotStore.prototype.snapshot = function (runtime) {
+        var e_1, _a, e_2, _b, e_3, _c, e_4, _d, e_5, _e;
+        var _f;
+        runtime.ensureNotIterating("snapshot");
+        if (runtime.commands.hasPending())
+            runtime.flush();
+        var componentRegs = [];
+        try {
+            for (var _g = __values(this.componentSnapshotByCtor), _h = _g.next(); !_h.done; _h = _g.next()) {
+                var _j = __read(_h.value, 2), reg = _j[1];
+                componentRegs.push(reg);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_h && !_h.done && (_a = _g.return)) _a.call(_g);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        componentRegs.sort(function (a, b) { return a.key.localeCompare(b.key); });
+        var serializedColumnsByArch = new Map();
+        try {
+            for (var _k = __values(runtime.archetypes), _l = _k.next(); !_l.done; _l = _k.next()) {
+                var a = _l.value;
+                if (!a)
+                    continue;
+                var cols = [];
+                try {
+                    for (var componentRegs_1 = (e_3 = void 0, __values(componentRegs)), componentRegs_1_1 = componentRegs_1.next(); !componentRegs_1_1.done; componentRegs_1_1 = componentRegs_1.next()) {
+                        var reg = componentRegs_1_1.value;
+                        if (!a.has(reg.tid))
+                            continue;
+                        cols.push({
+                            type: reg.key,
+                            column: a.column(reg.tid),
+                            serialize: reg.serialize
+                        });
+                    }
+                }
+                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                finally {
+                    try {
+                        if (componentRegs_1_1 && !componentRegs_1_1.done && (_c = componentRegs_1.return)) _c.call(componentRegs_1);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                }
+                serializedColumnsByArch.set(a.id, cols);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_l && !_l.done && (_b = _k.return)) _b.call(_k);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        var entities = [];
+        for (var id = 1; id < runtime.entities.meta.length; id++) {
+            var m = runtime.entities.meta[id];
+            if (!m || !m.alive)
+                continue;
+            var cols = (_f = serializedColumnsByArch.get(m.arch)) !== null && _f !== void 0 ? _f : [];
+            var components = new Array(cols.length);
+            for (var i = 0; i < cols.length; i++) {
+                var c = cols[i];
+                components[i] = {
+                    type: c.type,
+                    data: c.serialize(c.column[m.row])
+                };
+            }
+            entities.push({ id: id, gen: m.gen, components: components });
+        }
+        var resourceRegs = [];
+        try {
+            for (var _m = __values(this.resourceSnapshotByCtor), _o = _m.next(); !_o.done; _o = _m.next()) {
+                var _p = __read(_o.value, 2), ctor = _p[0], reg = _p[1];
+                resourceRegs.push({ ctor: ctor, reg: reg });
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_o && !_o.done && (_d = _m.return)) _d.call(_m);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+        resourceRegs.sort(function (a, b) { return a.reg.key.localeCompare(b.reg.key); });
+        var resources = [];
+        try {
+            for (var resourceRegs_1 = __values(resourceRegs), resourceRegs_1_1 = resourceRegs_1.next(); !resourceRegs_1_1.done; resourceRegs_1_1 = resourceRegs_1.next()) {
+                var entry = resourceRegs_1_1.value;
+                if (!runtime.resources.has(entry.ctor))
+                    continue;
+                resources.push({
+                    type: entry.reg.key,
+                    data: entry.reg.serialize(runtime.resources.get(entry.ctor))
+                });
+            }
+        }
+        catch (e_5_1) { e_5 = { error: e_5_1 }; }
+        finally {
+            try {
+                if (resourceRegs_1_1 && !resourceRegs_1_1.done && (_e = resourceRegs_1.return)) _e.call(resourceRegs_1);
+            }
+            finally { if (e_5) throw e_5.error; }
+        }
+        return {
+            format: WORLD_SNAPSHOT_FORMAT,
+            allocator: runtime.entities.snapshotAllocator(),
+            entities: entities,
+            resources: resources
+        };
+    };
+    WorldSnapshotStore.prototype.restore = function (runtime, snapshot) {
+        var e_6, _a, e_7, _b, e_8, _c, e_9, _d, e_10, _e;
+        runtime.ensureNotIterating("restore");
+        if (snapshot.format !== WORLD_SNAPSHOT_FORMAT) {
+            throw new Error("Unsupported world snapshot format \"".concat(snapshot.format, "\". ") +
+                "Expected \"".concat(WORLD_SNAPSHOT_FORMAT, "\"."));
+        }
+        runtime.commands.drain();
+        try {
+            for (var _f = __values(runtime.eventChannels.values()), _g = _f.next(); !_g.done; _g = _f.next()) {
+                var ch = _g.value;
+                ch.clearAll();
+            }
+        }
+        catch (e_6_1) { e_6 = { error: e_6_1 }; }
+        finally {
+            try {
+                if (_g && !_g.done && (_a = _f.return)) _a.call(_f);
+            }
+            finally { if (e_6) throw e_6.error; }
+        }
+        runtime.resources.clear();
+        runtime.entities.restoreAllocator(snapshot.allocator);
+        runtime.resetArchetypes();
+        var seenResourceTypes = new Set();
+        try {
+            for (var _h = __values(snapshot.resources), _j = _h.next(); !_j.done; _j = _h.next()) {
+                var resource = _j.value;
+                if (seenResourceTypes.has(resource.type)) {
+                    throw new Error("Duplicate snapshot resource type \"".concat(resource.type, "\""));
+                }
+                seenResourceTypes.add(resource.type);
+                var ctor = this.resourceSnapshotCtorByKey.get(resource.type);
+                if (!ctor) {
+                    throw new Error("Missing resource snapshot codec for \"".concat(resource.type, "\". Register it before restore()."));
+                }
+                var reg = this.resourceSnapshotByCtor.get(ctor);
+                runtime.resources.set(ctor, reg.deserialize(resource.data));
+            }
+        }
+        catch (e_7_1) { e_7 = { error: e_7_1 }; }
+        finally {
+            try {
+                if (_j && !_j.done && (_b = _h.return)) _b.call(_h);
+            }
+            finally { if (e_7) throw e_7.error; }
+        }
+        var freeSet = new Set(snapshot.allocator.free);
+        var seenEntityIds = new Set();
+        try {
+            for (var _k = __values(snapshot.entities), _l = _k.next(); !_l.done; _l = _k.next()) {
+                var entity = _l.value;
+                if (!Number.isInteger(entity.id) || entity.id <= 0) {
+                    throw new Error("Invalid snapshot entity id: ".concat(entity.id));
+                }
+                if (!Number.isInteger(entity.gen) || entity.gen <= 0) {
+                    throw new Error("Invalid snapshot entity generation for id ".concat(entity.id, ": ").concat(entity.gen));
+                }
+                if (seenEntityIds.has(entity.id)) {
+                    throw new Error("Duplicate snapshot entity id ".concat(entity.id));
+                }
+                seenEntityIds.add(entity.id);
+                if (freeSet.has(entity.id)) {
+                    throw new Error("Invalid snapshot: entity id ".concat(entity.id, " is both alive and free"));
+                }
+                var meta = runtime.entities.meta[entity.id];
+                if (!meta) {
+                    throw new Error("Invalid snapshot: missing allocator generation entry for entity id ".concat(entity.id, ". ") +
+                        "Ensure snapshot.allocator.generations includes all alive ids.");
+                }
+                if (meta.gen !== entity.gen) {
+                    throw new Error("Invalid snapshot: allocator generation mismatch for entity id ".concat(entity.id, ". ") +
+                        "Expected gen ".concat(meta.gen, ", got ").concat(entity.gen, "."));
+                }
+                var componentValues = new Map();
+                var seenComponentTypes = new Set();
+                try {
+                    for (var _m = (e_9 = void 0, __values(entity.components)), _o = _m.next(); !_o.done; _o = _m.next()) {
+                        var component = _o.value;
+                        if (seenComponentTypes.has(component.type)) {
+                            throw new Error("Duplicate component type \"".concat(component.type, "\" on entity ").concat(entity.id));
+                        }
+                        seenComponentTypes.add(component.type);
+                        var ctor = this.componentSnapshotCtorByKey.get(component.type);
+                        if (!ctor) {
+                            throw new Error("Missing component snapshot codec for \"".concat(component.type, "\". Register it before restore()."));
+                        }
+                        var reg = this.componentSnapshotByCtor.get(ctor);
+                        componentValues.set(reg.tid, reg.deserialize(component.data));
+                    }
+                }
+                catch (e_9_1) { e_9 = { error: e_9_1 }; }
+                finally {
+                    try {
+                        if (_o && !_o.done && (_d = _m.return)) _d.call(_m);
+                    }
+                    finally { if (e_9) throw e_9.error; }
+                }
+                var sig = Array.from(componentValues.keys()).sort(function (a, b) { return a - b; });
+                var a = runtime.getOrCreateArchetype(sig);
+                var row = a.addRow({ id: entity.id, gen: entity.gen });
+                try {
+                    for (var sig_1 = (e_10 = void 0, __values(sig)), sig_1_1 = sig_1.next(); !sig_1_1.done; sig_1_1 = sig_1.next()) {
+                        var t = sig_1_1.value;
+                        a.column(t).push(componentValues.get(t));
+                    }
+                }
+                catch (e_10_1) { e_10 = { error: e_10_1 }; }
+                finally {
+                    try {
+                        if (sig_1_1 && !sig_1_1.done && (_e = sig_1.return)) _e.call(sig_1);
+                    }
+                    finally { if (e_10) throw e_10.error; }
+                }
+                meta.alive = true;
+                meta.arch = a.id;
+                meta.row = row;
+            }
+        }
+        catch (e_8_1) { e_8 = { error: e_8_1 }; }
+        finally {
+            try {
+                if (_l && !_l.done && (_c = _k.return)) _c.call(_k);
+            }
+            finally { if (e_8) throw e_8.error; }
+        }
+    };
+    WorldSnapshotStore.prototype._normalizeSnapshotKey = function (key, kind) {
+        var normalized = key.trim();
+        if (normalized.length === 0) {
+            throw new Error("register".concat(kind === "component" ? "Component" : "Resource", "Snapshot() failed: codec.key must be a non-empty string"));
+        }
+        return normalized;
+    };
+    return WorldSnapshotStore;
+}());
+exports.WorldSnapshotStore = WorldSnapshotStore;

package/lib/ecs/stats/StatsOverlay.d.ts

@@ -0,0 +1,72 @@
+import type { WorldStats, WorldStatsHistory } from "../Types";
+export type StatsOverlayOptions = Readonly<{
+    /** Parent element to attach the overlay to. Defaults to document.body */
+    parent?: HTMLElement;
+    /** Fixed positioning offsets */
+    left?: number;
+    top?: number;
+    /** Canvas size */
+    width?: number;
+    height?: number;
+    /** Target frame timeline (ms). Defaults to 16.67 (60fps). */
+    targetFrameMs?: number;
+    /** Threshold where bars become "slow" (ms). Defaults to 20. */
+    slowFrameMs?: number;
+    /** How many history samples to render (uses world history capacity). */
+    maxSamples?: number;
+}>;
+export declare class StatsOverlay {
+    private root;
+    private header;
+    private toggleButton;
+    private debugToggleButton;
+    private content;
+    private text;
+    private canvas;
+    private ctx;
+    private opts;
+    private resizeObserver;
+    private isExpanded;
+    private debugLoggingEnabled;
+    private isInitialized;
+    private debugingEnabled;
+    protected _profilingEnabled: boolean;
+    protected _frameCounter: number;
+    protected _lastDt: number;
+    protected _lastFrameMs: number;
+    protected readonly _phaseMs: Map<string, number>;
+    protected readonly _systemMs: Map<string, number>;
+    protected _historyCapacity: number;
+    protected readonly _histDt: number[];
+    protected readonly _histFrameMs: number[];
+    protected readonly _histPhaseMs: Map<string, number[]>;
+    protected readonly _histSystemMs: Map<string, number[]>;
+    private isDragging;
+    private dragOffsetX;
+    private dragOffsetY;
+    constructor(options?: StatsOverlayOptions);
+    private initializeDom;
+    setDebugging(enabled: boolean): void;
+    setProfilingEnabled(enabled: boolean): void;
+    setProfilingHistorySize(frames: number): void;
+    protected _trimHistoryToCapacity(): void;
+    protected _pushSeriesFrame(series: Map<string, number[]>, current: Map<string, number>): void;
+    /** @internal Called by Schedule/World.update to start a new profiling frame */
+    _profBeginFrame(dt: number): number;
+    /** @internal Called by Schedule/World.update to end a new profiling frame */
+    _profEndFrame(frameStartMs: number): void;
+    /** @internal */
+    _profAddPhase(phase: string, ms: number): void;
+    /** @internal */
+    _profAddSystem(name: string, ms: number): void;
+    private createDebugToggleButton;
+    private toggleDebugLogging;
+    private setupDrag;
+    private resizeCanvas;
+    private toggle;
+    destroyOverlay(): void;
+    /** Convenience: call each frame */
+    updateOverlay(stats: WorldStats, statsHistory: WorldStatsHistory): void;
+    private render;
+    private drawFrameGraph;
+}