illutions 0.31.0 → 0.33.0

package/dist/main.d.ts

@@ -50,26 +50,24 @@ export declare interface AmbientlightCfg {
     intensity: number;
 }
 
-/** @event Fired when an object or material color animation starts or completes. */
+/** @event Fired when an object or material color animation starts, completes, or is canceled. */
 export declare interface AnimEvent {
-    type: 'Anim_Complete' | 'Anim_Start';
+    type: 'Anim_Complete' | 'Anim_Start' | 'Anim_Cancel';
     /** The name of the `THREE.Object3D` whose animation changed state. */
     objName: string;
     /** The name of the calling method. */
     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>;
 }
 
 /**
@@ -90,7 +88,6 @@ export declare class App<TComps extends Comps = {}> {
     readonly stateMachine: StateMachine;
     private readonly webCtrls;
     private cam3D;
-    private readonly inspector;
     readonly comps: CompsInsts<TComps>;
     private objs3DMap;
     private websMap;
@@ -114,17 +111,18 @@ export declare class App<TComps extends Comps = {}> {
  */
 declare class Audio_2 {
     private readonly ctx;
+    private listener;
     private readonly loader;
-    private readonly scene;
     private readonly events;
-    private readonly loadedSounds;
     private readonly params;
-    private listener;
+    private readonly scene;
+    private readonly sounds;
     private attachSoundTo;
+    private fadeSound;
     /**
-     * Returns a snapshot of playback timing and positional audio settings.
+     * Returns the shared positional sound defaults.
      */
-    get(): Partial<AudioCfg>;
+    get(): SoundParamsPos;
     /**
      * Checks whether a named sound is loaded.
      * @param params - Sound selection.
@@ -146,52 +144,84 @@ declare class Audio_2 {
      * Loads an audio file without playing it and sends an `Audio_Loaded` event when the sound is ready.
      * @param params - The sound options.
      */
-    load({ name, url, object, volume, fade, loop }: SoundParams): void;
+    load(params: SoundParams): void;
     /**
      * 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.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({ name, url, object, volume, fade, loop }: SoundParams): void;
+    loadAndPlay({ time, ease, ...params }: {
+        time?: number;
+        ease?: string;
+    } & SoundParams): void;
     /**
-     * Plays a loaded sound with a volume fade-in.
+     * Plays or resumes a loaded sound, optionally fading in from zero.
      * When using {@link load}, call this method after receiving the matching `Audio_Loaded` event.
      * 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.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, time, ease }: {
+        name: string;
+        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.time - Fade-out duration in seconds. Defaults to 0 (no fade).
+     * @param params.ease - GSAP easing for the fade-out. Defaults to linear ('none').
      */
-    play({ name }: {
+    pause({ name, time, ease }: {
         name: string;
+        time?: number;
+        ease?: string;
     }): void;
     /**
      * Resumes the Web Audio context after a user gesture.
      */
     resume(): void;
-    private setAttribute;
+    /**
+     * Updates shared positional defaults without replacing individual sound overrides.
+     * @param params - Positional defaults to update; omitted values remain unchanged.
+     */
+    set(params: Partial<SoundParamsPos>): void;
     private setAudioContext;
     /**
      * Attaches an audio listener to a scene object or camera. Set a listener before loading sounds.
      *
      * @param params - Listener target.
-     * @param params.object - Scene object name or camera to attach the listener to.
+     * @param params.obj - Scene object name or camera to attach the listener to.
      */
-    setListener({ object }: {
-        object: string | Cam3D;
+    setListener({ obj }: {
+        obj: string | Cam3D;
     }): void;
-    private setAllPositionalSoundsCfg;
-    private setPositionalSoundCfg;
     /**
-     * Updates one or more audio parameters at runtime.
-     * @param params - Audio parameters to update.
+     * Updates the volume and positional overrides of a loaded sound immediately.
+     * Volume is stored during a fade without interrupting it.
+     * @param params - Sound name and settings to change; omitted settings remain unchanged.
      */
-    set(params: Partial<AudioCfg>): void;
+    setSoundParams({ name, volume, ...positional }: {
+        name: string;
+        volume?: number;
+    } & Partial<SoundParamsPos>): void;
+    private setSoundParamsPos;
     /**
-     * Fades out a playing sound and stops it.
+     * Stops a playing or paused sound and resets its position, optionally fading out.
      * @param params - Sound selection.
      * @param params.name - Sound name.
+     * @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 }: {
+    stop({ name, time, ease }: {
         name: string;
+        time?: number;
+        ease?: string;
     }): void;
     /**
      * Runs an extension callback immediately with access to the public API.
@@ -205,7 +235,7 @@ export { Audio_2 as Audio }
  * Controls playback timing and how positional sound fades with distance.
  * @category Cfg
  */
-export declare interface AudioCfg {
+export declare interface AudioCfg extends SoundParamsPos {
     /**
      * Whether audio support is initialized when the application starts.
      * @default false
@@ -220,48 +250,13 @@ export declare interface AudioCfg {
      * Delay in milliseconds before loading audio for automatic playback.
      * @default 200
      */
-    delayPlaySound: number;
-    /**
-     * The reference distance after which the attenuation begins.
-     * @default 1
-     */
-    refDistance: number;
-    /**
-     * Determines how quickly the volume falls off with distance.
-     * @default 1
-     */
-    rolloffFactor: number;
-    /**
-     * Distance beyond which linear attenuation stops reducing volume.
-     * @default 1000
-     */
-    maxDistance: number;
-    /**
-     * The distance attenuation model used.
-     * @default 'inverse'
-     */
-    distanceModel: 'linear' | 'inverse' | 'exponential';
-    /**
-     * Inner cone angle in degrees, within which sound is not attenuated.
-     * @default 360
-     */
-    coneInnerAngle: number;
-    /**
-     * Outer cone angle in degrees, beyond which `coneOuterGain` applies.
-     * @default 360
-     */
-    coneOuterAngle: number;
-    /**
-     * The gain factor outside the cone.
-     * @default 0
-     */
-    coneOuterGain: number;
+    delayLoadSound: number;
 }
 
-/** @event Fired when an audio file has finished loading and is ready for playback. */
-export declare interface AudioLoadedEvent {
-    type: 'Audio_Loaded';
-    /** The unique name assigned to the loaded sound. */
+/** @event Fired when a sound finishes loading, starts playback, completes naturally, or is stopped. */
+export declare interface AudioEvent {
+    type: 'Audio_Loaded' | 'Audio_Start' | 'Audio_Complete' | 'Audio_Stop';
+    /** The unique name assigned to the sound. */
     soundName: string;
 }
 
@@ -580,9 +575,8 @@ export declare class Engine {
     private rttNode;
     private traaWarmupContext;
     private ecoButtonActive;
-    private gfxChanging;
-    private gfxIndex;
-    private gfxLevels;
+    private gfxLevelChanges;
+    private gfxLevel;
     private gfxMode;
     private readonly gfxPostProfiles;
     private gfxState;
@@ -791,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';
 
@@ -1247,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;
@@ -1303,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;
@@ -1565,7 +1550,6 @@ export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
  */
 export declare class OrbitCtrls {
     private readonly cam3D;
-    private readonly canvas;
     private readonly engine;
     private readonly events;
     private readonly modules;
@@ -2070,129 +2054,178 @@ export declare class Scene {
     private readonly cam3D;
     private readonly events;
     private readonly objs3D;
+    private readonly tweensObj;
+    private readonly tweensMtrl;
+    private readonly mtrls;
+    /** The underlying Three.js scene. */
+    readonly obj: THREE_TYPE.Scene;
     private ambientLight;
     private hemisphereLight;
-    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;
     }): void;
-    private calcEaseArea;
+    /**
+     * Animates selected local position, rotation, and scale components from their current values.
+     * @param params - Target object and transformation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @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.time - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.ease - GSAP easing function. Default: **'power2.inOut'**
+     *
+     * @remarks
+     * Rotation uses quaternion interpolation along the shortest path and does not support full turns.
+     * Omitted rotation axes keep their current target angles, but may change during interpolation.
+     * Cameras switch to free look mode. The caller coordinates other animations and controls.
+     * 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, time, ease }: {
+        obj: string | Obj3D;
+        pos?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        rot?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        scale?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        time?: number;
+        ease?: string;
+    }): void;
+    private getMtrls;
+    private getObjectName;
     /**
      * Plays a named animation clip with blending, looping, and speed control.
      *
      * @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.
@@ -2200,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.
@@ -2218,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.
@@ -2279,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;
@@ -2298,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;
 }
 
@@ -2392,21 +2439,76 @@ export declare interface SmaaCfg {
     guiOpened: boolean;
 }
 
-/** Parameters used to load a global or positional audio source. */
-export declare type SoundParams = {
-    /** Unique name used to identify the audio source. */
+/**
+ * Parameters used to load a global or positional audio source.
+ * @category Cfg
+ */
+export declare interface SoundParams extends Partial<SoundParamsPos> {
+    /**
+     * Whether playback should loop.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Unique name used to identify the audio source.
+     */
     name: string;
-    /** Path or URL to the audio file. */
+    /**
+     * Scene object name or Obj3D component for positional audio. Use an empty string for global audio.
+     */
+    obj: string | Obj3D;
+    /**
+     * Path or URL to the audio file.
+     */
     url: string;
-    /** Name of the scene object for positional audio. Use an empty string for global audio. */
-    object: string;
-    /** Target playback volume. Default: `0`. */
+    /**
+     * Target playback volume.
+     * @default 0
+     */
     volume?: number;
-    /** Fade-in duration in seconds. Default: `2`. */
-    fade?: number;
-    /** Whether playback should loop. Default: `true`. */
-    loop?: boolean;
-};
+}
+
+/**
+ * Controls distance attenuation and directional cones for positional sounds.
+ * @category Cfg
+ */
+export declare interface SoundParamsPos {
+    /**
+     * The reference distance after which the attenuation begins.
+     * @default 1
+     */
+    refDistance: number;
+    /**
+     * Determines how quickly the volume falls off with distance.
+     * @default 1
+     */
+    rolloffFactor: number;
+    /**
+     * Distance beyond which linear attenuation stops reducing volume.
+     * @default 1000
+     */
+    maxDistance: number;
+    /**
+     * The distance attenuation model used.
+     * @default 'inverse'
+     */
+    distanceModel: 'linear' | 'inverse' | 'exponential';
+    /**
+     * Inner cone angle in degrees, within which sound is not attenuated.
+     * @default 360
+     */
+    coneInnerAngle: number;
+    /**
+     * Outer cone angle in degrees, beyond which `coneOuterGain` applies.
+     * @default 360
+     */
+    coneOuterAngle: number;
+    /**
+     * The gain factor outside the cone.
+     * @default 0
+     */
+    coneOuterGain: number;
+}
 
 /**
  * Controls contact shading with WebGL SSAO.