@needle-tools/engine 5.1.8 → 5.1.10

package/dist/needle-engine.d.ts

@@ -5,6 +5,7 @@ import { Audio as Audio_2 } from 'three';
 import { AudioListener as AudioListener_3 } from 'three';
 import { BatchedMesh } from 'three';
 import { BloomEffect as BloomEffect_2 } from 'postprocessing';
+import { Bone } from 'three';
 import { Box3 } from 'three';
 import { BufferGeometry } from 'three';
 import { Camera as Camera_2 } from 'three';
@@ -111,11 +112,14 @@ import { WebGLRenderTarget } from 'three';
 import { WebXRArrayCamera } from 'three';
 import { World } from '@dimforge/rapier3d-compat';
 import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerModelFactory.js';
-import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
 
+/* Excluded from this release type: $fHATZ */
+
+/* Excluded from this release type: $Ljyi */
+
 export declare const $physicsKey: unique symbol;
 
 export declare class __Ignore {
@@ -123,7 +127,7 @@ export declare class __Ignore {
 
 export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;
 
-/* Excluded from this release type: __sKHtRdk */
+/* Excluded from this release type: __KODK */
 
 /** Data describing the accessible semantics for a 3D object or component. */
 declare type AccessibilityData = {
@@ -4119,8 +4123,9 @@ declare abstract class Component implements IComponent, EventTarget, Partial<INe
      * Use to modify session initialization parameters
      * @param mode The XR session mode being requested
      * @param args The session initialization parameters that can be modified
+     * @returns void, or a promise that is awaited before the session is requested (e.g. to load assets)
      */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     /**
      * Called when this component joins an XR session or becomes active in a running session
      * @param args Event data for the XR session
@@ -5564,7 +5569,7 @@ export declare class DepthOfField extends PostProcessingEffect {
     unapply(): void;
 }
 
-declare enum DepthOfFieldMode {
+export declare enum DepthOfFieldMode {
     Off = 0,
     Gaussian = 1,
     Bokeh = 2
@@ -9052,8 +9057,8 @@ export declare type INeedleXRSession = NeedleXRSession;
 export declare interface INeedleXRSessionEventReceiver extends Pick<IComponent, "destroyed"> {
     get activeAndEnabled(): boolean;
     supportsXR?(mode: XRSessionMode): boolean;
-    /** Called before requesting a XR session */
-    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void;
+    /** Called before requesting a XR session. May return a promise that is awaited before requesting. */
+    onBeforeXR?(mode: XRSessionMode, args: XRSessionInit): void | Promise<void>;
     onEnterXR?(args: NeedleXREventArgs): void;
     onUpdateXR?(args: NeedleXREventArgs): void;
     onLeaveXR?(args: NeedleXREventArgs): void;
@@ -10497,6 +10502,10 @@ declare abstract class Joint extends Component {
     protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
+declare type JointBone = Bone & {
+    jointName?: string;
+};
+
 /** Locks the follow object's world rotation to the quaternion captured at drag-start. */
 export declare class KeepRotationConstraint implements IDragConstraint {
     private readonly _savedQuat;
@@ -11045,19 +11054,28 @@ export declare enum LogType {
  */
 export declare class LookAt extends Component implements UsdzBehaviour {
     /**
-     * The target object to look at. If not set, the main camera will be used.
+     * The target object to look at.
+     * @default undefined — when no target is set the main camera is used
      */
     target?: Object3D;
     /**
-     * Inverts the forward direction.
+     * Inverts the forward direction, so the object turns its back to the target
+     * instead of facing it. Useful for models authored facing -Z.
+     * @default false
      */
     invertForward: boolean;
     /**
-     * Keep the up direction.
+     * Keeps the object upright while turning, so it only rotates around the up
+     * axis rather than tilting to point directly at a target above or below it.
+     * @default true
      */
     keepUpDirection: boolean;
     /**
-     * Copy the target rotation.
+     * Copies the target's rotation instead of aiming at its position. Use this to
+     * match a target's orientation, for example to align with the camera.
+     *
+     * Ignored during a VR or AR session.
+     * @default false
      */
     copyTargetRotation: boolean;
     private static flipYQuat;
@@ -11155,8 +11173,6 @@ declare class LowPassFilter {
     reset(value?: number): void;
 }
 
-/* Excluded from this release type: LuMYUbW */
-
 declare type MagicSkyboxName = "studio" | "blurred-skybox" | "quicklook-ar" | "quicklook";
 
 export declare class MainModule {
@@ -11253,7 +11269,7 @@ export declare class MaskableGraphic extends Graphic {
  * This means:
  * - If you change the object's material, the overrides will still be applied to the new material
  * - Multiple objects can share the same material but have different property overrides
- * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOveride}, {@link clearAllOverrides}, or {@link dispose}
+ * - If you don't want overrides applied after changing a material, you must remove them using {@link removeOverride}, {@link clearAllOverrides}, or {@link dispose}
  *
  * The property block system works by:
  * - Temporarily applying overrides in onBeforeRender
@@ -11315,7 +11331,7 @@ export declare class MaskableGraphic extends Graphic {
  * // If you don't want overrides on the new material, remove them:
  * block.clearAllOverrides(); // Remove all overrides
  * // or
- * block.removeOveride("color"); // Remove specific override
+ * block.removeOverride("color"); // Remove specific override
  * // or
  * block.dispose(); // Remove the entire property block
  * ```
@@ -11442,11 +11458,20 @@ export declare class MaterialPropertyBlock<T extends Material = Material> {
      * block.setOverride("lightMap", lightmapTexture);
      *
      * // Remove a specific override - the material will now use its original color
-     * block.removeOveride("color");
+     * block.removeOverride("color");
      *
      * // Other overrides (roughness, lightMap) remain active
      * ```
      */
+    removeOverride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
+    /**
+     * Removes a specific property override.
+     *
+     * @param name The property name to remove the override for
+     *
+     * @deprecated The name is missing an `r`. Use {@link removeOverride} instead — this
+     * alias is kept so existing code keeps working and will be removed in a future version.
+     */
     removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
     /**
      * Removes all property overrides from this block.
@@ -11488,7 +11513,7 @@ export declare class MaterialPropertyBlock<T extends Material = Material> {
      * });
      * ```
      *
-     * @see {@link removeOveride} - To remove a single override
+     * @see {@link removeOverride} - To remove a single override
      * @see {@link dispose} - To completely remove the property block and clean up resources
      */
     clearAllOverrides(): void;
@@ -12956,6 +12981,11 @@ export declare class NeedleXRSession implements INeedleXRSession {
     readonly session: XRSession;
     /** XR Session Mode: AR or VR */
     readonly mode: XRSessionMode;
+    /** The framebuffer scale factor this session was started with. On this
+     * version the engine never requests a custom scale, so it is always 1 —
+     * the property exists so session-resolution handling (e.g. the App Clip
+     * canvas scaling) reads one authoritative value. */
+    readonly appliedFramebufferScaleFactor: number;
     /**
      * The XRSession interface's read-only interactionMode property describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.
      * @link https://developer.mozilla.org/en-US/docs/Web/API/XRSession/interactionMode
@@ -13325,7 +13355,7 @@ export declare class NestedGltf extends Component {
     private hash;
 }
 
-declare enum NEToneMappingMode {
+export declare enum NEToneMappingMode {
     None = 0,
     Neutral = 1,// Neutral tonemapper, close to Reinhard
     ACES = 2,// ACES Filmic reference tonemapper (custom approximation)
@@ -16250,6 +16280,24 @@ export declare class OrbitControls extends Component implements ICameraControlle
          get effects(): readonly IPostProcessingEffect[];
          get dirty(): boolean;
          set dirty(value: boolean);
+         private _enabled;
+         /**
+          * Whether the postprocessing stack runs at all. When disabled the scene is
+          * rendered directly, with no effects and no composer.
+          *
+          * Every effect keeps its own `enabled` state, so switching this back on
+          * restores exactly the stack that was there before. Useful for a quality
+          * setting, for a clean screenshot, or for comparing a scene with and
+          * without effects.
+          *
+          * @default true
+          * @example
+          * ```ts
+          * context.postprocessing.enabled = false;
+          * ```
+          */
+         get enabled(): boolean;
+         set enabled(value: boolean);
          /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
          get handler(): IPostProcessingHandler | null;
          /**
@@ -16720,6 +16768,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export { QTrailParticle }
 
+     export declare enum QualityLevel {
+         LOW = 0,
+         MEDIUM = 1,
+         HIGH = 2,
+         ULTRA = 3
+     }
+
      declare type Quat = {
          x: number;
          y: number;
@@ -18899,7 +18954,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      }
 
      /**See (N8AO documentation)[https://github.com/N8python/n8ao] */
-     declare enum ScreenSpaceAmbientOcclusionN8QualityMode {
+     export declare enum ScreenSpaceAmbientOcclusionN8QualityMode {
          Performance = 0,
          Low = 1,
          Medium = 2,
@@ -23551,8 +23606,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private updateDarkness;
      }
 
-     /* Excluded from this release type: _VIq */
-
      /**
       * Action to show or hide an object.
       * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
@@ -24493,22 +24546,22 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * **Tip:** Add all your markers upfront. In WebXR mode they all work simultaneously.
           * In QuickLook mode, the first (primary) marker is used.
           *
-          * @param image The marker configuration to add
-          * @param asPrimary Set to true to make this the primary marker (for QuickLook fallback)
+          * @param image The marker configuration - either a plain options object or a {@link WebXRImageTrackingModel}.
+          *              Set `asPrimary: true` to make this the primary marker (for QuickLook fallback).
           *
           * @example
           * ```ts
-          * // Super simple - works across all platforms
-          * const marker = new WebXRImageTrackingModel({
+          * // Super simple - just pass the marker url and the object to show
+          * imageTracking.addImage({
           *   url: "https://mysite.com/poster.png",
-          *   widthInMeters: 0.42, // A3 poster width
-          *   object: cool3DModel
+          *   object: cool3DModel,
+          *   widthInMeters: 0.42, // A3 poster width (optional, defaults to 0.25)
           * });
-          * imageTracking.addImage(marker);
           * // That's it! Needle does the rest.
           * ```
           */
-         addImage(image: WebXRImageTrackingModel, asPrimary?: boolean): void;
+         addImage(options: WebXRImageTrackingOptions): void;
+         addImage(model: WebXRImageTrackingModel): void;
          /**
           * Your list of markers to track. Add as many as you need!
           *
@@ -24544,9 +24597,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /* Excluded from this release type: awake */
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
+         private onInvalidImageSizeDetected;
          private onBeforeUSDZExport;
          /* Excluded from this release type: onBeforeXR */
          /* Excluded from this release type: onEnterXR */
+         /** Late-registers this component's marker images into an already running session
+          * via the NeedleGo polyfill's runtime hook. See {@link onEnterXR}. */
+         private registerImagesWithRunningSession;
          /* Excluded from this release type: onLeaveXR */
          private readonly imageToObjectMap;
          private readonly currentImages;
@@ -24598,14 +24655,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @param params.imageDoesNotMove Enable for static markers (floor/wall mounted) to improve tracking stability
           * @param params.hideWhenTrackingIsLost If true, hides the object when tracking is lost; if false, leaves it at the last known position
           */
-         constructor(params: {
-             url: string;
-             widthInMeters: number; /** Object to track */
-             object: AssetReference | Object3D;
-             createObjectInstance?: boolean;
-             imageDoesNotMove?: boolean;
-             hideWhenTrackingIsLost?: boolean;
-         });
+         constructor(params: Omit<WebXRImageTrackingOptions, "asPrimary">);
          /**
           * URL to the marker image to track.
           * **Important:** Use images with high contrast and unique features to improve tracking quality.
@@ -24680,6 +24730,27 @@ export declare class OrbitControls extends Component implements ICameraControlle
          getNameFromUrl(): string | null;
      }
 
+     /**
+      * Options for adding a trackable image marker via {@link WebXRImageTracking.addImage}.
+      * A convenience shape that also accepts a plain {@link Object3D} for `object`.
+      */
+     export declare interface WebXRImageTrackingOptions {
+         /** URL to the marker image to track. Use high-contrast images with unique features for reliable tracking. */
+         url?: string;
+         /** The 3D object (or {@link AssetReference}) to display when the marker is detected. */
+         object: AssetReference | Object3D;
+         /** Physical width of the printed marker in meters. Must match the real marker size. @default 0.25 */
+         widthInMeters?: number;
+         /** Create a new instance of the object for each detection. @default false */
+         createObjectInstance?: boolean;
+         /** Enable for static markers (walls/floor) to improve tracking stability. @default false */
+         imageDoesNotMove?: boolean;
+         /** Hide the object when tracking is lost. @default true */
+         hideWhenTrackingIsLost?: boolean;
+         /** Make this the primary marker (used in QuickLook fallback mode). @default false */
+         asPrimary?: boolean;
+     }
+
      /**
       * [WebXRPlaneTracking](https://engine.needle.tools/docs/api/WebXRPlaneTracking) tracks planes and meshes in the real world when in immersive-ar (e.g. on Oculus Quest).
       * @category XR
@@ -25088,6 +25159,32 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      export declare type XRGestureName = "pinch";
 
+     /**
+      * Renders a skinned hand mesh and drives its bones from the tracked WebXR joint poses.
+      *
+      * @see {@link XRControllerModel} which creates one per tracked hand.
+      */
+     declare class XRHandMeshModel {
+         /** The three XRHandSpace whose `joints` drive this mesh. */
+         readonly controller: XRHandSpace;
+         /** The object the loaded hand mesh is added to. */
+         readonly handModel: Object3D;
+         /** The bones driven by {@link updateMesh}, in {@link JOINT_NAMES} order. Sparse if the model lacks joints. */
+         readonly bones: Array<JointBone | undefined>;
+         /**
+          * @param handModel the object the loaded mesh is parented to
+          * @param controller the hand space providing joint poses
+          * @param path base path for the model (defaults to the generic hand profile CDN)
+          * @param handedness file name to load (without extension) — either "left"/"right" for the
+          *                   default profile, or a full path for a custom hand model
+          * @param loader loader to use; a plain GLTFLoader is created when omitted
+          * @param onLoad invoked with the loaded hand object once it has been added
+          */
+         constructor(handModel: Object3D, controller: XRHandSpace, path: string | null, handedness: string, loader?: GLTFLoader | null, onLoad?: ((object: Object3D) => void) | null);
+         /** Copies the current tracked joint poses onto the mesh bones. Called every XR frame. */
+         updateMesh(): void;
+     }
+
      declare type XRMesh_2 = {
          meshSpace: XRSpace;
          lastChangedTime: number;