illutions 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.24.0
+
+### Added
+
+- Added animation modes `BlendMode`, `FinishMode`, `LoopMode`, `StopMode`
+- Added `fadeDuration` to `playClip()` and `playClipCam()`.
+- Added `Audio.load()` to load audio without starting playback.
+- Added the `AudioLoadedEvent` (`AUDIO_LOADED`) event for handling completed audio loading.
+
+### Changed
+
+- Replaced `pauseActions` with `stopMode` and `infinite` with `loop` in animation clip playback.
+- Renamed `Raycast.trackSelectable()` to `Raycast.trackSelectables()`.
+- Changed the `LightCfg` shadow defaults to match the corresponding Three.js defaults, while keeping `castShadow` enabled by default.
+
+### Fixed
+
+- Fixed visual stuttering when transitioning from orbit rotation to panning with damping enabled by keeping `OrbitCtrls` in `lookMode = 'target'` for all OrbitControls interactions.
+
 ## 0.23.1
 
 ### FIXED

package/dist/main.d.ts

@@ -137,7 +137,8 @@ declare class Audio_2 {
     private readonly ctx;
     private readonly loader;
     private readonly engine;
-    private readonly sounds;
+    private readonly events;
+    private readonly loadedSounds;
     private readonly params;
     private listener;
     /* Excluded from this release type: __constructor */
@@ -165,32 +166,32 @@ declare class Audio_2 {
     isPlaying({ name }: {
         name: string;
     }): boolean;
+    private loadSound;
     /**
-     * Loads an audio file and plays it once loaded with a smooth fade-in.
-     * @param params - The parameters for loading and playing an audio.
-     * @param params.name - Unique name of the audio.
-     * @param params.url - Path or URL to the audio file.
-     * @param params.object - The name of the object to attach the audio to for positional audio. Pass an empty string for global audio.
-     * @param params.volume - The target playback volume. Default: **0**
-     * @param params.fade - The fade-in duration of the audio in seconds. Default: **2**
-     * @param params.loop - Whether the audio should loop. Default: **true**
+     * Loads an audio file without playing it and sends an `AUDIO_LOADED` event when the sound is ready.
+     * @param params - The sound options.
      */
-    loadAndPlay({ name, url, object, volume, fade, loop }: {
-        name: string;
-        url: string;
-        object: string;
-        volume?: number;
-        fade?: number;
-        loop?: boolean;
-    }): void;
+    load({ name, url, object, volume, fade, loop }: SoundParams): void;
     /**
-     * Plays an already loaded audio with a smooth fade-in.
+     * 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.
+     */
+    loadAndPlay({ name, url, object, volume, fade, loop }: SoundParams): void;
+    /**
+     * Plays an audio that has finished loading, with a smooth fade-in.
+     * 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 - Parameter object.
-     * @param params.name - The name of the audio to play.
+     * @param params.name - The name of the loaded audio to play.
      */
     play({ name }: {
         name: string;
     }): void;
+    /**
+     * Resumes the Web Audio context after a user gesture.
+     */
+    resume(): void;
     private setAttribute;
     private setAudioContext;
     /**
@@ -283,6 +284,21 @@ export declare interface AudioCfg {
     coneOuterGain: number;
 }
 
+/** @event Fired when an audio file has finished loading and is ready for playback. */
+export declare interface AudioLoadedEvent {
+    /** Identifies this event type. */
+    type: 'AUDIO_LOADED';
+    /** The unique name assigned to the loaded sound. */
+    soundName: string;
+}
+
+/**
+ * Defines how an animation action is blended with other active actions.
+ * - `'normal'`: Blends the action's values with other normal actions according to their weights.
+ * - `'additive'`: Adds the action's values to the current animation result according to its weight.
+ */
+export declare type BlendMode = 'normal' | 'additive';
+
 /**
  * Wraps a `THREE.Camera` and provides a structured interface for configuring and controlling camera settings.
  * @category 3D Objects
@@ -597,15 +613,16 @@ export declare class Engine {
     private readonly cfg;
     private readonly infoBox;
     private actionObserver;
+    private readonly objActions;
     private gltf;
     private mixer;
+    private callbacks;
+    private canvas;
     private composer;
     /* Excluded from this release type: renderer */
     private renderPipeline;
     /* Excluded from this release type: sceneReady */
     /* Excluded from this release type: rendererReady */
-    private callbacks;
-    private canvas;
     private fxaaPass;
     private outputPass;
     private renderPass;
@@ -633,6 +650,7 @@ export declare class Engine {
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: init */
     private initWebGpuRenderer;
+    private addActionToObj;
     /**
      * Registers a callback that is executed on every requestAnimationFrame update.
      * @param {(deltaTime: number) => void} cb - Callback executed once per frame with `deltaTime`.
@@ -736,6 +754,8 @@ export declare class Engine {
         [key: string]: any;
     }): void;
     private calcEaseArea;
+    private stopObjActions;
+    private finishAction;
     /**
      * Selects the active anti-aliasing mode. The modes `'fxaa'` and `'smaa'` lazy-load their required modules.
      * @param aaMode - The anti-aliasing mode to use.
@@ -755,37 +775,43 @@ export declare class Engine {
     /* Excluded from this release type: isPostEnabled */
     private isPostGpu;
     private loadScene;
-    private pauseObjActions;
     /**
-     * The method finds a Three.js animation clip by name, validates that it exists within the loaded GLTF and plays it via the `THREE.AnimationMixer`. It supports fade-in/out speed transitions, reverse playback,
-     * and infinite looping of the clip.
+     * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
-     * @param params - Parameter object for controlling the animation playback.
+     * @param params - Parameters for controlling the animation playback.
      * @param params.obj - The name of the object whose animation clip should be played.
      * @param params.clip - The name of the animation clip to play.
-     * @param params.pauseActions - Defines which other actions of the same object should be paused before playing this clip. Default: **'all'**
+     * @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.loop - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same object 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.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
-     * @param params.reset - If `true`, resets the clip to its start position before playback. In reverse mode, it resets to the clip end. Default: **false**
-     * @param params.startSpeed - The initial playback speed at the beginning of the fade. Default: **0**
-     * @param params.endSpeed - The target playback speed at the end of the fade. Default: **1**
-     * @param params.duration - The duration in seconds for the fade transition between start and end speed. Default: **0**
-     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
-
+     * @param params.reset - If `true`, resets the clip before 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'**
+     *
      * @remarks
-     * The method interpolates `timeScale` of the `THREE.AnimationAction`, allowing smooth acceleration or deceleration of animation playback.
+     * `finishMode` and `fadeDurationFinish` have no effect when `loop` is `'infinite'`.
      *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClip({ obj, clip: clipName, pauseActions, reverse, infinite, reset, startSpeed, endSpeed, duration, ease }: {
+    playClip({ obj, clip: clipName, blendMode, finishMode, loop, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
         obj: string;
         clip: string;
         singleAction?: boolean;
-        pauseActions?: PauseObjectActions;
+        blendMode?: BlendMode;
+        finishMode?: FinishMode;
+        loop?: LoopMode;
+        stopMode?: StopMode;
+        fadeDuration?: number;
+        fadeDurationFinish?: number;
         reverse?: boolean;
-        infinite?: boolean;
         reset?: boolean;
         startSpeed?: number;
         endSpeed?: number;
@@ -793,34 +819,36 @@ export declare class Engine {
         ease?: string;
     }): void;
     /**
-     * The method finds a camera animation clip by name, validates that it exists within the loaded GLTF and plays it via the `THREE.AnimationMixer`. It supports fade-in/out speed transitions, reverse playback,
-     * and infinite looping of the clip.
+     * Finds a camera animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
-     * @param params - Parameter object for controlling the animation playback.
+     * @param params - Parameters for controlling the camera animation playback.
      * @param params.obj - The name of the camera object whose animation clip should be played.
-     * @param params.clip - The name of the camera object's animation clip to play.
-     * @param params.pauseActions - Defines which other actions of the same object should be paused before playing this clip. Default: **'all'**
+     * @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.loop - Number of plays or `'infinite'` for endless looping. Default: **1**
+     * @param params.stopMode - Which previous actions of the same object 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.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.infinite - If `true`, the animation loops infinitely. Default: **false**
-     * @param params.reset - If `true`, resets the clip to its start position before playback. In reverse mode, it resets to the clip end. Default: **false**
-     * @param params.startSpeed - The initial playback speed at the beginning of the fade. Default: **0**
-     * @param params.endSpeed - The target playback speed at the end of the fade. Default: **1**
-     * @param params.duration - The duration in seconds for the fade transition between start and end speed. Default: **0**
-     * @param params.ease - The easing function name for GSAP. Default: **'power1.inOut'**
-     *
-     * @remarks
-     * The method interpolates `timeScale` of the `THREE.AnimationAction`, allowing smooth acceleration or deceleration of camera animation playback.
+     * @param params.reset - If `true`, resets the clip before 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'**
      *
+
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClipCam({ obj, clip: clipName, pauseActions, reverse, infinite, reset, startSpeed, endSpeed, duration, ease }: {
+    playClipCam({ obj, clip: clipName, blendMode, loop, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
         obj: string;
         clip: string;
-        pauseActions?: PauseObjectActions;
+        blendMode?: BlendMode;
+        loop?: LoopMode;
+        stopMode?: StopMode;
+        fadeDuration?: number;
         reverse?: boolean;
-        infinite?: boolean;
         reset?: boolean;
         startSpeed?: number;
         endSpeed?: number;
@@ -1090,6 +1118,7 @@ export declare class Events {
     private enqueue;
     /* Excluded from this release type: anim */
     /* Excluded from this release type: animFade */
+    /* Excluded from this release type: audioLoaded */
     /* Excluded from this release type: clip */
     /* Excluded from this release type: clipFade */
     /* Excluded from this release type: modelError */
@@ -1103,6 +1132,13 @@ export declare class Events {
     /* Excluded from this release type: windowResize */
 }
 
+/**
+ * Defines how an animation action behaves after its final loop.
+ * - `'hold'`: Keeps the action enabled and holds its final pose.
+ * - `'fadeOut'`: Fades the action out using `fadeDurationFinish`, or disables it immediately when the duration is `0`.
+ */
+export declare type FinishMode = 'hold' | 'fadeOut';
+
 /**
  * Defines the fog settings controlling scene depth-based color attenuation.
  * @category Cfg
@@ -1430,38 +1466,50 @@ export declare class Light3D extends Obj3D {
  * @category Cfg
  */
 export declare interface LightCfg {
+    /**
+     * If true, the light casts shadows.
+     * @default true
+     */
+    castShadow: boolean;
     /**
      * Shadow map resolution along the horizontal axis.
-     * @default 2048
+     * @default 512
      */
     mapWidth: number;
     /**
      * Shadow map resolution along the vertical axis.
-     * @default 2048
+     * @default 512
      */
     mapHeight: number;
     /**
      * Constant shadow bias applied to reduce shadow acne.
-     * @default -0.00002
+     * @default 0
      */
     bias: number;
     /**
      * Normal-based shadow bias to further reduce shadow artifacts.
-     * @default 0.005
+     * @default 0
      */
     normalBias: number;
     /**
      * Near clipping plane of the light's shadow camera.
-     * @default 0.1
+     * @default 0.5
      */
     near: number;
     /**
      * Far clipping plane of the light's shadow camera.
-     * @default 5
+     * @default 500
      */
     far: number;
 }
 
+/**
+ * Defines how often an animation action is played.
+ * - `number`: Plays the action the specified positive number of times.
+ * - `'infinite'`: Repeats the action indefinitely.
+ */
+export declare type LoopMode = number | 'infinite';
+
 /**
  * Defines the menu bar settings used to display licensed UI controls and branding.
  * @category Cfg
@@ -1822,8 +1870,6 @@ export declare class OrbitCtrls {
     private readonly params;
     private orbitCtrlsFirstChange;
     private callback;
-    private listenerPointersStart;
-    private listenerPointersEnd;
     private readonly touchPointerIds;
     /* Excluded from this release type: __constructor */
     /** Creates three.js `OrbitControls`. */
@@ -1859,8 +1905,6 @@ export declare class OrbitCtrls {
      * The extension is executed once immediately when `use()` is called.
      */
     use(extension: (orbitCtrls: OrbitCtrls) => void): void;
-    private updatePointersEnd;
-    private updatePointersStart;
 }
 
 /**
@@ -1956,15 +2000,6 @@ export declare interface OrbitCtrlsEvent {
     type: 'ORBITCTRLS_CHANGED' | 'ORBITCTRLS_DISABLED' | 'ORBITCTRLS_ENABLED' | 'ORBITCTRLS_END' | 'ORBITCTRLS_START' | 'ORBITCTRLS_DISPOSED';
 }
 
-/**
- * Defines which existing animation actions of the same object should be paused before a new clip is played.
- * - `'all'`: Pauses all actions of the object.
- * - `'finished'`: Pauses only actions of the object that are no longer active.
- * - `'last'`: Pauses only the last matching action of the object.
- * - `'none'`: Pauses no actions.
- */
-export declare type PauseObjectActions = 'all' | 'finished' | 'last' | 'none';
-
 /**
  * Defines the post-processing settings used by the rendering pipeline.
  * @category Cfg
@@ -2058,7 +2093,7 @@ export declare class Raycast {
      * @param params - Parameter object.
      * @param params.objs3D - The `Obj3D` instances to track.
      */
-    trackSelectable({ objs3D }: {
+    trackSelectables({ objs3D }: {
         objs3D: Obj3D[];
     }): void;
     /**
@@ -2203,7 +2238,7 @@ export declare interface RenderCfg {
         /**
          * Parameters passed to `THREE.WebGPURenderer`.
          */
-        params: WebGpuRendererParameters;
+        params: WebGpuRendererParams;
     };
 }
 
@@ -2262,6 +2297,22 @@ 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. */
+    name: string;
+    /** 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`. */
+    volume?: number;
+    /** Fade-in duration in seconds. Default: `2`. */
+    fade?: number;
+    /** Whether playback should loop. Default: `true`. */
+    loop?: boolean;
+};
+
 /**
  * Defines the screen-space ambient occlusion settings used to enhance depth and shading.
  * @category Cfg
@@ -2516,10 +2567,18 @@ export declare interface StateMachineCfg {
     inspector: boolean;
 }
 
+/**
+ * Defines which previous active animation actions of the same object are stopped before a new action is played.
+ * - `'all'`: Stops all previous active actions.
+ * - `'last'`: Stops only the most recently played previous active action.
+ * - `'none'`: Keeps all previous active actions running.
+ */
+export declare type StopMode = 'all' | 'last' | 'none';
+
 /** Function returned by an event subscription. Calling it removes the associated listener. */
 export declare type Unsubscribe = () => void;
 
-export declare type WebGpuRendererParameters = NonNullable<ConstructorParameters<typeof THREE_WEBGPU_TYPE.WebGPURenderer>[0]>;
+export declare type WebGpuRendererParams = NonNullable<ConstructorParameters<typeof THREE_WEBGPU_TYPE.WebGPURenderer>[0]>;
 
 /** @event Fired when the window size changes and triggers the corresponding XState event. */
 export declare interface WindowResizeEvent {