@woosh/meep-engine 2.145.0 → 2.147.0

package/src/engine/simulation/Ticker.js

@@ -24,12 +24,34 @@ class Ticker {
      */
     clock = new Clock();
 
+    /**
+     * When `true`, ticking is suspended while the host document/tab is in the
+     * background (hidden, or stored in the back/forward cache) and resumes from
+     * the current moment once it returns to the foreground.
+     *
+     * This avoids dispatching a flood of catch-up ticks (or one huge delta) for
+     * the time spent suspended, which would otherwise destabilise the simulation.
+     *
+     * Has no effect in environments without document/visibility support (e.g.
+     * Node.js), where the relevant lifecycle events simply never fire.
+     *
+     * @type {boolean}
+     */
+    suspend_in_background = true;
+
     /**
      * @private
      * @type {boolean}
      */
     #isRunning = false;
 
+    /**
+     * Whether ticking is currently suspended because the host page is in the background
+     * @private
+     * @type {boolean}
+     */
+    #isSuspended = false;
+
     #animationFrameHandle = -1;
     #timeoutHandle = -1;
 
@@ -54,6 +76,107 @@ class Ticker {
         return this.#timeoutHandle !== -1 && this.#animationFrameHandle !== -1;
     }
 
+    /**
+     * Stop dispatching ticks because the host page moved to the background.
+     * The clock is paused so no simulation time accrues while suspended. The
+     * update loop itself keeps cycling so it can pick back up cleanly, but
+     * {@link Ticker#onTick} stays silent until the page returns to the foreground.
+     * @private
+     */
+    #suspend() {
+        if (!this.suspend_in_background) {
+            return;
+        }
+
+        if (!this.#isRunning) {
+            // not actively ticking, nothing to suspend
+            return;
+        }
+
+        if (this.#isSuspended) {
+            return;
+        }
+
+        this.#isSuspended = true;
+
+        this.clock.pause();
+    }
+
+    /**
+     * Resume after the host page returned to the foreground.
+     *
+     * The clock is always restarted here (it was paused while suspended), with the
+     * delta accumulated for the suspended period discarded so that time continues
+     * from the current moment rather than catching up all at once. Whether ticks
+     * actually flow afterwards is still governed by the running flag, so a manual
+     * {@link Ticker#pause} taken during suspension is preserved.
+     * @private
+     */
+    #resume() {
+        if (!this.#isSuspended) {
+            return;
+        }
+
+        this.#isSuspended = false;
+
+        this.clock.getDelta(); //discard time spent suspended
+        this.clock.start();
+    }
+
+    #handleVisibilityChange = () => {
+        const doc = globalThis.document;
+
+        if (doc === undefined) {
+            return;
+        }
+
+        if (doc.visibilityState === 'hidden') {
+            this.#suspend();
+        } else {
+            this.#resume();
+        }
+    };
+
+    #handlePageHide = () => {
+        this.#suspend();
+    };
+
+    #handlePageShow = () => {
+        this.#resume();
+    };
+
+    /**
+     * Subscribe to page lifecycle events where the host environment provides them.
+     * Degrades gracefully where there is no DOM event target (e.g. Node.js).
+     * @private
+     */
+    #addLifecycleListeners() {
+        const doc = globalThis.document;
+        if (doc !== undefined && typeof doc.addEventListener === 'function') {
+            doc.addEventListener('visibilitychange', this.#handleVisibilityChange);
+        }
+
+        if (typeof globalThis.addEventListener === 'function') {
+            globalThis.addEventListener('pagehide', this.#handlePageHide);
+            globalThis.addEventListener('pageshow', this.#handlePageShow);
+        }
+    }
+
+    /**
+     * @private
+     */
+    #removeLifecycleListeners() {
+        const doc = globalThis.document;
+        if (doc !== undefined && typeof doc.removeEventListener === 'function') {
+            doc.removeEventListener('visibilitychange', this.#handleVisibilityChange);
+        }
+
+        if (typeof globalThis.removeEventListener === 'function') {
+            globalThis.removeEventListener('pagehide', this.#handlePageHide);
+            globalThis.removeEventListener('pageshow', this.#handlePageShow);
+        }
+    }
+
     /**
      *
      * @param {number} [maxTimeout]
@@ -67,9 +190,10 @@ class Ticker {
         }
 
         this.#isRunning = true;
+        this.#isSuspended = false;
 
         const update = () => {
-            if (!this.#isRunning) {
+            if (!this.#isRunning || this.#isSuspended) {
                 return;
             }
 
@@ -103,7 +227,15 @@ class Ticker {
         this.clock.getDelta(); //purge delta
         this.clock.start();
 
+        this.#addLifecycleListeners();
+
         requestAnimationFrame(animationFrameCallback);
+
+        //if we are starting while the page is already in the background, suspend right away
+        const doc = globalThis.document;
+        if (doc !== undefined && doc.visibilityState === 'hidden') {
+            this.#suspend();
+        }
     }
 
     pause() {
@@ -126,9 +258,12 @@ class Ticker {
     }
 
     stop() {
+        this.#removeLifecycleListeners();
+
         clearTimeout(this.#timeoutHandle);
         cancelAnimationFrame(this.#animationFrameHandle);
         this.#isRunning = false;
+        this.#isSuspended = false;
 
         this.#timeoutHandle = -1;
         this.#animationFrameHandle = -1;

package/src/engine/network/sim/BinaryInterpolationAdapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BinaryInterpolationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/BinaryInterpolationAdapter.js"],"names":[],"mappings":";;;;;gCAMU,MAAM;AANhB;;;;;;;GAOG;AACH;IACI,gEAAgE;;IAEhE,qEAAqE;;IAErE,+DAA+D;;GAEhE;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAEI,sDAAsD;IACtD,MADW,MAAM,CACe;IAEhC;;;;;;;;;;;;;OAaG;IACH,0EAJW,MAAM,iBACN,MAAM,KACN,MAAM,QAIhB;CACJ"}

package/src/engine/network/sim/InterpolationLog.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"InterpolationLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/InterpolationLog.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAkBI;;;;;OAKG;IACH,0DALW;QAAE,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,EAkGvE;IA9EG,+BAA+B;IAC/B,0BADqB,MAAM,CACiB;IAe5C,+BAA+B;IAC/B,2BADqB,MAAM,CACa;IA+D5C;;;;;;;;OAQG;IACH,iBAFW,MAAM,QAkEhB;IAED;;;;;;;;;;;;;OAaG;IACH,yBAJW,MAAM,WACN,MAAM,GACJ,YAAY,CAmCxB;IAED;;;;;OAKG;IACH,mBAsDC;IAED;;;;;;;OAOG;IACH,iBAeC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,YAPW,MAAM,EAAE,GAAC,WAAW,cACpB,MAAM,QACN,MAAM,cACN,MAAM,WACN,MAAM,GACJ,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBATW,YAAY,cACZ,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,KACN,MAAM,wCAEJ,OAAO,CAuBnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,eAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,cASC;;CACJ;6BArkB4B,sCAAsC"}