XR
Advanced Components
To help developers quickly develop XR projects, Galacean provides the @galacean/engine-toolkit-xr advanced components. This document details their properties and interfaces.
Type | Class | Description |
---|
Component | TrackedComponent | Automatically attached to tracked prefabs/models when tracking is detected. Retrieve it via XRAnchorManager.getTrackedComponentByTrackId by ID. |
| XROrigin | A component that defines the XR space's origin and camera . Only one can be active at a time. |
Manager | XRAnchorManager | A component that enables anchor tracking, configures anchors, and attaches prefabs/models. Only one can be active at a time. |
| XRImageManager | A component that enables image tracking, configures reference images, and attaches prefabs/models. Only one can be active at a time. |
| XRPlaneManager | A component that enables plane tracking, configures detection modes, and attaches prefabs/models. Only one can be active at a time. |
All are high-level features implemented via scripts, providing high-level abstractions for @galacean/engine-xr core operations.
Property | Type | Description |
---|
mode | XRSessionMode | XR session mode. For AR , specify XRTrackedInputDevice.Camera . For VR , specify XRTrackedInputDevice.LeftCamera and XRTrackedInputDevice.RightCamera . |
origin | Entity | Sets the XRManager.origin |
camera | Entity | Connects the virtual camera to the device camera (typically AR camera) |
leftCamera | Entity | Connects to the left eye of HMD devices |
rightCamera | Entity | Connects to the right eye of HMD devices |
Property | Type | Description |
---|
data | XRTracked | Tracking result data containing ID, pose, and status |
destroyedOnRemoval | boolean | Whether to remove the entity when tracking is lost (typically true ) |
Property | Type | Description |
---|
prefab | boolean | Whether to remove the entity when tracking is lost (typically true ) |
Method | Description |
---|
getTrackedComponentByTrackId | Retrieve the component attached to a tracked object by its unique ID |
Property | Type | Description |
---|
anchors | Anchor Array | Specifies anchor poses to track |
Property | Type | Description |
---|
trackingImages | XRReferenceImage Array | Specifies images to track |
Property | Type | Description |
---|
detectionMode | XRPlaneMode | Specifies plane detection type |
const scene = sceneManager.scenes[0];
const origin = scene.addRootEntity("origin");
const camera = origin.createChild("camera");
camera.addComponent(Camera);
const xrOrigin = origin.addComponent(XROrigin);
// Set mode, origin, and camera
xrOrigin.mode = XRSessionMode.AR;
xrOrigin.origin = origin;
xrOrigin.camera = camera;
// Add plane detection manager and configure detection mode
const xrPlaneManager = origin.addComponent(XRPlaneManager);
xrPlaneManager.detectionMode = XRPlaneMode.EveryThing;
// When a plane is tracked, retrieve the component by ID
xrManager
.getFeature(XRPlaneTracking)
.addChangedListener(
(added: readonly XRTrackedPlane[], updated: readonly XRTrackedPlane[], removed: readonly XRTrackedPlane[]) => {
added.forEach((plane) => {
console.log("component", xrPlaneManager.getTrackedComponentByTrackId(plane.id));
});
}
);