@needle-tools/engine 4.11.0-beta.1 → 4.11.0-next.687516a

package/src/engine-components/utils/OpenURL.ts

@@ -15,8 +15,9 @@ export enum OpenURLMode {
     NewWindow = 2
 }
 
-/**
- * OpenURL behaviour opens a URL in a new tab or window.
+/** 
+ * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
+ * 
  * @category Interactivity
  * @group Components
  */

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

@@ -24,6 +24,8 @@ const debug = getParam("debugarcamera");
 /**
  * WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.
  * 
+ * - Example: https://samples.needle.tools/ar-camera-background
+ * 
  * @category XR
  * @group Components
  */

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

@@ -20,7 +20,7 @@ const invertForwardMatrix = new Matrix4().makeRotationY(Math.PI);
 
 /**
  * The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.  
- * It is also responsible for scaling the user in AR. 
+ * It is also responsible for scaling the user in AR and to define the center of the AR scene. If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
  * 
  * @example 
  * ```ts

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

@@ -27,6 +27,8 @@ const debugQuicklook = getParam("debugusdz");
  * 
  * 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
+ * 
  * @example Enable VR and AR support using code
  * ```ts
  * import { onStart, WebXR } from "@needle-tools/engine";

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

@@ -290,6 +290,16 @@ class ImageTrackingExtension implements IUSDExporterExtension {
 
 
 /**
+ * Add this component to a object to enable image tracking in WebXR sessions.    
+ * 
+ * You need to add at least one {@link WebXRImageTrackingModel} to the `trackedImages` array to define which images to track and which objects to place on top of them.
+ * 
+ * **NOTE:** For Android devices, image tracking currently requires the user to enable the `chrome://flags/#webxr-incubations` flag in Chrome.  
+ * 
+ * **NOTE:** For iOS only one image can be tracked at a time. If you have multiple images in the `trackedImages` array, only the first one will be tracked. You can use the {@link setPrimaryImage} method to change which image is tracked before entering the XR session.  
+ * 
+ * - Example: https://samples.needle.tools/image-tracking
+ * 
  * @category XR
  * @group Components
  */
@@ -313,7 +323,14 @@ export class WebXRImageTracking extends Behaviour {
 
     /**
      * Add an image to track. If the image is already in the trackedImages array it won't be added again.  
-     * Note: that adding images at runtime *while* in AR is not supported.
+     * Note: that adding images at runtime *while* in AR is not supported.  
+     * 
+     * @example
+     * ```ts
+     * const imageTracking = GameObject.getComponent(myGameObject, WebXRImageTracking);
+     * const image = new WebXRImageTrackingModel({ url: "https://example.com/my-marker.png", widthInMeters: 0.2, object: myObject });
+     * imageTracking.addImage(image, true); // add and set as primary image
+     * ```
      */
     addImage(image: WebXRImageTrackingModel, asPrimary: boolean = false) {
         if (!this.trackedImages.includes(image)) {
@@ -324,7 +341,11 @@ export class WebXRImageTracking extends Behaviour {
     }
 
 
-
+    /**
+     * List of images to track in the WebXR session. Use {@link WebXRImageTrackingModel} to define each image and the object to place on top of it.  
+     * 
+     * Use the `addImage()` and `setPrimaryImage()` methods to modify this array at runtime.
+     */
     @serializable(WebXRImageTrackingModel)
     readonly trackedImages: WebXRImageTrackingModel[] = [];
 
@@ -339,6 +360,7 @@ export class WebXRImageTracking extends Behaviour {
 
     private _supported: boolean = true;
 
+    /** @internal */
     awake(): void {
         if (debug) console.log(this)
         if (!this.trackedImages) return;
@@ -348,9 +370,11 @@ export class WebXRImageTracking extends Behaviour {
             }
         }
     }
+    /** @internal */
     onEnable() {
         USDZExporter.beforeExport.addEventListener(this.onBeforeUSDZExport);
     }
+    /** @internal */
     onDisable(): void {
         USDZExporter.beforeExport.removeEventListener(this.onBeforeUSDZExport);
     }
@@ -362,7 +386,7 @@ export class WebXRImageTracking extends Behaviour {
     }
 
 
-
+    /** @internal */
     onBeforeXR(_mode: XRSessionMode, args: XRSessionInit & { trackedImages: Array<any> }): void {
         // console.log("onXRRequested", args, this.trackedImages)
         if (this.trackedImages) {
@@ -386,6 +410,7 @@ export class WebXRImageTracking extends Behaviour {
         }
     }
 
+    /** @internal */
     onEnterXR(_args: NeedleXREventArgs): void {
         if (this.trackedImages) {
             for (const trackedImage of this.trackedImages) {
@@ -408,6 +433,7 @@ export class WebXRImageTracking extends Behaviour {
         }
     };
 
+    /** @internal */
     onLeaveXR(_args: NeedleXREventArgs): void {
 
         if (!this.supported && DeviceUtilities.isAndroidDevice()) {
@@ -440,6 +466,7 @@ export class WebXRImageTracking extends Behaviour {
 
     private readonly webXRIncubationsWarning = "Image tracking is currently not supported on this device. On Chrome for Android, you can enable the <a target=\"_blank\" href=\"#\" onclick=\"() => console.log('I')\">chrome://flags/#webxr-incubations</a> flag.";
 
+    /** @internal */
     onUpdateXR(args: NeedleXREventArgs): void {
         this.currentImages.length = 0;