@needle-tools/engine 4.13.0 → 4.13.1

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

@@ -13,24 +13,85 @@ import { Behaviour } from "../Component.js";
 const debugParam = getParam("debugviewbox");
 const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
 
+/**
+ * Defines how the {@link ViewBox} component applies camera framing adjustments.
+ *
+ * - `"continuous"`: Camera framing is continuously updated while the ViewBox is active. Use for animated or dynamic ViewBoxes.
+ * - `"once"`: Camera framing is applied once when the ViewBox becomes active, then updates stop. Use for initial framing with subsequent user control.
+ */
 export type ViewBoxMode = "continuous" | "once";
 
 /**
- * This component can be used to automatically fit a certain box area into the camera view - no matter your screen size or aspect ratio.  
- * This is useful for example to frame a character or object in the center of the screen and ensure it is always fully visible. You can also animate or scale the viewbox to create zoom or framing effects.
+ * [ViewBox](https://engine.needle.tools/docs/api/ViewBox) automatically fits a defined box area into the camera view regardless of screen size or aspect ratio.  
+ * This component is useful for framing characters, objects, or scenes in the center of the view while ensuring they remain fully visible.  
+ * You can animate or scale the viewbox to create dynamic zoom effects, cinematic transitions, or responsive framing.  
  * 
+ * [![](https://cloud.needle.tools/-/media/Thy6svVftsIC6Z_wIxUJMA.gif)](https://engine.needle.tools/samples/bike-scrollytelling-responsive-3d)
+ *
+ * The ViewBox component works by adjusting the camera's focus rect settings (offset and zoom) to ensure that the box defined by the
+ * GameObject's position, rotation, and scale fits perfectly within the visible viewport. It supports different modes for one-time
+ * fitting or continuous adjustment, making it versatile for both static compositions and animated sequences.
+ *
+ * **Key Features:**
+ * - Automatically adjusts camera framing to fit the box area
+ * - Works with any screen size and aspect ratio
+ * - Supports one-time fitting or continuous updates
+ * - Can be animated for dynamic zoom and framing effects
+ * - Multiple ViewBoxes can be active, with the most recently enabled taking priority
+ * - Handles camera positioning to ensure the box is visible (moves camera if inside the box)
+ *
+ * **Common Use Cases:**
+ * - Character framing in cutscenes or dialogue
+ * - Product showcases with guaranteed visibility
+ * - Scrollytelling experiences with animated camera movements
+ * - Responsive layouts that adapt to different screen sizes
+ * - UI-driven camera transitions
+ *
  * - [Example on needle.run](https://viewbox-demo-z23hmxbz2gkayo-z1nyzm6.needle.run/)
- * - [Scrollytelling Demo using animated Viewbox](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)   
+ * - [Scrollytelling Demo using animated Viewbox](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/)
  * - [Example on Stackblitz](https://stackblitz.com/edit/needle-engine-view-box-example)
- * 
- * @example Add a Viewbox component to an object in your scene
+ *
+ * @example Basic setup - Add a ViewBox component to frame an object
+ * ```ts
+ * const viewBox = new Object3D();
+ * viewBox.position.set(0, 1, 0); // Position the viewbox center
+ * viewBox.scale.set(2, 2, 2);    // Define the box size
+ * viewBox.addComponent(ViewBox, { debug: true });
+ * scene.add(viewBox);
+ * ```
+ *
+ * @example Animated ViewBox for zoom effects
+ * ```ts
+ * const viewBox = new Object3D();
+ * viewBox.addComponent(ViewBox, { mode: "continuous" });
+ * scene.add(viewBox);
+ *
+ * // Animate the viewbox scale over time
+ * function update() {
+ *   const scale = 1 + Math.sin(Date.now() * 0.001) * 0.5;
+ *   viewBox.scale.setScalar(scale);
+ * }
+ * ```
+ *
+ * @example One-time fitting with user control afterwards
  * ```ts
-  const viewBox = new Object3D();
-  viewBox.scale.set(0, 0, 0);
-  viewBox.addComponent(ViewBox, { debug: true });
-  scene.add(viewBox);
+ * const viewBox = new Object3D();
+ * viewBox.addComponent(ViewBox, {
+ *   mode: "once", // Fit once, then allow free camera control
+ *   referenceFieldOfView: 60
+ * });
+ * scene.add(viewBox);
  * ```
-  
+ *
+ * @see {@link Camera} - The camera component that ViewBox controls
+ * @see {@link OrbitControls} - Camera controls that work alongside ViewBox
+ * @see {@link DragControls} - Alternative camera controls compatible with ViewBox
+ * @see {@link LookAtConstraint} - Another way to control camera targeting
+ * @see {@link SceneSwitcher} - Can be combined with ViewBox for scene transitions
+ * @see {@link Context.setCameraFocusRect} - The underlying focus rect API used by ViewBox
+ * @see {@link Context.focusRectSettings} - Manual control of focus rect settings
+ * @see {@link ViewBoxMode} - The mode type for controlling ViewBox behavior
+ *
  * @summary Automatically fits a box area into the camera view
  * @category Camera and Controls
  * @group Components
@@ -40,22 +101,50 @@ export type ViewBoxMode = "continuous" | "once";
 export class ViewBox extends Behaviour {
 
     /**
-     * All active ViewBox instances. The last one in the array is the currently active one.
+     * Array of all active ViewBox instances in the scene.
+     * When multiple ViewBoxes are enabled, the last one in the array (most recently enabled) takes priority and controls the camera.
+     * Other ViewBoxes remain registered but inactive, displayed with a dimmed gizmo color when debug visualization is enabled.
      */
     static readonly instances: ViewBox[] = [];
 
     /**
-     * The reference field of view is used to calculate the box size. This should usually be the same as your camera's fov.
-     * @default -1 (meaning it will use the camera fov on the first frame)
+     * The reference field of view (in degrees) used to calculate how the box should fit within the camera view.
+     * This determines the baseline camera FOV for fitting calculations.
+     *
+     * **Behavior:**
+     * - If set to `-1` (default), the component will automatically use the camera's FOV on the first frame
+     * - Should typically match your camera's FOV for predictable framing
+     * - Can be set to a different value to create specific framing effects
+     *
+     * **Example:**
+     * If your camera has an FOV of 60° and you set `referenceFieldOfView` to 60, the ViewBox will fit objects
+     * as they would appear with that field of view. Setting it to a wider FOV (e.g., 90) makes objects appear
+     * smaller, while a narrower FOV (e.g., 30) makes them appear larger.
+     *
+     * @see {@link Camera} for the camera component and its FOV property
+     * @default -1 (automatically uses the camera's FOV on the first frame)
      */
     @serializable()
     referenceFieldOfView: number = -1;
 
     /**
-     * The mode determines if the viewbox should be applied once or continuously while it is the active viewbox.  
-     * Options:
-     * - "once": The viewbox will be applied once when it becomes the active viewbox. This is useful if you want to fit the view once and then allow the user to zoom or pan freely.
-     * - "continuous": The viewbox will be applied continuously while it is the active viewbox. This is useful if you animate or scale the viewbox over time.
+     * Controls how the ViewBox applies camera adjustments.
+     *
+     * **Modes:**
+     * - `"once"`: Applies the framing adjustment once when the ViewBox becomes active, then stops updating.
+     *   This is ideal when you want to frame the view initially but allow users to freely zoom, pan, or orbit afterwards.
+     *   Perfect for interactive scenes where you want a good starting view but full user control.
+     *
+     * - `"continuous"`: Continuously updates the camera framing while this ViewBox is active.
+     *   Use this when animating or scaling the ViewBox over time, or when you need the framing to constantly adjust.
+     *   Great for cutscenes, scrollytelling, or any scenario with animated ViewBoxes.
+     *
+     * **Example Use Cases:**
+     * - Set to `"once"` for: Initial scene framing, product showcases where users explore freely after initial framing
+     * - Set to `"continuous"` for: Animated zoom effects, scrollytelling sequences, dynamic camera movements tied to ViewBox transforms
+     *
+     * @see {@link ViewBoxMode} for the type definition
+     * @default "continuous"
     */
     @serializable()
     get mode() { return this._mode; }
