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

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)"));