@needle-tools/engine 5.1.0-alpha.2 → 5.1.0-alpha.3

package/dist/needle-engine.d.ts

@@ -1472,6 +1472,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.
@@ -1627,9 +1696,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;
     /**
@@ -1654,7 +1724,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);
@@ -1702,7 +1773,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.
@@ -1730,6 +1805,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;
     /**
@@ -1737,8 +1821,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.
@@ -2946,7 +3031,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;
@@ -3623,7 +3708,7 @@ declare class ColorSerializer extends TypeSerializer {
     onSerialize(data: any): any | void;
 }
 
-export declare const colorSerializer: ColorSerializer;
+export declare let colorSerializer: ColorSerializer;
 
 /**
  * Utility method to check if two materials were created from the same glTF material
@@ -4097,7 +4182,7 @@ declare class ComponentSerializer extends TypeSerializer {
     findObjectForGuid(guid: string, root: Object3D): any;
 }
 
-export declare const componentSerializer: ComponentSerializer;
+export declare let componentSerializer: ComponentSerializer;
 
 declare type ComponentType = "button" | "thumbstick" | "squeeze" | "touchpad";
 
@@ -5480,6 +5565,12 @@ export declare class DragControls extends Component implements IPointerEventHand
      * providing visual feedback about the object's position relative to surfaces below it.
      */
     showGizmo: boolean;
+    /** Invoked once when a drag begins (after the minimum drag distance threshold is met). */
+    dragStarted: EventList;
+    /** Invoked every frame while the object is being dragged. */
+    dragUpdated: EventList;
+    /** Invoked once when the last pointer is released and the drag ends. */
+    dragEnded: EventList;
     /**
      * Returns the object currently being dragged by this DragControls component, if any.
      * @returns The object being dragged or null if no object is currently dragged
@@ -5920,19 +6011,6 @@ export declare class EnvironmentScene extends Scene {
     createAreaLightMaterial(intensity: number): MeshBasicMaterial;
 }
 
-export declare const euler: EulerSerializer;
-
-declare class EulerSerializer extends TypeSerializer {
-    constructor();
-    onDeserialize(data: any, _context: SerializationContext): Euler | undefined;
-    onSerialize(data: any, _context: SerializationContext): {
-        x: any;
-        y: any;
-        z: any;
-        order: any;
-    };
-}
-
 /**
  * EventList manages a list of callbacks that can be invoked together.
  * Used for Unity-style events that can be configured in the editor (Unity or Blender).
@@ -6065,7 +6143,7 @@ declare class EventListSerializer extends TypeSerializer {
     onDeserialize(data: EventListData, context: SerializationContext): EventList<any> | undefined | null;
 }
 
-export declare const eventListSerializer: EventListSerializer;
+export declare let eventListSerializer: EventListSerializer;
 
 /**
  * [EventSystem](https://engine.needle.tools/docs/api/EventSystem) is responsible for managing and dispatching input events to UI components within the scene.
@@ -8457,10 +8535,20 @@ 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;
+
 /** Register the Rapier physics backend. Called from {@link initEngine}
  * to ensure it runs regardless of tree-shaking. */
 export declare function initPhysics(): 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.
@@ -11051,6 +11139,8 @@ export declare type MouseButtonName = "left" | "right" | "middle";
  * Safe to import at module level, including in SSR environments.
  * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
+ * @experimental This API may change in future releases.
+ *
  * @example
  * import { needle } from "@needle-tools/engine";
  * button.onclick = () => {
@@ -11207,11 +11297,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';
@@ -12165,8 +12261,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;
@@ -12212,6 +12307,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?;
@@ -12831,7 +12928,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
  */
@@ -13052,7 +13149,7 @@ declare class ObjectSerializer extends TypeSerializer {
     onDeserialize(data: ObjectData | string | null, context: SerializationContext): Object3D<Object3DEventMap> | Component | null | undefined;
 }
 
-export declare const objectSerializer: ObjectSerializer;
+export declare let objectSerializer: ObjectSerializer;
 
 declare type ObjectToNodeMap = {
     [uuid: string]: number;
@@ -20409,6 +20506,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          set font(val: string | null);
          get font(): string | null;
          private _font;
+         private _assignedAtRuntime;
          /**
           * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
           * @default false