@zephyr3d/scene 0.9.4 → 0.9.6

package/dist/asset/assetmanager.js

@@ -1,5 +1,4 @@
-import { DWeakRef, ASSERT, base64ToUint8Array, Vector3, DRef, Vector4, VFSError, isPowerOf2, nextPowerOf2 } from '@zephyr3d/base';
-import { GLTFLoader } from './loaders/gltf/gltf_loader.js';
+import { DWeakRef, DRef, ASSERT, base64ToUint8Array, Vector3, Vector4, guessMimeType, isPowerOf2, nextPowerOf2 } from '@zephyr3d/base';
 import { WebImageLoader } from './loaders/image/webimage_loader.js';
 import { DDSLoader } from './loaders/dds/dds_loader.js';
 import { HDRLoader } from './loaders/hdr/hdr.js';
@@ -35,20 +34,20 @@ import '../render/clipmap.js';
 import '../shaders/atmosphere.js';
 import { FontAsset } from '../text/font/font_asset.js';
 
-/**
- * Centralized asset manager for loading and caching resources.
- *
- * Responsibilities:
- * - Abstracts resource loading via VFS (text/json/binary).
- * - Dispatches texture/model loading to registered loaders by MIME type.
- * - Caches results and uses weak references to allow GPU resources to be GC'd when unused.
- * - Harmonizes cross-backend constraints (e.g., WebGL non-power-of-two rules and sRGB handling).
- * - Provides access to built-in textures with device-restore handlers.
- *
- * Threading/async model:
- * - All I/O is async; repeated calls are coalesced via internal promise caches keyed by URL or hash.
- *
- * @public
+/**
+ * Centralized asset manager for loading and caching resources.
+ *
+ * Responsibilities:
+ * - Abstracts resource loading via VFS (text/json/binary).
+ * - Dispatches texture/model loading to registered loaders by MIME type.
+ * - Caches results and uses weak references to allow GPU resources to be GC'd when unused.
+ * - Harmonizes cross-backend constraints (e.g., WebGL non-power-of-two rules and sRGB handling).
+ * - Provides access to built-in textures with device-restore handlers.
+ *
+ * Threading/async model:
+ * - All I/O is async; repeated calls are coalesced via internal promise caches keyed by URL or hash.
+ *
+ * @public
  */ class AssetManager {
     /** @internal */ static _builtinTextures = {};
     /** @internal */ static _builtinTextureLoaders = {
@@ -60,9 +59,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         new HDRLoader(),
         new TGALoader()
     ];
-    /** @internal */ static _modelLoaders = [
-        new GLTFLoader()
-    ];
+    /** @internal */ _modelLoaders = {};
     /** @internal */ _textures;
     /** @internal */ _models;
     /** @internal */ _binaryDatas;
@@ -74,8 +71,8 @@ import { FontAsset } from '../text/font/font_asset.js';
     /** @internal */ _skeletons;
     /** @internal */ _jsonDatas;
     /** @internal */ _resourceManager;
-    /**
-   * Creates an instance of AssetManager
+    /**
+   * Creates an instance of AssetManager
    */ constructor(resourceManager){
         this._resourceManager = resourceManager ?? getEngine().resourceManager;
         this._textures = {};
@@ -89,18 +86,18 @@ import { FontAsset } from '../text/font/font_asset.js';
         this._textDatas = {};
         this._jsonDatas = {};
     }
-    /**
-   * VFS used to read resources (files, URLs, virtual mounts).
+    /**
+   * VFS used to read resources (files, URLs, virtual mounts).
    */ get vfs() {
         return this._resourceManager.VFS;
     }
-    /**
-   * Clear cached references and promises.
-   *
-   * - Disposes any DWeakRef holders maintained by this manager.
-   * - Empties internal maps for textures, models, and raw data (text/json/binary).
-   * - Does not forcibly dispose GPU resources; it only clears references so they can be GC'd
-   *   if no other owners are holding them.
+    /**
+   * Clear cached references and promises.
+   *
+   * - Disposes any DWeakRef holders maintained by this manager.
+   * - Empties internal maps for textures, models, and raw data (text/json/binary).
+   * - Does not forcibly dispose GPU resources; it only clears references so they can be GC'd
+   *   if no other owners are holding them.
    */ clearCache() {
         for(const k in Object.keys(this._textures)){
             const v = this._textures[k];
@@ -142,13 +139,13 @@ import { FontAsset } from '../text/font/font_asset.js';
         this._textDatas = {};
         this._jsonDatas = {};
     }
-    /**
-   * Removes a cached font asset entry by URL.
-   *
-   * This only evicts the cache entry. It does not dispose any external references to the FontAsset.
-   *
-   * @param url - Resource URL or VFS path.
-   * @returns `true` if a cache entry existed and was removed.
+    /**
+   * Removes a cached font asset entry by URL.
+   *
+   * This only evicts the cache entry. It does not dispose any external references to the FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @returns `true` if a cache entry existed and was removed.
    */ releaseFontAsset(url) {
         if (url in this._fontAssets) {
             delete this._fontAssets[url];
@@ -156,101 +153,97 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return false;
     }
-    /**
-   * Register a texture loader (highest priority first).
-   *
-   * Note: This is a static registry shared by all AssetManager instances.
-   *
-   * @param loader - A concrete texture loader implementation.
+    /**
+   * Register a texture loader (highest priority first).
+   *
+   * Note: This is a static registry shared by all AssetManager instances.
+   *
+   * @param loader - A concrete texture loader implementation.
    */ static addTextureLoader(loader) {
         if (loader) {
             this._textureLoaders.unshift(loader);
         }
     }
-    /**
-   * Register a model loader (highest priority first).
-   *
-   * Note: This is a static registry shared by all AssetManager instances.
-   *
-   * @param loader - A concrete model loader implementation.
-   */ static addModelLoader(loader) {
+    /**
+   * Register a model loader (highest priority first).
+   */ setModelLoader(mimeType, loader) {
         if (loader) {
-            this._modelLoaders.unshift(loader);
-        }
-    }
-    /**
-   * Fetch a UTF-8 text resource via VFS.
-   *
-   * - Results are cached per resolved URL (via HttpRequest.urlResolver if provided; otherwise the raw URL).
-   * - If cached, any provided postProcess is ignored for subsequent calls; create a separate AssetManager
-   *   if you need different post-processing of the same URL.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the loaded text.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) text.
-   */ async fetchTextData(url, postProcess, httpRequest, VFSs) {
+            this._modelLoaders[mimeType] = loader;
+        }
+    }
+    /**
+   * Fetch a UTF-8 text resource via VFS.
+   *
+   * - Results are cached per resolved URL (via HttpRequest.urlResolver if provided; otherwise the raw URL).
+   * - If cached, any provided postProcess is ignored for subsequent calls; create a separate AssetManager
+   *   if you need different post-processing of the same URL.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the loaded text.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) text.
+   */ async fetchTextData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._textDatas[hash];
         if (!P) {
-            P = this.loadTextData(url, postProcess, VFSs);
+            P = this.loadTextData(url, postProcess, options?.overrideVFS);
             this._textDatas[hash] = P;
         }
         return P;
     }
-    /**
-   * Fetch a JSON resource via VFS.
-   *
-   * - Parses as JSON after text load.
-   * - Cached per resolved URL. Post-process is applied only on the first load for a given cache key.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the parsed JSON object.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) JSON value.
-   */ async fetchJsonData(url, postProcess, httpRequest, VFSs) {
+    /**
+   * Fetch a JSON resource via VFS.
+   *
+   * - Parses as JSON after text load.
+   * - Cached per resolved URL. Post-process is applied only on the first load for a given cache key.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the parsed JSON object.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) JSON value.
+   */ async fetchJsonData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._jsonDatas[hash];
         if (!P) {
-            P = this.loadJsonData(url, postProcess, VFSs);
+            P = this.loadJsonData(url, postProcess, options?.overrideVFS);
             this._jsonDatas[hash] = P;
         }
         return P;
     }
-    /**
-   * Fetch a binary resource via VFS.
-   *
-   * - Cached per resolved URL. Post-process is applied only on first load for a given key.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the loaded ArrayBuffer.
-   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
-   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
-   */ async fetchBinaryData(url, postProcess, httpRequest, VFSs) {
+    /**
+   * Fetch a binary resource via VFS.
+   *
+   * - Cached per resolved URL. Post-process is applied only on first load for a given key.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the loaded ArrayBuffer.
+   * @param httpRequest - Optional HttpRequest for custom URL resolution/headers.
+   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
+   */ async fetchBinaryData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
         let P = this._binaryDatas[hash];
         if (!P) {
-            P = this.loadBinaryData(url, postProcess, VFSs);
+            P = this.loadBinaryData(url, postProcess, options?.overrideVFS);
             this._binaryDatas[hash] = P;
         }
         return P;
     }
-    /**
-   * Fetch a font asset via VFS.
-   *
-   * - Cached per URL only.
-   * - `options` are applied only when the font is first loaded for that URL.
-   * - If the URL is already cached, later calls ignore `options` and reuse the cached FontAsset.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param options - Optional MSDF atlas settings bound to the loaded FontAsset.
-   * @returns A promise that resolves to the loaded (and optionally processed) font asset.
-   */ async fetchFontAsset(url, options, VFSs) {
+    /**
+   * Fetch a font asset via VFS.
+   *
+   * - Cached per URL only.
+   * - `options` are applied only when the font is first loaded for that URL.
+   * - If the URL is already cached, later calls ignore `options` and reuse the cached FontAsset.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param options - Optional MSDF atlas settings bound to the loaded FontAsset.
+   * @returns A promise that resolves to the loaded (and optionally processed) font asset.
+   */ async fetchFontAsset(url, options) {
         const hash = url;
         let P = this._fontAssets[hash];
         if (!P) {
             P = new Promise((resolve, reject)=>{
-                this.loadBinaryData(url, null, VFSs).then((data)=>{
+                this.loadBinaryData(url, null, options?.overrideVFS).then((data)=>{
                     resolve(data ? FontAsset.fromBuffer(data, options) : null);
                 }).catch((err)=>{
                     reject(new Error(`Failed to load font asset from ${url}: ${err instanceof Error ? err.message : err}`));
@@ -260,36 +253,36 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return P;
     }
-    /**
-   * Fetch a font asset via VFS if already cached.
-   * @param url - Resource URL or VFS path.
-   * @returns The cached FontAsset if it exists and is loaded, or null if not cached or still loading.
+    /**
+   * Fetch a font asset via VFS if already cached.
+   * @param url - Resource URL or VFS path.
+   * @returns The cached FontAsset if it exists and is loaded, or null if not cached or still loading.
    */ getFontAsset(url) {
         const hash = url;
         return this._fontAssets[hash] instanceof Promise ? null : this._fontAssets[hash] ?? null;
     }
-    async fetchBluePrint(url, VFSs) {
+    async fetchBluePrint(url, options) {
         const hash = url;
         let P = this._bluePrints[hash];
         if (!P) {
-            P = this.loadBluePrint(url, VFSs);
+            P = this.loadBluePrint(url, options?.overrideVFS);
             this._bluePrints[hash] = P;
         }
         return P;
     }
-    /**
-   * Fetch a material resource.
-   *
-   * @typeParam T - Expected concrete material type.
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded material.
-   */ async fetchMaterial(url, VFSs) {
+    /**
+   * Fetch a material resource.
+   *
+   * @typeParam T - Expected concrete material type.
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded material.
+   */ async fetchMaterial(url, options) {
         const hash = url;
         let P = this._materials[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadMaterial(url, false, VFSs);
+            P = this.loadMaterial(url, false, options?.overrideVFS);
             this._materials[hash] = P;
         }
         const material = await P;
@@ -298,19 +291,19 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return material;
     }
-    /**
-   * Fetch a primitive resource.
-   *
-   * @typeParam T - Expected concrete primitive type.
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded primitive.
-   */ async fetchPrimitive(url, VFSs) {
+    /**
+   * Fetch a primitive resource.
+   *
+   * @typeParam T - Expected concrete primitive type.
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded primitive.
+   */ async fetchPrimitive(url, options) {
         const hash = url;
         let P = this._primitives[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadPrimitive(url, VFSs);
+            P = this.loadPrimitive(url, options?.overrideVFS);
             this._primitives[hash] = P;
         }
         const primitive = await P;
@@ -319,29 +312,29 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return primitive;
     }
-    /**
-   * Fetch a texture resource via registered loaders.
-   *
-   * - Chooses loader by explicit MIME type or by VFS file extension inference.
-   * - Deduplicates in-flight requests and caches ready textures.
-   * - If `options.texture` is provided, the asset will be uploaded/blitted into that texture.
-   * - On WebGL backends, enforces constraints by repacking non-power-of-two or sRGB textures.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param url - Resource URL or VFS path.
-   * @param options - Texture fetching options (color space, sampler, target texture).
-   * @param httpRequest - Optional HttpRequest (not used for binary read but may supply URL resolver for hashing).
-   * @returns A promise that resolves to the loaded texture.
-   */ async fetchTexture(url, options, VFSs) {
+    /**
+   * Fetch a texture resource via registered loaders.
+   *
+   * - Chooses loader by explicit MIME type or by VFS file extension inference.
+   * - Deduplicates in-flight requests and caches ready textures.
+   * - If `options.texture` is provided, the asset will be uploaded/blitted into that texture.
+   * - On WebGL backends, enforces constraints by repacking non-power-of-two or sRGB textures.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param url - Resource URL or VFS path.
+   * @param options - Texture fetching options (color space, sampler, target texture).
+   * @param httpRequest - Optional HttpRequest (not used for binary read but may supply URL resolver for hashing).
+   * @returns A promise that resolves to the loaded texture.
+   */ async fetchTexture(url, options) {
         if (options?.texture) {
-            return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, VFSs);
+            return this.loadTexture(url, options.mimeType ?? null, !options.linearColorSpace, options.samplerOptions, options.texture, options.overrideVFS);
         } else {
             const hash = this.getHash('2d', url, options);
             let P = this._textures[hash];
             if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
                 return P.get();
             } else if (!P || P instanceof DWeakRef) {
-                P = this.loadTexture(url, options?.mimeType ?? null, !options?.linearColorSpace, options?.samplerOptions, null, VFSs);
+                P = this.loadTexture(url, options?.mimeType ?? null, !options?.linearColorSpace, options?.samplerOptions, null, options?.overrideVFS);
                 this._textures[hash] = P;
             }
             const tex = await P;
@@ -351,23 +344,23 @@ import { FontAsset } from '../text/font/font_asset.js';
             return tex;
         }
     }
-    /**
-   * Fetch a model resource via registered model loaders (data only).
-   *
-   * - Returns a SharedModel which can create scene nodes in any Scene.
-   * - Uses DWeakRef to cache and allow model data to be reclaimed if unused.
-   *
-   * @param url - Model URL or VFS path.
-   * @param options - Model loader options (MIME override, Draco, instancing hint, post-process).
-   * @returns A promise that resolves to the SharedModel.
-   * @internal
-   */ async fetchModelData(url, options, VFSs) {
+    /**
+   * Fetch a model resource via registered model loaders (data only).
+   *
+   * - Returns a SharedModel which can create scene nodes in any Scene.
+   * - Uses DWeakRef to cache and allow model data to be reclaimed if unused.
+   *
+   * @param url - Model URL or VFS path.
+   * @param options - Model loader options (MIME override, Draco, instancing hint, post-process).
+   * @returns A promise that resolves to the SharedModel.
+   * @internal
+   */ async fetchModelData(url, options) {
         const hash = url;
         let P = this._models[hash];
         if (P instanceof DWeakRef && P.get() && !P.get().disposed) {
             return P.get();
         } else if (!P || P instanceof DWeakRef) {
-            P = this.loadModel(url, options, VFSs);
+            P = this.loadModel(url, options, options?.overrideVFS);
             this._models[hash] = P;
         }
         const sharedModel = await P;
@@ -376,38 +369,46 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return sharedModel;
     }
-    /**
-   * Fetch a model resource and instantiate it under a scene.
-   *
-   * - Loads or retrieves a cached SharedModel, then creates a SceneNode hierarchy.
-   * - Returns both the created group node and any associated AnimationSet.
-   *
-   * @param scene - Scene into which the model node will be created.
-   * @param url - Model URL or VFS path.
-   * @param options - Model loader options and instancing hint.
-   * @param httpRequest - Optional HttpRequest (unused for binary read; present for API symmetry).
-   * @returns A promise with the created node group and animation set info.
-   */ async fetchModel(scene, url, options, VFSs) {
-        const sharedModel = await this.fetchModelData(url, options, VFSs);
-        const node = sharedModel.createSceneNode(scene, !!options?.enableInstancing);
-        return {
-            group: node,
-            animationSet: node.animationSet
-        };
-    }
-    /**
-   * Load a text resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchTextData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the text.
-   * @returns A promise that resolves to the loaded (and optionally processed) text.
-   * @internal
-   */ async loadTextData(url, postProcess, VFSs) {
-        let text = await this.readFileFromVFSs(url, {
+    /**
+   * Fetch a model resource and instantiate it under a scene.
+   *
+   * - Loads or retrieves a cached SharedModel, then creates a SceneNode hierarchy.
+   * - Returns both the created group node and any associated AnimationSet.
+   *
+   * @param scene - Scene into which the model node will be created.
+   * @param url - Model URL or VFS path.
+   * @param options - Model loader options and instancing hint.
+   * @param httpRequest - Optional HttpRequest (unused for binary read; present for API symmetry).
+   * @returns A promise with the created node group and animation set info.
+   *
+   * @internal
+   */ async fetchModel(scene, url, options) {
+        const sharedModel = new DRef();
+        try {
+            sharedModel.set(await this.fetchModelData(url, options));
+            const node = await sharedModel.get().createSceneNode(getEngine().resourceManager, scene, options?.enableInstancing ?? false, options?.loadMeshes ?? true, options?.loadSkeletons ?? true, options?.loadAnimations ?? true, options?.loadJointDynamics ?? true, options?.overrideVFS ?? getEngine().resourceManager.VFS);
+            node.sharedModel = sharedModel.get();
+            node.animationSet.resetSkeletonModifiers();
+            return node;
+        } catch (err) {
+            console.error(`Load model failed: ${url}: ${err}`);
+        } finally{
+            sharedModel.dispose();
+        }
+    }
+    /**
+   * Load a text resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchTextData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the text.
+   * @returns A promise that resolves to the loaded (and optionally processed) text.
+   * @internal
+   */ async loadTextData(url, postProcess, vfs) {
+        let text = await this.readFileFromVFS(url, {
             encoding: 'utf8'
-        }, VFSs);
+        }, vfs);
         if (postProcess) {
             try {
                 text = postProcess(text);
@@ -417,19 +418,19 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return text;
     }
-    /**
-   * Load a JSON resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchJsonData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the parsed JSON.
-   * @returns A promise that resolves to the loaded (and optionally processed) JSON.
-   * @internal
-   */ async loadJsonData(url, postProcess, VFSs) {
-        let json = JSON.parse(await this.readFileFromVFSs(url, {
+    /**
+   * Load a JSON resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchJsonData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the parsed JSON.
+   * @returns A promise that resolves to the loaded (and optionally processed) JSON.
+   * @internal
+   */ async loadJsonData(url, postProcess, vfs) {
+        let json = JSON.parse(await this.readFileFromVFS(url, {
             encoding: 'utf8'
-        }, VFSs));
+        }, vfs));
         if (postProcess) {
             try {
                 json = postProcess(json);
@@ -439,20 +440,20 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         return json;
     }
-    /**
-   * Load a binary resource via VFS and optionally post-process it.
-   *
-   * - Does not use or modify the internal cache; use fetchBinaryData for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @param postProcess - Optional transformation applied to the ArrayBuffer.
-   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
-   * @internal
-   */ async loadBinaryData(url, postProcess, VFSs) {
+    /**
+   * Load a binary resource via VFS and optionally post-process it.
+   *
+   * - Does not use or modify the internal cache; use fetchBinaryData for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @param postProcess - Optional transformation applied to the ArrayBuffer.
+   * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
+   * @internal
+   */ async loadBinaryData(url, postProcess, vfs) {
         try {
-            let data = await this.readFileFromVFSs(url, {
+            let data = await this.readFileFromVFS(url, {
                 encoding: 'binary'
-            }, VFSs);
+            }, vfs);
             if (postProcess) {
                 data = postProcess(data);
             }
@@ -462,11 +463,11 @@ import { FontAsset } from '../text/font/font_asset.js';
             return null;
         }
     }
-    async loadPrimitive(url, VFSs) {
+    async loadPrimitive(url, vfs) {
         try {
-            const data = await this.readFileFromVFSs(url, {
+            const data = await this.readFileFromVFS(url, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const content = JSON.parse(data);
             ASSERT(content.type === 'Primitive' || content.type === 'Default', `Unsupported primitive type: ${content.type}`);
             if (content.type === 'Primitive') {
@@ -532,20 +533,22 @@ import { FontAsset } from '../text/font/font_asset.js';
             }
         }
     }
-    async loadBluePrintMaterialData(url, reload, VFSs) {
+    async loadBluePrintMaterialData(url, reload, vfs) {
         try {
             let irData;
             if (typeof url === 'string') {
-                const data = await this.readFileFromVFSs(url, {
+                const data = await this.readFileFromVFS(url, {
                     encoding: 'utf8'
-                }, VFSs);
+                }, vfs);
                 const content = JSON.parse(data);
                 ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial', `Unsupported material type: ${content.type}`);
                 irData = content.data;
             } else {
                 irData = url;
             }
-            const ir = reload ? await this.loadBluePrint(irData.IR, VFSs) : await this.fetchBluePrint(irData.IR, VFSs);
+            const ir = reload ? await this.loadBluePrint(irData.IR, vfs) : await this.fetchBluePrint(irData.IR, vfs ? {
+                overrideVFS: vfs
+            } : undefined);
             const uniformValues = irData.uniformValues.map((v)=>({
                     ...v,
                     finalValue: v.value.length === 1 ? v.value[0] : new Float32Array(v.value)
@@ -554,8 +557,9 @@ import { FontAsset } from '../text/font/font_asset.js';
             const textures = irData.uniformTextures;
             for (const v of textures){
                 const tex = await this.fetchTexture(v.texture, {
-                    linearColorSpace: !v.sRGB
-                }, VFSs);
+                    linearColorSpace: !v.sRGB,
+                    overrideVFS: vfs
+                });
                 uniformTextures.push({
                     ...v,
                     finalTexture: new DRef(tex),
@@ -580,27 +584,27 @@ import { FontAsset } from '../text/font/font_asset.js';
             return null;
         }
     }
-    /**
-   * Load a material.
-   *
-   * - Does not use or modify the internal cache; use fetchMaterial for cached loads.
-   *
-   * @param url - Resource URL or VFS path.
-   * @returns A promise that resolves to the loaded material.
-   * @internal
-   */ async loadMaterial(url, reload, VFSs) {
+    /**
+   * Load a material.
+   *
+   * - Does not use or modify the internal cache; use fetchMaterial for cached loads.
+   *
+   * @param url - Resource URL or VFS path.
+   * @returns A promise that resolves to the loaded material.
+   * @internal
+   */ async loadMaterial(url, reload, vfs) {
         try {
-            const data = await this.readFileFromVFSs(url, {
+            const data = await this.readFileFromVFS(url, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const content = JSON.parse(data);
             ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial' || content.type === 'Default', `Unsupported material type: ${content.type}`);
             let mat;
             if (content.type === 'PBRBluePrintMaterial') {
-                const data = await this.loadBluePrintMaterialData(content.data, reload, VFSs);
+                const data = await this.loadBluePrintMaterialData(content.data, reload, vfs);
                 mat = new PBRBluePrintMaterial(data.irFragment, data.irVertex, data.uniformValues, data.uniformTextures);
             } else if (content.type === 'SpriteBluePrintMaterial') {
-                const data = await this.loadBluePrintMaterialData(content.data, reload, VFSs);
+                const data = await this.loadBluePrintMaterialData(content.data, reload, vfs);
                 mat = new SpriteBlueprintMaterial(data.irFragment, data.uniformValues, data.uniformTextures);
             } else {
                 const obj = await this._resourceManager.deserializeObject(null, content.data);
@@ -743,11 +747,11 @@ import { FontAsset } from '../text/font/font_asset.js';
     invalidateBluePrint(path) {
         delete this._bluePrints[path];
     }
-    async loadBluePrint(path, VFSs) {
+    async loadBluePrint(path, vfs) {
         try {
-            const content = await this.readFileFromVFSs(path, {
+            const content = await this.readFileFromVFS(path, {
                 encoding: 'utf8'
-            }, VFSs);
+            }, vfs);
             const bp = JSON.parse(content);
             ASSERT(bp.type === 'PBRMaterial' || bp.type === 'SpriteMaterial' || bp.type === 'MaterialFunction', `Unsupported blueprint type: ${bp.type}`);
             const states = bp.state;
@@ -773,19 +777,19 @@ import { FontAsset } from '../text/font/font_asset.js';
             return null;
         }
     }
-    /**
-   * Load a texture directly from an ArrayBuffer or typed array.
-   *
-   * - Chooses an appropriate loader based on the provided MIME type.
-   * - Can upload into an existing texture if `texture` is specified.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param arrayBuffer - Raw texture data buffer.
-   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options passed to the loader path.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
+    /**
+   * Load a texture directly from an ArrayBuffer or typed array.
+   *
+   * - Chooses an appropriate loader based on the provided MIME type.
+   * - Can upload into an existing texture if `texture` is specified.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param arrayBuffer - Raw texture data buffer.
+   * @param mimeType - MIME type of the texture (must be supported by a registered loader).
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options passed to the loader path.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
    */ async loadTextureFromBuffer(arrayBuffer, mimeType, srgb, samplerOptions, texture) {
         for (const loader of AssetManager._textureLoaders){
             if (!loader.supportMIMEType(mimeType)) {
@@ -796,24 +800,24 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         throw new Error(`Can not find loader for MIME type '${mimeType}'`);
     }
-    /**
-   * Load a texture via VFS by URL and MIME type.
-   *
-   * - Uses the first loader that supports the inferred or provided MIME type.
-   * - On WebGL, may repack textures (resample to power-of-two, convert formats) to meet backend constraints.
-   * - If `texture` is provided, the source is blitted into it, possibly resizing or changing sampling accordingly.
-   *
-   * @param url - Texture URL or VFS path.
-   * @param mimeType - Optional explicit MIME type; otherwise inferred by VFS.
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options for loader or blit path.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
-   * @internal
-   */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, VFSs) {
-        const data = await this.readFileFromVFSs(url, {
+    /**
+   * Load a texture via VFS by URL and MIME type.
+   *
+   * - Uses the first loader that supports the inferred or provided MIME type.
+   * - On WebGL, may repack textures (resample to power-of-two, convert formats) to meet backend constraints.
+   * - If `texture` is provided, the source is blitted into it, possibly resizing or changing sampling accordingly.
+   *
+   * @param url - Texture URL or VFS path.
+   * @param mimeType - Optional explicit MIME type; otherwise inferred by VFS.
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options for loader or blit path.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
+   * @internal
+   */ async loadTexture(url, mimeType, srgb, samplerOptions, texture, vfs) {
+        const data = await this.readFileFromVFS(url, {
             encoding: 'binary'
-        }, VFSs);
+        }, vfs);
         mimeType = mimeType ?? this.vfs.guessMIMEType(url);
         for (const loader of AssetManager._textureLoaders){
             if (!loader.supportMIMEType(mimeType)) {
@@ -827,18 +831,18 @@ import { FontAsset } from '../text/font/font_asset.js';
         }
         throw new Error(`Can not find loader for asset ${url}`);
     }
-    /**
-   * Internal routine that executes the texture load using a specific loader and applies
-   * backend-specific compatibility steps (e.g., WebGL NPOT/sRGB rules).
-   *
-   * @param loader - Concrete loader to use for decoding/creation.
-   * @param mimeType - Texture MIME type.
-   * @param data - Raw binary data.
-   * @param srgb - If true, treat image as sRGB; otherwise linear.
-   * @param samplerOptions - Optional sampler options.
-   * @param texture - Optional destination texture to populate.
-   * @returns A promise that resolves to the created or populated texture.
-   * @internal
+    /**
+   * Internal routine that executes the texture load using a specific loader and applies
+   * backend-specific compatibility steps (e.g., WebGL NPOT/sRGB rules).
+   *
+   * @param loader - Concrete loader to use for decoding/creation.
+   * @param mimeType - Texture MIME type.
+   * @param data - Raw binary data.
+   * @param srgb - If true, treat image as sRGB; otherwise linear.
+   * @param samplerOptions - Optional sampler options.
+   * @param texture - Optional destination texture to populate.
+   * @returns A promise that resolves to the created or populated texture.
+   * @internal
    */ async doLoadTexture(loader, mimeType, data, srgb, samplerOptions, texture) {
         const device = getDevice();
         if (device.type !== 'webgl') {
@@ -889,33 +893,22 @@ import { FontAsset } from '../text/font/font_asset.js';
             return tex;
         }
     }
-    /**
-   * Load a model via registered model loaders.
-   *
-   * - Selects loader by MIME type (explicit or inferred).
-   * - Optionally applies a post-process transform to the SharedModel.
-   * - Sets the model's name from the source filename for convenience.
-   *
-   * @param url - Model URL or VFS path.
-   * @param options - Model load options (MIME override, Draco module, post-process hook).
-   * @returns A promise that resolves to the loaded SharedModel.
-   * @internal
-   */ async loadModel(url, options, VFSs) {
-        const arrayBuffer = await this.readFileFromVFSs(url, {
-            encoding: 'binary'
-        }, VFSs);
-        const mimeType = options?.mimeType || this.vfs.guessMIMEType(url);
-        const data = new Blob([
-            arrayBuffer
-        ], {
-            type: mimeType
-        });
-        const filename = this.vfs.basename(url);
-        for (const loader of AssetManager._modelLoaders){
-            if (!loader.supportMIMEType(mimeType)) {
-                continue;
-            }
-            let model = await loader.load(this, url, options?.mimeType || data.type, data, options?.dracoDecoderModule, VFSs);
+    /**
+   * Load a model via registered model loaders.
+   *
+   * - Selects loader by MIME type (explicit or inferred).
+   * - Optionally applies a post-process transform to the SharedModel.
+   * - Sets the model's name from the source filename for convenience.
+   *
+   * @param url - Model URL or VFS path.
+   * @param options - Model load options (MIME override, Draco module, post-process hook).
+   * @returns A promise that resolves to the loaded SharedModel.
+   * @internal
+   */ async loadModel(url, options, vfs) {
+        const mimeType = options?.mimeType || guessMimeType(url);
+        const importer = this._modelLoaders[mimeType];
+        if (importer) {
+            let model = await importer.loadModel(url, vfs);
             if (!model) {
                 throw new Error(`Load asset failed: ${url}`);
             }
@@ -926,22 +919,21 @@ import { FontAsset } from '../text/font/font_asset.js';
                     throw new Error(`Model loader post process failed: ${err}`);
                 }
             }
-            model.name = filename;
             return model;
         }
         throw new Error(`Can not find loader for asset ${url}`);
     }
-    /**
-   * Fetch a built-in texture synchronously by name.
-   *
-   * - If this built-in was not created yet, the registered loader is invoked.
-   * - Registers a device restore handler so the texture can be re-initialized after device loss.
-   * - If an existing texture is provided, the loader uploads into it.
-   *
-   * @typeParam T - Expected concrete texture type.
-   * @param name - Built-in texture identifier.
-   * @param texture - Optional destination texture to populate.
-   * @returns The built-in texture (created or populated).
+    /**
+   * Fetch a built-in texture synchronously by name.
+   *
+   * - If this built-in was not created yet, the registered loader is invoked.
+   * - Registers a device restore handler so the texture can be re-initialized after device loss.
+   * - If an existing texture is provided, the loader uploads into it.
+   *
+   * @typeParam T - Expected concrete texture type.
+   * @param name - Built-in texture identifier.
+   * @param texture - Optional destination texture to populate.
+   * @returns The built-in texture (created or populated).
    */ fetchBuiltinTexture(name, texture) {
         const loader = AssetManager._builtinTextureLoaders[name];
         if (!loader) {
@@ -961,14 +953,14 @@ import { FontAsset } from '../text/font/font_asset.js';
             return texture;
         }
     }
-    /**
-   * Override or unregister the loader for a named built-in texture.
-   *
-   * - Passing a valid loader function sets/overrides the creation path.
-   * - Passing `undefined` removes the loader mapping for the given name.
-   *
-   * @param name - Built-in texture identifier.
-   * @param loader - Factory that creates the built-in texture using the provided AssetManager.
+    /**
+   * Override or unregister the loader for a named built-in texture.
+   *
+   * - Passing a valid loader function sets/overrides the creation path.
+   * - Passing `undefined` removes the loader mapping for the given name.
+   *
+   * @param name - Built-in texture identifier.
+   * @param loader - Factory that creates the built-in texture using the provided AssetManager.
    */ static setBuiltinTextureLoader(name, loader) {
         if (loader) {
             this._builtinTextureLoaders[name] = loader;
@@ -976,54 +968,41 @@ import { FontAsset } from '../text/font/font_asset.js';
             delete this._builtinTextureLoaders[name];
         }
     }
-    /**
-   * Compute a cache key for texture requests.
-   *
-   * Includes texture type tag, URL, and color space choice to avoid cross-color-space cache collisions.
-   *
-   * @typeParam T - Texture type parameter (not used for runtime behavior; helps preserve generic intent).
-   * @param type - Logical texture type tag (e.g., '2d', 'cube').
-   * @param url - Resource URL or VFS path.
-   * @param options - Texture fetch options to incorporate into the key.
-   * @returns A string cache key combining type, URL, and color space choice.
-   * @internal
+    /**
+   * Compute a cache key for texture requests.
+   *
+   * Includes texture type tag, URL, and color space choice to avoid cross-color-space cache collisions.
+   *
+   * @typeParam T - Texture type parameter (not used for runtime behavior; helps preserve generic intent).
+   * @param type - Logical texture type tag (e.g., '2d', 'cube').
+   * @param url - Resource URL or VFS path.
+   * @param options - Texture fetch options to incorporate into the key.
+   * @returns A string cache key combining type, URL, and color space choice.
+   * @internal
    */ getHash(type, url, options) {
         return `${type}:${url}:${!options?.linearColorSpace}`;
     }
-    /**
-   * Try reading from file from a list of VFSs
-   *
-   * @param path - File path
-   * @param options - Read options
-   * @param vfsList - VFS list
-   * @returns File content
-   *
-   * @internal
-   */ async readFileFromVFSs(path, options, vfsList) {
-        vfsList = vfsList ?? [
-            this.vfs
-        ];
-        for (const vfs of vfsList){
-            try {
-                return await vfs.readFile(path, options);
-            } catch  {}
-        }
-        throw new VFSError(`File does not exist: ${path}`, 'ENOENT', path);
-    }
-    /**
-   * Write file to a list of VFSs
-   *
-   * @param path - File path
-   * @param data - Data to write
-   * @param options - Write options
-   * @param vfsList - Which VFSs will be written to
-   */ async writeFileToVFSs(path, data, options, vfsList) {
-        vfsList = vfsList ?? [
-            this.vfs
-        ];
-        for (const vfs of vfsList){
-            await vfs.writeFile(path, data, options);
-        }
+    /**
+   * Try reading from file from a VFS
+   *
+   * @param path - File path
+   * @param options - Read options
+   * @param vfs - VFS to read from
+   * @returns File content
+   *
+   * @internal
+   */ async readFileFromVFS(path, options, vfs) {
+        return await (vfs ?? this.vfs).readFile(path, options);
+    }
+    /**
+   * Write file to a VFS
+   *
+   * @param path - File path
+   * @param data - Data to write
+   * @param options - Write options
+   * @param vfs - VFS to write to
+   */ async writeFileToVFSs(path, data, options, vfs) {
+        await (vfs ?? this.vfs).writeFile(path, data, options);
     }
 }