@zephyr3d/scene 0.9.3 → 0.9.5

package/dist/scene/scene_node.js

@@ -3,33 +3,40 @@ import { AnimationSet } from '../animation/animationset.js';
 import { getEngine } from '../app/api.js';
 import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttachments } from './script_attachment.js';
 
-/**
- * The base class of all scene graph objects.
- *
- * @remarks
- * Responsibilities:
- * - Defines hierarchical transform (position, rotation, scale) with lazily computed matrices.
- * - Integrates with the scene graph (parent/children, attachment notifications).
- * - Provides traversal utilities (`iterate`, `iterateBottomToTop`, `traverse`).
- * - Manages visibility state and CPU/GPU picking flags.
- * - Computes and caches local/world bounding volumes, notifies scene for spatial updates.
- * - Supports cloning and shared model instancing.
- * - Emits events on visibility, transform, bounding volume, attachment, and disposal.
- *
- * Performance:
- * - `localMatrix`, `worldMatrix`, and `invWorldMatrix` are cached until invalidated.
- * - Transform mutations and `invalidateBoundingVolume` update caches and spatial structures.
- *
- * Events:
- * - `nodeattached`, `noderemoved`, `visiblechanged`, `transformchanged`, `bvchanged`, `dispose`.
- *
- * @public
+const sceneMeshAssetBindings = new WeakMap();
+/** @internal */ function setSceneMeshAssetBinding(mesh, binding) {
+    sceneMeshAssetBindings.set(mesh, binding);
+}
+/** @internal */ function getSceneMeshAssetBinding(mesh) {
+    return sceneMeshAssetBindings.get(mesh) ?? null;
+}
+/**
+ * The base class of all scene graph objects.
+ *
+ * @remarks
+ * Responsibilities:
+ * - Defines hierarchical transform (position, rotation, scale) with lazily computed matrices.
+ * - Integrates with the scene graph (parent/children, attachment notifications).
+ * - Provides traversal utilities (`iterate`, `iterateBottomToTop`, `traverse`).
+ * - Manages visibility state and CPU/GPU picking flags.
+ * - Computes and caches local/world bounding volumes, notifies scene for spatial updates.
+ * - Supports cloning and shared model instancing.
+ * - Emits events on visibility, transform, bounding volume, attachment, and disposal.
+ *
+ * Performance:
+ * - `localMatrix`, `worldMatrix`, and `invWorldMatrix` are cached until invalidated.
+ * - Transform mutations and `invalidateBoundingVolume` update caches and spatial structures.
+ *
+ * Events:
+ * - `nodeattached`, `noderemoved`, `visiblechanged`, `transformchanged`, `bvchanged`, `dispose`.
+ *
+ * @public
  */ class SceneNode extends makeObservable(Disposable)() {
     static _runTimeId = 1;
-    /*
-  static readonly PICK_INHERITED = -1;
-  static readonly PICK_DISABLED = 0;
-  static readonly PICK_ENABLED = 1;
+    /*
+  static readonly PICK_INHERITED = -1;
+  static readonly PICK_DISABLED = 0;
+  static readonly PICK_ENABLED = 1;
   */ /** Bounding-box draw mode inherited from nearest graph ancestor. */ static BBOXDRAW_INHERITED = -1;
     /** Disable bounding-box visualization. */ static BBOXDRAW_DISABLED = 0;
     /** Draw local-space bounding box. */ static BBOXDRAW_LOCAL = 1;
@@ -39,6 +46,7 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** @internal Prefab id */ _prefabId;
     /** @internal Animation set reference. */ _animationSet;
     /** @internal Optional shared model reference for instancing. */ _sharedModel;
+    /** @internal Model-level morph target groups bound to runtime meshes. */ _morphTargetGroups;
     /** @internal */ _jointTypeT;
     /** @internal */ _jointTypeS;
     /** @internal */ _jointTypeR;
@@ -70,14 +78,14 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** @internal Arbitrary metadata payload for this node. */ _metaData;
     /** @internal If greater than zero, suppress transform-change callbacks (during bulk updates). */ _disableCallback;
     /** @internal User-attached script entries (engine-defined). */ _scripts;
-    /**
-   * Construct a scene node.
-   *
-   * @remarks
-   * If a `scene` is provided and this is not the root node, the node is reparented
-   * under the scene's root immediately.
-   *
-   * @param scene - Scene that will own this node.
+    /**
+   * Construct a scene node.
+   *
+   * @remarks
+   * If a `scene` is provided and this is not the root node, the node is reparented
+   * under the scene's root immediately.
+   *
+   * @param scene - Scene that will own this node.
    */ constructor(scene){
         super();
         this._runtimeId = SceneNode._runTimeId++;
@@ -87,6 +95,7 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         this._name = '';
         this._animationSet = new DRef();
         this._sharedModel = new DRef();
+        this._morphTargetGroups = [];
         this._jointTypeT = 'none';
         this._jointTypeS = 'none';
         this._jointTypeR = 'none';
@@ -118,11 +127,11 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         this._parent = null;
         this.reparent(scene?.rootNode ?? null);
     }
-    /**
-   * Whether the node should be inserted into the scene's spatial structure.
-   *
-   * @remarks
-   * Toggling this hints the scene to (re)place the node in octree/acceleration structures.
+    /**
+   * Whether the node should be inserted into the scene's spatial structure.
+   *
+   * @remarks
+   * Toggling this hints the scene to (re)place the node in octree/acceleration structures.
    */ get placeToOctree() {
         return this._placeToOctree;
     }
@@ -134,88 +143,88 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             }
         }
     }
