@zephyr3d/scene 0.9.3 → 0.9.4

package/dist/utility/serialization/manager.js

@@ -31,11 +31,12 @@ import '../../material/pbrsg.js';
 import '../../material/pbrblueprint.js';
 import '../../material/sprite.js';
 import '../../material/sprite_std.js';
+import '../../material/msdf_text.js';
 import { PBRBlockNode, SpriteBlockNode, VertexBlockNode } from '../blueprint/material/pbr.js';
 import { ConstantScalarNode, ConstantVec2Node, ConstantVec3Node, ConstantVec4Node, ConstantBooleanNode, ConstantBVec2Node, ConstantBVec3Node, ConstantBVec4Node } from '../blueprint/common/constants.js';
 import { ConstantTexture2DNode, ConstantTexture2DArrayNode, ConstantTextureCubeNode, PannerNode, TextureSampleNode } from '../blueprint/material/texture.js';
 import { MakeVectorNode, SwizzleNode, EqualNode, NotEqualNode, LogicallyAndNode, LogicallyOrNode, CompComparisonNode, AnyConditionNode, AllConditionNode, SelectionNode, Degrees2RadiansNode, Radians2DegreesNode, SinNode, CosNode, TanNode, ArcSinNode, ArcCosNode, ArcTanNode, ArcTan2Node, SinHNode, CosHNode, TanHNode, ArcsineHNode, ArccosineHNode, ArctangentHNode, ExpNode, Exp2Node, LogNode, Log2Node, SqrtNode, InvSqrtNode, AbsNode, SignNode, FloorNode, CeilNode, FractNode, DDXNode, DDYNode, FWidthNode, CompAddNode, CompSubNode, CompMulNode, CompDivNode, ModNode, MinNode, MaxNode, PowNode, StepNode, SmoothStepNode, FmaNode, ClampNode, SaturateNode, MixNode, NormalizeNode, TransformNode, RotateAboutAxisNode, FaceForwardNode, ReflectNode, RefractNode, LengthNode, DistanceNode, DotProductNode, CrossProductNode, Hash1Node, Hash2Node, Hash3Node, SimplexNoise2DNode, PerlinNoise2DNode } from '../blueprint/common/math.js';
-import { VertexColorNode, VertexUVNode, VertexPositionNode, PixelWorldPositionNode, VertexNormalNode, PixelNormalNode, VertexTangentNode, VertexBinormalNode, ViewMatrixNode, ProjectionMatrixNode, ViewProjMatrixNode, InvProjMatrixNode, InvViewProjMatrixNode, BillboardMatrixNode, CameraPositionNode, CameraVectorNode, CameraNearFarNode, SkyEnvTextureNode, ElapsedTimeNode, ResolveVertexPositionNode, ResolveVertexTangentNode, ResolveVertexNormalNode } from '../blueprint/material/inputs.js';
+import { VertexOutputNode, VertexIndexNode, InstanceIndexNode, VertexColorNode, VertexUVNode, VertexPositionNode, PixelWorldPositionNode, VertexNormalNode, PixelNormalNode, VertexTangentNode, VertexBinormalNode, ViewMatrixNode, ProjectionMatrixNode, ViewProjMatrixNode, InvProjMatrixNode, InvViewProjMatrixNode, BillboardMatrixNode, CameraPositionNode, CameraVectorNode, CameraNearFarNode, SkyEnvTextureNode, ElapsedTimeNode, ResolveVertexPositionNode, ResolveVertexTangentNode, ResolveVertexNormalNode } from '../blueprint/material/inputs.js';
 import { FunctionInputNode, FunctionOutputNode, FunctionCallNode } from '../blueprint/material/func.js';
 import '../../render/rendergraph/forward_plus_builder.js';
 import '../../render/sky.js';
@@ -45,6 +46,7 @@ import { SceneNode } from '../../scene/scene_node.js';
 import '../../shadow/shadowmapper.js';
 import '../../scene/mesh.js';
 import '../../scene/basesprite.js';
