@babylonjs/core
Version:
Getting started? Play directly with the Babylon.js API using our [playground](https://playground.babylonjs.com/). It also contains a lot of samples to learn how to use it.
308 lines (307 loc) • 11.3 kB
TypeScript
import type { IWebXRFeature } from "../webXRFeaturesManager.js";
import { Observable } from "../../Misc/observable.js";
import type { WebXRSessionManager } from "../webXRSessionManager.js";
import type { Nullable } from "../../types.js";
import type { WebXRInput } from "../webXRInput.js";
import type { AbstractMesh } from "../../Meshes/abstractMesh.js";
import { Vector3, Quaternion } from "../../Maths/math.vector.js";
import type { Material } from "../../Materials/material.js";
import type { PickingInfo } from "../../Collisions/pickingInfo.js";
import { WebXRAbstractFeature } from "./WebXRAbstractFeature.js";
import { Color4 } from "../../Maths/math.color.js";
import type { Scene } from "../../scene.js";
/**
* The options container for the teleportation module
*/
export interface IWebXRTeleportationOptions {
/**
* if provided, this scene will be used to render meshes.
*/
customUtilityLayerScene?: Scene;
/**
* Values to configure the default target mesh
*/
defaultTargetMeshOptions?: {
/**
* Fill color of the teleportation area
*/
teleportationFillColor?: string;
/**
* Border color for the teleportation area
*/
teleportationBorderColor?: string;
/**
* Disable the mesh's animation sequence
*/
disableAnimation?: boolean;
/**
* Disable lighting on the material or the ring and arrow
*/
disableLighting?: boolean;
/**
* Override the default material of the torus and arrow
*/
torusArrowMaterial?: Material;
/**
* Override the default material of the Landing Zone
*/
teleportationCircleMaterial?: Material;
};
/**
* A list of meshes to use as floor meshes.
* Meshes can be added and removed after initializing the feature using the
* addFloorMesh and removeFloorMesh functions
* If empty, rotation will still work
*/
floorMeshes?: AbstractMesh[];
/**
* use this rendering group id for the meshes (optional)
*/
renderingGroupId?: number;
/**
* Should teleportation move only to snap points
*/
snapPointsOnly?: boolean;
/**
* An array of points to which the teleportation will snap to.
* If the teleportation ray is in the proximity of one of those points, it will be corrected to this point.
*/
snapPositions?: Vector3[];
/**
* How close should the teleportation ray be in order to snap to position.
* Default to 0.8 units (meters)
*/
snapToPositionRadius?: number;
/**
* Provide your own teleportation mesh instead of babylon's wonderful doughnut.
* If you want to support rotation, make sure your mesh has a direction indicator.
*
* When left untouched, the default mesh will be initialized.
*/
teleportationTargetMesh?: AbstractMesh;
/**
* If main component is used (no thumbstick), how long in milliseconds should the "long press" take before teleport. Defaults to 3 seconds
*/
timeToTeleport?: number;
/**
* If the main component is used, how long in milliseconds should the "long press" take before teleport starts. Defaults to 0
*/
timeToTeleportStart?: number;
/**
* Disable using the thumbstick and use the main component (usually trigger) on long press.
* This will be automatically true if the controller doesn't have a thumbstick or touchpad.
*/
useMainComponentOnly?: boolean;
/**
* Should meshes created here be added to a utility layer or the main scene
*/
useUtilityLayer?: boolean;
/**
* Babylon XR Input class for controller
*/
xrInput: WebXRInput;
/**
* Meshes that the teleportation ray cannot go through
*/
pickBlockerMeshes?: AbstractMesh[];
/**
* define an optional predicate to select which meshes should block the teleportation ray
*/
blockerMeshesPredicate?: (mesh: AbstractMesh) => boolean;
/**
* Should the teleportation ray be blocked by all of the scene's pickable meshes?
* Defaults to false
*/
blockAllPickableMeshes?: boolean;
/**
* Color of the teleportation ray when it is blocked by a mesh in the pickBlockerMeshes array
* Defaults to red.
*/
blockedRayColor?: Color4;
/**
* Should teleport work only on a specific hand?
*/
forceHandedness?: XRHandedness;
/**
* If provided, this function will be used to generate the ray mesh instead of the lines mesh being used per default
*/
generateRayPathMesh?: (points: Vector3[], pickingInfo: PickingInfo) => AbstractMesh;
}
/**
* This is a teleportation feature to be used with WebXR-enabled motion controllers.
* When enabled and attached, the feature will allow a user to move around and rotate in the scene using
* the input of the attached controllers.
*/
export declare class WebXRMotionControllerTeleportation extends WebXRAbstractFeature {
private _options;
private _controllers;
private _currentTeleportationControllerId;
private _floorMeshes;
private _quadraticBezierCurve;
private _selectionFeature;
private _snapToPositions;
private _snappedToPoint;
private _teleportationRingMaterial?;
private _blockedRayColor;
private _cachedColor4White;
private _tmpRay;
private _tmpVector;
private _tmpQuaternion;
private _worldScaleObserver?;
/**
* Skip the next teleportation. This can be controlled by the user to prevent the user from teleportation
* to sections that are not yet "unlocked", but should still show the teleportation mesh.
*/
skipNextTeleportation: boolean;
/**
* The module's name
*/
static readonly Name: "xr-controller-teleportation";
/**
* The (Babylon) version of this module.
* This is an integer representing the implementation version.
* This number does not correspond to the webxr specs version
*/
static readonly Version = 1;
/**
* Is movement backwards enabled
*/
backwardsMovementEnabled: boolean;
/**
* Distance to travel when moving backwards
*/
backwardsTeleportationDistance: number;
/**
* The distance from the user to the inspection point in the direction of the controller
* A higher number will allow the user to move further
* defaults to 5 (meters, in xr units)
*/
parabolicCheckRadius: number;
/**
* Should the module support parabolic ray on top of direct ray
* If enabled, the user will be able to point "at the sky" and move according to predefined radius distance
* Very helpful when moving between floors / different heights
*/
parabolicRayEnabled: boolean;
/**
* The second type of ray - straight line.
* Should it be enabled or should the parabolic line be the only one.
*/
straightRayEnabled: boolean;
/**
* How much rotation should be applied when rotating right and left
*/
rotationAngle: number;
/**
* This observable will notify when the target mesh position was updated.
* The picking info it provides contains the point to which the target mesh will move ()
*/
onTargetMeshPositionUpdatedObservable: Observable<PickingInfo>;
/**
* Is teleportation enabled. Can be used to allow rotation only.
*/
teleportationEnabled: boolean;
private _rotationEnabled;
/**
* Observable raised before camera rotation
*/
onBeforeCameraTeleportRotation: Observable<number>;
/**
* Observable raised after camera rotation
*/
onAfterCameraTeleportRotation: Observable<Quaternion>;
/**
* Observable raised before camera teleportation
*/
onBeforeCameraTeleport: Observable<Vector3>;
/**
* Observable raised after camera teleportation
*/
onAfterCameraTeleport: Observable<Vector3>;
/**
* Is rotation enabled when moving forward?
* Disabling this feature will prevent the user from deciding the direction when teleporting
*/
get rotationEnabled(): boolean;
/**
* Sets whether rotation is enabled or not
* @param enabled is rotation enabled when teleportation is shown
*/
set rotationEnabled(enabled: boolean);
/**
* Exposes the currently set teleportation target mesh.
*/
get teleportationTargetMesh(): Nullable<AbstractMesh>;
/**
* constructs a new teleportation system
* @param _xrSessionManager an instance of WebXRSessionManager
* @param _options configuration object for this feature
*/
constructor(_xrSessionManager: WebXRSessionManager, _options: IWebXRTeleportationOptions);
/**
* Get the snapPointsOnly flag
*/
get snapPointsOnly(): boolean;
/**
* Sets the snapPointsOnly flag
* @param snapToPoints should teleportation be exclusively to snap points
*/
set snapPointsOnly(snapToPoints: boolean);
/**
* Add a new mesh to the floor meshes array
* @param mesh the mesh to use as floor mesh
*/
addFloorMesh(mesh: AbstractMesh): void;
/**
* Add a mesh to the list of meshes blocking the teleportation ray
* @param mesh The mesh to add to the teleportation-blocking meshes
*/
addBlockerMesh(mesh: AbstractMesh): void;
/**
* Add a new snap-to point to fix teleportation to this position
* @param newSnapPoint The new Snap-To point
*/
addSnapPoint(newSnapPoint: Vector3): void;
attach(): boolean;
detach(): boolean;
dispose(): void;
/**
* Remove a mesh from the floor meshes array
* @param mesh the mesh to remove
*/
removeFloorMesh(mesh: AbstractMesh): void;
/**
* Remove a mesh from the blocker meshes array
* @param mesh the mesh to remove
*/
removeBlockerMesh(mesh: AbstractMesh): void;
/**
* Remove a mesh from the floor meshes array using its name
* @param name the mesh name to remove
*/
removeFloorMeshByName(name: string): void;
/**
* This function will iterate through the array, searching for this point or equal to it. It will then remove it from the snap-to array
* @param snapPointToRemove the point (or a clone of it) to be removed from the array
* @returns was the point found and removed or not
*/
removeSnapPoint(snapPointToRemove: Vector3): boolean;
/**
* This function sets a selection feature that will be disabled when
* the forward ray is shown and will be reattached when hidden.
* This is used to remove the selection rays when moving.
* @param selectionFeature the feature to disable when forward movement is enabled
*/
setSelectionFeature(selectionFeature: Nullable<IWebXRFeature>): void;
protected _onXRFrame(_xrFrame: XRFrame): void;
private _attachController;
private _createDefaultTargetMesh;
private _detachController;
private _findClosestSnapPointWithRadius;
private _setTargetMeshPosition;
private _setTargetMeshVisibility;
private _disposeBezierCurve;
private _colorArray;
private _showParabolicPath;
private _teleportForward;
}