@zephyr3d/scene 0.9.25 → 0.9.27

package/dist/asset/assetmanager.js

@@ -16,19 +16,24 @@ import '../material/unlit.js';
 import '../material/particle.js';
 import '../material/subsurfaceprofile.js';
 import '../material/skin.js';
+import '../material/eye.js';
 import { Material } from '../material/material.js';
 import '../material/meshmaterial.js';
+import '../material/hair.js';
+import '../material/hairstrand.js';
 import '../material/grassmaterial.js';
 import '../material/terrain-cm.js';
 import '../material/pbrmr.js';
 import '../material/pbrsg.js';
 import '../material/mtoon.js';
 import { PBRBluePrintMaterial } from '../material/pbrblueprint.js';
+import { PBRBluePrintMaterialInstance } from '../material/pbrblueprint_instance.js';
 import '../material/sprite.js';
 import '../material/sprite_std.js';
 import { SpriteBlueprintMaterial } from '../material/spriteblueprint.js';
 import { BoundingBox } from '../utility/bounding_volume.js';
 import { MaterialBlueprintIR } from '../utility/blueprint/material/ir.js';
+import { getDefaultTexture2D } from '../utility/blueprint/material/texture.js';
 import '../render/render_queue.js';
 import '../render/rendergraph/forward_plus_builder.js';
 import '../render/lightpass.js';
@@ -76,6 +81,8 @@ import { FontAsset } from '../text/font/font_asset.js';
     /** @internal */ _primitives;
     /** @internal */ _skeletons;
     /** @internal */ _jsonDatas;
