@needle-tools/engine 4.11.3 → 4.11.4

package/src/engine/engine_utils_attributes.ts

@@ -0,0 +1,72 @@
+
+
+/**
+ * @internal
+ */
+export namespace InternalAttributeUtils {
+
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    export function isFalsey(value: string | null): boolean {
+        return value === "0" || value?.toLowerCase() === "false";
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    export function getAttributeValueIfNotFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string) => void }): string | null {
+        const attrValue = element.getAttribute(attributeName);
+        if (isFalsey(attrValue)) {
+            return null;
+        }
+        opts?.onAttribute?.call(null, attrValue!);
+        return attrValue;
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     * 
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     * 
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    export function getAttributeAndCheckFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string, falsey:boolean) => void }): false | string | null {
+        const attrValue = element.getAttribute(attributeName);
+        // If the attribute is not set at all we just return
+        if(attrValue === null) {
+            return null;
+        }
+        if (isFalsey(attrValue)) {
+            opts?.onAttribute?.call(null, attrValue!, true);
+            return false;
+        }
+        opts?.onAttribute?.call(null, attrValue!, false);
+        return attrValue;
+    }
+
+}
+

package/src/engine/engine_utils_qrcode.ts

@@ -0,0 +1,266 @@
+
+// use for typesafe interface method calls
+import { Quaternion, Vector2, Vector3, Vector4 } from "three";
+
+import { needleLogoOnlySVG } from "./assets/index.js";
+import { isDevEnvironment } from "./debug/debug.js";
+import { hasCommercialLicense } from "./engine_license.js";
+import { InternalAttributeUtils } from "./engine_utils_attributes.js";
+import type { NeedleEngineWebComponent } from "./webcomponents/needle-engine.js";
+
+
+
+/** Generates a QR code HTML image using https://github.com/davidshimjs/qrcodejs
+ * @param args.text The text to encode
+ * @param args.width The width of the QR code
+ * @param args.height The height of the QR code
+ * @param args.colorDark The color of the dark squares
+ * @param args.colorLight The color of the light squares
+ * @param args.correctLevel The error correction level to use
+ * @param args.showLogo If true, the logo will be shown in the center of the QR code. By default the Needle Logo will be used. You can override which logo is being used by setting the `needle-engine` web component's `qr-logo-src` attribute. The logo can also be disabled by setting that attribute to a falsey value (e.g. "0" or "false")
+ * @param args.showUrl If true, the URL will be shown below the QR code
+ * @param args.domElement The dom element to append the QR code to. If not provided a new div will be created and returned
+ * @returns The dom element containing the QR code
+ */
+export async function generateQRCode(args: { domElement?: HTMLElement, text: string, width?: number, height?: number, colorDark?: string, colorLight?: string, correctLevel?: any, showLogo?: boolean, showUrl?: boolean }): Promise<HTMLElement> {
+
+    // Ensure that the QRCode library is loaded
+    if (!globalThis["QRCode"]) {
+        const url = "https://cdn.jsdelivr.net/gh/davidshimjs/qrcodejs@gh-pages/qrcode.min.js";
+        let script = document.head.querySelector(`script[src="${url}"]`) as HTMLScriptElement;
+        if (!script) {
+            script = document.createElement("script");
+            script.src = url;
+            document.head.appendChild(script);
+        }
+
+        await new Promise((resolve, _reject) => {
+            script.addEventListener("load", () => {
+                resolve(true);
+            });
+        });
+    }
+
+    const QRCODE = globalThis["QRCode"];
+    const target = args.domElement ?? document.createElement("div");
+    const qrCode = new QRCODE(target, {
+        width: args.width ?? 256,
+        height: args.height ?? 256,
+        colorDark: "#000000",
+        colorLight: "#ffffff",
+        correctLevel: args.showLogo ? QRCODE.CorrectionLevel.H : QRCODE.CorrectLevel.M,
+        ...args,
+    });
+
+    // Number of rows/columns of the generated QR code
+    const moduleCount = qrCode?._oQRCode.moduleCount || 0;
+    const canvas = qrCode?._oDrawing?._elCanvas as HTMLCanvasElement;
+
+    let sizePercentage = 0.25;
+    if (moduleCount < 40)
+        sizePercentage = Math.floor(moduleCount / 4) / moduleCount;
+    else
+        sizePercentage = Math.floor(moduleCount / 6) / moduleCount;
+
+    const paddingPercentage = Math.floor(moduleCount / 20) / moduleCount;
+    try {
+        const img = await internalRenderQRCodeOverlays(canvas, { showLogo: args.showLogo, logoSize: sizePercentage, logoPadding: paddingPercentage }).catch(_e => { /** ignore */ });
+        if (img) {
+            target.innerHTML = "";
+            target.append(img);
+        }
+    }
+    catch { } // Ignore
+
+    if (args.showUrl !== false && args.text) {
+        // Add link label below the QR code
+        // Clean up the text. If it's a URL: remove the protocol, www. part, trailing slashes or trailing question marks
+        const existingLabel = target.querySelector(".qr-code-link-label");
+        let displayText = args.text.replace(/^(https?:\/\/)?(www\.)?/, "").replace(/\/+$/, "").replace(/\?+$/, "");
+        displayText = "Scan to visit " + displayText;
+        if (existingLabel) {
+            existingLabel.textContent = displayText;
+        } else {
+            // Create a new label
+            const linkLabel = document.createElement("div");
+            linkLabel.classList.add("qr-code-link-label");
+            args.text = displayText;
+            linkLabel.textContent = args.text;
+            linkLabel.addEventListener("click", (ev) => {
+                // Prevent the QR panel from closing
+                ev.stopImmediatePropagation();
+            });
+
+            linkLabel.style.textAlign = "center";
+            linkLabel.style.fontSize = "0.8em";
+            linkLabel.style.marginTop = "0.1em";
+            linkLabel.style.color = "#000000";
+            linkLabel.style.fontFamily = "'Roboto Flex', sans-serif";
+            linkLabel.style.opacity = "0.5";
+            linkLabel.style.wordBreak = "break-all";
+            linkLabel.style.wordWrap = "break-word";
+            linkLabel.style.marginBottom = "0.3em";
+
+            // Ensure max. width
+            target.style.width = "calc(210px + 20px)";
+
+            target.appendChild(linkLabel);
+        }
+    }
+
+    return target;
+}
+
+
+async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean, logoSize?: number, logoPadding?: number }): Promise<HTMLImageElement | void> {
+    if (!canvas) return;
+
+    // Internal settings
+    const canvasPadding = 8;
+    const shadowBlur = 20;
+    const rectanglePadding = args.logoPadding || 1. / 32;
+    // With dropshadow under the logo
+    /*
+    const shadowColor = "#00000099";
+    const rectangleRadius = 0.4 * 16;
+    */
+    // Without dropshadow under the logo
+    const shadowColor = "transparent";
+    const rectangleRadius = 0;
+
+    // Draw the website's icon in the center of the QR code
+    const image = new Image();
+    const element = document.querySelector("needle-engine") as NeedleEngineWebComponent;
+    if (!element) {
+        console.debug("[QR Code] No web component found")
+    }
+
+    const canUseCustomLogo = hasCommercialLicense();
+
+    // Query logo src from needle-engine attribute.
+    // For any supported attribute it's possible to use "falsey" values (e.g. "0" or "false" to disable the logo in the QR code)
+    let logoSrc: false | string | null = null;
+    logoSrc = InternalAttributeUtils.getAttributeAndCheckFalsey(element, "qrcode-logo-src");
+    if (canUseCustomLogo && args.showLogo !== true && logoSrc === false) return; // Explictly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "logo-src");
+    if (canUseCustomLogo && args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "loading-logo-src", {
+        onAttribute: () => {
+            if (isDevEnvironment()) console.warn("[QR Code] 'loading-logo-src' is deprecated, please use 'logo-src' or 'qrcode-logo-src' instead.");
+            else console.debug("[QR Code] 'loading-logo-src' is deprecated.");
+        }
+    });
+    if (canUseCustomLogo && args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+
+    if (logoSrc && !canUseCustomLogo) {
+        console.warn("[QR Code] Custom logo is only available with a commercial license. Using default Needle logo. Please get a commercial license at https://needle.tools/pricing.");
+        logoSrc = null;
+    }
+
+    logoSrc ||= needleLogoOnlySVG;
+    if (!logoSrc) return;
+
+    let haveLogo = false;
+    if (args.showLogo !== false) {
+        image.src = logoSrc;
+        haveLogo = await new Promise((resolve, _reject) => {
+            image.onload = () => resolve(true);
+            image.onerror = (err) => {
+                let errorUrl = logoSrc !== needleLogoOnlySVG ? "'" + logoSrc + "'" : null;
+                console.error("[QR Code] Error loading logo image for QR code", errorUrl, isDevEnvironment() ? err : "");
+                resolve(false);
+            };
+        });
+    }
+
+    // Add some padding around the canvas – we need to copy the QR code image to a larger canvas
+    const paddedCanvas = document.createElement("canvas");
+    paddedCanvas.width = canvas.width + canvasPadding;
+    paddedCanvas.height = canvas.height + canvasPadding;
+    const paddedContext = paddedCanvas.getContext("2d");
+    if (!paddedContext) {
+        return;
+    }
+
+    // Clear with white
+    paddedContext.fillStyle = "#ffffff";
+    paddedContext.fillRect(0, 0, paddedCanvas.width, paddedCanvas.height);
+    paddedContext.drawImage(canvas, canvasPadding / 2, canvasPadding / 2);
+
+    // Enable anti-aliasing
+    paddedContext.imageSmoothingEnabled = true;
+    paddedContext.imageSmoothingQuality = "high";
+    // @ts-ignore
+    paddedContext.mozImageSmoothingEnabled = true;
+    // @ts-ignore
+    paddedContext.webkitImageSmoothingEnabled = true;
+
+    // Draw a slight gradient background with 10% opacity and "lighten" composite operation
+    paddedContext.globalCompositeOperation = "lighten";
+    const gradient = paddedContext.createLinearGradient(0, 0, 0, paddedCanvas.height);
+    gradient.addColorStop(0, "rgb(45, 45, 45)");
+    gradient.addColorStop(1, "rgb(45, 45, 45)");
+    paddedContext.fillStyle = gradient;
+    paddedContext.fillRect(0, 0, paddedCanvas.width, paddedCanvas.height);
+    paddedContext.globalCompositeOperation = "source-over";
+
+
+    let sizeX = Math.min(canvas.width, canvas.height) * (args.logoSize || 0.25);
+    let sizeY = sizeX;
+
+    if (haveLogo) {
+        // Get aspect of image
+        const aspect = image.width / image.height;
+        if (aspect > 1) sizeY = sizeX / aspect;
+        else sizeX = sizeY * aspect;
+
+        const rectanglePaddingPx = rectanglePadding * canvas.width;
+
+        // Apply padding
+        const sizeForBackground = Math.max(sizeX, sizeY);
+        const sizeXPadded = Math.round(sizeForBackground + rectanglePaddingPx);
+        const sizeYPadded = Math.round(sizeForBackground + rectanglePaddingPx);
+        const x = (paddedCanvas.width - sizeForBackground) / 2;
+        const y = (paddedCanvas.height - sizeForBackground) / 2;
+
+        // Draw shape with blurred shadow
+        paddedContext.shadowColor = shadowColor;
+        paddedContext.shadowBlur = shadowBlur;
+
+        // Draw rounded rectangle with radius
+        // Convert 0.4rem to pixels, taking DPI into account
+        const radius = rectangleRadius;
+        const xPadded = Math.round(x - rectanglePaddingPx / 2);
+        const yPadded = Math.round(y - rectanglePaddingPx / 2);
+        paddedContext.beginPath();
+        paddedContext.moveTo(xPadded + radius, yPadded);
+        paddedContext.lineTo(xPadded + sizeXPadded - radius, yPadded);
+        paddedContext.quadraticCurveTo(xPadded + sizeXPadded, yPadded, xPadded + sizeXPadded, yPadded + radius);
+        paddedContext.lineTo(xPadded + sizeXPadded, yPadded + sizeYPadded - radius);
+        paddedContext.quadraticCurveTo(xPadded + sizeXPadded, yPadded + sizeYPadded, xPadded + sizeXPadded - radius, yPadded + sizeYPadded);
+        paddedContext.lineTo(xPadded + radius, yPadded + sizeYPadded);
+        paddedContext.quadraticCurveTo(xPadded, yPadded + sizeYPadded, xPadded, yPadded + sizeYPadded - radius);
+        paddedContext.lineTo(xPadded, yPadded + radius);
+        paddedContext.quadraticCurveTo(xPadded, yPadded, xPadded + radius, yPadded);
+        paddedContext.fillStyle = "#ffffff";
+        paddedContext.closePath();
+        paddedContext.fill();
+        paddedContext.clip();
+
+        // Reset shadow and draw favicon
+        paddedContext.shadowColor = "transparent";
+        const logoX = (paddedCanvas.width - sizeX) / 2;
+        const logoY = (paddedCanvas.height - sizeY) / 2;
+        paddedContext.drawImage(image, logoX, logoY, sizeX, sizeY);
+    }
+
+    // Replace the canvas with the padded one
+    const paddedImage = paddedCanvas.toDataURL("image/png");
+    const img = document.createElement("img");
+    img.src = paddedImage;
+    img.style.width = "100%";
+    img.style.height = "auto";
+
+    return img;
+}
+

package/src/engine/webcomponents/buttons.ts

@@ -1,6 +1,6 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/debug.js";
 import { IContext } from "../engine_types.js";
-import { generateQRCode, isMobileDevice } from "../engine_utils.js";
+import { generateQRCode } from "../engine_utils_qrcode.js";
 import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { getIconElement } from "./icons.js";
 

package/src/engine-components/Animation.ts

@@ -58,7 +58,7 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject
+ * Animation component to play animations on a GameObject.
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/AnimationCurve.ts

@@ -27,7 +27,10 @@ export class Keyframe {
 }
 
 /**
- * AnimationCurve is a representation of a curve that can be used to animate values over time.  
+ * AnimationCurve is a representation of a curve that can be used to animate values over time. 
+ * 
+ * @category Animation
+ * @group Utilities 
  */
 export class AnimationCurve {
 

package/src/engine-components/Animator.ts

@@ -39,8 +39,9 @@ export declare class PlayOptions {
 
 /** 
  * The Animator component plays and manages animations on a GameObject. 
- * It works with an AnimatorController to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
+ * It works with an {@link AnimatorController} to handle state transitions and animation blending.
+ * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+ * 
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AnimatorController.ts

@@ -51,6 +51,9 @@ declare type CreateAnimatorControllerOptions = {
  * 
  * Use the static method {@link AnimatorController.createFromClips} to create
  * an animator controller from a set of animation clips.
+ * 
+ * @category Animation and Sequencing
+ * @group Utilities
  */
 export class AnimatorController {
 

package/src/engine-components/LookAtConstraint.ts

@@ -2,9 +2,14 @@ import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
+import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
+ * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
+ * This component is used by {@link OrbitControls} internally.
+ * 
+ * @category Camera Controls
+ * @group Components
  */
 export class LookAtConstraint extends Behaviour {
 

package/src/engine-components/NeedleMenu.ts

@@ -9,6 +9,7 @@ import { Behaviour } from './Component.js';
  * 
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
+ * 
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -10,6 +10,9 @@ const debug = getParam("debugnestedgltf");
 
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+ * 
+ * @category Asset Management
+ * @group Components
  */
 export class NestedGltf extends Behaviour {
 

package/src/engine-components/ReflectionProbe.ts

@@ -15,6 +15,10 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 const $originalMaterial = Symbol("original material");
 
 /**
+ * A ReflectionProbe provides reflection data to materials within its defined area.
+ * 
+ * - Sample: http://samples.needle.tools/reflection-probes
+ * 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/RendererLightmap.ts

@@ -9,9 +9,13 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
-// this component is automatically added by the Renderer if the object has lightmap uvs AND we have a lightmap
-// for multimaterial objects GLTF exports a "Group" with the renderer component
-// and every child mesh is a material from unity
+
+/**
+ * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
+ * 
+ * @category Rendering
+ * @group Components
+ */
 export class RendererLightmap {
 
     get lightmap(): Texture | null {

package/src/engine-components/SeeThrough.ts

@@ -39,6 +39,9 @@ let i = 0;
  * Requires a Renderer component on the same object or a child object.
  * 
  * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class SeeThrough extends Behaviour {
 

package/src/engine-components/Skybox.ts

@@ -120,6 +120,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/SpriteRenderer.ts

@@ -9,6 +9,9 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugspriterenderer");
 const showWireframe = getParam("wireframe");
 
+/**
+ * @internal
+ */
 class SpriteUtils {
 
     static cache: { [key: string]: BufferGeometry } = {};
@@ -82,7 +85,7 @@ function updateTextureIfNecessary(tex: Texture) {
 }
 
 /**
- * A sprite is a mesh that represents a 2D image
+ * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
  * @category Rendering
  * @group Components
  */
@@ -152,6 +155,9 @@ export class Sprite {
 
 const $spriteTexOwner = Symbol("spriteOwner");
 
+/**
+ * @category Sprites
+ */
 export class SpriteSheet {
 
     @serializable(Sprite)
@@ -162,6 +168,11 @@ export class SpriteSheet {
     }
 }
 
+/**
+ * Used by the {@link SpriteRenderer} to hold the sprite sheet and the currently active sprite index.
+ * 
+ * @category Sprites
+ */
 export class SpriteData {
 
     static create() {
@@ -246,7 +257,12 @@ export class SpriteData {
 }
 
 /**
- * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).  
+ * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).   
+ * 
+ * - Example: https://engine.needle.tools/samples/spritesheet-animation
+ * 
+ * @category Sprites
+ * @group Components
  */
 export class SpriteRenderer extends Behaviour {
 

package/src/engine-components/splines/Spline.ts

@@ -36,6 +36,9 @@ export class SplineData {
  * The spline is defined by an array of knots (SplineData) which define position, rotation and tangents.  
  * 
  * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineContainer extends Behaviour {
 

package/src/engine-components/splines/SplineUtils.ts

@@ -3,7 +3,9 @@ import { Vector3 } from "three";
 import { Mathf } from "../../engine/engine_math.js";
 import { SplineContainer, SplineData } from "./Spline.js";
 
-
+/**
+ * @category Splines
+ */
 export namespace SplineUtils {
 
     /**

package/src/engine-components/splines/SplineWalker.ts

@@ -11,6 +11,9 @@ import { SplineContainer } from "./Spline.js";
  * Use this with a SplineContainer component.
  * 
  * - Example http://samples.needle.tools/splines
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineWalker extends Behaviour {
 

package/src/engine-components/timeline/SignalAsset.ts

@@ -2,15 +2,23 @@ import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
+import type { PlayableDirector } from "./PlayableDirector.js";
 
 const debug = getParam("debugsignals")
 
 
+/**
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ */
 export class SignalAsset {
     @serializable()
     guid!: string;
 }
 
+/**
+ * An event that links a signal to a reaction.
+ * Used internally by {@link SignalReceiver}.
+ */
 export class SignalReceiverEvent {
     @serializable(SignalAsset)
     signal!: SignalAsset;
@@ -19,7 +27,10 @@ export class SignalReceiverEvent {
 }
 
 /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. 
- * Signals can be added to a signal track on a timeline
+ * Signals can be added to a signal track on a {@link PlayableDirector}
+ * 
+ * @category Sequencing and Timelines
+ * @group Components
  */
 export class SignalReceiver extends Behaviour {
 
@@ -41,7 +52,7 @@ export class SignalReceiver extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if(debug) console.log("SignalReceiver awake", this);
+        if (debug) console.log("SignalReceiver awake", this);
     }
 
     /** @internal */

package/src/engine-components/ui/Raycaster.ts

@@ -28,6 +28,12 @@ export abstract class Raycaster extends Behaviour {
 }
 
 
+/**
+ * A Raycaster that performs raycasting against its own GameObject.  
+ * 
+ * @category Interaction
+ * @group Components
+ */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
     private raycastHits: Intersection[] = [];
@@ -65,6 +71,13 @@ export class ObjectRaycaster extends Raycaster {
     }
 }
 
+
+/**
+ * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
+ * 
+ * @category UI
+ * @group Components
+ */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
     // ignoreReversedGraphics: boolean = false;
@@ -76,6 +89,12 @@ export class GraphicRaycaster extends ObjectRaycaster {
     }
 }
 
+/**
+ * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
+ * 
+ * @category XR
+ * @group Components
+ */
 export class SpatialGrabRaycaster extends Raycaster {
 
     /**