@needle-tools/gltf-progressive 2.1.6 → 3.0.0-alpha.2

package/lib/extension.js

@@ -1,80 +1,15 @@
 import { BufferGeometry, Mesh, Texture, TextureLoader } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { addDracoAndKTX2Loaders } from "./loaders.js";
-import { getParam, resolveUrl } from "./utils.internal.js";
+import { resolveUrl } from "./utils.internal.js";
 import { getRaycastMesh, registerRaycastMesh } from "./utils.js";
 // All of this has to be removed
 // import { getRaycastMesh, setRaycastMesh } from "../../engine_physics.js";
 // import { PromiseAllWithErrors, resolveUrl } from "../../engine_utils.js";
 import { plugins } from "./plugins/plugin.js";
+import { debug } from "./lods.debug.js";
 export const EXTENSION_NAME = "NEEDLE_progressive";
-const debug = getParam("debugprogressive");
 const $progressiveTextureExtension = Symbol("needle-progressive-texture");
-const debug_toggle_maps = new Map();
-const debug_materials = new Set();
-if (debug) {
-    let currentDebugLodLevel = -1;
-    let maxLevel = 2;
-    let wireframe = false;
-    function debugToggleProgressive() {
-        currentDebugLodLevel += 1;
-        console.log("Toggle LOD level", currentDebugLodLevel, debug_toggle_maps);
-        debug_toggle_maps.forEach((arr, obj) => {
-            for (const key of arr.keys) {
-                const cur = obj[key];
-                // if it's null or undefined we skip it
-                if (cur == null) {
-                    continue;
-                }
-                if (cur.isBufferGeometry === true) {
-                    const info = NEEDLE_progressive.getMeshLODInformation(cur);
-                    const level = !info ? 0 : Math.min(currentDebugLodLevel, info.lods.length);
-                    obj["DEBUG:LOD"] = level;
-                    // NEEDLE_progressive.assignMeshLOD(obj as Mesh, level);
-                    if (info)
-                        maxLevel = Math.max(maxLevel, info.lods.length - 1);
-                }
-                else if (obj.isMaterial === true) {
-                    obj["DEBUG:LOD"] = currentDebugLodLevel;
-                    // NEEDLE_progressive.assignTextureLOD(obj as Material, currentDebugLodLevel);
-                }
-            }
-        });
-        if (currentDebugLodLevel >= maxLevel) {
-            currentDebugLodLevel = -1;
-        }
-    }
-    window.addEventListener("keyup", evt => {
-        if (evt.key === "p")
-            debugToggleProgressive();
-        if (evt.key === "w") {
-            wireframe = !wireframe;
-            if (debug_materials) {
-                debug_materials.forEach(mat => {
-                    // we don't want to change the skybox material
-                    if (mat.name == "BackgroundCubeMaterial")
-                        return;
-                    if (mat["glyphMap"] != undefined)
-                        return;
-                    if ("wireframe" in mat) {
-                        mat.wireframe = wireframe;
-                    }
-                });
-            }
-        }
-    });
-}
-function registerDebug(obj, key, sourceId) {
-    if (!debug)
-        return;
-    if (!debug_toggle_maps.has(obj)) {
-        debug_toggle_maps.set(obj, { keys: [], sourceId });
-    }
-    const existing = debug_toggle_maps.get(obj);
-    if (existing?.keys?.includes(key) == false) {
-        existing.keys.push(key);
-    }
-}
 /**
  * The NEEDLE_progressive extension for the GLTFLoader is responsible for loading progressive LODs for meshes and textures.
  * This extension can be used to load different resolutions of a mesh or texture at runtime (e.g. for LODs or progressive textures).
@@ -95,13 +30,19 @@ export class NEEDLE_progressive {
     get name() {
         return EXTENSION_NAME;
     }
-    static getMeshLODInformation(geo) {
+    static getMeshLODExtension(geo) {
         const info = this.getAssignedLODInformation(geo);
         if (info?.key) {
             return this.lodInfos.get(info.key);
         }
         return null;
     }
+    static getPrimitiveIndex(geo) {
+        const index = this.getAssignedLODInformation(geo)?.index;
+        if (index === undefined || index === null)
+            return -1;
+        return index;
+    }
     static getMaterialMinMaxLODsCount(material, minmax) {
         const self = this;
         // we can cache this material min max data because it wont change at runtime
@@ -261,8 +202,6 @@ export class NEEDLE_progressive {
                         // if (debug == "verbose") console.log("Progressive Mesh " + mesh.name + " loaded", currentGeometry, "→", geo, "\n", mesh)
                         if (isGeometry) {
                             mesh.geometry = geo;
-                            if (debug)
-                                registerDebug(mesh, "geometry", lodinfo.url);
                         }
                         else if (debug) {
                             console.error("Invalid LOD geometry", geo);
@@ -311,8 +250,6 @@ export class NEEDLE_progressive {
             const material = materialOrTexture;
             const promises = [];
             const slots = new Array();
-            if (debug)
-                debug_materials.add(material);
             // Handle custom shaders / uniforms progressive textures. This includes support for VRM shaders
             if (material.uniforms && (material.isRawShaderMaterial || material.isShaderMaterial === true)) {
                 // iterate uniforms of custom shaders
@@ -391,13 +328,6 @@ export class NEEDLE_progressive {
                         }
                         material[slot] = tex;
                     }
-                    if (debug && slot && material) {
-                        const lodinfo = this.getAssignedLODInformation(current);
-                        if (lodinfo)
-                            registerDebug(material, slot, lodinfo.url);
-                        else
-                            console.warn("No LOD info for texture", current);
-                    }
                     // check if the old texture is still used by other objects
                     // if not we dispose it...
                     // this could also be handled elsewhere and not be done immediately
@@ -440,7 +370,7 @@ export class NEEDLE_progressive {
         return this.parser.getDependency("mesh", meshIndex).then(mesh => {
             this._isLoadingMesh = false;
             if (mesh) {
-                NEEDLE_progressive.registerMesh(this.url, ext.guid, mesh, ext.lods?.length, undefined, ext);
+                NEEDLE_progressive.registerMesh(this.url, ext.guid, mesh, ext.lods?.length, 0, ext);
             }
             return mesh;
         });
@@ -522,7 +452,7 @@ export class NEEDLE_progressive {
         if (tex.source)
             tex.source[$progressiveTextureExtension] = ext;
         const LODKEY = ext.guid;
-        NEEDLE_progressive.assignLODInformation(url, tex, LODKEY, level, index, undefined);
+        NEEDLE_progressive.assignLODInformation(url, tex, LODKEY, level, index);
         NEEDLE_progressive.lodInfos.set(LODKEY, ext);
         NEEDLE_progressive.lowresCache.set(LODKEY, tex);
     };
@@ -530,8 +460,6 @@ export class NEEDLE_progressive {
      * Register a mesh with LOD information
      */
     static registerMesh = (url, key, mesh, level, index, ext) => {
-        if (debug)
-            console.log("> Progressive: register mesh", index, mesh.name, ext, mesh.uuid, mesh);
         const geometry = mesh.geometry;
         if (!geometry) {
             if (debug)
@@ -540,7 +468,9 @@ export class NEEDLE_progressive {
         }
         if (!geometry.userData)
             geometry.userData = {};
-        NEEDLE_progressive.assignLODInformation(url, geometry, key, level, index, ext.density);
+        if (debug)
+            console.log("> Progressive: register mesh " + mesh.name, { index, uuid: mesh.uuid }, ext, mesh);
+        NEEDLE_progressive.assignLODInformation(url, geometry, key, level, index);
         NEEDLE_progressive.lodInfos.set(key, ext);
         let existing = NEEDLE_progressive.lowresCache.get(key);
         if (existing)
@@ -695,7 +625,7 @@ export class NEEDLE_progressive {
                         if (found) {
                             let tex = await parser.getDependency("texture", index);
                             if (tex) {
-                                NEEDLE_progressive.assignLODInformation(LOD.url, tex, LODKEY, level, undefined, undefined);
+                                NEEDLE_progressive.assignLODInformation(LOD.url, tex, LODKEY, level, undefined);
                             }
                             if (debugverbose)
                                 console.log("change \"" + current.name + "\" → \"" + tex.name + "\"", lod_url, index, tex, KEY);
@@ -733,7 +663,7 @@ export class NEEDLE_progressive {
                                 console.log(`Loaded Mesh \"${mesh.name}\"`, lod_url, index, mesh, KEY);
                             if (mesh.isMesh === true) {
                                 const geo = mesh.geometry;
-                                NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, undefined, meshExt.density);
+                                NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, 0);
                                 return resolve(geo);
                             }
                             else {
@@ -742,7 +672,7 @@ export class NEEDLE_progressive {
                                     const child = mesh.children[i];
                                     if (child.isMesh === true) {
                                         const geo = child.geometry;
-                                        NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, i, meshExt.density);
+                                        NEEDLE_progressive.assignLODInformation(LOD.url, geo, LODKEY, level, i);
                                         geometries.push(geo);
                                     }
                                 }
@@ -786,12 +716,12 @@ export class NEEDLE_progressive {
         }
         return null;
     }
-    static assignLODInformation(url, res, key, level, index, density) {
+    static assignLODInformation(url, res, key, level, index) {
         if (!res)
             return;
         if (!res.userData)
             res.userData = {};
-        const info = new LODInformation(url, key, level, index, density);
+        const info = new LODInformation(url, key, level, index);
         res.userData.LODS = info;
     }
     static getAssignedLODInformation(res) {
@@ -848,16 +778,12 @@ class LODInformation {
     level;
     /** For multi objects (e.g. a group of meshes) this is the index of the object */
     index;
-    /** the mesh density */
-    density;
-    constructor(url, key, level, index, density) {
+    constructor(url, key, level, index) {
         this.url = url;
         this.key = key;
         this.level = level;
         if (index != undefined)
             this.index = index;
-        if (density != undefined)
-            this.density = density;
     }
 }
 ;

package/lib/index.d.ts

@@ -1,13 +1,13 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager, type LOD_Results } from "./lods_manager.js";
+export { LODsManager, type LOD_Results } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { WebGLRenderer } from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { SmartLoadingHints } from "./loaders.js";
-import { LODsManager } from "./lods_manager.js";
+import { LODsManager } from "./lods.manager.js";
 declare type UseNeedleGLTFProgressiveOptions = {
     /**
      * When set to true the LODs manager will automatically be enabled

package/lib/index.js

@@ -1,12 +1,12 @@
 export { version as VERSION } from "./version.js";
 export * from "./extension.js";
 export * from "./plugins/index.js";
-export { LODsManager } from "./lods_manager.js";
+export { LODsManager } from "./lods.manager.js";
 export { setDracoDecoderLocation, setKTX2TranscoderLocation, createLoaders, addDracoAndKTX2Loaders, configureLoader } from "./loaders.js";
 export { getRaycastMesh, registerRaycastMesh, useRaycastMeshes } from "./utils.js";
 import { addDracoAndKTX2Loaders, configureLoader, createLoaders } from "./loaders.js";
 import { NEEDLE_progressive } from "./extension.js";
-import { LODsManager } from "./lods_manager.js";
+import { LODsManager } from "./lods.manager.js";
 /** Use this function to enable progressive loading of gltf models.
  * @param url The url of the gltf model.
  * @param renderer The renderer of the scene.

package/lib/lods.debug.d.ts

@@ -0,0 +1,4 @@
+import { Material } from "three";
+export declare const debug: string | boolean;
+export declare let debug_OverrideLodLevel: number;
+export declare function applyDebugSettings(material: Material | Array<Material>): void;

package/lib/lods.debug.js

@@ -0,0 +1,41 @@
+import { getParam } from "./utils.internal.js";
+export const debug = getParam("debugprogressive");
+let debug_RenderWireframe;
+export let debug_OverrideLodLevel = -1; // -1 is automatic
+if (debug) {
+    let maxLevel = 6;
+    function debugToggleProgressive() {
+        debug_OverrideLodLevel += 1;
+        if (debug_OverrideLodLevel >= maxLevel) {
+            debug_OverrideLodLevel = -1;
+        }
+        console.log(`Toggle LOD level [${debug_OverrideLodLevel}]`);
+    }
+    window.addEventListener("keyup", evt => {
+        if (evt.key === "p")
+            debugToggleProgressive();
+        if (evt.key === "w") {
+            debug_RenderWireframe = !debug_RenderWireframe;
+            console.log(`Toggle wireframe [${debug_RenderWireframe}]`);
+        }
+        const pressedNumber = parseInt(evt.key);
+        if (!isNaN(pressedNumber) && pressedNumber >= 0) {
+            debug_OverrideLodLevel = pressedNumber;
+            console.log(`Set LOD level to [${debug_OverrideLodLevel}]`);
+        }
+    });
+}
+export function applyDebugSettings(material) {
+    if (!debug)
+        return;
+    if (Array.isArray(material)) {
+        for (const mat of material) {
+            applyDebugSettings(mat);
+        }
+    }
+    else if (material) {
+        if ("wireframe" in material) {
+            material.wireframe = debug_RenderWireframe === true;
+        }
+    }
+}

package/lib/{lods_manager.d.ts → lods.manager.d.ts}

@@ -1,5 +1,6 @@
-import { Camera, Material, Matrix4, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
+import { Camera, Material, Object3D, Scene, Texture, Vector3, WebGLRenderer } from "three";
 import { NEEDLE_progressive_plugin } from "./plugins/plugin.js";
+import { PromiseGroupOptions } from "./lods.promise.js";
 export type LODManagerContext = {
     engine: "three" | "needle-engine" | "model-viewer" | "react-three-fiber" | "unknown";
 };
@@ -43,9 +44,14 @@ declare type LODChangedEventListener = (args: {
  */
 export declare class LODsManager {
     #private;
-    /** Assign a function to draw debug lines for the LODs. This function will be called with the start and end position of the line and the color of the line when the `debugprogressive` query parameter is set.
+    /**
+     * Assign a function to draw debug lines for the LODs. This function will be called with the start and end position of the line and the color of the line when the `debugprogressive` query parameter is set.
      */
     static debugDrawLine?: (a: Vector3, b: Vector3, color: number) => void;
+    /**
+     * Force override the LOD level for all objects in the scene
+     */
+    static overrideGlobalLodLevel?: number;
     /** @internal */
     static getObjectLODState(object: Object3D): LOD_state | undefined;
     static addPlugin(plugin: NEEDLE_progressive_plugin): void;
@@ -56,9 +62,9 @@ export declare class LODsManager {
      * @returns The LODsManager instance.
      */
     static get(renderer: WebGLRenderer, context?: LODManagerContext): LODsManager;
-    private readonly context;
     readonly renderer: WebGLRenderer;
-    readonly projectionScreenMatrix: Matrix4;
+    private readonly context;
+    private readonly projectionScreenMatrix;
     /** @deprecated use static `LODsManager.addPlugin()` method. This getter will be removed in later versions */
     get plugins(): NEEDLE_progressive_plugin[];
     /**
@@ -88,6 +94,17 @@ export declare class LODsManager {
      * @default false
      */
     manual: boolean;
+    private readonly _newPromiseGroups;
+    private _promiseGroupIds;
+    /**
+     * Call to await LODs loading during the next render cycle.
+     */
+    awaitLoading(opts?: PromiseGroupOptions): Promise<{
+        cancelled: boolean;
+        awaited_count: number;
+        resolved_count: number;
+    }>;
+    private _postprocessPromiseGroups;
     private readonly _lodchangedlisteners;
     addEventListener(evt: "changed", listener: LODChangedEventListener): void;
     removeEventListener(evt: "changed", listener: LODChangedEventListener): void;

package/lib/{lods_manager.js → lods.manager.js}

@@ -1,9 +1,11 @@
 import { Box3, Clock, Matrix4, Mesh, MeshStandardMaterial, Sphere, Vector3 } from "three";
 import { NEEDLE_progressive } from "./extension.js";
 import { createLoaders } from "./loaders.js";
-import { getParam, isMobileDevice } from "./utils.internal.js";
+import { getParam, isDevelopmentServer, isMobileDevice } from "./utils.internal.js";
 import { plugins } from "./plugins/plugin.js";
 import { getRaycastMesh } from "./utils.js";
+import { applyDebugSettings, debug, debug_OverrideLodLevel } from "./lods.debug.js";
+import { PromiseGroup } from "./lods.promise.js";
 const debugProgressiveLoading = getParam("debugprogressive");
 const suppressProgressiveLoading = getParam("noprogressive");
 const $lodsManager = Symbol("Needle:LODSManager");
@@ -40,9 +42,14 @@ const levels = { mesh_lod: -1, texture_lod: -1 };
  * ```
  */
 export class LODsManager {
-    /** Assign a function to draw debug lines for the LODs. This function will be called with the start and end position of the line and the color of the line when the `debugprogressive` query parameter is set.
+    /**
+     * Assign a function to draw debug lines for the LODs. This function will be called with the start and end position of the line and the color of the line when the `debugprogressive` query parameter is set.
      */
     static debugDrawLine;
+    /**
+     * Force override the LOD level for all objects in the scene
+     */
+    static overrideGlobalLodLevel;
     /** @internal */
     static getObjectLODState(object) {
         return object[$lodstate];
@@ -72,8 +79,8 @@ export class LODsManager {
         renderer[$lodsManager] = lodsManager;
         return lodsManager;
     }
-    context;
     renderer;
+    context;
     projectionScreenMatrix = new Matrix4();
     /** @deprecated use static `LODsManager.addPlugin()` method. This getter will be removed in later versions */
     get plugins() { return plugins; }
@@ -105,6 +112,37 @@ export class LODsManager {
      * @default false
      */
     manual = false;
+    _newPromiseGroups = [];
+    _promiseGroupIds = 0;
+    /**
+     * Call to await LODs loading during the next render cycle.
+     */
+    awaitLoading(opts) {
+        const id = this._promiseGroupIds++;
+        const newGroup = new PromiseGroup(this.#frame, { ...opts, });
+        this._newPromiseGroups.push(newGroup);
+        const start = performance.now();
+        newGroup.ready.finally(() => {
+            const index = this._newPromiseGroups.indexOf(newGroup);
+            if (index >= 0) {
+                this._newPromiseGroups.splice(index, 1);
+                if (isDevelopmentServer())
+                    performance.measure("LODsManager:awaitLoading", {
+                        start,
+                        detail: { id, name: opts?.name, awaited: newGroup.awaitedCount, resolved: newGroup.resolvedCount }
+                    });
+            }
+        });
+        return newGroup.ready;
+    }
+    _postprocessPromiseGroups() {
+        if (this._newPromiseGroups.length === 0)
+            return;
+        for (let i = this._newPromiseGroups.length - 1; i >= 0; i--) {
+            const group = this._newPromiseGroups[i];
+            group.update(this.#frame);
+        }
+    }
     _lodchangedlisteners = [];
     addEventListener(evt, listener) {
         if (evt === "changed") {
@@ -226,6 +264,7 @@ export class LODsManager {
                 return;
             }
             this.internalUpdate(scene, camera);
+            this._postprocessPromiseGroups();
         }
     }
     /**
@@ -305,17 +344,26 @@ export class LODsManager {
         for (const plugin of plugins) {
             plugin.onBeforeUpdateLOD?.(this.renderer, scene, camera, object);
         }
-        this.calculateLodLevel(camera, object, state, desiredDensity, levels);
-        levels.mesh_lod = Math.round(levels.mesh_lod);
-        levels.texture_lod = Math.round(levels.texture_lod);
+        const debugLodLevel = LODsManager.overrideGlobalLodLevel !== undefined ? LODsManager.overrideGlobalLodLevel : debug_OverrideLodLevel;
+        if (debugLodLevel >= 0) {
+            levels.mesh_lod = debugLodLevel;
+            levels.texture_lod = debugLodLevel;
+        }
+        else {
+            this.calculateLodLevel(camera, object, state, desiredDensity, levels);
+            levels.mesh_lod = Math.round(levels.mesh_lod);
+            levels.texture_lod = Math.round(levels.texture_lod);
+        }
         // we currently only support auto LOD changes for meshes
         if (levels.mesh_lod >= 0) {
             this.loadProgressiveMeshes(object, levels.mesh_lod);
         }
         // TODO: we currently can not switch texture lods because we need better caching for the textures internally (see copySettings in progressive + NE-4431)
-        let textureLOD = levels.texture_lod;
-        if (object.material && textureLOD >= 0) {
-            this.loadProgressiveTextures(object.material, textureLOD);
+        if (object.material && levels.texture_lod >= 0) {
+            this.loadProgressiveTextures(object.material, levels.texture_lod);
+        }
+        if (debug && object.material && !object["isGizmo"]) {
+            applyDebugSettings(object.material);
         }
         for (const plugin of plugins) {
             plugin.onAfterUpdatedLOD?.(this.renderer, scene, camera, object, levels);
@@ -353,9 +401,10 @@ export class LODsManager {
         }
         if (update) {
             material[$currentLOD] = level;
-            NEEDLE_progressive.assignTextureLOD(material, level).then(_ => {
+            const promise = NEEDLE_progressive.assignTextureLOD(material, level).then(_ => {
                 this._lodchangedlisteners.forEach(l => l({ type: "texture", level, object: material }));
             });
+            PromiseGroup.addPromise("texture", promise, this._newPromiseGroups);
         }
     }
     /** Load progressive meshes for the given mesh
@@ -376,19 +425,14 @@ export class LODsManager {
         if (update) {
             mesh[$currentLOD] = level;
             const originalGeometry = mesh.geometry;
-            return NEEDLE_progressive.assignMeshLOD(mesh, level).then(res => {
+            const promise = NEEDLE_progressive.assignMeshLOD(mesh, level).then(res => {
                 if (res && mesh[$currentLOD] == level && originalGeometry != mesh.geometry) {
                     this._lodchangedlisteners.forEach(l => l({ type: "mesh", level, object: mesh }));
-                    // if (this.handles) {
-                    //     for (const inst of this.handles) {
-                    //         // if (inst["LOD"] < level) continue;
-                    //         // inst["LOD"] = level;
-                    //         inst.setGeometry(mesh.geometry);
-                    //     }
-                    // }
                 }
                 return res;
             });
+            PromiseGroup.addPromise("mesh", promise, this._newPromiseGroups);
+            return promise;
         }
         return Promise.resolve(null);
     }
@@ -435,8 +479,8 @@ export class LODsManager {
             return mesh["DEBUG:LOD"];
         }
         // The mesh info contains also the density for all available LOD level so we can use this for selecting which level to show
-        const mesh_lods_info = NEEDLE_progressive.getMeshLODInformation(mesh.geometry);
-        const mesh_lods = mesh_lods_info?.lods;
+        const mesh_lods = NEEDLE_progressive.getMeshLODExtension(mesh.geometry)?.lods;
+        const primitive_index = NEEDLE_progressive.getPrimitiveIndex(mesh.geometry);
         const has_mesh_lods = mesh_lods && mesh_lods.length > 0;
         const texture_lods_minmax = NEEDLE_progressive.getMaterialMinMaxLODsCount(mesh.material);
         const has_texture_lods = texture_lods_minmax?.min_count != Infinity && texture_lods_minmax.min_count > 0 && texture_lods_minmax.max_count > 0;
@@ -590,7 +634,8 @@ export class LODsManager {
             // const framerate = this.context.time.smoothedFps;
             if (mesh_lods && state.lastScreenCoverage > 0) {
                 for (let l = 0; l < mesh_lods.length; l++) {
-                    const densityForThisLevel = mesh_lods[l].density;
+                    const lod = mesh_lods[l];
+                    const densityForThisLevel = lod.densities?.[primitive_index] || lod.density || .00001;
                     const resultingDensity = densityForThisLevel / state.lastScreenCoverage;
                     if (resultingDensity < desiredDensity) {
                         expectedLevel = l;

package/lib/lods.promise.d.ts

@@ -0,0 +1,50 @@
+type PromiseType = "texture" | "mesh";
+export type PromiseGroupOptions = {
+    name?: string;
+    /** How many renderer frames can requests be captured to be awaited */
+    frames?: number;
+    signal?: AbortSignal;
+};
+type PromiseGroupResolveResult = {
+    /**
+     * `true` if the group was cancelled, `false` if it was resolved normally.
+     */
+    cancelled: boolean;
+    /**
+     * The number of promises that started to being awaited
+     */
+    awaited_count: number;
+    /**
+     * The number of promises that were resolved
+    */
+    resolved_count: number;
+};
+/**
+ * A group of promises that can be awaited together.
+ * This is used for awaiting LOD
+ */
+export declare class PromiseGroup {
+    static readonly addPromise: (type: PromiseType, promise: Promise<any>, groups: PromiseGroup[]) => void;
+    readonly frame_start: number;
+    readonly frame_capture_end: number;
+    readonly ready: Promise<PromiseGroupResolveResult>;
+    private _resolve;
+    private readonly _signal?;
+    /**
+     * The number of promises that have been added to this group so far.
+     */
+    get awaitedCount(): number;
+    get resolvedCount(): number;
+    get currentlyAwaiting(): number;
+    private _resolved;
+    private _addedCount;
+    private _resolvedCount;
+    /** These promises are currently being awaited */
+    private readonly _awaiting;
+    constructor(frame: number, options: PromiseGroupOptions);
+    private _currentFrame;
+    update(frame: number): void;
+    private add;
+    private resolveNow;
+}
+export {};

package/lib/lods.promise.js

@@ -0,0 +1,82 @@
+/**
+ * A group of promises that can be awaited together.
+ * This is used for awaiting LOD
+ */
+export class PromiseGroup {
+    static addPromise = (type, promise, groups) => {
+        groups.forEach(group => {
+            group.add(type, promise);
+        });
+    };
+    frame_start;
+    frame_capture_end;
+    ready;
+    _resolve;
+    _signal;
+    /**
+     * The number of promises that have been added to this group so far.
+     */
+    get awaitedCount() {
+        return this._addedCount;
+    }
+    get resolvedCount() {
+        return this._resolvedCount;
+    }
+    get currentlyAwaiting() {
+        return this._awaiting.length;
+    }
+    _resolved = false;
+    _addedCount = 0;
+    _resolvedCount = 0;
+    /** These promises are currently being awaited */
+    _awaiting = [];
+    constructor(frame, options) {
+        const minFrames = 2; // wait at least 2 frames to capture promises
+        const framesToCapture = Math.max(options.frames ?? minFrames, minFrames); // default to 2 frames and make sure it's at least 2 frames
+        this.frame_start = frame;
+        this.frame_capture_end = frame + framesToCapture;
+        this.ready = new Promise((resolve) => {
+            this._resolve = resolve;
+        });
+        this.ready.finally(() => {
+            this._resolved = true;
+            this._awaiting.length = 0;
+        });
+        this._signal = options.signal;
+        this._signal?.addEventListener("abort", () => {
+            this.resolveNow();
+        });
+    }
+    _currentFrame = 0;
+    update(frame) {
+        this._currentFrame = frame;
+        // If we've passes the frame capture end frame and didn't add any promises, we resolve immediately
+        if (this._signal?.aborted || (this._currentFrame > this.frame_capture_end && this._awaiting.length === 0)) {
+            this.resolveNow();
+        }
+    }
+    add(_type, promise) {
+        if (this._resolved) {
+            console.warn("PromiseGroup: Trying to add a promise to a resolved group, ignoring.");
+            return;
+        }
+        if (this._currentFrame > this.frame_capture_end) {
+            return; // we are not capturing any more promises
+        }
+        this._awaiting.push(promise);
+        this._addedCount++;
+        promise.finally(() => {
+            this._resolvedCount++;
+            this._awaiting.splice(this._awaiting.indexOf(promise), 1);
+        });
+    }
+    resolveNow() {
+        if (this._resolved)
+            return;
+        this._resolve?.({
+            awaited_count: this._addedCount,
+            resolved_count: this._resolvedCount,
+            cancelled: this._signal?.aborted ?? false,
+        });
+    }
+}

package/lib/plugins/modelviewer.js

@@ -1,4 +1,4 @@
-import { LODsManager } from "../lods_manager.js";
+import { LODsManager } from "../lods.manager.js";
 import { EXTENSION_NAME, NEEDLE_progressive } from "../extension.js";
 const $meshLODSymbol = Symbol("NEEDLE_mesh_lod");
 const $textureLODSymbol = Symbol("NEEDLE_texture_lod");