archetype-ecs-lib 0.4.1 → 0.5.0

package/lib/ecs/World.js

@@ -37,11 +37,28 @@ 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;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.World = void 0;
 var Archetype_1 = require("./Archetype");
 var Commands_1 = require("./Commands");
 var EntityManager_1 = require("./EntityManager");
+var Events_1 = require("./Events");
 var Signature_1 = require("./Signature");
 var TypeRegistry_1 = require("./TypeRegistry");
 var World = /** @class */ (function () {
@@ -51,14 +68,18 @@ var World = /** @class */ (function () {
         this.archByKey = new Map();
         this.systems = [];
         this.commands = new Commands_1.Commands();
-        this._isIterating = false;
+        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);
     }
     /** Queue structural changes to apply safely after systems run. */
-    World.prototype.cmd = function () { return this.commands; };
+    World.prototype.cmd = function () {
+        return this.commands;
+    };
     World.prototype.addSystem = function (fn) {
         this.systems.push(fn);
         return this;
@@ -70,7 +91,7 @@ var World = /** @class */ (function () {
      */
     World.prototype.update = function (dt) {
         var e_1, _a;
-        this._isIterating = true;
+        this._iterateDepth++;
         try {
             try {
                 for (var _b = __values(this.systems), _c = _b.next(); !_c.done; _c = _b.next()) {
@@ -87,27 +108,120 @@ var World = /** @class */ (function () {
             }
         }
         finally {
-            this._isIterating = false;
+            this._iterateDepth--;
             this.flush();
         }
     };
     World.prototype.flush = function () {
         var e_2, _a;
-        var ops = this.commands.drain();
+        this._ensureNotIterating("flush");
+        // Apply commands until 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()) {
+                    var op = ops_1_1.value;
+                    this._apply(op);
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_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; }
+            }
+        }
+    };
+    //#region ---------- Resources (singletons) ----------
+    World.prototype.setResource = function (key, value) {
+        this.resources.set(key, value);
+    };
+    World.prototype.getResource = function (key) {
+        if (!this.resources.has(key))
+            return undefined;
+        return this.resources.get(key);
+    };
+    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)."));
+        }
+        return this.resources.get(key);
+    };
+    World.prototype.hasResource = function (key) {
+        return this.resources.has(key);
+    };
+    World.prototype.removeResource = function (key) {
+        return this.resources.delete(key);
+    };
+    World.prototype.initResource = function (key, factory) {
+        if (this.resources.has(key))
+            return this.resources.get(key);
+        var value = factory();
+        this.resources.set(key, value);
+        return value;
+    };
+    //#endregion
+    //#region ---------- Events (phase-scoped) ----------
+    World.prototype.emit = function (key, ev) {
+        this._events(key).emit(ev);
+    };
+    World.prototype.events = function (key) {
+        return this._events(key);
+    };
+    World.prototype.drainEvents = function (key, fn) {
+        var ch = this.eventChannels.get(key);
+        if (!ch)
+            return;
+        ch.drain(fn);
+    };
+    World.prototype.clearEvents = function (key) {
+        var e_3, _a;
+        if (key) {
+            var ch = this.eventChannels.get(key);
+            if (!ch)
+                return;
+            ch.clear();
+            return;
+        }
         try {
-            for (var ops_1 = __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);
+            // clear all readable buffers
+            for (var _b = __values(this.eventChannels.values()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var ch = _c.value;
+                ch.clear();
             }
         }
-        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
         finally {
             try {
-                if (ops_1_1 && !ops_1_1.done && (_a = ops_1.return)) _a.call(ops_1);
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_2) throw e_2.error; }
+            finally { if (e_3) throw e_3.error; }
         }
     };
+    /** @internal Called by Schedule at phase boundaries */
+    World.prototype.swapEvents = function () {
+        var e_4, _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 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+    };
+    //#endregion
     //#region ---------- Entity lifecycle ----------
     World.prototype.spawn = function () {
         var entity = this.entities.create();
@@ -119,16 +233,53 @@ var World = /** @class */ (function () {
         entityMeta.row = row;
         return entity;
     };
+    World.prototype.spawnMany = function () {
+        var e_5, _a;
+        var items = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            items[_i] = arguments[_i];
+        }
+        var e = this.spawn();
+        try {
+            for (var items_1 = __values(items), items_1_1 = items_1.next(); !items_1_1.done; items_1_1 = items_1.next()) {
+                var _b = __read(items_1_1.value, 2), ctor = _b[0], value = _b[1];
+                this.add(e, ctor, value);
+            }
+        }
+        catch (e_5_1) { e_5 = { error: e_5_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; }
+        }
+        return e;
+    };
     World.prototype.isAlive = function (e) {
         return this.entities.isAlive(e);
     };
     World.prototype.despawn = function (e) {
-        if (!this.entities.isAlive(e))
-            return;
+        this._assertAlive(e, 'despawn');
         this._ensureNotIterating("despawn");
         this._removeFromArchetype(e);
         this.entities.kill(e);
     };
+    World.prototype.despawnMany = function (entities) {
+        var e_6, _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 }; }
+        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; }
+        }
+    };
     //#endregion
     //#region ---------- Components ----------
     World.prototype.has = function (e, ctor) {
@@ -149,18 +300,15 @@ var World = /** @class */ (function () {
         return a.column(tid)[meta.row];
     };
     World.prototype.set = function (e, ctor, value) {
-        var meta = this.entities.meta[e.id];
-        if (!meta || !meta.alive || meta.gen !== e.gen)
-            return;
+        var meta = this._assertAlive(e, "set(".concat(this._formatCtor(ctor), ")"));
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var a = this.archetypes[meta.arch];
         if (!a.has(tid))
-            throw new Error("set() requires component to exist; use add()");
+            throw new Error("set(".concat(this._formatCtor(ctor), ") requires component to exist on ").concat(this._formatEntity(e), "; use add()"));
         a.column(tid)[meta.row] = value;
     };
     World.prototype.add = function (e, ctor, value) {
-        if (!this.entities.isAlive(e))
-            return;
+        this._assertAlive(e, "add(".concat(this._formatCtor(ctor), ")"));
         this._ensureNotIterating("add");
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var srcMeta = this.entities.meta[e.id];
@@ -178,9 +326,28 @@ var World = /** @class */ (function () {
             return src.column(t)[srcMeta.row];
         });
     };
+    World.prototype.addMany = function (e) {
+        var e_7, _a;
+        var items = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            items[_i - 1] = arguments[_i];
+        }
+        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);
+            }
+        }
+        catch (e_7_1) { e_7 = { error: e_7_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; }
+        }
+    };
     World.prototype.remove = function (e, ctor) {
-        if (!this.entities.isAlive(e))
-            return;
+        this._assertAlive(e, "remove(".concat(this._formatCtor(ctor), ")"));
         this._ensureNotIterating("remove");
         var tid = (0, TypeRegistry_1.typeId)(ctor);
         var srcMeta = this.entities.meta[e.id];
@@ -194,90 +361,104 @@ var World = /** @class */ (function () {
             return src.column(t)[srcMeta.row];
         });
     };
