@needle-tools/engine 4.11.4 → 4.11.5-next.4201116

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

@@ -16,6 +16,12 @@ import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overl
 import { NeedleEngineAttributes, TonemappingAttributeOptions } from "./needle-engine.attributes.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-engine": NeedleEngineWebComponent;
+    }
+}
+
 // registering loader here too to make sure it's imported when using engine via vanilla js
 registerLoader(NeedleLoader);
 
@@ -55,17 +61,17 @@ const observedAttributes = [
 // https://developers.google.com/web/fundamentals/web-components/customelements
 
 /** 
- * <needle-engine> web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
- * The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.   
- * The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
- * The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context).
+ * 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
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
  * @example
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
-*/
+ */
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
     static get observedAttributes() {
@@ -100,7 +106,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         else this.setAttribute("camera-controls", value ? "true" : "false");
     }
 
-
     /**
      * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.  
      * The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
@@ -133,7 +138,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
     private _previousSrc: string | null | string[] = null;
-    /** set to true after <needle-engine> did load completely at least once. Set to false when <needle-engine> is removed from the document */
+    /** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
     private _didFullyLoad: boolean = false;
 
     constructor() {
@@ -296,6 +301,10 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         }
     }
 
+    connectedMoveCallback() {
+        // we dont want needle-engine to cleanup JUST because the element is moved in the DOM. See https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+    }
+
     /**
      * @internal
      */
@@ -317,7 +326,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "loadfinished":
                 if (typeof newValue === "string" && newValue.length > 0) {
                     if (debug) console.log(name + " attribute changed", newValue);
-                    this.registerEventFromAttribute(name, newValue);
+                    this.registerEventFromAttribute("loadfinished", newValue);
                 }
                 break;
             case "dracoDecoderPath":
@@ -441,7 +450,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (allowOverridingDefaultLoading) {
             // Handle the <needle-engine hide-loading-overlay> attribute
             const hideOverlay = this.getAttribute("hide-loading-overlay");
-            if (hideOverlay !== null && hideOverlay !== undefined && hideOverlay !== "0") {
+            if (hideOverlay !== null && hideOverlay !== undefined && (hideOverlay as any) !== "0") {
                 useDefaultLoading = false;
             }
         }
@@ -668,7 +677,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (attributeValue)
             this.registerEventFromAttribute("loadstart", attributeValue);
     }
-    private registerEventFromAttribute(eventName: string, code: string) {
+    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart', code: string) {
         const prev = this._previouslyRegisteredMap.get(eventName);
         if (prev) {
             this._previouslyRegisteredMap.delete(eventName);
@@ -681,6 +690,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
                 // const fn = new Function(newValue);
                 if (typeof fn === "function") {
                     this._previouslyRegisteredMap.set(eventName, fn);
+                    // @ts-ignore // not sure how to type this properly
                     this.addEventListener(eventName, evt => fn?.call(globalThis, this._context, evt));
                 }
             }
@@ -828,15 +838,157 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             setKtx2TranscoderPath(customKtx2DecoderPath);
         }
     }
