@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
233 lines (232 loc) • 10.4 kB
TypeScript
/// <reference types="webxr" />
import { AssetReference } from "../../engine/engine_addressables.js";
import { type NeedleXREventArgs, NeedleXRSession } from "../../engine/engine_xr.js";
import { WebXRButtonFactory } from "../../engine/webcomponents/WebXRButtons.js";
import { Behaviour } from "../Component.js";
import { XRControllerModel } from "./controllers/XRControllerModel.js";
import { XRControllerMovement } from "./controllers/XRControllerMovement.js";
import { WebARSessionRoot } from "./WebARSessionRoot.js";
/**
* WebXR component to enable VR, AR and Quicklook on iOS in your scene.
* It provides a simple wrapper around the {@link NeedleXRSession} API and adds some additional features like creating buttons or enabling default movement behaviour.
* @category XR
* @group Components
*/
export declare class WebXR extends Behaviour {
/**
* When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter VR mode.
*/
createVRButton: boolean;
/**
* When enabled, a button will be automatically added to {@link NeedleMenu} that allows users to enter AR mode.
*/
createARButton: boolean;
/**
* When enabled, a button to send the experience to an Oculus Quest will be shown if the current device does not support VR.
* This helps direct users to compatible devices for optimal VR experiences.
*/
createSendToQuestButton: boolean;
/**
* When enabled, a QR code will be generated and displayed on desktop devices to allow easy opening of the experience on mobile devices.
*/
createQRCode: boolean;
/**
* When enabled, default movement controls will be automatically added to the scene when entering VR.
* This includes teleportation and smooth locomotion options for VR controllers.
*/
useDefaultControls: boolean;
/**
* When enabled, 3D models representing the user's VR controllers will be automatically created and rendered in the scene.
*/
showControllerModels: boolean;
/**
* When enabled, 3D models representing the user's hands will be automatically created and rendered when hand tracking is available.
*/
showHandModels: boolean;
/**
* When enabled, a reticle will be displayed to help place the scene in AR. The user must tap on a detected surface to position the scene.
*/
usePlacementReticle: boolean;
/**
* Optional custom 3D object to use as the AR placement reticle instead of the default one.
*/
customARPlacementReticle?: AssetReference;
/**
* When enabled, users can adjust the position, rotation, and scale of the AR scene with one or two fingers after initial placement.
*/
usePlacementAdjustment: boolean;
/**
* Determines the scale of the user relative to the scene in AR. Larger values make the 3D content appear smaller.
* Only applies when `usePlacementReticle` is enabled.
*/
arScale: number;
/**
* When enabled, an XRAnchor will be created for the AR scene and its position will be regularly updated to match the anchor.
* This can help with spatial persistence in AR experiences.
* @experimental
*/
useXRAnchor: boolean;
/**
* When enabled, the scene will be automatically placed as soon as a suitable surface is detected in AR,
* without requiring the user to tap to confirm placement.
*/
autoPlace: boolean;
/**
* 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.
*/
autoCenter: boolean;
/**
* When enabled, a USDZExporter component will be automatically added to the scene if none is found.
* This allows iOS and visionOS devices to view 3D content using Apple's AR QuickLook.
*/
useQuicklookExport: boolean;
/**
* When enabled, the 'depth-sensing' WebXR feature will be requested to provide real-time depth occlusion.
* Currently only supported on Oculus Quest devices.
* @see https://developer.mozilla.org/en-US/docs/Web/API/XRDepthInformation
* @experimental
*/
useDepthSensing: boolean;
/**
* When enabled, a {@link SpatialGrabRaycaster} will be added or enabled in the scene,
* allowing users to interact with objects at a distance in VR/AR.
* @default true
*/
useSpatialGrab: boolean;
/**
* Specifies the avatar representation that will be created when entering a WebXR session.
* Can be a reference to a 3D model or a boolean to use the default avatar.
*/
defaultAvatar?: AssetReference | boolean;
private _playerSync?;
/** these components were created by the WebXR component on session start and will be cleaned up again in session end */
private readonly _createdComponentsInSession;
private _usdzExporter?;
static activeWebXRComponent: WebXR | null;
/**
* Initializes the WebXR component by obtaining the XR sync object for this context.
* @internal
*/
awake(): void;
/**
* Sets up the WebXR component when it's enabled. Checks for HTTPS connection,
* sets up USDZ export if enabled, creates UI buttons, and configures avatar settings.
* @internal
*/
onEnable(): void;
/**
* Cleans up resources when the component is disabled.
* Destroys the USDZ exporter if one was created and removes UI buttons.
* @internal
*/
onDisable(): void;
/**
* Checks if WebXR is supported and offers an appropriate session.
* This is used to show the WebXR session joining prompt in browsers that support it.
* @returns A Promise that resolves to true if a session was offered, false otherwise
*/
private handleOfferSession;
/** the currently active webxr input session */
get session(): NeedleXRSession | null;
/** immersive-vr or immersive-ar */
get sessionMode(): XRSessionMode | null;
/** While AR: this will return the currently active WebARSessionRoot component.
* You can also query this component in your scene with `findObjectOfType(WebARSessionRoot)`
*/
get arSessionRoot(): WebARSessionRoot | null;
/** Call to start an WebVR session.
*
* This is a shorthand for `NeedleXRSession.start("immersive-vr", init, this.context)`
*/
enterVR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
/** Call to start an WebAR session
*
* This is a shorthand for `NeedleXRSession.start("immersive-ar", init, this.context)`
*/
enterAR(init?: XRSessionInit): Promise<NeedleXRSession | null>;
/** Call to end a WebXR (AR or VR) session.
*
* This is a shorthand for `NeedleXRSession.stop()`
*/
exitXR(): void;
private _exitXRMenuButton?;
private _previousXRState;
private _spatialGrabRaycaster?;
private _activeWebARSessionRoot;
private get isActiveWebXR();
/**
* Called before entering a WebXR session. Sets up optional features like depth sensing, if needed.
* @param _mode The XR session mode being requested (immersive-ar or immersive-vr)
* @param args The XRSessionInit object that will be passed to the WebXR API
* @internal
*/
onBeforeXR(_mode: XRSessionMode, args: XRSessionInit): void;
/**
* Called when a WebXR session begins. Sets up the scene for XR by configuring controllers,
* AR placement, and other features based on component settings.
* @param args Event arguments containing information about the started XR session
* @internal
*/
onEnterXR(args: NeedleXREventArgs): Promise<void>;
/**
* Called every frame during an active WebXR session.
* Updates components that depend on the current XR state.
* @param _args Event arguments containing information about the current XR session frame
* @internal
*/
onUpdateXR(_args: NeedleXREventArgs): void;
/**
* Called when a WebXR session ends. Restores pre-session state,
* removes temporary components, and cleans up resources.
* @param _ Event arguments containing information about the ended XR session
* @internal
*/
onLeaveXR(_: NeedleXREventArgs): void;
/** Call to enable or disable default controller behaviour */
setDefaultMovementEnabled(enabled: boolean): XRControllerMovement | null;
/** Call to enable or disable default controller rendering */
setDefaultControllerRenderingEnabled(enabled: boolean): XRControllerModel | null;
/**
* Creates and instantiates the user's avatar representation in the WebXR session.
* @param xr The active session
*/
protected createLocalAvatar(xr: NeedleXRSession): Promise<void>;
/**
* Event handler called when a player avatar is spawned.
* Ensures the avatar has the necessary Avatar component.
* @param instance The spawned avatar 3D object
*/
private onAvatarSpawned;
/** @deprecated use {@link getButtonsFactory} or directly access {@link WebXRButtonFactory.getOrCreate} */
getButtonsContainer(): WebXRButtonFactory;
/**
* Returns the WebXR button factory, creating one if it doesn't exist.
* Use this to access and modify WebXR UI buttons.
* @returns The WebXRButtonFactory instance
*/
getButtonsFactory(): WebXRButtonFactory;
/**
* Reference to the WebXR button factory used by this component.
*/
private _buttonFactory?;
/**
* Creates and sets up UI elements for WebXR interaction based on component settings
* and device capabilities. Handles creating AR, VR, QuickLook buttons and utility buttons like QR codes.
*/
private handleCreatingHTML;
/**
* Storage for UI buttons created by this component.
*/
private readonly _buttons;
/**
* Adds a button to the UI with the specified priority.
* @param button The HTML element to add
* @param priority The button's priority value (lower numbers appear first)
*/
private addButton;
/**
* Removes all buttons created by this component from the UI.
*/
private removeButtons;
}