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

package/src/engine-components/Joints.ts

@@ -4,6 +4,12 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
+/**
+ * Base class for physics joints connecting two rigid bodies.
+ * @summary Connect two Rigidbodies
+ * @category Physics
+ * @group Components
+ */
 export abstract class Joint extends Behaviour {
     @serializable(Rigidbody)
     connectedBody?: Rigidbody;
@@ -30,6 +36,12 @@ export abstract class Joint extends Behaviour {
     protected abstract createJoint(self: Rigidbody, other: Rigidbody);
 }
 
+/**
+ * The FixedJoint groups together 2 rigidbodies, making them stick together in their bound position
+ * @summary Connect two Rigidbodies and make them stick together
+ * @category Physics
+ * @group Components
+ */
 export class FixedJoint extends Joint {
 
     protected createJoint(self: Rigidbody, other: Rigidbody) {
@@ -37,6 +49,14 @@ export class FixedJoint extends Joint {
     }
 }
 
+/**
+ * The HingeJoint groups together 2 rigid bodies, constraining them to move like connected by a hinge.
+ * 
+ * You can specify the anchor point and axis of rotation for the hinge.
+ * @summary Connect two Rigidbodies with a hinge
+ * @category Physics
+ * @group Components
+ */
 export class HingeJoint extends Joint {
 
     @serializable(Vector3)

package/src/engine-components/LODGroup.ts

@@ -41,7 +41,7 @@ declare class LODSetting {
 /**
  * LODGroup allows to create a group of LOD levels for an object.
  * 
- * @summary Level of Detail (LOD) Group Component
+ * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
  */

package/src/engine-components/LookAtConstraint.ts

@@ -9,7 +9,7 @@ import type { OrbitControls } from "./OrbitControls.js";
  * This component is used by {@link OrbitControls} internally.
  * 
  * @summary Look At Constraint for OrbitControls
- * @category Camera Controls
+ * @category Camera and Controls
  * @group Components
  */
 export class LookAtConstraint extends Behaviour {

package/src/engine-components/Networking.ts

@@ -11,7 +11,7 @@ const debug = getParam("debugnet");
  * This component supplies websocket URLs for establishing connections.
  * It implements the {@link INetworkingWebsocketUrlProvider} interface.
  * 
- * @summary Networking configuration component
+ * @summary Networking configuration
  * @category Networking
  * @group Components
  */

package/src/engine-components/OrbitControls.ts

@@ -64,7 +64,7 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
  * The three OrbitControls object can be accessed via the `controls` property.  
  * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
  * @summary Camera controller using three.js OrbitControls
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  */
 export class OrbitControls extends Behaviour implements ICameraController {

package/src/engine-components/Renderer.ts

@@ -805,6 +805,12 @@ export class Renderer extends Behaviour implements IRenderer {
 export class MeshRenderer extends Renderer {
 }
 
+/**
+ * Renders deformable meshes that deform via bones and/or blend shapes.
+ * @summary Renderer for deformable meshes
+ * @category Rendering
+ * @group Components
+ **/
 export class SkinnedMeshRenderer extends MeshRenderer {
 
     private _needUpdateBoundingSphere = false;

package/src/engine-components/RendererInstancing.ts

@@ -669,14 +669,17 @@ class InstancedMeshRenderer {
     private grow(geometry: BufferGeometry) {
         const id = ++this._growId;
         const growFactor = 2;
-        const newSize = Math.ceil(this._maxInstanceCount * growFactor);
+
+        const growInstances = this.count >= this._maxInstanceCount;
+        const newSize = growInstances ? Math.ceil(this._maxInstanceCount * growFactor) : this._maxInstanceCount;
 
         // create a new BatchedMesh instance
         // TODO: we should keep track of how many instances for each geometry we have and consider that when estimating new space
         const estimatedSpace = this.tryEstimateVertexCountSize(newSize, [geometry]);// geometry.attributes.position.count;
         // const indices = geometry.index ? geometry.index.count : 0;
-        const newMaxVertexCount = Math.max(this._maxVertexCount, estimatedSpace.vertexCount);
-        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount);//, Math.ceil(this._maxVertexCount * growFactor));
+        const vertexGrowFactor = 1.25;
+        const newMaxVertexCount = Math.max(this._maxVertexCount, Math.ceil(estimatedSpace.vertexCount * vertexGrowFactor));
+        const newMaxIndexCount = Math.max(this._maxIndexCount, Math.ceil(estimatedSpace.indexCount * vertexGrowFactor));
 
         if (debugInstancing) {
             const geometryInfo = getMeshInformation(geometry);

package/src/engine-components/SceneSwitcher.ts

@@ -261,7 +261,7 @@ export class SceneSwitcher extends Behaviour {
             if (scene && !scene.hasUrl && scene.asset instanceof Object3D) {
                 GameObject.remove(scene.asset);
             }
-            else if(scene instanceof Object3D) {
+            else if (scene instanceof Object3D) {
                 GameObject.remove(scene);
             }
         }
@@ -477,13 +477,13 @@ export class SceneSwitcher extends Behaviour {
      * @returns a promise that resolves to true if the scene was loaded successfully
      */
     select(index: number | string): Promise<boolean> {
-        if (debug) console.log("select", index);
+        if (debug) console.log("[SceneSwitcher] select", index);
 
         if (typeof index === "object") {
             // If a user tries to reference a scene object in a UnityEvent and invoke select(obj) 
             // Then the object will be serialized as a object { guid : ... } or with the index json pointer
             // This case is not supported right now. Object references in the editor must not be scene references
-            console.warn("Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
+            console.warn("[SceneSwitcher] Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
         }
 
         if (typeof index === "string") {
@@ -595,7 +595,7 @@ export class SceneSwitcher extends Behaviour {
         const current = this._currentScene;
         this._currentScene = undefined;
         if (current) {
-            if (debug) console.log("UNLOAD", current.url, "HasURL?: " + current.hasUrl)
+            if (debug) console.log("[SceneSwitcher] UNLOAD", current.url, "HasURL?: " + current.hasUrl)
             const sceneListener = this.tryGetSceneEventListener(current.asset as any as Object3D);
             if (sceneListener?.sceneClosing) {
                 const res = sceneListener.sceneClosing();
@@ -620,6 +620,7 @@ export class SceneSwitcher extends Behaviour {
         const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
 
         try {
+            if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene start: ${scene.url} (index: ${index})`);
             this._currentlyLoadingScene = scene;
             this._currentLoadingProgress = new ProgressEvent("progress", { loaded: 0, total: 1 });
 
@@ -632,7 +633,7 @@ export class SceneSwitcher extends Behaviour {
                 if (debug) {
                     const t01 = prog.loaded / prog.total;
                     const progressBarString = "[" + "=".repeat(Math.floor(t01 * 20)) + "-".repeat(20 - Math.floor(t01 * 20)) + "]";
-                    console.debug(`[SceneSwitcher] Download ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
+                    console.debug(`${Date.now()} [SceneSwitcher] Loading scene progress: ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
                 }
                 this._currentLoadingProgress = prog;
                 this.dispatchEvent(prog);
@@ -646,15 +647,15 @@ export class SceneSwitcher extends Behaviour {
             this._currentlyLoadingScene = undefined;
 
             if (finishedEvt.defaultPrevented) {
-                if (debug) console.warn("Adding loaded scene prevented:", scene, finishedEvt);
+                if (debug) console.warn("[SceneSwitcher] Adding loaded scene prevented:", scene, finishedEvt);
                 return false;
             }
             if (!scene.asset) {
-                if (debug) console.warn("Failed loading scene:", scene);
+                if (debug) console.warn("[SceneSwitcher] Failed loading scene:", scene);
                 return false;
             }
             if (this._currentIndex === index) {
-                if (debug) console.log("ADD", scene.url);
+                if (debug) console.log("[SceneSwitcher] ADD", scene.url);
                 this._currentScene = scene;
 
 
@@ -683,7 +684,7 @@ export class SceneSwitcher extends Behaviour {
                         this.context.scene.background = skybox;
                     }
                     else if (debug) {
-                        console.warn("SceneSwitcher: Can't find skybox for scene " + scene.url);
+                        console.warn("[SceneSwitcher] Can't find skybox for scene " + scene.url);
                     }
                 }
 
@@ -713,10 +714,9 @@ export class SceneSwitcher extends Behaviour {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
-
+                if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene finished: ${scene.url} (index: ${index})`);
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
-
                 this.sceneLoaded?.invoke(this);
                 return true;
             }
@@ -772,7 +772,7 @@ export class SceneSwitcher extends Behaviour {
             }
         }
 
-        if (isLocalNetwork()) console.warn("Can not find scene: \"" + value + "\"", this)
+        if (isLocalNetwork()) console.warn("[SceneSwitcher] Can not find scene: \"" + value + "\"", this)
 
         return couldNotLoadScenePromise;
     }
@@ -913,7 +913,7 @@ class PreLoadScheduler {
      */
     begin(delay: number) {
         if (this._isRunning) return;
-        if (debug) console.log("Preload begin", { delay })
+        if (debug) console.log("[SceneSwitcher] Preload scheduled", { delay });
         this._isRunning = true;
         let lastRoom: number = -10;
         let searchDistance: number;
@@ -923,7 +923,7 @@ class PreLoadScheduler {
         const interval = setInterval(() => {
             if (this.allLoaded()) {
                 if (debug)
-                    console.log("All scenes (pre-)loaded");
+                    console.log("[SceneSwitcher] All scenes (pre-)loaded");
                 this.stop();
             }
             if (!this._isRunning) {
@@ -950,7 +950,7 @@ class PreLoadScheduler {
             if (roomIndex < 0 || roomIndex >= array.length) return;
             if (!this._loadTasks.some(t => t.index === roomIndex)) {
                 const scene = array[roomIndex];
-                if (debug) console.log("Preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
+                if (debug) console.log("[SceneSwitcher] Schedule preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
                 new LoadTask(roomIndex, scene, this._loadTasks);
             }
         }, 200);
@@ -1019,10 +1019,10 @@ class LoadTask {
     private async awaitLoading() {
         if (this.asset && !this.asset.isLoaded()) {
             if (debug)
-                console.log("Preload start: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload start: " + this.asset.url, this.index);
             await this.asset.preload();
             if (debug)
-                console.log("Preload finished: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload finished: " + this.asset.url, this.index);
         }
 
         const i = this.tasks.indexOf(this);

package/src/engine-components/ShadowCatcher.ts

@@ -23,7 +23,7 @@ enum ShadowMode {
  * 
  * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
  * 
- * @summary Renders shadows or light on the object
+ * @summary Creates a shadow mask or a light occluder 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/SpectatorCamera.ts

@@ -1,4 +1,5 @@
 import { Color, Object3D, PerspectiveCamera, Quaternion, Vector3, WebGLState } from "three";
+import { PlayerState } from "../engine-components-experimental/networking/PlayerSync.js";
 
 import { InputEvents } from "../engine/engine_input.js";
 import { RoomEvents } from "../engine/engine_networking.js";
@@ -8,7 +9,7 @@ import { PlayerView, ViewDevice } from "../engine/engine_playerview.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
 import type { ICamera } from "../engine/engine_types.js";
-import { getParam } from "../engine/engine_utils.js";
+import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, Component, GameObject } from "./Component.js";
 import { OrbitControls } from "./OrbitControls.js";
@@ -35,7 +36,7 @@ const debug = getParam("debugspectator");
  * 
  * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
  * 
- * @summary Follow other users in a networked room
+ * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
  */
@@ -98,7 +99,7 @@ export class SpectatorCamera extends Behaviour {
     }
 
     /** Gets the local player's connection ID */
-    private get localId() : string {
+    private get localId(): string {
         return this.context.connection.connectionId ?? "local";
     }
 
@@ -196,9 +197,8 @@ export class SpectatorCamera extends Behaviour {
      */
     private isSupportedPlatform() {
         const ua = window.navigator.userAgent;
-        const standalone = /Windows|MacOS/.test(ua);
         const isHololens = /Windows NT/.test(ua) && /Edg/.test(ua) && !/Win64/.test(ua);
-        return standalone && !isHololens;
+        return DeviceUtilities.isDesktop() && !DeviceUtilities.isMobileDevice() && !isHololens;
     }
 
     /**
@@ -268,11 +268,16 @@ export class SpectatorCamera extends Behaviour {
         const previousRenderTarget = renderer.getRenderTarget();
         let oldFramebuffer: WebGLFramebuffer | null = null;
 
+
         const webglState = renderer.state as WebGLState & { bindXRFramebuffer?: Function };
 
+
         // seems that in some cases, renderer.getRenderTarget returns null
         // even when we're rendering to a headset.
-        if (!previousRenderTarget) {
+        if (!previousRenderTarget || 
+            // Prevent rendering if in XR - @TODO: check if we need to allow this for VR?
+            previousRenderTarget["isXRRenderTarget"] === true) 
+        {
             if (!renderer.state.bindFramebuffer || !webglState.bindXRFramebuffer)
                 return;
 
@@ -557,12 +562,18 @@ class SpectatorSelectionController {
             for (const hit of hits) {
                 if (hit.distance < .2) continue;
                 const obj = hit.object;
-                const avatar = GameObject.getComponentInParent(obj, AvatarMarker);
-                const id = avatar?.connectionId;
+                // For WebXR
+                const state = PlayerState.getFor(obj);
+                let id = state?.owner;
+                // for SpectatorCamera
+                if (!id) {
+                    const avatar = GameObject.getComponentInParent(obj, AvatarMarker);
+                    id = avatar?.connectionId;
+                }
                 if (id) {
                     const view = this.context.players.getPlayerView(id);
                     this.spectator.target = view;
-                    if (debug) console.log("spectate", id, avatar);
+                    if (debug) console.log("spectate", id, state);
                     break;
                 }
             }
@@ -633,7 +644,7 @@ class SpectatorCamNetworking {
         this.context.connection.beginListen("spectator-request-follow", this._requestFollowMethod);
         this.context.connection.beginListen(RoomEvents.JoinedRoom, this._joinedRoomMethod);
         this.context.domElement.addEventListener("keydown", evt => {
-            if(!this.spectator.useKeys) return;
+            if (!this.spectator.useKeys) return;
             if (evt.key === "f") {
                 this.onRequestFollowMe();
             }
@@ -767,7 +778,7 @@ class SpectatorCamNetworking {
     }
 
     private _enforceFollowInterval: any;
-    
+
     /**
      * Periodically retries following a user if the initial attempt failed
      */

package/src/engine-components/SpriteRenderer.ts

@@ -262,7 +262,8 @@ export class SpriteData {
  * 
  * - Example: https://engine.needle.tools/samples/spritesheet-animation
  * 
- * @category Sprites
+ * @summary Renders 2D images from a sprite sheet
+ * @category Rendering
  * @group Components
  */
 export class SpriteRenderer extends Behaviour {

package/src/engine-components/Voip.ts

@@ -14,7 +14,7 @@ const debugParam = getParam("debugvoip");
 /**
  * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
  * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
- * @summary Voice over IP (VoIP) for networked audio communication
+ * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
  */

package/src/engine-components/api.ts

@@ -35,7 +35,8 @@
  */
 
 export * from "./codegen/components.js";
-export { Behaviour, Component, GameObject } from "./Component.js"
+export { Behaviour, Component, GameObject } from "./Component.js";
+export { Collider } from "./Collider.js"; // export abstract type
 
 // We dont want to export everything in the extensions
 export { ClearFlags } from "./Camera.js"

package/src/engine-components/codegen/components.ts

@@ -23,7 +23,6 @@ export { BoxHelperComponent } from "../BoxHelperComponent.js";
 export { Camera } from "../Camera.js";
 export { CharacterController } from "../CharacterController.js";
 export { CharacterControllerInput } from "../CharacterController.js";
-export { Collider } from "../Collider.js";
 export { SphereCollider } from "../Collider.js";
 export { BoxCollider } from "../Collider.js";
 export { MeshCollider } from "../Collider.js";

package/src/engine-components/export/gltf/GltfExport.ts

@@ -30,6 +30,11 @@ export class GltfExportBox extends BoxHelperComponent {
 }
 
 /**
+ * GltfExport is a component that enables exporting selected 3D objects from the scene to the glTF format.  
+ * You can specify whether to export in binary format (.glb) or JSON format (.gltf), and select specific objects to include in the export.
+ * The exported glTF file can be used in various 3D applications and engines that support the glTF standard.
+ * 
+ * @summary Export selected 3D objects to glTF format
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -84,6 +84,7 @@ type BeforeLODExportArguments = {
  * usdz.autoExportAudioSources = true;
  * usdz.exportAsync();
  * ```
+ * @summary Export 3D objects as USDZ files for QuickLook
  * @category XR
  * @group Components
  */

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -692,7 +692,7 @@ class ParticlesEmissionState implements EmissionState {
  * 
  * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
  * 
- * @summary Particle System
+ * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
  */

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

@@ -30,7 +30,7 @@ export class SignalReceiverEvent {
  * Signals can be added to a signal track on a {@link PlayableDirector}
  * 
  * @summary Receives signals and invokes reactions
- * @category Sequencing and Timelines
+ * @category Animation and Sequencing
  * @group Components
  */
 export class SignalReceiver extends Behaviour {

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

@@ -64,7 +64,7 @@ class AnimationTriggers {
  * Button is a UI component that can be clicked by the user to perform an action.  
  * It supports different visual states such as normal, highlighted, pressed, and disabled.  
  * You can customize the button's appearance using colors or animations for each state.
- * @summary Button UI Component
+ * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
  */

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

@@ -29,7 +29,7 @@ const debugLayout = getParam("debuguilayout");
  * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
  * Canvases can be set to render in world space or screen space (overlay or camera).  
  * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
- * @summary Canvas UI Component
+ * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
  */

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

@@ -10,7 +10,7 @@ import { type ICanvasGroup, type IHasAlphaFactor } from "./Interfaces.js";
  * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.  
  * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.  
  * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
- * @summary CanvasGroup UI Component
+ * @summary Group UI elements to control transparency and interactivity
  * @category User Interface
  * @group Components
  */

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

@@ -37,7 +37,7 @@ onInitialized((ctx) => {
 
 /**
  * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
- * @summary UI Input Event System
+ * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components
  */

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

@@ -15,7 +15,7 @@ class Sprite {
  * Image is a UI component that displays a sprite (2D image) in the user interface.  
  * You can set the image property to assign a texture to be displayed.  
  * The sprite can be customized with various properties such as color tinting and pixel density.
- * @summary Image UI Component
+ * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
  */

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

@@ -13,7 +13,7 @@ const debug = getParam("debuginputfield");
  * InputField is a UI component that allows users to enter and edit text.  
  * It provides a text input area where users can type, delete, and modify text.  
  * The InputField supports placeholder text, events for value changes, and end edit actions.
- * @summary Text Input Field UI Component
+ * @summary Text field for user input
  * @category User Interface
  * @group Components
  */

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

@@ -7,7 +7,7 @@ import { Behaviour } from "../Component.js";
 /**
  * Outline is a UI component that adds an outline effect to UI elements.  
  * You can customize the outline color and distance to create a visual border around the UI element.
- * @summary Outline UI Component
+ * @summary Add an outline effect to UI elements
  * @category User Interface
  * @group Components
  */

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

@@ -31,7 +31,7 @@ export abstract class Raycaster extends Behaviour {
 /**
  * A Raycaster that performs raycasting against its own GameObject.  
  * 
- * @category Interaction
+ * @category Interactivity
  * @group Components
  */
 export class ObjectRaycaster extends Raycaster {
@@ -75,7 +75,8 @@ export class ObjectRaycaster extends Raycaster {
 /**
  * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
  * 
- * @category UI
+ * @summary Raycaster for UI elements
+ * @category User Interface
  * @group Components
  */
 export class GraphicRaycaster extends ObjectRaycaster {

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

@@ -29,6 +29,12 @@ const tempVec = new Vector3();
 const tempMatrix = new Matrix4();
 const tempQuaternion = new Quaternion();
 
+/** 
+* RectTransform is a component that defines a rectangle for UI layout. 
+* @summary UI Rectangle Transform
+* @category User Interface
+* @group Components
+*/
 export class RectTransform extends BaseUIComponent implements IRectTransform, IRectTransformChangedReceiver {
 
     get parent() {

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

@@ -6,6 +6,13 @@ import { serializable } from '../../engine/engine_serialization.js';
 import { getWorldRotation, setWorldRotationXYZ } from '../../engine/engine_three_utils.js';
 import { Behaviour } from '../Component.js';
 
+/**
+ * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.  
+ * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
+ * @summary Render HTML elements as 3D objects in the scene
+ * @category User Interface
+ * @group Components
+ */
 export class SpatialHtml extends Behaviour {
 
     @serializable()

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

@@ -41,6 +41,8 @@ export enum FontStyle {
 
 /**
  * Text is a UI component that displays text in the user interface.
+ * 
+ * @summary Display text in the UI
  * @category User Interface
  * @group Components
  */

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

@@ -13,7 +13,8 @@ import { Behaviour } from "../Component.js";
  * It can also invert the forward direction and keep the up direction.
  * 
  * @summary Makes the object look at a target object or the camera
- * @category Interactivity, Everywhere Actions
+ * @category Everywhere Actions
+ * @category Interactivity
  * @group Components
  */
 export class LookAt extends Behaviour implements UsdzBehaviour {

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

@@ -15,7 +15,7 @@ const debug = getParam("debugcursor");
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
  * 
  * @summary Makes the object follow the cursor position on screen
- * @category Web
+ * @category Interactivity
  * @group Components
  * @component
  */

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

@@ -14,7 +14,7 @@ import { Behaviour } from "../Component.js";
  * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
  * 
  * @summary Hover Animation on Pointer Enter/Exit
- * @category Web
+ * @category Interactivity
  * @group Components
  */
 @registerType

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

@@ -32,7 +32,7 @@ export type ViewBoxMode = "continuous" | "once";
  * ```
   
  * @summary Automatically fits a box area into the camera view
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  * @component
  */

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

@@ -12,6 +12,7 @@ import { Behaviour, GameObject } from "../Component.js";
 import { SyncedTransform } from "../SyncedTransform.js";
 import { AvatarMarker } from "./WebXRAvatar.js";
 import { XRFlag } from "./XRFlag.js";
+import { ViewDevice } from "../../engine/engine_playerview.js";
 
 const debug = getParam("debugwebxr");
 
@@ -55,10 +56,13 @@ export class Avatar extends Behaviour {
             const marker = this.gameObject.addComponent(AvatarMarker)!;
             marker.avatar = this.gameObject;
             marker.connectionId = playerstate.owner;
+
+            this.context.players.setPlayerView(playerstate.owner, this.head?.asset, ViewDevice.Headset);
         }
         else if (this.context.connection.isConnected) console.error("No player state found for avatar", this);
         // don't destroy the avatar when entering XR and not connected to a networking backend
         else if (playerstate && !this.context.connection.isConnected) playerstate.dontDestroy = true;
+
     }
 
     onLeaveXR(_args: NeedleXREventArgs): void {