@needle-tools/engine 4.12.0-next.dd87659 → 4.12.0-next.f0b1535

package/src/engine/engine_utils.ts

@@ -606,7 +606,8 @@ export namespace DeviceUtilities {
     /** @returns `true` if we're currently on an iPad */
     export function isiPad() {
         if (__isiPad !== undefined) return __isiPad;
-        return __isiPad = /iPad/.test(navigator.userAgent);
+        const userAgent = navigator.userAgent.toLowerCase();
+        return __isiPad = /iPad/.test(navigator.userAgent) || userAgent.includes("macintosh") && "ontouchend" in document;
     }
 
     let __isAndroidDevice: boolean | undefined;
@@ -623,17 +624,25 @@ export namespace DeviceUtilities {
         return __isMozillaXR = /WebXRViewer\//i.test(navigator.userAgent);
     }
 
+    let __isNeedleAppClip: boolean | undefined;
+    /** @returns `true` if we're currently in the Needle App Clip */
+    export function isNeedleAppClip() {
+        if (__isNeedleAppClip !== undefined) return __isNeedleAppClip;
+        return __isNeedleAppClip = /NeedleAppClip\//i.test(navigator.userAgent);
+    }
+
     let __isMacOS: boolean | undefined;
     // https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgentData
     /** @returns `true` for MacOS devices */
     export function isMacOS() {
         if (__isMacOS !== undefined) return __isMacOS;
+        if (isiOS() || isiPad()) return __isMacOS = false;
+        const userAgent = navigator.userAgent.toLowerCase();
         if (navigator.userAgentData) {
             // Use modern UA Client Hints API if available
             return __isMacOS = navigator.userAgentData.platform === 'macOS';
         } else {
             // Fallback to user agent string parsing
-            const userAgent = navigator.userAgent.toLowerCase();
             return __isMacOS = userAgent.includes('mac os x') || userAgent.includes('macintosh');
         }
     }
@@ -642,13 +651,13 @@ export namespace DeviceUtilities {
     /** @returns `true` for VisionOS devices */
     export function isVisionOS() {
         if (__isVisionOS !== undefined) return __isVisionOS;
-        return __isVisionOS = (isMacOS() && "xr" in navigator);
+        return __isVisionOS = (isiPad() && "xr" in navigator && supportsQuickLookAR());
     }
 
     let __isiOS: boolean | undefined;
     const iosDevices = ['iPad Simulator', 'iPhone Simulator', 'iPod Simulator', 'iPad', 'iPhone', 'iPod'];
 
-    /** @returns `true` for iOS devices like iPad, iPhone, iPod... */
+    /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
     export function isiOS() {
         if (__isiOS !== undefined) return __isiOS;
         // eslint-disable-next-line deprecation/deprecation
@@ -725,6 +734,16 @@ export namespace DeviceUtilities {
         else __chromeVersion = null;
         return __chromeVersion;
     }
+
+    let __safariVersion: string | null | undefined;
+    export function getSafariVersion() {
+        if (__safariVersion !== undefined) return __safariVersion;
+        const match = navigator.userAgent.match(/Version\/(\d+\.\d+)/);
+        if (match && isSafari()) {
+            __safariVersion = match[1];
+        } else __safariVersion = null;
+        return __safariVersion;
+    }
 }
 
 /**

package/src/engine/extensions/extensions.ts

@@ -30,20 +30,44 @@ const KHR_ANIMATIONPOINTER_IMPORT = import("@needle-tools/three-animation-pointe
 });
 
 
-declare type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
-declare type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
+/**
+ * Callback type for glTF import plugins. See {@link INeedleGLTFExtensionPlugin.onImport}
+ */
+export type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
+
+/**
+ * Callback type for glTF export plugins. See {@link INeedleGLTFExtensionPlugin.onExport}
+ */
+export type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
 
 /**
- * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders. Register your plugin via {@link addCustomExtensionPlugin}
+ * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders.   
+ * Register your plugin using the {@link addCustomExtensionPlugin} method
  */
 export interface INeedleGLTFExtensionPlugin {
     /** The Name of your plugin */
     name: string;
-    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the GLTFLoader */
+    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the [GLTFLoader](https://threejs.org/docs/#GLTFLoader.register)  
+     * 
+     * @example Add a custom extension to the GLTFloader
+     * ```ts
+     * onImport: (loader, url, context) => {
+     *    loader.register((parser) => new MyCustomExtension(parser));
+     * }
+     * ```
+     */
     onImport?: OnImportCallback;
-    /** Called after the glTF has been loaded */
+    /** Called after a glTF file has been loaded */
     onLoaded?: (url: string, gltf: GLTF, context: Context) => void;
-    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the GLTFExporter */
+    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the [GLTFExporter](https://threejs.org/docs/#examples/en/exporters/GLTFExporter.register) 
+     * 
+     * @example Add a custom extension to the GLTFExporter
+     * ```ts
+     * onExport: (exporter, context) => {
+     *    exporter.register((writer) => new MyCustomExportExtension(writer));
+     * }
+     * 
+    */
     onExport?: OnExportCallback;
 }
 

package/src/engine/webcomponents/WebXRButtons.ts

@@ -57,13 +57,16 @@ export class WebXRButtonFactory {
         this._quicklookButton = button;
         button.dataset["needle"] = "quicklook-button";
         const supportsQuickLook = DeviceUtilities.supportsQuickLookAR();
+        let buttonText = "View in AR";
         // we can immediately enter this scene, because the platform supports rel="ar" links
-        if (supportsQuickLook) {
-            button.innerText = "View in AR";
+        if (DeviceUtilities.isVisionOS()) {
+            buttonText = "View in AR";
         }
-        else {
-            button.innerText = "View in AR";
+        else if (supportsQuickLook || DeviceUtilities.isiOS()) {
+            buttonText = "Open in Quicklook";
         }
+
+        button.innerText = buttonText;
         button.prepend(getIconElement("view_in_ar"));
 
         let createdExporter = false;
@@ -209,13 +212,20 @@ export class WebXRButtonFactory {
     }
 
     private updateSessionSupported(button: HTMLButtonElement, mode: XRSessionMode) {
+        if (mode === "immersive-ar" && DeviceUtilities.isiOS() && !DeviceUtilities.isVisionOS()) {
+            // on iOS, we can forward to the AppClip experience from the same button,
+            // so we always show the button. No AppClip support on VisionOS for now, so
+            // button state depends on WebXR support there.
+            return;
+        }
+
         if (!("xr" in navigator)) {
             button.style.display = "none";
             return;
         }
         NeedleXRSession.isSessionSupported(mode).then(supported => {
             button.style.display = !supported ? "none" : "";
-            if (isDevEnvironment() && !supported) console.log("[WebXR] \"" + mode + "\" is not supported on this device – make sure your server runs using HTTPS and you have a device connected that supports " + mode);
+            if (isDevEnvironment() && !supported) console.log("[WebXR] \"" + mode + "\" is not supported on this device. Make sure your server runs using HTTPS and you have a device connected that supports " + mode);
         });
     }
 

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -601,16 +601,15 @@ export class NeedleMenuElement extends HTMLElement {
             bottom: calc(100% + 5px);
             z-index: 100;
             width: auto;
-            left: .2rem;
-            right: .2rem;
-            padding: .2rem;
+            max-width: 90vw;
+            left: 50%;
+            transform: translateX(-50%);
+            padding: .2rem 1em;
 
         }
         .compact.logo-hidden .foldout {
             /** for when there's no logo we want to center the foldout **/
             min-width: 24ch;
-            margin-left: 50%;
-            transform: translateX(calc(-50% - .2rem));
         }
         
         .compact.top .foldout {

package/src/engine/webcomponents/needle-engine.ar-overlay.ts

@@ -118,6 +118,12 @@ export class AROverlayHandler {
     }
 
     private ensureQuitARButton(element: HTMLElement) {
+
+        // No quit button in app clips, we provide one via the native UI
+        if (DeviceUtilities.isNeedleAppClip()) {
+            return;
+        }
+
         const quitARSlot = document.createElement("slot");
         quitARSlot.setAttribute("name", "quit-ar");
         this.appendElement(quitARSlot, element);

package/src/engine/webcomponents/needle-engine.ts

@@ -356,7 +356,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "loadfinished":
                 if (typeof newValue === "string" && newValue.length > 0) {
                     if (debug) console.log(name + " attribute changed", newValue);
-                    this.registerEventFromAttribute("loadfinished", newValue);
+                    this.registerEventFromAttribute(name, newValue);
                 }
                 break;
             case "dracoDecoderPath":
@@ -708,7 +708,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (attributeValue)
             this.registerEventFromAttribute("loadstart", attributeValue);
     }
-    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart', code: string) {
+    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart' | 'progress', code: string) {
         const prev = this._previouslyRegisteredMap.get(eventName);
         if (prev) {
             this._previouslyRegisteredMap.delete(eventName);

package/src/engine/xr/NeedleXRSession.ts

@@ -82,6 +82,34 @@ function getDOMOverlayElement(domElement: HTMLElement) {
 handleSessionGranted();
 async function handleSessionGranted() {
 
+    // await delay(400);
+
+
+    let defaultMode: XRSessionMode = "immersive-vr";
+
+    try {
+        // In app clips we default to AR
+        if (DeviceUtilities.isNeedleAppClip()) {
+            defaultMode = "immersive-ar";
+        }
+        // Check if VR is even supported, otherwise try AR
+        else if (!(await navigator.xr?.isSessionSupported("immersive-vr"))) {
+            defaultMode = "immersive-ar";
+        }
+        // Check if AR is supported, otherwise we can't do anything
+        if (!(await navigator.xr?.isSessionSupported("immersive-ar")) && defaultMode === "immersive-ar") {
+            console.warn("[NeedleXRSession:granted] Neither VR nor AR supported, aborting session start.");
+            // showBalloonMessage("NeidleXRSession: Neither VR nor AR supported, aborting session start.");
+            return;
+        }
+    } catch (e) {
+        console.error("[NeedleXRSession:granted] Error while checking XR support:", e);
+        // showBalloonWarning("NeedleXRSession: Error while checking XR support: " + (e as Error).message);
+        return;
+    }
+
+    // showBalloonMessage("sessiongranted: " + defaultMode);
+
     // TODO: asap session granted doesnt handle the pre-room yet
     if (getParam("debugasap")) {
         let asapSession = globalThis["needle:XRSession"] as XRSession | undefined | Promise<XRSession>;
@@ -94,11 +122,11 @@ async function handleSessionGranted() {
                 enableSpatialConsole(true);
                 const session = await asapSession;
                 if (session) {
-                    const sessionInit = NeedleXRSession.getDefaultSessionInit("immersive-vr");
-                    NeedleXRSession.setSession("immersive-vr", session, sessionInit, cb.context);
+                    const sessionInit = NeedleXRSession.getDefaultSessionInit(defaultMode);
+                    NeedleXRSession.setSession(defaultMode, session, sessionInit, cb.context);
                 }
                 else {
-                    console.error("NeedleXRSession: ASAP session was rejected");
+                    console.error("[NeedleXRSession:granted] ASAP session was rejected");
                 }
                 asapSession = undefined;
             });
@@ -106,6 +134,9 @@ async function handleSessionGranted() {
         }
     }
 
+    // console.log("Attaching sessiongranted handler...", { haveXR: 'xr' in navigator });
+    // setTimeout(() => console.log("Session Granted handler attached.", { haveXR: 'xr' in navigator }), 1000);
+
     if ('xr' in navigator) {
         // WebXRViewer (based on Firefox) has a bug where addEventListener
         // throws a silent exception and aborts execution entirely.
@@ -115,10 +146,7 @@ async function handleSessionGranted() {
         }
 
         navigator.xr?.addEventListener('sessiongranted', async () => {
-            enableSpatialConsole(true);
-
-            console.log("Received Session Granted...")
-            await delay(100);
+            // enableSpatialConsole(true);
 
             const lastSessionMode = sessionStorage.getItem("needle_xr_session_mode") as XRSessionMode;
             const lastSessionInit = sessionStorage.getItem("needle_xr_session_init") ?? null;
@@ -126,7 +154,8 @@ async function handleSessionGranted() {
 
             let info: SessionInfo | null = null;
             if (contextIsLoading()) {
-                await TemporaryXRContext.start(lastSessionMode || "immersive-vr", init || NeedleXRSession.getDefaultSessionInit("immersive-vr"));
+                await TemporaryXRContext.start(lastSessionMode || defaultMode, init || NeedleXRSession.getDefaultSessionInit(defaultMode))
+                    .catch(e => console.warn("[NeedleXRSession:granted] TemporaryXRContext start failed:", e));
                 await waitForContextLoadingFinished();
                 info = await TemporaryXRContext.handoff();
             }
@@ -134,17 +163,19 @@ async function handleSessionGranted() {
                 NeedleXRSession.setSession(info.mode, info.session, info.init, Context.Current);
             }
             else if (lastSessionMode && lastSessionInit) {
-                console.log("Session Granted: Restore last session")
+                console.log("[NeedleXRSession:granted] Restore last session")
                 const init = JSON.parse(lastSessionInit);
                 NeedleXRSession.start(lastSessionMode as XRSessionMode, init).catch(e => console.warn(e));
             }
             else {
                 // if no session was found we start VR by default
-                NeedleXRSession.start("immersive-vr").catch(e => console.warn("Session Granted failed:", e));
+                NeedleXRSession.start(defaultMode).catch(e => console.warn("[NeedleXRSession:granted] failed:", e));
             }
             // make sure we only subscribe to the event once
         }, { once: true });
-
+    }
+    else {
+        // showBalloonWarning("NeedleXRSession: WebXR not available in this browser.");
     }
 }
 function saveSessionInfo(mode: XRSessionMode, init: XRSessionInit) {
@@ -419,28 +450,48 @@ export class NeedleXRSession implements INeedleXRSession {
      * @param init The XRSessionInit to use (optional), docs: https://developer.mozilla.org/en-US/docs/Web/API/XRSessionInit
      * @param context The Needle Engine context to use
      */
-    static async start(mode: XRSessionMode | "ar", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null> {
+    static async start(mode: XRSessionMode | "ar" | "quicklook", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null> {
 
-        // handle iOS platform where "immersive-ar" is not supported
+        // handle iOS platform where "immersive-ar" is special:
+        // - we either launch QuickLook
+        // - or forward to the Needle App Clip experience for WebXR AR
         // TODO: should we add a separate mode (e.g. "AR")? https://linear.app/needle/issue/NE-5303
         if (DeviceUtilities.isiOS()) {
-            if (mode === "ar") {
-                const arSupported = await this.isARSupported();
-                if (!arSupported) {
-                    InternalUSDZRegistry.exportAndOpen();
-                    return null;
-                }
-                else {
-                    mode = "immersive-ar";
-                }
+
+            const arSupported = await this.isARSupported().catch(() => false);
+            
+            // On VisionOS, we use QuickLook for AR experiences; no AppClip support for now.
+            if (DeviceUtilities.isVisionOS() && !arSupported && (mode === "ar" || mode === "immersive-ar")) {
+                mode = "quicklook";
+            }
+
+            if (mode === "quicklook") {
+                InternalUSDZRegistry.exportAndOpen();
+                return null;
             }
+            
+            if (!arSupported && (mode === "immersive-ar" || mode === "ar")) {
+                // Forward to the AppClip experience
+                // const url = `https://appclip.apple.com/id?p=tools.needle.launch-app.Clip&url=${encodeURIComponent(location.href)}` 
+                const url =`https://appclip.needle.tools/ar?url=${encodeURIComponent(location.href)}`;
+                console.debug("iOS device detected - opening Needle App Clip for AR experience", url, { mode, init });
+                // navigate to app clip url but keep the current url in history, open in same tab
+                window.location.href = url;
+
+                return null;
+            }
+        }
+
+        if (mode === "quicklook") {
+            console.warn("QuickLook mode is only supported on iOS devices");
+            return null;
         }
-        else if (mode == "ar") {
+        
+        // Since we now know we are not on iOS, ar mode becomes "immersive-ar"
+        if (mode == "ar") {
             mode = "immersive-ar";
         }
 
-
-
         if (isDevEnvironment() && getParam("debugxrpreroom")) {
             console.warn("Debug: Starting temporary XR session");
             await TemporaryXRContext.start(mode, init || NeedleXRSession.getDefaultSessionInit(mode));
@@ -539,8 +590,8 @@ export class NeedleXRSession implements INeedleXRSession {
         this._currentSessionRequestMode = mode;
         /**@type {XRSystem} */
         const newSession = await (this._currentSessionRequest)?.catch(e => {
-            console.error(e, "Code: " + e.code);
-            if (e.code === 9) showBalloonWarning("Make sure your device has the required permissions (e.g. camera access)")
+            console.error(e, "Code: " + e?.code);
+            if (e?.code === 9) showBalloonWarning("Couldn't start XR session. Make sure you allow the required permissions.")
             console.log("If the specified XR configuration is not supported (e.g. entering AR doesnt work) - make sure you access the website on a secure connection (HTTPS) and your device has the required permissions (e.g. camera access)");
             const notSecure = location.protocol === 'http:';
             if (notSecure) showBalloonWarning("XR requires a secure connection (HTTPS)");

package/src/engine/xr/TempXRContext.ts

@@ -32,7 +32,13 @@ export class TemporaryXRContext {
                 return null;
             }
             this._requestInFlight = true;
-            const session = await navigator.xr.requestSession(mode, init);
+            const session = await navigator.xr.requestSession(mode, init).catch(err => {
+                console.error("Failed to start temporary XR session:", err);
+            });
+            if (!session) {
+                this._requestInFlight = false;
+                return null;
+            }
             session.addEventListener("end", () => {
                 this._active = null;
             });
@@ -82,10 +88,14 @@ export class TemporaryXRContext {
         this._session = session;
         this._session.addEventListener("end", this.onEnd);
 
-        this._renderer = new WebGLRenderer({ alpha: true });
+        this._renderer = new WebGLRenderer({ alpha: true, antialias: true }); 
+        this._renderer.outputColorSpace = 'srgb';
         this._renderer.setAnimationLoop(this.onFrame);
         this._renderer.xr.setSession(session);
         this._renderer.xr.enabled = true;
+        // Set pixel ratio and size
+        this._renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
+        this._renderer.setSize(window.innerWidth, window.innerHeight);
         this._camera = new PerspectiveCamera();
         this._scene = new Scene();
         this._scene.fog = new Fog(0x444444, 10, 250);

package/src/engine/xr/usdz.ts

@@ -1,3 +1,4 @@
+import { isDevEnvironment } from "../debug/index.js";
 
 declare type USDZExporter = {
     exportAndOpen(): Promise<any>,
@@ -11,7 +12,11 @@ export namespace InternalUSDZRegistry {
     const usdzExporter: USDZExporter[] = [];
 
     export function exportAndOpen(): boolean {
-        if (!usdzExporter?.length) return false;
+        if (!usdzExporter?.length) {
+            if (isDevEnvironment()) {
+                console.warn("No USDZ exporters found – cannot export USDZ for QuickLook.");
+            }
+        }
         for (const exp of usdzExporter) {
             exp.exportAndOpen();
         }

package/src/engine-components/AlignmentConstraint.ts

@@ -9,9 +9,8 @@ import { Behaviour, GameObject } from "./Component.js";
  * You can use this to create dynamic beams or connectors between objects.
  *
  * @summary Aligns and scales the object between two target GameObjects
- * @category Utility
+ * @category Constraints
  * @group Components 
- 
  **/
 export class AlignmentConstraint extends Behaviour {
 

package/src/engine-components/Animation.ts

@@ -59,6 +59,8 @@ class Vec2 { x!: number; y!: number }
 
 /**
  * Animation component to play animations on a GameObject.
+ * 
+ * @summary Plays animations from AnimationClips 
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/Animator.ts

@@ -43,6 +43,7 @@ export declare class PlayOptions {
  * It works with an {@link AnimatorController} to handle state transitions and animation blending.
  * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
  * 
+ * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AudioListener.ts

@@ -9,7 +9,7 @@ import { Behaviour, GameObject } from "./Component.js";
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
  * 
- * @summary Audio listener for 3D audio capture
+ * @summary Receives audio in the scene and outputs it to speakers
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AudioSource.ts

@@ -52,7 +52,7 @@ export enum AudioRolloffMode {
  * is muted, the volume is set to 0. When unmuted, the volume
  * returns to its previous value.
  * 
- * @summary 3D audio source with spatial positioning and playback controls
+ * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/BasicIKConstraint.ts

@@ -3,6 +3,14 @@ import { Vector3 } from "three";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.  
+ * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
+ * 
+ * @summary Simple Inverse Kinematics Constraint
+ * @category Animation
+ * @group Components
+ */
 export class BasicIKConstraint extends Behaviour {
 
     private from!: GameObject;

package/src/engine-components/BoxHelperComponent.ts

@@ -14,6 +14,7 @@ const debug = getParam("debugboxhelper");
  * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
  * Helper visualization can be enabled with the URL parameter `?gizmos`.
  * 
+ * @summary Bounding box helper with intersection tests
  * @category Helpers
  * @group Components
  */

package/src/engine-components/Camera.ts

@@ -36,8 +36,8 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
- * @summary Camera rendering scenes from a specific viewpoint
- * @category Camera
+ * @summary Rendering scenes from a specific viewpoint
+ * @category Camera and Controls
  * @group Components
  */
 export class Camera extends Behaviour implements ICamera {

package/src/engine-components/CharacterController.ts

@@ -110,8 +110,12 @@ export class CharacterController extends Behaviour {
 }
 
 /**
- * @category Camera
- * @category Interactivity
+ * CharacterControllerInput handles user input to control a CharacterController.  
+ * It supports movement, looking around, jumping, and double jumping.  
+ * You can customize movement speed, rotation speed, and jump forces.  
+ * It also integrates with an Animator component for character animations.
+ * @summary User Input for Character Controller
+ * @category Character
  * @group Components
  */
 export class CharacterControllerInput extends Behaviour {

package/src/engine-components/Collider.ts

@@ -22,11 +22,11 @@ import { Rigidbody } from "./RigidBody.js";
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation 
  * 
- * 
+ * @summary Physics collider
  * @category Physics  
  * @group Components
  */
-export class Collider extends Behaviour implements ICollider {
+export abstract class Collider extends Behaviour implements ICollider {
 
     /**
      * Identifies this component as a collider.

package/src/engine-components/Component.ts

@@ -476,10 +476,11 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
      * Gets a component of the specified type in the gameObject's children hierarchy
      * @param go GameObject to search in
      * @param typeName Constructor of the component type
+     * @param includeInactive Whether to include inactive objects in the search
      * @returns The first matching component if found, otherwise null
      */
-    public static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>): T | null {
-        return getComponentInChildren(go, typeName);
+    public static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>, includeInactive: boolean = false): T | null {
+        return getComponentInChildren(go, typeName, includeInactive);
     }
 
     /**
@@ -588,7 +589,7 @@ export abstract class Component implements IComponent, EventTarget,
      */
     get [$componentName]() { return TypeStore.getKey(this.constructor as any) || undefined; }
 
-    
+
     private __context: Context | undefined;
 
     /**
@@ -1106,7 +1107,7 @@ export abstract class Component implements IComponent, EventTarget,
             this.dispatchEvent(new CustomEvent("destroyed", { detail: this }));
         }
         destroyComponentInstance(this as any);
-        if(isHotReloadEnabled()) unregisterHotReloadType(this);
+        if (isHotReloadEnabled()) unregisterHotReloadType(this);
     }
 
     /**

package/src/engine-components/ContactShadows.ts

@@ -53,7 +53,7 @@ type FitParameters = {
  * 
  * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
  * 
- * 
+ * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
 */

package/src/engine-components/DragControls.ts

@@ -485,6 +485,8 @@ interface IDragHandler {
     onDragUpdate?(numberOfPointers: number): void;
 }
 
+
+// #region MultiTouchDragHandler
 /** 
  * Handles two touch points affecting one object. 
  * Enables multi-touch interactions that allow movement, scaling, and rotation of objects.
@@ -734,6 +736,7 @@ class MultiTouchDragHandler implements IDragHandler {
 }
 
 
+// #region DragPointerHandler
 /** 
  * Handles a single pointer on an object. 
  * DragPointerHandlers manage determining if a drag operation has started, tracking pointer movement,
@@ -1335,6 +1338,7 @@ class DragPointerHandler implements IDragHandler {
     }
 }
 
+// #region LegacyDragVisualsHelper
 /** 
  * Provides visual helper elements for DragControls.
  * Shows where objects will be placed and their relation to surfaces below them.

package/src/engine-components/Gizmos.ts

@@ -8,6 +8,8 @@ import { Behaviour } from "./Component.js";
 
 /**
  * BoxGizmo is a component that displays a box around the object in the scene. It can optionally expand to the object's bounds.
+ *
+ * @summary Display a box around the object
  * @category Helpers
  * @group Components
  */