@needle-tools/engine 4.17.0-next.36dcae2 → 4.17.0-next.4989636

package/dist/needle-engine.d.ts

@@ -18,10 +18,10 @@ import { default as default_3 } from 'three/src/materials/nodes/MeshPhysicalNode
 import { DepthOfFieldEffect } from 'postprocessing';
 import { DepthTexture } from 'three';
 import { dimforgeRapier3dCompat } from '@dimforge/rapier3d-compat';
-import { DocumentedOptions } from 'three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
+import { DocumentedOptions } from '../../../node_modules/three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
 import { Effect } from 'postprocessing';
 import { EffectComposer } from 'postprocessing';
-import { EffectComposer as EffectComposer_2 } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { EffectComposer as EffectComposer_2 } from '../../node_modules/@types/three/examples/jsm/postprocessing/EffectComposer.js';
 import { EmitterShape } from 'three.quarks';
 import { Euler } from 'three';
 import { EventDispatcher } from 'three';
@@ -29,14 +29,15 @@ import { Face } from 'three';
 import * as fflate from 'three/examples/jsm/libs/fflate.module.js';
 import * as flatbuffers from 'flatbuffers';
 import { Fog as Fog_2 } from 'three';
-import { Font } from 'three/examples/jsm/loaders/FontLoader.js';
+import { Font } from '../../node_modules/@types/three/examples/jsm/loaders/FontLoader.js';
 import { Frustum } from 'three';
-import { GLTF as GLTF_2 } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
-import { GLTFExporterOptions } from 'three/examples/jsm/exporters/GLTFExporter.js';
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { GLTFLoaderPlugin } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { GLTFParser } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { GLTF as GLTF_2 } from '../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
+import { GLTF as GLTF_3 } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
+import { GLTFExporter } from '../../../node_modules/@types/three/examples/jsm/exporters/GLTFExporter.js';
+import { GLTFExporterOptions } from '../../../../node_modules/@types/three/examples/jsm/exporters/GLTFExporter.js';
+import { GLTFLoader } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
+import { GLTFLoaderPlugin } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
+import { GLTFParser } from '../../../node_modules/@types/three/examples/jsm/loaders/GLTFLoader.js';
 import { Group } from 'three';
 import { InstancedMesh } from 'three';
 import { Intersection } from 'three';
@@ -44,7 +45,7 @@ import { IParticleSystem as IParticleSystem_2 } from 'three.quarks';
 import { KeyframeTrack } from 'three';
 import { Layers } from 'three';
 import { LightProbe } from 'three';
-import { Line2 } from 'three/examples/jsm/lines/Line2.js';
+import { Line2 } from '../../../../node_modules/@types/three/examples/jsm/lines/Line2.js';
 import { Loader } from 'three';
 import { LoadingManager } from 'three';
 import { LOD_Results } from '@needle-tools/gltf-progressive';
@@ -63,11 +64,12 @@ import { needleToolsMaterialx } from '@needle-tools/materialx';
 import { NormalBufferAttributes } from 'three';
 import { Object3D } from 'three';
 import { Object3DEventMap } from 'three';
-import { Options } from 'three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
-import { OrbitControls as OrbitControls_2 } from 'three/examples/jsm/controls/OrbitControls.js';
+import { Options } from '../../../node_modules/three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
+import { OrbitControls as OrbitControls_2 } from '../../node_modules/@types/three/examples/jsm/controls/OrbitControls.js';
 import { OrthographicCamera } from 'three';
 import { ParticleSystem as ParticleSystem_2 } from 'three.quarks';
 import { Pass } from 'postprocessing';
+import { peerjs } from 'peerjs';
 import { PeerJSOption } from 'peerjs';
 import { PerspectiveCamera } from 'three';
 import { PositionalAudio } from 'three';
@@ -88,7 +90,7 @@ import { Sprite as Sprite_2 } from 'three';
 import { SpriteMaterial } from 'three';
 import { Texture } from 'three';
 import * as ThreeMeshUI from 'three-mesh-ui';