+import '../../scene/meshdrawable.js';
 import '../../scene/water.js';
 import '../../scene/particlesys.js';
 import '../../scene/batchgroup.js';
@@ -59,6 +61,7 @@ import '../../animation/joint_dynamics/solver.js';
 import '../../animation/joint_dynamics/joint_dynamics_system.js';
 import { getJSONPropClass, getJSONNumberClass, getJSONStringClass, getJSONBoolClass, getJSONObjectClass, getJSONArrayClass } from './json.js';
 import { getSpriteClass } from './scene/sprite.js';
+import { getTextSpriteClass, getMSDFTextSpriteClass, getMSDFTextClass } from './scene/text.js';
 
 const defaultValues = {
     bool: false,
@@ -111,29 +114,29 @@ const defaultValues = {
     ],
     command: null
 };
-/**
- * Manages serialization and deserialization of engine objects to/from JSON,
- * including asset resolution via a virtual file system (VFS) and asset manager.
- *
- * @remarks
- * - Keeps a registry of serializable classes and their properties.
- * - Converts object graphs to JSON using per-class metadata and property accessors.
- * - Supports async asset embedding/export and lazy deserialization via phases.
- * - Maps loaded assets/objects back to their source IDs for caching and deduplication.
- *
- * Typical workflow:
- * 1. Construct with a `VFS`.
- * 2. Optionally `registerClass` for custom types.
- * 3. Use `serializeObject` and `deserializeObject` to convert between runtime objects and JSON.
- * 4. Use `saveScene` / `loadScene` for scene I/O.
- *
- * Caching:
- * - `getAssetId` returns the known source ID for an allocated asset when available.
- *
- * Threading:
- * - Methods returning Promises perform async I/O using the provided `VFS`/AssetManager.
- *
- * @public
+/**
+ * Manages serialization and deserialization of engine objects to/from JSON,
+ * including asset resolution via a virtual file system (VFS) and asset manager.
+ *
+ * @remarks
+ * - Keeps a registry of serializable classes and their properties.
+ * - Converts object graphs to JSON using per-class metadata and property accessors.
+ * - Supports async asset embedding/export and lazy deserialization via phases.
+ * - Maps loaded assets/objects back to their source IDs for caching and deduplication.
+ *
+ * Typical workflow:
+ * 1. Construct with a `VFS`.
+ * 2. Optionally `registerClass` for custom types.
+ * 3. Use `serializeObject` and `deserializeObject` to convert between runtime objects and JSON.
+ * 4. Use `saveScene` / `loadScene` for scene I/O.
+ *
+ * Caching:
+ * - `getAssetId` returns the known source ID for an allocated asset when available.
+ *
+ * Threading:
+ * - Methods returning Promises perform async I/O using the provided `VFS`/AssetManager.
+ *
+ * @public
  */ class ResourceManager {
     _classMap;
     _vfs;
@@ -143,10 +146,10 @@ const defaultValues = {
     _assetManager;
     _editorMode;
     _allocated;
-    /**
-   * Create a ResourceManager bound to a virtual file system.
-   *
-   * @param vfs - Virtual file system used for reading/writing assets and scenes.
+    /**
+   * Create a ResourceManager bound to a virtual file system.
+   *
+   * @param vfs - Virtual file system used for reading/writing assets and scenes.
    */ constructor(vfs, editorMode = false){
         this._vfs = vfs;
         this._editorMode = editorMode;
@@ -179,6 +182,9 @@ const defaultValues = {
             getGraphNodeClass(),
             getMeshClass(),
             getSpriteClass(),
+            getTextSpriteClass(),
+            getMSDFTextSpriteClass(),
+            getMSDFTextClass(),
             getWaterClass(this),
             getTerrainClass(this),
             getFFTWaveGeneratorClass(),
@@ -292,6 +298,9 @@ const defaultValues = {
             Hash3Node.getSerializationCls(),
             SimplexNoise2DNode.getSerializationCls(),
             PerlinNoise2DNode.getSerializationCls(),
+            VertexOutputNode.getSerializationCls(),
+            VertexIndexNode.getSerializationCls(),
+            InstanceIndexNode.getSerializationCls(),
             VertexColorNode.getSerializationCls(),
             VertexUVNode.getSerializationCls(),
             VertexPositionNode.getSerializationCls(),
@@ -330,49 +339,49 @@ const defaultValues = {
             this.registerProps(k[1]);
         }
     }
-    /**
-   * The virtual file system used by this manager.
-   *
-   * @remarks
-   * Used by asset fetchers and scene save/load operations.
+    /**
+   * The virtual file system used by this manager.
+   *
+   * @remarks
+   * Used by asset fetchers and scene save/load operations.
    */ get VFS() {
         return this._vfs;
     }
     set VFS(vfs) {
         this._vfs = vfs;
     }
-    /**
-   * Wethether editor mode is enabled
-   *
-   * @remarks
-   * In editor mode, some properties will be disabled
+    /**
+   * Wethether editor mode is enabled
+   *
+   * @remarks
+   * In editor mode, some properties will be disabled
    */ get editorMode() {
         return this._editorMode;
     }
-    /**
-   * AssetManager
+    /**
+   * AssetManager
    */ get assetManager() {
         return this._assetManager;
     }
-    /**
-   * Get the list of all registered serializable classes.
-   *
-   * @remarks
-   * Includes built-in classes registered during construction and any custom classes
-   * registered via `registerClass`.
-   *
-   * @returns An array of `SerializableClass` metadata.
+    /**
+   * Get the list of all registered serializable classes.
+   *
+   * @remarks
+   * Includes built-in classes registered during construction and any custom classes
+   * registered via `registerClass`.
+   *
+   * @returns An array of `SerializableClass` metadata.
    */ getClasses() {
         return [
             ...this._classMap.values()
         ];
     }
-    /**
-   * Get serialization metadata by a constructor function.
-   *
-   * @param ctor - The class constructor to look up.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by a constructor function.
+   *
+   * @param ctor - The class constructor to look up.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByConstructor(ctor) {
         let current = ctor;
         while(typeof current === 'function' && current !== Function.prototype){
@@ -384,21 +393,21 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Get serialization metadata by an object instance.
-   *
-   * @param obj - The object whose constructor will be used for the lookup.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by an object instance.
+   *
+   * @param obj - The object whose constructor will be used for the lookup.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByObject(obj) {
         return this.getClassByConstructor(obj.constructor);
     }
-    /**
-   * Get serialization metadata by class name.
-   *
-   * @param className - Fully qualified class name as stored in JSON.
-   *
-   * @returns The `SerializableClass` metadata, or `null` if not found.
+    /**
+   * Get serialization metadata by class name.
+   *
+   * @param className - Fully qualified class name as stored in JSON.
+   *
+   * @returns The `SerializableClass` metadata, or `null` if not found.
    */ getClassByName(className) {
         for (const val of this._classMap){
             if (val[0].name === className) {
@@ -407,12 +416,12 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Find the class that owns a given property accessor.
-   *
-   * @param prop - Property accessor to search for.
-   *
-   * @returns The `SerializableClass` that declares the property, or `null` if unknown.
+    /**
+   * Find the class that owns a given property accessor.
+   *
+   * @param prop - Property accessor to search for.
+   *
+   * @returns The `SerializableClass` that declares the property, or `null` if unknown.
    */ getClassByProperty(prop) {
         for (const k of this._clsPropMap){
             if (k[1].indexOf(prop) >= 0) {
@@ -421,21 +430,21 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Get the properties declared on a given class.
-   *
-   * @param cls - Serializable class metadata.
-   *
-   * @returns An array of `PropertyAccessor` entries, or `null` if none.
+    /**
+   * Get the properties declared on a given class.
+   *
+   * @param cls - Serializable class metadata.
+   *
+   * @returns An array of `PropertyAccessor` entries, or `null` if none.
    */ getPropertiesByClass(cls) {
         return this._clsPropMap.get(cls) ?? null;
     }
-    /**
-   * Get all properties declared on a given class and its ancestors.
-   *
-   * @param cls - Serializable class metadata.
-   *
-   * @returns An array of `PropertyAccessor` entries, or `null` if none.
+    /**
+   * Get all properties declared on a given class and its ancestors.
+   *
+   * @param cls - Serializable class metadata.
+   *
+   * @returns An array of `PropertyAccessor` entries, or `null` if none.
    */ getAllPropertiesByClass(cls) {
         const props = new Map();
         while(cls){
@@ -453,72 +462,72 @@ const defaultValues = {
             ...props.values()
         ];
     }
-    /**
-   * Get a property accessor by class and property name.
-   *
-   * @param cls - Serializable class metadata.
-   * @param name - Property name to search for.
-   *
-   * @returns The `PropertyAccessor`, or `null` if not found.
+    /**
+   * Get a property accessor by class and property name.
+   *
+   * @param cls - Serializable class metadata.
+   * @param name - Property name to search for.
+   *
+   * @returns The `PropertyAccessor`, or `null` if not found.
    */ getPropertyByClass(cls, name) {
         return this.getPropertiesByClass(cls)?.find((value)=>value.name === name) ?? null;
     }
-    /**
-   * Get a property accessor by its canonical path.
-   *
-   * @remarks
-   * The canonical path format is `/ClassName/propName`.
-   *
-   * @param name - Canonical property path.
-   *
-   * @returns The `PropertyAccessor`, or `null` if not found.
+    /**
+   * Get a property accessor by its canonical path.
+   *
+   * @remarks
+   * The canonical path format is `/ClassName/propName`.
+   *
+   * @param name - Canonical property path.
+   *
+   * @returns The `PropertyAccessor`, or `null` if not found.
    */ getPropertyByName(name) {
         return this._propMap[name] ?? null;
     }
-    /**
-   * Get the canonical path for a property accessor.
-   *
-   * @remarks
-   * Returns a string like `/ClassName/propName` if the property is registered.
-   *
-   * @param prop - Property accessor.
-   *
-   * @returns The canonical path, or `null` if unknown.
+    /**
+   * Get the canonical path for a property accessor.
+   *
+   * @remarks
+   * Returns a string like `/ClassName/propName` if the property is registered.
+   *
+   * @param prop - Property accessor.
+   *
+   * @returns The canonical path, or `null` if unknown.
    */ getPropertyName(prop) {
         return this._propNameMap.get(prop) ?? null;
     }
-    /**
-   * Register a serializable class and its properties.
-   *
-   * @remarks
-   * - No effect if the class is already registered.
-   * - Also registers the class's properties with canonical paths.
-   *
-   * @param cls - Serializable class metadata to register.
+    /**
+   * Register a serializable class and its properties.
+   *
+   * @remarks
+   * - No effect if the class is already registered.
+   * - Also registers the class's properties with canonical paths.
+   *
+   * @param cls - Serializable class metadata to register.
    */ registerClass(cls) {
         if (!this._classMap.has(cls.ctor)) {
             this._classMap.set(cls.ctor, cls);
             this.registerProps(cls);
         }
     }
-    /**
-   * Get the known asset ID previously associated with a loaded/allocated asset.
-   *
-   * @remarks
-   * Returns `null` if the asset was not loaded or tracked by this manager.
-   *
-   * @param asset - Asset instance (e.g., texture, model group) to look up.
-   *
-   * @returns The asset ID string, or `null` if unknown.
+    /**
+   * Get the known asset ID previously associated with a loaded/allocated asset.
+   *
+   * @remarks
+   * Returns `null` if the asset was not loaded or tracked by this manager.
+   *
+   * @param asset - Asset instance (e.g., texture, model group) to look up.
+   *
+   * @returns The asset ID string, or `null` if unknown.
    */ getAssetId(asset) {
         return this._allocated.get(asset) ?? null;
     }
-    /**
-   * Associate an asset ID to a loaded/allocated asset.
-   *
-   * @param asset - Asset instance (e.g., texture, model group) to set Id.
-   * @param id - Asset ID to associated to this asset.
-   *
+    /**
+   * Associate an asset ID to a loaded/allocated asset.
+   *
+   * @param asset - Asset instance (e.g., texture, model group) to set Id.
+   * @param id - Asset ID to associated to this asset.
+   *
    */ setAssetId(asset, id) {
         if (asset) {
             if (id) {
@@ -528,35 +537,66 @@ const defaultValues = {
             }
         }
     }
-    /**
-   * Fetch a binary asset by ID via the asset manager.
-   *
-   * @remarks
-   * - Associates the returned data with the given ID for future reverse lookup.
-   * - The ID is typically a VFS path or locator.
-   *
-   * @param id - Asset identifier or path.
-   *
-   * @returns A Promise that resolves to the binary content, or `null` if not found.
-   */ async fetchBinary(id) {
+    /**
+   * Fetch a binary asset by ID via the asset manager.
+   *
+   * @remarks
+   * - Associates the returned data with the given ID for future reverse lookup.
+   * - The ID is typically a VFS path or locator.
+   *
+   * @param path - VFS path of the binary asset.
+   *
+   * @returns A Promise that resolves to the binary content, or `null` if not found.
+   */ async fetchBinary(path) {
+        const id = this.VFS.normalizePath(path);
         const data = await this._assetManager.fetchBinaryData(id);
         if (data) {
             this._allocated.set(data, id);
         }
         return data;
     }
-    /**
-   * Serialize an object to a JSON structure using registered class metadata.
-   *
-   * @remarks
-   * - Throws if the object's class is not registered.
-   * - Populates `asyncTasks` with pending I/O tasks for embedded resources.
-   *
-   * @param obj - The object to serialize.
-   * @param json - Optional existing JSON object to fill.
-   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
-   *
-   * @returns The serialized JSON structure.
+    /**
+   * Fetch a text asset by ID via the asset manager.
+   *
+   * @param path - VFS path of TTF/OTF file.
+   * @returns A Promise that resolves to the font asset, or `null` if not found.
+   */ async fetchFontAsset(path, options) {
+        const id = this.VFS.normalizePath(path);
+        const fontAsset = await this._assetManager.fetchFontAsset(id, options);
+        if (fontAsset) {
+            this._allocated.set(fontAsset, id);
+        }
+        return fontAsset;
+    }
+    /**
+   * Get a cached font asset by ID if already loaded.
+   *
+   * @param path - VFS path of TTF/OTF file.
+   * @returns The cached FontAsset if it exists and is loaded, or null if not cached or still loading.
+   */ getFontAsset(path) {
+        return this._assetManager.getFontAsset(this.VFS.normalizePath(path));
+    }
+    /**
+   * Removes a cached font asset entry by asset instance or asset ID.
+   *
+   * @param asset - Loaded font asset instance or its asset ID/path.
+   * @returns `true` if a cache entry existed and was removed.
+   */ releaseFontAsset(asset) {
+        const path = typeof asset === 'string' ? asset : this.getAssetId(asset);
+        return path ? this._assetManager.releaseFontAsset(this.VFS.normalizePath(path)) : false;
+    }
+    /**
+   * Serialize an object to a JSON structure using registered class metadata.
+   *
+   * @remarks
+   * - Throws if the object's class is not registered.
+   * - Populates `asyncTasks` with pending I/O tasks for embedded resources.
+   *
+   * @param obj - The object to serialize.
+   * @param json - Optional existing JSON object to fill.
+   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
+   *
+   * @returns The serialized JSON structure.
    */ async serializeObject(obj, json, asyncTasks) {
         if (obj === null || obj === undefined) {
             return obj;
@@ -582,14 +622,14 @@ const defaultValues = {
         }
         return json;
     }
-    /**
-   * Serialize object properties into a JSON structure.
-   *
-   * @param obj - The target object to serialize.
-   * @param json - The JSON structure to populate.
-   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
-   * @param info - Optional serialization metadata for the object's class.
-   * @returns A Promise that resolves when serialization is complete.
+    /**
+   * Serialize object properties into a JSON structure.
+   *
+   * @param obj - The target object to serialize.
+   * @param json - The JSON structure to populate.
+   * @param asyncTasks - Optional list to collect async tasks for embedded asset export.
+   * @param info - Optional serialization metadata for the object's class.
+   * @returns A Promise that resolves when serialization is complete.
    */ async serializeObjectProps(obj, json, asyncTasks, info) {
         if (!info) {
             const cls = this.getClasses();
@@ -606,17 +646,17 @@ const defaultValues = {
         }
         return json;
     }
-    /**
-   * Deserialize a JSON structure into an object instance.
-   *
-   * @remarks
-   * - Uses the `ClassName` field to locate the registered class.
-   * - Supports custom `createFunc` and phased property loading.
-   *
-   * @param ctx - Context object passed to custom constructors/resolvers.
-   * @param json - The serialized JSON structure.
-   *
-   * @returns A Promise resolving to the reconstructed object instance, or `null` on failure.
+    /**
+   * Deserialize a JSON structure into an object instance.
+   *
+   * @remarks
+   * - Uses the `ClassName` field to locate the registered class.
+   * - Supports custom `createFunc` and phased property loading.
+   *
+   * @param ctx - Context object passed to custom constructors/resolvers.
+   * @param json - The serialized JSON structure.
+   *
+   * @returns A Promise resolving to the reconstructed object instance, or `null` on failure.
    */ async deserializeObject(ctx, json) {
         const cls = this.getClasses();
         const className = json['ClassName'];
@@ -649,12 +689,12 @@ const defaultValues = {
         }
         return obj;
     }
-    /**
-   * Deserialize object properties from JSON into an existing object instance.
-   *
-   * @param obj - The target object to populate.
-   * @param json - The JSON structure containing serialized properties.
-   * @param info - Optional serialization metadata for the object's class.
+    /**
+   * Deserialize object properties from JSON into an existing object instance.
+   *
+   * @param obj - The target object to populate.
+   * @param json - The JSON structure containing serialized properties.
+   * @param info - Optional serialization metadata for the object's class.
    */ async deserializeObjectProps(obj, json, info) {
         if (!info) {
             const cls = this.getClasses();
@@ -669,95 +709,99 @@ const defaultValues = {
             info = this.getClassByConstructor(info.parent);
         }
     }
-    /**
-   * Load a model by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Model identifier or path.
-   * @param scene - Scene into which the model is loaded.
-   * @param options - Optional model fetch options.
-   *
-   * @returns A Promise resolving to the loaded model object, or `null` if failed.
-   */ async fetchModel(id, scene, options) {
+    /**
+   * Load a model by ID and track the allocation for reverse lookup.
+   *
+   * @param path - VFS path of the model file.
+   * @param scene - Scene into which the model is loaded.
+   * @param options - Optional model fetch options.
+   *
+   * @returns A Promise resolving to the loaded model object, or `null` if failed.
+   */ async fetchModel(path, scene, options) {
+        const id = this.VFS.normalizePath(path);
         const model = await this._assetManager.fetchModel(scene, id, options);
         if (model) {
             this._allocated.set(model.group, id);
         }
         return model;
     }
-    /**
-   * 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) {
         return this._assetManager.loadTextureFromBuffer(arrayBuffer, mimeType, srgb, samplerOptions, texture);
     }
-    /**
-   * Load a texture by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Texture identifier or path.
-   * @param options - Optional texture fetch options.
-   *
-   * @returns A Promise resolving to the loaded texture, or `null` if failed.
-   */ async fetchTexture(id, options) {
+    /**
+   * Load a texture by ID and track the allocation for reverse lookup.
+   *
+   * @param path - VFS path of the texture file.
+   * @param options - Optional texture fetch options.
+   *
+   * @returns A Promise resolving to the loaded texture, or `null` if failed.
+   */ async fetchTexture(path, options) {
+        const id = this.VFS.normalizePath(path);
         const texture = await this._assetManager.fetchTexture(id, options);
         if (texture) {
             this._allocated.set(texture, id);
         }
         return texture;
     }
-    /**
-   * Load a material by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Material identifier or path.
-   *
-   * @returns A Promise resolving to the loaded material, or `null` if failed.
-   */ async fetchMaterial(id) {
+    /**
+   * Load a material by ID and track the allocation for reverse lookup.
+   *
+   * @param path - VFS path of the material file.
+   *
+   * @returns A Promise resolving to the loaded material, or `null` if failed.
+   */ async fetchMaterial(path) {
+        const id = this.VFS.normalizePath(path);
         const material = await this._assetManager.fetchMaterial(id);
         if (material) {
             this._allocated.set(material, id);
         }
         return material;
     }
-    /**
-   * Reload specific blue print materials
-   *
-   * @param filter - Determine whether a blue print material should reload.
-   *
+    /**
+   * Reload specific blue print materials
+   *
+   * @param filter - Determine whether a blue print material should reload.
+   *
    */ async reloadBluePrintMaterials(filter) {
         await this._assetManager.reloadBluePrintMaterials(filter);
     }
-    /**
-   * Mark specific blue print as changed
-   * @param path - BluePrint file path
+    /**
+   * Mark specific blue print as changed
+   * @param path - BluePrint file path
    */ invalidateBluePrint(path) {
         this._assetManager.invalidateBluePrint(path);
     }
-    /**
-   * Load a primitive by ID and track the allocation for reverse lookup.
-   *
-   * @param id - Primitive identifier or path.
-   *
-   * @returns A Promise resolving to the loaded primitive, or `null` if failed.
-   */ async fetchPrimitive(id) {
+    /**
+   * Load a primitive by ID and track the allocation for reverse lookup.
+   *
+   * @param path - VFS path of the primitive file.
+   *
+   * @returns A Promise resolving to the loaded primitive, or `null` if failed.
+   */ async fetchPrimitive(path) {
+        const id = this.VFS.normalizePath(path);
         const primitive = await this._assetManager.fetchPrimitive(id);
         if (primitive) {
             this._allocated.set(primitive, id);
         }
         return primitive;
     }
-    /**
-   * Load a prefab content.
-   * @param path - Path to the prefab JSON file in VFS.
-   * @returns A Promise resolving to the prefab json object, or `null` on failure.
+    /**
+   * Load a prefab content.
+   * @param path - Path to the prefab JSON file in VFS.
+   * @returns A Promise resolving to the prefab json object, or `null` on failure.
    */ async loadPrefabContent(path) {
         try {
             const content = await this._vfs.readFile(path, {
@@ -770,11 +814,11 @@ const defaultValues = {
             return null;
         }
     }
-    /**
-   * Instantiate a prefab from a JSON file via VFS.
-   * @param parent - Parent node to attach the instantiated prefab to.
-   * @param path - Path to the prefab JSON file in VFS.
-   * @returns A Promise resolving to the instantiated `SceneNode`, or `null` on failure.
+    /**
+   * Instantiate a prefab from a JSON file via VFS.
+   * @param parent - Parent node to attach the instantiated prefab to.
+   * @param path - Path to the prefab JSON file in VFS.
+   * @returns A Promise resolving to the instantiated `SceneNode`, or `null` on failure.
    */ async instantiatePrefab(parent, path) {
         try {
             const json = await this.loadPrefabContent(path);
@@ -793,16 +837,16 @@ const defaultValues = {
             return null;
         }
     }
-    /**
-   * Load a scene from a JSON file via VFS.
-   *
-   * @remarks
-   * - Deserializes the scene graph.
-   * - Attaches scripts referenced by nodes after load (asynchronous).
-   *
-   * @param filename - Path to the scene JSON file in VFS.
-   *
-   * @returns A Promise resolving to the loaded `Scene`.
+    /**
+   * Load a scene from a JSON file via VFS.
+   *
+   * @remarks
+   * - Deserializes the scene graph.
+   * - Attaches scripts referenced by nodes after load (asynchronous).
+   *
+   * @param filename - Path to the scene JSON file in VFS.
+   *
+   * @returns A Promise resolving to the loaded `Scene`.
    */ async loadScene(filename) {
         const content = await this._vfs.readFile(filename, {
             encoding: 'utf8'
@@ -810,15 +854,15 @@ const defaultValues = {
         const json = JSON.parse(content);
         return await this.deserializeObject(null, json);
     }
-    /**
-   * Save a scene to a JSON file via VFS.
-   *
-   * @remarks
-   * - Collects async export tasks for embedded resources and awaits them.
-   * - Writes a UTF-8 JSON representation to VFS.
-   *
-   * @param scene - Scene to serialize and save.
-   * @param filename - Destination path in VFS.
+    /**
+   * Save a scene to a JSON file via VFS.
+   *
+   * @remarks
+   * - Collects async export tasks for embedded resources and awaits them.
+   * - Writes a UTF-8 JSON representation to VFS.
+   *
+   * @param scene - Scene to serialize and save.
+   * @param filename - Destination path in VFS.
    */ async saveScene(scene, filename) {
         const asyncTasks = [];
         const content = await this.serializeObject(scene, null, asyncTasks);
@@ -950,11 +994,11 @@ const defaultValues = {
     async loadBluePrint(path) {
         return this._assetManager.loadBluePrint(path);
     }
-    /**
-   * Clear cached allocations and asset-manager caches.
-   *
-   * @remarks
-   * Useful when reloading content or changing VFS mounts.
+    /**
+   * Clear cached allocations and asset-manager caches.
+   *
+   * @remarks
+   * Useful when reloading content or changing VFS mounts.
    */ clearCache() {
         this._allocated = new WeakMap();
         this._assetManager.clearCache();
@@ -973,18 +1017,18 @@ const defaultValues = {
         }
         return null;
     }
-    /**
-   * Find the object targeted by an animation track starting from a node.
-   *
-   * @remarks
-   * - Parses a target path like `prop/subprop[0]/child` where indexed entries
-   *   require `object_array` type and non-indexed entries require `object` type.
-   * - Returns `null` if any segment cannot be resolved through registered metadata.
-   *
-   * @param node - Root node used as the starting point.
-   * @param track - Property track containing a target path.
-   *
-   * @returns The resolved target object, or `null` if not found.
+    /**
+   * Find the object targeted by an animation track starting from a node.
+   *
+   * @remarks
+   * - Parses a target path like `prop/subprop[0]/child` where indexed entries
+   *   require `object_array` type and non-indexed entries require `object` type.
+   * - Returns `null` if any segment cannot be resolved through registered metadata.
+   *
+   * @param node - Root node used as the starting point.
+   * @param track - Property track containing a target path.
+   *
+   * @returns The resolved target object, or `null` if not found.
    */ findAnimationTarget(node, track) {
         const target = track.target ?? '';
         const value = {