@needle-tools/engine 4.3.0-alpha → 4.3.0-alpha.1

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

@@ -31,74 +31,127 @@ const debugQuicklook = getParam("debugusdz");
 export class WebXR extends Behaviour {
 
     // UI
-    /** When enabled a button will be added to the UI to enter VR */
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
+     */
     @serializable()
     createVRButton: boolean = true;
-    /** When enabled a button will be added to the UI to enter AR */
+
+    /**
+     * When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
+     */
     @serializable()
     createARButton: boolean = true;
-    /** When enabled a send to quest button will be shown if the device does not support VR */
+
+    /**
+     * When enabled, a button to send the experience to an Oculus Quest will be shown if the current device does not support VR.
+     * This helps direct users to compatible devices for optimal VR experiences.
+     */
     @serializable()
     createSendToQuestButton: boolean = true;
-    /** When enabled a QRCode will be created to open the website on a mobile device */
+
+    /**
+     * When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
+     */
     @serializable()
     createQRCode: boolean = true;
 
     // VR Settings
-    /** When enabled default movement behaviour will be added */
+    /**
+     * When enabled, default movement controls will be automatically added to the scene when entering VR.
+     * This includes teleportation and smooth locomotion options for VR controllers.
+     */
     @serializable()
     useDefaultControls: boolean = true;
-    /** When enabled controller models will automatically be created and updated when you are using controllers in WebXR */
+
+    /**
+     * When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
+     */
     @serializable()
     showControllerModels: boolean = true;
-    /** When enabled hand models will automatically be created and updated when you are using hands in WebXR */
+
+    /**
+     * When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
+     */
     @serializable()
     showHandModels: boolean = true;
 
     // AR Settings
-    /** When enabled the scene must be placed in AR */
+    /**
+     * When enabled, a reticle will be displayed to help place the scene in AR. The user must tap on a detected surface to position the scene.
+     */
     @serializable()
     usePlacementReticle: boolean = true;
-    /** When assigned this object will be used as the AR placement reticle */
+
+    /**
+     * Optional custom 3D object to use as the AR placement reticle instead of the default one.
+     */
     @serializable(AssetReference)
     customARPlacementReticle?: AssetReference;
-    /** When enabled you can position, rotate or scale your AR scene with one or two fingers */
+
+    /**
+     * When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
+     */
     @serializable()
     usePlacementAdjustment: boolean = true;
-    /** Used when `usePlacementReticle` is enabled. This is the scale of the user in the scene in AR. Larger values make the 3D content appear smaller */
+
+    /**
+     * Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
+     * Only applies when `usePlacementReticle` is enabled.
+     */
     @serializable()
     arScale: number = 1;
-    /** Experimental: When enabled an XRAnchor will be created for the AR scene and the position will be updated to the anchor position every few frames */
+
+    /**
+     * When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
+     * This can help with spatial persistence in AR experiences.
+     * @experimental
+     */
     @serializable()
     useXRAnchor: boolean = false;
+
     /**
-     * When enabled the scene will be placed automatically when a point in the real world is found
+     * When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,
+     * without requiring the user to tap to confirm placement.
      */
     @serializable()
-    autoPlace: boolean = true;
-    /** When enabled the AR session root center will be automatically adjusted to place the center of the scene */
+    autoPlace: boolean = false;
+
+    /**
+     * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
+     * This helps ensure the scene is properly aligned with detected surfaces.
+     */
     @serializable()
     autoCenter: boolean = false;
 
-    /** When enabled a USDZExporter component will be added to the scene (if none is found) */
+    /**
+     * When enabled, a USDZExporter component will be automatically added to the scene if none is found.
+     * This allows iOS and visionOS devices to view 3D content using Apple's AR QuickLook.
+     */
     @serializable()
     useQuicklookExport: boolean = false;
 
-
-    /** Preview feature enabling occlusion (when available: https://github.com/cabanier/three.js/commit/b6ee92bcd8f20718c186120b7f19a3b68a1d4e47)
-     * Enables the 'depth-sensing' WebXR feature to provide realtime depth occlusion. Only supported on Oculus Quest right now.
+    /**
+     * When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
+     * Currently only supported on Oculus Quest devices.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/XRDepthInformation
+     * @experimental
      */
     @serializable()
     useDepthSensing: boolean = false;
 
     /**
-     * When enabled the spatial grab raycaster will be added or enabled in the scene
+     * When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
+     * allowing users to interact with objects at a distance in VR/AR.
      * @default true
      */
     @serializable()
     useSpatialGrab: boolean = true;
 
-    /** This avatar representation will be spawned when you enter a webxr session */
+    /**
+     * Specifies the avatar representation that will be created when entering a WebXR session.
+     * Can be a reference to a 3D model or a boolean to use the default avatar.
+     */
     @serializable(AssetReference)
     defaultAvatar?: AssetReference | boolean;
 
@@ -111,10 +164,17 @@ export class WebXR extends Behaviour {
 
     static activeWebXRComponent: WebXR | null = null;
 
+    /**
+     * Initializes the WebXR component by obtaining the XR sync object for this context.
+     */
     awake() {
         NeedleXRSession.getXRSync(this.context);
     }
 
+    /**
+     * Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
+     * sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
+     */
     onEnable(): void {
         // check if we're on a secure connection:
         if (window.location.protocol !== "https:") {
@@ -153,11 +213,20 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Cleans up resources when the component is disabled.
+     * Destroys the USDZ exporter if one was created and removes UI buttons.
+     */
     onDisable(): void {
         this._usdzExporter?.destroy();
         this.removeButtons();
     }
 
+    /**
+     * Checks if WebXR is supported and offers an appropriate session.
+     * This is used to show the WebXR session joining prompt in browsers that support it.
+     * @returns A Promise that resolves to true if a session was offered, false otherwise
+     */
     private async handleOfferSession() {
         if (this.createVRButton) {
             const hasVRSupport = await NeedleXRSession.isVRSupported();
@@ -196,7 +265,7 @@ export class WebXR extends Behaviour {
         NeedleXRSession.stop();
     }
 
-    private _exitXRMenuButton?: HTMLElement;
+        private _exitXRMenuButton?: HTMLElement;
     private _previousXRState: number = 0;
     private _spatialGrabRaycaster?: SpatialGrabRaycaster;
 
@@ -204,6 +273,11 @@ export class WebXR extends Behaviour {
         return !WebXR.activeWebXRComponent || WebXR.activeWebXRComponent === this;
     }
 
+    /**
+     * Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
+     * @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
+     * @param args The XRSessionInit object that will be passed to the WebXR API
+     */
     onBeforeXR(_mode: XRSessionMode, args: XRSessionInit): void {
         if (!this.isActiveWebXR) {
             console.warn(`WebXR: another WebXR component is already active (${WebXR.activeWebXRComponent?.name}). This is ignored: ${this.name}`);
@@ -217,6 +291,11 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
+     * AR placement, and other features based on component settings.
+     * @param args Event arguments containing information about the started XR session
+     */
     async onEnterXR(args: NeedleXREventArgs) {
         if (!this.isActiveWebXR) return;
 
@@ -288,6 +367,11 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Called every frame during an active WebXR session.
+     * Updates components that depend on the current XR state.
+     * @param _args Event arguments containing information about the current XR session frame
+     */
     onUpdateXR(_args: NeedleXREventArgs): void {
         if (!this.isActiveWebXR) return;
         if (this._spatialGrabRaycaster) {
@@ -295,6 +379,11 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Called when a WebXR session ends. Restores pre-session state,
+     * removes temporary components, and cleans up resources.
+     * @param _ Event arguments containing information about the ended XR session
+     */
     onLeaveXR(_: NeedleXREventArgs): void {
         this._exitXRMenuButton?.remove();
 
@@ -339,8 +428,10 @@ export class WebXR extends Behaviour {
         return models;
     }
 
-
-
+    /**
+     * Creates and instantiates the user's avatar representation in the WebXR session.
+     * @param xr The active session
+     */
     protected async createLocalAvatar(xr: NeedleXRSession) {
         if (this._playerSync && xr.running && typeof this.defaultAvatar != "boolean") {
             this._playerSync.asset = this.defaultAvatar;
@@ -348,6 +439,11 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Event handler called when a player avatar is spawned.
+     * Ensures the avatar has the necessary Avatar component.
+     * @param instance The spawned avatar 3D object
+     */
     private onAvatarSpawned = (instance: Object3D) => {
         // spawned webxr avatars must have a avatar component
         if (debug) console.log("WebXR.onAvatarSpawned", instance);
@@ -360,13 +456,16 @@ export class WebXR extends Behaviour {
 
     // HTML UI
 
-    /** @deprecated use `getButtonsFactory()` or access `WebXRButtonFactory.getOrCreate()` directory */
+    /** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
     getButtonsContainer(): WebXRButtonFactory {
         return this.getButtonsFactory();
     }
 
-    /** Calling this function will get the Needle WebXR button factory (it will be created if it doesnt exist yet)  
-     * @returns the Needle WebXR button factory */
+    /**
+     * Returns the WebXR button factory, creating one if it doesn't exist.
+     * Use this to access and modify WebXR UI buttons.
+     * @returns The WebXRButtonFactory instance
+     */
     getButtonsFactory(): WebXRButtonFactory {
         if (!this._buttonFactory) {
             this._buttonFactory = WebXRButtonFactory.getOrCreate();
@@ -374,8 +473,15 @@ export class WebXR extends Behaviour {
         return this._buttonFactory;
     }
 
+    /**
+     * Reference to the WebXR button factory used by this component.
+     */
     private _buttonFactory?: WebXRButtonFactory;
 
+    /**
+     * Creates and sets up UI elements for WebXR interaction based on component settings
+     * and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
+     */
     private handleCreatingHTML() {
         const xrButtonsPriority = 50;
 
@@ -423,14 +529,25 @@ export class WebXR extends Behaviour {
         }
     }
 
+    /**
+     * Storage for UI buttons created by this component.
+     */
     private readonly _buttons: HTMLElement[] = [];
 
+    /**
+     * Adds a button to the UI with the specified priority.
+     * @param button The HTML element to add
+     * @param priority The button's priority value (lower numbers appear first)
+     */
     private addButton(button: HTMLElement, priority: number) {
         this._buttons.push(button);
         button.setAttribute("priority", priority.toString());
         this.context.menu.appendChild(button);
     }
 
+    /**
+     * Removes all buttons created by this component from the UI.
+     */
     private removeButtons() {
         for (const button of this._buttons) {
             button.remove();

package/src/engine-components-experimental/networking/PlayerSync.ts

@@ -12,6 +12,7 @@ import { EventList } from "../../engine-components/EventList.js";
 
 const debug = getParam("debugplayersync");
 
+/** Type definition for a PlayerSync instance with a guaranteed asset property */
 declare type PlayerSyncWithAsset = PlayerSync & Required<Pick<PlayerSync, "asset">>;
 
 /**
@@ -23,7 +24,10 @@ export class PlayerSync extends Behaviour {
 
     /**
      * This API is experimental and may change or be removed in the future.
-     * Create a PlayerSync instance at runtime from a given URL
+     * Creates a PlayerSync instance at runtime from a given URL and sets it up for networking
+     * @param url Path to the asset that should be instantiated for each player
+     * @param init Optional initialization parameters for the PlayerSync component
+     * @returns Promise resolving to a PlayerSync instance with a guaranteed asset property
      * @example
      * ```typescript
      * const res = await PlayerSync.setupFrom("/assets/demo.glb");
@@ -47,15 +51,22 @@ export class PlayerSync extends Behaviour {
         return ps as PlayerSyncWithAsset;
     }
 
-    /** when enabled PlayerSync will automatically load and instantiate the assigned asset when joining a networked room */
+    /** 
+     * When enabled, PlayerSync will automatically load and instantiate the assigned asset when joining a networked room
+     */
     @serializable()
     autoSync: boolean = true;
 
-    /** This asset will be loaded and instantiated when PlayerSync becomes active and joins a networked room */
+    /** 
+     * The asset that will be loaded and instantiated when PlayerSync becomes active and joins a networked room
+     */
     @serializable(AssetReference)
     asset?: AssetReference;
 
-    /** Event called when an instance is spawned */
+    /** 
+     * Event invoked when a player instance is spawned with the spawned {@link Object3D} as parameter
+     * @serializable
+     */
     @serializable(EventList)
     onPlayerSpawned?: EventList<Object3D>;
 
@@ -86,6 +97,10 @@ export class PlayerSync extends Behaviour {
         if (this.autoSync) this.getInstance();
     }
 
+    /**
+     * Gets or creates an instance of the assigned asset for the local player
+     * @returns Promise resolving to the instantiated player object or null if creation failed
+     */
     async getInstance() {
         if (this._localInstance) return this._localInstance;
 
@@ -123,6 +138,9 @@ export class PlayerSync extends Behaviour {
         return this._localInstance;
     }
 
+    /**
+     * Destroys the current player instance and cleans up networking state
+     */
     destroyInstance = () => {
         this._localInstance?.then(go => {
             if (debug) console.log("PlayerSync.destroyInstance", go);
@@ -131,8 +149,9 @@ export class PlayerSync extends Behaviour {
         this._localInstance = undefined;
     }
 
-
-
+    /**
+     * Sets up visibility change listeners to handle player cleanup when browser tab visibility changes
+     */
     private watchTabVisible() {
         window.addEventListener("visibilitychange", _ => {
             if (document.visibilityState === "visible") {
@@ -147,32 +166,50 @@ export class PlayerSync extends Behaviour {
     }
 }
 
+/**
+ * Enum defining events that can be triggered by PlayerState
+ */
 export enum PlayerStateEvent {
+    /** Triggered when a PlayerState's owner property changes */
     OwnerChanged = "ownerChanged",
 }
 
+/** Arguments passed when a PlayerState's owner changes */
 export declare interface PlayerStateOwnerChangedArgs {
+    /** The PlayerState instance that changed */
     playerState: PlayerState;
+    /** Previous owner's connection ID */
     oldValue: string;
+    /** New owner's connection ID */
     newValue: string;
 }
 
+/** Callback type for PlayerState events */
 export declare type PlayerStateEventCallback = (args: CustomEvent<PlayerStateOwnerChangedArgs>) => void;
 
+/**
+ * Represents a player instance in the networked environment.
+ * Handles ownership, synchronization, and lifecycle management of player objects.
+ */
 export class PlayerState extends Behaviour {
 
     private static _all: PlayerState[] = [];
-    /** all instances for all players */
+    /** All PlayerState instances for all players in the scene */
     static get all(): PlayerState[] {
         return PlayerState._all;
     };
 
     private static _local: PlayerState[] = [];
-    /** all instances for the local player */
+    /** All PlayerState instances that belong to the local player */
     static get local(): PlayerState[] {
         return PlayerState._local;
     }
 
+    /**
+     * Gets the PlayerState component for a given object or component
+     * @param obj Object3D or Component to find the PlayerState for
+     * @returns The PlayerState component if found, undefined otherwise
+     */
     static getFor(obj: Object3D | Component) {
         if (obj instanceof Object3D) {
             return GameObject.getComponentInParent(obj, PlayerState);
@@ -183,22 +220,34 @@ export class PlayerState extends Behaviour {
         return undefined;
     }
 
-    //** use to check if a component or gameobject is part of a instance owned by the local player */
+    /**
+     * Checks if a given object or component belongs to the local player
+     * @param obj Object3D or Component to check
+     * @returns True if the object belongs to the local player, false otherwise
+     */
     static isLocalPlayer(obj: Object3D | Component): boolean {
         const state = PlayerState.getFor(obj);
         return state?.isLocalPlayer ?? false;
     }
 
-    // static Callback
     private static _callbacks: { [key: string]: PlayerStateEventCallback[] } = {};
     /**
-     * Add a callback for a PlayerStateEvent
+     * Registers a callback for a specific PlayerState event
+     * @param event The event to listen for
+     * @param cb Callback function that will be invoked when the event occurs
+     * @returns The provided callback function for chaining
      */
     static addEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback) {
         if (!this._callbacks[event]) this._callbacks[event] = [];
         this._callbacks[event].push(cb);
         return cb;
     }
+
+    /**
+     * Removes a previously registered event callback
+     * @param event The event type to remove the callback from
+     * @param cb The callback function to remove
+     */
     static removeEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback) {
         if (!this._callbacks[event]) return;
         const index = this._callbacks[event].indexOf(cb);
@@ -212,20 +261,39 @@ export class PlayerState extends Behaviour {
     }
 
 
+    /** Event triggered when the owner of this PlayerState changes */
     public onOwnerChangeEvent = new EventList();
+    
+    /** Event triggered the first time an owner is assigned to this PlayerState */
     public onFirstOwnerChangeEvent = new EventList();
+    
+    /** Indicates if this PlayerState has an owner assigned */
     public hasOwner = false;
 
+    /**
+     * The connection ID of the player who owns this PlayerState instance
+     * @syncField Synchronized across the network
+     */
     @syncField(PlayerState.prototype.onOwnerChange)
     owner?: string;
 
-    /** when enabled PlayerSync will not destroy itself when not connected anymore */
+    /** 
+     * When enabled, PlayerState will not destroy itself when the owner is not connected anymore 
+     */
     dontDestroy: boolean = false;
 
+    /**
+     * Indicates if this PlayerState belongs to the local player
+     */
     get isLocalPlayer(): boolean {
         return this.owner === this.context.connection.connectionId;
     }
 
+    /**
+     * Handles owner change events and updates relevant state
+     * @param newOwner The new owner's connection ID
+     * @param oldOwner The previous owner's connection ID
+     */
     private onOwnerChange(newOwner: string, oldOwner: string) {
         if (debug) console.log(`PlayerSync.onOwnerChange: ${oldOwner} → ${newOwner} (me: ${this.context.connection.connectionId})`);
 
@@ -300,7 +368,7 @@ export class PlayerState extends Behaviour {
         }
     }
 
-    /** this tells the server that this client has been destroyed and the networking message for the instantiate will be removed */
+    /** Tells the server that this client has been destroyed, and the networking message for the instantiate will be removed      */
     doDestroy() {
         if (debug) console.log("PlayerSync.doDestroy → syncDestroy", this.name);
         syncDestroy(this.gameObject, this.context.connection, true, { saveInRoom: false });
@@ -319,6 +387,10 @@ export class PlayerState extends Behaviour {
         }
     }
 
+    /**
+     * Handler for when a user leaves the networked room
+     * @param model Object containing the ID of the user who left
+     */
     private onUserLeftRoom = (model: { userId: string }) => {
         if (model.userId === this.owner) {
             if (debug)