+    /** @internal */ _cacheKeysByPath;
+    /** @internal */ _cachePathByKey;
     /** @internal */ _resourceManager;
     /**
    * Creates an instance of AssetManager
@@ -91,6 +98,8 @@ import { FontAsset } from '../text/font/font_asset.js';
         this._fontAssets = {};
         this._textDatas = {};
         this._jsonDatas = {};
+        this._cacheKeysByPath = new Map();
+        this._cachePathByKey = new Map();
     }
     /**
    * VFS used to read resources (files, URLs, virtual mounts).
@@ -105,45 +114,149 @@ import { FontAsset } from '../text/font/font_asset.js';
    * - 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];
-            if (v instanceof DWeakRef) {
-                v.dispose();
+        this.clearCacheEntries(this._textures);
+        this._textures = {};
+        this.clearCacheEntries(this._models);
+        this._models = {};
+        this.clearCacheEntries(this._materials);
+        this._materials = {};
+        this.clearCacheEntries(this._primitives);
+        this._primitives = {};
+        this.clearCacheEntries(this._skeletons);
+        this._skeletons = {};
+        this._bluePrints = {};
+        this._fontAssets = {};
+        this._binaryDatas = {};
+        this._textDatas = {};
+        this._jsonDatas = {};
+        this._cacheKeysByPath.clear();
+        this._cachePathByKey.clear();
+    }
+    /**
+   * Evicts cached data loaded from a VFS path.
+   *
+   * Existing scene objects keep their current resources. Subsequent loads read the asset again.
+   *
+   * @param path - Changed VFS file or directory path.
+   * @param recursive - Whether entries below a directory path should also be evicted.
+   * @returns Number of cache entries removed.
+   */ invalidateAsset(path, recursive = false) {
+        const normalizedPath = this.vfs.normalizePath(path);
+        let removed = 0;
+        const indexedPaths = recursive ? [
+            ...this._cacheKeysByPath.keys()
+        ].filter((sourcePath)=>this.cachePathMatches(sourcePath, normalizedPath, true)) : [
+            normalizedPath
+        ];
+        for (const sourcePath of indexedPaths){
+            const tokens = this._cacheKeysByPath.get(sourcePath);
+            if (!tokens) {
+                continue;
+            }
+            for (const token of [
+                ...tokens
+            ]){
+                const separator = token.indexOf('\0');
+                const kind = token.slice(0, separator);
+                const key = token.slice(separator + 1);
+                if (this.removeCacheEntry(kind, key)) {
+                    removed++;
+                }
             }
         }
-        this._textures = {};
-        for(const k in Object.keys(this._models)){
-            const v = this._models[k];
-            if (v instanceof DWeakRef) {
-                v.dispose();
+        return removed;
+    }
+    clearCacheEntries(cache, matches = ()=>true) {
+        let removed = 0;
+        for (const key of Object.keys(cache)){
+            if (!matches(key)) {
+                continue;
             }
+            const cached = cache[key];
+            if (cached instanceof DWeakRef) {
+                cached.dispose();
+            }
+            delete cache[key];
+            removed++;
         }
-        this._models = {};
-        for(const k in Object.keys(this._materials)){
-            const v = this._materials[k];
-            if (v instanceof DWeakRef) {
-                v.dispose();
+        return removed;
+    }
+    cachePathMatches(cachePath, normalizedPath, recursive) {
+        return cachePath === normalizedPath || recursive && cachePath.startsWith(normalizedPath.endsWith('/') ? normalizedPath : `${normalizedPath}/`);
+    }
+    normalizeAssetSourcePath(path) {
+        return /^(?:[a-z]+:)?\/\//i.test(path) || path.startsWith('data:') || path.startsWith('blob:') ? path : this.vfs.normalizePath(path);
+    }
+    getCache(kind) {
+        switch(kind){
+            case 'texture':
+                return this._textures;
+            case 'model':
+                return this._models;
+            case 'binary':
+                return this._binaryDatas;
+            case 'font':
+                return this._fontAssets;
+            case 'text':
+                return this._textDatas;
+            case 'blueprint':
+                return this._bluePrints;
+            case 'material':
+                return this._materials;
+            case 'primitive':
+                return this._primitives;
+            case 'skeleton':
+                return this._skeletons;
+            case 'json':
+                return this._jsonDatas;
+        }
+    }
+    getCacheToken(kind, key) {
+        return `${kind}\0${key}`;
+    }
+    trackCacheEntry(kind, key, sourcePath) {
+        const token = this.getCacheToken(kind, key);
+        const normalizedSourcePath = this.normalizeAssetSourcePath(sourcePath);
+        const previousPath = this._cachePathByKey.get(token);
+        if (previousPath === normalizedSourcePath) {
+            return;
+        }
+        if (previousPath) {
+            const previousKeys = this._cacheKeysByPath.get(previousPath);
+            previousKeys?.delete(token);
+            if (previousKeys?.size === 0) {
+                this._cacheKeysByPath.delete(previousPath);
             }
         }
-        this._materials = {};
-        for(const k in Object.keys(this._primitives)){
-            const v = this._primitives[k];
-            if (v instanceof DWeakRef) {
-                v.dispose();
+        let keys = this._cacheKeysByPath.get(normalizedSourcePath);
+        if (!keys) {
+            keys = new Set();
+            this._cacheKeysByPath.set(normalizedSourcePath, keys);
+        }
+        keys.add(token);
+        this._cachePathByKey.set(token, normalizedSourcePath);
+    }
+    removeCacheEntry(kind, key) {
+        const cache = this.getCache(kind);
+        const existed = key in cache;
+        if (existed) {
+            const cached = cache[key];
+            if (cached instanceof DWeakRef) {
+                cached.dispose();
             }
+            delete cache[key];
         }
-        this._primitives = {};
-        for(const k in Object.keys(this._skeletons)){
-            const v = this._skeletons[k];
-            if (v instanceof DWeakRef) {
-                v.dispose();
+        const token = this.getCacheToken(kind, key);
+        const sourcePath = this._cachePathByKey.get(token);
+        if (sourcePath) {
+            const keys = this._cacheKeysByPath.get(sourcePath);
+            keys?.delete(token);
+            if (keys?.size === 0) {
+                this._cacheKeysByPath.delete(sourcePath);
             }
+            this._cachePathByKey.delete(token);
         }
-        this._skeletons = {};
-        this._fontAssets = {};
-        this._binaryDatas = {};
-        this._textDatas = {};
-        this._jsonDatas = {};
+        return existed;
     }
     /**
    * Removes a cached font asset entry by URL.
@@ -153,11 +266,15 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @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];
-            return true;
-        }
-        return false;
+        return this.removeCacheEntry('font', url);
+    }
+    /**
+   * Remove one material entry from cache.
+   *
+   * @param url - Material asset path.
+   * @returns `true` if an entry existed and was removed.
+   */ invalidateMaterial(url) {
+        return this.removeCacheEntry('material', url);
     }
     /**
    * Register a texture loader (highest priority first).
@@ -194,6 +311,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         if (!P) {
             P = this.loadTextData(url, postProcess, options?.overrideVFS);
             this._textDatas[hash] = P;
+            this.trackCacheEntry('text', hash, url);
         }
         return P;
     }
@@ -213,6 +331,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         if (!P) {
             P = this.loadJsonData(url, postProcess, options?.overrideVFS);
             this._jsonDatas[hash] = P;
+            this.trackCacheEntry('json', hash, url);
         }
         return P;
     }
@@ -224,6 +343,7 @@ import { FontAsset } from '../text/font/font_asset.js';
    * @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.
+   * @param options - Optional fetch options
    * @returns A promise that resolves to the loaded (and optionally processed) ArrayBuffer.
    */ async fetchBinaryData(url, postProcess, httpRequest, options) {
         const hash = httpRequest?.urlResolver?.(url) ?? url;
@@ -231,6 +351,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         if (!P) {
             P = this.loadBinaryData(url, postProcess, options?.overrideVFS);
             this._binaryDatas[hash] = P;
+            this.trackCacheEntry('binary', hash, url);
         }
         return P;
     }
@@ -256,6 +377,7 @@ import { FontAsset } from '../text/font/font_asset.js';
                 });
             });
             this._fontAssets[hash] = P;
+            this.trackCacheEntry('font', hash, url);
         }
         return P;
     }
@@ -273,6 +395,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         if (!P) {
             P = this.loadBluePrint(url, options?.overrideVFS);
             this._bluePrints[hash] = P;
+            this.trackCacheEntry('blueprint', hash, url);
         }
         return P;
     }
@@ -290,9 +413,10 @@ import { FontAsset } from '../text/font/font_asset.js';
         } else if (!P || P instanceof DWeakRef) {
             P = this.loadMaterial(url, false, options?.overrideVFS);
             this._materials[hash] = P;
+            this.trackCacheEntry('material', hash, url);
         }
         const material = await P;
