@needle-tools/engine 5.1.0-next.1780579670.dramatic-pierogi.b8fa941 → 5.1.1

package/dist/needle-engine.d.ts

@@ -118,13 +118,13 @@ import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
-/* Excluded from this release type: _$DeHzisx */
+/* Excluded from this release type: $Mhcqc */
 
 export declare const $physicsKey: unique symbol;
 
-/* Excluded from this release type: _$zFmYj */
+/* Excluded from this release type: $uRk */
 
-/* Excluded from this release type: __EOmPHdLs */
+/* Excluded from this release type: __dSkNu */
 
 export declare class __Ignore {
 }
@@ -4576,8 +4576,8 @@ export declare class ContactShadows extends Component {
      * in which case ContactShadows scale would affect the projection
      **/
     private readonly shadowsRoot;
-    private shadowCamera?;
     private readonly shadowGroup;
+    private shadowCamera?;
     private renderTarget?;
     private renderTargetBlur?;
     private plane?;
@@ -4592,11 +4592,16 @@ export declare class ContactShadows extends Component {
      * Call to fit the shadows to the scene.
      */
     fitShadows(params?: FitParameters): void;
+    /**
+     * Call to update the shadows immediately. Only needed if `manualUpdate` is enabled, usually the shadows will update automatically when the scene changes or when the component is enabled.
+     */
+    renderShadowsNow(): void;
     /* Excluded from this release type: awake */
-    /* Excluded from this release type: start */
-    onEnable(): void;
+    /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDestroy */
     /* Excluded from this release type: onBeforeRender */
+    private _ensureSetup;
+    private _renderShadows;
     private blurShadow;
     private applyMinSize;
 }
@@ -8263,6 +8268,12 @@ export declare class GroundProjectedEnv extends Component {
     private _lastHeight?;
     private _projection?;
     private _watcher?;
+    /** The scene's real backgroundBlurriness, stored while we temporarily override it for the render. */
+    private _savedBackgroundBlur;
+    /** pre_render_callback: force the skybox blur just before the render (after all component onBeforeRender). */
+    private readonly _forceBackgroundBlur;
+    /** post_render_callback: restore the scene's real blur right after the render. */
+    private readonly _restoreBackgroundBlur;
     /* Excluded from this release type: awake */
     /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDisable */
@@ -12365,7 +12376,7 @@ export declare class NeedleMenu extends Component {
      */
     position: "top" | "bottom";
     /**
-     * Controls the visibility of the Needle logo in the menu (requires PRO license)
+     * Controls the visibility of the Needle logo in the menu (requires a commercial license)
      */
     showNeedleLogo: boolean;
     /**
@@ -12464,10 +12475,10 @@ declare class NeedleMenu_2 {
     setPosition(position: "top" | "bottom"): void;
     /**
      * Call to show or hide the menu.
-     * NOTE: Hiding the menu is a PRO feature and requires a needle engine license. Hiding the menu will not work in production without a license.
+     * NOTE: Hiding the menu requires a commercial license. Hiding the menu will not work in production without a license.
      */
     setVisible(visible: boolean): void;
-    /** When set to false, the Needle Engine logo will be hidden. Hiding the logo requires a needle engine license */
+    /** When set to false, the Needle Engine logo will be hidden. Hiding the logo requires a commercial license */
     showNeedleLogo(visible: boolean): void;
     /** @returns true if the logo is visible */
     get logoIsVisible(): boolean;
@@ -12862,6 +12873,26 @@ export declare class NeedleXRSession implements INeedleXRSession {
     static getXRSync(context: Context): NeedleXRSync;
     static get currentSessionRequest(): XRSessionMode | null;
     private static _currentSessionRequestMode;
+    /** Base URL for branded Needle AppClip experiences */
+    private static readonly appClipBaseUrl;
+    private static _appClipUrl;
+    /**
+     * Optionally provide a custom Needle AppClip experience to open on iOS instead of the default Needle AppClip.
+     * This enables custom App Clip card branding (your own title and image) when launching AR on iPhone and iPad.
+     *
+     * You can provide either:
+     * - the full URL, e.g. `https://appclip.needle.tools/x/your-experience`
+     * - or just the experience id, e.g. `your-experience` (expanded to `https://appclip.needle.tools/x/your-experience`)
+     *
+     * **IMPORTANT**: the resulting URL must exactly match an App Clip experience URL you have registered (with custom card metadata).
+     * For this reason the URL is opened as-is, without appending any query parameters.
+     *
+     * Note: custom App Clip branding requires an active PRO subscription. See the iOS WebXR App Clip docs (Custom Branding for iOS AR).
+     * @link https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip#custom-branding-for-ios-ar
+     */
+    static get appClipUrl(): string | null;
+    static set appClipUrl(value: string | null);
+    /* Excluded from this release type: getAppClipLaunchUrl */
     /**
      * @returns the active @type {NeedleXRSession} (if any active) or null
      */
@@ -12895,6 +12926,10 @@ export declare class NeedleXRSession implements INeedleXRSession {
      */
     static isSessionSupported(mode: XRSessionMode): Promise<boolean>;
     private static _sessionSupportedCache;
+    private static _deviceChangeHooked;
+    /** Invalidate the support cache when the set of XR devices changes, so a newly
+     * connected headset is picked up by the next isSessionSupported() call. */
+    private static ensureDeviceChangeInvalidation;
     private static _currentSessionRequest?;
     private static _activeSession;
     /** Register to listen to XRSession start events. Unsubscribe with `offXRSessionStart` */
@@ -16270,7 +16305,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          multisampling: "auto" | number;
          /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
           * and restored when performance recovers.
-          * @default true
+          * @experimental
+          * @default false
           */
          adaptiveResolution: boolean;
          constructor(context: Context);
@@ -17235,7 +17271,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          unapply(obj: Object3D): void;
      }
 
-     declare enum ReflectionProbeUsage {
+     export declare enum ReflectionProbeUsage {
          Off = 0,
          BlendProbes = 1,
          BlendProbesAndSkybox = 2,
@@ -18322,6 +18358,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          switchScene(scene: AssetReference): Promise<boolean>;
          private __unloadCurrentScene;
          private _currentlyLoadingScene?;
+         private _loadingRequestId;
+         private _activeLoadingRequestId;
          /* Excluded from this release type: __internalSwitchScene */
          preload(index: number): Promise<boolean> | Promise<ArrayBufferLike | null>;
          private tryLoadFromQueryParam;
@@ -19174,13 +19212,42 @@ export declare class OrbitControls extends Component implements ICameraControlle
           *
           */
          autoUpdate: boolean;
+         /**
+          * The alpha (opacity) the object is currently faded to, in the `[0, 1]` range.
+          * `1` means fully visible, `0` means fully hidden. This is the live, animated value
+          * (it lerps toward the target over {@link fadeDuration}), updated every frame the fade runs.
+          *
+          * External components can read this to react to the see-through state — e.g. toggling a
+          * collider, muting audio, or driving a UI prompt as the object fades in or out.
+          *
+          * @example React to the object becoming (almost) hidden
+          * ```ts
+          * if (seeThrough.currentAlpha < 0.1) {
+          *   // object is essentially see-through now
+          * }
+          * ```
+          * @default 1
+          */
+         get currentAlpha(): number;
+         /**
+          * Below this alpha the object stops casting a shadow. The shadow map only stores depth, so a
+          * faded object would otherwise keep casting a fully solid shadow (three.js does not fade shadows
+          * by opacity). Toggling shadow casting off near-invisible is the cleanest fix; we drive it via
+          * the {@link Renderer.shadowCastingMode} so it cooperates with the per-frame shadow settings the
+          * Renderer re-applies. Note this is a hard on/off, not a fade.
+          */
+         static readonly shadowHideThreshold = 0.05;
          private readonly _referencePointVector;
          private readonly _referencePointDir;
          private _distance;
          private _renderer;
          private _needsUpdate;
          private _id;
+         private _currentAlpha;
+         /** Renderers whose shadow casting we turned off while hidden, mapped to their original mode for restore. */
+         private readonly _suppressedShadowCasting;
          /* Excluded from this release type: onEnable */
+         /* Excluded from this release type: onDestroy */
          /* Excluded from this release type: update */
          private updateDirection;
          /**
@@ -19189,6 +19256,15 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @param duration Duration in seconds to reach the target alpha. 0 means immediate. Default is the component's fadeDuration.
           */
          updateAlpha(targetAlpha: number, duration?: number): void;
+         /**
+          * Suppress or restore a renderer's shadow casting based on its current alpha.
+          * Driving {@link Renderer.shadowCastingMode} (rather than the raw `mesh.castShadow`) is required
+          * because the Renderer re-applies that setting every frame; we remember the original mode so it
+          * is restored exactly when the object fades back in.
+          */
+         private updateShadowCasting;
+         /** Restore every renderer we suppressed shadow casting on, then clear the bookkeeping. */
+         private restoreSuppressedShadowCasting;
      }
 
      export declare function sendDestroyed(guid: string, con: INetworkConnection, opts?: SyncDestroyOptions): void;
@@ -19407,7 +19483,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare function setWorldScale(obj: Object3D, vec: Vector3): void;
 
-     declare enum ShadowCastingMode {
+     export declare enum ShadowCastingMode {
          Off = 0,
          On = 1,
          TwoSided = 2,
@@ -23747,14 +23823,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @max renderer.capabilities.maxSamples
           */
          multisampling: "auto" | number;
-         /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
-          * and restored when performance recovers. This helps maintain smooth frame rates
-          * on devices where full retina resolution is too expensive for postprocessing.
-          * Pushed to `context.postprocessing.adaptiveResolution` when this Volume is active.
-          * Disable this if you need a fixed resolution and prefer consistent quality over frame rate.
-          * @default true
-          */
-         adaptiveResolution: boolean;
          /**
           * Add a post processing effect to this Volume and push it to the core postprocessing stack.
           */
@@ -23781,7 +23849,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private pushEffectsToCore;
          /** Remove all effects this Volume contributed from the core stack */
          private removeEffectsFromCore;
-         /** Push multisampling and adaptiveResolution config to the core stack */
+         /** Push multisampling config to the core stack */
          private syncConfigToCore;
          private _applyPostQueue;
          /** called from needle editor sync package if its active */
@@ -25117,28 +25185,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
      export { }
 
 
-declare module 'three' {
-    interface SkinnedMesh {
-        staticGenerator?: StaticGeometryGenerator;
-        staticGeometry?: BufferGeometry;
-        staticGeometryLastUpdate?: number;
-    }
-    interface Mesh {
-        acceleratedRaycast?: any;
-    }
-    interface SkinnedMesh {
-        /** @deprecated use autoUpdateMeshBvhInterval */
-        autoUpdateMeshBVH?: boolean;
-        /**
-         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
-         * @default undefined (disabled)
-         */
-        autoUpdateMeshBvhInterval?: number;
-        bvhNeedsUpdate?: boolean;
-    }
-}
-
-
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;
@@ -25284,3 +25330,25 @@ declare module 'three' {
         slerp(end: Vector3, t: number): Vector3;
     }
 }
+
+
+declare module 'three' {
+    interface SkinnedMesh {
+        staticGenerator?: StaticGeometryGenerator;
+        staticGeometry?: BufferGeometry;
+        staticGeometryLastUpdate?: number;
+    }
+    interface Mesh {
+        acceleratedRaycast?: any;
+    }
+    interface SkinnedMesh {
+        /** @deprecated use autoUpdateMeshBvhInterval */
+        autoUpdateMeshBVH?: boolean;
+        /**
+         * Interval in milliseconds to automatically update the mesh BVH. When set to >= 0 the BVH will be updated every x milliseconds.
+         * @default undefined (disabled)
+         */
+        autoUpdateMeshBvhInterval?: number;
+        bvhNeedsUpdate?: boolean;
+    }
+}