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

package/src/engine/engine_materialpropertyblock.ts

@@ -1,4 +1,4 @@
-import { Material, Object3D, Color, Texture, Vector2, Vector3, Vector4, WebGLRenderer, Scene, Camera, BufferGeometry, Group, Euler } from "three";
+import { BufferGeometry, Camera, Color, Euler,Group, Material, Object3D, Scene, Texture, Vector2, Vector3, Vector4, WebGLRenderer } from "three";
 
 
 // @TODO: we need to detect objects with materials both transparent and NOT transparent. These need to be updated in scene.onBeforeRender to have correct renderlists
@@ -122,17 +122,26 @@ class PropertyBlockRegistry {
 const registry = new PropertyBlockRegistry();
 
 /**
- * MaterialPropertyBlock allows per-object material property overrides without creating new material instances.  
- * This is useful for rendering multiple objects with the same base material but different properties  
- * (e.g., different colors, textures, or shader parameters).  
+ * MaterialPropertyBlock allows per-object material property overrides without creating new material instances.
+ * This is useful for rendering multiple objects with the same base material but different properties
+ * (e.g., different colors, textures, or shader parameters).
  *
- * The property block system works by:  
+ * ## How Property Blocks Work
+ *
+ * **Important**: Overrides are registered on the **Object3D**, not on the material.
+ * This means:
+ * - If you change the object's material, the overrides will still be applied to the new material
+ * - Multiple objects can share the same material but have different property overrides
+ * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOveride}, {@link clearAllOverrides}, or {@link dispose}
+ *
+ * The property block system works by:
  * - Temporarily applying overrides in onBeforeRender
  * - Restoring original values in onAfterRender
  * - Managing shader defines and program cache keys for correct shader compilation
  * - Supporting texture coordinate transforms per object
  *
- * Common use cases:
+ * ## Common Use Cases
+ *
  * - **Lightmaps**: Apply unique lightmap textures to individual objects sharing the same material
  * - **Reflection Probes**: Apply different environment maps per object for localized reflections
  * - **See-through effects**: Temporarily override transparency/transmission properties for X-ray effects
@@ -170,6 +179,26 @@ const registry = new PropertyBlockRegistry();
  * block.setDefine("USE_CUSTOM_FEATURE", 1);
  * ```
  *
+ * @example Material swapping behavior
+ * ```typescript
+ * const mesh = new Mesh(geometry, materialA);
+ * const block = MaterialPropertyBlock.get(mesh);
+ * block.setOverride("color", new Color(1, 0, 0));
+ *
+ * // The color override is red for materialA
+ *
+ * // Swap the material - overrides persist and apply to the new material!
+ * mesh.material = materialB;
+ * // The color override is now red for materialB too
+ *
+ * // If you don't want overrides on the new material, remove them:
+ * block.clearAllOverrides(); // Remove all overrides
+ * // or
+ * block.removeOveride("color"); // Remove specific override
+ * // or
+ * block.dispose(); // Remove the entire property block
+ * ```
+ *
  * @example Lightmap usage
  * ```typescript
  * const block = MaterialPropertyBlock.get(mesh);
@@ -317,8 +346,25 @@ export class MaterialPropertyBlock<T extends Material = Material> {
     }
 
     /**
-     * Removes a specific property override
-     * @param name The property name to clear
+     * Removes a specific property override.
+     * After removal, the material will use its original property value for this property.
+     *
+     * @param name The property name to remove the override for
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Set some overrides
+     * block.setOverride("color", new Color(1, 0, 0));
+     * block.setOverride("roughness", 0.5);
+     * block.setOverride("lightMap", lightmapTexture);
+     *
+     * // Remove a specific override - the material will now use its original color
+     * block.removeOveride("color");
+     *
+     * // Other overrides (roughness, lightMap) remain active
+     * ```
      */
     removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void {
         const index = this._overrides.findIndex(o => o.name === name);
@@ -328,7 +374,47 @@ export class MaterialPropertyBlock<T extends Material = Material> {
     }
 
     /**
-     * Removes all property overrides from this block
+     * Removes all property overrides from this block.
+     * After calling this, the material will use its original values for all properties.
+     *
+     * **Note**: This does NOT remove shader defines. Use {@link clearDefine} or {@link dispose} for that.
+     *
+     * @example Remove all overrides but keep the property block
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Set multiple overrides
+     * block.setOverride("color", new Color(1, 0, 0));
+     * block.setOverride("roughness", 0.5);
+     * block.setOverride("lightMap", lightmapTexture);
+     *
+     * // Later, remove all overrides at once
+     * block.clearAllOverrides();
+     *
+     * // The material now uses its original values
+     * // The property block still exists and can be reused with new overrides
+     * ```
+     *
+     * @example Temporarily disable all overrides
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(mesh);
+     *
+     * // Save current overrides if you want to restore them later
+     * const savedOverrides = [...block.overrides];
+     *
+     * // Clear all overrides temporarily
+     * block.clearAllOverrides();
+     *
+     * // Do some rendering without overrides...
+     *
+     * // Restore overrides
+     * savedOverrides.forEach(override => {
+     *   block.setOverride(override.name, override.value, override.textureTransform);
+     * });
+     * ```
+     *
+     * @see {@link removeOveride} - To remove a single override
+     * @see {@link dispose} - To completely remove the property block and clean up resources
      */
     clearAllOverrides(): void {
         this._overrides = [];
@@ -797,11 +883,11 @@ function attachPropertyBlockToObject(object: Object3D, _propertyBlock: MaterialP
     if (object.type === "Group") {
         object.children.forEach(child => {
             if (child.type === "Mesh" || child.type === "SkinnedMesh") {
-                attachCallbacksToMesh(child, object);
+                attachCallbacksToMesh(child, object, _propertyBlock);
             }
         });
     } else if (object.type === "Mesh" || object.type === "SkinnedMesh") {
-        attachCallbacksToMesh(object, object);
+        attachCallbacksToMesh(object, object, _propertyBlock);
     }
 }
 /**
@@ -811,7 +897,7 @@ function attachPropertyBlockToObject(object: Object3D, _propertyBlock: MaterialP
  * @param propertyBlockOwner The object that owns the property block (may be the mesh itself or its parent Group)
  * @internal
  */
-function attachCallbacksToMesh(mesh: Object3D, propertyBlockOwner: Object3D): void {
+function attachCallbacksToMesh(mesh: Object3D, propertyBlockOwner: Object3D, _propertyBlock: MaterialPropertyBlock): void {
     // Check if this specific mesh already has our callbacks attached for this property block owner
     if (registry.isHooked(mesh, propertyBlockOwner)) {
         // Already hooked for this property block owner
@@ -820,6 +906,11 @@ function attachCallbacksToMesh(mesh: Object3D, propertyBlockOwner: Object3D): vo
 
     registry.addHook(mesh, propertyBlockOwner);
 
+    /**
+     * Expose the property block for e.g. Needle Inspector
+     */
+    mesh["needle:materialPropertyBlock"] = _propertyBlock;
+
     if (!mesh.onBeforeRender) {
         mesh.onBeforeRender = onBeforeRender_MaterialBlock;
     } else {

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

@@ -5,9 +5,9 @@ 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";
-import { Behaviour } from "./Component.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

@@ -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;