-import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
+import { TransformControls } from '../../node_modules/@types/three/examples/jsm/controls/TransformControls.js';
 import { Vector2 } from 'three';
 import { Vector2Like } from 'three';
 import { Vector3 } from 'three';
@@ -104,8 +106,8 @@ import { WebGLRendererParameters } from 'three';
 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 { XRControllerModelFactory } from '../../../../node_modules/@types/three/examples/jsm/webxr/XRControllerModelFactory.js';
+import { XRHandMeshModel } from '../../../../node_modules/@types/three/examples/jsm/webxr/XRHandMeshModel.js';
 import { XRHandSpace } from 'three';
 
 export declare const $componentName: unique symbol;
@@ -3414,6 +3416,7 @@ export declare abstract class Collider extends Component implements ICollider {
     /* Excluded from this release type: start */
     /* Excluded from this release type: onEnable */
     /* Excluded from this release type: onDisable */
+    /* Excluded from this release type: onDestroy */
     /**
      * Returns the underlying physics body from the physics engine.
      * Only available if the component is enabled and active in the scene.
@@ -6972,7 +6975,7 @@ export declare function getParentHierarchyPath(obj: Object3D): string;
 /** @deprecated use resolveUrl instead */
 export declare function getPath(source: SourceIdentifier | undefined, uri: string): string;
 
-export declare function getPeerjsInstance(id?: string, opts?: PeerJSOption): default_2;
+export declare function getPeerjsInstance(id?: string, opts?: PeerJSOption): Promise<default_2>;
 
 export declare function getPeerOptions(): PeerJSOption | undefined;
 
@@ -9099,6 +9102,14 @@ export declare interface IPhysicsEngine {
      * @param body The component whose physics body should be removed
      */
     removeBody(body: IComponent): any;
+    /**
+     * Enables or disables a collider in the physics world without destroying it.
+     * Uses Rapier's `setEnabled()` for efficient toggling instead of removing and recreating the collider.
+     * @param collider The collider component to enable or disable
+     * @param enabled Whether the collider should be enabled
+     * @returns True if the collider was found and its state was changed, false otherwise
+     */
+    setColliderEnabled(collider: ICollider, enabled: boolean): boolean;
     /**
      * Gets the physics body for a component
      * @param obj The collider or rigidbody component
@@ -10004,9 +10015,41 @@ export declare class LookAt extends Component implements UsdzBehaviour {
 }
 
 /**
- * @deprecated LookAtConstraint has been removed. Use a plain Object3D/Transform reference on OrbitControls instead.
+ * @deprecated LookAtConstraint will be removed in future versions. Please either use a direct object reference instead (e.g. assigning an Object3D as a look target in scripts that reply on the LookAtConstraint) or implement the LookAtConstraint signature in your web project:
+ * ```ts
+ * export class LookAtConstraint extends Behaviour {
+ *   constraintActive: boolean = true;
+ *   locked: boolean = false;
+ *   sources: Object3D[] = [];
+ *   setConstraintPosition(worldPosition: Vector3) {
+ *     const source = this.sources[0];
+ *     if (source) source.worldPosition = worldPosition;
+ *   }
+ * }
+ * ```
  */
 export declare class LookAtConstraint extends Component {
+    /**
+     * When true, the constraint is active and affects the target.
+     * Set to false to temporarily disable without removing sources.
+     */
+    constraintActive: boolean;
+    /**
+     * When true, the look-at position is locked and won't update
+     * even if source objects move.
+     */
+    locked: boolean;
+    /**
+     * Objects to look at. The first object in the array is used
+     * as the primary look-at target.
+     */
+    sources: Object3D[];
+    /**
+     * Sets the world position that the constraint should look at.
+     * Updates the first source object's position.
+     * @param worldPosition The world-space position to look at
+     */
+    setConstraintPosition(worldPosition: Vector3): void;
 }
 
 export declare function lookAtInverse(obj: Object3D, target: Vector3): void;
@@ -10737,9 +10780,9 @@ declare class NEEDLE_components implements GLTFLoaderPlugin {
     parser?: GLTFParser;
     nodeToObjectMap: NodeToObjectMap;
     /** The loaded gltf */
-    gltf: GLTF_2 | null;
+    gltf: GLTF_3 | null;
     beforeRoot(): null;
-    afterRoot(result: GLTF_2): Promise<void>;
+    afterRoot(result: GLTF_3): Promise<void>;
     private createComponents;
 }
 
@@ -10787,6 +10830,14 @@ export declare const NEEDLE_ENGINE_MODULES: {
         /** Load the module */
         load(): Promise<any>;
     };
+    PEERJS: {
+        MODULE: peerjs;
+        MAYBEMODULE: peerjs | null;
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        ready(): Promise<peerjs>;
+        /** Load the module */
+        load(): Promise<peerjs>;
+    };
 };
 
 export { NEEDLE_progressive }
@@ -11299,7 +11350,7 @@ declare class NeedleMenu_2 {
     /** When enabled=true the menu will be visible in VR/AR sessions */
     showSpatialMenu(enabled: boolean): void;
     setSpatialMenuVisible(display: boolean): void;
-    get spatialMenuIsVisible(): boolean | undefined;
+    get spatialMenuIsVisible(): any;
     /**
      * Call to add or remove a button to the menu to show a QR code for the current page
      * If enabled=true then a button will be added to the menu that will show a QR code for the current page when clicked.
@@ -11828,6 +11879,7 @@ export declare class NeedleXRSession implements INeedleXRSession {
      *
      * **For AR**
      * If you want to modify the scale in AR at runtime get the WebARSessionRoot component via `findObjectOfType(WebARSessionRoot)` and then set the `arScale` value.
+     * @returns the scale of the XR rig
      *
      */
     get rigScale(): number;
@@ -12182,6 +12234,7 @@ declare type NEToneMappingModeNames = keyof typeof NEToneMappingMode;
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link OwnershipModel} for object ownership
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
+ * @category Networking
  */
 export declare class NetworkConnection implements INetworkConnection {
     private context;
@@ -12248,7 +12301,7 @@ export declare class NetworkConnection implements INetworkConnection {
     joinRoom(room: string, viewOnly?: boolean): boolean;
     /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
     leaveRoom(room?: string | null): boolean;
-    /** Send a message to the networking backend - it will broadcasted to all connected users in the same room by default */
+    /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
     send<T extends WebsocketSendType>(key: string | OwnershipEvent, data?: T | null, queue?: SendQueue): void;
     /**
      * Deletes the network state for a specific object on the server.
@@ -12402,7 +12455,7 @@ export declare class NetworkedStreams extends EventDispatcher<any> {
 }
 
 /**
- * Provides websocket URL configuration for the built-in networking system.
+ * Provides websocket URL configuration for the {@link NetworkConnection | built-in networking system}.
  * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
  *
  * The component registers itself as a URL provider on `awake()`. When the networking system connects,
@@ -12429,6 +12482,7 @@ export declare class NetworkedStreams extends EventDispatcher<any> {
  * @see {@link SyncedRoom} for automatic room joining
  * @see {@link OwnershipModel} for networked object ownership
  * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link isLocalNetwork} for local network detection
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
  * @summary Networking configuration
  * @category Networking
@@ -15226,6 +15280,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          debugRenderColliders: boolean;
          debugRenderRaycasts: boolean;
          removeBody(obj: IComponent): void;
+         setColliderEnabled(collider: ICollider, enabled: boolean): boolean;
          updateBody(comp: ICollider | IRigidbody, translation: boolean, rotation: boolean): void;
          updateProperties(obj: IRigidbody | ICollider): void;
          addForce(rigidbody: IRigidbody, force: Vec3, wakeup: boolean): void;
@@ -15356,6 +15411,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
          private internalUpdateColliderProperties;
          private internalUpdateRigidbodyProperties;
          private lines?;
+         private disabledLines?;
          step(dt?: number): void;
          postStep(): void;
          private updateDebugRendering;
@@ -19324,6 +19380,7 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * @summary Joins a networked room based on URL parameters or a random room
       * @category Networking
       * @group Components
+      * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
       * @see {@link SyncedTransform} for synchronizing object transforms
       * @see {@link Voip} for voice communication in rooms
       * @see {@link ScreenCapture} for screen/video sharing
@@ -20281,15 +20338,26 @@ export declare class OrbitControls extends Component implements ICameraControlle
      declare class _TypeStore {
          private _types;
          private _reverseTypes;
+         private _lazyLoaders;
          constructor();
          /**
           * add a type to the store
           */
          add(key: string, type: Type): void;
+         /**
+          * Register a lazy-loadable type. The loader is called on first use via {@link getAsync}.
+          * Once resolved, the type is cached for synchronous access via {@link get}.
+          */
+         addLazy(key: string, loader: () => Promise<Type>): void;
          /**
           * @returns the type for the given key if registered
           */
          get(key: string): Type | null;
+         /**
+          * Async version of {@link get} that also resolves lazy-registered types.
+          * After resolving, the type is cached for future synchronous access.
+          */
+         getAsync(key: string): Promise<Type | null>;
          /**
           * @returns the key/name for the given type if registered
           */
@@ -21635,7 +21703,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 and AR on **iOS and Android** in your scene. VisionOS support is also provided via QuickLook USDZ export.
+      * Use the [WebXR](https://engine.needle.tools/docs/api/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.
       *
@@ -21664,12 +21732,25 @@ export declare class OrbitControls extends Component implements ICameraControlle
       * });
       * ```
       *
+      *
+      * @example Start AR session with placement reticle and touch to place and adjust the scene
+      * ```ts
+      * import { onStart, WebXR } from "@needle-tools/engine";
+      * onStart(context => {
+      *  const webxr = context.scene.addComponent(WebXR);
+      *  webxr.autoPlace = false; // disable auto placement, we want the user to tap to place the scene
+      *  webxr.usePlacementReticle = true; // show the placement reticle to help the user find surfaces to place the scene
+      *  webxr.usePlacementAdjustment = true; // allow the user to adjust the position, rotation and scale of the scene with touch after placing
+      *  webxr.arScale = 2; // set the initial scale of the scene in AR. Larger values make the scene appear smaller in AR.
+      *  webxr.enterAR(); // start AR session
+      * });
+      *
       * @summary WebXR Component for VR and AR support
       * @category XR
       * @group Components
       * @see {@link NeedleXRSession} for low-level XR API
       * @see {@link XRControllerMovement} for VR locomotion
-      * @see {@link WebARSessionRoot} for AR session configuration
+      * @see {@link WebARSessionRoot} for AR session configuration and an AR content placement event
       * @see {@link Avatar} for networked user avatars
       * @see {@link screenshot2} for taking screenshots in XR (including AR camera feed compositing)
       * @link https://engine.needle.tools/docs/xr.html
@@ -22678,21 +22759,6 @@ declare module 'three' {
 }
 
 
-declare module 'three/examples/jsm/controls/OrbitControls.js' {
-    interface OrbitControls {
-        _sphericalDelta: import("three").Spherical;
-        _rotateLeft: (angleInRadians: number) => void;
-        _rotateUp: (angleInRadians: number) => void;
-        _pan: (dx: number, dy: number) => void;
-        _dollyIn: (dollyScale: number) => void;
-        _dollyOut: (dollyScale: number) => void;
-    }
-    interface OrbitControlsEventMap {
-        endMovement: Event;
-    }
-}
-
-
 declare module 'three' {
     interface Object3D {
         get guid(): string | undefined;