@reactvision/react-viro 2.53.1 → 2.55.0

package/README.md

@@ -1,4 +1,3 @@
-
 <p align="center" style="background-colour: #CCCCCC;">
   <a href="https://www.reactvision.xyz/">
     <img src="https://avatars.githubusercontent.com/u/74572641?s=200&v=4" alt="ReactVision logo" width="120px" height="120px">
@@ -17,78 +16,118 @@
   </a>
 </p>
 
-<h1 align="center">ViroReact (ReactVision)</h1>
+# ViroReact, By ReactVision
 
-ViroReact is a library for building Augmented Reality (AR) and Virtual Reality (VR) experiences using React Native. Viro runs your code natively across mobile VR (including Google Daydream, Samsung Gear VR, and Google Cardboard on iOS and Android) and AR platforms (iOS ARKit and Android ARCore).
+ViroReact is the most widely used open-source library for building Augmented Reality (AR) and Virtual Reality (VR) experiences with React Native. Write your app once in TypeScript and ship it natively across mobile AR and VR headsets — no new engine, no new language, no months of ramp-up.
 
-<table>
-  <tr>
-    <td align="centre">
-      <img height="200" src="https://raw.githubusercontent.com/viromedia/viro/master/code-samples/js/ARCarDemo/viro_car_marker_demo.gif" alt="AR car demo">
-    </td>
-    <td align="centre">
-      <img height="200" src="https://github.com/ViroCommunity/viro/assets/430272/b153b8e4-7b40-4197-b05b-dd1eb1566102" alt="Viro example">
-    </td>
-  </tr>
-</table>
+ViroReact is MIT licensed and free forever.
 
-## Documentation
+## Supported Platforms
+
+| Platform         | Support      |
+| ---------------- | ------------ |
+| iOS (ARKit)      | ✅ Supported |
+| Android (ARCore) | ✅ Supported |
+| Meta Horizon OS  | ✅ Supported |
+
+ViroReact works with both **React Native CLI** and **Expo** projects.
+
+## Installation
+
+```bash
+npm install @reactvision/react-viro
+```
+
+For Expo projects, the easiest way to start is to clone the official starter kit:
+
+- **Expo + TypeScript starter kit:** <https://github.com/ReactVision/expo-starter-kit-typescript>
+- **React Native CLI starter kit:** <https://github.com/ReactVision/starter-kit>
+
+For step-by-step setup instructions, including platform-specific permissions and build configuration, see the full installation guide in the docs: <https://viro-community.readme.io/docs/installation-instructions>
+
+## Features
+
+ViroReact ships with a complete spatial computing toolkit out of the box — no third-party plugins, no paid add-ons.
+
+**Tracking and anchoring**
+
+- AR plane detection with horizontal and vertical surface anchors
+- Image and object recognition triggers
+- Cloud Anchors for persistent, multi-user shared AR content _(Platform feature)_
+- Geospatial Anchors that pin content to real-world latitude, longitude, and altitude _(Platform feature)_
 
-Documentation is available here: https://viro-community.readme.io/docs/overview
+**Rendering**
 
-We do our best to keep it up to date, but you may occasionally encounter broken links or outdated samples. If you spot anything, please submit an edit or reach out on Discord: https://discord.gg/A6TaFNqwVc
+- PBR lighting, HDR environment maps, and real-time shadow casting
+- 360° photo and video environments
+- Portal rendering for immersive pass-through experiences
+- OBJ, FBX, and GLTF/GLB model loading with embedded animations
+- Custom procedural geometry and custom GPU shaders
 
-## Getting Started
+**Interaction and motion**
 
-If you’re starting a fresh project with ViroReact, clone one of the starter kits:
+- Built-in physics engine with dynamic and static bodies, collision callbacks
+- Particle system for fire, smoke, rain, snow, confetti, and other effects
+- Declarative animation system with sequencing and chaining
+- Full input event system: tap, drag, pinch, rotate, fuse, hover
 
-- Expo + TypeScript: https://github.com/ReactVision/expo-starter-kit-typescript
-- React Native: https://github.com/ReactVision/starter-kit
-- Expo + JavaScript: https://github.com/ReactVision/expo-starter-kit
+**Audio**
 
