@needle-tools/engine 4.13.0 → 4.13.1-beta

package/src/engine-components/web/Clickthrough.ts

@@ -23,16 +23,125 @@ onStart(ctx => {
 
 
 /**
- * ClickThrough component allows pointer events to "click through" the 3D canvas to HTML elements behind it.  
- * 
- * 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.  
- * 
- * 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>`).
- * 
- * - 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.
+ * [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.  
+ *
+ * ![](https://cloud.needle.tools/-/media/VeahihyjzpBWf4jHHVnrqw.gif)  
+ *
+ * **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)  
+ *
+ * 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/src/engine-components/web/CursorFollow.ts

@@ -10,11 +10,82 @@ import { Behaviour } from "../Component.js";
 const debug = getParam("debugcursor");
 
 /**
- * The CursorFollow component makes the object follow the cursor (or touch) position on screen.  
- * 
- * - 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.
- * 
- * @summary Makes the object follow the cursor 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.  
+ *
+ * ![](https://cloud.needle.tools/-/media/GDspQGC_kB85Bc9IyEtr9Q.gif)  
+ *
+ * **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,34 +96,128 @@ export 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
      */
     @serializable()
     damping: number = 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
      */
     @serializable()
     useFullPage: boolean = 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
      */
     @serializable()
     keepDistance: boolean = 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
      */
     @serializable()
     snapToSurface: boolean = false;
 
 
     private _distance: number = -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: boolean = false) {
         if (!force && (this.keepDistance && this._distance !== -1)) {
             return;

package/src/engine-components/web/HoverAnimation.ts

@@ -9,36 +9,134 @@ 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.  
- * 
- * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
- * 
- * @summary Hover Animation on Pointer Enter/Exit
+ * [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.
+ *
+ * **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)
+ *
+ * **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
  */
 @registerType
 export 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"
      */
     @serializable()
     type: ScaleClipType = "linear";
 
     /**
-     * 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
      */
     @serializable()
     duration: number = 0.1;
 
     /**
-     * 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
      */
     @serializable()
@@ -46,13 +144,44 @@ export class HoverAnimation extends Behaviour {
 
 
     /**
-     * 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)
      */
     @serializable(AnimationClip)
     hovered: AnimationClip | null = 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)
      */
     @serializable(AnimationClip)
     idle: AnimationClip | null = null;

package/src/engine-components/web/ScrollFollow.ts

@@ -33,10 +33,13 @@ type ScrollFollowEvent = {
 }
 
 /**
- * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.  
+ * The [ScrollFollow](https://engine.needle.tools/docs/api/ScrollFollow) component allows you to link the scroll position of the page (or a specific element) to one or more target objects.  
  
  * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
  * 
+ * ![](https://cloud.needle.tools/-/media/SYuH-vXxO4Jf30oU1HhjKQ.gif)  
+ * ![](https://cloud.needle.tools/-/media/RplmU_j7-xb8XHXkOzc9PA.gif)  
+ * 
  * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
  * 
  * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/