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.

TypeClassDescription
ComponentTrackedComponentAutomatically attached to tracked prefabs/models when tracking is detected. Retrieve it via XRAnchorManager.getTrackedComponentByTrackId by ID.
XROriginA component that defines the XR space's origin and camera. Only one can be active at a time.
ManagerXRAnchorManagerA component that enables anchor tracking, configures anchors, and attaches prefabs/models. Only one can be active at a time.
XRImageManagerA component that enables image tracking, configures reference images, and attaches prefabs/models. Only one can be active at a time.
XRPlaneManagerA component that enables plane tracking, configures detection modes, and attaches prefabs/models. Only one can be active at a time.

Inheritance Hierarchy

All are high-level features implemented via scripts, providing high-level abstractions for @galacean/engine-xr core operations.

XROrigin

PropertyTypeDescription
modeXRSessionModeXR session mode. For AR, specify XRTrackedInputDevice.Camera. For VR, specify XRTrackedInputDevice.LeftCamera and XRTrackedInputDevice.RightCamera.
originEntitySets the XRManager.origin
cameraEntityConnects the virtual camera to the device camera (typically AR camera)
leftCameraEntityConnects to the left eye of HMD devices
rightCameraEntityConnects to the right eye of HMD devices

TrackedComponent

PropertyTypeDescription
dataXRTrackedTracking result data containing ID, pose, and status
destroyedOnRemovalbooleanWhether to remove the entity when tracking is lost (typically true)

XRTrackedObjectManager

PropertyTypeDescription
prefabbooleanWhether to remove the entity when tracking is lost (typically true)
MethodDescription
getTrackedComponentByTrackIdRetrieve the component attached to a tracked object by its unique ID

XRAnchorManager

PropertyTypeDescription
anchorsAnchor ArraySpecifies anchor poses to track

XRImageManager

PropertyTypeDescription
trackingImagesXRReferenceImage ArraySpecifies images to track

XRPlaneManager

PropertyTypeDescription
detectionModeXRPlaneModeSpecifies plane detection type

Example Usage

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));
      });
    }
  );

Was this page helpful?