@needle-tools/engine 4.12.0-next.ca2cebd → 4.12.0-next.dcaf2b0

package/dist/needle-engine.d.ts

@@ -225,7 +225,7 @@ declare type Alignment = "horizontal" | "vertical" | "any";
  * You can use this to create dynamic beams or connectors between objects.
  *
  * @summary Aligns and scales the object between two target GameObjects
- * @category Utility
+ * @category Constraints
  * @group Components
  **/
 export declare class AlignmentConstraint extends Component {
@@ -251,7 +251,7 @@ declare type Anchoring = "plane" | "image" | "face" | "none";
 /**
  * Animation component to play animations on a GameObject.
  *
- * @summary Play animations
+ * @summary Plays animations from AnimationClips
  * @category Animation and Sequencing
  * @group Components
  */
@@ -535,7 +535,7 @@ export declare class AnimationUtils {
  * It works with an {@link AnimatorController} to handle state transitions and animation blending.
  * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
  *
- * @summary Animation controller and playback component
+ * @summary Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
  */
@@ -1212,7 +1212,7 @@ export declare class AudioExtension implements IUSDExporterExtension {
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
  *
- * @summary Audio listener for 3D audio capture
+ * @summary Receives audio in the scene and outputs it to speakers
  * @category Multimedia
  * @group Components
  */
@@ -1268,7 +1268,7 @@ declare enum AudioRolloffMode {
  * is muted, the volume is set to 0. When unmuted, the volume
  * returns to its previous value.
  *
- * @summary 3D audio source with spatial positioning and playback controls
+ * @summary Plays audio clips from files or media streams
  * @category Multimedia
  * @group Components
  */
@@ -2168,7 +2168,7 @@ export declare class CallInfo {
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  *
  * @summary Rendering scenes from a specific viewpoint
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  */
 export declare class Camera extends Component implements ICamera {
@@ -2592,8 +2592,12 @@ export declare class CharacterController extends Component {
 }
 
 /**
- * @category Camera
- * @category Interactivity
+ * CharacterControllerInput handles user input to control a CharacterController.
+ * It supports movement, looking around, jumping, and double jumping.
+ * You can customize movement speed, rotation speed, and jump forces.
+ * It also integrates with an Animator component for character animations.
+ * @summary User Input for Character Controller
+ * @category Character
  * @group Components
  */
 export declare class CharacterControllerInput extends Component {
@@ -2756,7 +2760,7 @@ export declare type ClipModel = {
  * @category Physics
  * @group Components
  */
-export declare class Collider extends Component implements ICollider {
+export declare abstract class Collider extends Component implements ICollider {
     /* Excluded from this release type: isCollider */
     /**
      * The {@link Rigidbody} that this collider is attached to. This handles the physics simulation for this collider.
@@ -4071,7 +4075,7 @@ export declare function createMotion(name: string, id?: InstantiateIdProvider):
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
  *
  * @summary Makes the object follow the cursor position on screen
- * @category Web
+ * @category Interactivity
  * @group Components
  * @component
  */
@@ -4308,11 +4312,13 @@ export declare namespace DeviceUtilities {
     export function isAndroidDevice(): boolean;
     /** @returns `true` if we're currently using the Mozilla XR Browser (only available for iOS) */
     export function isMozillaXR(): boolean;
+    /** @returns `true` if we're currently in the Needle App Clip */
+    export function isNeedleAppClip(): boolean;
     /** @returns `true` for MacOS devices */
     export function isMacOS(): boolean;
     /** @returns `true` for VisionOS devices */
     export function isVisionOS(): boolean;
-    /** @returns `true` for iOS devices like iPad, iPhone, iPod... */
+    /** @returns `true` for mobile Apple devices like iPad, iPhone, iPod, Vision Pro, ... */
     export function isiOS(): boolean;
     /** @returns `true` if we're currently on safari */
     export function isSafari(): boolean;
@@ -4324,6 +4330,7 @@ export declare namespace DeviceUtilities {
     export function microphonePermissionsGranted(): Promise<boolean>;
     export function getiOSVersion(): string | null;
     export function getChromeVersion(): string | null;
+    export function getSafariVersion(): string | null;
 }
 
 /**
@@ -4492,6 +4499,7 @@ export declare enum DragMode {
 
 /** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
  * It can be used to allow users to drag and drop glTF files into the scene to add new objects.
+ * Existing child objects will behave like placeholders and will be removed when new files are dropped.
  *
  * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
  * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
@@ -5306,6 +5314,12 @@ declare type FitParameters = {
     scaleFactor?: Partial<Vector3Like>;
 };
 
+/**
+ * The FixedJoint groups together 2 rigidbodies, making them stick together in their bound position
+ * @summary Connect two Rigidbodies and make them stick together
+ * @category Physics
+ * @group Components
+ */
 export declare class FixedJoint extends Joint {
     protected createJoint(self: Rigidbody, other: Rigidbody): void;
 }
@@ -5663,9 +5677,10 @@ export declare abstract class GameObject extends Object3D implements Object3D, I
      * Gets a component of the specified type in the gameObject's children hierarchy
      * @param go GameObject to search in
      * @param typeName Constructor of the component type
+     * @param includeInactive Whether to include inactive objects in the search
      * @returns The first matching component if found, otherwise null
      */
-    static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>): T | null;
+    static getComponentInChildren<T extends IComponent>(go: IGameObject | Object3D, typeName: Constructor<T>, includeInactive?: boolean): T | null;
     /**
      * Gets all components of the specified type in the gameObject's children hierarchy
      * @param go GameObject to search in
@@ -6166,7 +6181,8 @@ export declare class Graphic extends BaseUIComponent implements IGraphic, IRectT
 /**
  * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).
  *
- * @category UI
+ * @summary Raycaster for UI elements
+ * @category User Interface
  * @group Components
  */
 export declare class GraphicRaycaster extends ObjectRaycaster {
@@ -6354,6 +6370,14 @@ export declare class HideOnStart extends Component implements UsdzBehaviour {
     beforeCreateDocument(): void;
 }
 
+/**
+ * The HingeJoint groups together 2 rigid bodies, constraining them to move like connected by a hinge.
+ *
+ * You can specify the anchor point and axis of rotation for the hinge.
+ * @summary Connect two Rigidbodies with a hinge
+ * @category Physics
+ * @group Components
+ */
 export declare class HingeJoint extends Joint {
     anchor?: Vector3;
     axis?: Vector3;
@@ -6405,7 +6429,7 @@ declare enum HorizontalWrapMode {
  * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
  *
  * @summary Hover Animation on Pointer Enter/Exit
- * @category Web
+ * @category Interactivity
  * @group Components
  */
 export declare class HoverAnimation extends Component {
@@ -6816,16 +6840,33 @@ export declare interface INeedleEngineComponent extends HTMLElement {
 }
 
 /**
- * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders. Register your plugin via {@link addCustomExtensionPlugin}
+ * Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders.
+ * Register your plugin using the {@link addCustomExtensionPlugin} method
  */
 export declare interface INeedleGLTFExtensionPlugin {
     /** The Name of your plugin */
     name: string;
-    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the GLTFLoader */
+    /** Called before starting to load a glTF file. This callback can be used to add custom extensions to the [GLTFLoader](https://threejs.org/docs/#GLTFLoader.register)
+     *
+     * @example Add a custom extension to the GLTFloader
+     * ```ts
+     * onImport: (loader, url, context) => {
+     *    loader.register((parser) => new MyCustomExtension(parser));
+     * }
+     * ```
+     */
     onImport?: OnImportCallback;
-    /** Called after the glTF has been loaded */
+    /** Called after a glTF file has been loaded */
     onLoaded?: (url: string, gltf: GLTF, context: Context) => void;
-    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the GLTFExporter */
+    /** Called before starting to export a glTF file. This callback can be used to add custom extensions to the [GLTFExporter](https://threejs.org/docs/#examples/en/exporters/GLTFExporter.register)
+     *
+     * @example Add a custom extension to the GLTFExporter
+     * ```ts
+     * onExport: (exporter, context) => {
+     *    exporter.register((writer) => new MyCustomExportExtension(writer));
+     * }
+     *
+     */
     onExport?: OnExportCallback;
 }
 
@@ -8438,7 +8479,8 @@ export declare enum LogType {
  * It can also invert the forward direction and keep the up direction.
  *
  * @summary Makes the object look at a target object or the camera
- * @category Interactivity, Everywhere Actions
+ * @category Everywhere Actions
+ * @category Interactivity
  * @group Components
  */
 export declare class LookAt extends Component implements UsdzBehaviour {
@@ -8468,7 +8510,7 @@ export declare class LookAt extends Component implements UsdzBehaviour {
  * This component is used by {@link OrbitControls} internally.
  *
  * @summary Look At Constraint for OrbitControls
- * @category Camera Controls
+ * @category Camera and Controls
  * @group Components
  */
 export declare class LookAtConstraint extends Component {
@@ -9853,7 +9895,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
      * @param init The XRSessionInit to use (optional), docs: https://developer.mozilla.org/en-US/docs/Web/API/XRSessionInit
      * @param context The Needle Engine context to use
      */
-    static start(mode: XRSessionMode | "ar", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null>;
+    static start(mode: XRSessionMode | "ar" | "quicklook", init?: XRSessionInit, context?: Context): Promise<NeedleXRSession | null>;
     static setSession(mode: XRSessionMode, session: XRSession, init: XRSessionInit, context: Context): NeedleXRSession;
     private static $_stop_request;
     /** stops the active XR session */
@@ -10109,6 +10151,11 @@ export declare class NEPointerEvent extends PointerEvent {
     /** What type of input created this event: touch, mouse, xr controller, xr hand tracking... */
     get pointerType(): PointerTypeNames;
     private readonly _pointerType;
+    /**
+     * The button name that raised this event (e.g. for mouse events "left", "right", "middle" or for XRTrigger "xr-standard-trigger" or "xr-standard-thumbstick")
+     * Use {@link button} to get the numeric button index (e.g. 0, 1, 2...) on the controller or mouse.
+     */
+    readonly buttonName?: ButtonName | "none";
     /** The input that raised this event like `pointerdown` */
     get type(): InputEventNames;
     private readonly _type;
@@ -10567,7 +10614,7 @@ export declare type ObjectOptions = {
 /**
  * A Raycaster that performs raycasting against its own GameObject.
  *
- * @category Interaction
+ * @category Interactivity
  * @group Components
  */
 export declare class ObjectRaycaster extends Raycaster_2 {
@@ -10782,9 +10829,15 @@ export declare class OneEuroFilterXYZ {
     reset(value?: Vec3): void;
 }
 
-declare type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
+/**
+ * Callback type for glTF export plugins. See {@link INeedleGLTFExtensionPlugin.onExport}
+ */
+export declare type OnExportCallback = (exporter: GLTFExporter, context: Context) => void;
 
-declare type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
+/**
+ * Callback type for glTF import plugins. See {@link INeedleGLTFExtensionPlugin.onImport}
+ */
+export declare type OnImportCallback = (loader: GLTFLoader, url: string, context: Context) => void;
 
 /**
  * Register a callback in the engine context created event.
@@ -10916,7 +10969,7 @@ declare enum OpenURLMode {
  * The three OrbitControls object can be accessed via the `controls` property.
  * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
  * @summary Camera controller using three.js OrbitControls
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  */
 export declare class OrbitControls extends Component implements ICameraController {
@@ -12841,6 +12894,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          height: number;
      }
 
+     /**
+      * RectTransform is a component that defines a rectangle for UI layout.
+      * @summary UI Rectangle Transform
+      * @category User Interface
+      * @group Components
+      */
      export declare class RectTransform extends BaseUIComponent implements IRectTransform, IRectTransformChangedReceiver {
          get parent(): RectTransform | undefined;
          get translation(): Vector3;
@@ -13737,9 +13796,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          sceneLoaded: EventList<SceneSwitcher>;
          private _currentIndex;
          private _currentScene;
+         private _currentSceneAsset;
          private _engineElementOverserver;
          private _preloadScheduler?;
          private _menuButtons?;
+         private __lastSwitchScene?;
+         private __lastSwitchScenePromise?;
          /* Excluded from this release type: awake */
          /* Excluded from this release type: onEnable */
          /* Excluded from this release type: onDisable */
@@ -13791,8 +13853,6 @@ export declare class OrbitControls extends Component implements ICameraControlle
           * @returns a promise that resolves to true if the scene was loaded successfully
           */
          reload(): Promise<boolean>;
-         private __lastSwitchScene?;
-         private __lastSwitchScenePromise?;
          /**
           * Switch to a scene by its AssetReference.
           * If the scene is already loaded it will be unloaded and the new scene will be loaded.
@@ -14740,7 +14800,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * Signals can be added to a signal track on a {@link PlayableDirector}
       *
       * @summary Receives signals and invokes reactions
-      * @category Sequencing and Timelines
+      * @category Animation and Sequencing
       * @group Components
       */
      export declare class SignalReceiver extends Component {
@@ -14805,6 +14865,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
          evaluate(t01: number, target?: Vec3, lerpFactor?: number): Vec3;
      }
 
+     /**
+      * Renders deformable meshes that deform via bones and/or blend shapes.
+      * @summary Renderer for deformable meshes
+      * @category Rendering
+      * @group Components
+      **/
      export declare class SkinnedMeshRenderer extends MeshRenderer {
          private _needUpdateBoundingSphere;
          awake(): void;
@@ -15360,7 +15426,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * - Example: https://engine.needle.tools/samples/spritesheet-animation
       *
-      * @category Sprites
+      * @summary Renders 2D images from a sprite sheet
+      * @category Rendering
       * @group Components
       */
      export declare class SpriteRenderer extends Component {
@@ -17004,7 +17071,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * ```
 
       * @summary Automatically fits a box area into the camera view
-      * @category Camera
+      * @category Camera and Controls
       * @group Components
       * @component
       */
@@ -17353,9 +17420,12 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.
-      * It is also responsible for scaling the user in AR and to define the center of the AR scene. If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
+      * It is also responsible for scaling the user in AR and to define the center of the AR scene.
+      * If not present in the scene it will be created automatically by the WebXR component when entering an AR session.
       *
-      * @example
+      * **Note**: If the WebXR component {@link WebXR.autoCenter} option is enabled the scene will be automatically centered based on the content in the scene.
+      *
+      * @example Callback when the scene has been placed in AR:
       * ```ts
       * WebARSessionRoot.onPlaced((args) => {
       *    console.log("Scene has been placed in AR");
@@ -17451,7 +17521,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      declare type WebsocketSendType = IModel | object | boolean | null | string | number;
 
      /**
-      * Use the WebXR component to enable VR, AR and Quicklook on iOS in your scene.
+      * Use the WebXR component to enable VR and AR on iOS and Android in your scene. VisionOS support is also provided via QuickLook USDZ export.
       *
       * The WebXR component is a simple to use wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons for AR, VR, enabling default movement behaviour ({@link XRControllerMovement}) and controller rendering ({@link XRControllerModel}), as well as handling AR placement and Quicklook USDZ export.
       *
@@ -17545,6 +17615,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
          /**
           * When enabled, the AR session root center will be automatically adjusted to place the center of the scene.
           * This helps ensure the scene is properly aligned with detected surfaces.
+          *
+          * **Note**: This option overrides the placement of the {@link WebARSessionRoot} component if both are used.
           */
          autoCenter: boolean;
          /**