illutions 0.32.0 → 0.34.0

package/dist/main.d.ts

@@ -1,6 +1,8 @@
 import { AnyEventObject } from 'xstate';
 import { AnyStateMachine } from 'xstate';
+import { degToRad } from 'three/src/math/MathUtils.js';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { radToDeg } from 'three/src/math/MathUtils.js';
 import { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
 import type * as THREE_TYPE from 'three';
 import type * as THREE_WEBGPU_TYPE from 'three/webgpu';
@@ -59,17 +61,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 +151,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 +164,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 +217,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;
     /**
@@ -286,6 +286,7 @@ export declare class Cam3D extends Obj3D {
     /** Reference to the original target `THREE.Object3D` loaded from the GLTF scene. */
     targetGltf: THREE_TYPE.Object3D | null;
     private readonly tmpVec;
+    animVelRotTo(params: Parameters<Obj3D['animVelRotTo']>[0]): void;
     /**
      * Called when a matching GLTF camera is found. Adopts its projection and world transform when the camera types match.
      * @param objGltf - The GLTF `THREE.Camera` object.
@@ -526,6 +527,9 @@ export declare interface CompsOverlapCfg {
     padding: number;
 }
 
+/** Coordinate space used for transformations. */
+export declare type CoordinateSpace = 'parent' | 'local' | 'world';
+
 /**
  * Controls diagnostic console output.
  * @category Cfg
@@ -549,6 +553,8 @@ declare type DeepPartial<T> = T extends readonly unknown[] ? T : T extends objec
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
+export { degToRad }
+
 /**
  * Renders the scene and controls post-processing and adaptive performance.
  * @category Core
@@ -676,7 +682,7 @@ export declare class EnvCtrls {
     /** Removes environment lighting and background maps, cancels pending updates, and stops rotation. */
     disable(): void;
     /**
-     * Returns a snapshot of environment rotation, intensity, and background blurriness.
+     * Returns a snapshot of environment rotation in radians, rotation speed in radians per second, intensity, and background blurriness.
      */
     get(): Partial<EnvCtrlsCfg>;
     /**
@@ -687,7 +693,7 @@ export declare class EnvCtrls {
     private loadText;
     /**
      * Updates supported environment control values at runtime.
-     * @param params - Runtime values to update: rotation speed, intensities, background blurriness or rotation.
+     * @param params - Runtime values to update: rotation speed in radians per second, intensities, background blurriness or rotation in radians.
      */
     set(params: Partial<EnvCtrlsCfg>): void;
     private setEnv;
@@ -741,7 +747,7 @@ export declare interface EnvCtrlsCfg {
      */
     map: string[];
     /**
-     * Environment and background rotation values in degrees.
+     * Environment and background rotation values in radians.
      * @default { x: 0, y: 0, z: 0 }
      */
     rotation: {
@@ -750,7 +756,7 @@ export declare interface EnvCtrlsCfg {
         z: number;
     };
     /**
-     * Environment and background rotation speed in degrees per second.
+     * Environment and background rotation speed in radians per second.
      * @default 0
      */
     rotationSpeed: number;
@@ -787,7 +793,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 +1249,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 +1296,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;
@@ -1420,23 +1417,31 @@ export declare class Obj3D {
      * @public
      */
     scene: Scene;
-    private posNdc;
-    private posScreen;
+    private coordTransl;
+    private coordRot;
+    private readonly tweensVel;
+    private readonly posNdc;
+    private readonly posScreen;
     private posScreenLast;
-    private posWorld;
+    private readonly posWorld;
     private posWorldLast;
-    private posCamWorld;
+    private readonly posCamWorld;
     private posWorldOccl;
     private posCamWorldOccl;
-    private quatWorld;
-    private quatWorldLast;
-    private rotWorld;
-    private visible;
+    private readonly orientWorld;
+    private orientWorldLast;
+    private readonly orientAnglesWorld;
+    private readonly velQuat;
+    private readonly velRotAxis;
+    private readonly velRotWorldToParent;
+    private readonly velTranslFrame;
+    private readonly velTranslWorldToParent;
     private inFrustum;
     private inFrustumLast;
-    private visibleLast;
     private occluded;
     private objHidden;
+    private visible;
+    private visibleLast;
     private visibleBeforeHidden;
     /**
      * Subscribes to an object event.
@@ -1447,11 +1452,90 @@ export declare class Obj3D {
     addEventListener<TType extends Obj3DEvent['type']>(type: TType, listener: (event: Extract<Obj3DEvent, {
         type: TType;
     }>) => void): Unsubscribe;
-    private calcFrustumVisibility;
-    private calcPosScreen;
-    private calcPosOccl;
-    private calcRotWorld;
-    private calcVisibility;
+    /**
+     * Animates this object's orientation in radians through {@link Scene.animRotTo}.
+     * @param params - Target orientation and animation settings, without an object parameter.
+     */
+    animRotTo(params: Omit<Parameters<Scene['animRotTo']>[0], 'obj'>): void;
+    /**
+     * Animates this object's scale through {@link Scene.animScaleTo}.
+     * @param params - Target scale and animation settings, without an object parameter.
+     */
+    animScaleTo(params: Omit<Parameters<Scene['animScaleTo']>[0], 'obj'>): void;
+    /**
+     * Animates this object's position through {@link Scene.animTranslTo}.
+     * @param params - Target position and animation settings, without an object parameter.
+     */
+    animTranslTo(params: Omit<Parameters<Scene['animTranslTo']>[0], 'obj'>): void;
+    /**
+     * Animates angular velocity in radians per second. World rotation requires uniformly scaled parents.
+     * @param params - Target angular velocity and animation settings.
+     * @param params.vx - Target velocity around X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity around Y.
+     * @param params.vz - Target velocity around Z.
+     * @param params.space - Coordinate space. Default: **'local'**
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelRotTo({ vx, vy, vz, space, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        space?: CoordinateSpace;
+        time?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Animates additive local scale velocity in scale units per second.
+     * @param params - Target scale velocity and animation settings.
+     * @param params.vx - Target velocity along X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity along Y.
+     * @param params.vz - Target velocity along Z.
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelScaleTo({ vx, vy, vz, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        time?: number;
+        ease?: string;
+    }): void;
+    private animVelTo;
+    /**
+     * Animates translation velocity in coordinate units per second. Parent scaling affects parent and local movement.
+     * @param params - Target translation velocity and animation settings.
+     * @param params.vx - Target velocity along X; omitted axes remain unchanged.
+     * @param params.vy - Target velocity along Y.
+     * @param params.vz - Target velocity along Z.
+     * @param params.space - Coordinate space. Default: **'parent'**
+     * @param params.time - Duration in seconds. Default: **0** (immediate).
+     * @param params.ease - GSAP easing. Default: **'none'** (linear).
+     * @remarks
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     * Completion means the target velocity is reached; motion continues unless the target is zero.
+     * With `time: 0`, start and completion are emitted immediately.
+     */
+    animVelTranslTo({ vx, vy, vz, space, time, ease }: {
+        vx?: number;
+        vy?: number;
+        vz?: number;
+        space?: CoordinateSpace;
+        time?: number;
+        ease?: string;
+    }): void;
+    private checkFrustumVisible;
+    private checkPosOccl;
+    private checkPosScreen;
+    private checkRotWorld;
     /**
      * Returns the object's screen position in canvas coordinates.
      * @param cam3D - Camera used for projection to canvas coordinates.
@@ -1492,6 +1576,7 @@ export declare class Obj3D {
         type: TType;
     }>) => void): void;
     private resetEventState;
+    private updVisible;
 }
 
 /** Object events available to registered listeners. */
@@ -1659,7 +1744,7 @@ export declare interface OrbitCtrlsCfg {
      */
     load: boolean;
     /**
-     * Maximum allowed horizontal orbit angle in degrees.
+     * Maximum allowed horizontal orbit angle in radians.
      * @default Infinity
      */
     maxAzimuthAngle: number;
@@ -1669,12 +1754,12 @@ export declare interface OrbitCtrlsCfg {
      */
     maxDistance: number;
     /**
-     * Maximum allowed vertical orbit angle in degrees.
-     * @default 180
+     * Maximum allowed vertical orbit angle in radians.
+     * @default Math.PI
      */
     maxPolarAngle: number;
     /**
-     * Minimum allowed horizontal orbit angle in degrees.
+     * Minimum allowed horizontal orbit angle in radians.
      * @default -Infinity
      */
     minAzimuthAngle: number;
@@ -1684,7 +1769,7 @@ export declare interface OrbitCtrlsCfg {
      */
     minDistance: number;
     /**
-     * Minimum allowed vertical orbit angle in degrees.
+     * Minimum allowed vertical orbit angle in radians.
      * @default 0
      */
     minPolarAngle: number;
@@ -1754,6 +1839,8 @@ export declare interface ProgressBarHiddenEvent {
     type: 'ProgressBar_Hidden';
 }
 
+export { radToDeg }
+
 /**
  * Manages collider-based occlusion and pointer picking in a `THREE.Scene`. Collider roles determine which objects block rays, emit pointer events, or remain hidden while participating in raycasting.
  * @category Core
@@ -2065,170 +2152,217 @@ 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;
     }): void;
     /**
-     * Animates selected local position, rotation, and scale components from their current values.
-     * @param params - Target object and transformation settings.
+     * Animates orientation from its current value using Euler angles in radians.
+     * @param params - Target object, orientation, and animation 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.duration - Duration in seconds. Default: **1**. A value of 0 applies the values immediately.
+     * @param params.x - Target X angle in radians; omitted axes keep their starting target angles.
+     * @param params.y - Target Y angle in radians.
+     * @param params.z - Target Z angle in radians.
+     * @param params.path - Rotation interpolation. Default: **'euler'**; **'quat'** takes the shortest orientation path.
+     * @param params.order - Euler order for interpreting angles in both paths. Default: **'XYZ'**
+     * @param params.space - Orientation space. Default: **'parent'**
+     * @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.
+     * Euler interpolation supports full turns. Each call starts from the current orientation without retaining previous turns.
+     * Quaternion interpolation takes the shortest path; omitted Euler axes may change during interpolation.
+     * World targets account for moving parents. The caller is responsible for non-uniform parent scaling.
      * 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.
+     * A new call cancels only the previous orientation animation of the same object.
      * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
      */
-    animTransformTo({ obj, pos, rot, scale, duration, ease }: {
+    animRotTo({ obj, x, y, z, path, order, space, 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;
-        };
-        duration?: number;
+        x?: number;
+        y?: number;
+        z?: number;
+        path?: 'euler' | 'quat';
+        order?: THREE_TYPE.EulerOrder;
+        space?: 'parent' | 'world';
+        time?: number;
+        ease?: string;
+    }): void;
+    /**
+     * Animates selected local scale axes from their current values.
+     * @param params - Target object, scale, and animation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @param params.x - Target X scale; omitted axes remain unchanged.
+     * @param params.y - Target Y scale.
+     * @param params.z - Target Z scale.
+     * @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
+     * A new call cancels only the previous scale animation of the same object.
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     */
+    animScaleTo({ obj, x, y, z, time, ease }: {
+        obj: string | Obj3D;
+        x?: number;
+        y?: number;
+        z?: number;
+        time?: number;
         ease?: string;
     }): void;
-    private getObjectName;
+    /**
+     * Animates selected position axes from their current values in parent or world space.
+     * @param params - Target object, position, and animation settings.
+     * @param params.obj - Scene object name or component, including cameras.
+     * @param params.x - Target X position; omitted axes keep their starting values.
+     * @param params.y - Target Y position.
+     * @param params.z - Target Z position.
+     * @param params.space - Position space. Default: **'parent'**
+     * @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
+     * World targets account for moving parents. Cameras switch to free look mode.
+     * A new call cancels only the previous position animation of the same object.
+     * Emits {@link AnimEvent}: `Anim_Start`, `Anim_Complete`, or `Anim_Cancel` when replaced.
+     */
+    animTranslTo({ obj, x, y, z, space, time, ease }: {
+        obj: string | Obj3D;
+        x?: number;
+        y?: number;
+        z?: number;
+        space?: 'parent' | 'world';
+        time?: number;
+        ease?: string;
+    }): void;
+    private getMtrls;
+    private getObj;
     /**
      * 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.
@@ -2236,16 +2370,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 +2388,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 +2449,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 +2482,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;
 }