illutions 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.25.0
+
+### Added
+
+- Added `CanvasPointerLeave` handling to the `OBJ3D_POINTER_LEAVE` event.
+- Added `ActionCtrls` for centralized animation action lifecycle, layer grouping, and interruptible fades.
+- Extended `ClipEvent` with `CLIP_CANCEL`, `CLIP_FADE_START`, `CLIP_FADE_COMPLETE`, `CLIP_SPEED_START`, and `CLIP_SPEED_COMPLETE` events.
+
+### Fixed
+
+- Fixed `OBJ3D_POINTER_LEAVE` being emitted during pointer movement with a pressed mouse button and ensured touch pointers emit it after `OBJ3D_POINTER_UP` when contact ends.
+
+## 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

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
@@ -48,6 +48,8 @@ export declare interface aaCfg {
     mode: 'none' | 'fxaa' | 'smaa';
 }
 
+export declare type ActionFadeMode = 'in' | 'out';
+
 /**
  * Defines the ambient light settings controlling global scene illumination.
  * @category Cfg
@@ -112,6 +114,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>;
     /**
@@ -294,8 +298,8 @@ export declare interface AudioLoadedEvent {
 
 /**
  * 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.
+ * - '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';
 
@@ -500,28 +504,18 @@ export declare type Classes<TObj3DClasses extends Record<string, Obj3DClass> = {
     comps?: TCompClasses;
 };
 
-/** @event Fired when a clip starts or finishes playing and triggers the corresponding XState event. */
+/** @event Fired when a clip starts, completes, is canceled, fades its weight, or changes its playback speed. */
 export declare interface ClipEvent {
     /** Identifies this event type. */
-    type: 'CLIP_START' | 'CLIP_COMPLETE';
-    /** The name of the `THREE.AnimationClip` that changed state. */
-    clipName: string;
-    /** The name of the calling method. */
-    fct: string;
-    /** The associated animation action, when available. */
-    action?: THREE_TYPE.AnimationAction;
-}
-
-/** @event Fired when a clip fade starts, completes, or fade-out starts/completes and triggers the corresponding XState event. */
-export declare interface ClipFadeEvent {
-    /** Identifies this event type. */
-    type: 'CLIP_FADE_START' | 'CLIP_FADE_COMPLETE' | 'CLIP_FADEOUT_COMPLETE' | 'CLIP_FADEOUT_START';
-    /** The name of the `THREE.AnimationClip` whose fade changed state. */
+    type: 'CLIP_START' | 'CLIP_COMPLETE' | 'CLIP_CANCEL' | 'CLIP_FADE_START' | 'CLIP_FADE_COMPLETE' | 'CLIP_SPEED_START' | 'CLIP_SPEED_COMPLETE';
+    /** The name of the affected `THREE.AnimationClip`. */
     clipName: string;
     /** The name of the calling method. */
     fct: string;
     /** The associated animation action, when available. */
     action?: THREE_TYPE.AnimationAction;
+    /** Whether the clip weight is fading in or out. */
+    fadeMode?: ActionFadeMode;
 }
 
 declare type ColorNode = THREE_WEBGPU_TYPE.Node<'vec4'>;
