@needle-tools/engine 4.14.0-next.31f837e → 4.14.0-next.52fdb13

package/src/engine/engine_math.ts

@@ -254,7 +254,40 @@ class LowPassFilter {
 }
 
 /**
- * OneEuroFilter is a simple low-pass filter for noisy signals. It uses a one-euro filter to smooth the signal.
+ * [OneEuroFilter](https://engine.needle.tools/docs/api/OneEuroFilter) is a low-pass filter designed to reduce jitter in noisy signals while maintaining low latency.
+ * It's particularly useful for smoothing tracking data from XR controllers, hand tracking, or other input devices where the signal contains noise but responsiveness is important.
+ *
+ * The filter automatically adapts its smoothing strength based on the signal's velocity:
+ * - When the signal moves slowly, it applies strong smoothing to reduce jitter
+ * - When the signal moves quickly, it reduces smoothing to maintain responsiveness
+ *
+ * Based on the research paper: [1€ Filter: A Simple Speed-based Low-pass Filter for Noisy Input](http://cristal.univ-lille.fr/~casiez/1euro/)
+ *
+ * @example Basic usage with timestamp
+ * ```ts
+ * const filter = new OneEuroFilter(120, 1.0, 0.0);
+ *
+ * // In your update loop:
+ * const smoothedValue = filter.filter(noisyValue, this.context.time.time);
+ * ```
+ *
+ * @example Without timestamps (using frequency estimate)
+ * ```ts
+ * // Assuming 60 FPS update rate
+ * const filter = new OneEuroFilter(60, 1.0, 0.5);
+ *
+ * // Call without timestamp - uses the frequency estimate
+ * const smoothedValue = filter.filter(noisyValue);
+ * ```
+ *
+ * @example Smoothing 3D positions
+ * ```ts
+ * const posFilter = new OneEuroFilterXYZ(90, 0.5, 0.0);
+ *
+ * posFilter.filter(trackedPosition, smoothedPosition, this.context.time.time);
+ * ```
+ *
+ * @see {@link OneEuroFilterXYZ} for filtering 3D vectors
  */
 export class OneEuroFilter {
     /**

package/src/engine/engine_networking.ts

@@ -1,5 +1,5 @@
 const defaultNetworkingBackendUrlProvider = "https://urls.needle.tools/default-networking-backend/index";
-let networkingServerUrl: string | undefined = "wss://networking.needle.tools/socket";
+let networkingServerUrl: string | undefined = "wss://networking-2.needle.tools/socket";
 
 import * as flatbuffers from 'flatbuffers';
 import { type Websocket } from 'websocket-ts';

package/src/engine/engine_types.ts

@@ -164,10 +164,15 @@ export interface IHasGuid {
     guid: string;
 }
 
+// DO NOT CHANGE THE SYMBOL NAME
+export const $componentName = Symbol("component-name");
+
 // TODO: we might want to separate the IComponent and IBehaviour where the Behaviour is the one with custom methods and the component only has e.g. the gameobject reference
 export interface IComponent extends IHasGuid {
     get isComponent(): boolean;
 
+    get [$componentName](): string | undefined;
+
     /** the object this component is attached to */
     gameObject: IGameObject;
     // guid: string;

package/src/engine/webcomponents/icons.ts

@@ -17,6 +17,9 @@ export function getIconElement(str: string): HTMLElement {
     span.innerText = str;
     span.style.visibility = "hidden";
     span.style.userSelect = "none";
+    span.setAttribute("role", "img");
+    span.setAttribute("aria-label", str + " icon");
+    span.setAttribute("aria-hidden", "true");
     fontReady(fontname).then(res => {
         if (res) span.style.visibility = "";
         else {

package/src/engine/webcomponents/logo-element.ts

@@ -84,8 +84,11 @@ export class NeedleLogoElement extends HTMLElement {
             globalThis.open("https://needle.tools", "_blank");
         });
 
-        // set title
+    }
+
+    connectedCallback() {
         this.wrapper.setAttribute("title", "Made with Needle Engine");
+        this.setAttribute("aria-label", "Needle Engine logo. Click to open the Needle Engine website.");
     }
 
     private readonly _root: ShadowRoot;

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/Camera.ts

@@ -132,7 +132,7 @@ export class Camera extends Behaviour implements ICamera {
      */
     get nearClipPlane(): number { return this._nearClipPlane; }
     @serializable()
-    set nearClipPlane(val) {
+    set nearClipPlane(val: number) {
         const changed = this._nearClipPlane != val;
         this._nearClipPlane = val;
         if (this._cam && (changed || this._cam.near != val)) {
@@ -149,7 +149,7 @@ export class Camera extends Behaviour implements ICamera {
      */
     get farClipPlane(): number { return this._farClipPlane; }
     @serializable()
-    set farClipPlane(val) {
+    set farClipPlane(val: number) {
         const changed = this._farClipPlane != val;
         this._farClipPlane = val;
         if (this._cam && (changed || this._cam.far != val)) {

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/DropListener.ts

@@ -181,7 +181,7 @@ export class DropListener extends Behaviour {
      * Only used when fitIntoVolume is enabled.
      */
     @serializable(Vector3)
-    fitVolumeSize = new Vector3(1, 1, 1);
+    fitVolumeSize: Vector3 = new Vector3(1, 1, 1);
 
     /** 
      * When enabled, dropped objects will be positioned at the point where the cursor hit the scene.

package/src/engine-components/Duplicatable.ts

@@ -66,7 +66,7 @@ export class Duplicatable extends Behaviour implements IPointerEventHandler {
      * @default 60
      */
     @serializable()
-    limitCount = 60;
+    limitCount: number = 60;
 
     private _currentCount = 0;
     private _startPosition: Vector3 | null = null;

package/src/engine-components/GroundProjection.ts

@@ -5,7 +5,10 @@ import { Gizmos } from "../engine/engine_gizmos.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getBoundingBox, getTempVector, getWorldScale, Graphics, setVisibleInCustomShadowRendering, setWorldPosition } from "../engine/engine_three_utils.js";
 import { delayForFrames, getParam, Watch as Watch } from "../engine/engine_utils.js";
+// Type-only imports for TSDoc @see links
+import type { Camera } from "./Camera.js";
 import { Behaviour } from "./Component.js";
+import type { ContactShadows } from "./ContactShadows.js";
 
 const debug = getParam("debuggroundprojection");
 

package/src/engine-components/NeedleMenu.ts

@@ -2,12 +2,15 @@ import type { Context } from '../engine/engine_context.js';
 import { serializable } from '../engine/engine_serialization.js';
 import { DeviceUtilities } from '../engine/engine_utils.js';
 import { Behaviour } from './Component.js';
+// Type-only imports for TSDoc @see links
+import type { ScreenCapture } from './ScreenCapture.js';
+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:**
@@ -15,7 +18,7 @@ import { Behaviour } from './Component.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,
@@ -33,6 +36,8 @@ import { Behaviour } from './Component.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/NestedGltf.ts

@@ -64,7 +64,7 @@ export class NestedGltf extends Behaviour {
      * EXPERIMENTAL for cloud asset loading
      */
     @serializable()
-    loadAssetInParent = true;
+    loadAssetInParent: boolean = true;
 
 
     private _isLoadingOrDoneLoading: boolean = false;

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;