@@ -68,7 +157,18 @@ export class ViewBox extends Behaviour {
     private _mode: ViewBoxMode = "continuous";
 
     /**
-     * Enable debug logs and rendering for this component instance
+     * Enables debug visualization and logging for this ViewBox instance.
+     *
+     * **When enabled, you will see:**
+     * - A yellow wireframe box showing the active ViewBox bounds in 3D space
+     * - Gray wireframe boxes for inactive ViewBox instances
+     * - A red dashed outline on screen showing the projected box in 2D (when using `?debugviewbox` URL parameter)
+     * - Console logs for mode changes, FOV settings, and camera adjustments
+     *
+     * **Tip:** You can also enable debug visualization globally for all ViewBoxes by adding `?debugviewbox` to your URL.
+     *
+     * @see {@link Gizmos} for the gizmo rendering system used for debug visualization
+     * @default false
      */
     @serializable()
     debug: boolean = false;

package/src/engine-components/webxr/TeleportTarget.ts

@@ -1,12 +1,31 @@
 import { Behaviour } from "../Component.js";
 import type { XRControllerMovement } from "./controllers/XRControllerMovement.js";
 
-/** 
- * This component is just used as a marker on objects for WebXR teleportation  
- * The {@link XRControllerMovement} component can be configured to check if the TeleportTarget component is present on an object to allow teleporting to that object.
- * 
+/**
+ * Marks a GameObject as a valid teleportation target for VR locomotion.  
+ * Add this component to objects or surfaces where users should be able to teleport.  
+ *
+ * **Usage:**  
+ * - Add to floor surfaces, platforms, or designated teleport spots
+ * - Works with {@link XRControllerMovement} component's teleport system
+ * - Can be used to restrict teleportation to specific areas
+ *
+ * **Setup:**
+ * 1. Add this component to GameObjects that should be teleport destinations
+ * 2. Configure {@link XRControllerMovement} to use teleport targets (optional)
+ * 3. Test teleportation in VR mode
+ *
+ * @example
+ * ```ts
+ * // Make a platform teleportable
+ * const platform = myPlatform.addComponent(TeleportTarget);
+ * ```
+ *
+ * @summary Marker component for valid VR teleportation destinations
  * @category XR
  * @group Components
+ * @see {@link XRControllerMovement} for VR locomotion and teleport configuration
+ * @see {@link WebXR} for general WebXR setup
  */
 export class TeleportTarget extends Behaviour {
 

package/src/engine-components/webxr/WebXR.ts

@@ -23,12 +23,13 @@ const debug = getParam("debugwebxr");
 const debugQuicklook = getParam("debugusdz");
 
 /**
- * Use the WebXR component to enable VR and AR on iOS and Android in your scene. VisionOS support is also provided via QuickLook USDZ export.  
+ * Use the WebXR component to enable VR and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.  
  * 
- * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
+ * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.  
  * 
- * - Example: https://samples.needle.tools/collaborative-sandbox
+ * ![](https://cloud.needle.tools/-/media/gcj_YoSns8FivafQRiCiOQ.gif)
  * 
+ *
  * @example Enable VR and AR support using code
  * ```ts
  * import { onStart, WebXR } from "@needle-tools/engine";
@@ -54,6 +55,13 @@ const debugQuicklook = getParam("debugusdz");
  * @summary WebXR Component for VR and AR support
  * @category XR
  * @group Components
+ * @see {@link NeedleXRSession} for low-level XR API
+ * @see {@link XRControllerMovement} for VR locomotion
+ * @see {@link WebARSessionRoot} for AR session configuration
+ * @see {@link Avatar} for networked user avatars
+ * @link https://engine.needle.tools/docs/xr.html
+ * @link https://engine.needle.tools/samples/?overlay=samples&tag=xr
+ * @link https://engine.needle.tools/samples/collaborative-sandbox
  */
 export class WebXR extends Behaviour {
 

package/src/engine-components/webxr/WebXRAvatar.ts

@@ -6,32 +6,61 @@ import { XRFlag } from "./XRFlag.js";
 
 export const debug = getParam("debugavatar");
 
+/**
+ * Event arguments for avatar marker creation and destruction events
+ */
 export type AvatarMarkerEventArgs = {
+    /** The AvatarMarker component instance */
     avatarMarker: AvatarMarker;
+    /** The GameObject that contains the avatar marker */
     gameObject: Object3D;
 }
 
-/** 
- * This is used to mark an object being controlled / owned by a player   
- * This system might be refactored and moved to a more centralized place in a future version
+/**
+ * Marks a GameObject as being controlled or owned by a player in networked XR sessions.  
+ * This is used internally by the networking system to identify player-controlled objects.  
+ *
+ * **Note:** This is an internal marker class. For most use cases, use the {@link Avatar} component instead.  
+ *
+ * @summary Internal marker for player-controlled objects in networked sessions
+ * @category XR
+ * @category Networking
+ * @group Components
+ * @see {@link Avatar} for avatar setup and configuration
  */
-// We might be updating this system in the future to a centralized API (PlayerView)  
+// We might be updating this system in the future to a centralized API (PlayerView)
 // but since currently quite a few core components rely on it, we're keeping it for now
 export class AvatarMarker extends Behaviour {
 
+    /**
+     * Get an avatar marker by index from the global list of avatar markers.
+     * @param index The index in the instances array
+     * @returns The AvatarMarker at the specified index, or null if index is out of bounds
+     */
     public static getAvatar(index: number): AvatarMarker | null {
         if (index >= 0 && index < AvatarMarker.instances.length)
             return AvatarMarker.instances[index];
         return null;
     }
 
+    /** Global list of all active AvatarMarker instances */
     public static instances: AvatarMarker[] = [];
 
+    /**
+     * Subscribe to avatar marker creation events.
+     * @param cb Callback function called when a new avatar marker is created
+     * @returns The callback function (for removal)
+     */
     public static onAvatarMarkerCreated(cb: (args: AvatarMarkerEventArgs) => void): Function {
         AvatarMarker._onNewAvatarMarkerAdded.push(cb);
         return cb;
     }
 
+    /**
+     * Subscribe to avatar marker destruction events.
+     * @param cb Callback function called when an avatar marker is destroyed
+     * @returns The callback function (for removal)
+     */
     public static onAvatarMarkerDestroyed(cb: (args: AvatarMarkerEventArgs) => void): Function {
         AvatarMarker._onAvatarMarkerDestroyed.push(cb);
         return cb;
@@ -41,9 +70,12 @@ export class AvatarMarker extends Behaviour {
     private static _onAvatarMarkerDestroyed: Array<(args: AvatarMarkerEventArgs) => void> = [];
 
 
+    /** The network connection ID of the player who owns this avatar */
     public connectionId!: string;
+    /** Reference to the avatar GameObject with optional XR flags */
     public avatar?: Object3D & { flags?: XRFlag[] }
 
+    /** @internal */
     awake() {
         AvatarMarker.instances.push(this);
         if (debug)
@@ -53,6 +85,7 @@ export class AvatarMarker extends Behaviour {
             cb({ avatarMarker: this, gameObject: this.gameObject });
     }
 
+    /** @internal */
     onDestroy() {
         AvatarMarker.instances.splice(AvatarMarker.instances.indexOf(this), 1);
 
@@ -60,6 +93,10 @@ export class AvatarMarker extends Behaviour {
             cb({ avatarMarker: this, gameObject: this.gameObject });
     }
 
+    /**
+     * Check if this avatar marker represents the local player.
+     * @returns True if this avatar belongs to the local player, false otherwise
+     */
     isLocalAvatar() {
         return this.connectionId === this.context.connection.connectionId;
     }