illutions 0.23.1 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.24.1
+
+### Added
+
+- Added the `PROGRESSBAR_HIDDEN` event.
+
+### Changed
+
+- Renamed the `aaCfg` interface to `AaCfg`.
+
+### Fixed
+
+- Fixed an incorrect `objTarget.position` when enabling orbit or FPV controls after setting it in `Cam3D.onReady()`.
+
+## 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

@@ -35,7 +35,7 @@ import { TierResult } from 'detect-gpu';
  * Defines the shared anti-aliasing settings.
  * @category Cfg
  */
-export declare interface aaCfg {
+export declare interface AaCfg {
     /**
      * Whether the GUI anti-aliasing dropdown is open.
      * @default false
@@ -112,6 +112,8 @@ export declare class App<TClasses extends Classes = {}> {
     private readonly inspector;
     readonly comps: CompInsts<NonNullable<TClasses['comps']>>;
     readonly objs3D: Obj3DInsts<NonNullable<TClasses['objs3D']>>;
+    private compsMap;
+    private objs3DMap;
     /* Excluded from this release type: __constructor */
     init(cfg: Cfg): Promise<void>;
     /**
@@ -137,7 +139,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 +168,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 +286,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 +615,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 +652,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 +756,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 +777,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 +821,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 +1120,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 +1134,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 +1468,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 +1872,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 +1907,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 +2002,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
@@ -1976,7 +2013,7 @@ export declare interface PostCfg {
      */
     guiOpened: boolean;
     /** Anti-aliasing settings. */
-    aa: aaCfg;
+    aa: AaCfg;
     /** Shared SSAO settings. */
     ssao: SsaoCfg;
     /** Shared SSR settings. */
@@ -2002,6 +2039,12 @@ export declare interface PostCfg {
     };
 }
 
+/** @event Fired after the progress bar has finished hiding and triggers the corresponding XState event. */
+export declare interface ProgressBarHiddenEvent {
+    /** Identifies this event type. */
+    type: 'PROGRESSBAR_HIDDEN';
+}
+
 /**
  * The Raycast class manages pointer-based raycasting in a `THREE.Scene`. It tracks specified objects, detects cursor intersections with them, and triggers intersection and non-intersection events via
  * the application state. The class dynamically enables or disables pointer listeners depending on the number of tracked objects. It also handles pointer events (click, down, up, move, enter, leave) for the
@@ -2058,7 +2101,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 +2246,7 @@ export declare interface RenderCfg {
         /**
          * Parameters passed to `THREE.WebGPURenderer`.
          */
-        params: WebGpuRendererParameters;
+        params: WebGpuRendererParams;
     };
 }
 
@@ -2262,6 +2305,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 +2575,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 {