@needle-tools/engine 4.14.0 → 4.15.0-next.cecd8e7

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

@@ -13,32 +13,58 @@ const htmlTagName = "needle-button";
 const isDev = isDevEnvironment();
 
 /**
- * A <needle-button> can be used to simply add VR, AR or Quicklook buttons to your website without having to write any code.  
- * @example
+ * [&lt;needle-button&gt;](https://engine.needle.tools/docs/api/NeedleButtonElement) is a web component for easily adding AR, VR, Quicklook, or QR code buttons to your website without writing JavaScript code.
+ *
+ * The button automatically handles session management and displays appropriate UI based on device capabilities.
+ * It comes with default styling (glassmorphism design) but can be fully customized with CSS.
+ *
+ * **Supported button types:**
+ * - `ar` - WebXR AR session button
+ * - `vr` - WebXR VR session button
+ * - `quicklook` - Apple AR Quick Look button (iOS only)
+ * - `qrcode` - QR code sharing button
+ *
+ * @example Basic AR/VR buttons
  * ```html
+ * <needle-engine src="scene.glb"></needle-engine>
  * <needle-button ar></needle-button>
  * <needle-button vr></needle-button>
  * <needle-button quicklook></needle-button>
  * ```
- * 
- * @example custom label
+ *
+ * @example Custom button labels
  * ```html
- * <needle-button ar>Start AR</needle-button>
- * <needle-button vr>Start VR</needle-button>
+ * <needle-button ar>Start AR Experience</needle-button>
+ * <needle-button vr>Enter VR Mode</needle-button>
  * <needle-button quicklook>View in AR</needle-button>
  * ```
- * 
- * @example custom styling
+ *
+ * @example Custom styling
  * ```html
- * <!-- You can either style the element directly or use a CSS stylesheet -->
  * <style>
- * needle-button {
- *    background-color: red;
- *   color: white;
- * }
+ *   needle-button {
+ *     background-color: #ff6b6b;
+ *     color: white;
+ *     border-radius: 8px;
+ *     padding: 1rem 2rem;
+ *   }
+ *   needle-button:hover {
+ *     background-color: #ff5252;
+ *   }
  * </style>
  * <needle-button ar>Start AR</needle-button>
  * ```
+ *
+ * @example Unstyled button (for complete custom styling)
+ * ```html
+ * <needle-button ar unstyled>
+ *   <span class="my-icon">🥽</span>
+ *   Launch AR
+ * </needle-button>
+ * ```
+ *
+ * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
+ * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
 export class NeedleButtonElement extends HTMLElement {
 
@@ -73,18 +99,22 @@ export class NeedleButtonElement extends HTMLElement {
         if (this.getAttribute("ar") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createARButton();
+            this.setAttribute("aria-label", "Enter augmented reality mode");
         }
         else if (this.getAttribute("vr") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createVRButton();
+            this.setAttribute("aria-label", "Enter virtual reality mode");
         }
         else if (this.getAttribute("quicklook") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createQuicklookButton();
+            this.setAttribute("aria-label", "View in AR with Apple Quick Look");
         }
         else if (this.getAttribute("qrcode") != null) {
             this.#buttonfactory ??= new ButtonsFactory();
             this.#button = this.#buttonfactory.createQRCode({ anchorElement: this });
+            this.setAttribute("aria-label", "Share application with QR code");
         }
         else {
             if (isDev) {
@@ -93,6 +123,7 @@ export class NeedleButtonElement extends HTMLElement {
             else {
                 console.debug("No button type specified for <needle-button>. Use either ar, vr or quicklook attribute.")
             }
+            this.setAttribute("aria-label", "Needle Button with no specified type");
             return;
         }
 

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

@@ -87,17 +87,25 @@ const observedAttributes = [
 
 // https://developers.google.com/web/fundamentals/web-components/customelements
 
-/** 
- * The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
- * The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.   
- * The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.  
+/**
+ * The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes
+ * The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.
+ * The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.
  * The context is accessible from the `<needle-engine>` element: `document.querySelector("needle-engine").context`.
  * See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
  *
- * @example
+ * @example Basic usage
+ * ```html
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
- * @example
+ * ```
+ *
+ * @example With camera controls disabled
+ * ```html
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
+ * ```
+ *
+ * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
+ * @see {@link NeedleMenu} for the built-in menu configuration component
  */
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
@@ -176,7 +184,9 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
         ensureFonts();
 