-        if (this._materials[hash] instanceof Promise) {
+        if (this._materials[hash] === P) {
             this._materials[hash] = new DWeakRef(material);
         }
         return material;
@@ -311,9 +435,10 @@ import { FontAsset } from '../text/font/font_asset.js';
         } else if (!P || P instanceof DWeakRef) {
             P = this.loadPrimitive(url, options?.overrideVFS);
             this._primitives[hash] = P;
+            this.trackCacheEntry('primitive', hash, url);
         }
         const primitive = await P;
-        if (this._primitives[hash] instanceof Promise) {
+        if (this._primitives[hash] === P) {
             this._primitives[hash] = new DWeakRef(primitive);
         }
         return primitive;
@@ -342,9 +467,10 @@ import { FontAsset } from '../text/font/font_asset.js';
             } else if (!P || P instanceof DWeakRef) {
                 P = this.loadTexture(url, options?.mimeType ?? null, !options?.linearColorSpace, options?.samplerOptions, null, options?.overrideVFS);
                 this._textures[hash] = P;
+                this.trackCacheEntry('texture', hash, url);
             }
             const tex = await P;
-            if (this._textures[hash] instanceof Promise) {
+            if (this._textures[hash] === P) {
                 this._textures[hash] = new DWeakRef(tex);
             }
             return tex;
@@ -368,9 +494,10 @@ import { FontAsset } from '../text/font/font_asset.js';
         } else if (!P || P instanceof DWeakRef) {
             P = this.loadModel(url, options, options?.overrideVFS);
             this._models[hash] = P;
+            this.trackCacheEntry('model', hash, url);
         }
         const sharedModel = await P;
-        if (this._models[hash] instanceof Promise) {
+        if (this._models[hash] === P) {
             this._models[hash] = new DWeakRef(sharedModel);
         }
         return sharedModel;
@@ -526,18 +653,68 @@ import { FontAsset } from '../text/font/font_asset.js';
             }
         }
         const materials = await Promise.all(promises);
