@needle-tools/engine 4.13.0 → 4.13.1-beta

package/lib/engine-components/web/CursorFollow.d.ts

@@ -1,10 +1,81 @@
 import { Behaviour } from "../Component.js";
 /**
- * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * [CursorFollow](https://engine.needle.tools/docs/api/CursorFollow) makes an object smoothly follow the cursor or touch position in 3D space.
+ * The component tracks pointer movement and updates the object's position to follow it, with optional damping for smooth motion.
  *
- * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
+ * ![](https://cloud.needle.tools/-/media/GDspQGC_kB85Bc9IyEtr9Q.gif)
  *
- * @summary Makes the object follow the cursor position on screen
+ * **How It Works:**
+ * The component creates a ray from the camera through the cursor position and places the object along that ray.
+ * By default, it maintains the object's initial distance from the camera, creating a natural cursor-following effect
+ * that works consistently regardless of camera movement.
+ *
+ * **Key Features:**
+ * - Smooth cursor following with configurable damping
+ * - Works with both mouse and touch input
+ * - Can follow cursor across the entire page or just within the canvas
+ * - Maintains consistent distance from camera by default
+ * - Optional surface snapping using raycasts
+ * - Responds to camera movement automatically
+ *
+ * **Common Use Cases:**
+ * - Interactive 3D cursors or pointers
+ * - Look-at effects combined with {@link LookAtConstraint}
+ * - Floating UI elements that track cursor
+ * - Interactive product showcases
+ * - 3D header effects and hero sections
+ * - Virtual laser pointers in XR experiences
+ *
+ * @example Basic cursor follow with smooth damping
+ * ```ts
+ * const follower = new Object3D();
+ * follower.position.set(0, 0, -5); // Initial position 5 units from camera
+ * follower.addComponent(CursorFollow, {
+ *   damping: 0.2,        // Smooth following with 200ms damping
+ *   keepDistance: true,  // Maintain initial distance
+ *   useFullPage: true    // Track cursor across entire page
+ * });
+ * scene.add(follower);
+ * ```
+ *
+ * @example Surface-snapping cursor with raycast
+ * ```ts
+ * const cursor = new Object3D();
+ * cursor.addComponent(CursorFollow, {
+ *   snapToSurface: true,  // Snap to surfaces in the scene
+ *   keepDistance: false,  // Don't maintain distance when snapping
+ *   damping: 0.1          // Quick, responsive movement
+ * });
+ * scene.add(cursor);
+ * ```
+ *
+ * @example Instant cursor following (no damping)
+ * ```ts
+ * gameObject.addComponent(CursorFollow, {
+ *   damping: 0,           // Instant movement
+ *   useFullPage: false    // Only track within canvas
+ * });
+ * ```
+ *
+ * @example Interactive 3D header that looks at cursor
+ * ```ts
+ * const character = loadModel("character.glb");
+ * const lookTarget = new Object3D();
+ * lookTarget.addComponent(CursorFollow, { damping: 0.3 });
+ * character.addComponent(LookAtConstraint, { target: lookTarget });
+ * scene.add(lookTarget, character);
+ * ```
+ *
+ * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/) - Combines CursorFollow with LookAt for an interactive 3D header
+ *
+ * @see {@link LookAtConstraint} - Commonly combined with CursorFollow for look-at effects
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ * @see {@link DragControls} - For dragging objects in 3D space
+ * @see {@link OrbitControls} - For camera controls that work alongside CursorFollow
+ * @see {@link Context.input} - The input system that provides cursor position
+ * @see {@link Context.physics.raycastFromRay} - Used when snapToSurface is enabled
+ *
+ * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
  * @group Components
  * @component
@@ -12,25 +83,118 @@ import { Behaviour } from "../Component.js";
 export declare class CursorFollow extends Behaviour {
     static readonly NAME = "CursorFollow";
     /**
-     * Damping for the movement, set to 0 for instant movement
+     * Damping factor controlling how smoothly the object follows the cursor (in seconds).
+     *
+     * This value determines the "lag" or smoothness of the following motion:
+     * - `0`: Instant movement, no damping (object snaps directly to cursor position)
+     * - `0.1-0.2`: Quick, responsive following with slight smoothing
+     * - `0.3-0.5`: Noticeable smooth trailing effect
+     * - `1.0+`: Slow, heavily damped movement
+     *
+     * The damping uses delta time, so the movement speed is framerate-independent and
+     * provides consistent behavior across different devices.
+     *
+     * **Tip:** For look-at effects, values between 0.2-0.4 typically feel most natural.
+     * For cursor indicators, 0.1 or less provides better responsiveness.
+     *
      * @default 0
      */
     damping: number;
     /**
-     * When enabled the object will follow the cursor even outside of the needle-engine canvas. This is useful for example for look at effects where you have a small needle-engine element on your page and you want the 3D object to keep looking at the cursor even when it's outside of the canvas.
+     * Whether the object should track the cursor across the entire webpage or only within the canvas.
+     *
+     * **When `true` (default):**
+     * - The object follows the cursor anywhere on the page, even outside the canvas bounds
+     * - Perfect for look-at effects where you want continuous tracking
+     * - Great for embedded 3D elements that should feel aware of the whole page
+     * - Example: A 3D character in a hero section that watches the cursor as you scroll
+     *
+     * **When `false`:**
+     * - The object only follows the cursor when it's inside the Needle Engine canvas
+     * - Useful for contained experiences where the 3D element shouldn't react to external cursor movement
+     * - Better for multi-canvas scenarios or when you want isolated 3D interactions
+     *
+     * **Note:** When enabled, the component listens to `window.pointermove` events to track the
+     * full-page cursor position. When disabled, it uses the context's input system which is
+     * canvas-relative.
+     *
+     * @see {@link Context.input.mousePositionRC} for canvas-relative cursor position
      * @default true
      */
     useFullPage: boolean;
     /**
-     * If true, the initial distance to the camera is maintained when following the cursor.
+     * Whether to maintain the object's initial distance from the camera while following the cursor.
+     *
+     * **When `true` (default):**
+     * - The object stays at a constant distance from the camera, moving in a spherical arc around it
+     * - Creates a natural "floating at cursor position" effect
+     * - The object's depth remains consistent as you move the cursor around
+     * - Perfect for cursors, pointers, or look-at targets
+     *
+     * **When `false`:**
+     * - The object's distance can change based on where the cursor projects in 3D space
+     * - More useful when combined with {@link snapToSurface} to follow surface geometry
+     * - Can create unusual depth behavior if not carefully configured
+     *
+     * **How it works:**
+     * On the first update, the component measures the distance from the object to the camera.
+     * This initial distance is then maintained throughout the object's lifetime (unless {@link updateDistance} is called).
+     * The object moves along a ray from the camera through the cursor, staying at this fixed distance.
+     *
+     * @see {@link updateDistance} to manually recalculate the distance
      * @default true
      */
     keepDistance: boolean;
     /**
-     * If true, the object will attempt to snap to the surface of other objects in the scene using a raycast.
+     * When enabled, the object snaps to the surfaces of other objects in the scene using raycasting.
+     *
+     * **How it works:**
+     * After positioning the object at the cursor location, a raycast is performed backwards toward the camera.
+     * If the ray hits any surface, the object is moved to that hit point, effectively "snapping" to the surface.
+     *
+     * **Use cases:**
+     * - 3D paint or decal placement tools
+     * - Surface markers or waypoints
+     * - Interactive object placement in AR/VR
+     * - Cursor that follows terrain or mesh surfaces
+     *
+     * **Important notes:**
+     * - Requires objects in the scene to have colliders for raycasting to work
+     * - Works best with {@link keepDistance} set to `false` to allow depth changes
+     * - Can be combined with {@link damping} for smooth surface following
+     * - The raycast uses the physics system's raycast functionality
+     *
+     * **Debug mode:**
+     * Add `?debugcursor` to your URL to visualize the raycast hits with green debug lines.
+     *
+     * @see {@link Context.physics.raycastFromRay} for the underlying raycast implementation
+     * @see {@link keepDistance} should typically be false when using surface snapping
+     * @default false
      */
     snapToSurface: boolean;
     private _distance;