-## Examples
+- Spatial audio, 360° sound fields, and positioned 3D audio
 
-See the `./examples` directory for sample code demonstrating ViroReact usage, including automatic architecture detection and other features.
+## Platform Features
 
-You can also browse the example projects page: https://viro-community.readme.io/docs/examples  
-These are a little old (~2019), but they’re still a useful reference for many parts of the library.
+Cloud Anchors, Geospatial Anchors, and AI-powered 3D asset creation are powered by **ReactVision Platform** — managed cloud infrastructure built directly into ViroReact. Add your `rvApiKey` and `rvProjectId` and the platform handles hosting, resolution, and geospatial infrastructure for you.
 
-## Connect with the ReactVision Community
+You can get a Studio account, which includes Platform access, for free at <https://studio.reactvision.xyz>.
 
-For support, discussion, or contributing to ViroReact, Discord is the best place to find us:
+- Cloud Anchors guide: <https://viro-community.readme.io/docs/cloud-anchors>
+- Geospatial Anchors guide: <https://viro-community.readme.io/docs/geospatial-anchors>
+
+## Documentation
+
+- Full API reference and guides: <https://viro-community.readme.io/docs/overview>
+- Getting started tutorial: <https://updates.reactvision.xyz/get-started-with-the-viroreact-and-expo-starter-kit-a9ca88803e5a>
+
+## Community
+
+Discord is the best place to find the team and other developers building with ViroReact:
 
 <a href="https://discord.gg/A6TaFNqwVc">
-  <img src="https://discordapp.com/api/guilds/774471080713781259/widget.png?style=banner2" alt="Discord Banner"/>
+  <img src="https://discordapp.com/api/guilds/774471080713781259/widget.png?style=banner2" />
 </a>
 
-## External Support
+## Enterprise Support and Partners
 
-If you need hands-on help, we maintain a list of trusted partners you can hire:  
-https://viro-community.readme.io/docs/hire-a-viro-react-expert
+For teams adopting XR at scale, the ReactVision team works directly with you on architecture, migrations from 8th Wall or Unity, performance audits, and shipping production experiences. <https://reactvision.xyz/contact>
 
-All partners are vetted by the ReactVision team and have experience shipping production-grade apps with Viro.
+For independent agencies and consultants vetted by the ReactVision team: <https://reactvision.xyz/partners>
 
-## Powered by
+## Supporters
 
-[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)
+A huge thank you to everyone who supports ongoing development by sponsoring us on GitHub: <https://github.com/sponsors/ReactVision>
 
