mbt-3d 0.4.3 → 0.4.4

package/dist/index.d.ts

@@ -33,7 +33,9 @@ declare interface AmbientLightConfig {
  *
  * The ref provides these methods:
  * - `playAnimation(name, options)` - Play an animation with optional loop/restore
+ * - `playAnimationLayers(layers)` - Play multiple animation layers in parallel
  * - `stopAnimation()` - Stop current animation
+ * - `stopAnimationLayers()` - Stop all active animation layers
  * - `getAnimationNames()` - Get list of available animations
  * - `getGroup()` - Get the THREE.Group for advanced manipulation
  * - `setMorphTarget(name, value)` - Set morph target value
@@ -45,6 +47,8 @@ declare interface AmbientLightConfig {
  * @param rotation - Model rotation in radians as [x, y, z]. Example: `[0, Math.PI, 0]`. Default: `[0, 0, 0]`
  * @param scale - Uniform scale (number) or per-axis scale [x, y, z]. Examples: `0.5` or `[1, 2, 1]`. Default: `1`
  * @param defaultAnimation - Name of animation to play on load. If not specified, plays first animation. Example: `"Idle"`
+ * @param animation - Controlled single animation name
+ * @param animationLayers - Controlled parallel animation layers (takes priority over `animation`)
  * @param morphTargets - Morph target values as key-value pairs where value is 0-1. Example: `{ muscular: 0.5, thin: 0.2 }`
  * @param meshVisibility - Mesh visibility as key-value pairs. Example: `{ "Hairgirl1": true, "Hairgirl2": false }`
  * @param materialColors - Material colors as key-value pairs. Example: `{ "Hair_girl_1": "#ff0000" }`
@@ -79,6 +83,40 @@ declare interface AmbientLightConfig {
  */
 export declare const AnimatedModel: ForwardRefExoticComponent<AnimatedModelProps & RefAttributes<AnimatedModelHandle>>;
 
+/**
+ * Single animation layer configuration for parallel playback.
+ */
+export declare interface AnimatedModelAnimationLayer {
+    /** Animation name (supports exact and partial matching) */
+    name: string;
+    /** Loop layer continuously. Default: true */
+    loop?: boolean;
+    /** Layer weight. Default: 1 */
+    weight?: number;
+    /** Playback speed multiplier. Default: 1 */
+    timeScale?: number;
+    /** Fade-in duration in seconds. Default: 0.2 */
+    fadeIn?: number;
+    /** Optional mask to apply this layer only to selected nodes */
+    mask?: AnimatedModelAnimationMask;
+}
+
+/**
+ * Animation layer input (short form string or full config).
+ */
+export declare type AnimatedModelAnimationLayerInput = string | AnimatedModelAnimationLayer;
+
+/**
+ * Node mask for animation layer tracks.
+ * Use node names from `onLoad` (`meshes` and `bones`) to limit where a layer applies.
+ */
+export declare interface AnimatedModelAnimationMask {
+    /** Only tracks targeting these nodes will be played */
+    includeNodes?: string[];
+    /** Tracks targeting these nodes will be removed from the layer */
+    excludeNodes?: string[];
+}
+
 /**
  * Imperative handle for AnimatedModel (accessed via ref)
  *
@@ -104,6 +142,13 @@ export declare interface AnimatedModelHandle {
     }) => void;
     /** Stop the currently playing animation */
     stopAnimation: () => void;
+    /**
+     * Play multiple animations in parallel layers
+     * @param layers - List of animation layer configs (or plain names)
+     */
+    playAnimationLayers: (layers: AnimatedModelAnimationLayerInput[]) => void;
+    /** Stop all currently active animation layers */
+    stopAnimationLayers: () => void;
     /** Get array of all available animation names */
     getAnimationNames: () => string[];
     /** Get the THREE.Group object for advanced manipulation */
@@ -188,6 +233,18 @@ export declare interface AnimatedModelProps extends Omit<ModelProps, 'onLoad'> {
     defaultAnimation?: string;
     /** Controlled animation name. When changed, AnimatedModel switches to this animation */
     animation?: string;
+    /**
+     * Controlled parallel animation layers.
+     * If provided, takes priority over `animation`.
+     *
+     * @example
+     * animationLayers={[
+     *   'Idleger1',
+     *   { name: 'GirlFaceidle.007', mask: { includeNodes: ['Eyewitegirl', 'Girlbody_1'] } },
+     *   { name: 'Lashesgirl6idle.013', mask: { includeNodes: ['Lashesgirl'] } },
+     * ]}
+     */
+    animationLayers?: AnimatedModelAnimationLayerInput[];
     /** Morph target values as key-value pairs { targetName: value } where value is 0-1 */
     morphTargets?: Record<string, number>;
     /** Mesh visibility as key-value pairs { meshName: visible }. Example: { "Hairgirl1": true, "Hairgirl2": false } */
@@ -827,6 +884,8 @@ export declare function useAnimationController(animations: THREE.AnimationClip[]
         restoreDefault?: boolean;
     }) => void;
     stopAnimation: () => void;
+    playAnimationLayers: (layers: AnimatedModelAnimationLayerInput[]) => void;
+    stopAnimationLayers: () => void;
     getAnimationNames: () => string[];
     actions: {
         [x: string]: THREE.AnimationAction | null;