-    //#endregion
-    //region ---------- Queries ----------
-    /**
-     * Query all entities having all required component types.
-     * Iterates archetypes (tables) and yields SoA columns for cache-friendly loops.
-     */
+    World.prototype.removeMany = function (e) {
+        var e_8, _a;
+        var ctors = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            ctors[_i - 1] = arguments[_i];
+        }
+        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);
+            }
+        }
+        catch (e_8_1) { e_8 = { error: e_8_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; }
+        }
+    };
     World.prototype.query = function () {
         var ctors = [];
         for (var _i = 0; _i < arguments.length; _i++) {
             ctors[_i] = arguments[_i];
         }
-        var requested = ctors.map(TypeRegistry_1.typeId); // preserve caller order
-        var needSorted = Array.from(new Set(requested)).sort(function (a, b) { return a - b; }); // for signatureHasAll
+        // 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;
         function gen(world) {
-            var _loop_1, _a, _b, a, e_3_1;
-            var e_3, _c;
+            var _a, _b, a, cols, i, row, e, out, i, e_9_1;
+            var e_9, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
                     case 0:
-                        world._isIterating = true;
+                        world._iterateDepth++;
                         _d.label = 1;
                     case 1:
-                        _d.trys.push([1, , 10, 11]);
-                        _loop_1 = function (a) {
-                            var cols, row, e, out, i;
-                            return __generator(this, function (_e) {
-                                switch (_e.label) {
-                                    case 0:
-                                        if (!a)
-                                            return [2 /*return*/, "continue"];
-                                        // if (!signatureHasAll(a.sig, need)) continue;
-                                        if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
-                                            return [2 /*return*/, "continue"];
-                                        cols = requested.map(function (t) { return a.column(t); });
-                                        row = 0;
-                                        _e.label = 1;
-                                    case 1:
-                                        if (!(row < a.entities.length)) return [3 /*break*/, 4];
-                                        e = a.entities[row];
-                                        out = { e: e };
-                                        for (i = 0; i < cols.length; i++)
-                                            out["c".concat(i + 1)] = cols[i][row];
-                                        return [4 /*yield*/, out];
-                                    case 2:
-                                        _e.sent();
-                                        _e.label = 3;
-                                    case 3:
-                                        row++;
-                                        return [3 /*break*/, 1];
-                                    case 4: return [2 /*return*/];
-                                }
-                            });
-                        };
+                        _d.trys.push([1, , 12, 13]);
                         _d.label = 2;
                     case 2:
-                        _d.trys.push([2, 7, 8, 9]);
+                        _d.trys.push([2, 9, 10, 11]);
                         _a = __values(world.archetypes), _b = _a.next();
                         _d.label = 3;
                     case 3:
-                        if (!!_b.done) return [3 /*break*/, 6];
+                        if (!!_b.done) return [3 /*break*/, 8];
                         a = _b.value;
-                        return [5 /*yield**/, _loop_1(a)];
+                        if (!a)
+                            return [3 /*break*/, 7];
+                        if (!(0, Signature_1.signatureHasAll)(a.sig, needSorted))
+                            return [3 /*break*/, 7];
+                        cols = new Array(requested.length);
+                        for (i = 0; i < requested.length; i++)
+                            cols[i] = a.column(requested[i]);
+                        row = 0;
+                        _d.label = 4;
                     case 4:
-                        _d.sent();
-                        _d.label = 5;
+                        if (!(row < a.entities.length)) return [3 /*break*/, 7];
+                        e = a.entities[row];
+                        out = { e: e };
+                        for (i = 0; i < cols.length; i++)
+                            out["c".concat(i + 1)] = cols[i][row];
+                        return [4 /*yield*/, out];
                     case 5:
+                        _d.sent();
+                        _d.label = 6;
+                    case 6:
+                        row++;
+                        return [3 /*break*/, 4];
+                    case 7:
                         _b = _a.next();
                         return [3 /*break*/, 3];
-                    case 6: return [3 /*break*/, 9];
-                    case 7:
-                        e_3_1 = _d.sent();
-                        e_3 = { error: e_3_1 };
-                        return [3 /*break*/, 9];
-                    case 8:
+                    case 8: return [3 /*break*/, 11];
+                    case 9:
+                        e_9_1 = _d.sent();
+                        e_9 = { error: e_9_1 };
+                        return [3 /*break*/, 11];
+                    case 10:
                         try {
                             if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
                         }
-                        finally { if (e_3) throw e_3.error; }
+                        finally { if (e_9) throw e_9.error; }
                         return [7 /*endfinally*/];
-                    case 9: return [3 /*break*/, 11];
-                    case 10:
-                        world._isIterating = false;
+                    case 11: return [3 /*break*/, 13];
+                    case 12:
+                        world._iterateDepth--;
                         return [7 /*endfinally*/];
-                    case 11: return [2 /*return*/];
+                    case 13: return [2 /*return*/];
                 }
             });
         }