@@ -608,12 +602,10 @@ export declare class Engine {
     private readonly cam3D;
     private readonly events;
     private readonly modules;
-    private readonly comps;
     private readonly objs3D;
     private readonly cfg;
     private readonly infoBox;
-    private actionObserver;
-    private readonly objActions;
+    private actionCtrls;
     private gltf;
     private mixer;
     private callbacks;
@@ -650,7 +642,6 @@ 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`.
@@ -754,8 +745,6 @@ 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.
@@ -779,35 +768,37 @@ export declare class Engine {
      * Finds a Three.js animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
      * @param params - Parameters for controlling the animation playback.
-     * @param params.obj - The name of the object whose animation clip should be played.
+     * @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.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.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.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before playback. 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'**
      *
      * @remarks
-     * `finishMode` and `fadeDurationFinish` have no effect when `loop` is `'infinite'`.
+     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
+     *
+     * `finishMode` and `fadeDurationFinish` have no effect when `loopMode` is `'infinite'`.
      *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClip({ obj, clip: clipName, blendMode, finishMode, loop, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        obj: string;
+    playClip({ layer, clip: clipName, blendMode, finishMode, loopMode, stopMode, fadeDuration, fadeDurationFinish, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
         clip: string;
         singleAction?: boolean;
         blendMode?: BlendMode;
         finishMode?: FinishMode;
-        loop?: LoopMode;
+        loopMode?: LoopMode;
         stopMode?: StopMode;
         fadeDuration?: number;
         fadeDurationFinish?: number;
@@ -822,30 +813,31 @@ export declare class Engine {
      * Finds a camera animation clip by name and plays it through the `THREE.AnimationMixer`.
      *
      * @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.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.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.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.reverse - If `true`, plays the clip in reverse. Default: **false**
-     * @param params.reset - If `true`, resets the clip before playback. 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'**
      *
-
+     * @remarks
+     * Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.
+     *
      * **Events**
      *
      * {@link ClipEvent}
      */
-    playClipCam({ obj, clip: clipName, blendMode, loop, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
-        obj: string;
+    playClipCam({ layer, clip: clipName, blendMode, loopMode, stopMode, fadeDuration, reverse, reset, startSpeed, endSpeed, duration, ease }: {
+        layer: string;
         clip: string;
         blendMode?: BlendMode;
-        loop?: LoopMode;
+        loopMode?: LoopMode;
         stopMode?: StopMode;
         fadeDuration?: number;
         reverse?: boolean;
@@ -944,12 +936,12 @@ export declare class Engine {
      * @param params.ease - The easing function name for the fade-out transition. Default: **'power1.inOut'**
      *
      * @remarks
-     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero, allowing a visually smooth stop. Once completed, a `ClipFade` event with type `CLIP_FADEOUT_COMPLETE`
-     * is emitted. If no fade-out is specified, the clip stops immediately.
+     * The method gradually reduces the clip's playback speed to zero when `fadeOut` is greater than zero. It emits `CLIP_SPEED_START`, `CLIP_SPEED_COMPLETE`, and finally `CLIP_CANCEL`.
+     * If no speed transition is specified, the clip is canceled immediately.
      *
      * **Events**
      *
-     * {@link ClipFadeEvent}
+     * {@link ClipEvent}
      */
     stopAnimClip({ clipName, fadeOut, ease }: {
         clipName: string;
@@ -1120,7 +1112,6 @@ export declare class Events {
     /* 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 */
     /* Excluded from this release type: modelLoading */
     /**
@@ -1134,8 +1125,8 @@ export declare class Events {
 
 /**
  * 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`.
+ * - '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';
 
@@ -1505,8 +1496,8 @@ export declare interface LightCfg {
 
 /**
  * Defines how often an animation action is played.
- * - `number`: Plays the action the specified positive number of times.
- * - `'infinite'`: Repeats the action indefinitely.
+ * - number: Plays the action the specified positive number of times.
+ * - 'infinite': Repeats the action indefinitely.
  */
 export declare type LoopMode = number | 'infinite';
 
@@ -2011,7 +2002,7 @@ export declare interface PostCfg {
      */
     guiOpened: boolean;
     /** Anti-aliasing settings. */
-    aa: aaCfg;
+    aa: AaCfg;
     /** Shared SSAO settings. */
     ssao: SsaoCfg;
     /** Shared SSR settings. */
@@ -2037,6 +2028,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
@@ -2057,12 +2054,14 @@ export declare class Raycast {
     private objCandidate;
     private closestObjCounter;
     private isEnabled;
-    private callbackSelect;
+    private callback;
     private listenerClick;
+    private listenerCancel;
     private listenerDown;
+    private listenerLeave;
     private listenerMove;
     private listenerUp;
-    private pointerEvent;
+    private eventPointerMove;
     private posPrevPointerX;
     private posPrevPointerY;
     private posWorldObj;
@@ -2073,6 +2072,7 @@ export declare class Raycast {
     enable(): void;
     /** Disables pointer-based raycasting and removes all pointer event listeners and the frame update callback. */
     disable(): void;
+    private getObjectAtPointer;
     /**
      * Checks whether an object's world position is visible from the active camera without being occluded.
      *
@@ -2080,15 +2080,19 @@ export declare class Raycast {
      * @returns `true` if no other object blocks the line of sight to the object's world position, otherwise `false`.
      */
     isVisibleOcclusion(obj: THREE_TYPE.Object3D): boolean;
-    private onClick;
-    private onPointerDown;
+    private onCanvasClick;
+    private onCanvasPointerLeave;
+    private onCanvasPointerMove;
+    private onCanvasPointerCancel;
+    private onCanvasPointerDown;
+    private onCanvasPointerExit;
+    private onCanvasPointerUp;
     private onPointerEnter;
     private onPointerLeave;
     private onPointerMove;
-    private onPointerUp;
     /**
      * Begins tracking a list of scene objects for pointer intersection detection. If the raycaster is not yet listening for pointer movements, this method automatically attaches pointer event listeners
-     * (`pointermove`, `click`, `pointerdown`, `pointerup`).
+     * (`pointermove`, `click`, `pointercancel`, `pointerdown`, `pointerleave`, `pointerup`).
      *
      * @param params - Parameter object.
      * @param params.objs3D - The `Obj3D` instances to track.
@@ -2111,8 +2115,8 @@ export declare class Raycast {
     untrackSelectable({ objs3D }: {
         objs3D: Obj3D[];
     }): void;
-    /* Excluded from this release type: updateSelect */
-    private updatePointer;
+    /* Excluded from this release type: updatePointerHover */
+    private updatePointerPosition;
 }
 
 /**
@@ -2568,10 +2572,10 @@ export declare interface StateMachineCfg {
 }
 
 /**
- * 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.
+ * Defines which previous active animation actions of the same layer 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';