@needle-tools/gltf-progressive 3.5.0-rc → 3.6.0-alpha.2

package/lib/extension.d.ts

@@ -24,6 +24,10 @@ type TextureLODsMinMaxInfo = {
         max_height: number;
     }>;
 };
+export type AssignTextureLODOptions = {
+    /** Force the exact requested level. Intended for explicit/debug LOD overrides. */
+    force?: boolean;
+};
 /**
  * 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).
@@ -42,8 +46,31 @@ type TextureLODsMinMaxInfo = {
 export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     /** The name of the extension */
     get name(): string;
+    /**
+     * Get the progressive mesh LOD extension data associated with a geometry.
+     * Returns the extension metadata (available LOD levels, vertex/index counts, densities) if the geometry was registered with progressive LODs, or `null` otherwise.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The mesh LOD extension data, or `null` if no progressive LODs are registered for this geometry.
+     */
     static getMeshLODExtension(geo: BufferGeometry): NEEDLE_ext_progressive_mesh | null;
+    /**
+     * Get the glTF primitive index for a geometry within its parent mesh.
+     * A single glTF mesh node can contain multiple primitives (sub-geometries). This returns which primitive the geometry corresponds to.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The zero-based primitive index, or `-1` if no LOD information is assigned to this geometry.
+     */
     static getPrimitiveIndex(geo: BufferGeometry): number;
+    /**
+     * Compute the minimum and maximum number of texture LOD levels across all textures of a material (or array of materials).
+     * Iterates over all texture slots on the material and collects LOD count ranges and per-level resolution bounds.
+     * Results are cached on the material so subsequent calls are free.
+     *
+     * @param material - A single material or an array of materials to inspect.
+     * @param minmax - Optional accumulator to merge results into (used internally for recursive calls with material arrays).
+     * @returns An object with `min_count` / `max_count` (the range of LOD levels across all textures) and a per-level `lods` array with `min_height` / `max_height`.
+     */
     static getMaterialMinMaxLODsCount(material: Material | Material[], minmax?: TextureLODsMinMaxInfo): TextureLODsMinMaxInfo;
     /** Check if a LOD level is available for a mesh or a texture
      * @param obj the mesh or texture to check
@@ -65,7 +92,10 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
      * });
      * ```
      */
-    static assignMeshLOD(mesh: Mesh, level: number): Promise<BufferGeometry | null>;
+    static assignMeshLOD(mesh: Mesh, level: number, options?: {
+        /** If false, load and return the requested geometry without assigning it to the mesh. Pass a function to apply it manually. */
+        apply?: boolean | ((geometry: BufferGeometry, level: number, mesh: Mesh) => boolean | void);
+    }): Promise<BufferGeometry | null>;
     /** Load a different resolution of a texture (if available)
      * @param context the context
      * @param source the sourceid of the file from which the texture is loaded (this is usually the component's sourceId)
@@ -73,9 +103,9 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
      * @param level the level of detail to load (0 is the highest resolution) - currently only 0 is supported
      * @returns a promise that resolves to the material or texture with the requested LOD level
      */