-    /**
-   * Node's runtime unique identifier
+    /**
+   * Node's runtime unique identifier
    */ get runtimeId() {
         return this._runtimeId;
     }
-    /**
-   * Node's persistent identifier.
-   *
-   * @remarks
-   * Changing this affects serialization and registry lookup; ensure uniqueness.
+    /**
+   * Node's persistent identifier.
+   *
+   * @remarks
+   * Changing this affects serialization and registry lookup; ensure uniqueness.
    */ get persistentId() {
         return this._id;
     }
     set persistentId(id) {
         this._id = id;
     }
-    /**
-   * If not empty, this node was loaded from a prefab
-   *
-   * @remarks
-   * Internal used for serialization
+    /**
+   * If not empty, this node was loaded from a prefab
+   *
+   * @remarks
+   * Internal used for serialization
    */ get prefabId() {
         return this._prefabId;
     }
     set prefabId(id) {
         this._prefabId = id;
     }
-    /**
-   * Get prefab node this node belongs to, or null if this node does not belongs to any prefab
-   * @returns prefab node this node belongs to
+    /**
+   * Get prefab node this node belongs to, or null if this node does not belongs to any prefab
+   * @returns prefab node this node belongs to
    */ getPrefabNode() {
         return this._prefabId ? this : this.parent?.getPrefabNode() ?? null;
     }
-    /**
-   * Translation type if this is a joint node of any skeleton
-   *
-   * @remarks
-   * Internal used for serialization
+    /**
+   * Translation type if this is a joint node of any skeleton
+   *
+   * @remarks
+   * Internal used for serialization
    */ get jointTypeT() {
         return this._jointTypeT;
     }
     set jointTypeT(val) {
         this._jointTypeT = val;
     }
-    /**
-   * Scale type if this is a joint node of any skeleton
-   *
-   * @remarks
-   * Internal used for serialization
+    /**
+   * Scale type if this is a joint node of any skeleton
+   *
+   * @remarks
+   * Internal used for serialization
    */ get jointTypeS() {
         return this._jointTypeS;
     }
     set jointTypeS(val) {
         this._jointTypeS = val;
     }
-    /**
-   * Rotation type if this is a joint node of any skeleton
-   *
-   * @remarks
-   * Internal used for serialization
+    /**
+   * Rotation type if this is a joint node of any skeleton
+   *
+   * @remarks
+   * Internal used for serialization
    */ get jointTypeR() {
         return this._jointTypeR;
     }
     set jointTypeR(val) {
         this._jointTypeR = val;
     }
-    /**
-   * Arbitrary metadata associated with this node.
-   *
-   * @remarks
-   * Stored and transported with the node; format is application-defined.
+    /**
+   * Arbitrary metadata associated with this node.
+   *
+   * @remarks
+   * Stored and transported with the node; format is application-defined.
    */ get metaData() {
         return this._metaData;
     }
     set metaData(val) {
         this._metaData = val;
     }
