@needle-tools/engine 4.13.0 → 4.13.1

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

@@ -17,16 +17,125 @@ onStart(ctx => {
     }
 });
 /**
- * ClickThrough component allows pointer events to "click through" the 3D canvas to HTML elements behind it.
+ * [ClickThrough](https://engine.needle.tools/docs/api/ClickThrough) enables pointer events to pass through the 3D canvas to HTML elements positioned behind it.
+ * This component dynamically toggles `pointer-events: none` on the canvas when no 3D objects are hit by raycasts, allowing interaction with underlying HTML content.
  *
- * This is useful if you have a transparent canvas overlaying HTML content and want to interact with the HTML content through the transparent areas of the canvas.
+ * ![](https://cloud.needle.tools/-/media/VeahihyjzpBWf4jHHVnrqw.gif)
  *
- * Usage Options:
- * - Add the ClickThrough component to any GameObject in your scene.
- * - Alternatively, add the `clickthrough` attribute to the `<needle-engine>` HTML element (e.g. `<needle-engine clickthrough></needle-engine>`).
+ * **How It Works:**
+ * The component listens to pointer events and performs raycasts to detect if any 3D objects are under the cursor:
+ * - **When 3D objects are hit**: Canvas has `pointer-events: all` (normal 3D interaction)
+ * - **When nothing is hit**: Canvas has `pointer-events: none` (clicks pass through to HTML)
  *
- * - Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
- * @summary Allows pointer events to "click through" the 3D canvas to HTML elements behind it.
+ * This creates a seamless experience where users can interact with both 3D objects and underlying HTML elements
+ * through the same canvas area, depending on what's under the cursor.
+ *
+ * **Key Features:**
+ * - Automatic pointer event routing based on 3D hit detection
+ * - Works with both mouse and touch input
+ * - Supports transparent or semi-transparent canvases
+ * - Can be enabled via component or HTML attribute
+ * - No performance impact when disabled
+ * - Handles multi-touch scenarios correctly
+ *
+ * **Common Use Cases:**
+ * - Overlaying 3D elements on top of HTML content (headers, hero sections)
+ * - Creating "floating" 3D objects that don't block underlying UI
+ * - Mixed 2D/3D interfaces where both need to be interactive
+ * - Transparent 3D overlays on websites
+ * - Product showcases with clickable text/buttons beneath the 3D view
+ * - Interactive storytelling with mixed HTML and 3D content
+ *
+ * **Setup Options:**
+ *
+ * **Option 1: Component-based** (programmatic setup)
+ * ```ts
+ * // Add to any GameObject in your scene
+ * scene.addComponent(ClickThrough);
+ * ```
+ *
+ * **Option 2: HTML attribute** (declarative setup, recommended)
+ * ```html
+ * <!-- Enable clickthrough via HTML attribute -->
+ * <needle-engine clickthrough></needle-engine>
+ *
+ * <!-- Dynamically toggle clickthrough -->
+ * <needle-engine id="engine" clickthrough="true"></needle-engine>
+ * <script>
+ *   // Disable clickthrough
+ *   document.getElementById('engine').setAttribute('clickthrough', 'false');
+ * </script>
+ * ```
+ *
+ * @example Basic transparent canvas over HTML
+ * ```html
+ * <style>
+ *   .container { position: relative; }
+ *   needle-engine { position: absolute; top: 0; left: 0; }
+ *   .html-content { position: absolute; top: 0; left: 0; }
+ * </style>
+ *
+ * <div class="container">
+ *   <div class="html-content">
+ *     <h1>Click me!</h1>
+ *     <button>I'm clickable through the 3D canvas</button>
+ *   </div>
+ *   <needle-engine clickthrough src="scene.glb"></needle-engine>
+ * </div>
+ * ```
+ *
+ * @example Programmatic setup with toggle
+ * ```ts
+ * const clickthrough = scene.addComponent(ClickThrough);
+ *
+ * // Toggle clickthrough based on some condition
+ * function setInteractiveMode(mode: 'html' | '3d' | 'mixed') {
+ *   switch(mode) {
+ *     case 'html':
+ *       clickthrough.enabled = false; // 3D blocks HTML
+ *       break;
+ *     case '3d':
+ *       clickthrough.enabled = false; // 3D only
+ *       break;
+ *     case 'mixed':
+ *       clickthrough.enabled = true;  // Smart switching
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @example 3D header with clickable logo beneath
+ * ```html
+ * <!-- 3D animated object over a clickable logo -->
+ * <div class="header">
+ *   <a href="/" class="logo">My Brand</a>
+ *   <needle-engine clickthrough src="header-animation.glb"></needle-engine>
+ * </div>
+ * ```
+ *
+ * **Technical Notes:**
+ * - The component uses `pointer-events` CSS property for passthrough
+ * - Touch events are handled separately with a special timing mechanism
+ * - Only pointer ID 0 is tracked to avoid multi-touch issues
+ * - The component stores the previous `pointer-events` value and restores it on disable
+ * - Raycasts are performed on both `pointerdown` and `pointermove` events
+ *
+ * **Troubleshooting:**
+ * - Ensure your canvas has a transparent background if you want to see HTML beneath
+ * - Make sure 3D objects have colliders or are raycastable
+ * - If clicks aren't passing through, check that no invisible objects are blocking raycasts
+ * - HTML elements must be properly positioned (z-index) behind the canvas
+ *
+ * **Live Example:**
+ * - [3D Over HTML Sample on Stackblitz](https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html)
+ *
+ * @see {@link Context.input} - The input system used for pointer event detection
+ * @see {@link Context.physics.raycast} - Used to detect 3D object hits
+ * @see {@link ObjectRaycaster} - Controls which objects are raycastable
+ * @see {@link PointerEvents} - For more complex pointer interaction handling
+ * @see {@link NEPointerEvent} - The pointer event type used internally
+ *
+ * @summary Enables pointer events to pass through canvas to HTML elements behind it
  * @category Web
  * @group Components
  * @component

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

@@ -1 +1 @@
-{"version":3,"file":"Clickthrough.js","sourceRoot":"","sources":["../../../src/engine-components/web/Clickthrough.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Clickthrough.js","sourceRoot":"","sources":["../../../src/engine-components/web/Clickthrough.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAGhC,OAAO,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,+GAA+G;AAC/G,OAAO,CAAC,GAAG,CAAC,EAAE;IACV,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAC9D,IAAI,mBAAmB,CAAC,SAAS,CAAC,EAAE;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QAClD,0BAA0B,CAAC,GAAG,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,EAAE;YAC5D,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;KACN;IAED,SAAS,mBAAmB,CAAC,GAAkB;QAC3C,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,OAAO,CAAC;IAC1D,CAAC;AACL,CAAC,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2HG;AACH,MAAM,OAAO,YAAa,SAAQ,SAAS;IAE/B,sBAAsB,GAAW,KAAK,CAAC;IAE/C,QAAQ;QACJ,mDAAmD;QACnD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACxE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE;YACpE,KAAK,EAAE,GAAG;SACb,CAAC,CAAC;QACH,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,aAAa,CAAC;IAC9E,CAAC;IACD,SAAS;QACL,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3E,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3E,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAC5D,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,sBAAsB,CAAC;IAC9E,CAAC;IACD,cAAc;QACV,gDAAgD;IACpD,CAAC;IAEO,cAAc,GAAG,CAAC,GAAmB,EAAE,EAAE;QAC7C,IAAI,GAAG,CAAC,SAAS,GAAG,CAAC;YAAE,OAAO;QAC9B,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;QACxC,2LAA2L;QAC3L,IAAI,aAAa,EAAE,MAAM,IAAI,CAAC,EAAE;YAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,aAAa,GAAG,MAAM,CAAC;SACxD;aAAM;YACH,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC;SACvD;IACL,CAAC,CAAC;IAIF,qBAAqB;IAEb,oBAAoB,GAAG,KAAK,CAAC;IAE7B,YAAY,GAAG,CAAC,IAAgB,EAAE,EAAE;QAExC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1D,yBAAyB;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;YACtC,WAAW,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC;SACrC,CAAC,CAAA;QACF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;YACjB,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;SACpC;IACL,CAAC,CAAA;IAEO,UAAU,GAAG,CAAC,IAAgB,EAAE,EAAE;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,oBAAoB,CAAC;QAC1C,IAAI,CAAC,oBAAoB,GAAG,KAAK,CAAC;QAClC,UAAU,CAAC,GAAG,EAAE;YACZ,IAAI,OAAO;gBAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC;QACrE,CAAC,EAAE,GAAG,CAAC,CAAC;IACZ,CAAC,CAAA;CACJ"}

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":"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"}