-    static assignTextureLOD(materialOrTexture: Material, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
-    static assignTextureLOD(materialOrTexture: Mesh, level: number): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
-    static assignTextureLOD(materialOrTexture: Texture, level: number): Promise<Texture | null>;
+    static assignTextureLOD(materialOrTexture: Material, level: number, options?: AssignTextureLODOptions): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
+    static assignTextureLOD(materialOrTexture: Mesh, level: number, options?: AssignTextureLODOptions): Promise<Array<ProgressiveMaterialTextureLoadingResult> | null>;
+    static assignTextureLOD(materialOrTexture: Texture, level: number, options?: AssignTextureLODOptions): Promise<Texture | null>;
     /**
      * Set the maximum number of concurrent loading tasks for LOD resources. This limits how many LOD resources (meshes or textures) can be loaded at the same time to prevent overloading the network or GPU. If the limit is reached, additional loading requests will be queued and processed as previous ones finish.
      * @default 50 on desktop, 20 on mobile devices
@@ -83,6 +113,16 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     static set maxConcurrentLoadingTasks(value: number);
     static get maxConcurrentLoadingTasks(): number;
     private static assignTextureLODForSlot;
+    private static trackedTextureSlots;
+    private static pendingTextureSlotRequests;
+    private static trackCurrentMaterialTextureSlots;
+    private static getPendingTextureSlotRequest;
+    private static setPendingTextureSlotRequest;
+    private static getMaterialTextureSlot;
+    private static setMaterialTextureSlot;
+    private static assignTrackedTextureSlot;
+    private static ensureTrackedTextureSlot;
+    private static releaseTrackedTextureSlot;
     private readonly parser;
     private readonly url;
     constructor(parser: GLTFParser);
@@ -90,11 +130,29 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     loadMesh: (meshIndex: number) => Promise<any> | null;
     afterRoot(gltf: GLTF): null;
     /**
-     * Register a texture with LOD information
+     * Register a texture with progressive LOD information. This associates the texture with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower resolution versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     *
+     * @param url - The source URL of the glTF file this texture was loaded from.
+     * @param tex - The three.js Texture instance to register.
+     * @param level - The LOD level this texture represents (0 = highest resolution).
+     * @param index - The texture index within the glTF file.
+     * @param ext - The parsed progressive texture extension data containing all available LOD levels and their dimensions.
      */
     static registerTexture: (url: string, tex: Texture, level: number, index: number, ext: NEEDLE_ext_progressive_texture) => void;
     /**
-     * Register a mesh with LOD information
+     * Register a mesh with progressive LOD information. This associates the mesh geometry with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower density versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     * If the mesh is registered at a level > 0 (i.e. not full resolution), a raycast mesh is automatically preserved for accurate picking.
+     *
+     * @param url - The source URL of the glTF file this mesh was loaded from.
+     * @param key - A unique key identifying this mesh's LOD group (typically derived from the extension GUID).
+     * @param mesh - The three.js Mesh instance to register.
+     * @param level - The LOD level this mesh represents (0 = highest resolution / full density).
+     * @param index - The primitive index within the glTF mesh node.
+     * @param ext - The parsed progressive mesh extension data containing all available LOD levels with vertex/index counts and densities.
      */
     static registerMesh: (url: string, key: string, mesh: Mesh, level: number, index: number, ext: NEEDLE_ext_progressive_mesh) => void;
     /**
@@ -134,6 +192,7 @@ export declare class NEEDLE_progressive implements GLTFLoaderPlugin {
     private static readonly workers;
     private static _workersIndex;
     private static getOrLoadLOD;
+    private static tryResolveLODCacheEntry;
     private static _queue;
     private static get queue();
     private static assignLODInformation;

package/lib/extension.js

@@ -36,6 +36,13 @@ export class NEEDLE_progressive {
         return EXTENSION_NAME;
     }
     // #region PUBLIC API
+    /**
+     * Get the progressive mesh LOD extension data associated with a geometry.
+     * Returns the extension metadata (available LOD levels, vertex/index counts, densities) if the geometry was registered with progressive LODs, or `null` otherwise.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The mesh LOD extension data, or `null` if no progressive LODs are registered for this geometry.
+     */
     static getMeshLODExtension(geo) {
         const info = this.getAssignedLODInformation(geo);
         if (info?.key) {
@@ -43,12 +50,28 @@ export class NEEDLE_progressive {
         }
         return null;
     }
+    /**
+     * Get the glTF primitive index for a geometry within its parent mesh.
+     * A single glTF mesh node can contain multiple primitives (sub-geometries). This returns which primitive the geometry corresponds to.
+     *
+     * @param geo - The buffer geometry to look up.
+     * @returns The zero-based primitive index, or `-1` if no LOD information is assigned to this geometry.
+     */
     static getPrimitiveIndex(geo) {
         const index = this.getAssignedLODInformation(geo)?.index;
         if (index === undefined || index === null)
             return -1;
         return index;
     }
+    /**
+     * Compute the minimum and maximum number of texture LOD levels across all textures of a material (or array of materials).
+     * Iterates over all texture slots on the material and collects LOD count ranges and per-level resolution bounds.
+     * Results are cached on the material so subsequent calls are free.
+     *
+     * @param material - A single material or an array of materials to inspect.
+     * @param minmax - Optional accumulator to merge results into (used internally for recursive calls with material arrays).
+     * @returns An object with `min_count` / `max_count` (the range of LOD levels across all textures) and a per-level `lods` array with `min_height` / `max_height`.
+     */
     static getMaterialMinMaxLODsCount(material, minmax) {
         const self = this;
         // we can cache this material min max data because it wont change at runtime
@@ -186,7 +209,7 @@ export class NEEDLE_progressive {
      * });
      * ```
      */
-    static assignMeshLOD(mesh, level) {
+    static assignMeshLOD(mesh, level, options) {
         if (!mesh)
             return Promise.resolve(null);
         if (mesh instanceof Mesh || mesh.isMesh === true) {
@@ -210,11 +233,16 @@ export class NEEDLE_progressive {
                     if (geo && currentGeometry != geo) {
                         const isGeometry = geo?.isBufferGeometry;
                         // if (debug == "verbose") console.log("Progressive Mesh " + mesh.name + " loaded", currentGeometry, "→", geo, "\n", mesh)
-                        if (isGeometry) {
-                            mesh.geometry = geo;
+                        if (!isGeometry) {
+                            if (debug) {
+                                console.error("Invalid LOD geometry", geo);
+                            }
                         }
-                        else if (debug) {
-                            console.error("Invalid LOD geometry", geo);
+                        else if (typeof options?.apply === "function") {
+                            options.apply(geo, level, mesh);
+                        }
+                        else if (options?.apply !== false) {
+                            mesh.geometry = geo;
                         }
                     }
                 }
@@ -231,15 +259,16 @@ export class NEEDLE_progressive {
         }
         return Promise.resolve(null);
     }
-    static assignTextureLOD(materialOrTexture, level = 0) {
+    static assignTextureLOD(materialOrTexture, level = 0, options) {
         if (!materialOrTexture)
             return Promise.resolve(null);
+        const force = options?.force === true;
         if (materialOrTexture.isMesh === true) {
             const mesh = materialOrTexture;
             if (Array.isArray(mesh.material)) {
                 const arr = new Array();
                 for (const mat of mesh.material) {
-                    const promise = this.assignTextureLOD(mat, level);
+                    const promise = this.assignTextureLOD(mat, level, options);
                     arr.push(promise);
                 }
                 return Promise.all(arr).then(res => {
@@ -253,13 +282,14 @@ export class NEEDLE_progressive {
                 });
             }
             else {
-                return this.assignTextureLOD(mesh.material, level);
+                return this.assignTextureLOD(mesh.material, level, options);
             }
         }
         if (materialOrTexture.isMaterial === true) {
             const material = materialOrTexture;
             const promises = [];
             const slots = new Array();
+            this.trackCurrentMaterialTextureSlots(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
@@ -267,7 +297,7 @@ export class NEEDLE_progressive {
                 for (const slot of Object.keys(shaderMaterial.uniforms)) {
                     const val = shaderMaterial.uniforms[slot].value;
                     if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot).then(res => {
+                        const task = this.assignTextureLODForSlot(val, level, material, slot, force).then(res => {
                             if (res && shaderMaterial.uniforms[slot].value != res) {
                                 shaderMaterial.uniforms[slot].value = res;
                                 shaderMaterial.uniformsNeedUpdate = true;
@@ -283,7 +313,7 @@ export class NEEDLE_progressive {
                 for (const slot of Object.keys(material)) {
                     const val = material[slot];
                     if (val?.isTexture === true) {
-                        const task = this.assignTextureLODForSlot(val, level, material, slot);
+                        const task = this.assignTextureLODForSlot(val, level, material, slot, force);
                         promises.push(task);
                         slots.push(slot);
                     }
@@ -306,7 +336,7 @@ export class NEEDLE_progressive {
         }
         if (materialOrTexture instanceof Texture || materialOrTexture.isTexture === true) {
             const texture = materialOrTexture;
-            return this.assignTextureLODForSlot(texture, level, null, null);
+            return this.assignTextureLODForSlot(texture, level, null, null, force);
         }
         return Promise.resolve(null);
     }
@@ -321,14 +351,29 @@ export class NEEDLE_progressive {
         return NEEDLE_progressive.queue.maxConcurrent;
     }
     // #region INTERNAL
-    static assignTextureLODForSlot(current, level, material, slot) {
+    static assignTextureLODForSlot(current, level, material, slot, force) {
         if (current?.isTexture !== true) {
             return Promise.resolve(null);
         }
         if (slot === "glyphMap") {
             return Promise.resolve(current);
         }
-        return NEEDLE_progressive.getOrLoadLOD(current, level).then(tex => {
+        const currentLOD = this.getAssignedLODInformation(current);
+        if (currentLOD) {
+            if (currentLOD.level === level) {
+                return Promise.resolve(current);
+            }
+            if (!force && currentLOD.level < level) {
+                return Promise.resolve(current);
+            }
+        }
+        if (material && slot) {
+            const pending = this.getPendingTextureSlotRequest(material, slot);
+            if (pending && pending.level === level && pending.force === force) {
+                return pending.promise;
+            }
+        }
+        const promise = NEEDLE_progressive.getOrLoadLOD(current, level).then(tex => {
             // this can currently not happen
             if (Array.isArray(tex)) {
                 console.warn("Progressive: Got an array of textures for a texture slot, this should not happen...");
@@ -337,40 +382,19 @@ export class NEEDLE_progressive {
             if (tex?.isTexture === true) {
                 if (tex != current) {
                     if (material && slot) {
-                        const assigned = material[slot];
+                        const assigned = this.getMaterialTextureSlot(material, slot) ?? current;
                         // Check if the assigned texture LOD is higher quality than the current LOD
                         // This is necessary for cases where e.g. a texture is updated via an explicit call to assignTextureLOD
-                        if (assigned && !debug) {
+                        if (assigned && !force) {
                             const assignedLOD = this.getAssignedLODInformation(assigned);
                             if (assignedLOD && assignedLOD?.level < level) {
                                 if (debug === "verbose")
                                     console.warn("Assigned texture level is already higher: ", assignedLOD.level, level, material, assigned, tex);
-                                // Dispose the newly loaded texture since we're not using it
-                                // (the assigned texture is higher quality, so we reject the new one)
-                                // Note: We dispose directly here (not via untrackTextureUsage) because this texture
-                                // was never tracked/used - it was rejected immediately upon loading
-                                if (tex && tex !== assigned) {
-                                    if (debug || debugGC) {
-                                        console.log(`[gltf-progressive] Disposing rejected lower-quality texture LOD ${level} (assigned is ${assignedLOD.level})`, tex.uuid);
-                                    }
-                                    tex.dispose();
-                                }
                                 return null;
                             }
                             // assigned.dispose();
                         }
-                        // Track reference count for new texture
-                        this.trackTextureUsage(tex);
-                        // Untrack the old texture (may dispose if ref count hits 0)
-                        // This prevents accumulation of GPU VRAM while waiting for garbage collection
-                        if (assigned && assigned !== tex) {
-                            const wasDisposed = this.untrackTextureUsage(assigned);
-                            if (wasDisposed && (debug || debugGC)) {
-                                const assignedLOD = this.getAssignedLODInformation(assigned);
-                                console.log(`[gltf-progressive] Disposed old texture LOD ${assignedLOD?.level ?? '?'} → ${level} for ${material.name || material.type}.${slot}`, assigned.uuid);
-                            }
-                        }
-                        material[slot] = tex;
+                        this.assignTrackedTextureSlot(material, slot, tex);
                     }
                     // Note: We use reference counting above to track texture usage across multiple materials.
                     // When the reference count hits zero, GPU memory (VRAM) is freed immediately via gl.deleteTexture(),
@@ -390,6 +414,129 @@ export class NEEDLE_progressive {
             console.error("Error loading LOD", current, err);
             return null;
         });
+        if (material && slot) {
+            this.setPendingTextureSlotRequest(material, slot, level, force, promise);
+        }
+        return promise;
+    }
+    // Track material slots, not just texture objects. A shared fallback texture can be
+    // referenced by many slots and should only be disposed after every slot moved away.
+    static trackedTextureSlots = new WeakMap();
+    static pendingTextureSlotRequests = new WeakMap();
+    static trackCurrentMaterialTextureSlots(material) {
+        if (material.uniforms && (material.isRawShaderMaterial || material.isShaderMaterial === true)) {
+            const shaderMaterial = material;
+            for (const slot of Object.keys(shaderMaterial.uniforms)) {
+                const value = shaderMaterial.uniforms[slot].value;
+                if (value?.isTexture === true) {
+                    this.ensureTrackedTextureSlot(material, slot, value);
+                }
+            }
+            return;
+        }
+        for (const slot of Object.keys(material)) {
+            const value = material[slot];
+            if (value?.isTexture === true) {
+                this.ensureTrackedTextureSlot(material, slot, value);
+            }
+        }
+    }
+    static getPendingTextureSlotRequest(material, slot) {
+        return this.pendingTextureSlotRequests.get(material)?.get(slot);
+    }
+    static setPendingTextureSlotRequest(material, slot, level, force, promise) {
+        let slots = this.pendingTextureSlotRequests.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.pendingTextureSlotRequests.set(material, slots);
+        }
+        const request = { level, force, promise };
+        slots.set(slot, request);
+        promise.finally(() => {
+            const current = slots.get(slot);
+            if (current === request) {
+                slots.delete(slot);
+            }
+        });
+    }
+    static getMaterialTextureSlot(material, slot) {
+        const uniforms = material.uniforms;
+        const uniform = uniforms?.[slot];
+        if (uniform?.value?.isTexture === true) {
+            return uniform.value;
+        }
+        const value = material[slot];
+        if (value?.isTexture === true) {
+            return value;
+        }
+        return null;
+    }
+    static setMaterialTextureSlot(material, slot, texture) {
+        const uniforms = material.uniforms;
+        const uniform = uniforms?.[slot];
+        if (uniform?.value?.isTexture === true) {
+            uniform.value = texture;
+            material.uniformsNeedUpdate = true;
+            return;
+        }
+        material[slot] = texture;
+    }
+    static assignTrackedTextureSlot(material, slot, texture) {
+        let slots = this.trackedTextureSlots.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.trackedTextureSlots.set(material, slots);
+        }
+        const assigned = this.getMaterialTextureSlot(material, slot);
+        let previousTracked = slots.get(slot);
+        if (!previousTracked && assigned) {
+            previousTracked = this.ensureTrackedTextureSlot(material, slot, assigned);
+        }
+        else if (previousTracked && assigned && previousTracked !== assigned) {
+            this.releaseTrackedTextureSlot(material, slot, previousTracked);
+            previousTracked = this.ensureTrackedTextureSlot(material, slot, assigned);
+        }
+        if (previousTracked === texture && assigned === texture) {
+            return;
+        }
+        if (previousTracked && previousTracked !== texture) {
+            this.releaseTrackedTextureSlot(material, slot, previousTracked);
+        }
+        if (previousTracked !== texture) {
+            this.trackTextureUsage(texture);
+            slots.set(slot, texture);
+        }
+        if (assigned !== texture) {
+            this.setMaterialTextureSlot(material, slot, texture);
+        }
+    }
+    static ensureTrackedTextureSlot(material, slot, texture) {
+        let slots = this.trackedTextureSlots.get(material);
+        if (!slots) {
+            slots = new Map();
+            this.trackedTextureSlots.set(material, slots);
+        }
+        const previous = slots.get(slot);
+        if (previous === texture) {
+            return previous;
+        }
+        if (previous) {
+            this.releaseTrackedTextureSlot(material, slot, previous);
+        }
+        this.trackTextureUsage(texture);
+        slots.set(slot, texture);
+        return texture;
+    }
+    static releaseTrackedTextureSlot(material, slot, texture) {
+        const slots = this.trackedTextureSlots.get(material);
+        if (slots?.get(slot) === texture) {
+            slots.delete(slot);
+        }
+        const wasDisposed = this.untrackTextureUsage(texture);
+        if (wasDisposed && (debug || debugGC)) {
+            const assignedLOD = this.getAssignedLODInformation(texture);
+            console.log(`[gltf-progressive] Disposed old texture LOD ${assignedLOD?.level ?? '?'} for ${material.name || material.type}.${slot}`, texture.uuid);
+        }
     }
     parser;
     url;
@@ -492,7 +639,15 @@ export class NEEDLE_progressive {
         return null;
     }
     /**
-     * Register a texture with LOD information
+     * Register a texture with progressive LOD information. This associates the texture with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower resolution versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     *
+     * @param url - The source URL of the glTF file this texture was loaded from.
+     * @param tex - The three.js Texture instance to register.
+     * @param level - The LOD level this texture represents (0 = highest resolution).
+     * @param index - The texture index within the glTF file.
+     * @param ext - The parsed progressive texture extension data containing all available LOD levels and their dimensions.
      */
     static registerTexture = (url, tex, level, index, ext) => {
         if (!tex) {
@@ -515,7 +670,17 @@ export class NEEDLE_progressive {
         NEEDLE_progressive.lowresCache.set(key, new WeakRef(tex));
     };
     /**
-     * Register a mesh with LOD information
+     * Register a mesh with progressive LOD information. This associates the mesh geometry with its LOD extension data
+     * so the LODs manager can later swap it for higher or lower density versions based on screen coverage.
+     * Typically called during glTF loading when the progressive extension is parsed.
+     * If the mesh is registered at a level > 0 (i.e. not full resolution), a raycast mesh is automatically preserved for accurate picking.
+     *
+     * @param url - The source URL of the glTF file this mesh was loaded from.
+     * @param key - A unique key identifying this mesh's LOD group (typically derived from the extension GUID).
+     * @param mesh - The three.js Mesh instance to register.
+     * @param level - The LOD level this mesh represents (0 = highest resolution / full density).
+     * @param index - The primitive index within the glTF mesh node.
+     * @param ext - The parsed progressive mesh extension data containing all available LOD levels with vertex/index counts and densities.
      */
     static registerMesh = (url, key, mesh, level, index, ext) => {
         const geometry = mesh.geometry;
@@ -604,6 +769,8 @@ export class NEEDLE_progressive {
             this.cache.clear();
             // Clear all texture reference counts when disposing everything
             this.textureRefCounts.clear();
+            this.trackedTextureSlots = new WeakMap();
+            this.pendingTextureSlotRequests = new WeakMap();
         }
     }
     /** Dispose a single cache entry's three.js resource(s) to free GPU memory. */
@@ -710,8 +877,8 @@ export class NEEDLE_progressive {
             return false;
         }
         function logDebugInfo(prefix, newCount) {
-            let width = texture.image?.width || texture.source?.data?.width || 0;
-            let height = texture.image?.height || texture.source?.data?.height || 0;
+            const width = texture.image?.width || texture.source?.data?.width || 0;
+            const height = texture.image?.height || texture.source?.data?.height || 0;
             const textureSize = width && height ? `${width}x${height}` : "N/A";
             let memorySize = "N/A";
             if (width && height) {
@@ -791,76 +958,16 @@ export class NEEDLE_progressive {
                 }
                 // check if the requested file has already been loaded
                 const KEY = lod_url + "_" + lodInfo.guid;
-                const slot = await this.queue.slot(lod_url);
                 // check if the requested file is currently being loaded or was previously loaded
-                const existing = this.cache.get(KEY);
-                if (existing !== undefined) {
-                    if (debugverbose)
-                        console.log(`LOD ${level} was already loading/loaded: ${KEY}`);
-                    if (existing instanceof WeakRef) {
-                        // Previously resolved resource — check if still alive in memory
-                        const derefed = existing.deref();
-                        if (derefed) {
-                            let res = derefed;
-                            let resourceIsDisposed = false;
-                            if (res instanceof Texture && current instanceof Texture) {
-                                if (res.image?.data || res.source?.data) {
-                                    res = this.copySettings(current, res);
-                                }
-                                else {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                                if (!res.attributes.position?.array) {
-                                    resourceIsDisposed = true;
-                                }
-                            }
-                            if (!resourceIsDisposed) {
-                                return res;
-                            }
-                        }
-                        // Resource was garbage collected or disposed — remove stale entry and re-load
-                        this.cache.delete(KEY);
-                        if (debug)
-                            console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${KEY}`);
-                    }
-                    else {
-                        // Promise — loading in progress or previously completed
-                        let res = await existing.catch(err => {
-                            console.error(`Error loading LOD ${level} from ${lod_url}\n`, err);
-                            return null;
-                        });
-                        let resouceIsDisposed = false;
-                        if (res == null) {
-                            // if the resource is null the last loading result didnt succeed (maybe because the url doesnt exist)
-                            // in which case we don't attempt to load it again
-                        }
-                        else if (res instanceof Texture && current instanceof Texture) {
-                            // check if the texture has been disposed or not
-                            if (res.image?.data || res.source?.data) {
-                                res = this.copySettings(current, res);
-                            }
-                            // if it has been disposed we need to load it again
-                            else {
-                                resouceIsDisposed = true;
-                                this.cache.delete(KEY);
-                            }
-                        }
-                        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
-                            if (res.attributes.position?.array) {
-                                // the geometry is OK
-                            }
-                            else {
-                                resouceIsDisposed = true;
-                                this.cache.delete(KEY);
-                            }
-                        }
-                        if (!resouceIsDisposed) {
-                            return res;
-                        }
-                    }
-                }
+                const cached = await this.tryResolveLODCacheEntry(this.cache.get(KEY), KEY, lod_url, current, level, debugverbose);
+                if (cached.found)
+                    return cached.value;
+                const slot = await this.queue.slot(lod_url);
+                // Another request can fill the cache while this one waits for a queue slot.
+                // Re-checking here avoids duplicate loads for heavily instanced assets.
+                const cachedAfterQueue = await this.tryResolveLODCacheEntry(this.cache.get(KEY), KEY, lod_url, current, level, debugverbose);
+                if (cachedAfterQueue.found)
+                    return cachedAfterQueue.value;
                 // #region loading
                 if (!slot.use) {
                     if (debug)
@@ -1056,6 +1163,67 @@ export class NEEDLE_progressive {
         }
         return null;
     }
