@needle-tools/engine 4.13.1 → 4.14.0-beta

package/src/engine-components/VideoPlayer.ts

@@ -604,11 +604,17 @@ export class VideoPlayer extends Behaviour {
             const videoMaterial = this._videoMaterial as any;
 
             if (!this.targetMaterialProperty) {
+                if (debug && videoMaterial[fieldName] === undefined) {
+                    console.warn(`The target material does not have a '${fieldName}' property, video might not render correctly.`);
+                }
                 videoMaterial[fieldName] = this._videoTexture;
             }
             else {
                 switch (this.targetMaterialProperty) {
                     default:
+                        if (debug && videoMaterial[this.targetMaterialProperty] === undefined) {
+                            console.warn(`The target material does not have a '${this.targetMaterialProperty}' property, video might not render correctly.`);
+                        }
                         videoMaterial[fieldName] = this._videoTexture;
                         break;
                     // doesnt render:

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

@@ -204,7 +204,7 @@ export class Button extends Behaviour implements IPointerEventHandler {
     // image? : Image;
 
     @serializable()
-    set interactable(value) {
+    set interactable(value: boolean) {
         this._interactable = value;
         if (this._image) {
             this._image.setInteractable(value);

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

@@ -63,7 +63,7 @@ export class ObjectRaycaster extends Raycaster {
     private raycastHits: Intersection[] = [];
 
     @serializable()
-    ignoreSkinnedMeshes = false;
+    ignoreSkinnedMeshes: boolean = false;
 
     start(): void {
         this.targets = [this.gameObject];

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

@@ -19,6 +19,7 @@ export enum OpenURLMode {
  * OpenURL behaviour opens a URL in a new tab or window when the object (or any if it's children) is clicked.
  * 
  * @category Interactivity
+ * @category Web
  * @group Components
  */
 export class OpenURL extends Behaviour implements IPointerClickHandler {

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

@@ -87,6 +87,7 @@ const debug = getParam("debugcursor");
  *
  * @summary Makes objects follow the cursor/touch position in 3D space
  * @category Interactivity
+ * @category Web
  * @group Components
  * @component
  */

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

@@ -66,6 +66,7 @@ type ScrollFollowEvent = {
  * 
  * @summary Links scroll position to target objects
  * @category Web
+ * @category Interaction
  * @group Components
  * @component
  */

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

@@ -8,6 +8,13 @@ import { registerType } from "../../engine/engine_typestore.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { RGBAColor } from "../../engine/js-extensions/RGBAColor.js";
 import { Behaviour } from "../Component.js";
+// Type-only imports for TSDoc @see links
+import type { Context } from "../../engine/engine_context.js";
+import type { Camera as CameraComponent } from "../Camera.js";
+import type { DragControls } from "../DragControls.js";
+import type { LookAtConstraint } from "../LookAtConstraint.js";
+import type { OrbitControls } from "../OrbitControls.js";
+import type { SceneSwitcher } from "../SceneSwitcher.js";
 
 
 const debugParam = getParam("debugviewbox");
@@ -83,7 +90,7 @@ export type ViewBoxMode = "continuous" | "once";
  * scene.add(viewBox);
  * ```
  *
- * @see {@link Camera} - The camera component that ViewBox controls
+ * @see {@link CameraComponent} - 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
@@ -121,7 +128,7 @@ export class ViewBox extends Behaviour {
      * 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
+     * @see {@link CameraComponent} for the camera component and its FOV property
      * @default -1 (automatically uses the camera's FOV on the first frame)
      */
     @serializable()

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

@@ -22,13 +22,22 @@ import { Behaviour } from "../Component.js";
 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.
- * 
+ * 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.  
+ *
+ * This component automatically requests `camera-access` permission when entering AR mode, which is required to:  
+ * - Display the real-world camera feed as a background  
+ * - Include the camera feed in AR screenshots taken with {@link screenshot2}  
+ *
+ * **Note**: If you want to take AR screenshots with the camera feed but don't need to display it as a background,   
+ * you can still add this component to your scene (it will request camera access) or manually request the  
+ * `camera-access` feature in your `onBeforeXR` method.  
+ *
  * - Example: https://samples.needle.tools/ar-camera-background
- * 
+ *
  * @summary Displays the camera feed as background in WebAR sessions
  * @category XR
  * @group Components
+ * @see {@link screenshot2} for taking screenshots in AR (requires camera access for camera feed compositing)
  */
 export class WebARCameraBackground extends Behaviour {
 

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

@@ -59,6 +59,7 @@ const debugQuicklook = getParam("debugusdz");
  * @see {@link XRControllerMovement} for VR locomotion
  * @see {@link WebARSessionRoot} for AR session configuration
  * @see {@link Avatar} for networked user avatars
+ * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
  * @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

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

@@ -66,13 +66,13 @@ export class WebXRPlaneTracking extends Behaviour {
      * Note: this will only be applied if dataTemplate is not assigned
      */
     @serializable()
-    occluder = true;
+    occluder: boolean = true;
 
     /**
      * If true the system will try to initiate room capture if no planes are detected.
      */
     @serializable()
-    initiateRoomCaptureIfNoData = true;
+    initiateRoomCaptureIfNoData: boolean = true;
 
     /**
      * If true plane tracking will be enabled
@@ -88,7 +88,7 @@ export class WebXRPlaneTracking extends Behaviour {
 
     /** when enabled mesh or plane tracking will also be used in VR */
     @serializable()
-    runInVR = true;
+    runInVR: boolean = true;
 
     /**
      * Returns all tracked planes

package/src/engine-components/webxr/controllers/XRControllerFollow.ts

@@ -63,7 +63,7 @@ export class XRControllerFollow extends Behaviour {
      * @default false
     */
     @serializable()
-    useGripSpace = false;
+    useGripSpace: boolean = false;
 
     /** when enabled the position, rotation and scale of this object will be set to the position it was at when it entered the XR session 
      * @default true

package/src/engine-components/webxr/controllers/XRControllerMovement.ts

@@ -40,13 +40,13 @@ export class XRControllerMovement extends Behaviour implements XRMovementBehavio
      * @default 1.5
     */
     @serializable()
-    movementSpeed = 1.5;
+    movementSpeed: number = 1.5;
 
     /** How many degrees to rotate the XR rig when using the rotation trigger
      * @default 30
      */
     @serializable()
-    rotationStep = 30;
+    rotationStep: number = 30;
 
     /** When enabled you can teleport using the right XR controller's thumbstick by pressing forward 
      * @default true
@@ -65,13 +65,13 @@ export class XRControllerMovement extends Behaviour implements XRMovementBehavio
      * @default false
     */
     @serializable()
-    useTeleportTarget = false;
+    useTeleportTarget: boolean = false;
 
     /** Enable to fade out the scene when teleporting 
      * @default false
     */
     @serializable()
-    useTeleportFade = false;
+    useTeleportFade: boolean = false;
 
     /** enable to visualize controller rays in the 3D scene 
      * @default true