-        this.attachShadow({ mode: 'open' });
+        this.attachShadow({ mode: 'open', delegatesFocus: true });
+        this.setAttribute("role", "application");
+        this.setAttribute("aria-label", "Needle Engine 3D scene");
         const template = document.createElement('template');
         // #region CSS
         template.innerHTML = `<style>
@@ -282,6 +292,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (this.getAttribute("tabindex") === null || this.getAttribute("tabindex") === undefined)
             this.setAttribute("tabindex", "0");
 
+
         this.addEventListener("xr-session-started", this.onXRSessionStarted);
         this.onSetupDesktop();
 

package/src/engine-components/Component.ts

@@ -10,7 +10,7 @@ import * as main from "../engine/engine_mainloop_utils.js";
 import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
 import * as threeutils from "../engine/engine_three_utils.js";
-import type { Collision, ComponentInit, Constructor, ConstructorConcrete, GuidsMap, ICollider, IComponent, IGameObject, SourceIdentifier } from "../engine/engine_types.js";
+import { $componentName, type Collision, type ComponentInit, type Constructor, type ConstructorConcrete, type GuidsMap, type ICollider, type IComponent, type IGameObject, type SourceIdentifier } from "../engine/engine_types.js";
 import { TypeStore } from "../engine/engine_typestore.js";
 import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
 import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
@@ -542,8 +542,6 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 }
 
-// DO NOT CHANGE THE SYMBOL NAME
-const $componentName = Symbol("component-name");
 
 /** 
  * Needle Engine component's are the main building blocks of the Needle Engine.    

package/src/engine-components/DragControls.ts

@@ -193,7 +193,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
         }
     }
-    
+
     private _rigidbody: Rigidbody | null = null;
 
     // future:
@@ -235,12 +235,22 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     /** @internal */
     onEnable(): void {
         DragControls._instances.push(this);
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Drag " + (this.gameObject.name || "object"),
+            hidden: false,
+        });
     }
     /** @internal */
     onDisable(): void {
+        this.context.accessibility.updateElement(this, { hidden: true });
         DragControls._instances = DragControls._instances.filter(i => i !== this);
     }
 
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
+    }
+
     /**
      * Checks if editing is allowed for the current networking connection.
      * @param _obj Optional object to check edit permissions for
@@ -268,6 +278,8 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         if (!dc || dc !== this) return;
         DragControls.lastHovered = evt.object;
         this.context.domElement.style.cursor = 'pointer';
+
+        this.context.accessibility.hover(this, `Draggable ${evt.object?.name}`);
     }
 
     /** 
@@ -339,6 +351,14 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
 
             args.use();
+
+            this.context.accessibility.updateElement(this, {
+                role: "button",
+                label: "Dragging " + (this.gameObject.name || "object"),
+                hidden: false,
+                busy: true,
+            });
+            this.context.accessibility.focus(this);
         }
     }
 
@@ -375,6 +395,11 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
             args.use();
         }
+
+        this.context.accessibility.unfocus(this);
+        this.context.accessibility.updateElement(this, {
+            busy: false,
+        });
     }
 
     /**
@@ -779,12 +804,12 @@ class DragPointerHandler implements IDragHandler {
      * Used for determining if enough motion has occurred to start a drag.
      */
     getTotalMovement(): Vector3 { return this._totalMovement; }
-    
+
     /** 
      * Returns the object that follows the pointer during dragging operations.
      */
     get followObject(): GameObject { return this._followObject; }
-    
+
     /**
      * Returns the point where the pointer initially hit the object in local space.
      */
@@ -1377,7 +1402,7 @@ class LegacyDragVisualsHelper {
 
     /** Controls whether visual helpers like lines and markers are displayed */
     showGizmo: boolean = true;
-    
+
     /** When true, drag plane alignment changes based on view angle */
     useViewAngle: boolean = true;
 

package/src/engine-components/NeedleMenu.ts

@@ -9,8 +9,8 @@ import type { Voip } from './Voip.js';
 /**
  * [NeedleMenu](https://engine.needle.tools/docs/api/NeedleMenu) provides configuration for the built-in UI menu.
  * The menu renders as HTML overlay in browser mode and automatically
- * switches to a 3D spatial menu in VR/AR.    
- * 
+ * switches to a 3D spatial menu in VR/AR.
+ *
  * ![](https://cloud.needle.tools/-/media/YKleg1oPy_I8Hv8sg_k40Q.png)
  *
  * **Features:**
@@ -18,7 +18,7 @@ import type { Voip } from './Voip.js';
  * - Audio mute/unmute button
  * - QR code sharing (desktop only)
  * - Spatial menu in XR (appears when looking up)
- * - Custom positioning (top/bottom)  
+ * - Custom positioning (top/bottom)
  *
  * **Programmatic access:**
  * Access the menu API via `this.context.menu` to add custom buttons,
@@ -36,6 +36,8 @@ import type { Voip } from './Voip.js';
  * @category User Interface
  * @group Components
  * @see {@link Context.menu} for programmatic menu control
+ * @see {@link NeedleButtonElement} for standalone <needle-button> web component
+ * @see {@link NeedleEngineWebComponent} for the main <needle-engine> element
  * @see {@link Voip} adds a microphone button to the menu
  * @see {@link ScreenCapture} adds a screen sharing button
  **/

package/src/engine-components/Networking.ts

@@ -7,10 +7,34 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugnet");
 
 /**
- * Provides configuration to the built-in networking system.
- * This component supplies websocket URLs for establishing connections.
- * It implements the {@link INetworkingWebsocketUrlProvider} interface.
- * 
+ * Provides websocket URL configuration for the built-in networking system.
+ * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
+ *
+ * The component registers itself as a URL provider on `awake()`. When the networking system connects,
+ * it queries this provider for the websocket URL to use instead of the default Needle networking backend.
+ *
+ * **URL resolution order:**
+ * 1. If `urlParameterName` is set and the corresponding URL parameter exists in the browser URL, that value is used
+ * 2. If running on a local network and `localhost` is set, the `localhost` URL is used
+ * 3. Otherwise, the `url` field is used
+ *
+ * Without this component, the default backend URL `wss://networking-2.needle.tools/socket` is used.
+ *
+ * **Note:** This component only configures the websocket URL. To actually join a networked room,
+ * use a `SyncedRoom` component or call `this.context.connection.joinRoom("room-name")` directly.
+ *
+ * @example Overriding the URL via browser parameter
+ * ```ts
+ * // With urlParameterName="server", visiting:
+ * // https://myapp.com/?server=wss://my-server.com/socket
+ * // will connect to that server instead
+ * ```
+ *
+ * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
+ * @see {@link SyncedRoom} for automatic room joining
+ * @see {@link OwnershipModel} for networked object ownership
+ * @see {@link RoomEvents} for room lifecycle events
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
  * @summary Networking configuration
  * @category Networking
  * @group Components
