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

package/dist/needle-engine.d.ts

@@ -84,6 +84,7 @@ import { RawShaderMaterial } from 'three';
 import { Ray } from 'three';
 import { Raycaster } from 'three';
 import { Scene } from 'three';
+import { SceneData } from '../../plugins/types/needle-bindings.d.ts';
 import { ShaderMaterial } from 'three';
 import { ShapeJSON } from 'three.quarks';
 import { SkinnedMesh } from 'three';
@@ -1471,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.
@@ -1626,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;
     /**
@@ -1653,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);
@@ -1701,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.
@@ -1729,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;
     /**
@@ -1736,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.
@@ -2192,7 +2278,7 @@ export declare namespace BlobStorage {
     /**
      * Generates an md5 hash from a given buffer
      * @param buffer The buffer to hash
-     * @returns The md5 hash
+     * @returns The md5 hash as a hex string
      */
     export function hashMD5(buffer: ArrayBuffer): string;
     export function hashMD5_Base64(buffer: ArrayBuffer): string;
@@ -2945,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;
@@ -3622,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
@@ -4096,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";
 
@@ -4458,6 +4544,25 @@ export declare class Context implements IContext {
      * The main camera of the scene - this camera is used for rendering
      * Use `setCurrentCamera` for updating the main camera.
      */
+    /**
+     * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
+     * Types are generated automatically from your GLB files when the dev server starts.
+     *
+     * You can store references to objects or components for later use.
+     * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
+     * in which case stored references may become stale.
+     *
+     * @experimental This API may change in future versions.
+     *
+     * @example
+     * // Toggle auto-rotate on the orbit camera
+     * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+     *
+     * @example
+     * // Change the background color
+     * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
+     */
+    get sceneData(): SceneData;
     get mainCamera(): Camera_2;
     /** Set the main camera of the scene. If set to null the camera of the {@link mainCameraComponent} will be used - this camera is used for rendering */
     set mainCamera(cam: Camera_2 | null);
@@ -4479,15 +4584,21 @@ export declare class Context implements IContext {
     connection: NetworkConnection;
     /**  @deprecated AssetDatabase is deprecated */
     assets: AssetDatabase;
-    /** The main light in the scene */
-    mainLight: ILight | null;
+    /** All registered lights in the scene, maintained by the Light component.
+     * @see mainLight for accessing the main directional light in the scene
+     */
+    readonly lights: ILight[];
+    /** The brightest registered directional light, or null if none are registered
+     * @see lights
+     */
+    get mainLight(): ILight | null;
     /** @deprecated Use sceneLighting */
-    get rendererData(): RendererData;
+    private get rendererData();
     /** Access the scene lighting manager to control lighting settings in the context */
-    sceneLighting: RendererData;
-    addressables: Addressables;
-    lightmaps: ILightDataRegistry;
-    players: PlayerViewManager;
+    readonly sceneLighting: RendererData;
+    readonly addressables: Addressables;
+    readonly lightmaps: ILightDataRegistry;
+    readonly players: PlayerViewManager;
     /** Access the LODs manager to control LOD behavior in the context */
     readonly lodsManager: LODsManager;
     /** Access the needle menu to add or remove buttons to the menu element */
@@ -5454,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
@@ -5894,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).
@@ -6039,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.
@@ -7130,6 +7234,20 @@ export declare function getPeerOptions(): PeerJSOption | undefined;
 
 export declare function getResourceUserCount(object: object): number | undefined;
 
+/**
+ * Returns a lazily-resolved proxy typed as {@link SceneData}.
+ * The proxy is cached per context — each context gets exactly one instance.
+ *
+ * Shape mirrors the generated `needle-bindings.gen.d.ts`:
+ *   ctx.sceneData.MyGlb.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.MyGlb.Camera.$object  // → THREE.Camera
+ *   ctx.sceneData.MyGlb.UI.Button.$components.Button  // → Needle Button component
+ *
+ * GLB name is ignored at runtime (scene is already loaded).
+ * Node lookup starts at the scene root.
+ */
+export declare function getSceneData(ctx: IContext): SceneData;
+
 export declare function getTempColor(color?: Color): Color;
 
 /**
@@ -7460,13 +7578,20 @@ export declare class GraphicRaycaster extends ObjectRaycaster {
  * Utility class to perform various graphics operations like copying textures to canvas
  */
 export declare class Graphics {
-    private static readonly planeGeometry;
-    private static readonly renderer;
-    private static readonly perspectiveCam;
-    private static readonly orthographicCam;
-    private static readonly scene;
-    private static readonly blitMaterial;
-    private static readonly mesh;
+    private static _planeGeometry;
+    private static _renderer;
+    private static _perspectiveCam;
+    private static _orthographicCam;
+    private static _scene;
+    private static _blitMaterial;
+    private static _mesh;
+    private static get planeGeometry();
+    private static get renderer();
+    private static get perspectiveCam();
+    private static get orthographicCam();
+    private static get scene();
+    private static get blitMaterial();
+    private static get mesh();
     /**
      * Copy a texture to a new texture
      * @param texture the texture to copy
@@ -7930,6 +8055,9 @@ export declare class HoverAnimation extends Component {
     private playHover;
 }
 
+/** SSR-safe base class for web components. */
+declare const HTMLElementBase: typeof HTMLElement;
+
 export declare type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
     addClip?(clip: AnimationClip): any;
@@ -8189,6 +8317,8 @@ declare interface ILayoutGroup extends IComponent {
 export declare interface ILight extends IComponent {
     intensity: number;
     color: Color;
+    /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
+    readonly type: "directional" | "point" | "spot";
 }
 
 declare interface ILightDataRegistry {
@@ -8405,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.
@@ -9699,6 +9839,9 @@ declare const enum KeyboardEnumType {
     KeyPressed = "keypress"
 }
 
+/** SSR-safe base class for keyboard events. */
+declare const KeyboardEventBase: typeof KeyboardEvent;
+
 declare type KeyboardEventListener = (evt: NEKeyboardEvent) => void;
 
 declare type KeyboardEventNames = EnumToPrimitiveUnion<KeyboardEnumType>;
@@ -9823,10 +9966,13 @@ declare type LifecycleMethodOptions = {
  */
 export declare class Light extends Component implements ILight {
     /**
-     * The type of light (spot, directional, point, etc.)
-     * Can not be changed at runtime.
+     * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
+     * Implements {@link ILight.type}. Can not be changed at runtime.
      */
-    private type;
+    get type(): ILight["type"];
+    /** Numeric LightType serialized from Unity/Blender — converts to string on write */
+    set type(value: LightType | ILight["type"]);
+    private _type;
     /**
      * The maximum distance the light affects.
      * Only applicable for spot and point lights.
@@ -9932,11 +10078,6 @@ export declare class Light extends Component implements ILight {
      * and applies all settings like shadows, intensity, and color.
      */
     createLight(): void;
-    /**
-     * Coroutine that updates the main light reference in the context
-     * if this directional light should be the main light
-     */
-    updateMainLightRoutine(): Generator<undefined, void, unknown>;
     /**
      * Controls whether the renderer's shadow map type can be changed when soft shadows are used
      */
@@ -9985,6 +10126,25 @@ declare enum LightShadows {
     Soft = 2
 }
 
+/**
+ * Defines the type of light in a scene.
+ * @see {@link Light} for configuring light properties and behavior
+ */
+declare enum LightType {
+    /** Spot light that emits light in a cone shape */
+    Spot = 0,
+    /** Directional light that emits parallel light rays in a specific direction */
+    Directional = 1,
+    /** Point light that emits light in all directions from a single point */
+    Point = 2,
+    /** Area light */
+    Area = 3,
+    /** Rectangle shaped area light that only affects baked lightmaps and light probes */
+    Rectangle = 3,
+    /** Disc shaped area light that only affects baked lightmaps and light probes */
+    Disc = 4
+}
+
 export declare class LimitVelocityOverLifetimeModule {
     enabled: boolean;
     dampen: number;
@@ -10972,6 +11132,23 @@ export declare type MouseButtonName = "left" | "right" | "middle";
 
 /* Excluded from this release type: nameofFactory */
 
+/**
+ * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
+ * Use it in React/Svelte/Vue components, button handlers, or plain JavaScript.
+ *
+ * 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 = () => {
+ *   needle.sceneData.Camera.OrbitControls.autoRotate = true;
+ * };
+ */
+export declare const needle: IContext;
+
 declare class NEEDLE_components implements GLTFLoaderPlugin {
     get name(): string;
     exportContext: {
@@ -11105,7 +11282,7 @@ export { NEEDLE_progressive }
  * @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 declare class NeedleButtonElement extends HTMLElement {
+export declare class NeedleButtonElement extends HTMLElementBase {
     #private;
     static observedAttributes: string[];
     constructor();
@@ -11120,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';
@@ -11245,7 +11428,7 @@ export declare namespace NeedleEngineModelLoader {
  * @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 declare class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
+export declare class NeedleEngineWebComponent extends HTMLElementBase implements INeedleEngineComponent {
     static get observedAttributes(): string[];
     get loadingProgress01(): number;
     get loadingFinished(): boolean;
@@ -12078,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;
@@ -12125,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?;
@@ -12218,7 +12402,7 @@ export declare class NeedleXRUtils {
     }): void;
 }
 
-export declare class NEKeyboardEvent extends KeyboardEvent {
+export declare class NEKeyboardEvent extends KeyboardEventBase {
     source?: Event;
     constructor(type: InputEvents, source: Event, init: KeyboardEventInit);
     stopImmediatePropagation(): void;
@@ -12242,7 +12426,7 @@ export declare class NEKeyboardEvent extends KeyboardEvent {
  * @see {@link Input} for the input management system
  * @see {@link PointerType} for available pointer types
  */
-export declare class NEPointerEvent extends PointerEvent {
+export declare class NEPointerEvent extends PointerEventBase {
     /**
      * Spatial input data
      */
@@ -12744,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
  */
@@ -12965,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;
@@ -15074,6 +15258,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
          PointerMove = "pointermove"
      }
 
+     /** SSR-safe base class for pointer events. */
+     declare const PointerEventBase: typeof PointerEvent;
+
      /** [PointerEventData](https://engine.needle.tools/docs/api/PointerEventData) This pointer event data object is passed to all event receivers that are currently active
       * It contains hit information if an object was hovered or clicked
       * If the event is received in onPointerDown or onPointerMove, you can call `setPointerCapture` to receive onPointerMove events even when the pointer has left the object until you call `releasePointerCapture` or when the pointerUp event happens
@@ -16961,6 +17148,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      declare type ScaleClipType = "linear" | "spring";
 
+     export { SceneData }
+
      export declare class SceneLightSettings extends Component {
          ambientMode: AmbientMode;
          ambientLight?: Color;
@@ -20317,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