+        const knownPaths = new Set(paths);
+        for (const assetId of this._resourceManager.getTrackedMaterialAssetIds()){
+            if (knownPaths.has(assetId)) {
+                continue;
+            }
+            const refs = this._resourceManager.getMaterialRefsByAssetId(assetId);
+            for (const ref of refs ?? []){
+                const material = ref.get();
+                if (material instanceof PBRBluePrintMaterial && !material.disposed) {
+                    materials.push(material);
+                    paths.push(assetId);
+                    knownPaths.add(assetId);
+                    break;
+                }
+            }
+        }
+        // Reload blueprint parents first so dependent instances always resync against the latest parent state.
         for(let i = 0; i < materials.length; i++){
             const m = materials[i];
-            if (m instanceof PBRBluePrintMaterial && (!filter || filter(m))) {
+            if (m instanceof PBRBluePrintMaterial && !(m instanceof PBRBluePrintMaterialInstance) && (!filter || filter(m))) {
+                const content = JSON.parse(await this.readFileFromVFS(paths[i], {
+                    encoding: 'utf8'
+                }));
                 const data = await this.loadBluePrintMaterialData(paths[i], true);
                 if (data) {
                     m.fragmentIR = data.irFragment;
                     m.vertexIR = data.irVertex;
                     m.uniformValues = data.uniformValues;
                     m.uniformTextures = data.uniformTextures;
+                    if (content.type === 'PBRBluePrintMaterial' && content.props) {
+                        await this._resourceManager.deserializeObjectProps(m, content.props);
+                    }
+                    this._resourceManager.syncMaterialReferences(m);
                 }
             }
         }
+        // Then reload instances from disk so override maps stay in sync with the refreshed parent materials.
+        for(let i = 0; i < materials.length; i++){
+            const m = materials[i];
+            if (m instanceof PBRBluePrintMaterialInstance && (!filter || filter(m))) {
+                const content = JSON.parse(await this.readFileFromVFS(paths[i], {
+                    encoding: 'utf8'
+                }));
+                if (content.type !== 'PBRBluePrintMaterialInstance' || !content.data?.parent) {
+                    continue;
+                }
+                const parent = await this.fetchMaterial(content.data.parent);
+                if (!(parent instanceof PBRBluePrintMaterial)) {
+                    continue;
+                }
+                m.setParentMaterial(parent, content.data.parent);
+                m.setOverrides(content.data.uniformValues ?? [], await this.hydrateBluePrintUniformTextures(content.data.uniformTextures ?? []));
+                const instanceContent = JSON.parse(await this.readFileFromVFS(paths[i], {
+                    encoding: 'utf8'
+                }));
+                if (instanceContent.type === 'PBRBluePrintMaterialInstance' && instanceContent.props) {
+                    await this._resourceManager.deserializeObjectProps(m, instanceContent.props);
+                }
+                m.setMaterialPropertyOverrides(Object.keys(instanceContent.props ?? {}));
+                this._resourceManager.syncMaterialReferences(m);
+            }
+        }
     }
     async loadBluePrintMaterialData(url, reload, vfs) {
         try {
@@ -547,8 +724,23 @@ import { FontAsset } from '../text/font/font_asset.js';
                     encoding: 'utf8'
                 }, vfs);
                 const content = JSON.parse(data);
-                ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial', `Unsupported material type: ${content.type}`);
-                irData = content.data;
+                ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'PBRBluePrintMaterialInstance' || content.type === 'SpriteBluePrintMaterial', `Unsupported material type: ${content.type}`);
+                if (content.type === 'PBRBluePrintMaterialInstance') {
+                    const parentPath = content.data.parent;
+                    ASSERT(typeof parentPath === 'string' && !!parentPath, 'Blueprint material instance requires parent');
+                    const parentContent = JSON.parse(await this.readFileFromVFS(parentPath, {
+                        encoding: 'utf8'
+                    }, vfs));
+                    ASSERT(parentContent.type === 'PBRBluePrintMaterial', `Invalid parent blueprint material: ${parentPath}`);
+                    irData = {
+                        IR: parentContent.data?.IR ?? content.data.IR ?? '',
+                        uniformValues: content.data.uniformValues ?? parentContent.data?.uniformValues ?? [],
+                        uniformTextures: content.data.uniformTextures ?? parentContent.data?.uniformTextures ?? []
+                    };
+                    ASSERT(!!irData.IR, `Parent blueprint material missing IR path: ${parentPath}`);
+                } else {
+                    irData = content.data;
+                }
             } else {
                 irData = url;
             }
@@ -559,26 +751,7 @@ import { FontAsset } from '../text/font/font_asset.js';
                     ...v,
                     finalValue: v.value.length === 1 ? v.value[0] : new Float32Array(v.value)
                 }));
-            const uniformTextures = [];
-            const textures = irData.uniformTextures;
-            for (const v of textures){
-                const tex = await this.fetchTexture(v.texture, {
-                    linearColorSpace: !v.sRGB,
-                    overrideVFS: vfs
-                });
-                uniformTextures.push({
-                    ...v,
-                    finalTexture: new DRef(tex),
-                    finalSampler: getDevice().createSampler({
-                        addressU: v.wrapS,
-                        addressV: v.wrapT,
-                        minFilter: v.minFilter,
-                        magFilter: v.magFilter,
-                        mipFilter: v.mipFilter
-                    }),
-                    params: tex ? new Vector4(tex.width, tex.height, tex.depth, tex.mipLevelCount) : Vector4.zero()
-                });
-            }
+            const uniformTextures = await this.hydrateBluePrintUniformTextures(irData.uniformTextures, vfs);
             return {
                 irFragment: ir?.['fragment'] ?? null,
                 irVertex: ir?.['vertex'] ?? null,
@@ -604,11 +777,19 @@ import { FontAsset } from '../text/font/font_asset.js';
                 encoding: 'utf8'
             }, vfs);
             const content = JSON.parse(data);