-## Supporters
+- [Device Cloud](https://devicecloud.dev/)
+- [Looking Glass](http://looking-glass.space)
+- [@lentesta](https://github.com/lentesta)
+
+## Powered by
 
-A huge thank you to everyone who supports ongoing development by sponsoring us on GitHub:  
-https://github.com/sponsors/ReactVision
+[![JetBrains logo](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)
 
-- https://github.com/devicecloud-dev — Device Cloud: https://devicecloud.dev/
-- https://github.com/lentesta
-- Looking Glass: http://looking-glass.space
+JetBrains supports ViroReact development through their [Open Source program](https://jb.gg/OpenSource).
 
-## A little history…
+## Find Out More
 
-ViroReact was originally developed by Viro Media (http://www.viromedia.com/) and open-sourced in 2019.
+- Website: <https://reactvision.xyz>
+- ViroReact: <https://reactvision.xyz/viro-react>
+- ReactVision Studio: <https://studio.reactvision.xyz>
+- Blog: <https://updates.reactvision.xyz>
 
-In late 2020, the Viro Community formed to help maintain and modernise the project—keeping it compatible with current React Native versions and expanding functionality over time.
+## A little history…
 
-In 2025, Morrow acquired ReactVision (https://www.themorrow.digital/blog/morrow-acquires-reactvision-and-viroreact-library) to accelerate development and invest in the future of ViroReact. ReactVision now has a full-time team working to keep the codebase current and ready for the next generation of XR / spatial computing.
+ViroReact was originally developed by Viro Media and open-sourced in 2019. In late 2020, the Viro Community formed to maintain and modernise the project, keeping it compatible with current React Native versions. In January 2025, Morrow Digital acquired the project to invest in its future, and in late 2025 ReactVision was spun out as an independent company with a full-time team building the next generation of XR tooling.
 
-Our vision is to enable React Native developers to build AR and VR applications that run across XR devices (smartphones, smart glasses, and headsets) from a single React Native codebase.
+---
 
-We (as a community) owe a great debt to Viro Media and the original authors of this library, and we hope to make them proud as it continues to grow within ReactVision.
+MIT licensed. © ReactVision, Inc.

package/components/AR/ViroARCamera.tsx

@@ -14,11 +14,16 @@
 import * as React from "react";
 import { ViewProps } from "react-native";
 import { ViroCamera } from "../ViroCamera";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 export class ViroARCamera extends React.Component<ViewProps> {
   _component: ViroCamera | null = null;
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARCamera is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this to check props
     return (
       <ViroCamera

package/components/AR/ViroARImageMarker.tsx

@@ -19,6 +19,7 @@ import {
   ViroARAnchorUpdatedEvent,
 } from "../Types/ViroEvents";
 import { ViroBase } from "../ViroBase";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 /**
  * Container for Viro Components anchored to a detected image.
@@ -47,6 +48,10 @@ export class ViroARImageMarker extends ViroBase<{}> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARImageMarker is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARImageMarker", this.props);
 

package/components/AR/ViroARObjectMarker.tsx

@@ -14,6 +14,7 @@
 import { ViroBase } from "../ViroBase";
 import * as React from "react";
 import { NativeSyntheticEvent, requireNativeComponent } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 import {
   ViroARAnchorFoundEvent,
   ViroARAnchorRemovedEvent,
@@ -45,6 +46,10 @@ export class ViroARObjectMarker extends ViroBase<Props> {
   }
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARObjectMarker is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARObjectMarker", this.props);
 

package/components/AR/ViroARPlane.tsx

@@ -19,6 +19,7 @@ import {
 import { ViroBase } from "../ViroBase";
 import * as React from "react";
 import { NativeSyntheticEvent, requireNativeComponent } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 type Props = {
   anchorId?: string;
@@ -58,6 +59,10 @@ export class ViroARPlane extends ViroBase<Props> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARPlane is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARPlane", this.props);
 

package/components/AR/ViroARPlaneSelector.tsx

@@ -13,6 +13,7 @@
 
 import { ViroAnchor, ViroPlaneUpdatedMap } from "../Types/ViroEvents";
 import * as React from "react";
+import { isQuest } from "../Utilities/ViroPlatform";
 import { ViroMaterials } from "../Material/ViroMaterials";
 import { ViroNode } from "../ViroNode";
 import { ViroQuad } from "../ViroQuad";
@@ -416,6 +417,10 @@ export class ViroARPlaneSelector extends React.Component<Props, State> {
   // ---------------------------------------------------------------------------
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARPlaneSelector is not supported on Quest and will not render.");
+      return null;
+    }
     return <ViroNode>{this._renderPlanes()}</ViroNode>;
   }
 

package/components/AR/ViroARScene.tsx

@@ -50,6 +50,7 @@ import { ViroCamera } from "../ViroCamera";
 import { ViroTrackingStateConstants } from "../ViroConstants";
 import { ViroCommonProps } from "./ViroCommonProps";
 import { ViroOrbitCamera } from "components/ViroOrbitCamera";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 const ViroCameraModule = NativeModules.ViroCameraModule;
 
@@ -413,6 +414,10 @@ export class ViroARScene extends ViroBase<Props> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARScene is not supported on Quest and will not render. Use ViroScene instead.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARScene", this.props);
 

package/components/AR/ViroARSceneNavigator.tsx

@@ -18,8 +18,11 @@ import {
   NativeModules,
   requireNativeComponent,
   StyleSheet,
+  Text,
+  View,
   ViewProps,
 } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 import {
   ViroWorldOrigin,
   ViroProvider,
@@ -75,6 +78,13 @@ type Props = ViewProps & {
   };
   initialSceneKey?: string;
 
+  /**
+   * Optional fallback rendered when this navigator is mounted on a Meta Quest
+   * device (where AR is not supported). When omitted, a default message view
+   * is rendered. Pass `null` to render nothing.
+   */
+  questFallback?: React.ReactNode;
+
   autofocus?: boolean;
   /**
    * iOS only props! Note: these props may change as the underlying platforms coalesce in features.
@@ -130,6 +140,28 @@ type Props = ViewProps & {
    */
   depthDebugEnabled?: boolean;
 
+  /**
+   * Enable semantic segmentation debug visualization. When enabled, the camera
+   * background shows a color overlay for each real-world category (sky, building, tree,
+   * road, sidewalk, terrain, structure, object, vehicle, person, water).
+   * Requires `setSemanticModeEnabled(true)` to be called on the scene navigator first.
+   *
+   * @default false
+   */
+  semanticDebugEnabled?: boolean;
+
+  /**
+   * Confidence threshold (0.0–1.0) below which semantic labels are discarded (treated
+   * as unlabeled = 0) before the texture is uploaded to the GPU. Higher values reduce
+   * noise and boundary blinking at the cost of smaller labeled regions.
+   *
+   * Only used on Android (ARCore provides per-pixel confidence). On iOS, ARKit's
+   * segmentation is already temporally smoothed by the OS.
+   *
+   * @default 0.0
+   */
+  semanticConfidenceThreshold?: number;
+
   /**
    * [iOS Only] Prefer monocular depth estimation over LiDAR.
    * When true, monocular depth will be used even on devices with LiDAR.
@@ -210,6 +242,7 @@ type State = {
  * ViroARSceneNavigator is used to transition between multiple AR Scenes.
  */
 export class ViroARSceneNavigator extends React.Component<Props, State> {
+  static _questWarningLogged = false;
   _component: ViroNativeRef = null;
 
   constructor(props: Props) {
@@ -1105,6 +1138,22 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     );
   };
 
+  _rvGetProject = async (): Promise<any> => {
+    return await ViroARSceneNavigatorModule.rvGetProject(findNodeHandle(this));
+  };
+
+  _rvGetScene = async (sceneId: string): Promise<any> => {
+    return await ViroARSceneNavigatorModule.rvGetScene(
+      findNodeHandle(this), sceneId
+    );
+  };
+
+  _rvGetSceneAssets = async (sceneId: string): Promise<any> => {
+    return await ViroARSceneNavigatorModule.rvGetSceneAssets(
+      findNodeHandle(this), sceneId
+    );
+  };
+
   _rvAttachAssetToCloudAnchor = async (
     anchorId: string,
     fileUrl: string,
@@ -1394,6 +1443,9 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     rvAttachAssetToCloudAnchor: this._rvAttachAssetToCloudAnchor,
     rvRemoveAssetFromCloudAnchor: this._rvRemoveAssetFromCloudAnchor,
     rvTrackCloudAnchorResolution: this._rvTrackCloudAnchorResolution,
+    rvGetProject: this._rvGetProject,
+    rvGetScene: this._rvGetScene,
+    rvGetSceneAssets: this._rvGetSceneAssets,
     // Assets API
     rvUploadAsset: this._rvUploadAsset,
     // Scene Semantics API
@@ -1452,6 +1504,9 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     rvAttachAssetToCloudAnchor: this._rvAttachAssetToCloudAnchor,
     rvRemoveAssetFromCloudAnchor: this._rvRemoveAssetFromCloudAnchor,
     rvTrackCloudAnchorResolution: this._rvTrackCloudAnchorResolution,
+    rvGetProject: this._rvGetProject,
+    rvGetScene: this._rvGetScene,
+    rvGetSceneAssets: this._rvGetSceneAssets,
     // Assets API
     rvUploadAsset: this._rvUploadAsset,
     // Scene Semantics API
@@ -1472,6 +1527,26 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARSceneNavigator", this.props);
 
+    if (isQuest) {
+      if (!ViroARSceneNavigator._questWarningLogged) {
+        console.warn(
+          "[Viro] ViroARSceneNavigator is not supported on Meta Quest. " +
+            "Use ViroXRSceneNavigator (auto-detects Quest) or ViroVRSceneNavigator instead."
+        );
+        ViroARSceneNavigator._questWarningLogged = true;
+      }
+      if ("questFallback" in this.props) {
+        return <>{this.props.questFallback}</>;
+      }
+      return (
+        <View style={[styles.container, styles.questFallback]}>
+          <Text style={styles.questFallbackText}>
+            AR is not supported on Meta Quest.
+          </Text>
+        </View>
+      );
+    }
+
     const items = this._renderSceneStackItems();
 
     // update the arSceneNavigator with the latest given props on every render
@@ -1520,6 +1595,15 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
   },
+  questFallback: {
+    backgroundColor: "#000",
+    padding: 24,
+  },
+  questFallbackText: {
+    color: "#fff",
+    fontSize: 16,
+    textAlign: "center",
+  },
 });
 
 const VRTARSceneNavigator = requireNativeComponent<any>(

package/components/AR/ViroCommonProps.ts

@@ -103,6 +103,17 @@ export type ViroObjectProps = {
   shadowCastingBitMask?: number;
 
   shaderModifiers?: ViroShaderModifiers;
+  /**
+   * Apply shader modifiers from named materials to this node and all its children,
+   * preserving embedded textures (e.g. GLB/VRX). Unlike `materials`, which replaces
+   * the root geometry's material entirely, `shaderOverrides` merges only the shader
+   * modifiers and rendering properties from the named material onto every child mesh
+   * in the hierarchy. Use this for GLB models when you want to apply semantic masking,
+   * custom effects, or other per-material shader modifiers without losing the model's
+   * original textures and skinning.
+   *
+   * Accepts an array of material names previously registered via `ViroMaterials.createMaterials`.
+   */
   shaderOverrides?: string[];
   materialUniforms?: { [key: string]: any } | ViroShaderUniform[];
 

package/components/Material/ViroMaterials.ts

@@ -54,6 +54,43 @@ export type ViroResolvedCubeMap = {
   pz: ImageResolvedAssetSource;
 };
 
+export type ViroSemanticMaskMode = "showOnly" | "hide" | "debug";
+
+export type ViroSemanticLabel =
+  | "sky"
+  | "building"
+  | "tree"
+  | "road"
+  | "sidewalk"
+  | "terrain"
+  | "structure"
+  | "object"
+  | "vehicle"
+  | "person"
+  | "water";
+
+export type ViroSemanticMaskConfig = {
+  /** Whether to show the material only where the label matches, or to hide it there. */
+  mode: ViroSemanticMaskMode;
+  /** One or more semantic labels to match against. */
+  labels: ViroSemanticLabel[];
+};
+
+// Maps VROSemanticLabel enum value → bit position (bit N = label N, value 1-11).
+const kSemanticLabelBit: Record<ViroSemanticLabel, number> = {
+  sky:       1 << 1,
+  building:  1 << 2,
+  tree:      1 << 3,
+  road:      1 << 4,
+  sidewalk:  1 << 5,
+  terrain:   1 << 6,
+  structure: 1 << 7,
+  object:    1 << 8,
+  vehicle:   1 << 9,
+  person:    1 << 10,
+  water:     1 << 11,
+};
+
 export type ViroShaderModifier = {
   body?: string;
   uniforms?: string;
@@ -116,6 +153,10 @@ export type ViroMaterial = {
   ambientOcclusionTexture?: any; // TODO: types
   shaderModifiers?: ViroShaderModifiers;
   materialUniforms?: ViroShaderUniform[];
+  /** Semantic masking — shows or hides the material based on ARCore scene semantics labels.
+   *  Requires `setSemanticModeEnabled(true)` on the AR scene navigator.
+   *  Only supported on Android (ARCore). Gracefully no-ops on iOS. */
+  semanticMask?: ViroSemanticMaskConfig;
 };
 
 export type ViroMaterialDict = {
@@ -163,6 +204,16 @@ export class ViroMaterials {
         } else if (prop.endsWith("color") || prop.endsWith("Color")) {
           var color = processColor(material[prop]);
           resultMaterial[prop] = color;
+        } else if (prop === "semanticMask") {
+          const config = material[prop] as ViroSemanticMaskConfig;
+          let labelMask = 0;
+          for (const label of config.labels) {
+            labelMask |= kSemanticLabelBit[label] ?? 0;
+          }
+          resultMaterial["semanticMask"] = {
+            mode: config.mode,
+            labelMask,
+          };
         } else {
           //just apply material property directly.
           resultMaterial[prop] = material[prop];