@needle-tools/engine 5.1.0-alpha.5 → 5.1.0-canary.02ccb45

package/dist/needle-engine.d.ts

@@ -117,8 +117,12 @@ import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
+/* Excluded from this release type: _$HwXA */
+
 export declare const $physicsKey: unique symbol;
 
+/* Excluded from this release type: _$xxpfa */
+
 export declare class __Ignore {
 }
 
@@ -1794,7 +1798,7 @@ export { AudioListener_2 as AudioListener }
 /**
  * Defines how audio volume attenuates over distance from the listener.
  */
-declare enum AudioRolloffMode {
+export declare enum AudioRolloffMode {
     /**
      * Logarithmic rolloff provides a natural, real-world attenuation where volume decreases
      * exponentially with distance.
@@ -8147,14 +8151,8 @@ export declare type GuidsMap = {
     [key: string]: string;
 };
 
-/* Excluded from this release type: hasCommercialLicense */
-
-/* Excluded from this release type: hasIndieLicense */
-
 /* Excluded from this release type: hasPointerEventComponent */
 
-/* Excluded from this release type: hasProLicense */
-
 export declare function hideDebugConsole(): void;
 
 export declare enum HideFlags {
@@ -14470,6 +14468,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
        */
       private setLookTargetFromConstraint;
       private lerpLookTarget;
+      private canFocusAtPointer;
       private setTargetFromRaycast;
       /**
        * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
@@ -22597,6 +22596,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          userId: string;
      }
 
+     /* Excluded from this release type: UsFaeEU */
+
      /**
       * Marks a field to trigger the `onValidate` callback when its value changes.
       * Useful for reacting to property changes from the editor or at runtime.
@@ -22906,8 +22907,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _receivedInput;
          /* Excluded from this release type: __constructor */
          private _playErrors;
-         /** start playing the video source */
-         play(): void;
+         /**
+          * Plays the assigned video clip, URL, or MediaStream.
+          * If a `clip` argument is passed, it is used as the new video source (mirroring {@link AudioSource.play}).
+          *
+          * @param clip - Optional video URL string or {@link MediaStream} to play. If omitted, plays the currently assigned source.
+          * @returns A promise that resolves to `true` when playback was successfully started, or `false` on error.
+          */
+         play(clip?: string | MediaStream): Promise<boolean>;
          /**
           * Stop the video playback. This will reset the video to the beginning
           */
@@ -23177,9 +23184,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * voip.createMenuButton = true;
       *
       * // Manual control
-      * voip.connect();    // Start sending audio
-      * voip.disconnect(); // Stop sending
-      * voip.setMuted(true); // Mute microphone
+      * voip.connect();    // Start sending your microphone
+      * voip.disconnect(); // Stop sending your microphone
+      * voip.setMuted(true); // Mute incoming audio (silence other users)
       * ```
       *
       * @summary Voice over IP for networked audio communication
@@ -23238,8 +23245,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          get incomingStreams(): ReadonlyMap<string, HTMLAudioElement>;
          /**
-          * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
-          * they are considered "speaking". Default is 30.
+          * Normalized amplitude threshold for speaking detection (0–1). When a user's average
+          * audio amplitude exceeds this, they are considered "speaking". Default is 0.1.
           */
          speakingThreshold: number;
          /**
@@ -23249,6 +23256,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          onSpeakingChanged: EventList;
          private _speakingStates;
          private _analysers;
+         private _sharedAudioContext?;
+         private _lastSpeakingPollMs;
          private _net?;
          private _menubutton?;
          /* Excluded from this release type: awake */
@@ -23258,21 +23267,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /** Set via the mic button (e.g. when the websocket connection closes and rejoins but the user was muted before we don't want to enable VOIP again automatically) */
          private _allowSending;
          private _outputStream;
+         private _connectInFlight?;
          /**
           * @returns true if the component is currently sending audio
           */
          get isSending(): boolean;
          /** Start sending audio. */
          connect(audioSource?: MediaTrackConstraints): Promise<boolean>;
+         private _connectImpl;
          /** Stop sending audio (muting your own microphone) */
          disconnect(opts?: {
              remember: boolean;
          }): void;
          /**
-          * Mute or unmute the audio stream (this will only mute incoming streams and not mute your own microphone. Use disconnect() to mute your own microphone)
+          * Mute or unmute the audio you hear from other users (incoming streams).
+          * This does NOT mute your own microphone — use {@link disconnect} to stop sending your microphone.
           */
          setMuted(mute: boolean): void;
-         /** Returns true if the audio stream is currently muted */
+         /**
+          * Returns true if incoming audio is currently muted (you can't hear other users).
+          * When there are no incoming streams, returns false.
+          */
          get isMuted(): boolean;
          private updateButton;
          /** @deprecated */
@@ -23284,6 +23299,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: update */
          private setupAnalyser;
          private cleanupAnalyser;
+         private closeSharedAudioContext;
          private onReceiveStream;
          private onStreamEnded;
          private onEnabledChanged;
@@ -24001,6 +24017,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @link https://github.com/immersive-web/marker-tracking/blob/main/explainer.md - WebXR Marker Tracking Specification
       */
      export declare class WebXRImageTracking extends Component {
+         /**
+          * Event invoked every frame when images are being tracked.
+          * @example
+          * ```ts
+          * const tracker = this.gameObject.getComponent(WebXRImageTracking);
+          * tracker?.imageTracked.addEventListener(evt => {
+          *   for (const img of evt.trackedImages) {
+          *     console.log(img.url, img.state);
+          *   }
+          * });
+          * ```
+          */
+         imageTracked: EventList<WebXRImageTrackingEvent>;
+         /** @inheritdoc */
+         addEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+         addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+         /** @inheritdoc */
+         removeEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+         removeEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
          /**
           * Set which marker should be primary (first in the list).
           * Useful when deploying to QuickLook mode where one marker is tracked at a time.
@@ -24087,6 +24122,18 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private onImageTrackingUpdate;
      }
 
+     /** Data passed to image tracking event listeners. */
+     export declare interface WebXRImageTrackingEvent {
+         /** The images currently being tracked this frame. */
+         readonly trackedImages: readonly WebXRTrackedImage[];
+     }
+
+     /** Event map for {@link WebXRImageTracking} events. Use with `addEventListener` for typed event handling. */
+     export declare interface WebXRImageTrackingEventMap {
+         /** Dispatched every frame when images are being tracked. The event detail contains the tracking data for the current frame. */
+         "image-tracking": CustomEvent<WebXRImageTrackingEvent>;
+     }
+
      /**
       * Configuration model for a tracked image marker.
       * Defines which image to track, its physical size, and which 3D content to display when detected.
@@ -24285,8 +24332,39 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get widthInMeters(): number;
          /** The ImageBitmap used for tracking */
          get bitmap(): ImageBitmap;
-         /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
+         /**
+          * The {@link WebXRImageTrackingModel} configuration for this tracked image.
+          * Use this to access the assigned 3D object, marker settings, and other image tracking configuration.
+          * Available on each {@link WebXRTrackedImage} received from the `image-tracking` {@link CustomEvent} (`event.detail`).
+          * @example
+          * ```ts
+          * tracker.addEventListener("image-tracking", event => {
+          *   for (const img of event.detail.trackedImages) {
+          *     const model = img.model;
+          *     // Access the assigned 3D object
+          *     const obj = model.object;
+          *     // Access other settings
+          *     console.log(model.widthInMeters, model.hideWhenTrackingIsLost);
+          *   }
+          * });
+          * ```
+          */
          get model(): WebXRImageTrackingModel;
+         /**
+          * The 3D object or prefab assigned to this tracked image marker in the {@link WebXRImageTrackingModel}.
+          * Use this to access the object associated with an AR image tracking marker from the `image-tracking` {@link CustomEvent}.
+          * Shorthand for `this.model.object`.
+          * @example
+          * ```ts
+          * tracker.addEventListener("image-tracking", event => {
+          *   for (const img of event.detail.trackedImages) {
+          *     const obj = img.trackedModel;
+          *     // verbose alternative: img.model.object
+          *   }
+          * });
+          * ```
+          */
+         get trackedModel(): AssetReference | undefined;
          /**
           * The measured size of the detected image in the real world.
           * May differ from `widthInMeters` if the physical marker doesn't match the configured size.