-            ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'SpriteBluePrintMaterial' || content.type === 'Default', `Unsupported material type: ${content.type}`);
+            ASSERT(content.type === 'PBRBluePrintMaterial' || content.type === 'PBRBluePrintMaterialInstance' || 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, vfs);
                 mat = new PBRBluePrintMaterial(data.irFragment, data.irVertex, data.uniformValues, data.uniformTextures);
+            } else if (content.type === 'PBRBluePrintMaterialInstance') {
+                const parentMaterial = await this.fetchMaterial(content.data.parent, vfs ? {
+                    overrideVFS: vfs
+                } : undefined);
+                ASSERT(parentMaterial instanceof PBRBluePrintMaterial, `Invalid parent blueprint material: ${content.data.parent}`);
+                const instance = new PBRBluePrintMaterialInstance(parentMaterial, content.data.parent);
+                instance.setOverrides(content.data.uniformValues ?? [], await this.hydrateBluePrintUniformTextures(content.data.uniformTextures ?? [], vfs));
+                mat = instance;
             } else if (content.type === 'SpriteBluePrintMaterial') {
                 const data = await this.loadBluePrintMaterialData(content.data, reload, vfs);
                 mat = new SpriteBlueprintMaterial(data.irFragment, data.uniformValues, data.uniformTextures);
@@ -625,12 +806,45 @@ import { FontAsset } from '../text/font/font_asset.js';
             if (mat && content.props) {
                 await this._resourceManager.deserializeObjectProps(mat, content.props);
             }
+            if (mat instanceof PBRBluePrintMaterialInstance) {
+                mat.setMaterialPropertyOverrides(Object.keys(content.props ?? {}));
+                mat.syncInheritedUniforms();
+            }
             return mat;
         } catch (err) {
             console.error(`Load material failed: ${err}`);
             return null;
         }
     }
+    async hydrateBluePrintUniformTextures(textures, vfs) {
+        return Promise.all((textures ?? []).map(async (v)=>{
+            let tex = null;
+            if (v.texture) {
+                try {
+                    tex = await this.fetchTexture(v.texture, {
+                        linearColorSpace: !v.sRGB,
+                        overrideVFS: vfs
+                    });
+                } catch (err) {
+                    console.warn(`Load blueprint texture failed: ${v.texture}: ${String(err)}`);
+                }
+            }
+            tex = tex ?? getDefaultTexture2D();
+            return {
+                ...v,
+                exposed: v.exposed ?? true,
+                finalTexture: new DRef(tex),
+                finalSampler: getDevice().createSampler({
+                    addressU: v.wrapS,
+                    addressV: v.wrapT,
+                    minFilter: v.minFilter,
+                    magFilter: v.magFilter,
+                    mipFilter: v.mipFilter
+                }),
+                params: tex ? new Vector4(tex.width, tex.height, tex.depth, tex.mipLevelCount) : Vector4.zero()
+            };
+        }));
+    }
     rebuildGraphStructure(nodes, links) {
         const gs = {
             outgoing: {},
@@ -751,7 +965,7 @@ import { FontAsset } from '../text/font/font_asset.js';
         };
     }
     invalidateBluePrint(path) {
-        delete this._bluePrints[path];
+        this.removeCacheEntry('blueprint', path);
     }
     async loadBluePrint(path, vfs) {
         try {
@@ -766,11 +980,14 @@ import { FontAsset } from '../text/font/font_asset.js';
                 const roots = [];
                 const nodeMap = {};
                 const state = states[k];
-                for (const node of state.nodes){
-                    const impl = await this._resourceManager.deserializeObject(null, node.node);
-                    nodeMap[node.id] = impl;
+                const nodes = await Promise.all(state.nodes.map(async (node)=>({
+                        id: node.id,
+                        impl: await this._resourceManager.deserializeObject(null, node.node)
+                    })));
+                for (const { id, impl } of nodes){
+                    nodeMap[id] = impl;
                     if (impl.outputs.length === 0) {
-                        roots.push(node.id);
+                        roots.push(id);
                     }
                 }
                 const dag = await this.createBluePrintDAG(nodeMap, roots, state.links);