illutions 0.32.0 → 0.33.0

package/dist/main.d.ts

@@ -59,17 +59,15 @@ export declare interface AnimEvent {
     fct: string;
 }
 
-/** @event Fired when a numeric material animation starts or completes. */
-export declare interface AnimFadeEvent {
-    type: 'Anim_Fade_Complete' | 'Anim_Fade_Start';
-    /** The name of the `THREE.Mesh` whose material fade changed state. */
-    objName: string;
+/** @event Fired when a material color or numeric property animation starts, completes, or is canceled. */
+export declare interface AnimMaterialEvent {
+    type: 'Anim_Material_Complete' | 'Anim_Material_Start' | 'Anim_Material_Cancel';
+    /** The name of the material whose animation changed state. */
+    materialName: string;
     /** The name of the calling method. */
     fct: string;
-    /** The material property being faded. */
-    property: string;
-    /** The target value used for the fade operation. */
-    value: any;
+    /** Snapshot of all animated properties; colors are represented as hex strings. */
+    values: Record<string, number | string>;
 }
 
 /**
@@ -151,11 +149,11 @@ declare class Audio_2 {
      * Loads an audio file and plays it automatically when loading is complete.
      * Use this method when no separate `Audio_Loaded` handling is required.
      * @param params - The sound options.
-     * @param params.fade - Fade-in duration for this start in seconds. Defaults to 0 (no fade).
+     * @param params.time - Fade-in duration for this start in seconds. Defaults to 0 (no fade).
      * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
      */
-    loadAndPlay({ fade, ease, ...params }: {
-        fade?: number;
+    loadAndPlay({ time, ease, ...params }: {
+        time?: number;
         ease?: string;
     } & SoundParams): void;
     /**
@@ -164,24 +162,24 @@ declare class Audio_2 {
      * This method does not wait for an audio file that is still loading.
      * @param params - Sound selection.
      * @param params.name - Loaded sound name.
-     * @param params.fade - Fade-in duration in seconds. Defaults to 0 (no fade).
+     * @param params.time - Fade-in duration in seconds. Defaults to 0 (no fade).
      * @param params.ease - GSAP easing for the fade-in. Defaults to linear ('none').
      */
-    play({ name, fade, ease }: {
+    play({ name, time, ease }: {
         name: string;
-        fade?: number;
+        time?: number;
         ease?: string;
     }): void;
     /**
      * Pauses a playing sound and keeps its position for the next play().
      * @param params - Sound selection and optional fade-out settings.
      * @param params.name - Sound name.
-     * @param params.fade - Fade-out duration in seconds. Defaults to 0 (no fade).
+     * @param params.time - Fade-out duration in seconds. Defaults to 0 (no fade).
      * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
      */
-    pause({ name, fade, ease }: {
+    pause({ name, time, ease }: {
         name: string;
-        fade?: number;
+        time?: number;
         ease?: string;
     }): void;
     /**
@@ -217,12 +215,12 @@ declare class Audio_2 {
      * Stops a playing or paused sound and resets its position, optionally fading out.
      * @param params - Sound selection.
      * @param params.name - Sound name.
-     * @param params.fade - Fade-out duration in seconds. Defaults to 0 (no fade).
+     * @param params.time - Fade-out duration in seconds. Defaults to 0 (no fade).
      * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
      */
-    stop({ name, fade, ease }: {
+    stop({ name, time, ease }: {
         name: string;
-        fade?: number;
+        time?: number;
         ease?: string;
     }): void;
     /**
@@ -787,7 +785,7 @@ export declare class Events {
 /**
  * Controls what happens after the final animation loop.
  * - `'hold'`: Keeps the action enabled and holds its final pose.
- * - `'fadeOut'`: Fades out over `fadeDurationFinish` seconds, or stops immediately when the duration is `0`.
+ * - `'fadeOut'`: Fades out over `fadeTimeFinish` seconds, or stops immediately when the duration is `0`.
  */
 export declare type FinishMode = 'hold' | 'fadeOut';
 
@@ -1243,30 +1241,21 @@ export declare class Mesh3D extends Obj3D {
     reflectivesSSR: THREE_TYPE.Object3D[];
     private model;
     /**
-     * Animates one or more color properties of this mesh's material.
-     * @param params - Animation parameters and target material color properties such as `color` or `emissive`.
-     * @param params.duration - Animation duration in seconds. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
-     */
-    animMaterialColor(params: {
-        duration?: number;
-        ease?: string;
-    } & {
-        [key: string]: string | number | THREE_TYPE.Color;
-    }): void;
-    /**
-     * Animates the first numeric material property passed for this mesh.
-     * @param params - Animation parameters and the target numeric material property.
-     * @param params.startValue - Starting value. Defaults to the current material value.
-     * @param params.infinite - Whether the animation repeats indefinitely. Default: **false**
-     * @param params.duration - Animation duration in seconds. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
-     * @param params.needsUpdate - Requests one material recompilation when the animation starts. Default: **false**
+     * Animates all assigned materials of this mesh, optionally including descendant meshes.
+     * @param params - Numeric and color targets with shared animation settings.
+     * @param params.recursive - Includes descendant meshes. Default: **false**
+     * @param params.infinite - Repeats each animation indefinitely. Default: **false**
+     * @param params.time - Duration in seconds. Default: **0**
+     * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
+     * @param params.needsUpdate - Recompiles materials when animation starts. Default: **false**
+     *
+     * @remarks
+     * Tweens and animation events are managed per material.
      */
-    animMaterialNumeric({ needsUpdate, ...params }: {
-        startValue?: number | null;
+    animMaterialsTo(params: {
+        recursive?: boolean;
         infinite?: boolean;
-        duration?: number;
+        time?: number;
         ease?: string;
         needsUpdate?: boolean;
         [key: string]: any;
@@ -1299,7 +1288,7 @@ export declare class Mesh3D extends Obj3D {
      * @param properties.recursive - Includes all descendant meshes when true. Default: **false**
      * @param properties.needsUpdate - Requests material recompilation after applying the properties. Default: **false**
      */
-    setMaterialProps({ recursive, needsUpdate, ...properties }: {
+    setMaterialsProps({ recursive, needsUpdate, ...properties }: {
         recursive?: boolean;
         needsUpdate?: boolean;
         [key: string]: any;
@@ -2065,84 +2054,91 @@ export declare class Scene {
     private readonly cam3D;
     private readonly events;
     private readonly objs3D;
-    private readonly tweens;
+    private readonly tweensObj;
+    private readonly tweensMtrl;
+    private readonly mtrls;
+    /** The underlying Three.js scene. */
+    readonly obj: THREE_TYPE.Scene;
     private ambientLight;
     private hemisphereLight;
-    /**
-     * The underlying Three.js scene.
-     */
-    readonly obj: THREE_TYPE.Scene;
     /**
      * Moves the camera along a curved path, optionally turning it toward a new target.
      * @param params - Camera movement settings.
      * @param params.camTarget - Destination position or object.
      * @param params.aimTarget - Position or object to look at while moving.
      * @param params.radiusOut - Outward curve radius. Default: **1**
-     * @param params.duration - Duration in seconds. Default: **2**
+     * @param params.time - Duration in seconds. Default: **2**
      * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
      *
      * @remarks
      * Emits {@link AnimEvent} when the animation starts and completes.
      */
-    animCamCurveTo({ camTarget, aimTarget, radiusOut, duration, ease }: {
+    animCamCurveTo({ camTarget, aimTarget, radiusOut, time, ease }: {
         camTarget: THREE_TYPE.Vector3 | string | Obj3D;
         aimTarget?: THREE_TYPE.Vector3 | string | Obj3D;
         radiusOut?: number;
-        duration?: number;
+        time?: number;
         ease?: string;
     }): void;
     /**
      * Moves a perspective camera to frame an object while looking at it. Only the object's own geometry is used; child objects are excluded.
      * @param params - Camera movement settings.
      * @param params.target - Object or scene object name to frame.
-     * @param params.duration - Duration in seconds. Default: **1**
+     * @param params.time - Duration in seconds. Default: **1**
      * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
      * @param params.dist - Multiplier for the calculated camera distance. Default: **1.25**
      *
      * @remarks
      * Emits {@link AnimEvent} when the animation starts and completes.
      */
-    animCamTo({ target, duration, ease, dist }: {
+    animCamTo({ target, time, ease, dist }: {
         target: string | Obj3D;
-        duration?: number;
+        time?: number;
         ease?: string;
         dist?: number;
     }): void;
     /**
-     * Animates one or more material colors on a mesh.
-     * @param params - Target colors, such as `color` or `emissive`, and animation settings.
-     * @param params.mesh - Scene mesh name or `Mesh3D` component.
-     * @param params.duration - Duration in seconds. Default: **0**
+     * Animates numeric and color properties of a named material from their current values.
+     * @param params - Target values and shared animation settings.
+     * @param params.name - Material name.
+     * @param params.infinite - Repeats the animation indefinitely. Default: **false**
+     * @param params.time - Duration in seconds. Default: **0**
      * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
+     * @param params.needsUpdate - Recompiles the material when animation starts. Default: **false**
      *
      * @remarks
-     * Colors may be strings, numbers, or `THREE.Color` values. Emits {@link AnimFadeEvent} when the animation starts and completes.
+     * Colors may be strings, numbers, or `THREE.Color` values. All properties share one tween.
+     * Unknown materials, unknown easing functions, and empty property lists leave a running animation unchanged.
+     * Property names and target values are the caller's responsibility. Only numeric and color properties are animated.
+     * A new call cancels the entire previous animation of the same material.
+     * Emits {@link AnimMaterialEvent} once on start, completion, or cancellation with all current values.
      */
-    animMaterialColor({ mesh, duration, ease, ...colorProps }: {
-        mesh: string | Mesh3D;
-        duration?: number;
+    animMaterialTo({ name, infinite, time, ease, needsUpdate, ...props }: {
+        name: string;
+        infinite?: boolean;
+        time?: number;
         ease?: string;
-    } & {
-        [key: string]: string | number | THREE_TYPE.Color | Mesh3D;
+        needsUpdate?: boolean;
+        [key: string]: any;
     }): void;
     /**
-     * Animates a numeric material property on a mesh. Only the first supplied property is animated.
-     * @param params - Target value and animation settings.
-     * @param params.mesh - Scene mesh name or `Mesh3D` component.
-     * @param params.startValue - Starting value. Defaults to the current material value.
-     * @param params.infinite - Repeats the animation indefinitely. Default: **false**
-     * @param params.duration - Duration in seconds. Default: **0**
+     * Animates all assigned materials of an object, optionally including descendant meshes.
+     * @param params - Target material values and shared animation settings.
+     * @param params.obj - Scene object name or `Mesh3D` component.
+     * @param params.recursive - Includes descendant meshes. Default: **false**
+     * @param params.infinite - Repeats each animation indefinitely. Default: **false**
+     * @param params.time - Duration in seconds. Default: **0**
      * @param params.ease - GSAP easing function. Default: **'power1.inOut'**
-     * @param params.needsUpdate - Recompiles the material when animation starts. Default: **false**
+     * @param params.needsUpdate - Recompiles materials when animation starts. Default: **false**
      *
      * @remarks
-     * Emits {@link AnimFadeEvent} when the animation starts and completes.
+     * Each shared material is animated once. Tweens and {@link AnimMaterialEvent} are managed per material.
      */
-    animMaterialNumeric({ mesh, needsUpdate, startValue, infinite, duration, ease, ...props }: {
-        mesh: string | Mesh3D;
-        startValue?: number | null;
+    animMaterialsTo({ obj, recursive, ...params }: {
+        obj: string | Mesh3D;
+        recursive?: boolean;
         infinite?: boolean;
-        duration?: number;
+        time?: number;
         ease?: string;
         needsUpdate?: boolean;
         [key: string]: any;
@@ -2154,7 +2150,7 @@ export declare class Scene {
      * @param params.pos - Target local position; omitted axes remain unchanged.
      * @param params.rot - Target local Euler angles in degrees, using the object's Euler order.
      * @param params.scale - Target local scale; omitted axes remain unchanged.
-     * @param params.duration - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
      * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
      *
      * @remarks
@@ -2164,7 +2160,7 @@ export declare class Scene {
      * A new call cancels the entire previous transformation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animTransformTo({ obj, pos, rot, scale, duration, ease }: {
+    animTransformTo({ obj, pos, rot, scale, time, ease }: {
         obj: string | Obj3D;
         pos?: {
             x?: number;
@@ -2181,9 +2177,10 @@ export declare class Scene {
             y?: number;
             z?: number;
         };
-        duration?: number;
+        time?: number;
         ease?: string;
     }): void;
+    private getMtrls;
     private getObjectName;
     /**
      * Plays a named animation clip with blending, looping, and speed control.
@@ -2191,44 +2188,44 @@ export declare class Scene {
      * @param params - Parameters for controlling the animation playback.
      * @param params.layer - The freely named layer used to group animation actions.
      * @param params.clip - The name of the animation clip to play.
-     * @param params.blendMode - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.finishMode - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
-     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
-     * @param params.fadeDurationFinish - Duration in seconds for `finishMode: 'fadeOut'`. Default: **0**
+     * @param params.modeBlend - How the action is blended with other active actions. Default: **'normal'**
+     * @param params.modeFinish - Whether the final pose is held or faded out after the final loop. Default: **'hold'**
+     * @param params.modeLoop - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.modeStop - Which previous actions of the same layer are stopped before playback. Default: **'all'**
+     * @param params.fadeTime - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
+     * @param params.fadeTimeFinish - Duration in seconds for `modeFinish: 'fadeOut'`. Default: **0**
      * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
      * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
-     * @param params.startSpeed - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.endSpeed - Target playback speed. Default: **1**
-     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
+     * @param params.speedStart - Initial playback speed for speed interpolation. Default: **0**
+     * @param params.speedEnd - Target playback speed. Default: **1**
+     * @param params.speedTime - Duration in seconds for speed interpolation. Default: **0**
+     * @param params.speedEase - GSAP easing function name. Default: **'power1.inOut'**
      *
      * @remarks
      * Playing an active or fading-in action again updates its speed without restarting it. Finished or stopped actions restart; fading-out actions resume from their current time and weight.
      *
-     * `finishMode` and `fadeDurationFinish` have no effect when `loopMode` is `'infinite'`.
+     * `modeFinish` and `fadeTimeFinish` have no effect when `modeLoop` is `'infinite'`.
      *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClip({ layer, clip: clipName, blendMode, finishMode, loopMode, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+    playClip({ layer, clip: clipName, modeBlend, modeFinish, modeLoop, modeStop, fadeTime, fadeTimeFinish, reverse, reset, speedStart, speedEnd, speedTime, speedEase }: {
         layer: string;
         clip: string;
         singleAction?: boolean;
-        blendMode?: BlendMode;
-        finishMode?: FinishMode;
-        loopMode?: LoopMode;
-        stopMode?: StopMode;
-        fadeDuration?: number;
-        fadeDurationFinish?: number;
+        modeBlend?: BlendMode;
+        modeFinish?: FinishMode;
+        modeLoop?: LoopMode;
+        modeStop?: StopMode;
+        fadeTime?: number;
+        fadeTimeFinish?: number;
         reverse?: boolean;
         reset?: boolean;
-        startSpeed?: number;
-        endSpeed?: number;
-        duration?: number;
-        ease?: string;
+        speedStart?: number;
+        speedEnd?: number;
+        speedTime?: number;
+        speedEase?: string;
     }): void;
     /**
      * Plays a named camera animation clip with blending, looping, and speed control.
@@ -2236,16 +2233,16 @@ export declare class Scene {
      * @param params - Parameters for controlling the camera animation playback.
      * @param params.layer - The freely named layer used to group camera animation actions.
      * @param params.clip - The name of the camera animation clip to play.
-     * @param params.blendMode - How the action is blended with other active actions. Default: **'normal'**
-     * @param params.loopMode - Number of plays or `'infinite'` for endless looping. Default: **1**
-     * @param params.stopMode - Which previous actions of the same layer are stopped before playback. Default: **'all'**
-     * @param params.fadeDuration - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
+     * @param params.modeBlend - How the action is blended with other active actions. Default: **'normal'**
+     * @param params.modeLoop - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.modeStop - Which previous actions of the same layer are stopped before playback. Default: **'all'**
+     * @param params.fadeTime - Duration in seconds for fading affected previous actions out and the new action in. Default: **0**
      * @param params.reverse - If `true`, plays the clip in reverse. Default: **false**
      * @param params.reset - If `true`, resets the clip before a new playback. Default: **false**
-     * @param params.startSpeed - Initial playback speed for speed interpolation. Default: **0**
-     * @param params.endSpeed - Target playback speed. Default: **1**
-     * @param params.duration - Duration in seconds for speed interpolation. Default: **0**
-     * @param params.ease - GSAP easing function name. Default: **'power1.inOut'**
+     * @param params.speedStart - Initial playback speed for speed interpolation. Default: **0**
+     * @param params.speedEnd - Target playback speed. Default: **1**
+     * @param params.speedTime - Duration in seconds for speed interpolation. Default: **0**
+     * @param params.speedEase - GSAP easing function name. Default: **'power1.inOut'**
      *
      * @remarks
      * Playing an active or fading-in action again updates its speed without restarting it. Finished or stopped actions restart; fading-out actions resume from their current time and weight.
@@ -2254,19 +2251,19 @@ export declare class Scene {
      *
      * {@link ClipEvent}
      */
-    playClipCam({ layer, clip: clipName, blendMode, loopMode, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+    playClipCam({ layer, clip: clipName, modeBlend, modeLoop, modeStop, fadeTime, reverse, reset, speedStart, speedEnd, speedTime, speedEase }: {
         layer: string;
         clip: string;
-        blendMode?: BlendMode;
-        loopMode?: LoopMode;
-        stopMode?: StopMode;
-        fadeDuration?: number;
+        modeBlend?: BlendMode;
+        modeLoop?: LoopMode;
+        modeStop?: StopMode;
+        fadeTime?: number;
         reverse?: boolean;
         reset?: boolean;
-        startSpeed?: number;
-        endSpeed?: number;
-        duration?: number;
-        ease?: string;
+        speedStart?: number;
+        speedEnd?: number;
+        speedTime?: number;
+        speedEase?: string;
     }): void;
     /**
      * Removes the built-in ambient light and releases its resources.
@@ -2315,16 +2312,30 @@ export declare class Scene {
         intensity?: number;
     }): void;
     /**
-     * Updates all material slots on a mesh, optionally including its descendants. Shared materials also affect other objects that use them.
+     * Updates properties of a named material. Shared materials also affect other objects that use them.
+     * @param params - Target material values, such as `color`, `roughness`, or `map`.
+     * @param params.name - Material name.
+     * @param params.needsUpdate - Recompiles the material after applying the values. Default: **false**
+     *
+     * @remarks
+     * Texture paths for `map` and `emissiveMap` load asynchronously. Property names and values are the caller's responsibility.
+     */
+    setMaterialProps({ name, needsUpdate, ...props }: {
+        name: string;
+        needsUpdate?: boolean;
+        [key: string]: any;
+    }): void;
+    /**
+     * Updates all assigned materials of an object, optionally including descendant meshes.
      * @param params - Target material values, such as `color`, `roughness`, or `map`.
      * @param params.obj - Scene object name or `Mesh3D` component.
      * @param params.recursive - Includes descendant meshes. Default: **false**
      * @param params.needsUpdate - Recompiles materials after applying the values. Default: **false**
      *
      * @remarks
-     * Texture paths for `map` and `emissiveMap` load asynchronously. Unsupported values are skipped with a warning.
+     * Each shared material is updated once. Texture paths for `map` and `emissiveMap` load asynchronously.
      */
-    setMaterialProps({ obj, recursive, needsUpdate, ...props }: {
+    setMaterialsProps({ obj, recursive, ...props }: {
         obj: string | Mesh3D;
         recursive?: boolean;
         needsUpdate?: boolean;
@@ -2334,16 +2345,16 @@ export declare class Scene {
      * Stops a named animation clip, optionally slowing it to a halt first.
      * @param params - Stop settings.
      * @param params.clipName - Animation clip name.
-     * @param params.fadeOut - Slowdown duration in seconds. Default: **0**
-     * @param params.ease - GSAP easing function for the slowdown. Default: **'power1.inOut'**
+     * @param params.speedTime - Slowdown duration in seconds. Default: **0**
+     * @param params.speedEase - GSAP easing function for the slowdown. Default: **'power1.inOut'**
      *
      * @remarks
      * A slowdown emits `Clip_Speed_Start` and `Clip_Speed_Complete`, followed by `Clip_Cancel`. A duration of `0` cancels immediately. See {@link ClipEvent}.
      */
-    stopAnimClip({ clipName, fadeOut, ease }: {
+    stopClip({ clipName, speedTime, speedEase }: {
         clipName: string;
-        fadeOut?: number;
-        ease?: string;
+        speedTime?: number;
+        speedEase?: string;
     }): void;
 }