archetype-ecs-lib 0.4.1 → 0.4.2

package/README.md

@@ -1,3 +1,5 @@
+![Coverage](https://raw.githubusercontent.com/PirateJL/archetype-ecs-lib/refs/heads/gh-pages/coverage.svg)
+
 # Archetype ECS Lib
 
 A tiny **archetype-based ECS** (Entity Component System) for TypeScript.
@@ -16,10 +18,6 @@ Exports are defined in `index.ts`:
 
 ```bash
 npm i archetype-ecs-lib
-# or
-pnpm add archetype-ecs-lib
-# or
-yarn add archetype-ecs-lib
 ````
 
 ---

package/lib/ecs/Commands.d.ts

@@ -16,7 +16,7 @@ export type Command = {
     ctor: ComponentCtor<any>;
 };
 export declare class Commands {
-    private readonly q;
+    private q;
     spawn(init?: (e: Entity) => void): void;
     despawn(e: Entity): void;
     add<T>(e: Entity, ctor: ComponentCtor<T>, value: T): void;

package/lib/ecs/Commands.js

@@ -18,8 +18,8 @@ var Commands = /** @class */ (function () {
         this.q.push({ k: "remove", e: e, ctor: ctor });
     };
     Commands.prototype.drain = function () {
-        var out = this.q.slice();
-        this.q.length = 0;
+        var out = this.q;
+        this.q = [];
         return out;
     };
     return Commands;

package/lib/ecs/Schedule.js

@@ -38,7 +38,16 @@ var Schedule = /** @class */ (function () {
                 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;
-                        fn(world, dt);
+                        try {
+                            fn(world, dt);
+                        }
+                        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 }; }

package/lib/ecs/World.d.ts

@@ -6,7 +6,7 @@ export declare class World implements WorldI {
     private readonly archByKey;
     private readonly systems;
     private readonly commands;
-    private _isIterating;
+    private _iterateDepth;
     constructor();
     /** Queue structural changes to apply safely after systems run. */
     cmd(): Commands;
@@ -40,4 +40,10 @@ export declare class World implements WorldI {
      */
     private _moveEntity;
     private _apply;
+    private _formatEntity;
+    private _formatCtor;
+    /**
+     * Throws an error if the entity is not alive
+     */
+    private _assertAlive;
 }

package/lib/ecs/World.js

@@ -51,14 +51,16 @@ var World = /** @class */ (function () {
         this.archByKey = new Map();
         this.systems = [];
         this.commands = new Commands_1.Commands();
-        this._isIterating = false;
+        this._iterateDepth = 0;
         // 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 +72,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,12 +89,13 @@ var World = /** @class */ (function () {
             }
         }
         finally {
-            this._isIterating = false;
+            this._iterateDepth--;
             this.flush();
         }
     };
     World.prototype.flush = function () {
         var e_2, _a;
+        this._ensureNotIterating("flush");
         var ops = this.commands.drain();
         try {
             for (var ops_1 = __values(ops), ops_1_1 = ops_1.next(); !ops_1_1.done; ops_1_1 = ops_1.next()) {
@@ -123,8 +126,7 @@ var World = /** @class */ (function () {
         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);
@@ -149,18 +151,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];
@@ -179,8 +178,7 @@ var World = /** @class */ (function () {
         });
     };
     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];
@@ -205,79 +203,79 @@ var World = /** @class */ (function () {
         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 _a, _b, a, cols, i, row, e, out, i, e_3_1;
             var e_3, _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:
+                    case 8: return [3 /*break*/, 11];
+                    case 9:
                         e_3_1 = _d.sent();
                         e_3 = { error: e_3_1 };
-                        return [3 /*break*/, 9];
-                    case 8:
+                        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; }
                         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 +284,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."));
         }
     };
@@ -360,6 +358,24 @@ 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;
+    };
     return World;
 }());
 exports.World = World;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-ecs-lib",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "An Archetype Entity Component System (AECS)",
   "main": "./lib/index.js",
   "scripts": {
@@ -9,10 +9,21 @@
     "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"
+  },
   "keywords": [
-    "archetype",
+    "game",
+    "gamedev",
+    "threejs",
+    "game-development",
     "ecs",
-    "lib"
+    "entity-component-system",
+    "gameloop",
+    "ecs-framework",
+    "ecs-archetype",
+    "typescript"
   ],
   "author": {
     "name": "PirateJL"