@needle-tools/engine 4.12.0-next.dd87659 → 4.12.0-next.e42c144

package/dist/needle-engine.d.ts

@@ -225,9 +225,8 @@ 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 {
     private from;
@@ -251,6 +250,8 @@ declare type Anchoring = "plane" | "image" | "face" | "none";
 
 /**
  * Animation component to play animations on a GameObject.
+ *
+ * @summary Plays animations from AnimationClips
  * @category Animation and Sequencing
  * @group Components
  */
@@ -534,6 +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 Plays and manages animations on a GameObject based on an AnimatorController
  * @category Animation and Sequencing
  * @group Components
  */
@@ -1210,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
  */
@@ -1266,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
  */
@@ -1704,6 +1706,14 @@ export declare class BaseUIComponent extends Component {
     setInteractable(value: boolean): void;
 }
 
+/**
+ * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.
+ * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
+ *
+ * @summary Simple Inverse Kinematics Constraint
+ * @category Animation
+ * @group Components
+ */
 export declare class BasicIKConstraint extends Component {
     private from;
     private to;
@@ -1912,6 +1922,8 @@ export declare class BoxCollider extends Collider implements IBoxCollider {
 
 /**
  * BoxGizmo is a component that displays a box around the object in the scene. It can optionally expand to the object's bounds.
+ *
+ * @summary Display a box around the object
  * @category Helpers
  * @group Components
  */
@@ -1932,6 +1944,7 @@ export declare class BoxGizmo extends Component {
  * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
  * Helper visualization can be enabled with the URL parameter `?gizmos`.
  *
+ * @summary Bounding box helper with intersection tests
  * @category Helpers
  * @group Components
  */
@@ -1985,7 +1998,7 @@ export declare const builtinComponentKeyName = "builtin_components";
  * Button is a UI component that can be clicked by the user to perform an action.
  * It supports different visual states such as normal, highlighted, pressed, and disabled.
  * You can customize the button's appearance using colors or animations for each state.
- * @summary Button UI Component
+ * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
  */
@@ -2154,8 +2167,8 @@ export declare class CallInfo {
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  *
- * @summary Camera rendering scenes from a specific viewpoint
- * @category Camera
+ * @summary Rendering scenes from a specific viewpoint
+ * @category Camera and Controls
  * @group Components
  */
 export declare class Camera extends Component implements ICamera {
@@ -2372,7 +2385,7 @@ export declare class CameraTargetReachedEvent extends CustomEvent<{
  * It defines the area where UI elements are rendered and manages their layout and rendering settings.
  * Canvases can be set to render in world space or screen space (overlay or camera).
  * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
- * @summary Canvas UI Component
+ * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
  */
@@ -2441,7 +2454,7 @@ export declare class Canvas extends UIRootComponent implements ICanvas {
  * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.
  * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.
  * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
- * @summary CanvasGroup UI Component
+ * @summary Group UI elements to control transparency and interactivity
  * @category User Interface
  * @group Components
  */
@@ -2579,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 {
@@ -2739,11 +2756,11 @@ export declare type ClipModel = {
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation
  *
- *
+ * @summary Physics collider
  * @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.
@@ -3406,7 +3423,7 @@ export declare class ContactPoint {
  *
  * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
  *
- *
+ * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
  */
@@ -4058,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
  */
@@ -4295,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;
@@ -4311,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;
 }
 
 /**
@@ -4876,7 +4896,7 @@ export declare const eventListSerializer: EventListSerializer;
 
 /**
  * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
- * @summary UI Input Event System
+ * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components
  */
@@ -5293,6 +5313,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;
 }
@@ -5650,9 +5676,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
@@ -6077,6 +6104,11 @@ export declare class Gizmos {
 export declare type GLTF = GLTF_2;
 
 /**
+ * GltfExport is a component that enables exporting selected 3D objects from the scene to the glTF format.
+ * You can specify whether to export in binary format (.glb) or JSON format (.gltf), and select specific objects to include in the export.
+ * The exported glTF file can be used in various 3D applications and engines that support the glTF standard.
+ *
+ * @summary Export selected 3D objects to glTF format
  * @category Asset Management
  * @group Components
  */
@@ -6148,7 +6180,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 {
@@ -6336,6 +6369,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;
@@ -6387,7 +6428,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 {
@@ -6698,7 +6739,7 @@ declare interface ILightDataRegistry {
  * Image is a UI component that displays a sprite (2D image) in the user interface.
  * You can set the image property to assign a texture to be displayed.
  * The sprite can be customized with various properties such as color tinting and pixel density.
- * @summary Image UI Component
+ * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
  */
@@ -6798,16 +6839,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;
 }
 
@@ -7101,7 +7159,7 @@ export declare const enum InputEvents {
  * InputField is a UI component that allows users to enter and edit text.
  * It provides a text input area where users can type, delete, and modify text.
  * The InputField supports placeholder text, events for value changes, and end edit actions.
- * @summary Text Input Field UI Component
+ * @summary Text field for user input
  * @category User Interface
  * @group Components
  */
@@ -7975,6 +8033,12 @@ export declare class JoinedRoomResponse {
     inRoom: string[];
 }
 
+/**
+ * Base class for physics joints connecting two rigid bodies.
+ * @summary Connect two Rigidbodies
+ * @category Physics
+ * @group Components
+ */
 declare abstract class Joint extends Component {
     connectedBody?: Rigidbody;
     get rigidBody(): Rigidbody | null;
@@ -8340,7 +8404,7 @@ declare enum LODFadeMode {
 /**
  * LODGroup allows to create a group of LOD levels for an object.
  *
- * @summary Level of Detail (LOD) Group Component
+ * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
  */
@@ -8414,7 +8478,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 {
@@ -8444,7 +8509,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 {
@@ -9829,7 +9894,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 */
@@ -10085,6 +10150,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;
@@ -10362,7 +10432,7 @@ export declare class NetworkedStreams extends EventDispatcher<any> {
  * This component supplies websocket URLs for establishing connections.
  * It implements the {@link INetworkingWebsocketUrlProvider} interface.
  *
- * @summary Networking configuration component
+ * @summary Networking configuration
  * @category Networking
  * @group Components
  */
@@ -10543,7 +10613,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 {
@@ -10758,9 +10828,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.
@@ -10892,7 +10968,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 {
@@ -11168,7 +11244,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * Outline is a UI component that adds an outline effect to UI elements.
       * You can customize the outline color and distance to create a visual border around the UI element.
-      * @summary Outline UI Component
+      * @summary Add an outline effect to UI elements
       * @category User Interface
       * @group Components
       */
@@ -11310,7 +11386,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
       *
-      * @summary Particle System
+      * @summary Handles the motion and rendering of many individual particles
       * @category Rendering
       * @group Components
       */
@@ -12817,6 +12893,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;
@@ -14549,7 +14631,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
       *
-      * @summary Renders shadows or light on the object
+      * @summary Creates a shadow mask or a light occluder
       * @category Rendering
       * @group Components
       */
@@ -14716,7 +14798,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 {
@@ -14781,6 +14863,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;
@@ -14845,6 +14933,13 @@ export declare class OrbitControls extends Component implements ICameraControlle
          performRaycast(_opts?: IRaycastOptions | RaycastOptions | null): Intersection[] | null;
      }
 
+     /**
+      * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.
+      * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
+      * @summary Render HTML elements as 3D objects in the scene
+      * @category User Interface
+      * @group Components
+      */
      export declare class SpatialHtml extends Component {
          id: string | null;
          keepAspect: boolean;
@@ -14952,7 +15047,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       *
       * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
       *
-      * @summary Follow other users in a networked room
+      * @summary Spectator camera for following other users
       * @category Networking
       * @group Components
       */
@@ -15329,7 +15424,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 {
@@ -15763,6 +15859,8 @@ export declare class OrbitControls extends Component implements ICameraControlle
 
      /**
       * Text is a UI component that displays text in the user interface.
+      *
+      * @summary Display text in the UI
       * @category User Interface
       * @group Components
       */
@@ -16486,6 +16584,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * usdz.autoExportAudioSources = true;
       * usdz.exportAsync();
       * ```
+      * @summary Export 3D objects as USDZ files for QuickLook
       * @category XR
       * @group Components
       */
@@ -16970,7 +17069,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
       */
@@ -17063,7 +17162,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
      /**
       * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.
       * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).
-      * @summary Voice over IP (VoIP) for networked audio communication
+      * @summary Voice over IP for networked audio communication
       * @category Networking
       * @group Components
       */