@@ -286,7 +467,7 @@ var World = /** @class */ (function () {
     //#endregion
     //#region ---------- Internals ----------
     World.prototype._ensureNotIterating = function (op) {
-        if (this._isIterating) {
+        if (this._iterateDepth > 0) {
             throw new Error("Cannot do structural change (".concat(op, ") while iterating. Use world.cmd() and flush at end of frame."));
         }
     };
@@ -316,7 +497,7 @@ var World = /** @class */ (function () {
      * Then swap-remove from src.
      */
     World.prototype._moveEntity = function (e, src, srcRow, dst, pick) {
-        var e_4, _a;
+        var e_10, _a;
         // add row in dst
         var dstRow = dst.addRow(e);
         try {
@@ -325,12 +506,12 @@ var World = /** @class */ (function () {
                 dst.column(t).push(pick(t));
             }
         }
-        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; }
         }
         // update meta to dst before removing from src (in case src==dst should never happen here)
         var m = this.entities.meta[e.id];
@@ -360,6 +541,32 @@ var World = /** @class */ (function () {
                 return this.remove(op.e, op.ctor);
         }
     };
+    World.prototype._formatEntity = function (e) {
+        return "e#".concat(e.id, "@").concat(e.gen);
+    };
+    World.prototype._formatCtor = function (ctor) {
+        var n = ctor === null || ctor === void 0 ? void 0 : ctor.name;
+        return n && n.length > 0 ? n : "<token>";
+    };
+    /**
+     * 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", ")"));
+        }
+        return meta;
+    };
+    World.prototype._events = function (key) {
+        var ch = this.eventChannels.get(key);
+        if (!ch) {
+            ch = new Events_1.EventChannel();
+            this.eventChannels.set(key, ch);
+        }
+        return ch;
+    };
     return World;
 }());
 exports.World = World;

package/lib/index.d.ts

@@ -3,3 +3,4 @@ export * from "./ecs/TypeRegistry";
 export * from "./ecs/Commands";
 export * from "./ecs/World";
 export * from "./ecs/Schedule";
+export * from "./ecs/Events";

package/lib/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./ecs/TypeRegistry"), exports);
 __exportStar(require("./ecs/Commands"), exports);
 __exportStar(require("./ecs/World"), exports);
 __exportStar(require("./ecs/Schedule"), exports);
+__exportStar(require("./ecs/Events"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-ecs-lib",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "An Archetype Entity Component System (AECS)",
   "main": "./lib/index.js",
   "scripts": {
@@ -9,10 +9,22 @@
     "lint": "tslint -c tslint.json src/**/*.ts",
     "reload-packages": "rm -Rf node_modules && npm cache clean --force && npm ci"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PirateJL/archetype-ecs-lib.git"
+  },
+  "homepage": "https://piratejl.github.io/archetype-ecs-lib",
   "keywords": [
-    "archetype",
+    "game",
+    "gamedev",
+    "threejs",
+    "game-development",
     "ecs",
-    "lib"
+    "entity-component-system",
+    "gameloop",
+    "ecs-framework",
+    "ecs-archetype",
+    "typescript"
   ],
   "author": {
     "name": "PirateJL"