Galacean Logo
Documentation
API Reference
Examples
Playground
XR

Developing XR Interactions

This document explains how to quickly develop XR interactions in both the editor and ProCode environments.

Editor

The workflow for developing XR interactions in the editor is as follows:

Create Project

Click Create Project on the Home Page, then select WebXR as the physics backend in Project Settings.

image.png

Add XR Node

Add an XR node in the Hierarchy Panel.

image.png

Adding an XR node automatically creates and selects origin and camera. Therefore, no other Camera components should exist in the scene unless intentionally added.

Multiple XR nodes can be added to a scene, but only one XR node will be active at any given time.

Preview

If you've followed the XR Debugging Guide and installed Chrome with the Immersive Web Emulator extension, you can preview directly now.

image.png

XR Capabilities

To achieve immersive mixed reality effects, additional capabilities can be added to XR interactions.

Anchor Tracking

Add the XR Anchor Manager component to any active entity to enable anchor tracking in XR.

PropertyDescription
Anchor ListList of anchors to track, defined by Position and RotationQuaternion
PrefabIf set, this prefab will be instantiated and attached to the tracked anchor
image.png

Image Tracking

Add the XR Image Manager component to any active entity to enable image tracking in XR.

PropertyDescription
Image ListList of reference images for tracking
PrefabIf set, this prefab will be instantiated when the image is tracked
image.png

To upload reference images:
Right-click in the Asset Panel → Upload → XRReferenceImage → Select the target image.

PropertyDescription
NameUnique identifier for the tracked image
PrefabIf set, this prefab will be instantiated when the image is tracked

Image tracking cannot be debugged in the editor. Mobile preview and debugging are required after export.

Plane Tracking

Add the XR Plane Manager component to any active entity to enable plane tracking in XR.

PropertyDescription
Detection ModePlane detection mode (None, Horizontal, Vertical, Everything)
PrefabIf set, this prefab will be instantiated when a plane is detected
image.png

Notes

Note that WebXR requires entering the XR context via a button click on the page. For XR projects, the editor automatically adds a button during preview. After export, developers must manually implement this:

// XR Manager  
const xrManager = engine.xrManager;  
// Target XR session mode  
const xrMode = XRSessionMode.AR;  
engine.xrManager.sessionManager.isSupportedMode(xrMode).then(  
  () => {  
    // Enter XR session on button click  
    htmlButton.onclick = () => {  
      xrManager.enterXR(xrMode);  
    };  
  },  
  (error) => {  
    // Mode not supported  
    console.error(error);  
  }  
);

Was this page helpful?