@needle-tools/engine 5.0.4 → 5.0.5

package/dist/needle-engine.d.ts

@@ -1362,6 +1362,75 @@ export declare class Attractor extends Component {
 
 declare type AttributeChangeCallback = (value: string | null) => void;
 
+/**
+ * Represents an audio clip that can be loaded and played independently.
+ * The AudioClip class encapsulates the URL of the audio resource and provides
+ * methods for playback control (play, pause, stop) and querying duration.
+ */
+export declare class AudioClip {
+    readonly url: string;
+    /**
+     * Creates a new AudioClip instance with the specified URL.
+     * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
+     */
+    constructor(url: string);
+    /** Whether the clip is currently playing.
+     * @returns `true` if the clip is actively playing audio.
+     */
+    get isPlaying(): boolean;
+    /**
+     * The total duration of the audio clip in seconds.
+     * Loads the audio metadata if not already available.
+     * @returns A promise that resolves with the duration in seconds.
+     */
+    getDuration(): Promise<number>;
+    /**
+     * Plays the audio clip from the current position.
+     * @returns A promise that resolves when playback finishes, or rejects on error.
+     * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses playback at the current position.
+     * Call {@link play} to resume.
+     */
+    pause(): void;
+    /**
+     * Stops playback and resets the position to the beginning.
+     */
+    stop(): void;
+    /** Whether the clip should loop when reaching the end. */
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Playback volume from 0 (silent) to 1 (full). */
+    get volume(): number;
+    set volume(value: number);
+    /** Current playback position in seconds. */
+    get currentTime(): number;
+    set currentTime(value: number);
+    /** Normalized playback progress from 0 to 1.
+     * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
+     */
+    get progress(): number;
+    /**
+     * Seeks to a normalized position (0–1) in the clip.
+     * @param position A value between 0 (start) and 1 (end).
+     */
+    seek(position: number): void;
+    /** The underlying HTMLAudioElement, or `undefined` if not yet created.
+     * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
+     * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
+     */
+    get audioElement(): HTMLAudioElement | undefined;
+    private _audioElement?;
+    private _duration?;
+    private _loadPromise?;
+    private _loop;
+    private _volume;
+    /** Lazily creates and loads the shared HTMLAudioElement. */
+    private ensureAudioElement;
+}
+
 /**
  * @category Animation and Sequencing
  * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
@@ -1517,9 +1586,10 @@ export declare class AudioSource extends Component {
      */
     get isPlaying(): boolean;
     /**
-     * The total duration of the current audio clip in seconds.
+     * The total duration of the currently loaded audio clip in seconds.
      *
      * @returns Duration in seconds or undefined if no clip is loaded
+     * @remarks For MediaStream clips, duration is not directly available and will return undefined. If the audio clip has not started loading or is still loading, duration may also be undefined until the audio buffer is ready.
      */
     get duration(): number | undefined;
     /**
@@ -1544,7 +1614,8 @@ export declare class AudioSource extends Component {
     /**
      * Controls how the audio is positioned in space.
      * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
-     * Note: 2D playback is not fully supported in the current implementation.
+     * Internally uses a dual-path audio graph to crossfade between a spatialized (PannerNode)
+     * and a non-spatialized (direct) signal path.
      */
     get spatialBlend(): number;
     set spatialBlend(val: number);
@@ -1592,7 +1663,11 @@ export declare class AudioSource extends Component {
     private audioLoader;
     private shouldPlay;
     private _lastClipStartedLoading;
+    private _loadedClip;
     private _audioElement;
+    private _entryNode;
+    private _spatialGain;
+    private _bypassGain;
     /**
      * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
      * The audio source needs a user interaction to be initialized due to browser autoplay policies.
@@ -1620,6 +1695,15 @@ export declare class AudioSource extends Component {
     private onApplicationMuteChanged;
     private createAudio;
     private __onAllowAudioCallback;
+    /**
+     * Sets up the dual-path audio graph for spatial blend crossfading.
+     * Creates two parallel signal paths from source to output:
+     * - 3D path: entry → panner → spatialGain → gain (spatialized)
+     * - 2D path: entry → bypassGain → gain (non-spatialized)
+     */
+    private setupSpatialBlendNodes;
+    /** Updates the spatial/bypass gain values based on the current spatialBlend. */
+    private updateSpatialBlendGains;
     private applySpatialDistanceSettings;
     private onNewClip;
     /**
@@ -1627,8 +1711,9 @@ export declare class AudioSource extends Component {
      * If no argument is provided, plays the currently assigned clip.
      *
      * @param clip - Optional audio clip or {@link MediaStream} to play
+     * @returns A promise that resolves when playback starts successfully, or rejects on error
      */
-    play(clip?: string | MediaStream | undefined): void;
+    play(clip?: string | MediaStream | undefined): Promise<boolean>;
     /**
      * Pauses audio playback while maintaining the current position.
      * Use play() to resume from the paused position.
@@ -2836,7 +2921,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
     private _receivers;
     registerEventReceiver(receiver: ICanvasEventReceiver): void;
     unregisterEventReceiver(receiver: ICanvasEventReceiver): void;
-    onEnterXR(args: NeedleXREventArgs): Promise<void>;
+    onEnterXR(args: NeedleXREventArgs): void;
     onLeaveXR(args: NeedleXREventArgs): void;
     onBeforeRenderRoutine: () => void;
     onAfterRenderRoutine: () => void;
@@ -8272,12 +8357,16 @@ export declare class InheritVelocityModule {
     applyCurrent(vel: Vector3 | Vector3_2, t01: number, lerpFactor: number): void;
 }
 
+/* Excluded from this release type: initAddressableSerializers */
+
 /** Register all builtin serializers and prototype patches.
  * Must be called from {@link initEngine} so the registrations survive tree-shaking
  * when the package declares `sideEffects: false`.
  */
 export declare function initBuiltinSerializers(): void;
 
+/* Excluded from this release type: initVolumeParameterSerializer */
+
 /**
  * Handles all input events including mouse, touch, keyboard, and XR controllers.
  * Access via `this.context.input` from any component.
@@ -10950,11 +11039,17 @@ export declare interface NeedleEngineAttributes {
     'hash': string;
     /** Set to automatically add OrbitControls to the loaded scene. */
     'camera-controls': string;
-    /** Override the default draco decoder path location. */
+    /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
+     * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
+     * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
+     */
     'dracoDecoderPath': string;
-    /** Override the default draco library type. */
+    /** Override the default Draco decoder type. */
     'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
+    /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
+     * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
+     * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
+     */
     'ktx2DecoderPath': string;
     /** Prevent context from being disposed when element is removed from DOM. */
     'keep-alive': 'true' | 'false';
@@ -11907,8 +12002,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
     get referenceSpace(): XRSpace | null;
     /** @returns the XRFrame `viewerpose` using the xr `referenceSpace` */
     get viewerPose(): XRViewerPose | undefined;
-    /** @returns `true` if any image is currently being tracked */
-    /** returns true if images are currently being tracked */
+    /** @returns `true` if any image is currently being tracked or emulated */
     get isTrackingImages(): boolean;
     /** The currently active XR rig */
     get rig(): IXRRig | null;
@@ -11954,6 +12048,8 @@ export declare class NeedleXRSession implements INeedleXRSession {
     private readonly _xr_update_scripts;
     /** scripts that are in the scene but inactive (e.g. disabled parent gameObject) */
     private readonly _inactive_scripts;
+    /** tracks scripts that have received onEnterXR — prevents spurious onLeaveXR calls */
+    private readonly _scripts_in_xr;
     private readonly _controllerAdded;
     private readonly _controllerRemoved;
     private readonly _originalCameraWorldPosition?;
@@ -12161,8 +12257,8 @@ export declare type NEPointerEventIntersection = Intersection & {
 
 /**
  * NestedGltf loads and instantiates a glTF file when the component starts.
- * NestedGltf components are created by the Unity exporter when nesting Objects with the GltfObject component (in Unity).
- * Use this for lazy-loading content, modular scene composition, or dynamic asset loading.
+ * This enables splitting a scene into multiple `.glb` files that are loaded on demand,
+ * keeping initial load times small and allowing parts of a scene to be reused across different contexts.
  *
  * ![](https://cloud.needle.tools/-/media/lJKrr_2tWlqRFdFc46U4bQ.gif)
  *
@@ -12175,6 +12271,23 @@ export declare type NEPointerEventIntersection = Intersection & {
  * - Preloading support for faster display
  * - Event callback when loading completes
  *
+ * **Limitations:**
+ * - Loads only once; there is no public API to unload and reload content
+ * - Requires a parent object — does nothing if the GameObject has no parent
+ * - Not intended to be added from code. For loading glTF assets at runtime,
+ *   use {@link AssetReference.loadAsset} or {@link SceneSwitcher} instead
+ *
+ * **Unity Editor usage:**
+ * NestedGltf components are created automatically by the exporter when nesting GltfObject components:
+ * - A parent GameObject with a `GltfObject` component is exported as a `.glb` file
+ * - Any child GameObject that also has a `GltfObject` component is exported as a separate `.glb` file
+ * - The child's `GltfObject` is replaced with a `NestedGltf` reference pointing to that separate `.glb`
+ *
+ * ```
+ * Parent [GltfObject]       → exported as parent.glb
+ *   └─ Child [GltfObject]   → exported as child.glb, replaced with NestedGltf in parent.glb
+ * ```
+ *
  * @example Load a glTF when object becomes active
  * ```ts
  * const nested = myPlaceholder.addComponent(NestedGltf);
@@ -12191,7 +12304,6 @@ export declare type NEPointerEventIntersection = Intersection & {
  * // Later, when object becomes active, it displays instantly
  * ```
  *
- * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
  * @see {@link AssetReference} for asset loading utilities
@@ -12573,7 +12685,7 @@ export declare interface NetworkEventMap {
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
- * @summary Networking configuration
+ * @summary Configures the websocket server URL for multiplayer networking
  * @category Networking
  * @group Components
  */