+    static async tryResolveLODCacheEntry(existing, key, lodUrl, current, level, debugverbose) {
+        if (existing === undefined) {
+            return { found: false };
+        }
+        if (debugverbose)
+            console.log(`LOD ${level} was already loading/loaded: ${key}`);
+        if (existing instanceof WeakRef) {
+            const derefed = existing.deref();
+            if (derefed) {
+                let res = derefed;
+                let resourceIsDisposed = false;
+                if (res instanceof Texture && current instanceof Texture) {
+                    if (res.image?.data || res.source?.data) {
+                        res = this.copySettings(current, res);
+                    }
+                    else {
+                        resourceIsDisposed = true;
+                    }
+                }
+                else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+                    if (!res.attributes.position?.array) {
+                        resourceIsDisposed = true;
+                    }
+                }
+                if (!resourceIsDisposed) {
+                    return { found: true, value: res };
+                }
+            }
+            this.cache.delete(key);
+            if (debug)
+                console.log(`[gltf-progressive] Re-loading GC'd/disposed resource: ${key}`);
+            return { found: false };
+        }
+        let res = await existing.catch(err => {
+            console.error(`Error loading LOD ${level} from ${lodUrl}\n`, err);
+            return null;
+        });
+        let resourceIsDisposed = false;
+        if (res == null) {
+            // Failed loads stay cached as null so we don't retry the same missing resource forever.
+        }
+        else if (res instanceof Texture && current instanceof Texture) {
+            if (res.image?.data || res.source?.data) {
+                res = this.copySettings(current, res);
+            }
+            else {
+                resourceIsDisposed = true;
+                this.cache.delete(key);
+            }
+        }
+        else if (res instanceof BufferGeometry && current instanceof BufferGeometry) {
+            if (!res.attributes.position?.array) {
+                resourceIsDisposed = true;
+                this.cache.delete(key);
+            }
+        }
+        if (resourceIsDisposed) {
+            return { found: false };
+        }
+        return { found: true, value: res };
+    }
     static _queue;
     static get queue() { return this._queue ??= new PromiseQueue(isMobileDevice() ? 20 : 50, { debug: debug != false }); }
     static assignLODInformation(url, res, key, level, index) {