@woosh/meep-engine 2.144.0 → 2.146.0

package/src/engine/physics/queries/overlap_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}

package/src/engine/physics/queries/overlap_shape.js

@@ -1,183 +1,185 @@
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
-import { returnTrue } from "../../../core/function/returnTrue.js";
-import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
-import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
-import { body_id_index } from "../body/BodyStorage.js";
-import { gjk } from "../gjk/gjk.js";
-import { aabb_world_to_local } from "../narrowphase/decomposition/aabb_world_to_local.js";
-import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
-import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
-import { PosedShape } from "../narrowphase/PosedShape.js";
-
-/**
- * Scratch state — module-scoped to avoid per-query allocation. Safe
- * because PhysicsSystem queries run on the main thread, sequentially.
- */
-const local_aabb = new Float64Array(6);
-const world_aabb = new Float64Array(6);
-const concave_query_aabb = new Float64Array(6);
-const simplex_buf = new Float64Array(12);
-
-const query_posed = new PosedShape();
-const candidate_posed = new PosedShape();
-const triangle_shape = new Triangle3D();
-
-/**
- * Maximum triangles a concave candidate can emit per overlap pair.
- * Same rationale as the narrowphase's `MAX_TRIANGLES_PER_PAIR`: the
- * broadphase has already bounded the query AABB to the query shape's
- * envelope, so a single candidate typically yields tens of triangles.
- * Excess triangles are dropped by the enumerator's bounds check —
- * worst case is a missed overlap on a far edge of the candidate's
- * geometry, recovered next query.
- * @type {number}
- */
-const MAX_TRIANGLES_PER_PAIR = 1024;
-
-const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
-
-/**
- * Broadphase candidate buffer. Grows by doubling on overflow.
- * @type {Uint32Array}
- */
-let scratch_candidates = new Uint32Array(64);
-
-/**
- * Test what bodies overlap a convex shape placed at a given pose. Each
- * overlapping body's `body_id` is written to `output` starting at
- * `output_offset`; the function returns the number of body ids written.
- *
- * Use case: speculative physics queries for kinematic / character
- * controllers. An external system can ask "would my body collide with
- * anything if I moved it here?" without committing a tick of
- * simulation. The output is a flat list of body ids so the caller can
- * decide what to do per hit (skip, push, slide, etc.).
- *
- * The pipeline mirrors the narrowphase pair test:
- *   1. Build the query shape's world AABB.
- *   2. Pull candidates from both broadphase trees that overlap that AABB.
- *   3. For each candidate, run GJK in world frame. Convex candidates
- *      go through one GJK call; concave candidates (heightmap / mesh)
- *      go through the per-triangle decomposition path.
- *   4. Apply the optional `filter` callback (same signature as in
- *      raycast / shapeCast) before the GJK test — early-out on bodies
- *      the caller already wants to skip (themselves, allies, etc.).
- *
- * The query shape must be convex (`is_convex === true`). Concave shapes
- * are typically static terrain and not used as kinematic query
- * probes; rejecting them avoids the M×N triangle-pair cost.
- *
- * @param {PhysicsSystem} system
- * @param {AbstractShape3D} shape  query shape, convex; expressed in
- *   its own local frame
- * @param {{x:number,y:number,z:number}} position world position of the
- *   query shape
- * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
- *   of the query shape (unit quaternion)
- * @param {Uint32Array|number[]} output buffer to write body_ids into.
- *   Caller is responsible for sizing it; ids past its end are dropped.
- * @param {number} output_offset float-index in output to start writing at
- * @param {(entity:number, collider:Collider)=>boolean} [filter]
- *   defaults to {@link returnTrue} (accept every candidate)
- * @returns {number} number of overlapping bodies written
- * @throws {Error} if `shape.is_convex === false`
- */
-export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
-    if (shape.is_convex === false) {
-        throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
-    }
-
-    // ── 1. Query shape's world AABB ─────────────────────────────────
-    shape.compute_bounding_box(local_aabb);
-    aabb3_transform_oriented(
-        world_aabb, 0,
-        local_aabb[0], local_aabb[1], local_aabb[2],
-        local_aabb[3], local_aabb[4], local_aabb[5],
-        position.x, position.y, position.z,
-        rotation.x, rotation.y, rotation.z, rotation.w
-    );
-
-    // ── 2. Gather broadphase candidates ─────────────────────────────
-    const n_static = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, 0, system.staticBvh, world_aabb
-    );
-    const n_dynamic = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, n_static, system.dynamicBvh, world_aabb
-    );
-    const n_total = n_static + n_dynamic;
-    if (n_total === 0) return 0;
-
-    // ── 3. Set up query PosedShape (constant across candidates) ─────
-    query_posed.setup(shape, position, rotation);
-
-    // ── 4. Per-candidate narrowphase ────────────────────────────────
-    const output_capacity = output.length - output_offset;
-    let count = 0;
-    let cursor = output_offset;
-
-    for (let i = 0; i < n_total; i++) {
-        if (count >= output_capacity) break;
-
-        const body_id = scratch_candidates[i];
-        const body_idx = body_id_index(body_id);
-
-        const entity = system.entityOf(body_id);
-        if (entity < 0) continue;
-
-        const collider = system.__primary_collider(body_idx);
-        if (collider === null) continue;
-        if (!filter(entity, collider)) continue;
-
-        const candidate_tr = system.__transforms[body_idx];
-
-        let overlaps = false;
-
-        if (collider.shape.is_convex !== false) {
-            candidate_posed.setup(collider.shape, candidate_tr.position, candidate_tr.rotation);
-            overlaps = gjk(simplex_buf, query_posed, candidate_posed);
-        } else {
-            // Concave candidate: project the query's world AABB into
-            // the candidate's body-local frame, decompose to triangles,
-            // run per-triangle GJK until one overlap is found.
-            aabb_world_to_local(
-                concave_query_aabb, 0,
-                world_aabb,
-                candidate_tr.position.x, candidate_tr.position.y, candidate_tr.position.z,
-                candidate_tr.rotation.x, candidate_tr.rotation.y, candidate_tr.rotation.z, candidate_tr.rotation.w
-            );
-
-            const tri_count = decompose_to_triangles(
-                triangle_buffer, 0, collider.shape,
-                concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
-                concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
-            );
-
-            // Re-pose candidate as the concave body, rebinding the
-            // flyweight triangle per iteration.
-            candidate_posed.shape = triangle_shape;
-            candidate_posed.px = candidate_tr.position.x;
-            candidate_posed.py = candidate_tr.position.y;
-            candidate_posed.pz = candidate_tr.position.z;
-            candidate_posed.qx = candidate_tr.rotation.x;
-            candidate_posed.qy = candidate_tr.rotation.y;
-            candidate_posed.qz = candidate_tr.rotation.z;
-            candidate_posed.qw = candidate_tr.rotation.w;
-
-            for (let t = 0; t < tri_count; t++) {
-                triangle_shape.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);
-                if (gjk(simplex_buf, query_posed, candidate_posed)) {
-                    overlaps = true;
-                    break;
-                }
-            }
-        }
-
-        if (overlaps) {
-            output[cursor] = body_id;
-            cursor++;
-            count++;
-        }
-    }
-
-    return count;
-}
+import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+import { returnTrue } from "../../../core/function/returnTrue.js";
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
+import { body_id_index } from "../body/BodyStorage.js";
+import { gjk } from "../gjk/gjk.js";
+import { aabb_world_to_local } from "../narrowphase/decomposition/aabb_world_to_local.js";
+import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
+import { PosedShape } from "../narrowphase/PosedShape.js";
+
+/**
+ * Scratch state — module-scoped to avoid per-query allocation. Safe
+ * because PhysicsSystem queries run on the main thread, sequentially.
+ */
+const local_aabb = new Float64Array(6);
+const world_aabb = new Float64Array(6);
+const concave_query_aabb = new Float64Array(6);
+const simplex_buf = new Float64Array(12);
+
+const query_posed = new PosedShape();
+const candidate_posed = new PosedShape();
+const triangle_shape = new Triangle3D();
+
+/**
+ * Maximum triangles a concave candidate can emit per overlap pair.
+ * Same rationale as the narrowphase's `MAX_TRIANGLES_PER_PAIR`: the
+ * broadphase has already bounded the query AABB to the query shape's
+ * envelope, so a single candidate typically yields tens of triangles
+ * (a heightmap's count scales O(N²) with its `tessellation`, still
+ * inside the buffer for a bounded query at moderate tessellation).
+ * Excess triangles are dropped by the enumerator's bounds check —
+ * worst case is a missed overlap on a far edge of the candidate's
+ * geometry, recovered next query.
+ * @type {number}
+ */
+const MAX_TRIANGLES_PER_PAIR = 1024;
+
+const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
+
+/**
+ * Broadphase candidate buffer. Grows by doubling on overflow.
+ * @type {Uint32Array}
+ */
+let scratch_candidates = new Uint32Array(64);
+
+/**
+ * Test what bodies overlap a convex shape placed at a given pose. Each
+ * overlapping body's `body_id` is written to `output` starting at
+ * `output_offset`; the function returns the number of body ids written.
+ *
+ * Use case: speculative physics queries for kinematic / character
+ * controllers. An external system can ask "would my body collide with
+ * anything if I moved it here?" without committing a tick of
+ * simulation. The output is a flat list of body ids so the caller can
+ * decide what to do per hit (skip, push, slide, etc.).
+ *
+ * The pipeline mirrors the narrowphase pair test:
+ *   1. Build the query shape's world AABB.
+ *   2. Pull candidates from both broadphase trees that overlap that AABB.
+ *   3. For each candidate, run GJK in world frame. Convex candidates
+ *      go through one GJK call; concave candidates (heightmap / mesh)
+ *      go through the per-triangle decomposition path.
+ *   4. Apply the optional `filter` callback (same signature as in
+ *      raycast / shapeCast) before the GJK test — early-out on bodies
+ *      the caller already wants to skip (themselves, allies, etc.).
+ *
+ * The query shape must be convex (`is_convex === true`). Concave shapes
+ * are typically static terrain and not used as kinematic query
+ * probes; rejecting them avoids the M×N triangle-pair cost.
+ *
+ * @param {PhysicsSystem} system
+ * @param {AbstractShape3D} shape  query shape, convex; expressed in
+ *   its own local frame
+ * @param {{x:number,y:number,z:number}} position world position of the
+ *   query shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
+ *   of the query shape (unit quaternion)
+ * @param {Uint32Array|number[]} output buffer to write body_ids into.
+ *   Caller is responsible for sizing it; ids past its end are dropped.
+ * @param {number} output_offset float-index in output to start writing at
+ * @param {(entity:number, collider:Collider)=>boolean} [filter]
+ *   defaults to {@link returnTrue} (accept every candidate)
+ * @returns {number} number of overlapping bodies written
+ * @throws {Error} if `shape.is_convex === false`
+ */
+export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
+    if (shape.is_convex === false) {
+        throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
+    }
+
+    // ── 1. Query shape's world AABB ─────────────────────────────────
+    shape.compute_bounding_box(local_aabb);
+    aabb3_transform_oriented(
+        world_aabb, 0,
+        local_aabb[0], local_aabb[1], local_aabb[2],
+        local_aabb[3], local_aabb[4], local_aabb[5],
+        position.x, position.y, position.z,
+        rotation.x, rotation.y, rotation.z, rotation.w
+    );
+
+    // ── 2. Gather broadphase candidates ─────────────────────────────
+    const n_static = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, 0, system.staticBvh, world_aabb
+    );
+    const n_dynamic = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, n_static, system.dynamicBvh, world_aabb
+    );
+    const n_total = n_static + n_dynamic;
+    if (n_total === 0) return 0;
+
+    // ── 3. Set up query PosedShape (constant across candidates) ─────
+    query_posed.setup(shape, position, rotation);
+
+    // ── 4. Per-candidate narrowphase ────────────────────────────────
+    const output_capacity = output.length - output_offset;
+    let count = 0;
+    let cursor = output_offset;
+
+    for (let i = 0; i < n_total; i++) {
+        if (count >= output_capacity) break;
+
+        const body_id = scratch_candidates[i];
+        const body_idx = body_id_index(body_id);
+
+        const entity = system.entityOf(body_id);
+        if (entity < 0) continue;
+
+        const collider = system.__primary_collider(body_idx);
+        if (collider === null) continue;
+        if (!filter(entity, collider)) continue;
+
+        const candidate_tr = system.__transforms[body_idx];
+
+        let overlaps = false;
+
+        if (collider.shape.is_convex !== false) {
+            candidate_posed.setup(collider.shape, candidate_tr.position, candidate_tr.rotation);
+            overlaps = gjk(simplex_buf, query_posed, candidate_posed);
+        } else {
+            // Concave candidate: project the query's world AABB into
+            // the candidate's body-local frame, decompose to triangles,
+            // run per-triangle GJK until one overlap is found.
+            aabb_world_to_local(
+                concave_query_aabb, 0,
+                world_aabb,
+                candidate_tr.position.x, candidate_tr.position.y, candidate_tr.position.z,
+                candidate_tr.rotation.x, candidate_tr.rotation.y, candidate_tr.rotation.z, candidate_tr.rotation.w
+            );
+
+            const tri_count = decompose_to_triangles(
+                triangle_buffer, 0, collider.shape,
+                concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
+                concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
+            );
+
+            // Re-pose candidate as the concave body, rebinding the
+            // flyweight triangle per iteration.
+            candidate_posed.shape = triangle_shape;
+            candidate_posed.px = candidate_tr.position.x;
+            candidate_posed.py = candidate_tr.position.y;
+            candidate_posed.pz = candidate_tr.position.z;
+            candidate_posed.qx = candidate_tr.rotation.x;
+            candidate_posed.qy = candidate_tr.rotation.y;
+            candidate_posed.qz = candidate_tr.rotation.z;
+            candidate_posed.qw = candidate_tr.rotation.w;
+
+            for (let t = 0; t < tri_count; t++) {
+                triangle_shape.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);
+                if (gjk(simplex_buf, query_posed, candidate_posed)) {
+                    overlaps = true;
+                    break;
+                }
+            }
+        }
+
+        if (overlaps) {
+            output[cursor] = body_id;
+            cursor++;
+            count++;
+        }
+    }
+
+    return count;
+}

package/src/engine/simulation/Ticker.d.ts

@@ -20,6 +20,20 @@ declare class Ticker {
      * @type {Clock}
      */
     readonly clock: 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: boolean;
     /**
      * Dispatches time delta in seconds since last tick
      * @readonly

package/src/engine/simulation/Ticker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAiBpB;;;;OAIG;IACH,iBAFU,OAAO,MAAM,CAAC,CAEF;IAUtB;;;OAGG;IACH,uBAFW,MAAM,QAgDhB;IAED,cAOC;IAED,eAQC;IAED,aAOC;;CACJ;kBArIiB,aAAa;mBADZ,oCAAoC"}
+{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAEpB;;;;;;;;;;;;OAYG;IACH,uBAFU,OAAO,CAEY;IAwB7B;;;;OAIG;IACH,iBAFU,OAAO,MAAM,CAAC,CAEF;IA+GtB;;;OAGG;IACH,uBAFW,MAAM,QAyDhB;IAED,cAOC;IAED,eAQC;IAED,aAUC;;CACJ;kBA5QiB,aAAa;mBADZ,oCAAoC"}

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;