Refactor XR session handling into a script (#184)

* Refactor XR session handling into a script

* Lint fixes

* Tweak xr-session script

Author: willeastcott

examples/animation.html

@@ -21,6 +21,7 @@
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-controllers.mjs"></pc-asset>
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-navigation.mjs"></pc-asset>
             <pc-asset src="../node_modules/playcanvas/scripts/esm/shadow-catcher.mjs"></pc-asset>
+            <pc-asset src="assets/scripts/xr-session.mjs"></pc-asset>
             <pc-asset src="assets/skies/dry-lake-bed-2k.hdr" id="lake-bed"></pc-asset>
             <pc-asset src="assets/models/t-rex.glb" id="t-rex"></pc-asset>
             <!-- Scene -->
@@ -43,6 +44,7 @@
                     <pc-scripts>
                         <pc-script name="xrControllers"></pc-script>
                         <pc-script name="xrNavigation"></pc-script>
+                        <pc-script name="xrSession"></pc-script>
                     </pc-scripts>
                 </pc-entity>
                 <!-- Light -->

examples/annotations.html

@@ -25,6 +25,7 @@
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-navigation.mjs"></pc-asset>
             <pc-asset src="../node_modules/playcanvas/scripts/esm/shadow-catcher.mjs"></pc-asset>
             <pc-asset src="assets/scripts/annotation.mjs"></pc-asset>
+            <pc-asset src="assets/scripts/xr-session.mjs"></pc-asset>
             <pc-asset src="assets/skies/shanghai-riverside-4k.hdr" id="shanghai"></pc-asset>
             <pc-asset src="assets/models/jet-fighter.glb" id="jet-fighter"></pc-asset>
             <!-- Scene -->
@@ -47,6 +48,7 @@
                     <pc-scripts>
                         <pc-script name="xrControllers"></pc-script>
                         <pc-script name="xrNavigation"></pc-script>
+                        <pc-script name="xrSession"></pc-script>
                     </pc-scripts>
                 </pc-entity>
                 <!-- Light -->

examples/assets/scripts/xr-session.mjs

@@ -0,0 +1,156 @@
+import { Color, Quat, Script, Vec3 } from 'playcanvas';
+
+export class XrSession extends Script {
+    static scriptName = 'xrSession';
+
+    /**
+     * Event name to start the XR session. Handler expects two arguments:
+     *  (type: 'immersive-ar' | 'immersive-vr', space?: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer')
+     * If type is omitted, defaults to 'immersive-vr'. If space is omitted, defaults to 'local-floor'.
+     * @type {string}
+     * @attribute
+     */
+    startEvent = 'xr:start';
+
+    /**
+     * Event name to end the XR session.
+     * @type {string}
+     * @attribute
+     */
+    endEvent = 'xr:end';
+
+    cameraEntity = null;
+
+    cameraRootEntity = null;
+
+    clearColor = new Color();
+
+    originalSkyType = null;
+
+    positionRoot = new Vec3();
+
+    rotationRoot = new Quat();
+
+    positionCamera = new Vec3();
+
+    rotationCamera = new Quat();
+
+    onKeyDownHandler = null;
+
+    initialize() {
+        this.cameraEntity = this.entity.findComponent('camera')?.entity || null;
+        this.cameraRootEntity = this.entity || null;
+
+        // Listen to global XR lifecycle to mirror example.mjs behavior
+        this.app.xr?.on('start', this.onXrStart, this);
+        this.app.xr?.on('end', this.onXrEnd, this);
+
+        // Listen for external events to control session
+        this.app.on(this.startEvent, this.onStartEvent, this);
+        this.app.on(this.endEvent, this.onEndEvent, this);
+
+        // ESC to exit
+        this.onKeyDownHandler = (event) => {
+            if (event.key === 'Escape' && this.app.xr?.active) {
+                this.endSession();
+            }
+        };
+        window.addEventListener('keydown', this.onKeyDownHandler);
+    }
+
+    destroy() {
+        this.app.xr?.off('start', this.onXrStart, this);
+        this.app.xr?.off('end', this.onXrEnd, this);
+        this.app.off(this.startEvent, this.onStartEvent, this);
+        this.app.off(this.endEvent, this.onEndEvent, this);
+        if (this.onKeyDownHandler) {
+            window.removeEventListener('keydown', this.onKeyDownHandler);
+            this.onKeyDownHandler = null;
+        }
+    }
+
+    onStartEvent(type = 'immersive-vr', space = 'local-floor') {
+        this.startSession(type, space);
+    }
+
+    onEndEvent() {
+        this.endSession();
+    }
+
+    startSession(type = 'immersive-vr', space = 'local-floor') {
+        if (!this.cameraEntity.camera) {
+            console.error('XrSession: No cameraEntity.camera found on the entity.');
+            return;
+        }
+
+        // Start XR on the camera component
+        this.cameraEntity.camera.startXr(type, space, {
+            callback: (err) => {
+                if (err) console.error(`WebXR ${type} failed to start: ${err.message}`);
+            }
+        });
+    }
+
+    endSession() {
+        if (!this.cameraEntity.camera) return;
+        this.cameraEntity.camera.endXr();
+    }
+
+    onXrStart() {
+        if (!this.cameraEntity || !this.cameraRootEntity) return;
+
+        // Cache original camera rig transforms
+        this.positionRoot.copy(this.cameraRootEntity.getPosition());
+        this.rotationRoot.copy(this.cameraRootEntity.getRotation());
+        this.positionCamera.copy(this.cameraEntity.getPosition());
+        this.rotationCamera.copy(this.cameraEntity.getRotation());
+
+        // Place root at camera position/orientation
+        this.cameraRootEntity.setPosition(this.positionCamera.x, 0, this.positionCamera.z);
+        this.cameraRootEntity.setRotation(this.rotationCamera);
+
+        if (this.app.xr.type === 'immersive-ar') {
+            // Make camera background transparent and hide the sky
+            this.clearColor.copy(this.cameraEntity.camera.clearColor);
+            this.cameraEntity.camera.clearColor = new Color(0, 0, 0, 0);
+            this.disableSky();
+        }
+    }
+
+    onXrEnd() {
+        if (!this.cameraEntity || !this.cameraRootEntity) return;
+
+        // Restore original transforms
+        this.cameraRootEntity.setPosition(this.positionRoot);
+        this.cameraRootEntity.setRotation(this.rotationRoot);
+        this.cameraEntity.setPosition(this.positionCamera);
+        this.cameraEntity.setRotation(this.rotationCamera);
+
+        if (this.app.xr.type === 'immersive-ar') {
+            this.cameraEntity.camera.clearColor = this.clearColor;
+            this.restoreSky();
+        }
+    }
+
+    disableSky() {
+        const sky = document.querySelector('pc-sky');
+        if (!sky) return;
+        if (this.originalSkyType === null) {
+            this.originalSkyType = sky.getAttribute('type');
+        }
+        sky.setAttribute('type', 'none');
+    }
+
+    restoreSky() {
+        const sky = document.querySelector('pc-sky');
+        if (!sky) return;
+        if (this.originalSkyType !== null) {
+            if (this.originalSkyType) {
+                sky.setAttribute('type', this.originalSkyType);
+            } else {
+                sky.removeAttribute('type');
+            }
+            this.originalSkyType = null;
+        }
+    }
+}

examples/basic-shapes.html

@@ -20,6 +20,7 @@
             <pc-asset id="camera-controls" src="../node_modules/playcanvas/scripts/esm/camera-controls.mjs" preload></pc-asset>
             <pc-asset id="xr-controllers" src="../node_modules/playcanvas/scripts/esm/xr-controllers.mjs" preload></pc-asset>
             <pc-asset id="xr-navigation" src="../node_modules/playcanvas/scripts/esm/xr-navigation.mjs" preload></pc-asset>
+            <pc-asset src="assets/scripts/xr-session.mjs"></pc-asset>
             <!-- Materials -->
             <pc-material id="crimson" diffuse="crimson"></pc-material>
             <pc-material id="mediumseagreen" diffuse="mediumseagreen"></pc-material>
@@ -47,6 +48,7 @@
                     <pc-scripts>
                         <pc-script name="xrControllers"></pc-script>
                         <pc-script name="xrNavigation"></pc-script>
+                        <pc-script name="xrSession"></pc-script>
                     </pc-scripts>
                 </pc-entity>
                 <!-- Key Light (Spot) -->

examples/car-configurator.html

@@ -24,6 +24,7 @@
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-controllers.mjs"></pc-asset>
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-navigation.mjs"></pc-asset>
             <pc-asset src="assets/scripts/choose-color.mjs"></pc-asset>
+            <pc-asset src="assets/scripts/xr-session.mjs"></pc-asset>
             <pc-asset src="assets/skies/octagon-lamps-photo-studio-2k.hdr" id="studio"></pc-asset>
             <pc-asset src="assets/models/porsche-911-carrera-4s.glb" id="car"></pc-asset>
             <!-- Scene -->
@@ -48,6 +49,7 @@
                     <pc-scripts>
                         <pc-script name="xrControllers"></pc-script>
                         <pc-script name="xrNavigation"></pc-script>
+                        <pc-script name="xrSession"></pc-script>
                     </pc-scripts>
                 </pc-entity>
                 <!-- Car -->

examples/css/example.css

@@ -34,7 +34,7 @@ canvas {
     display: flex;
     position: relative;
     height: 40px;
-    background: rgba(255, 255, 255, 0.9);
+    background-color: rgba(255, 255, 255, 0.9);
     border: 1px solid #ddd;
     border-radius: 8px;
     cursor: pointer;
@@ -52,8 +52,17 @@ canvas {
 .example-button.icon {
     width: 40px;
     padding: 0;
+    background-position: center center;
+    background-repeat: no-repeat;
+    background-size: 24px 24px;
 }
 
+.example-button.icon.icon-ar { background-image: url("../img/ar.svg"); }
+.example-button.icon.icon-vr { background-image: url("../img/vr.svg"); }
+.example-button.icon.icon-fs-enter { background-image: url("../img/fullscreen-enter.svg"); }
+.example-button.icon.icon-fs-exit { background-image: url("../img/fullscreen-exit.svg"); }
+.example-button.icon.icon-source { background-image: url("../img/code.svg"); }
+
 .example-button:hover {
-    background: rgba(255, 255, 255, 1);
+    background-color: rgba(255, 255, 255, 1);
 }

examples/glb.html

@@ -21,6 +21,7 @@
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-controllers.mjs"></pc-asset>
             <pc-asset src="../node_modules/playcanvas/scripts/esm/xr-navigation.mjs"></pc-asset>
             <pc-asset src="assets/scripts/rotate.mjs"></pc-asset>
+            <pc-asset src="assets/scripts/xr-session.mjs"></pc-asset>
             <pc-asset src="assets/skies/octagon-lamps-photo-studio-2k.hdr" id="studio"></pc-asset>
             <pc-asset src="assets/models/playcanvas-cube.glb" id="cube"></pc-asset>
             <!-- Scene -->
@@ -43,6 +44,7 @@
                     <pc-scripts>
                         <pc-script name="xrControllers"></pc-script>
                         <pc-script name="xrNavigation"></pc-script>
+                        <pc-script name="xrSession"></pc-script>
                     </pc-scripts>
                 </pc-entity>
                 <!-- Light -->