-    /**
-   * Attached script filename or identifier (engine-specific).
-   *
-   * @remarks
-   * Integrates with the engine’s scripting system if available.
+    /**
+   * Attached script filename or identifier (engine-specific).
+   *
+   * @remarks
+   * Integrates with the engine’s scripting system if available.
    */ get script() {
         return this._scripts[0]?.script ?? '';
     }
@@ -229,8 +238,8 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             this._scripts.unshift(new ScriptAttachment(script));
         }
     }
-    /**
-   * Script component configuration payload used by editor/runtime script components.
+    /**
+   * Script component configuration payload used by editor/runtime script components.
    */ get scriptConfig() {
         return this._scripts[0]?.config ?? null;
     }
@@ -245,16 +254,16 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             this._scripts.splice(0, 1);
         }
     }
-    /**
-   * All script attachments on this node.
+    /**
+   * All script attachments on this node.
    */ get scripts() {
         return this._scripts;
     }
     set scripts(value) {
         this._scripts = normalizeScriptAttachments(value);
     }
-    /**
-   * Script configs for all script attachments.
+    /**
+   * Script configs for all script attachments.
    */ get scriptConfigs() {
         return this._scripts.map((item)=>item.config);
     }
@@ -270,8 +279,8 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         this._scripts = this._scripts.filter((item)=>item.script || item.config != null);
     }
-    /**
-   * Display name of the node (for UI/debugging).
+    /**
+   * Display name of the node (for UI/debugging).
    */ get name() {
         return this._name;
     }
@@ -281,8 +290,8 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** The owning scene. */ get scene() {
         return this._scene;
     }