+    /**
+     * Manually recalculates the distance between the object and the camera.
+     *
+     * By default, the distance is calculated once when the component starts and then maintained
+     * when {@link keepDistance} is enabled. Use this method to update the reference distance
+     * if the camera or object has moved significantly.
+     *
+     * **Use cases:**
+     * - After teleporting the camera or object
+     * - When switching between different camera positions
+     * - After zoom operations that change the desired following distance
+     * - Dynamically adjusting the cursor's depth in response to user input
+     *
+     * @param force - If `true`, forces a recalculation even if {@link keepDistance} is enabled and distance was already set
+     *
+     * @example Recalculate distance after camera movement
+     * ```ts
+     * const cursorFollow = gameObject.getComponent(CursorFollow);
+     * camera.position.set(0, 0, 10); // Move camera
+     * cursorFollow?.updateDistance(true); // Update the reference distance
+     * ```
+     */
     updateDistance(force?: boolean): void;
     /** @internal */
     awake(): void;

package/lib/engine-components/web/CursorFollow.js

@@ -12,11 +12,82 @@ import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 const debug = getParam("debugcursor");
 /**
- * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ * [CursorFollow](https://engine.needle.tools/docs/api/CursorFollow) makes an object smoothly follow the cursor or touch position in 3D space.
+ * The component tracks pointer movement and updates the object's position to follow it, with optional damping for smooth motion.
  *
- * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
+ * ![](https://cloud.needle.tools/-/media/GDspQGC_kB85Bc9IyEtr9Q.gif)
  *
- * @summary Makes the object follow the cursor position on screen
+ * **How It Works:**
+ * The component creates a ray from the camera through the cursor position and places the object along that ray.
+ * By default, it maintains the object's initial distance from the camera, creating a natural cursor-following effect
+ * that works consistently regardless of camera movement.
+ *
+ * **Key Features:**
+ * - Smooth cursor following with configurable damping
+ * - Works with both mouse and touch input
+ * - Can follow cursor across the entire page or just within the canvas
+ * - Maintains consistent distance from camera by default
+ * - Optional surface snapping using raycasts
+ * - Responds to camera movement automatically
+ *
+ * **Common Use Cases:**
+ * - Interactive 3D cursors or pointers
+ * - Look-at effects combined with {@link LookAtConstraint}
+ * - Floating UI elements that track cursor
+ * - Interactive product showcases
+ * - 3D header effects and hero sections
+ * - Virtual laser pointers in XR experiences
+ *
+ * @example Basic cursor follow with smooth damping
+ * ```ts
+ * const follower = new Object3D();
+ * follower.position.set(0, 0, -5); // Initial position 5 units from camera
+ * follower.addComponent(CursorFollow, {
+ *   damping: 0.2,        // Smooth following with 200ms damping
+ *   keepDistance: true,  // Maintain initial distance
+ *   useFullPage: true    // Track cursor across entire page
+ * });
+ * scene.add(follower);
+ * ```
+ *
+ * @example Surface-snapping cursor with raycast
+ * ```ts
+ * const cursor = new Object3D();
+ * cursor.addComponent(CursorFollow, {
+ *   snapToSurface: true,  // Snap to surfaces in the scene
+ *   keepDistance: false,  // Don't maintain distance when snapping
+ *   damping: 0.1          // Quick, responsive movement
+ * });
+ * scene.add(cursor);
+ * ```
+ *
+ * @example Instant cursor following (no damping)
+ * ```ts
+ * gameObject.addComponent(CursorFollow, {
+ *   damping: 0,           // Instant movement
+ *   useFullPage: false    // Only track within canvas
+ * });
+ * ```
+ *
+ * @example Interactive 3D header that looks at cursor
+ * ```ts
+ * const character = loadModel("character.glb");
+ * const lookTarget = new Object3D();
+ * lookTarget.addComponent(CursorFollow, { damping: 0.3 });
+ * character.addComponent(LookAtConstraint, { target: lookTarget });
+ * scene.add(lookTarget, character);
+ * ```
+ *
+ * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/) - Combines CursorFollow with LookAt for an interactive 3D header
+ *
+ * @see {@link LookAtConstraint} - Commonly combined with CursorFollow for look-at effects
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ * @see {@link DragControls} - For dragging objects in 3D space
+ * @see {@link OrbitControls} - For camera controls that work alongside CursorFollow
+ * @see {@link Context.input} - The input system that provides cursor position
+ * @see {@link Context.physics.raycastFromRay} - Used when snapToSurface is enabled
+ *
+ * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
  * @group Components
  * @component
@@ -25,25 +96,118 @@ export class CursorFollow extends Behaviour {
     // testing this for compilation
     static NAME = "CursorFollow";
     /**
-     * Damping for the movement, set to 0 for instant movement
+     * Damping factor controlling how smoothly the object follows the cursor (in seconds).
+     *
+     * This value determines the "lag" or smoothness of the following motion:
+     * - `0`: Instant movement, no damping (object snaps directly to cursor position)
+     * - `0.1-0.2`: Quick, responsive following with slight smoothing
+     * - `0.3-0.5`: Noticeable smooth trailing effect
+     * - `1.0+`: Slow, heavily damped movement
+     *
+     * The damping uses delta time, so the movement speed is framerate-independent and
+     * provides consistent behavior across different devices.
+     *
+     * **Tip:** For look-at effects, values between 0.2-0.4 typically feel most natural.
+     * For cursor indicators, 0.1 or less provides better responsiveness.
+     *
      * @default 0
      */
     damping = 0;
     /**
-     * When enabled the object will follow the cursor even outside of the needle-engine canvas. This is useful for example for look at effects where you have a small needle-engine element on your page and you want the 3D object to keep looking at the cursor even when it's outside of the canvas.
+     * Whether the object should track the cursor across the entire webpage or only within the canvas.
+     *
+     * **When `true` (default):**
+     * - The object follows the cursor anywhere on the page, even outside the canvas bounds
+     * - Perfect for look-at effects where you want continuous tracking
+     * - Great for embedded 3D elements that should feel aware of the whole page
+     * - Example: A 3D character in a hero section that watches the cursor as you scroll
+     *
+     * **When `false`:**
+     * - The object only follows the cursor when it's inside the Needle Engine canvas
+     * - Useful for contained experiences where the 3D element shouldn't react to external cursor movement
+     * - Better for multi-canvas scenarios or when you want isolated 3D interactions
+     *
+     * **Note:** When enabled, the component listens to `window.pointermove` events to track the
+     * full-page cursor position. When disabled, it uses the context's input system which is
+     * canvas-relative.
+     *
+     * @see {@link Context.input.mousePositionRC} for canvas-relative cursor position
      * @default true
      */
     useFullPage = true;
     /**
-     * If true, the initial distance to the camera is maintained when following the cursor.
+     * Whether to maintain the object's initial distance from the camera while following the cursor.
+     *
+     * **When `true` (default):**
+     * - The object stays at a constant distance from the camera, moving in a spherical arc around it
+     * - Creates a natural "floating at cursor position" effect
+     * - The object's depth remains consistent as you move the cursor around
+     * - Perfect for cursors, pointers, or look-at targets
+     *
+     * **When `false`:**
+     * - The object's distance can change based on where the cursor projects in 3D space
+     * - More useful when combined with {@link snapToSurface} to follow surface geometry
+     * - Can create unusual depth behavior if not carefully configured
+     *
+     * **How it works:**
+     * On the first update, the component measures the distance from the object to the camera.
+     * This initial distance is then maintained throughout the object's lifetime (unless {@link updateDistance} is called).
+     * The object moves along a ray from the camera through the cursor, staying at this fixed distance.
+     *
+     * @see {@link updateDistance} to manually recalculate the distance
      * @default true
      */
     keepDistance = true;
     /**
-     * If true, the object will attempt to snap to the surface of other objects in the scene using a raycast.
+     * When enabled, the object snaps to the surfaces of other objects in the scene using raycasting.
+     *
+     * **How it works:**
+     * After positioning the object at the cursor location, a raycast is performed backwards toward the camera.
+     * If the ray hits any surface, the object is moved to that hit point, effectively "snapping" to the surface.
+     *
+     * **Use cases:**
+     * - 3D paint or decal placement tools
+     * - Surface markers or waypoints
+     * - Interactive object placement in AR/VR
+     * - Cursor that follows terrain or mesh surfaces
+     *
+     * **Important notes:**
+     * - Requires objects in the scene to have colliders for raycasting to work
+     * - Works best with {@link keepDistance} set to `false` to allow depth changes
+     * - Can be combined with {@link damping} for smooth surface following
+     * - The raycast uses the physics system's raycast functionality
+     *
+     * **Debug mode:**
+     * Add `?debugcursor` to your URL to visualize the raycast hits with green debug lines.
+     *
+     * @see {@link Context.physics.raycastFromRay} for the underlying raycast implementation
+     * @see {@link keepDistance} should typically be false when using surface snapping
+     * @default false
      */
     snapToSurface = false;
     _distance = -1;
