@chocozhang/three-model-render 1.0.4 → 1.0.6

package/dist/loader/index.mjs

@@ -1,37 +1,22 @@
 import * as THREE from 'three';
 import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
 
-/******************************************************************************
-Copyright (c) Microsoft Corporation.
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-***************************************************************************** */
-/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
-
-
-function __awaiter(thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-}
-
-typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+let globalConfig = {
+    dracoDecoderPath: '/draco/',
+    ktx2TranscoderPath: '/basis/',
 };
+/**
+ * Update global loader configuration (e.g., set path to CDN)
+ */
+function setLoaderConfig(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Get current global loader configuration
+ */
+function getLoaderConfig() {
+    return globalConfig;
+}
 
 /**
  * @file modelLoader.ts
@@ -49,19 +34,22 @@ const DEFAULT_OPTIONS$1 = {
     maxTextureSize: null,
     useSimpleMaterials: false,
     skipSkinned: true,
+    useCache: true,
 };
+const modelCache = new Map();
 /** Automatically determine which options to enable based on extension (smart judgment) */
 function normalizeOptions(url, opts) {
     const ext = (url.split('.').pop() || '').toLowerCase();
-    const merged = Object.assign(Object.assign({}, DEFAULT_OPTIONS$1), opts);
+    const merged = { ...DEFAULT_OPTIONS$1, ...opts };
     if (ext === 'gltf' || ext === 'glb') {
+        const globalConfig = getLoaderConfig();
         // gltf/glb defaults to trying draco/ktx2 if user didn't specify
         if (merged.dracoDecoderPath === undefined)
-            merged.dracoDecoderPath = '/draco/';
+            merged.dracoDecoderPath = globalConfig.dracoDecoderPath;
         if (merged.useKTX2 === undefined)
             merged.useKTX2 = true;
         if (merged.ktx2TranscoderPath === undefined)
-            merged.ktx2TranscoderPath = '/basis/';
+            merged.ktx2TranscoderPath = globalConfig.ktx2TranscoderPath;
     }
     else {
         // fbx/obj/ply/stl etc. do not need draco/ktx2
@@ -71,103 +59,108 @@ function normalizeOptions(url, opts) {
     }
     return merged;
 }
-function loadModelByUrl(url_1) {
-    return __awaiter(this, arguments, void 0, function* (url, options = {}) {
-        var _a, _b;
-        if (!url)
-            throw new Error('url required');
-        const ext = (url.split('.').pop() || '').toLowerCase();
-        const opts = normalizeOptions(url, options);
-        const manager = (_a = opts.manager) !== null && _a !== void 0 ? _a : new THREE.LoadingManager();
-        let loader;
-        if (ext === 'gltf' || ext === 'glb') {
-            const { GLTFLoader } = yield import('three/examples/jsm/loaders/GLTFLoader.js');
-            const gltfLoader = new GLTFLoader(manager);
-            if (opts.dracoDecoderPath) {
-                const { DRACOLoader } = yield import('three/examples/jsm/loaders/DRACOLoader.js');
-                const draco = new DRACOLoader();
-                draco.setDecoderPath(opts.dracoDecoderPath);
-                gltfLoader.setDRACOLoader(draco);
-            }
-            if (opts.useKTX2 && opts.ktx2TranscoderPath) {
-                const { KTX2Loader } = yield import('three/examples/jsm/loaders/KTX2Loader.js');
-                const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
-                gltfLoader.__ktx2Loader = ktx2Loader;
-            }
-            loader = gltfLoader;
-        }
-        else if (ext === 'fbx') {
-            const { FBXLoader } = yield import('three/examples/jsm/loaders/FBXLoader.js');
-            loader = new FBXLoader(manager);
-        }
-        else if (ext === 'obj') {
-            const { OBJLoader } = yield import('three/examples/jsm/loaders/OBJLoader.js');
-            loader = new OBJLoader(manager);
-        }
-        else if (ext === 'ply') {
-            const { PLYLoader } = yield import('three/examples/jsm/loaders/PLYLoader.js');
-            loader = new PLYLoader(manager);
-        }
-        else if (ext === 'stl') {
-            const { STLLoader } = yield import('three/examples/jsm/loaders/STLLoader.js');
-            loader = new STLLoader(manager);
+async function loadModelByUrl(url, options = {}) {
+    if (!url)
+        throw new Error('url required');
+    const ext = (url.split('.').pop() || '').toLowerCase();
+    const opts = normalizeOptions(url, options);
+    const manager = opts.manager ?? new THREE.LoadingManager();
+    // Cache key includes URL and relevant optimization options
+    const cacheKey = `${url}_${opts.mergeGeometries}_${opts.maxTextureSize}_${opts.useSimpleMaterials}`;
+    if (opts.useCache && modelCache.has(cacheKey)) {
+        return modelCache.get(cacheKey).clone();
+    }
+    let loader;
+    if (ext === 'gltf' || ext === 'glb') {
+        const { GLTFLoader } = await import('three/examples/jsm/loaders/GLTFLoader.js');
+        const gltfLoader = new GLTFLoader(manager);
+        if (opts.dracoDecoderPath) {
+            const { DRACOLoader } = await import('three/examples/jsm/loaders/DRACOLoader.js');
+            const draco = new DRACOLoader();
+            draco.setDecoderPath(opts.dracoDecoderPath);
+            gltfLoader.setDRACOLoader(draco);
         }
-        else {
-            throw new Error(`Unsupported model extension: .${ext}`);
+        if (opts.useKTX2 && opts.ktx2TranscoderPath) {
+            const { KTX2Loader } = await import('three/examples/jsm/loaders/KTX2Loader.js');
+            const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
+            gltfLoader.__ktx2Loader = ktx2Loader;
         }
-        const object = yield new Promise((resolve, reject) => {
-            loader.load(url, (res) => {
-                var _a;
-                if (ext === 'gltf' || ext === 'glb') {
-                    const sceneObj = res.scene || res;
-                    // --- Critical: Expose animations to scene.userData (or scene.animations) ---
-                    // So the caller can access clips simply by getting sceneObj.userData.animations
-                    sceneObj.userData = (sceneObj === null || sceneObj === void 0 ? void 0 : sceneObj.userData) || {};
-                    sceneObj.userData.animations = (_a = res.animations) !== null && _a !== void 0 ? _a : [];
-                    resolve(sceneObj);
-                }
-                else {
-                    resolve(res);
-                }
-            }, undefined, (err) => reject(err));
-        });
-        // Optimize
-        object.traverse((child) => {
-            var _a, _b, _c;
-            const mesh = child;
-            if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
-                try {
-                    mesh.geometry = (_c = (_b = (_a = new THREE.BufferGeometry()).fromGeometry) === null || _b === void 0 ? void 0 : _b.call(_a, mesh.geometry)) !== null && _c !== void 0 ? _c : mesh.geometry;
-                }
-                catch (_d) { }
+        loader = gltfLoader;
+    }
+    else if (ext === 'fbx') {
+        const { FBXLoader } = await import('three/examples/jsm/loaders/FBXLoader.js');
+        loader = new FBXLoader(manager);
+    }
+    else if (ext === 'obj') {
+        const { OBJLoader } = await import('three/examples/jsm/loaders/OBJLoader.js');
+        loader = new OBJLoader(manager);
+    }
+    else if (ext === 'ply') {
+        const { PLYLoader } = await import('three/examples/jsm/loaders/PLYLoader.js');
+        loader = new PLYLoader(manager);
+    }
+    else if (ext === 'stl') {
+        const { STLLoader } = await import('three/examples/jsm/loaders/STLLoader.js');
+        loader = new STLLoader(manager);
+    }
+    else {
+        throw new Error(`Unsupported model extension: .${ext}`);
+    }
+    const object = await new Promise((resolve, reject) => {
+        loader.load(url, (res) => {
+            if (ext === 'gltf' || ext === 'glb') {
+                const sceneObj = res.scene || res;
+                // --- Critical: Expose animations to scene.userData (or scene.animations) ---
+                // So the caller can access clips simply by getting sceneObj.userData.animations
+                sceneObj.userData = sceneObj?.userData || {};
+                sceneObj.userData.animations = res.animations ?? [];
+                resolve(sceneObj);
             }
-        });
-        if (opts.maxTextureSize && opts.maxTextureSize > 0)
-            downscaleTexturesInObject(object, opts.maxTextureSize);
-        if (opts.useSimpleMaterials) {
-            object.traverse((child) => {
-                const m = child.material;
-                if (!m)
-                    return;
-                if (Array.isArray(m))
-                    child.material = m.map((mat) => toSimpleMaterial(mat));
-                else
-                    child.material = toSimpleMaterial(m);
-            });
-        }
-        if (opts.mergeGeometries) {
-            try {
-                yield tryMergeGeometries(object, { skipSkinned: (_b = opts.skipSkinned) !== null && _b !== void 0 ? _b : true });
+            else {
+                resolve(res);
             }
-            catch (e) {
-                console.warn('mergeGeometries failed', e);
+        }, undefined, (err) => reject(err));
+    });
+    // Optimize
+    object.traverse((child) => {
+        const mesh = child;
+        if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
+            try {
+                mesh.geometry = new THREE.BufferGeometry().fromGeometry?.(mesh.geometry) ?? mesh.geometry;
             }
+            catch { }
         }
-        return object;
     });
+    if (opts.maxTextureSize && opts.maxTextureSize > 0)
+        await downscaleTexturesInObject(object, opts.maxTextureSize);
+    if (opts.useSimpleMaterials) {
+        object.traverse((child) => {
+            const m = child.material;
+            if (!m)
+                return;
+            if (Array.isArray(m))
+                child.material = m.map((mat) => toSimpleMaterial(mat));
+            else
+                child.material = toSimpleMaterial(m);
+        });
+    }
+    if (opts.mergeGeometries) {
+        try {
+            await tryMergeGeometries(object, { skipSkinned: opts.skipSkinned ?? true });
+        }
+        catch (e) {
+            console.warn('mergeGeometries failed', e);
+        }
+    }
+    if (opts.useCache) {
+        modelCache.set(cacheKey, object);
+        return object.clone();
+    }
+    return object;
 }
-/** Runtime downscale textures in mesh to maxSize (canvas drawImage) to save GPU memory */
-function downscaleTexturesInObject(obj, maxSize) {
+/** Runtime downscale textures in mesh to maxSize (createImageBitmap or canvas) to save GPU memory */
+async function downscaleTexturesInObject(obj, maxSize) {
+    const tasks = [];
     obj.traverse((ch) => {
         if (!ch.isMesh)
             return;
@@ -186,27 +179,44 @@ function downscaleTexturesInObject(obj, maxSize) {
             const max = maxSize;
             if (image.width <= max && image.height <= max)
                 return;
-            // downscale using canvas (sync, may be heavy for many textures)
-            try {
-                const scale = Math.min(max / image.width, max / image.height);
-                const canvas = document.createElement('canvas');
-                canvas.width = Math.floor(image.width * scale);
-                canvas.height = Math.floor(image.height * scale);
-                const ctx = canvas.getContext('2d');
-                if (ctx) {
-                    ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
-                    const newTex = new THREE.Texture(canvas);
-                    newTex.needsUpdate = true;
-                    // copy common settings (encoding etc)
-                    newTex.encoding = tex.encoding;
-                    mat[p] = newTex;
+            tasks.push((async () => {
+                try {
+                    const scale = Math.min(max / image.width, max / image.height);
+                    const newWidth = Math.floor(image.width * scale);
+                    const newHeight = Math.floor(image.height * scale);
+                    let newSource;
+                    if (typeof createImageBitmap !== 'undefined') {
+                        newSource = await createImageBitmap(image, {
+                            resizeWidth: newWidth,
+                            resizeHeight: newHeight,
+                            resizeQuality: 'high'
+                        });
+                    }
+                    else {
+                        // Fallback for environments without createImageBitmap
+                        const canvas = document.createElement('canvas');
+                        canvas.width = newWidth;
+                        canvas.height = newHeight;
+                        const ctx = canvas.getContext('2d');
+                        if (ctx) {
+                            ctx.drawImage(image, 0, 0, newWidth, newHeight);
+                            newSource = canvas;
+                        }
+                    }
+                    if (newSource) {
+                        const newTex = new THREE.Texture(newSource);
+                        newTex.needsUpdate = true;
+                        newTex.encoding = tex.encoding;
+                        mat[p] = newTex;
+                    }
                 }
-            }
-            catch (e) {
-                console.warn('downscale texture failed', e);
-            }
+                catch (e) {
+                    console.warn('downscale texture failed', e);
+                }
+            })());
         });
     });
+    await Promise.all(tasks);
 }
 /**
  * Try to merge geometries in object (Only merge: non-transparent, non-SkinnedMesh, attribute compatible BufferGeometry)
@@ -214,81 +224,77 @@ function downscaleTexturesInObject(obj, maxSize) {
  * - Merging will group by material UUID (different materials cannot be merged)
  * - Merge function is compatible with common export names of BufferGeometryUtils
  */
-function tryMergeGeometries(root, opts) {
-    return __awaiter(this, void 0, void 0, function* () {
-        // collect meshes by material uuid
-        const groups = new Map();
-        root.traverse((ch) => {
-            var _a;
-            if (!ch.isMesh)
-                return;
-            const mesh = ch;
-            if (opts.skipSkinned && mesh.isSkinnedMesh)
-                return;
-            const mat = mesh.material;
-            // don't merge transparent or morph-enabled or skinned meshes
-            if (!mesh.geometry || mesh.visible === false)
-                return;
-            if (mat && mat.transparent)
-                return;
-            const geom = mesh.geometry.clone();
-            mesh.updateWorldMatrix(true, false);
-            geom.applyMatrix4(mesh.matrixWorld);
-            // ensure attributes compatible? we'll rely on merge function to return null if incompatible
-            const key = (mat && mat.uuid) || 'default';
-            const bucket = (_a = groups.get(key)) !== null && _a !== void 0 ? _a : { material: mat !== null && mat !== void 0 ? mat : new THREE.MeshStandardMaterial(), geoms: [] };
-            bucket.geoms.push(geom);
-            groups.set(key, bucket);
-            // mark for removal (we'll remove meshes after)
-            mesh.userData.__toRemoveForMerge = true;
-        });
-        if (groups.size === 0)
+async function tryMergeGeometries(root, opts) {
+    // collect meshes by material uuid
+    const groups = new Map();
+    root.traverse((ch) => {
+        if (!ch.isMesh)
             return;
-        // dynamic import BufferGeometryUtils and find merge function name
-        const bufUtilsMod = yield import('three/examples/jsm/utils/BufferGeometryUtils.js');
-        // use || chain (avoid mixing ?? with || without parentheses)
-        const mergeFn = bufUtilsMod.mergeBufferGeometries ||
-            bufUtilsMod.mergeGeometries ||
-            bufUtilsMod.mergeBufferGeometries || // defensive duplicate
-            bufUtilsMod.mergeGeometries;
-        if (!mergeFn)
-            throw new Error('No merge function found in BufferGeometryUtils');
-        // for each group, try merge
-        for (const [key, { material, geoms }] of groups) {
-            if (geoms.length <= 1) {
-                // nothing to merge
-                continue;
-            }
-            // call merge function - signature typically mergeBufferGeometries(array, useGroups)
-            const merged = mergeFn(geoms, false);
-            if (!merged) {
-                console.warn('merge returned null for group', key);
-                continue;
-            }
-            // create merged mesh at root (world-space geometry already applied)
-            const mergedMesh = new THREE.Mesh(merged, material);
-            root.add(mergedMesh);
+        const mesh = ch;
+        if (opts.skipSkinned && mesh.isSkinnedMesh)
+            return;
+        const mat = mesh.material;
+        // don't merge transparent or morph-enabled or skinned meshes
+        if (!mesh.geometry || mesh.visible === false)
+            return;
+        if (mat && mat.transparent)
+            return;
+        const geom = mesh.geometry.clone();
+        mesh.updateWorldMatrix(true, false);
+        geom.applyMatrix4(mesh.matrixWorld);
+        // ensure attributes compatible? we'll rely on merge function to return null if incompatible
+        const key = (mat && mat.uuid) || 'default';
+        const bucket = groups.get(key) ?? { material: mat ?? new THREE.MeshStandardMaterial(), geoms: [] };
+        bucket.geoms.push(geom);
+        groups.set(key, bucket);
+        // mark for removal (we'll remove meshes after)
+        mesh.userData.__toRemoveForMerge = true;
+    });
+    if (groups.size === 0)
+        return;
+    // dynamic import BufferGeometryUtils and find merge function name
+    const bufUtilsMod = await import('three/examples/jsm/utils/BufferGeometryUtils.js');
+    // use || chain (avoid mixing ?? with || without parentheses)
+    const mergeFn = bufUtilsMod.mergeBufferGeometries ||
+        bufUtilsMod.mergeGeometries ||
+        bufUtilsMod.mergeBufferGeometries || // defensive duplicate
+        bufUtilsMod.mergeGeometries;
+    if (!mergeFn)
+        throw new Error('No merge function found in BufferGeometryUtils');
+    // for each group, try merge
+    for (const [key, { material, geoms }] of groups) {
+        if (geoms.length <= 1) {
+            // nothing to merge
+            continue;
         }
-        // now remove original meshes flagged for removal
-        const toRemove = [];
-        root.traverse((ch) => {
-            var _a;
-            if ((_a = ch.userData) === null || _a === void 0 ? void 0 : _a.__toRemoveForMerge)
-                toRemove.push(ch);
-        });
-        toRemove.forEach((m) => {
-            if (m.parent)
-                m.parent.remove(m);
-            // free original resources (geometries already cloned/applied), but careful with shared materials
-            if (m.isMesh) {
-                const mm = m;
-                try {
-                    mm.geometry.dispose();
-                }
-                catch (_a) { }
-                // we do NOT dispose material because it may be reused by mergedMesh
+        // call merge function - signature typically mergeBufferGeometries(array, useGroups)
+        const merged = mergeFn(geoms, false);
+        if (!merged) {
+            console.warn('merge returned null for group', key);
+            continue;
+        }
+        // create merged mesh at root (world-space geometry already applied)
+        const mergedMesh = new THREE.Mesh(merged, material);
+        root.add(mergedMesh);
+    }
+    // now remove original meshes flagged for removal
+    const toRemove = [];
+    root.traverse((ch) => {
+        if (ch.userData?.__toRemoveForMerge)
+            toRemove.push(ch);
+    });
+    toRemove.forEach((m) => {
+        if (m.parent)
+            m.parent.remove(m);
+        // free original resources (geometries already cloned/applied), but careful with shared materials
+        if (m.isMesh) {
+            const mm = m;
+            try {
+                mm.geometry.dispose();
             }
-        });
+            catch { }
+            // we do NOT dispose material because it may be reused by mergedMesh
+        }
     });
 }
 /* ---------------------
@@ -305,7 +311,7 @@ function disposeObject(obj) {
                 try {
                     m.geometry.dispose();
                 }
-                catch (_a) { }
+                catch { }
             }
             const mat = m.material;
             if (mat) {
@@ -327,14 +333,14 @@ function disposeMaterial(mat) {
             try {
                 mat[k].dispose();
             }
-            catch (_a) { }
+            catch { }
         }
     });
     try {
         if (typeof mat.dispose === 'function')
             mat.dispose();
     }
-    catch (_a) { }
+    catch { }
 }
 // Helper to convert to simple material (stub)
 function toSimpleMaterial(mat) {
@@ -377,100 +383,97 @@ const equirectCache = new Map();
  * @param paths string[] 6 image paths, order: [px, nx, py, ny, pz, nz]
  * @param opts SkyboxOptions
  */
-function loadCubeSkybox(renderer_1, scene_1, paths_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, paths, opts = {}) {
-        var _a, _b;
-        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
-        if (!Array.isArray(paths) || paths.length !== 6)
-            throw new Error('cube skybox requires 6 image paths');
-        const key = paths.join('|');
-        // Cache handling
-        if (options.cache && cubeCache.has(key)) {
-            const rec = cubeCache.get(key);
-            rec.refCount += 1;
-            // reapply to scene (in case it was removed)
-            if (options.setAsBackground)
-                scene.background = rec.handle.backgroundTexture;
-            if (options.setAsEnvironment && rec.handle.envRenderTarget)
-                scene.environment = rec.handle.envRenderTarget.texture;
-            return rec.handle;
-        }
-        // Load cube texture
-        const loader = new THREE.CubeTextureLoader();
-        const texture = yield new Promise((resolve, reject) => {
-            loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
-        });
-        // Set encoding and mapping
-        if (options.useSRGBEncoding)
-            texture.encoding = THREE.sRGBEncoding;
-        texture.mapping = THREE.CubeReflectionMapping;
-        // apply as background if required
+async function loadCubeSkybox(renderer, scene, paths, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    if (!Array.isArray(paths) || paths.length !== 6)
+        throw new Error('cube skybox requires 6 image paths');
+    const key = paths.join('|');
+    // Cache handling
+    if (options.cache && cubeCache.has(key)) {
+        const rec = cubeCache.get(key);
+        rec.refCount += 1;
+        // reapply to scene (in case it was removed)
         if (options.setAsBackground)
-            scene.background = texture;
-        // environment: use PMREM to produce a proper prefiltered env map for PBR
-        let pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE.PMREMGenerator(renderer);
-        (_b = pmremGenerator.compileCubemapShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
-        // fromCubemap might be available in your three.js; fallback to fromEquirectangular approach if not
-        let envRenderTarget = null;
-        if (pmremGenerator.fromCubemap) {
-            envRenderTarget = pmremGenerator.fromCubemap(texture);
+            scene.background = rec.handle.backgroundTexture;
+        if (options.setAsEnvironment && rec.handle.envRenderTarget)
+            scene.environment = rec.handle.envRenderTarget.texture;
+        return rec.handle;
+    }
+    // Load cube texture
+    const loader = new THREE.CubeTextureLoader();
+    const texture = await new Promise((resolve, reject) => {
+        loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
+    });
+    // Set encoding and mapping
+    if (options.useSRGBEncoding)
+        texture.encoding = THREE.sRGBEncoding;
+    texture.mapping = THREE.CubeReflectionMapping;
+    // apply as background if required
+    if (options.setAsBackground)
+        scene.background = texture;
+    // environment: use PMREM to produce a proper prefiltered env map for PBR
+    let pmremGenerator = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileCubemapShader?.( /* optional */);
+    // fromCubemap might be available in your three.js; fallback to fromEquirectangular approach if not
+    let envRenderTarget = null;
+    if (pmremGenerator.fromCubemap) {
+        envRenderTarget = pmremGenerator.fromCubemap(texture);
+    }
+    else {
+        // Fallback: render cube to env map by using generator.fromEquirectangular with a converted equirect if needed.
+        // Simpler fallback: use the cube texture directly as environment (less correct for reflections).
+        envRenderTarget = null;
+    }
+    if (options.setAsEnvironment) {
+        if (envRenderTarget) {
+            scene.environment = envRenderTarget.texture;
         }
         else {
-            // Fallback: render cube to env map by using generator.fromEquirectangular with a converted equirect if needed.
-            // Simpler fallback: use the cube texture directly as environment (less correct for reflections).
-            envRenderTarget = null;
+            // fallback: use cube texture directly (works but not prefiltered)
+            scene.environment = texture;
         }
-        if (options.setAsEnvironment) {
+    }
+    const handle = {
+        key,
+        backgroundTexture: options.setAsBackground ? texture : null,
+        envRenderTarget: envRenderTarget,
+        pmremGenerator: options.pmremGenerator ? null : pmremGenerator, // only dispose if we created it
+        setAsBackground: !!options.setAsBackground,
+        setAsEnvironment: !!options.setAsEnvironment,
+        dispose() {
+            // remove from scene
+            if (options.setAsBackground && scene.background === texture)
+                scene.background = null;
+            if (options.setAsEnvironment && scene.environment) {
+                // only clear if it's the same texture we set
+                if (envRenderTarget && scene.environment === envRenderTarget.texture)
+                    scene.environment = null;
+                else if (scene.environment === texture)
+                    scene.environment = null;
+            }
+            // dispose resources only if not cached/shared
             if (envRenderTarget) {
-                scene.environment = envRenderTarget.texture;
+                try {
+                    envRenderTarget.dispose();
+                }
+                catch { }
             }
-            else {
-                // fallback: use cube texture directly (works but not prefiltered)
-                scene.environment = texture;
+            try {
+                texture.dispose();
             }
-        }
-        const handle = {
-            key,
-            backgroundTexture: options.setAsBackground ? texture : null,
-            envRenderTarget: envRenderTarget,
-            pmremGenerator: options.pmremGenerator ? null : pmremGenerator, // only dispose if we created it
-            setAsBackground: !!options.setAsBackground,
-            setAsEnvironment: !!options.setAsEnvironment,
-            dispose() {
-                // remove from scene
-                if (options.setAsBackground && scene.background === texture)
-                    scene.background = null;
-                if (options.setAsEnvironment && scene.environment) {
-                    // only clear if it's the same texture we set
-                    if (envRenderTarget && scene.environment === envRenderTarget.texture)
-                        scene.environment = null;
-                    else if (scene.environment === texture)
-                        scene.environment = null;
-                }
-                // dispose resources only if not cached/shared
-                if (envRenderTarget) {
-                    try {
-                        envRenderTarget.dispose();
-                    }
-                    catch (_a) { }
-                }
+            catch { }
+            // dispose pmremGenerator we created
+            if (!options.pmremGenerator && pmremGenerator) {
                 try {
-                    texture.dispose();
-                }
-                catch (_b) { }
-                // dispose pmremGenerator we created
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_c) { }
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            cubeCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    if (options.cache)
+        cubeCache.set(key, { handle, refCount: 1 });
+    return handle;
 }
 /**
  * Load Equirectangular/Single Image (Supports HDR via RGBELoader)
@@ -479,95 +482,90 @@ function loadCubeSkybox(renderer_1, scene_1, paths_1) {
  * @param url string - *.hdr, *.exr, *.jpg, *.png
  * @param opts SkyboxOptions
  */
-function loadEquirectSkybox(renderer_1, scene_1, url_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, url, opts = {}) {
-        var _a, _b;
-        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
-        const key = url;
-        if (options.cache && equirectCache.has(key)) {
-            const rec = equirectCache.get(key);
-            rec.refCount += 1;
-            if (options.setAsBackground)
-                scene.background = rec.handle.backgroundTexture;
-            if (options.setAsEnvironment && rec.handle.envRenderTarget)
-                scene.environment = rec.handle.envRenderTarget.texture;
-            return rec.handle;
-        }
-        // Dynamically import RGBELoader (for .hdr/.exr), if loading normal jpg/png directly use TextureLoader
-        const isHDR = /\.hdr$|\.exr$/i.test(url);
-        let hdrTexture;
-        if (isHDR) {
-            const { RGBELoader } = yield import('three/examples/jsm/loaders/RGBELoader.js');
-            hdrTexture = yield new Promise((resolve, reject) => {
-                new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
-            });
-            // RGBE textures typically use LinearEncoding
-            hdrTexture.encoding = THREE.LinearEncoding;
-        }
-        else {
-            // ordinary image - use TextureLoader
-            const loader = new THREE.TextureLoader();
-            hdrTexture = yield new Promise((resolve, reject) => {
-                loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
-            });
-            if (options.useSRGBEncoding)
-                hdrTexture.encoding = THREE.sRGBEncoding;
-        }
-        // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
-        const pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE.PMREMGenerator(renderer);
-        (_b = pmremGenerator.compileEquirectangularShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
-        const envRenderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
-        // envTexture to use for scene.environment
-        const envTexture = envRenderTarget.texture;
-        // set background and/or environment
-        if (options.setAsBackground) {
-            // for background it's ok to use the equirect texture directly or the envTexture
-            // envTexture is cubemap-like and usually better for reflections; using it as background creates cube-projected look
-            scene.background = envTexture;
-        }
-        if (options.setAsEnvironment) {
-            scene.environment = envTexture;
-        }
-        // We can dispose the original hdrTexture (the PMREM target contains the needed data)
-        try {
-            hdrTexture.dispose();
-        }
-        catch (_c) { }
-        const handle = {
-            key,
-            backgroundTexture: options.setAsBackground ? envTexture : null,
-            envRenderTarget,
-            pmremGenerator: options.pmremGenerator ? null : pmremGenerator,
-            setAsBackground: !!options.setAsBackground,
-            setAsEnvironment: !!options.setAsEnvironment,
-            dispose() {
-                if (options.setAsBackground && scene.background === envTexture)
-                    scene.background = null;
-                if (options.setAsEnvironment && scene.environment === envTexture)
-                    scene.environment = null;
+async function loadEquirectSkybox(renderer, scene, url, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    const key = url;
+    if (options.cache && equirectCache.has(key)) {
+        const rec = equirectCache.get(key);
+        rec.refCount += 1;
+        if (options.setAsBackground)
+            scene.background = rec.handle.backgroundTexture;
+        if (options.setAsEnvironment && rec.handle.envRenderTarget)
+            scene.environment = rec.handle.envRenderTarget.texture;
+        return rec.handle;
+    }
+    // Dynamically import RGBELoader (for .hdr/.exr), if loading normal jpg/png directly use TextureLoader
+    const isHDR = /\.hdr$|\.exr$/i.test(url);
+    let hdrTexture;
+    if (isHDR) {
+        const { RGBELoader } = await import('three/examples/jsm/loaders/RGBELoader.js');
+        hdrTexture = await new Promise((resolve, reject) => {
+            new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
+        });
+        // RGBE textures typically use LinearEncoding
+        hdrTexture.encoding = THREE.LinearEncoding;
+    }
+    else {
+        // ordinary image - use TextureLoader
+        const loader = new THREE.TextureLoader();
+        hdrTexture = await new Promise((resolve, reject) => {
+            loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
+        });
+        if (options.useSRGBEncoding)
+            hdrTexture.encoding = THREE.sRGBEncoding;
+    }
+    // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
+    const pmremGenerator = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileEquirectangularShader?.();
+    const envRenderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
+    // envTexture to use for scene.environment
+    const envTexture = envRenderTarget.texture;
+    // set background and/or environment
+    if (options.setAsBackground) {
+        // for background it's ok to use the equirect texture directly or the envTexture
+        // envTexture is cubemap-like and usually better for reflections; using it as background creates cube-projected look
+        scene.background = envTexture;
+    }
+    if (options.setAsEnvironment) {
+        scene.environment = envTexture;
+    }
+    // We can dispose the original hdrTexture (the PMREM target contains the needed data)
+    try {
+        hdrTexture.dispose();
+    }
+    catch { }
+    const handle = {
+        key,
+        backgroundTexture: options.setAsBackground ? envTexture : null,
+        envRenderTarget,
+        pmremGenerator: options.pmremGenerator ? null : pmremGenerator,
+        setAsBackground: !!options.setAsBackground,
+        setAsEnvironment: !!options.setAsEnvironment,
+        dispose() {
+            if (options.setAsBackground && scene.background === envTexture)
+                scene.background = null;
+            if (options.setAsEnvironment && scene.environment === envTexture)
+                scene.environment = null;
+            try {
+                envRenderTarget.dispose();
+            }
+            catch { }
+            if (!options.pmremGenerator && pmremGenerator) {
                 try {
-                    envRenderTarget.dispose();
-                }
-                catch (_a) { }
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_b) { }
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            equirectCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    if (options.cache)
+        equirectCache.set(key, { handle, refCount: 1 });
+    return handle;
 }
-function loadSkybox(renderer_1, scene_1, params_1) {
-    return __awaiter(this, arguments, void 0, function* (renderer, scene, params, opts = {}) {
-        if (params.type === 'cube')
-            return loadCubeSkybox(renderer, scene, params.paths, opts);
-        return loadEquirectSkybox(renderer, scene, params.url, opts);
-    });
+async function loadSkybox(renderer, scene, params, opts = {}) {
+    if (params.type === 'cube')
+        return loadCubeSkybox(renderer, scene, params.paths, opts);
+    return loadEquirectSkybox(renderer, scene, params.url, opts);
 }
 /* -------------------------
    Cache / Reference Counting Helper Methods
@@ -777,10 +775,9 @@ class BlueSkyManager {
      * Usually called when the scene is completely destroyed or the application exits
      */
     destroy() {
-        var _a;
         this.cancelLoad();
         this.dispose();
-        (_a = this.pmremGen) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.pmremGen?.dispose();
         this.isInitialized = false;
         this.loadingState = 'idle';
     }
@@ -793,5 +790,5 @@ class BlueSkyManager {
  */
 const BlueSky = new BlueSkyManager();
 
-export { BlueSky, disposeMaterial, disposeObject, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox };
+export { BlueSky, disposeMaterial, disposeObject, getLoaderConfig, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox, setLoaderConfig };
 //# sourceMappingURL=index.mjs.map