-    /**
-   * Whether this node is currently attached under the scene's root.
+    /**
+   * Whether this node is currently attached under the scene's root.
    */ get attached() {
         if (!this._scene) {
             return false;
@@ -293,20 +302,20 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         return node === this._scene.rootNode;
     }
-    /**
-   * If true, the node is logically sealed; some operations (like cloning as child)
-   * may be restricted by engine policies.
+    /**
+   * If true, the node is logically sealed; some operations (like cloning as child)
+   * may be restricted by engine policies.
    */ get sealed() {
         return this._sealed;
     }
     set sealed(val) {
         this._sealed = val;
     }
-    /**
-   * Lazily created animation set for this node.
-   *
-   * @remarks
-   * Accessing this schedules the node for update in the scene.
+    /**
+   * Lazily created animation set for this node.
+   *
+   * @remarks
+   * Accessing this schedules the node for update in the scene.
    */ get animationSet() {
         if (!this._animationSet.get()) {
             this._animationSet.set(new AnimationSet(this));
@@ -314,24 +323,30 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         return this._animationSet.get();
     }
-    /**
-   * Shared model reference for instancing/streaming systems.
+    /**
+   * Shared model reference for instancing/streaming systems.
    */ get sharedModel() {
         return this._sharedModel.get();
     }
     set sharedModel(model) {
         this._sharedModel.set(model);
     }
-    /**
-   * Clone this node.
-   *
-   * @remarks
-   * If a shared model exists, it may create an instanced node. The clone is
-   * attached under the same parent; children are cloned based on `method` and `recursive`.
-   *
-   * @param method - Clone method ('deep' or 'instance').
-   * @param recursive - Whether children are cloned recursively.
-   * @returns New node instance
+    /** Runtime morph target groups bound to this model instance. */ get morphTargetGroups() {
+        return this._morphTargetGroups;
+    }
+    set morphTargetGroups(groups) {
+        this._morphTargetGroups = (groups ?? []).filter((group)=>!!group?.name && group.bindings.length > 0);
+    }
+    /**
+   * Clone this node.
+   *
+   * @remarks
+   * If a shared model exists, it may create an instanced node. The clone is
+   * attached under the same parent; children are cloned based on `method` and `recursive`.
+   *
+   * @param method - Clone method ('deep' or 'instance').
+   * @param recursive - Whether children are cloned recursively.
+   * @returns New node instance
    */ async clone() {
         this.iterate((node)=>{
             if (node.isClipmapTerrain()) {
@@ -357,53 +372,53 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         return other;
     }
-    /**
-   * Whether the given node is a direct child of this node.
-   * @param child - The node to be checked
-   * @returns true if the given node is a direct child of this node, false otherwise
+    /**
+   * Whether the given node is a direct child of this node.
+   * @param child - The node to be checked
+   * @returns true if the given node is a direct child of this node, false otherwise
    */ hasChild(child) {
         return child && child.parent === this;
     }
-    /**
-   * Remove all children from this node.
+    /**
+   * Remove all children from this node.
    */ removeChildren() {
         while(this._children.length){
             this._children[0].get().remove();
         }
     }
-    /**
-   * Whether this node is an ancestor (direct or indirect) of the given node.
+    /**
+   * Whether this node is an ancestor (direct or indirect) of the given node.
    */ isParentOf(child) {
         while(child && child !== this){
             child = child.parent;
         }
         return child === this;
     }
-    /**
-   * Detach this node from its parent.
-   *
-   * @returns this
+    /**
+   * Detach this node from its parent.
+   *
+   * @returns this
    */ remove() {
         this.parent = null;
         return this;
     }
-    /**
-   * Depth-first traversal of this node's subtree (pre-order).
-   *
-   * @param v - Visitor invoked on each node.
+    /**
+   * Depth-first traversal of this node's subtree (pre-order).
+   *
+   * @param v - Visitor invoked on each node.
    */ traverse(v) {
         v.visit(this);
         for (const child of this._children){
             child.get().traverse(v);
         }
     }
-    /**
-   * Iterate self and descendants in pre-order.
-   *
-   * Warning: Do not remove children during this iteration. To allow removal, use `iterateBottomToTop`.
-   *
-   * @param callback - Called for each node; if returns true, iteration stops.
-   * @returns If returns true, the iteration will immediately stop.
+    /**
+   * Iterate self and descendants in pre-order.
+   *
+   * Warning: Do not remove children during this iteration. To allow removal, use `iterateBottomToTop`.
+   *
+   * @param callback - Called for each node; if returns true, iteration stops.
+   * @returns If returns true, the iteration will immediately stop.
    */ iterate(callback) {
         if (callback(this)) {
             return true;
@@ -415,13 +430,13 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         return false;
     }
-    /**
-   * Iterate self and descendants in reverse post-order (bottom-to-top).
-   *
-   * Child nodes can be safely removed during this iteration.
-   *
-   * @param callback - Called for each node; if returns true, iteration stops.
-   * @returns If returns true, the iteration will immediately stop.
+    /**
+   * Iterate self and descendants in reverse post-order (bottom-to-top).
+   *
+   * Child nodes can be safely removed during this iteration.
+   *
+   * @param callback - Called for each node; if returns true, iteration stops.
+   * @returns If returns true, the iteration will immediately stop.
    */ iterateBottomToTop(callback) {
         for(let i = this._children.length - 1; i >= 0; i--){
             const child = this._children[i];
@@ -446,6 +461,12 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** Type guard: true if this node is a sprite */ isSprite() {
         return false;
     }
+    /** Type guard: true if this node is a MSDF text sprite */ isMSDFTextSprite() {
+        return false;
+    }
+    /** Type guard: true if this node is a MSDF text sprite */ isMSDFText() {
+        return false;
+    }
     /** Type guard: true if this node is a water node. */ isWater() {
         return false;
     }
@@ -464,15 +485,15 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** true if this is a punctual light node, false otherwise */ isPunctualLight() {
         return false;
     }
-    /**
-   * Computes the bounding volume of the node
-   * @returns The output bounding volume
+    /**
+   * Computes the bounding volume of the node
+   * @returns The output bounding volume
    */ computeBoundingVolume() {
         return null;
     }
-    /**
-   * Gets the bounding volume of the node
-   * @returns The bounding volume of the node
+    /**
+   * Gets the bounding volume of the node
+   * @returns The bounding volume of the node
    */ getBoundingVolume() {
         if (this._bvDirty) {
             this._bv = this.computeBoundingVolume();
@@ -480,9 +501,9 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         }
         return this._bv;
     }
-    /**
-   * Sets the bounding volume of the node
-   * @param bv - The bounding volume to set
+    /**
+   * Sets the bounding volume of the node
+   * @param bv - The bounding volume to set
    */ setBoundingVolume(bv) {
         if (bv !== this._bv) {
             this._bv = bv;
@@ -490,23 +511,23 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             this.invalidateWorldBoundingVolume(false);
         }
     }
-    /**
-   * Gets the world space bounding volume of the node
-   * @returns The world space bounding volume of the node
+    /**
+   * Gets the world space bounding volume of the node
+   * @returns The world space bounding volume of the node
    */ getWorldBoundingVolume() {
         if (!this._bvWorld) {
             this._bvWorld = this.computeWorldBoundingVolume(this.getBoundingVolume());
         }
         return this._bvWorld;
     }
-    /**
-   * Computes the world space bounding volume of the node
-   * @returns The output bounding volume
+    /**
+   * Computes the world space bounding volume of the node
+   * @returns The output bounding volume
    */ computeWorldBoundingVolume(localBV) {
         return localBV?.transform(this.worldMatrix) ?? null;
     }
-    /**
-   * Force the bounding volume to be recalculated
+    /**
+   * Force the bounding volume to be recalculated
    */ invalidateBoundingVolume() {
         this._bvDirty = true;
         this.invalidateWorldBoundingVolume(false);
@@ -571,12 +592,12 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     set gpuPickable(val) {
         this._gpuPickable = !!val;
     }
-    /**
-   * Finds a scene node by its persistent ID.
-   *
-   * @typeParam T - Expected node type.
-   * @param id - Persistent identifier to match against `SceneNode.persistentId`.
-   * @returns The first matching node, or `null` if not found.
+    /**
+   * Finds a scene node by its persistent ID.
+   *
+   * @typeParam T - Expected node type.
+   * @param id - Persistent identifier to match against `SceneNode.persistentId`.
+   * @returns The first matching node, or `null` if not found.
    */ findNodeById(id) {
         let node = null;
         this.iterate((child)=>{
@@ -587,11 +608,18 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         });
         return node;
     }
-    /**
-   * Finds a skeleton object by its persistent ID.
-   * @param id - Persistent identifier to match against `Skeleton.persistentId`.
-   * @returns The first matchign node, or `null` if not found.
+    /**
+   * Finds a skeleton object by its persistent ID.
+   * @param id - Persistent identifier to match against `Skeleton.persistentId`.
+   * @returns The first matchign node, or `null` if not found.
    */ findSkeletonById(id) {
+        return this.findSkinBindingById(id);
+    }
+    /**
+   * Finds a skin binding by its persistent ID.
+   * @param id - Persistent identifier to match against `SkinBinding.persistentId`.
+   * @returns The first matching binding, or `null` if not found.
+   */ findSkinBindingById(id) {
         const prefabNode = this.getPrefabNode() ?? this;
         let sk = null;
         prefabNode.iterate((node)=>{
@@ -601,18 +629,31 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         // avoid ts2339 compilation error (maybe a typescript bug?)
         return sk?.get() ?? null;
     }
-    /**
-   * Finds a scene node by name.
-   *
-   * If multiple nodes share the same name, returns the first match encountered
-   * during traversal.
-   *
-   * @typeParam T - Expected node type.
-   * @param name - Node name to match.
-   * @returns The first matching node, or `null` if not found.
-   *
-   * @remarks
-   * Names are not guaranteed unique. Prefer IDs for stable references.
+    /**
+   * Finds a shared skeleton rig by its persistent ID.
+   * @param id - Persistent identifier to match against `SkeletonRig.persistentId`.
+   * @returns The first matching rig, or `null` if not found.
+   */ findSkeletonRigById(id) {
+        const prefabNode = this.getPrefabNode() ?? this;
+        let rig = null;
+        prefabNode.iterate((node)=>{
+            rig = node.animationSet.rigs.find((s)=>s.get().persistentId === id) ?? null;
+            return !!rig;
+        });
+        return rig?.get() ?? null;
+    }
+    /**
+   * Finds a scene node by name.
+   *
+   * If multiple nodes share the same name, returns the first match encountered
+   * during traversal.
+   *
+   * @typeParam T - Expected node type.
+   * @param name - Node name to match.
+   * @returns The first matching node, or `null` if not found.
+   *
+   * @remarks
+   * Names are not guaranteed unique. Prefer IDs for stable references.
    */ findNodeByName(name) {
         let node = null;
         this.iterate((child)=>{
@@ -639,9 +680,175 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     set boundingBoxDrawMode(mode) {
         this._boxDrawMode = mode;
     }
-    invalidateTransform(invalidateLocal = true) {
+    /** @internal */ matchesMorphTargetBinding(mesh, binding) {
+        const assetBinding = getSceneMeshAssetBinding(mesh);
+        if (binding.node && assetBinding?.node !== binding.node) {
+            return false;
+        }
+        if (binding.mesh && binding.mesh !== mesh && assetBinding?.mesh !== binding.mesh) {
+            return false;
+        }
+        return true;
+    }
+    /** @internal */ applyMorphTargetBindingWeight(mesh, binding, weight) {
+        if (!this.matchesMorphTargetBinding(mesh, binding)) {
+            return;
+        }
+        const targetWeight = weight * binding.weight;
+        const targetIndex = binding.targetIndex;
+        if (typeof targetIndex === 'number' && targetIndex >= 0 && targetIndex < mesh.getNumMorphTargets()) {
+            mesh.setMorphWeightByIndex(targetIndex, targetWeight);
+            return;
+        }
+        if (binding.targetName) {
+            mesh.setMorphWeight(binding.targetName, targetWeight);
+        }
+    }
+    /** @internal */ getMorphTargetGroupRoot() {
+        let node = this;
+        while(node){
+            if (node._morphTargetGroups.length > 0 || node.sharedModel) {
+                return node;
+            }
+            node = node.parent;
+        }
+        return this.getPrefabNode() ?? this;
+    }
+    /** @internal */ applyMorphTargetGroupWeight(group, weight) {
+        const root = this.getMorphTargetGroupRoot();
+        root.iterate((node)=>{
+            if (node.isMesh()) {
+                for (const binding of group.bindings){
+                    this.applyMorphTargetBindingWeight(node, binding, weight);
+                }
+            }
+        });
+    }
+    /** @internal */ getRuntimeMorphTargetGroup(name) {
+        const root = this.getMorphTargetGroupRoot();
+        return root._morphTargetGroups.find((group)=>group.name === name) ?? null;
+    }
+    /** Returns serialized morph target groups for this node. */ getSerializedMorphTargetGroups() {
+        return this._morphTargetGroups.map((group)=>({
+                name: group.name,
+                isBinary: group.isBinary,
+                weight: group.weight ?? 0,
+                bindings: group.bindings.filter((binding)=>!!binding.mesh).map((binding)=>({
+                        meshId: binding.mesh.persistentId,
+                        targetIndex: binding.targetIndex,
+                        targetName: binding.targetName,
+                        weight: binding.weight
+                    }))
+            })).filter((group)=>group.bindings.length > 0);
+    }
+    /** Restores serialized morph target groups for this node. */ setSerializedMorphTargetGroups(groups) {
+        const runtimeGroups = [];
+        for (const group of groups ?? []){
+            if (!group?.name || !Array.isArray(group.bindings)) {
+                continue;
+            }
+            const bindings = [];
+            for (const binding of group.bindings){
+                const mesh = binding?.meshId ? this.findNodeById(binding.meshId) : null;
+                if (mesh?.isMesh()) {
+                    bindings.push({
+                        mesh,
+                        targetIndex: binding.targetIndex,
+                        targetName: binding.targetName,
+                        weight: typeof binding.weight === 'number' ? binding.weight : 1
+                    });
+                }
+            }
+            if (bindings.length > 0) {
+                runtimeGroups.push({
+                    name: group.name,
+                    bindings,
+                    isBinary: group.isBinary,
+                    weight: typeof group.weight === 'number' ? group.weight : 0
+                });
+            }
+        }
+        this._morphTargetGroups = runtimeGroups;
+        for (const group of this._morphTargetGroups){
+            this.applyMorphTargetGroupWeight(group, group.weight ?? 0);
+        }
+    }
+    /**
+   * Force transform update and notify descendants.
+   * @param invalidateLocal - If true, also invalidate local matrix; otherwise only invalidate world matrix.
+   */ invalidateTransform(invalidateLocal = true) {
         this._onTransformChanged(invalidateLocal);
     }
+    /**
+   * Set morph target weight by name for all meshes in the subtree.
+   * @param name - Morph target name
+   * @param weight - Morph target weight
+   */ setMorphTargetWeight(name, weight) {
+        const root = this.getPrefabNode() ?? this;
+        root.iterate((node)=>{
+            if (node.isMesh()) {
+                const index = node.getMorphTargetIndexByName(name);
+                if (index >= 0) {
+                    node.setMorphWeightByIndex(index, weight);
+                }
+            }
+        });
+    }
+    /**
+   * Set morph target group weight for the model instance.
+   * @param name - Morph target group name
+   * @param weight - Group weight
+   */ setMorphTargetGroupWeight(name, weight) {
+        const runtimeGroup = this.getRuntimeMorphTargetGroup(name);
+        if (runtimeGroup) {
+            const groupWeight = runtimeGroup.isBinary ? weight > 0.5 ? 1 : 0 : weight;
+            runtimeGroup.weight = groupWeight;
+            this.applyMorphTargetGroupWeight(runtimeGroup, groupWeight);
+            return;
+        }
+        const root = this.getMorphTargetGroupRoot();
+        const group = root.sharedModel?.getMorphTargetGroup(name);
+        if (!group) {
+            this.setMorphTargetWeight(name, weight);
+            return;
+        }
+        const groupWeight = group.isBinary ? weight > 0.5 ? 1 : 0 : weight;
+        this.applyMorphTargetGroupWeight(group, groupWeight);
+    }
+    /**
+   * Get morph target group weight.
+   * @param name - Morph target group name
+   * @returns The group weight, or 0 if no group was found
+   */ getMorphTargetGroupWeight(name) {
+        const runtimeGroup = this.getRuntimeMorphTargetGroup(name);
+        return runtimeGroup?.weight ?? 0;
+    }
+    /**
+   * Collect all morph target names from meshes in the subtree.
+   * @returns Array of unique morph target names
+   */ collectMorphTargetNames() {
+        const root = this.getPrefabNode() ?? this;
+        const names = new Set();
+        root.iterate((node)=>{
+            if (node.isMesh()) {
+                for(let i = 0; i < node.getNumMorphTargets(); i++){
+                    names.add(node.getMorphTargetName(i));
+                }
+            }
+        });
+        return Array.from(names);
+    }
+    /**
+   * Collect all model-level morph target group names.
+   * @returns Array of morph target group names
+   */ collectMorphTargetGroupNames() {
+        const root = this.getMorphTargetGroupRoot();
+        if (root._morphTargetGroups.length > 0) {
+            return root._morphTargetGroups.map((group)=>group.name);
+        }
+        const groups = root.sharedModel?.morphTargetGroups;
+        return groups ? groups.map((group)=>group.name) : [];
+    }
     /** Get called when the node was just created by cloning from other node */ onPostClone() {}
     /** Disposes the node */ onDispose() {
         super.onDispose();
@@ -704,11 +911,11 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             }
         }
     }
-    /**
-   * Get called when this node is attached to scene
+    /**
+   * Get called when this node is attached to scene
    */ _onAttached() {}
-    /**
-   * Get called when this node is detached from scene
+    /**
+   * Get called when this node is detached from scene
    */ _onDetached() {}
     /** @internal */ _attached() {
         this.iterate((child)=>{
@@ -741,24 +948,24 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     /** Children of this xform */ get children() {
         return this._children.map((child)=>child.get());
     }
-    /**
-   * Position of the xform relative to it's parent
+    /**
+   * Position of the xform relative to it's parent
    */ get position() {
         return this._position;
     }
     set position(val) {
         this._position.setXYZ(val[0], val[1], val[2]);
     }
-    /**
-   * Scaling of the xform
+    /**
+   * Scaling of the xform
    */ get scale() {
         return this._scaling;
     }
     set scale(val) {
         this._scaling.setXYZ(val[0], val[1], val[2]);
     }
-    /**
-   * Rotation of the xform
+    /**
+   * Rotation of the xform
    */ get rotation() {
         return this._rotation;
     }
@@ -793,32 +1000,32 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     thisToOther(other, v, result) {
         return other.worldToThis(this.thisToWorld(v, result), result);
     }
-    /**
-   * Gets the position of the xform in world space
-   * @returns position of the xform in world space
+    /**
+   * Gets the position of the xform in world space
+   * @returns position of the xform in world space
    */ getWorldPosition(outPos) {
         return outPos?.setXYZ(this.worldMatrix.m03, this.worldMatrix.m13, this.worldMatrix.m23) ?? new Vector3(this.worldMatrix.m03, this.worldMatrix.m13, this.worldMatrix.m23);
     }
-    /**
-   * Moves the xform by an offset vector
-   * @param delta - The offset vector
-   * @returns self
+    /**
+   * Moves the xform by an offset vector
+   * @param delta - The offset vector
+   * @returns self
    */ moveBy(delta) {
         this._position.addBy(delta);
         return this;
     }
-    /**
-   * Scales the xform by a given scale factor
-   * @param factor - The scale factor
-   * @returns self
+    /**
+   * Scales the xform by a given scale factor
+   * @param factor - The scale factor
+   * @returns self
    */ scaleBy(factor) {
         this._scaling.mulBy(factor);
         return this;
     }
-    /**
-   * Sets the local transform matrix of the xform
-   * @param matrix - The transform matrix to set
-   * @returns self
+    /**
+   * Sets the local transform matrix of the xform
+   * @param matrix - The transform matrix to set
+   * @returns self
    */ setLocalTransform(matrix) {
         this._disableCallback++;
         matrix.decompose(this._scaling, this._rotation, this._position);
@@ -848,15 +1055,15 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
         this.syncTransform();
         return this._invWorldMatrix;
     }
-    /**
-   * Calculate local transform matrix
-   * @param outMatrix - Matrix object that holds the result of calculation
+    /**
+   * Calculate local transform matrix
+   * @param outMatrix - Matrix object that holds the result of calculation
    */ calculateLocalTransform(outMatrix) {
         outMatrix.compose(this._scaling, this._rotation, this._position);
     }
-    /**
-   * Calculate world transform matrix
-   * @param outMatrix - Matrix object that holds the result of calculation
+    /**
+   * Calculate world transform matrix
+   * @param outMatrix - Matrix object that holds the result of calculation
    */ calculateWorldTransform(outMatrix) {
         if (this._parent) {
             Matrix4x4.multiplyAffine(this._parent.worldMatrix, this.localMatrix, outMatrix);
@@ -864,21 +1071,21 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             outMatrix.set(this.localMatrix);
         }
     }
-    /**
-   * Sets the local tranformation matrix by a look-at matrix
-   * @param eye - The eye position used to make the look-at matrix
-   * @param target - The target position used to make the look-at matrix
-   * @param up - The up vector used to make the look-at matrix
-   * @returns self
+    /**
+   * Sets the local tranformation matrix by a look-at matrix
+   * @param eye - The eye position used to make the look-at matrix
+   * @param target - The target position used to make the look-at matrix
+   * @param up - The up vector used to make the look-at matrix
+   * @returns self
    */ lookAt(eye, target, up) {
         this.setLocalTransform(Matrix4x4.lookAt(eye, target, up));
         return this;
     }
-    /**
-   * Update node state once per-frame
-   * @param frameId - Current frame id
-   * @param elapsedInSeconds - Elapsed time from game start in seconds
-   * @param deltaInSeconds - Elapsed time since previous frame in seconds
+    /**
+   * Update node state once per-frame
+   * @param frameId - Current frame id
+   * @param elapsedInSeconds - Elapsed time from game start in seconds
+   * @param deltaInSeconds - Elapsed time since previous frame in seconds
    */ update(frameId, elapsedInSeconds, deltaInSeconds) {
         if (!this.attached) {
             return;
@@ -893,16 +1100,16 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
             }
         }
     }
-    /**
-   * Update node state once per-camera
-   * @param _camera - Updates according to which camera
-   * @param _elapsedInSeconds - Elapsed time from game start in seconds
-   * @param _deltaInSeconds - Elapsed time since previous frame in seconds
+    /**
+   * Update node state once per-camera
+   * @param _camera - Updates according to which camera
+   * @param _elapsedInSeconds - Elapsed time from game start in seconds
+   * @param _deltaInSeconds - Elapsed time since previous frame in seconds
    */ updatePerCamera(_camera, _elapsedInSeconds, _deltaInSeconds) {}
-    /**
-   * Removes this node from it's parent and add this node to another parent node if required
-   * @param p - The new parent node that this node should be added to or null
-   * @returns self
+    /**
+   * Removes this node from it's parent and add this node to another parent node if required
+   * @param p - The new parent node that this node should be added to or null
+   * @returns self
    */ reparent(p) {
         this.parent = p ?? null;
         return this;
@@ -924,5 +1131,5 @@ import { ScriptAttachment, normalizeScriptAttachmentConfig, normalizeScriptAttac
     }
 }
 
-export { SceneNode };
+export { SceneNode, setSceneMeshAssetBinding };
 //# sourceMappingURL=scene_node.js.map