@woosh/meep-engine 2.127.1 → 2.128.0

package/package.json

@@ -5,7 +5,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.127.1",
+  "version": "2.128.0",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/packing/miniball/Miniball.d.ts

@@ -1,6 +1,7 @@
 /**
  * Computes the miniball of the given point set.
  *
+ * Based on paper "Fast Smallest-Enclosing-Ball Computation in High Dimensions" by "Kaspar Fischer" et. al.
  * @copyright Company Named Limited (c) 2025
  */
 export class Miniball {
@@ -152,16 +153,17 @@ export class Miniball {
      *
      * Iteratively, we compute the point in support that is closest to the current center and then
      * walk towards this target as far as we can, i.e., we move until some new point touches the
-     * boundary of the ball and must thus be inserted into support. In each of these two alternating
-     * phases, we always have to check whether some point must be dropped from support, which is the
-     * case when the center lies in <i>aff(support)</i>. If such an attempt to drop fails, we are
-     * done; because then the center lies even <i>conv(support)</i>.
+     * boundary of the ball and must thus be inserted into support.
+     *
+     * In each of these two alternating phases, we always have to check whether some point must be dropped from support,
+     * which is the case when the center lies in <i>aff(support)</i>.
+     * If such an attempt to drop fails, we are done; because then the center lies even <i>conv(support)</i>.
      * @private
      */
     private compute;
     /**
      * If center doesn't already lie in <i>conv(support)</i> and is thus not optimal yet,
-     * {@link #successfulDrop()} elects a suitable point <i>k</i> to be removed from the support and
+     * {@link successfulDrop()} elects a suitable point <i>k</i> to be removed from the support and
      * returns true. If the center lies in the convex hull, however, false is returned (and the
      * support remains unaltered).
      *
@@ -171,16 +173,16 @@ export class Miniball {
     successfulDrop(): boolean;
     /**
      * Given the center of the current enclosing ball and the walking direction `centerToAff`,
-     * determine how much we can walk into this direction without losing a point from <i>S</i>. The
-     * (positive) factor by which we can walk along `centerToAff` is returned. Further,
-     * `stopper` is set to the index of the most restricting point and to -1 if no such point
-     * was found.
+     * determine how much we can walk into this direction without losing a point from <i>S</i>.
+     *
+     * The (positive) factor by which we can walk along `centerToAff` is returned.
+     * Further, `stopper` is set to the index of the most restricting point and to -1 if no such point was found.
      * @return {number}
      * @private
      */
     private findStopFraction;
     /**
-     * Outputs information about the miniball
+     * Outputs information about the Miniball
      * @return {string}
      */
     toString(): string;

package/src/core/geom/packing/miniball/Miniball.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Miniball.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/packing/miniball/Miniball.js"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH;IACI;;;;;OAKG;IACH,8BAkGC;IA/FG;;;OAGG;IACH,WAFU,MAAM,CAEE;IAClB;;;OAGG;IACH,WAFU,MAAM,CAEE;IAClB;;;OAGG;IACH,iBAFU,MAAM,CAEQ;IACxB;;;;;;;;;;OAUG;IACH,wBAAwB;IACxB;;;;OAIG;IACH,iBAAiB;IACjB;;;OAGG;IACH,SAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,YAAe;IAEf;;;;OAIG;IACH,eAA2B;IAI3B;;;OAGG;IACH,KAFU,MAAM,CAEU;IAM1B;;;;OAIG;IACH,iBAA4D;IAE5D;;;OAGG;IACH,aAFU,MAAM,EAAE,GAAC,YAAY,CAEkD;IAEjF;;;OAGG;IACH,eAFU,MAAM,EAAE,GAAC,YAAY,CAEwD;IAEvF;;;OAGG;IACH,SAFU,MAAM,EAAE,GAAC,YAAY,CAEsD;IAErF;;;;OAIG;IACH,kBAAgC;IAIpC;;;;;;;OAOG;IACH,WAFY,OAAO,CAIlB;IAED;;;;;;OAMG;IACH,UAFY,MAAM,CAIjB;IAED;;;;;;OAMG;IACH,UAFY,MAAM,EAAE,CAInB;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;OAMG;IACH,QAJY,MAAM,CAMjB;IAED;;;;;;;;OAQG;IACH,iBAkCC;IAED;;OAEG;IACH,yBAGC;IAED;;OAEG;IACH,qBAcC;IAED;;;;;;;;;;OAUG;IACH,gBA4CC;IAED;;;;;;;;OAQG;IACH,kBAFY,OAAO,CA4BlB;IAED;;;;;;;;OAQG;IACH,yBAyDC;IAGD;;;OAGG;IACH,YAFY,MAAM,CAkBjB;CACJ;wBAnbuB,cAAc"}
+{"version":3,"file":"Miniball.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/packing/miniball/Miniball.js"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH;IA8CI;;;;;OAKG;IACH,8BA4DC;IA9GD;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;;;;;;;OAUG;IACH,wBAAoB;IAEpB;;;;OAIG;IACH,iBAAa;IAEb;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAYR;;OAEG;IACH,YAAe;IAEf;;;;OAIG;IACH,eAA2B;IAI3B;;;OAGG;IACH,KAFU,MAAM,CAEU;IAM1B;;;;OAIG;IACH,iBAA4D;IAE5D;;;OAGG;IACH,aAFU,MAAM,EAAE,GAAC,YAAY,CAEkD;IAEjF;;;OAGG;IACH,eAFU,MAAM,EAAE,GAAC,YAAY,CAEwD;IAEvF;;;OAGG;IACH,SAFU,MAAM,EAAE,GAAC,YAAY,CAEsD;IAErF;;;;OAIG;IACH,kBAAgC;IAIpC;;;;;;;OAOG;IACH,WAFY,OAAO,CAIlB;IAED;;;;;;OAMG;IACH,UAFY,MAAM,CAIjB;IAED;;;;;;OAMG;IACH,UAFY,MAAM,EAAE,CAInB;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;OAMG;IACH,QAJY,MAAM,CAMjB;IAED;;;;;;;;OAQG;IACH,iBAkCC;IAED;;OAEG;IACH,yBAGC;IAED;;OAEG;IACH,qBAcC;IAED;;;;;;;;;;;OAWG;IACH,gBA4CC;IAED;;;;;;;;OAQG;IACH,kBAFY,OAAO,CA4BlB;IAED;;;;;;;;OAQG;IACH,yBA8DC;IAGD;;;OAGG;IACH,YAFY,MAAM,CA0BjB;CACJ;wBAzcuB,cAAc"}

package/src/core/geom/packing/miniball/Miniball.js

@@ -14,10 +14,10 @@ import { Subspan } from "./Subspan.js";
  * Small number
  * @type {number}
  */
-const Epsilon = 1.0E-14;
+const Epsilon = 1e-14;
 
 /**
- * Limit to how many iterations algorithm is allowed to perform, this is to cover poorly converging cases
+ * Limit to how many iterations the algorithm is allowed to perform, this is to cover poorly converging cases
  * @type {number}
  */
 const MAX_ITERATIONS = 10000;
@@ -25,9 +25,55 @@ const MAX_ITERATIONS = 10000;
 /**
  * Computes the miniball of the given point set.
  *
+ * Based on paper "Fast Smallest-Enclosing-Ball Computation in High Dimensions" by "Kaspar Fischer" et. al.
  * @copyright Company Named Limited (c) 2025
  */
 export class Miniball {
+
+    /**
+     *
+     * @type {number}
+     */
+    iteration = 0;
+
+    /**
+     *
+     * @type {number}
+     */
+    distToAff = 0;
+
+    /**
+     *
+     * @type {number}
+     */
+    distToAffSquare = 0;
+
+    /**
+     *
+     * The squared radius of the miniball.
+     *
+     * This is equivalent to `radius() * radius()`.
+     *
+     * Precondition: `!isEmpty()`
+     *
+     * @type {number}
+     * @private
+     */
+    __squaredRadius = 0;
+
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    __radius = 0;
+
+    /**
+     *
+     * @type {number}
+     */
+    stopper = 0;
+
     /**
      * Notice that the point set `points` is assumed to be immutable during the computation.
      * That is, if you add, remove, or change points in the point set, you have to create a new instance of {@link Miniball}.
@@ -37,44 +83,6 @@ export class Miniball {
     constructor(points) {
         assert.defined(points, 'points');
 
-        /**
-         *
-         * @type {number}
-         */
-        this.iteration = 0;
-        /**
-         *
-         * @type {number}
-         */
-        this.distToAff = 0;
-        /**
-         *
-         * @type {number}
-         */
-        this.distToAffSquare = 0;
-        /**
-         *
-         * The squared radius of the miniball.
-         *
-         * This is equivalent to `radius() * radius()`.
-         *
-         * Precondition: `!isEmpty()`
-         *
-         * @type {number}
-         * @private
-         */
-        this.__squaredRadius = 0;
-        /**
-         *
-         * @type {number}
-         * @private
-         */
-        this.__radius = 0;
-        /**
-         *
-         * @type {number}
-         */
-        this.stopper = 0;
 
         /**
          * @type {PointSet}
@@ -264,10 +272,11 @@ export class Miniball {
      *
      * Iteratively, we compute the point in support that is closest to the current center and then
      * walk towards this target as far as we can, i.e., we move until some new point touches the
-     * boundary of the ball and must thus be inserted into support. In each of these two alternating
-     * phases, we always have to check whether some point must be dropped from support, which is the
-     * case when the center lies in <i>aff(support)</i>. If such an attempt to drop fails, we are
-     * done; because then the center lies even <i>conv(support)</i>.
+     * boundary of the ball and must thus be inserted into support.
+     *
+     * In each of these two alternating phases, we always have to check whether some point must be dropped from support,
+     * which is the case when the center lies in <i>aff(support)</i>.
+     * If such an attempt to drop fails, we are done; because then the center lies even <i>conv(support)</i>.
      * @private
      */
     compute() {
@@ -318,7 +327,7 @@ export class Miniball {
 
     /**
      * If center doesn't already lie in <i>conv(support)</i> and is thus not optimal yet,
-     * {@link #successfulDrop()} elects a suitable point <i>k</i> to be removed from the support and
+     * {@link successfulDrop()} elects a suitable point <i>k</i> to be removed from the support and
      * returns true. If the center lies in the convex hull, however, false is returned (and the
      * support remains unaltered).
      *
@@ -355,10 +364,10 @@ export class Miniball {
 
     /**
      * Given the center of the current enclosing ball and the walking direction `centerToAff`,
-     * determine how much we can walk into this direction without losing a point from <i>S</i>. The
-     * (positive) factor by which we can walk along `centerToAff` is returned. Further,
-     * `stopper` is set to the index of the most restricting point and to -1 if no such point
-     * was found.
+     * determine how much we can walk into this direction without losing a point from <i>S</i>.
+     *
+     * The (positive) factor by which we can walk along `centerToAff` is returned.
+     * Further, `stopper` is set to the index of the most restricting point and to -1 if no such point was found.
      * @return {number}
      * @private
      */
@@ -379,7 +388,11 @@ export class Miniball {
         const centerToPoint = this.centerToPoint;
         const centerToAff = this.centerToAff;
 
+        const distToAffSquare = this.distToAffSquare;
+        const squaredRadius = this.__squaredRadius;
+
         const size = this.__size;
+        const distance_error = Epsilon * this.__radius * this.distToAff;
 
         for (j = 0; j < size; ++j) {
 
@@ -388,6 +401,7 @@ export class Miniball {
             }
 
             for (i = 0; i < dim; ++i) {
+                // read out a single point, offset by center
                 centerToPoint[i] = pointSet.coord(j, i) - center[i];
             }
 
@@ -397,7 +411,7 @@ export class Miniball {
                 dirPointProd += centerToAff[i] * centerToPoint[i];
             }
 
-            if ((this.distToAffSquare - dirPointProd) < (Epsilon * this.__radius * this.distToAff)) {
+            if ((distToAffSquare - dirPointProd) < distance_error) {
                 continue;
             }
 
@@ -407,7 +421,7 @@ export class Miniball {
                 bound += centerToPoint[i] * centerToPoint[i];
             }
 
-            bound = (this.__squaredRadius - bound) / 2 / (this.distToAffSquare - dirPointProd);
+            bound = (squaredRadius - bound) / 2 / (distToAffSquare - dirPointProd);
 
             if (bound > 0 && bound < scale) {
                 //if (com.dreizak.miniball.highdim.Logging.log)
@@ -423,15 +437,20 @@ export class Miniball {
 
 
     /**
-     * Outputs information about the miniball
+     * Outputs information about the Miniball
      * @return {string}
      */
     toString() {
         let s = "Miniball [";
+
         if (this.isEmpty()) {
-            s += ("isEmpty=true");
+
+            s += "isEmpty=true";
+
         } else {
-            s += ("center=(");
+
+            s += "center=(";
+
             for (let i = 0; i < this.dim; ++i) {
                 s += (this.__center[i]);
                 if (i < this.dim - 1)
@@ -439,8 +458,11 @@ export class Miniball {
             }
 
             s += `), radius=${this.__radius}, squaredRadius=${this.__squaredRadius}`;
+
         }
+
         s += "]";
+
         return s;
     }
 }

package/src/engine/Clock.d.ts

@@ -31,8 +31,9 @@ declare class Clock {
      * Allows us to slow down or speed up flow of time via modifiers, see {@link Stat} for details
      * Default speed is x1, i.e. - unmodified
      * @type {Stat}
+     * @readonly
      */
-    speed: Stat;
+    readonly speed: Stat;
     /**
      *
      * @param {number} v

package/src/engine/Clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;OAKG;IACH,OAFU,IAAI,CAEM;IAMpB;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAIC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA9HgB,4BAA4B"}
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAIC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA/HgB,4BAA4B"}

package/src/engine/Clock.js

@@ -50,6 +50,7 @@ class Clock {
      * Allows us to slow down or speed up flow of time via modifiers, see {@link Stat} for details
      * Default speed is x1, i.e. - unmodified
      * @type {Stat}
+     * @readonly
      */
     speed = new Stat(1);
 

package/src/engine/ecs/EntityManager.d.ts

@@ -141,7 +141,7 @@ export class EntityManager {
     /**
      * If the {@link EntityManager} is already started, the system will be started automatically before being added
      * @param {System} system
-     * @returns {Promise}
+     * @returns {Promise} resolution depends on {@link EntityManager}'s state, if running - promise resolves after system startup. Otherwise, the promise will be resolved immediately.
      * @throws {IllegalStateException}
      */
     addSystem(system: System<any, any, any, any, any>): Promise<any>;
@@ -166,8 +166,8 @@ export class EntityManager {
      */
     private startSystem;
     /**
-     * This method is asynchronous by nature, it has to wait for each individual system to finish its own statup.
-     * Make sure to register callback in order to be notified when the startup has finished
+     * This method is asynchronous by nature, it has to wait for each system to finish its own startup.
+     * Make sure to register callback to be notified when the startup has finished
      * @param {function} [readyCallback] executed once entity manager successfully completes startup
      * @param {function} [errorCallback] executed if entity manager encounters an error during startup
      */
@@ -179,17 +179,16 @@ export class EntityManager {
      */
     promiseSystem(systemClass: Class): Promise<System<any, any, any, any, any>>;
     /**
-     *
      * @param {Class} systemClass
      * @param {SystemState} state
      * @returns {Promise.<System>}
      */
     promiseSystemInState(systemClass: Class, state: SystemState): Promise<System<any, any, any, any, any>>;
     /**
-     * This method is asynchronous by nature, it will not be done until each individual system has finished its shutdown
+     * This method is asynchronous by nature, it will not be done until each system has finished its shutdown
      * Make sure to use callback to be notified when the shutdown has completed
      * @param {function} [readyCallback] Called when shutdown finishes successfully. defaults to no-operation
-     * @param {function} [errorCallback] Called when an error occurs during shutdown process. defaults to console error output
+     * @param {function} [errorCallback] Called when an error occurs during the shutdown process. defaults to console error output
      */
     shutdown(readyCallback?: Function, errorCallback?: Function): void;
     /**

package/src/engine/ecs/EntityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAWhB;;;;;;GAMG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAoEhB;IAED;;;;;OAKG;IACH,iEAoEC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBA6BC;IAED;;;;;OAKG;IACH,oBA0DC;IAED;;;;;OAKG;IACH,kEAwEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;;OAKG;IACH,8DAFa,wCAAgB,CAsB5B;IAED;;;;;OAKG;IACH,mEAsEC;IAGL;;OAEG;IACH,yBAhpBe,sBAAsB,UAgpBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBAl3BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAgBU,MAAM;;;;;;;;;AAiBhB;;;;;;GAMG;AACH;IAEI;;;;OAIG;IACH,kBAFU,iCAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;qBADO,uCAAc;;MAI1B;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;OAMG;IACH,gDAA2C;IAE3C;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IAEf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BAmFC;IAED;;;OAGG;IACH,uBAFa,OAAO,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,GACJ,IAAI,aAAS,CAiBzB;IAGD;;;OAGG;IACH,oBAFW,MAAM,QAoEhB;IAED;;;;;OAKG;IACH,iEA6DC;IAED;;;;OAIG;IACH,uDAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAmCC;IAED;;;;;OAKG;IACH,oBAqFC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,mCAFa,wCAAgB,CA0B5B;IAED;;;;OAIG;IACH,8DAFa,wCAAgB,CAsB5B;IAED;;;;;OAKG;IACH,mEAoFC;IAGL;;OAEG;IACH,yBAxrBe,sBAAsB,UAwrBA;IACrC;;OAEG;IACH,0BAAqC;CATpC;uBAh6BmC,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B"}

package/src/engine/ecs/EntityManager.js

@@ -25,6 +25,12 @@ export const EntityManagerState = {
     Stopped: 5
 };
 
+/**
+ * In seconds
+ * @type {number}
+ */
+const DEFAULT_SYSTEM_STARTUP_TIMEOUT_CHECK = 5;
+
 /**
  * Brings together {@link System}s and an {@link EntityComponentDataset}
  * Main entry point into the simulation process
@@ -261,7 +267,7 @@ export class EntityManager {
 
         const localComponentTypeMap = this.getComponentTypeMap();
 
-        //ensure compatibility with system-used component map
+        // ensure compatibility with system-used component map
         dataset.registerManyComponentTypes(localComponentTypeMap);
 
         this.dataset = dataset;
@@ -450,7 +456,7 @@ export class EntityManager {
     /**
      * If the {@link EntityManager} is already started, the system will be started automatically before being added
      * @param {System} system
-     * @returns {Promise}
+     * @returns {Promise} resolution depends on {@link EntityManager}'s state, if running - promise resolves after system startup. Otherwise, the promise will be resolved immediately.
      * @throws {IllegalStateException}
      */
     addSystem(system) {
@@ -472,17 +478,17 @@ export class EntityManager {
         try {
             validateSystem(system);
         } catch (e) {
-            console.error(`System validation failed '${computeSystemName(system)}' : `, e, system);
+            console.error(`Validation of '${computeSystemName(system)}' failed : `, e, system);
         }
 
         //check system state
         const systemState = system.state.getValue();
 
-        const legalStates = [SystemState.INITIAL, SystemState.STOPPED];
+        const valid_states = [SystemState.INITIAL, SystemState.STOPPED];
 
-        if (legalStates.indexOf(systemState) === -1) {
+        if (valid_states.indexOf(systemState) === -1) {
             //illegal state
-            throw new IllegalStateException(`System must be in one of these states: [${legalStates.join(",")}], instead was ${systemState}`);
+            throw new IllegalStateException(`System must be in one of these states: [${valid_states.join(",")}], instead was ${systemState}`);
         }
 
         const systems = this.systems;
@@ -495,22 +501,16 @@ export class EntityManager {
         const entityObserver = new EntityObserver(system.dependencies, system.link, system.unlink, system);
         this.systemObservers.set(system, entityObserver);
 
-        let startup_promise;
+        let result_promise;
         if (this.state === EntityManagerState.Running) {
             //initialize the system
-            startup_promise = new Promise((resolve, reject) => {
+            result_promise = new Promise((resolve, reject) => {
                 this.startSystem(system, resolve, reject);
             });
         } else {
-            startup_promise = Promise.resolve();
+            result_promise = Promise.resolve();
         }
 
-        // Link EntityManager
-        if (system.entityManager === null) {
-            system.entityManager = this;
-        } else if (system.entityManager !== this) {
-            throw new Error(`System is bound to another EntityManager`);
-        }
 
         // link dependency components
         this.dataset?.registerManyComponentTypes(system.referenced_components);
@@ -519,8 +519,7 @@ export class EntityManager {
 
         this.on.systemAdded.send1(system);
 
-
-        return startup_promise;
+        return result_promise;
     }
 
     /**
@@ -601,7 +600,13 @@ export class EntityManager {
         }
 
         try {
-            system.shutdown(self, systemReady, systemFailed);
+            const promise = system.shutdown(self);
+
+            assert.defined(promise, "promise");
+            assert.notNull(promise, "promise");
+            assert.isFunction(promise.then, "promise.then");
+
+            promise.then(systemReady, systemFailed);
         } catch (e) {
             console.error(`Failed to execute system shutdown`, e);
             errorCallback(e);
@@ -662,25 +667,53 @@ export class EntityManager {
             successCallback(system);
         }
 
-        function systemFailed(reason) {
-            errorCallback(reason);
-        }
-
         try {
-            system.startup(self, systemReady, systemFailed);
+
+            const deprecation_check = () => {
+                throw new Error("'success' callback was deprecated in meep 2.128.0, please use `async` instead.");
+            };
+
+            // Link EntityManager
+            if (system.entityManager === null) {
+                system.entityManager = this;
+            } else if (system.entityManager !== this) {
+                throw new Error(`System is bound to another EntityManager`);
+            }
+
+            const promise = system.startup(self, deprecation_check);
+
+
+            assert.defined(promise, "promise");
+            assert.notNull(promise, "promise");
+            assert.isFunction(promise.then, "promise.then");
+
+            const startup_check_timeout = setTimeout(
+                () => {
+                    console.warn(`System '${computeSystemName(system)}' failed to complete startup process in ${DEFAULT_SYSTEM_STARTUP_TIMEOUT_CHECK}s, check your code for potential deadlocks.`);
+                },
+                DEFAULT_SYSTEM_STARTUP_TIMEOUT_CHECK * 1000,
+            );
+
+            promise.finally(() => {
+                clearTimeout(startup_check_timeout);
+            });
+
+            promise.then(systemReady, errorCallback);
+
         } catch (e) {
             console.error(`Failed to execute system startup`, e);
-            systemFailed(e);
+            errorCallback(e);
         }
     }
 
     /**
-     * This method is asynchronous by nature, it has to wait for each individual system to finish its own statup.
-     * Make sure to register callback in order to be notified when the startup has finished
+     * This method is asynchronous by nature, it has to wait for each system to finish its own startup.
+     * Make sure to register callback to be notified when the startup has finished
      * @param {function} [readyCallback] executed once entity manager successfully completes startup
      * @param {function} [errorCallback] executed if entity manager encounters an error during startup
      */
     startup(readyCallback = noop, errorCallback = console.error) {
+
         if (this.state === EntityManagerState.Starting) {
             throw new IllegalStateException(`System is currently in starting state`);
         }
@@ -743,15 +776,15 @@ export class EntityManager {
             return;
         }
 
-        systems.forEach(function (system) {
+        for (const system of systems) {
             //ensure eventManager are there
             //start the system
             const cbOK = systemReady.bind(null, system);
             const cbError = systemError.bind(null, system);
 
-            self.startSystem(system, cbOK, cbError);
+            this.startSystem(system, cbOK, cbError);
 
-        });
+        }
     }
 
     /**
@@ -786,7 +819,6 @@ export class EntityManager {
     }
 
     /**
-     *
      * @param {Class} systemClass
      * @param {SystemState} state
      * @returns {Promise.<System>}
@@ -814,21 +846,24 @@ export class EntityManager {
     }
 
     /**
-     * This method is asynchronous by nature, it will not be done until each individual system has finished its shutdown
+     * This method is asynchronous by nature, it will not be done until each system has finished its shutdown
      * Make sure to use callback to be notified when the shutdown has completed
      * @param {function} [readyCallback] Called when shutdown finishes successfully. defaults to no-operation
-     * @param {function} [errorCallback] Called when an error occurs during shutdown process. defaults to console error output
+     * @param {function} [errorCallback] Called when an error occurs during the shutdown process. defaults to console error output
      */
     shutdown(readyCallback = noop, errorCallback = console.error) {
         if (this.state !== EntityManagerState.Running) {
             throw new IllegalStateException(`System is wrong state, expected '${EntityManagerState.Running}'`);
         }
 
+        assert.isFunction(readyCallback, 'readyCallback');
+        assert.isFunction(errorCallback, 'errorCallback');
+
         this.state = EntityManagerState.Stopping;
 
         if (this.dataset !== null) {
             // a dataset is still attached, to properly dispose of all the component-bound resources, we first detach the dataset
-            this.detachDataSet();
+            this.detachDataset();
         }
 
         const self = this;
@@ -877,18 +912,29 @@ export class EntityManager {
             finalizeShutdown();
         }
 
-        systems.forEach(function (system) {
+        for (const system of systems) {
+
             system.state.set(SystemState.STOPPING);
-            //start the system
+
             const cbOK = systemReady.bind(null, system);
             const cbError = systemError.bind(null, system);
+
             try {
-                system.shutdown(self, cbOK, cbError);
+                const promise = system.shutdown(this);
+
+                assert.defined(promise, 'promise');
+                assert.notNull(promise, 'promise');
+                assert.isFunction(promise.then, 'promise.then');
+
+                // TODO add timeout
+
+                promise.then(cbOK, cbError);
             } catch (e) {
                 //failure in shutdown function
                 cbError(e);
             }
-        });
+
+        }
     }
 }
 

package/src/engine/ecs/System.d.ts

@@ -11,9 +11,9 @@ export class System<A, B = any, C = any, D = any, E = any> {
 
     protected readonly entityManager: EntityManager
 
-    startup(em: EntityManager, ready_callback: () => void, error_callback: () => void): void
+    startup(em: EntityManager): Promise<void>
 
-    shutdown(em: EntityManager, ready_callback: () => void, error_callback: () => void): void
+    shutdown(em: EntityManager): Promise<void>
 
     link(a: A, entity: number): void
     link(a: A, b: B, entity: number): void

package/src/engine/ecs/System.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAEI;;;;;OAKG;IACH,uCAAqB;IAErB;;;;OAIG;IACH,oBAA+C;IAE/C;;;;;OAKG;IACH,oBAAkB;IAElB;;;;;;;;;OASG;IACH,iBAFU,6BAA6B,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;OAIG;IACH,oCAFY,MAAM,CA8BjB;IAED;;;;;;OAMG;IACH,8FAGC;IAED;;;;;;;OAOG;IACH,+FAEC;IAGD;;;;OAIG;IACH,wCAEC;IAED;;;;OAIG;IACH,0CAEC;IAED;;;;;;;;OAQG;IACH,6DAEC;IAED;;;;;;;;OAQG;IACH,6DAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,yBAA4B;IAG5B;;;;;;OAMG;IACH,oBAAuB;CAvBtB;;;;0BA8CS,MAAM;;;;;;;;qBAjPK,6BAA6B"}
+{"version":3,"file":"System.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/System.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAEI;;;;;OAKG;IACH,uCAAqB;IAErB;;;;OAIG;IACH,oBAA+C;IAE/C;;;;;;;OAOG;IACH,6BAAkB;IAElB;;;;;;;;;;OAUG;IACH,0BAFU,6BAA6B,CAElB;IAGrB;;OAEG;IACH,mCAcC;IAED;;;;;OAKG;IACH,oCAFY,MAAM,CA8BjB;IAED;;;;;;OAMG;IACH,uCAHa,QAAQ,IAAI,CAAC,CAKzB;IAED;;;;;;;OAOG;IACH,wCAHa,QAAQ,IAAI,CAAC,CAKzB;IAGD;;;;OAIG;IACH,wCAEC;IAED;;;;OAIG;IACH,0CAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAED;;;;;;;;;;OAUG;IACH,6DAEC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;;;OAIG;IACH,yBAA4B;IAG5B;;;;;;OAMG;IACH,oBAAuB;CAvBtB;;;;0BA8CS,MAAM;;;;;;;;qBAxPK,6BAA6B"}