@needle-tools/engine 5.1.0-alpha.7 → 5.1.0-alpha.9

package/dist/needle-engine.d.ts

@@ -75,6 +75,7 @@ import { Pass } from 'postprocessing';
 import { peerjs } from 'peerjs';
 import { PeerJSOption } from 'peerjs';
 import { PerspectiveCamera } from 'three';
+import { Plane } from 'three';
 import { PositionalAudio } from 'three';
 import { postprocessing } from 'postprocessing';
 import { Particle as QParticle } from 'three.quarks';
@@ -117,8 +118,6 @@ import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
-/* Excluded from this release type: $HDGDr */
-
 export declare const $physicsKey: unique symbol;
 
 export declare class __Ignore {
@@ -1978,11 +1977,18 @@ export declare class AudioSource extends Component {
     private sound;
     private helper;
     private wasPlaying;
-    private audioLoader;
     private shouldPlay;
-    private _lastClipStartedLoading;
     private _loadedClip;
     private _audioElement;
+    /**
+     * True when {@link _audioElement} is a file-URL element routed through
+     * `sound.setMediaElementSource()` (the iOS-survivable string-clip path). For this path ALL
+     * playback control (play/pause/stop/loop/pitch/time/isPlaying) goes through the element,
+     * because three.js sets `hasPlaybackControl = false` once a media source is attached.
+     * It is `false` for the distinct MediaStream path (which uses an element with `srcObject`
+     * plus `setMediaStreamSource()` and is controlled differently).
+     */
+    private _usesMediaElementSource;
     private _entryNode;
     private _spatialGain;
     private _bypassGain;
@@ -2006,11 +2012,39 @@ export declare class AudioSource extends Component {
      * @returns The {@link AudioContext} or null if not available
      */
     get audioContext(): AudioContext | undefined;
+    /**
+     * Resumes the shared AudioContext if it is currently suspended/interrupted and the
+     * page is visible. Uses the same policy as the global resume handler so this never
+     * triggers the iOS `InvalidStateError: Failed to start the audio device` (which
+     * happens when resuming while the page is hidden). No-op when the context is already
+     * running or when resuming is not currently allowed.
+     */
+    private ensureContextResumed;
     /* Excluded from this release type: awake */
     /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDisable */
     private onVisibilityChanged;
     private onApplicationMuteChanged;
+    /**
+     * Sets up playback of a string (file URL) clip through an `HTMLAudioElement` routed into the
+     * Web Audio graph via `sound.setMediaElementSource()`.
+     *
+     * Why a media element instead of a decoded `AudioBuffer`: on iOS Safari an
+     * `AudioBufferSourceNode` has its output torn down after a device lock / audio-session
+     * interruption and cannot be reliably revived. A `MediaElementAudioSourceNode` survives the
+     * lock because the playing `<audio>` element keeps iOS's media session alive, so the shared
+     * AudioContext is never torn down and resumes cleanly. This is the same approach three.js's own
+     * `webaudio_orientation` example uses.
+     *
+     * This does NOT start playback — it only creates/wires the element so a later `.play()` (driven
+     * by a user gesture) is cheap.
+     */
+    private createAudioFromElement;
+    /**
+     * Sets up the {@link PositionalAudio} graph for a MediaStream clip (used for the MediaStream
+     * path only — string clips go through {@link createAudioFromElement}). The actual stream node
+     * is attached in {@link play} via `setMediaStreamSource`.
+     */
     private createAudio;
     private __onAllowAudioCallback;
     /**
@@ -2032,6 +2066,15 @@ export declare class AudioSource extends Component {
      * @returns A promise that resolves when playback starts successfully, or rejects on error
      */
     play(clip?: string | MediaStream | undefined): Promise<boolean>;
+    /**
+     * Smoothly ramp the spatial-graph entry-gain node to `target` (1 = audible, 0 = silent) over a
+     * few ms. A short *fade* — not a hard 0/1 gain change and not a connect/disconnect — is what
+     * avoids the click on pause/resume (an instant change or a graph (dis)connect steps the waveform
+     * → audible click). On iOS the MediaElementAudioSourceNode keeps feeding the graph after
+     * element.pause() following an interruption, so fading this gain to 0 is what actually silences a
+     * "paused" media clip; element.pause() only freezes its playback position.
+     */
+    private fadeEntryGain;
     /**
      * Pauses audio playback while maintaining the current position.
      * Use play() to resume from the paused position.
@@ -2215,6 +2258,24 @@ declare enum Axis {
     Vertical = "y"
 }
 
+/**
+ * Constrains a dragged object to rotate only around a fixed world-space axis.
+ * Uses swing-twist decomposition to extract only the twist component around
+ * the given axis from the delta rotation since drag start, discarding any
+ * perpendicular swing that would tilt the object.
+ *
+ * This is the correct constraint for XZ-plane dragging when the parent is
+ * rotated — it restricts the object to yaw around the plane normal regardless
+ * of how the plane is oriented in world space.
+ */
+export declare class AxisRotationConstraint implements IDragConstraint {
+    private readonly _startQuat;
+    private readonly _axis;
+    constructor(axis: Vector3);
+    init(ctx: IDragConstraintContext): void;
+    apply(followObject: GameObject): void;
+}
+
 declare type BalloonOptions = {
     type: LogType;
     /**
@@ -5985,7 +6046,7 @@ export declare enum DragMode {
  * All properties are lazy getters over the flat serialized fields on the owning `DragControls`,
  * so runtime writes to those fields are reflected immediately without any extra bookkeeping.
  */
-declare class DragProfile {
+export declare class DragProfile {
     private readonly _dc;
     private readonly _xr;
     /* Excluded from this release type: __constructor */
@@ -7003,6 +7064,33 @@ export declare class FixedJoint extends Joint {
     protected createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
+/**
+ * Freezes individual rotation axes (X, Y, and/or Z) of the dragged object.
+ * The locked axis values are captured once at construction time and restored every frame.
+ *
+ * Set {@link useLocalSpace} to `true` to lock axes in the object's local space;
+ * leave it `false` (default) to lock axes in world space.
+ *
+ * @example Lock Y-axis rotation in world space:
+ * ```ts
+ * const c = new FixedRotationAxesConstraint(RotationAxis.Y, false);
+ * // init is called automatically by DragControls, or call manually: c.init(ctx);
+ * ```
+ */
+export declare class FixedRotationAxesConstraint implements IDragConstraint {
+    frozenAxes: RotationAxis;
+    useLocalSpace: boolean;
+    private readonly _startEuler;
+    private readonly _eulerCache;
+    /**
+     * @param frozenAxes       Bitfield of {@link RotationAxis} values indicating which axes to lock.
+     * @param useLocalSpace    When `true`, axes are locked in the object's local space; otherwise world space.
+     */
+    constructor(frozenAxes: RotationAxis, useLocalSpace?: boolean);
+    init(ctx: IDragConstraintContext): void;
+    apply(followObject: GameObject): void;
+}
+
 declare type FocusRect = DOMRect | Element | {
     x: number;
     y: number;
@@ -7913,6 +8001,22 @@ export declare class GltfExportBox extends BoxHelperComponent {
     sceneRoot?: Object3D;
 }
 
+/** Projects the grabbed attachment point back onto a plane after position is resolved,
+ *  with optional grid snapping on that plane.
+ *  Owned by the strategy that requires plane-clamping (e.g. {@link XZPlaneDragStrategy}). */
+export declare class GrabPointPlaneConstraint implements IDragConstraint {
+    /** Plane to project the grabbed point onto. Typically the strategy's fixed drag plane. */
+    readonly plane: Plane;
+    /** Attachment point in dragged-object local space. Set once at drag start; the handler
+     *  mutates this Vector3 in-place so updates are reflected automatically. */
+    hitPointInLocalSpace: Vector3 | null;
+    /** Grid snap resolution on the plane. 0 = projection only, no snapping. */
+    snapResolution: number;
+    constructor(plane: Plane);
+    init(ctx: IDragConstraintContext): void;
+    apply(followObject: GameObject): void;
+}
+
 export declare class Gradient {
     alphaKeys: Array<AlphaKey>;
     colorKeys: Array<ColorKey>;
@@ -8074,6 +8178,15 @@ export declare class GridLayoutGroup extends LayoutGroup {
     protected onCalculateLayout(): void;
 }
 
+/** Snaps the follow object's world position to a uniform grid. Resolution ≤ 0 is a no-op.
+ *  For XZ-plane mode, use {@link GrabPointPlaneConstraint} instead (it handles both
+ *  plane-clamping and optional grid-snapping on the plane). */
+export declare class GridSnapConstraint implements IDragConstraint {
+    snapGridResolution: number;
+    constructor(snapGridResolution: number);
+    apply(followObject: GameObject): void;
+}
+
 /**
  * The [GroundProjectedEnv](https://engine.needle.tools/docs/api/GroundProjectedEnv) projects the environment map onto a virtual ground plane.
  * Creates a realistic floor from 360° panoramas/HDRIs by deforming the skybox
@@ -8628,6 +8741,47 @@ export declare interface IDisposable {
     dispose(): void;
 }
 
+/**
+ * Contract for drag constraints applied after a follow object's position is resolved each frame.
+ * Implement this interface to add custom position/rotation/scale restrictions.
+ */
+declare interface IDragConstraint {
+    /**
+     * Called once at drag start and again whenever the drag context resets
+     * (e.g. multi-touch → single-pointer transition). Capture any object snapshot
+     * (position, rotation, scale) you need to hold fixed during the drag.
+     * Constraints that need no dynamic initialization may omit this method.
+     */
+    init?(context: IDragConstraintContext): void;
+    /** Modifies followObject in-place. Invoked after position is resolved each frame. */
+    apply(followObject: GameObject): void;
+}
+
+/**
+ * Context passed to {@link IDragConstraint.init} at drag start and whenever the drag context
+ * resets (e.g. transitioning from multi-touch back to single-pointer).
+ * Provides a snapshot of the dragged object and attachment data a constraint needs
+ * to initialize or re-initialize its locked reference values.
+ */
+declare interface IDragConstraintContext {
+    /** The object being dragged. Cast to IGameObject for world-space properties. */
+    readonly gameObject: Object3D;
+    /** Drag attachment point in the dragged object's local space. */
+    readonly hitPointInLocalSpace: Vector3;
+    /** Surface normal at drag attachment in the dragged object's local space. */
+    readonly hitNormalInLocalSpace: Vector3;
+    /**
+     * Local-space bounding box at scale=1. Non-null only for multi-touch drags
+     * where scale-aware constraints (e.g. keeping the bounds bottom grounded) are needed.
+     */
+    readonly boundsAtScaleOne: Box3 | null;
+    /**
+     * World scale of the object captured at the start of the current drag phase.
+     * Non-null alongside boundsAtScaleOne for multi-touch; null for single-pointer.
+     */
+    readonly initialWorldScale: Vector3 | null;
+}
+
 /** Implement to receive callbacks from {@type @needle-tools/editor-sync} package */
 declare interface IEditorModification {
     /**
@@ -8857,6 +9011,8 @@ export declare class ImageReference {
  */
 export declare function imageToCanvas(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, color?: Vector4 | undefined, flipY?: boolean, maxTextureSize?: number): Promise<OffscreenCanvasExt>;
 
+/* Excluded from this release type: _imGyfK */
+
 export declare interface IModel {
     guid: string;
     /**
@@ -10060,8 +10216,6 @@ export declare interface IRaycastOptions {
     allowSlowRaycastFallback?: boolean;
 }
 
-/* Excluded from this release type: _IrDl */
-
 declare interface IRectTransform extends IComponent {
     get isDirty(): boolean;
     markDirty(): any;
@@ -10363,6 +10517,20 @@ declare abstract class Joint extends Component {
     protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
+/** Locks the follow object's world rotation to the quaternion captured at drag-start. */
+export declare class KeepRotationConstraint implements IDragConstraint {
+    private readonly _savedQuat;
+    init(ctx: IDragConstraintContext): void;
+    apply(followObject: GameObject): void;
+}
+
+/** Locks the follow object's world scale to the value captured at drag-start. */
+export declare class KeepScaleConstraint implements IDragConstraint {
+    private readonly _savedScale;
+    init(ctx: IDragConstraintContext): void;
+    apply(followObject: GameObject): void;
+}
+
 declare const enum KeyboardEnumType {
     KeyDown = "keydown",
     KeyUp = "keyup",
@@ -10706,8 +10874,6 @@ export declare class LimitVelocityOverLifetimeModule {
     apply(_position: Vec3, baseVelocity: Vector3, currentVelocity: Vector3 | Vector3_2, _size: Vector3_2, t01: number, _dt: number, _scale: number): void;
 }
 
-/* Excluded from this release type: _LMtzpq */
-
 /**
  * Load a 3D model file from a URL (glTF, glb, FBX, OBJ, or any format with a registered loader).
  * @param url URL to the model file.
@@ -11006,7 +11172,7 @@ declare class LowPassFilter {
     setAlpha(alpha: number): void;
     filter(value: number, alpha: number): number;
     lastValue(): number | null;
-    reset(value: number): void;
+    reset(value?: number): void;
 }
 
 declare type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
@@ -15337,6 +15503,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
          bounds: Box3;
      };
 
+     /** Locks the follow object's signed distance from a plane to a value set at drag start.
+      *  Owned by {@link XZPlaneDragStrategy} to prevent slow Y drift in the side-view fallback path.
+      *  Immune to grab-point projection errors, stale matrixWorld, and epsilon guards.
+      *
+      *  When {@link boundsBottomSignedDistFromPivot} is non-zero (set by {@link MultiTouchDragHandler}
+      *  for XZPlane scaling), the effective locked height is shifted each frame so the **bottom of the
+      *  object's bounds** stays at the height captured at drag start instead of the pivot. */
+     export declare class PlaneHeightLockConstraint implements IDragConstraint {
+         private readonly plane;
+         private _lockedHeight;
+         private _boundsBottomSignedDistFromPivot;
+         /** Current pinch-scale ratio, updated each frame by {@link MultiTouchDragHandler}. */
+         currentScaleRatio: number;
+         constructor(plane: Plane);
+         init(ctx: IDragConstraintContext): void;
+         apply(followObject: GameObject): void;
+     }
+
      /**
       * PlayableDirector is the main component for controlling timelines in Needle Engine.
       * It orchestrates playback of TimelineAssets containing animation, audio, signal,
@@ -15403,6 +15587,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get playableAsset(): Models.TimelineAssetModel | undefined;
          set playableAsset(value: Models.TimelineAssetModel | undefined);
          private _playableAsset?;
+         private _didWarnInvalid;
          /**
           * When true, the timeline starts playing automatically when the component awakens.
           * Set to false to control playback manually via `play()`.
@@ -15458,6 +15643,11 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _clonedPlayableAsset;
          private _speed;
          /* Excluded from this release type: awake */
+         /**
+          * Returns true if the director has a valid playable asset. When invalid, warns once (dev only)
+          * that the director has no tracks — called from the user-facing play()/evaluate() entry points.
+          */
+         private warnIfInvalid;
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
          /* Excluded from this release type: onDestroy */
@@ -16416,11 +16606,14 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * Progress.end("export-usdz");
           *
           * // Auto step with weights:
+          * // A numeric weight applies to the NEXT step — it sets how many steps the
+          * // following auto-step advances. The call it is passed on advances by the
+          * // previously-set weight (1 by default).
           * Progress.start("export-usdz", undefined, (progress) => console.log("Progress: " + progress));
-          * Progress.report("export-usdz", { message: "Exporting objects", autoStep: true, totalSteps: 10 });
-          * Progress.report("export-usdz", { message: "Exporting object 1", autoStep: 8 }); // will advance to 80% progress
-          * Progress.report("export-usdz", "Exporting object 2"); // 90%
-          * Progress.report("export-usdz", "Exporting object 3"); // 100%
+          * Progress.report("export-usdz", { message: "Exporting objects", autoStep: true, totalSteps: 10 }); // step 1/10 (10%)
+          * Progress.report("export-usdz", { message: "Heavy step", autoStep: 8 });                           // step 2/10 (20%); weight 8 applies to the next step
+          * Progress.report("export-usdz", "Exporting object 2");                                              // advances by 8 -> step 10/10 (100%)
+          * Progress.report("export-usdz", "Exporting object 3");                                              // stays at 100%
           *
           * // Child scopes:
           * Progress.start("export-usdz", undefined, (progress) => console.log("Progress: " + progress));
@@ -16452,8 +16645,9 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * Progress.report("export-usdz", { totalSteps: 20, autoStep: true });
           * // show the progress as 50%
           * Progress.report("export-usdz", { progress: 0.5 });
-          * // give this step a weight of 20, which changes how progress is calculated. Useful for steps that take longer and/or have child scopes.
-          * Progress.report("export-usdz", { message. "Long process", autoStep: 20 });
+          * // give a weight of 20 to the NEXT step (useful for steps that take longer
+          * // and/or have child scopes); the following auto-step will advance by 20.
+          * Progress.report("export-usdz", { message: "Long process", autoStep: 20 });
           * // show the current step and total steps and implicitly calculate progress as 10%
           * Progress.report("export-usdz", { currentStep: 1, totalSteps: 10 });
           */
@@ -16518,6 +16712,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /** Adds an entry to the browser history. Internally uses `window.history.pushState` */
      export declare function pushState(title: string, urlParams: URLSearchParams, state?: any): void;
 
+     /* Excluded from this release type: _QchMjAD */
      export { QParticle }
 
      export { QParticleBehaviour }
@@ -17788,6 +17983,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          FreezeAll = 126
      }
 
+     /* Excluded from this release type: rkHTARX */
+
      /** Use to listen to room networking events like joining a networked room
       *  For example: `this.context.connection.beginListen(RoomEvents.JoinedRoom, () => { })`
       * @link https://engine.needle.tools/docs/networking.html#manual-networking
@@ -17809,6 +18006,17 @@ export declare class OrbitControls extends Component implements ICameraControlle
          RoomStateSent = "room-state-sent"
      }
 
+     /**
+      * Flags controlling which rotation axes are frozen by {@link FixedRotationAxesConstraint}.
+      * Values can be combined with the bitwise OR operator (`|`).
+      * @example Freeze X and Z: `RotationAxis.X | RotationAxis.Z`
+      */
+     declare enum RotationAxis {
+         X = 1,
+         Y = 2,
+         Z = 4
+     }
+
      export declare class RotationBySpeedModule {
          enabled: boolean;
          range: Vec2;
@@ -17866,6 +18074,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
       */
      declare type ScaleClipType = "linear" | "spring";
 
+     export declare class ScaleLimitConstraint implements IDragConstraint {
+         min: number;
+         max: number;
+         relativeToInitialScale: boolean;
+         /**
+          * @param min                    Lower bound. Relative mode: fraction of initial scale. Raw mode: absolute world-scale per axis.
+          * @param max                    Upper bound. Relative mode: fraction of initial scale. Raw mode: absolute world-scale per axis.
+          * @param relativeToInitialScale When `true`, clamp is relative to `initialWorldScale`. When `false`, each axis is clamped independently.
+          * @param initialWorldScale      Reference to the object's world scale captured at drag start. Required for relative mode.
+          */
+         private readonly _initialWorldScale;
+         constructor(min: number, max: number, relativeToInitialScale?: boolean);
+         init(ctx: IDragConstraintContext): void;
+         apply(followObject: GameObject): void;
+     }
+
      export { SceneData }
 
      export declare class SceneLightSettings extends Component {
@@ -18752,6 +18976,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
           */
          htmlSelector: string | null;
          mode: "window";
+         /**
+          * Read the scroll position from the **top-level window** instead of the window Needle Engine
+          * runs in. This matters when the canvas is embedded in an iframe:
+          * - When the page is **not** embedded this has no effect — the top window *is* the current window.
+          * - When embedded in a **same-origin** iframe, the component follows the *host page's* scroll,
+          *   which is almost always the intent (an embedded iframe usually isn't scrollable itself).
+          *
+          * Set this to `false` to always follow the engine's own window scroll, e.g. when the iframe
+          * itself is scrollable and you want to follow its own scroll rather than the host's.
+          *
+          * If the top window is **cross-origin** (and therefore inaccessible), the component
+          * transparently falls back to the local window and logs a warning in development —
+          * cross-origin embeds would require a `postMessage` scroll bridge from the host page.
+          * @default true
+          */
+         useTopWindowScroll: boolean;
          /**
           * Event fired when the scroll position changes
           */
@@ -18765,9 +19005,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private _appliedValue;
          private _needsUpdate;
          private _firstUpdate;
+         /** The window whose scroll position currently drives this component (resolved from {@link useTopWindowScroll}). */
+         private _scrollWindow;
+         /** The window the `wheel` listener is attached to — kept so we remove it from the same window. */
+         private _wheelTarget;
+         private _crossOriginWarned;
+         private _viewTimelineWarned;
          awake(): void;
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
+         /* Excluded from this release type: onValidate */
+         /**
+          * Resolves which browsing context's scroll position should drive this component.
+          * Honors {@link useTopWindowScroll}. When the top window is requested but is cross-origin
+          * (and therefore inaccessible) it falls back to the local window and warns once —
+          * cross-origin embeds would need a `postMessage` scroll bridge from the host page.
+          */
+         private resolveScrollWindow;
+         /** (Re)resolves the scroll window and moves the `wheel` listener onto it. */
+         private rebindScrollListener;
          /* Excluded from this release type: lateUpdate */
          private _lastSelectorValue;
          private _lastSelectorElement;
@@ -19584,6 +19840,28 @@ export declare class OrbitControls extends Component implements ICameraControlle
          updateNow(hard: boolean): void;
      }
 
+     /**
+      * Used by {@link SnapToSurfacesDragStrategy} for two-pointer (multi-touch) drags.
+      * Casts a downward ray each frame from the follow object's world position and adjusts
+      * it so the dragged object's bounding-box contact face rests on the detected surface.
+      *
+      * Only injected into the constraint pipeline for multi-touch; the single-pointer path
+      * continues to use {@link SnapToSurfacesDragStrategy.update} (pointer ray + drag plane
+      * intersection) unchanged.
+      */
+     export declare class SnapToSurfaceConstraint implements IDragConstraint {
+         private readonly _context;
+         private _gameObject;
+         private _boundsAtScaleOne;
+         private readonly _t1;
+         private readonly _t2;
+         private readonly _t3;
+         private readonly _t4;
+         constructor(_context: Context);
+         init(ctx: IDragConstraintContext): void;
+         apply(followObject: GameObject): void;
+     }
+
      /** used to find data registered via gltf files e.g. find lightmaps for a Renderer component that were shipped inside a gltf */
      export declare type SourceIdentifier = string;
 
@@ -24838,6 +25116,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
+declare module 'three' {
+    interface Vector3 {
+        slerp(end: Vector3, t: number): Vector3;
+    }
+}
+
+
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -24978,13 +25263,6 @@ declare module 'three' {
 }
 
 
-declare module 'three' {
-    interface Vector3 {
-        slerp(end: Vector3, t: number): Vector3;
-    }
-}
-
-
 declare module 'three' {
     interface SkinnedMesh {
         staticGenerator?: StaticGeometryGenerator;