+
+    /** Change which model gets loaded. This will trigger a reload of the model. */
+    setAttribute(name: 'src', value: string | string[]): void;
+    /** Optional string that will be applied to the context as a hash and can influence caching/identification. */
+    setAttribute(name: 'hash', value: string): void;
+    /** Public key used for licensing and feature gating (read-only on runtime if compiled-in). */
+    setAttribute(name: 'public-key', value: string): void;
+    /** Engine version string — usually set by the build/runtime. */
+    setAttribute(name: 'version', value: string): void;
+    /** If set to false the camera controls are disabled. Accepted values: true/false/none. Default behaviour is enabled. */
+    setAttribute(name: 'camera-controls', value: string): void;
+    /** Override path for the Draco decoder files. */
+    setAttribute(name: 'dracoDecoderPath', value: string): void;
+    /** Choose Draco decoder type: 'wasm' or 'js'. */
+    setAttribute(name: 'dracoDecoderType', value: 'wasm' | 'js'): void;
+    /** Override path for the KTX2 transcoder/decoder files. */
+    setAttribute(name: 'ktx2DecoderPath', value: string): void;
+    /** Tonemapping mode. Accepted values: 'none' | 'linear' | 'agx' | 'neutral'. */
+    setAttribute(name: 'tone-mapping', value: 'none' | 'linear' | 'agx' | 'neutral'): void;
+    /** Numeric exposure multiplier for tonemapping; accepts number or stringified number. */
+    setAttribute(name: 'tone-mapping-exposure', value: string | number): void;
+    /** Background image blur strength (0..1). Accepts number or string value. */
+    setAttribute(name: 'background-blurriness', value: string | number): void;
+    /** CSS color for the background; string color value expected (e.g. '#fff', 'rgba()' etc). */
+    setAttribute(name: 'background-color', value: string): void;
+    /** Intensity multiplier for environment lighting; accepts numeric value or string. */
+    setAttribute(name: 'environment-intensity', value: string | number): void;
+    /** When true the engine context is kept alive after the element is removed from DOM. Use 'true' or 'false'. */
+    setAttribute(name: 'keep-alive', value: 'true' | 'false'): void;
+    /** Generic typed setter for known Needle Engine attributes (useful from TS):
+     *  setAttribute<T extends keyof NeedleEngineAttributes>(name, value) will type-check against the declared attribute shape.
+     */
+    setAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T, value: NeedleEngineAttributes[T]): void;
+    setAttribute(qualifiedName: ({} & string), value: string): void;
+    setAttribute(qualifiedName: string, value: string): void {
+        super.setAttribute(qualifiedName, value);
+    }
+
+    /** Read the `src` attribute. Returns string, string[] (if codegen provided an array) or null if unset. */
+    getAttribute(name: 'src'): string | string[] | null;
+    /** Read the `hash` attribute — an optional string attached to the context for caching/identification. */
+    getAttribute(name: 'hash'): string | null;
+    /** Read the `public-key` attribute used for licensing/feature gating. */
+    getAttribute(name: 'public-key'): string | null;
+    /** Read the `version` attribute — the engine build/version string. */
+    getAttribute(name: 'version'): string | null;
+    /** Read the `camera-controls` attribute; string values include 'true'|'false'|'none' or null if unset. */
+    getAttribute(name: 'camera-controls'): string | null;
+    /** Read custom Draco decoder path if configured. */
+    getAttribute(name: 'dracoDecoderPath'): string | null;
+    /** Read Draco decoder type ('wasm'|'js') if configured. */
+    getAttribute(name: 'dracoDecoderType'): string | null;
+    /** Read custom KTX2 decoder/transcoder path if configured. */
+    getAttribute(name: 'ktx2DecoderPath'): string | null;
+    /** Read configured tone-mapping value, as a string matching accepted modes (none, linear, neutral, agx). */
+    getAttribute(name: 'tone-mapping'): string | null;
+    /** Read tone-mapping exposure multiplier (string or numeric string). */
+    getAttribute(name: 'tone-mapping-exposure'): string | null;
+    /** Read background-blurriness value (0..1) as string or null. */
+    getAttribute(name: 'background-blurriness'): string | null;
+    /** Read CSS background-color string value (e.g. '#fff', 'rgba()'). */
+    getAttribute(name: 'background-color'): string | null;
+    /** Read environment-intensity (numeric) as string or null. */
+    getAttribute(name: 'environment-intensity'): string | null;
+    /** Read keep-alive attribute; presence ("true") prevents the context from being disposed on disconnect. */
+    getAttribute(name: 'keep-alive'): string | null;
+    /** Defines a CSS selector or HTMLElement used to define the camera focus rectangle. */
+    getAttribute(name: 'focus-rect'): string | null;
+    /** @private */
+    getAttribute(name: 'loading-blur'): string | null;
+    /** @private */
+    getAttribute(name: 'alias'): string | null;
+    /** Typed getter for known NeedleEngine attribute names; returns the typed shape declared in NeedleEngineAttributes or null. */
+    getAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T): NeedleEngineAttributes[T] | null;
+    // getAttribute(qualifiedName: ({} & string)): string | null
+    getAttribute(qualifiedName: ({} & string)): string | null;
+    getAttribute(qualifiedName: string): string | null {
+        return super.getAttribute(qualifiedName);
+    }
+
+    /**
+     * Emitted when loading begins for the engine/scene. The event is cancelable — calling preventDefault() 
+     * will stop the default loading UI behavior (apps can implement custom loading flows).
+    * Event contains a small detail object with context and optional alias.
+     */
+    addEventListener(type: 'loadstart', listener: (ev: CustomEvent<{ context: Context; alias: string | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Emitted repeatedly while loading resources. Use the event detail to show progress: 
+    * Event contains progress metadata to report loader state.
+     */
+    addEventListener(type: 'progress', listener: (ev: CustomEvent<{ context: Context; name: string; progress: ProgressEvent<EventTarget>; index: number; count: number; totalProgress01: number }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Emitted when the initial loading has finished. detail contains the context, the source alias (if available) and a list of loaded models.
+    * Emitted when the initial load completes; contains helpful summary data.
+     */
+    addEventListener(type: 'loadfinished', listener: (ev: CustomEvent<{ context: Context; src: string | null; loadedFiles: LoadedModel[] }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when an XR session ends.
+     */
+    addEventListener(type: 'xr-session-ended', listener: (ev: CustomEvent<{ session: XRSession | null; context: Context; sessionMode: XRSessionMode | undefined }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when entering AR.
+     */
+    addEventListener(type: 'enter-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when exiting AR.
+     */
+    addEventListener(type: 'exit-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when entering VR.
+     */
+    addEventListener(type: 'enter-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+    * Emitted when exiting VR.
+     */
+    addEventListener(type: 'exit-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when the engine has rendered its first frame and is ready. */
+    addEventListener(type: 'ready', listener: (ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when an XR session is started — useful to prepare AR/VR UI. */
+    addEventListener(type: 'xr-session-started', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+
+    // Sadly not enough to make types work (see comment below)
+    addEventListener<K extends keyof HTMLElementEventMap>(type: ({} & K), listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    // These are from the super type. Not sure how we can remove intellisense for the "regular" events while still making the types work...
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+
+    addEventListener(type: string, listener: any, options?: boolean | AddEventListenerOptions): void
+    {
+        return super.addEventListener(type, listener as EventListenerOrEventListenerObject, options);
+    }
 }
 
 if (typeof window !== "undefined" && !window.customElements.get(htmlTagName))
     window.customElements.define(htmlTagName, NeedleEngineWebComponent);
 
+/** Usage of the types declared above */
 
+const elem = document.querySelector("needle-engine")!;
+elem.setAttribute("src", "model.glb");
+elem.addEventListener("loadfinished", (ev) => {
+    const context = ev.detail.context;
+});
+elem.setAttribute("dracoDecoderType", "wasm");
+elem.addEventListener("enter-ar", (ev) => {
+    const session = ev.detail.session;
+});
 
-
-
+elem.addEventListener("mousedown", (ev) => {
+    console.log("regular mousedown event", ev);
+});
 
 function getDisplayName(str: string) {
     if (str.startsWith("blob:")) {
@@ -956,4 +1108,4 @@ function handleLoadingBlur(needleEngineElement: NeedleEngineWebComponent) {
             }
         }
     }, { once: true });
-}
+}

package/src/engine/xr/NeedleXRSession.ts

@@ -527,7 +527,9 @@ export class NeedleXRSession implements INeedleXRSession {
         else
             console.log("%c" + `Requesting ${mode} session`, "font-weight:bold;");
         for (const script of scripts) {
-            if (script.onBeforeXR) script.onBeforeXR(mode, init);
+            if (script.onBeforeXR && script.activeAndEnabled && !script.destroyed) {
+                script.onBeforeXR(mode, init);
+            }
         }
         for (const listener of this._sessionRequestStartListeners) {
             listener({ mode, init });

package/src/engine-components/AlignmentConstraint.ts

@@ -4,6 +4,15 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * Aligns this GameObject between two other GameObjects, scaling it to fit the distance.  
+ * You can use this to create dynamic beams or connectors between objects.
+ *
+ * @summary Aligns and scales the object between two target GameObjects
+ * @category Utility
+ * @group Components 
+ 
+ **/
 export class AlignmentConstraint extends Behaviour {
 
     @serializable(GameObject)

package/src/engine-components/Animator.ts

@@ -14,6 +14,7 @@ const debug = getParam("debuganimator");
 /** 
  * Represents an event emitted by an animation mixer
  * @category Animation and Sequencing
+ * @group Components
  */
 export declare class MixerEvent {
     /** The type of event that occurred */

package/src/engine-components/AudioListener.ts

@@ -8,6 +8,8 @@ import { Behaviour, GameObject } from "./Component.js";
  * AudioListener represents a listener that can hear audio sources in the scene.
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
+ * 
+ * @summary Audio listener for 3D audio capture
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AudioSource.ts

@@ -52,6 +52,7 @@ export enum AudioRolloffMode {
  * is muted, the volume is set to 0. When unmuted, the volume
  * returns to its previous value.
  * 
+ * @summary 3D audio source with spatial positioning and playback controls
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AxesHelper.ts

@@ -7,6 +7,8 @@ import { Behaviour } from "./Component.js";
 /**
  * Component that visualizes the axes of an object in the scene.
  * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
+ * 
+ * @summary Visualizes object axes in the scene
  * @category Helpers
  * @group Components
  */

package/src/engine-components/Camera.ts

@@ -36,6 +36,7 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
+ * @summary Camera rendering scenes from a specific viewpoint
  * @category Camera
  * @group Components
  */

package/src/engine-components/CharacterController.ts

@@ -14,7 +14,10 @@ import { Rigidbody } from "./RigidBody.js";
 const debug = getParam("debugcharactercontroller");
 
 /**
- * @category Camera
+ * CharacterController adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.  
+ * It is designed for typical character movement in 3D environments.
+ * @summary Character Movement Controller
+ * @category Character  
  * @group Components
  */
 export class CharacterController extends Behaviour {

package/src/engine-components/Component.ts

@@ -11,6 +11,7 @@ import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/
 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 { TypeStore } from "../engine/engine_typestore.js";
 import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
 import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
 
@@ -540,7 +541,8 @@ 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.    
@@ -581,6 +583,12 @@ export abstract class Component implements IComponent, EventTarget,
      */
     get isComponent(): boolean { return true; }
 
+    /**
+     * Get the original component type name before minification (available if the component is registered in the TypeStore)
+     */
+    get [$componentName]() { return TypeStore.getKey(this.constructor as any) || undefined; }
+
+    
     private __context: Context | undefined;
 
     /**

package/src/engine-components/DeleteBox.ts

@@ -11,6 +11,8 @@ import { UsageMarker } from "./Interactable.js";
 const debug = getParam("debugdeletable");
 /**
  * A box-shaped area that can be used to delete objects that get into it. Useful for sandbox-style builders or physics simulations.
+ * 
+ * @summary Box area that deletes objects entering it
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/DeviceFlag.ts

@@ -11,6 +11,10 @@ export enum DeviceType {
 }
 
 /**
+ * Enables or disables the GameObject based on the device type (mobile or desktop).  
+ * You can use this to show or hide objects depending on whether the user is on a mobile device or a desktop.
+ * 
+ * @summary Show or hide GameObject based on device type
  * @category Utilities
  * @group Components
  */

package/src/engine-components/DragControls.ts

@@ -46,6 +46,7 @@ export enum DragMode {
  * DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space).
  * Debug mode can be enabled with the URL parameter `?debugdrag`, which shows visual helpers and logs drag operations.
  * 
+ * @summary Enables dragging of objects in 2D or 3D space
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/DropListener.ts

@@ -139,6 +139,7 @@ const blobKeyName = "blob";
  * });
  * ```
  * 
+ * @summary Component to handle drag and drop of files into the scene
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/Duplicatable.ts

@@ -14,6 +14,7 @@ import { ObjectRaycaster } from "./ui/Raycaster.js";
 /**
  * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
  *  
+ * @summary Duplicates a GameObject on pointer events
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/EventTrigger.ts

@@ -14,6 +14,8 @@ class TriggerEvent {
 /**
  * The EventTrigger component is used to trigger events when certain pointer events occur on the GameObject.
  * It implements the {@link IPointerEventHandler} interface and can be used to expose events to the user in the editor without writing code.
+ * 
+ * @summary Triggers events on pointer interactions
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/GridHelper.ts

@@ -6,6 +6,8 @@ import { Behaviour } from "./Component.js";
 
 /**
  * GridHelper is a component that allows to display a grid in the scene.
+ * 
+ * @example Display a grid in the scene
  * @category Helpers
  * @group Components
  */

package/src/engine-components/GroundProjection.ts

@@ -14,6 +14,7 @@ const debug = getParam("debuggroundprojection");
  * 
  * - Example https://engine.needle.tools/samples/ground-projection
  * 
+ * @summary Projects the environment map onto the ground
  * @category Rendering
  * @group Components
  */

package/src/engine-components/LODGroup.ts

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

package/src/engine-components/Light.ts

@@ -75,6 +75,7 @@ enum LightShadows {
  * Debug mode can be enabled with the URL parameter `?debuglights`, which shows
  * additional console output and visual helpers for lights.
  * 
+ * @summary Light component for various light types and shadow settings
  * @category Rendering
  * @group Components
  */

package/src/engine-components/LookAtConstraint.ts

@@ -8,6 +8,7 @@ import type { OrbitControls } from "./OrbitControls.js";
  * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
  * This component is used by {@link OrbitControls} internally.
  * 
+ * @summary Look At Constraint for OrbitControls
  * @category Camera Controls
  * @group Components
  */

package/src/engine-components/NeedleMenu.ts

@@ -10,6 +10,7 @@ import { Behaviour } from './Component.js';
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
  * 
+ * @summary Configuration component for the Needle Menu
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -11,6 +11,7 @@ const debug = getParam("debugnestedgltf");
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
  * 
+ * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/Networking.ts

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

package/src/engine-components/OffsetConstraint.ts

@@ -4,6 +4,13 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * OffsetConstraint component allows an object to maintain a specified positional and rotational offset 
+ * relative to another object, with options for alignment and leveling.
+ * @summary Maintains positional and rotational offset relative to another object
+ * @category Constraints
+ * @group Components
+ */
 export class OffsetConstraint extends Behaviour {
 
     @serializable(GameObject)

package/src/engine-components/OrbitControls.ts

@@ -63,6 +63,7 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
 /** The OrbitControls component is used to control a camera using the [OrbitControls from three.js](https://threejs.org/docs/#examples/en/controls/OrbitControls) library.  
  * 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
  * @group Components
  */

package/src/engine-components/PlayerColor.ts

@@ -9,6 +9,8 @@ import { AvatarMarker } from "./webxr/WebXRAvatar.js";
 /**
  * PlayerColor assigns a unique color for each user in the room to the object it is attached to.  
  * The color is generated based on the user's ID.
+ * 
+ * @summary Assigns a unique color to the player object
  * @category Networking
  * @group Components
  */

package/src/engine-components/ReflectionProbe.ts

@@ -1,4 +1,4 @@
-import { EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, MeshBasicMaterial, Object3D, SRGBColorSpace, Texture, Vector3 } from "three";
+import { CubeReflectionMapping, CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, MeshBasicMaterial, Object3D, SRGBColorSpace, Texture, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonWarning } from "../engine/debug/index.js";
 import { serializable } from "../engine/engine_serialization.js";
@@ -19,6 +19,7 @@ const $originalMaterial = Symbol("original material");
  * 
  * - Sample: http://samples.needle.tools/reflection-probes
  * 
+ * @summary Provides reflection data to materials
  * @category Rendering
  * @group Components
  */
@@ -63,13 +64,19 @@ export class ReflectionProbe extends Behaviour {
 
     // @serializable(Texture)
     set texture(tex: Texture) {
-        if (tex && !(tex instanceof Texture)) {
-            console.error("ReflectionProbe.texture must be a Texture", tex);
-            return;
-        }
+
+        if (this._texture === tex) return;
         this._texture = tex;
+
+        if (debug) console.debug("[ReflectionProbe] Set reflection probe texture " + (tex?.name || "(removed)"));
+
         if (tex) {
-            tex.mapping = EquirectangularReflectionMapping;
+            if (tex instanceof CubeTexture) {
+                // cube textures use CubeReflectionMapping by default
+            }
+            else if (tex.mapping !== EquirectangularReflectionMapping) {
+                tex.mapping = EquirectangularReflectionMapping;
+            }
             tex.colorSpace = LinearSRGBColorSpace;
             tex.needsUpdate = true;
         }
@@ -110,9 +117,8 @@ export class ReflectionProbe extends Behaviour {
         }
     }
     start(): void {
-        if (!this._texture && isDevEnvironment()) {
+        if (!this._texture) {
             console.warn(`[ReflectionProbe] Missing texture. Please assign a custom cubemap texture. To use reflection probes assign them to your renderer's "anchor" property.`);
-            showBalloonWarning("ReflectionProbe configuration hint: See browser console for details")
         }
     }
 
@@ -206,8 +212,11 @@ export class ReflectionProbe extends Behaviour {
             /** this is the material that we copied and that has the reflection probe */
             const copy = cached?.copy;
 
-            // make sure the reflection probe is assigned
-            copy["envMap"] = this.texture;
+            if ("envMap" in copy) {
+                // make sure the reflection probe is assigned
+                copy.envMap = this.texture;
+                copy.needsUpdate = true;
+            }
 
             _rend.sharedMaterials[i] = copy;
         }