@@ -20,6 +44,7 @@ export class Networking extends Behaviour implements INetworkingWebsocketUrlProv
     /** 
      * The websocket URL to connect to for networking functionality.
      * Can be a complete URL or a relative path that will be resolved against the current origin.
+     * @default null
      */
     @serializable()
     url: string | null = null;

package/src/engine-components/ReflectionProbe.ts

@@ -2,10 +2,11 @@ import { Color, CubeReflectionMapping, CubeTexture, EquirectangularReflectionMap
 
 import { isDevEnvironment, showBalloonWarning } from "../engine/debug/index.js";
 import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
+import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
 import type { IRenderer } from "../engine/engine_types.js";
-import { getParam } from "../engine/engine_utils.js";
+import { getParam, resolveUrl } from "../engine/engine_utils.js";
 import { BoxHelperComponent } from "./BoxHelperComponent.js";
 import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
@@ -90,10 +91,28 @@ export class ReflectionProbe extends Behaviour {
     }
 
     private _texture!: Texture;
+    private _textureUrlInFlight?: string;
 
-    @serializable(Texture)
+    @serializable([Texture, String])
     set texture(tex: Texture) {
         if (this._texture === tex) return;
+
+        if (typeof tex === "string") {
+            if(debug) console.debug(`[ReflectionProbe] Loading reflection probe texture from URL: ${tex}`);
+            this._textureUrlInFlight = tex;
+            const textureUrl = resolveUrl(this.sourceId, tex);
+            loadPMREM(textureUrl, this.context.renderer).then(loaded => {
+                if (this._textureUrlInFlight === tex && loaded) {
+                    this._textureUrlInFlight = undefined;
+                    if (debug) console.debug(`[ReflectionProbe] Successfully loaded reflection probe texture: ${tex}`);
+                    this.texture = loaded;
+                }
+            });
+            return;
+        }
+
+        this._textureUrlInFlight = undefined;
+
         this._texture = tex;
 
         if (debug) console.debug("[ReflectionProbe] Set reflection probe texture " + (tex?.name || "(removed)"));