illutions 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

package/dist/main.d.ts

@@ -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
@@ -296,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';
 
@@ -502,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'>;
@@ -610,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;
@@ -652,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`.
@@ -756,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.
@@ -781,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;
@@ -824,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;
@@ -946,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;
@@ -1122,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 */
     /**
@@ -1136,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';
 
@@ -1507,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';
 
@@ -2065,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;
@@ -2081,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.
      *
@@ -2088,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.
@@ -2119,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;
 }
 
 /**
@@ -2576,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';