fix(environment): compensate IBL rotation on XR recenter

Summary:
### Core fix: `environment-system.ts`

When a user recenters in XR (e.g., long-pressing the Oculus button), the reference space resets with a new origin/orientation. Previously, `environmentRotation` and `backgroundRotation` were not adjusted, causing the IBL lighting and skybox to visually shift relative to the real world.

The fix:
- Listens for `sessionstart`/`sessionend` on `xrManager` to track XR lifecycle
- Attaches a `reset` listener on the XR reference space (with deferred attachment via `needsResetListener` flag in the update loop if the ref space isn't available at session start)
- Extracts the yaw component from the reset event's quaternion transform
- Accumulates a `recenterYawOffset` that's applied to the Y rotation of both `scene.environmentRotation` (IBL) and `scene.backgroundRotation` (skybox) in `updateBackgroundProps`, `updateIBLProps`, and the immediate `applyRecenterCompensation` path
- Cleans up all listeners on session end and system disposal

### Test fixture: `scene-understanding` example

- Added a Venice sunset EXR texture to the asset manifest and `public/textures/`
- Added `IBLTexture` and `DomeTexture` components to the level root so the scene-understanding example has a directional HDR environment for visually verifying the recenter fix

Reviewed By: zjm-meta

Differential Revision: D94147476

fbshipit-source-id: 6ddf2d5f15aa9d83a11a8b28b4aa74ec1ca03f0f

Author: felixtrz

examples/scene-understanding/public/textures/venice_sunset_1k.exr

@@ -7,6 +7,7 @@
 
 import {
   XRAnchor,
+  AssetType,
   Color,
   XRMesh,
   XRPlane,
@@ -15,6 +16,8 @@ import {
   createSystem,
   Interactable,
   DistanceGrabbable,
+  IBLTexture,
+  DomeTexture,
   Mesh,
   SphereGeometry,
   MeshStandardMaterial,
@@ -90,7 +93,13 @@ export class SceneShowSystem extends createSystem({
 }
 
 World.create(document.getElementById('scene-container'), {
-  undefined,
+  assets: {
+    veniceSunset: {
+      url: './textures/venice_sunset_1k.exr',
+      type: AssetType.HDRTexture,
+      priority: 'critical',
+    },
+  },
   xr: {
     sessionMode: SessionMode.ImmersiveAR,
     referenceSpace: ReferenceSpaceType.Unbounded,
@@ -111,5 +120,9 @@ World.create(document.getElementById('scene-container'), {
 
   scene.background = new Color(0x808080);
 
+  const root = world.activeLevel.value;
+  root.addComponent(IBLTexture, { src: 'veniceSunset' });
+  root.addComponent(DomeTexture, { src: 'veniceSunset' });
+
   world.registerSystem(SceneShowSystem);
 });

examples/scene-understanding/src/index.js

@@ -77,6 +77,9 @@ export class EnvironmentSystem extends createSystem({
   private pmrem!: PMREMGenerator;
   private gradientGeometry?: SphereGeometry;
   private tmpColor: Color = new Color();
+  private recenterYawOffset: number = 0;
+  private resetListenerCleanup: (() => void) | null = null;
+  private needsResetListener: boolean = false;
 
   init(): void {
     this.pmrem = new PMREMGenerator(this.renderer);
@@ -93,9 +96,28 @@ export class EnvironmentSystem extends createSystem({
     this.cleanupFuncs.push(
       this.visibilityState.subscribe(() => this.updateBackgroundForXRMode()),
     );
+
+    // XR recenter compensation
+    this.xrManager.addEventListener('sessionstart', this.onXRSessionStart);
+    this.xrManager.addEventListener('sessionend', this.onXRSessionEnd);
+    this.cleanupFuncs.push(() => {
+      this.xrManager.removeEventListener('sessionstart', this.onXRSessionStart);
+      this.xrManager.removeEventListener('sessionend', this.onXRSessionEnd);
+      this.resetListenerCleanup?.();
+      this.resetListenerCleanup = null;
+    });
   }
 
   update(): void {
+    // Deferred reset listener attachment
+    if (this.needsResetListener) {
+      const refSpace = this.xrManager.getReferenceSpace();
+      if (refSpace) {
+        this.attachResetListener(refSpace);
+        this.needsResetListener = false;
+      }
+    }
+
     // Choose background source: DomeTexture > DomeGradient
     let backgroundEntity: Entity | undefined;
     for (const e of this.queries.domeTextures.entities) {
@@ -199,7 +221,11 @@ export class EnvironmentSystem extends createSystem({
     this.scene.backgroundBlurriness = blurriness;
     this.scene.backgroundIntensity = intensity;
     if (rot) {
-      this.scene.backgroundRotation?.set(rot[0] || 0, rot[1] || 0, rot[2] || 0);
+      this.scene.backgroundRotation?.set(
+        rot[0] || 0,
+        (rot[1] || 0) + this.recenterYawOffset,
+        rot[2] || 0,
+      );
     }
   }
 
@@ -295,7 +321,7 @@ export class EnvironmentSystem extends createSystem({
     if (rot) {
       this.scene.environmentRotation?.set(
         rot[0] || 0,
-        rot[1] || 0,
+        (rot[1] || 0) + this.recenterYawOffset,
         rot[2] || 0,
       );
     }
@@ -359,6 +385,76 @@ export class EnvironmentSystem extends createSystem({
     }
   }
 
+  // XR recenter handling
+  private onXRSessionStart = (): void => {
+    this.recenterYawOffset = 0;
+    const refSpace = this.xrManager.getReferenceSpace();
+    if (refSpace) {
+      this.attachResetListener(refSpace);
+    } else {
+      this.needsResetListener = true;
+    }
+  };
+
+  private attachResetListener(refSpace: XRReferenceSpace): void {
+    const onReset = (event: XRReferenceSpaceEvent) => {
+      this.onReferenceSpaceReset(event);
+    };
+    refSpace.addEventListener('reset', onReset);
+    this.resetListenerCleanup = () => {
+      refSpace.removeEventListener('reset', onReset);
+    };
+  }
+
+  private onXRSessionEnd = (): void => {
+    this.resetListenerCleanup?.();
+    this.resetListenerCleanup = null;
+    this.recenterYawOffset = 0;
+    this.needsResetListener = false;
+  };
+
+  private onReferenceSpaceReset(event: XRReferenceSpaceEvent): void {
+    const transform = event.transform;
+    if (!transform) {
+      return;
+    }
+
+    const q = transform.orientation;
+    const yaw = Math.atan2(
+      2 * (q.w * q.y + q.x * q.z),
+      1 - 2 * (q.y * q.y + q.z * q.z),
+    );
+
+    this.recenterYawOffset += yaw;
+    this.applyRecenterCompensation();
+  }
+
+  private applyRecenterCompensation(): void {
+    for (const entity of this.queries.iblTextures.entities) {
+      const rot = entity.getVectorView(IBLTexture, 'rotation');
+      if (rot) {
+        this.scene.environmentRotation?.set(
+          rot[0] || 0,
+          (rot[1] || 0) + this.recenterYawOffset,
+          rot[2] || 0,
+        );
+      }
+      break;
+    }
+
+    for (const entity of this.queries.domeTextures.entities) {
+      const rot = entity.getVectorView(DomeTexture, 'rotation');
+      if (rot) {
+        this.scene.backgroundRotation?.set(
+          rot[0] || 0,
+          (rot[1] || 0) + this.recenterYawOffset,
+          rot[2] || 0,
+        );
+      }
+      break;
+    }
+  }
+
   // XR background handling
   private updateBackgroundForXRMode(): void {
     const session = this.xrManager.getSession?.() ?? this.world.session;