+    /**
+     * Manually recalculates the distance between the object and the camera.
+     *
+     * By default, the distance is calculated once when the component starts and then maintained
+     * when {@link keepDistance} is enabled. Use this method to update the reference distance
+     * if the camera or object has moved significantly.
+     *
+     * **Use cases:**
+     * - After teleporting the camera or object
+     * - When switching between different camera positions
+     * - After zoom operations that change the desired following distance
+     * - Dynamically adjusting the cursor's depth in response to user input
+     *
+     * @param force - If `true`, forces a recalculation even if {@link keepDistance} is enabled and distance was already set
+     *
+     * @example Recalculate distance after camera movement
+     * ```ts
+     * const cursorFollow = gameObject.getComponent(CursorFollow);
+     * camera.position.set(0, 0, 10); // Move camera
+     * cursorFollow?.updateDistance(true); // Update the reference distance
+     * ```
+     */
     updateDistance(force = false) {
         if (!force && (this.keepDistance && this._distance !== -1)) {
             return;

package/lib/engine-components/web/CursorFollow.js.map

@@ -1 +1 @@
-{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,OAAO,YAAa,SAAQ,SAAS;IAEvC,+BAA+B;IAC/B,MAAM,CAAU,IAAI,GAAG,cAAc,CAAC;IAEtC;;;;;;;;;;;;;;;;OAgBG;IAEH,OAAO,GAAW,CAAC,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;OAoBG;IAEH,WAAW,GAAY,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IAEH,YAAY,GAAY,IAAI,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IAEH,aAAa,GAAY,KAAK,CAAC;IAGvB,SAAS,GAAW,CAAC,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,QAAiB,KAAK;QACjC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE;YACxD,OAAO;SACV;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACrG,CAAC;IAED,gBAAgB;IAChB,KAAK;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC;IAED,gBAAgB;IAChB,QAAQ;QACJ,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IAChE,CAAC;IACD,gBAAgB;IAChB,SAAS;QACL,MAAM,CAAC,mBAAmB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACnE,CAAC;IAEO,MAAM,GAAG,CAAC,CAAC;IACX,MAAM,GAAG,CAAC,CAAC;IAEX,cAAc,GAAG,CAAC,CAAe,EAAE,EAAE;QACzC,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,CAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC,CAAA;IAGD,gBAAgB;IAChB,UAAU;QACN,8DAA8D;QAC9D,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;QAChF,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;QAEhF,yEAAyE;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACvC,MAAM,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAE5C,iDAAiD;QACjD,MAAM,YAAY,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9D,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,CAAC;QAE7C,oDAAoD;QACpD,MAAM,WAAW,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACnG,IAAI,SAAS,GAAG,WAAW,CAAC;QAG5B,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAClE,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,GAAG,CAAC;YACpC,SAAS,GAAG,GAAG,CAAC;SACnB;aACI;YACD,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,WAAW,CAAC;SAC/C;QAGD,IAAI,IAAI,CAAC,aAAa,EAAE;YACpB,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC;YACvB,GAAG,CAAC,SAAS,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YACtD,IAAI,IAAI,EAAE,MAAM,EAAE;gBACd,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBACpB,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE;oBAClB,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;iBACzG;qBACI;oBACD,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC;iBAC7C;gBAED,IAAG,KAAK,EAAE;oBACN,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,MAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;iBACpE;aACJ;SACJ;IAEL,CAAC;;AAlMD;IADC,YAAY,EAAE;6CACK;AAwBpB;IADC,YAAY,EAAE;iDACa;AAyB5B;IADC,YAAY,EAAE;kDACc;AA6B7B;IADC,YAAY,EAAE;mDACgB;AAwHnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC"}

package/lib/engine-components/web/HoverAnimation.d.ts

@@ -2,39 +2,168 @@ import { AnimationClip } from "three";
 import { ScaleClipType } from "../../engine/engine_animation.js";
 import { Behaviour } from "../Component.js";
 /**
- * Plays a hover animation on the object this component was added to when the mouse pointer (or touch) is over the object or any of it's children.
+ * [HoverAnimation](https://engine.needle.tools/docs/api/HoverAnimation) plays animations in response to pointer hover events on the object this component is attached to.
+ * The component automatically detects when the mouse pointer or touch enters/exits the object or any of its children, triggering the corresponding animations.
  *
- * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
+ * **How It Works:**
+ * The component listens to pointer enter and exit events and switches between two animation states:
+ * - **Hover state**: Plays when the pointer enters the object (default: scale up to 110%)
+ * - **Idle state**: Plays when the pointer exits the object (default: returns to original scale)
  *
- * @summary Hover Animation on Pointer Enter/Exit
+ * **Default Behavior:**
+ * If no custom animation clips are provided, the component automatically creates a smooth scale-up animation using the
+ * {@link type}, {@link duration}, and {@link scaleFactor} properties. This provides instant hover feedback without
+ * requiring any animation setup.
+ *
+ * **Custom Animations:**
+ * You can provide your own animation clips for complete control over the hover effect. This allows you to create
+ * complex animations involving position, rotation, color changes, or any other animated property.
+ *
+ * **Common Use Cases:**
+ * - Interactive buttons with scale feedback
+ * - Product showcases with highlight animations
+ * - Menu items with hover effects
+ * - Interactive 3D objects in AR/VR experiences
+ * - Call-to-action elements with attention-grabbing animations
+ *
+ * @example Basic usage with default scale animation
+ * ```ts
+ * const button = new Object3D();
+ * button.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.2,    // Scale to 120% on hover
+ *   duration: 0.2,       // 200ms animation
+ *   type: "ease-in-out"  // Smooth easing
+ * });
+ * scene.add(button);
+ * ```
+ *
+ * @example Custom hover animations
+ * ```ts
+ * const obj = new Object3D();
+ * const hoverAnim = loadAnimationClip("hover-glow.anim");
+ * const idleAnim = loadAnimationClip("idle-pulse.anim");
+ *
+ * obj.addComponent(HoverAnimation, {
+ *   hovered: hoverAnim,  // Custom hover animation
+ *   idle: idleAnim       // Custom idle animation
+ * });
+ * scene.add(obj);
+ * ```
+ *
+ * @example Quick scale animation with custom settings
+ * ```ts
+ * gameObject.addComponent(HoverAnimation, {
+ *   scaleFactor: 1.15,
+ *   duration: 0.15,
+ *   type: "ease-out"
+ * });
+ * ```
+ *
+ * @see {@link Animation} - The underlying animation component used to play clips
+ * @see {@link AnimationClip} - For creating custom animation clips
+ * @see {@link AnimationUtils} - Utility functions for creating animations programmatically
+ * @see {@link ScaleClipType} - Available easing types for the default scale animation
+ * @see {@link ObjectRaycaster} - Controls which objects receive pointer events
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ *
+ * @summary Plays animations on pointer hover enter/exit events
  * @category Interactivity
  * @group Components
+ * @component
  */
 export declare class HoverAnimation extends Behaviour {
     /**
-     * Default hover animation type if no custom clip is provided.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The easing type for the default scale animation.
+     *
+     * This property controls how the scale animation interpolates from the start to end value.
+     * Different easing types create different "feels" for the hover effect.
+     *
+     * **Available types:**
+     * - `"linear"`: Constant speed throughout the animation
+     * - `"ease-in"`: Starts slow, ends fast
+     * - `"ease-out"`: Starts fast, ends slow (good for responsive feel)
+     * - `"ease-in-out"`: Starts slow, fast in middle, ends slow (smooth and natural)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
+     * @see {@link ScaleClipType} for all available easing types
      * @default "linear"
      */
     type: ScaleClipType;
     /**
-     * Duration of the hover animation in seconds.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * Duration of the default hover animation in seconds.
+     *
+     * This controls how long it takes for the object to scale up when hovered.
+     * Shorter durations feel more responsive, while longer durations feel smoother.
+     *
+     * **Recommendations:**
+     * - `0.1-0.15s`: Snappy, responsive feel (good for buttons)
+     * - `0.2-0.3s`: Smooth, noticeable animation
+     * - `0.4s+`: Slow, emphasized effect
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 0.1
      */
     duration: number;
     /**
-     * Scale factor to apply when hovering.
-     * **Node**: This is only used if no custom hover animation clip is provided.
+     * The scale multiplier to apply when the object is hovered.
+     *
+     * This value is multiplied with the object's original scale to determine the hover size.
+     * A value of `1.0` means no change, values greater than `1.0` scale up, and values less than `1.0` scale down.
+     *
+     * **Examples:**
+     * - `1.0`: No scale change
+     * - `1.1`: Scale to 110% (subtle effect, default)
+     * - `1.2`: Scale to 120% (noticeable effect)
+     * - `1.5`: Scale to 150% (dramatic effect)
+     * - `0.9`: Scale to 90% (shrink on hover)
+     *
+     * **Note:** This is only used when no custom {@link hovered} animation clip is provided.
+     * If you provide a custom animation clip, this property is ignored.
+     *
      * @default 1.1
      */
     scaleFactor: number;
     /**
-     * Animation clip to play when hovering. If null, a default scale-up animation is used.
+     * Custom animation clip to play when the pointer hovers over the object.
+     *
+     * If `null`, the component automatically generates a scale-up animation based on the
+     * {@link type}, {@link duration}, and {@link scaleFactor} properties.
+     *
+     * Provide a custom animation clip if you want more complex hover effects such as:
+     * - Color changes or material property animations
+     * - Position or rotation changes
+     * - Multi-property animations
+     * - Animations affecting child objects
+     *
+     * **Tip:** The animation plays with a 0.1s fade duration for smooth transitions.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.createScaleClip} for programmatically creating scale animations
+     * @default null (generates default scale animation)
      */
     hovered: AnimationClip | null;
     /**
-     * Animation clip to play when not hovering. If null, an empty clip is used.
+     * Custom animation clip to play when the pointer is not hovering over the object (idle state).
+     *
+     * If `null`, an empty animation clip is used, which returns the object to its original state
+     * when the hover animation ends.
+     *
+     * You can provide a custom idle animation for effects such as:
+     * - Subtle breathing or floating motion when not hovered
+     * - Pulsing or glowing effects in idle state
+     * - Return-to-normal animations with custom easing
+     * - Looping ambient animations
+     *
+     * **Tip:** The idle animation is played with `loop: true`, so it will repeat continuously
+     * until the object is hovered again.
+     *
+     * @see {@link AnimationClip} for creating custom animation clips
+     * @see {@link AnimationUtils.emptyClip} to see how the default empty clip is created
+     * @default null (uses empty clip that returns to original state)
      */
     idle: AnimationClip | null;
     private animation;