StudioSceneNavigator
Integrate Scenes built in ReactVision Editor into your project as either AR, VR or XR scenes using the StudioSceneNavigator
Introduced in ViroReact 2.55.0
StudioSceneNavigator is the runtime bridge between ReactVision Editor and the ViroReact renderer. It is a drop-in component that fetches a scene authored in ReactVision Editor, resolves all of its assets, animations, materials, and scene functions, and renders it cross-reality — AR on iOS and Android phones, VR on Meta Quest — using ViroXRSceneNavigator underneath.
In other words: StudioSceneNavigator is to scenes built in the Editor what ViroARSceneNavigator is to hand-coded AR scenes. Most apps built with the Editor mount one StudioSceneNavigator and let it handle the rest.
Editor integration
StudioSceneNavigator requires a ReactVision Editor account and a client key as rvApiKey in your Expo plugin config, with rvProjectId set to the project whose scenes it opens. A client key reaches only its own project, so it cannot open a scene from another one. For step-by-step setup — generating credentials, configuring the plugin, and creating a project — see the Getting Started with ReactVision Spatial guide.
The component talks to ReactVision Spatial through VRTStudioModule.rvGetProject() and VRTStudioModule.rvGetScene(sceneId) internally — no API keys or endpoint URLs are present in your JS bundle.
Platform compatibility
| Platform | Supported | Notes |
|---|---|---|
| iOS | ✅ | Renders the Editor scene in AR (ARKit) via ViroXRSceneNavigator's AR path |
| Android | ✅ | Renders the Editor scene in AR (ARCore) via ViroXRSceneNavigator's AR path |
| Meta Quest | ✅ | Renders the Editor scene in VR via VRActivity. StudioARScene swaps its root to ViroScene automatically on Quest |
| Apple visionOS | ✅ | 3.1.0+. Renders the Editor scene in the ImmersiveSpace. StudioARScene roots in ViroScene on visionOS, as on Quest (before 3.1.0 the scene was blank) |
| Web | ✅ | 3.0.0+. Renders in the browser with @reactvision/viro-web-renderer; no co-location, VPS location, photo capture, video recording or occlusion. See Editor scenes on web and the Web Setup Guide |
Required Expo / React Native versions
StudioSceneNavigator is built on top of ViroXRSceneNavigator and inherits the same requirements.
ViroReact 3.2.0 requires Expo SDK 58 and React Native 0.88 on every path (expo >=58.0.0 <59.0.0, react-native >=0.88.0 <0.89.0, React 19.3). React Native 0.86 and Expo SDK 57 stay on ViroReact 3.1.x. See Upgrading to 3.2.0. See the Meta Quest setup guide for full configuration steps.
Scene alerts (3.2.0+)
An alert shown by a scene's ALERT function shows its own close button label, read from the scene's alert_action_button_title. It always read OK before 3.2.0, and still reads OK when the label is empty or ReactVision Spatial does not send it. On phones the label goes on the native alert's button; on Meta Quest it goes on the in-scene panel's button.
Editor scenes on web (3.2.2+)
On web, StudioSceneNavigator follows the native host's rules more closely. These need @reactvision/viro-web-renderer 1.2.0.
- Animations follow the native host's animation slot rules. A looping animation reports a finish at every cycle but never ends, and a model clip is looked up in the model by its embedded name.
ALERTfunctions show a dialog over the canvas, with the scene's own button label (OK when it is empty). It is a DOM element beside the canvas, so it is not in a screenshot or a canvas recording, like the native dialog. A NAVIGATION remounts the scene, and an alert shown just before it stays up.onSceneChangefires once a NAVIGATION has loaded.- Assets wait for tracking. In an AR scene with
plane_detectionset toNONE, assets sit at fixed scene-root coordinates, so they wait for the first NORMAL tracking state before showing, as on native. If tracking never gets there (a feature-poor room, a covered camera) they are revealed after a short window. The camera and tap-to-place do not wait. Tap-to-place waits for the AR session to start. - Dragging: an asset with dragging on can be dragged in live AR, and
FixedToPlaneslides along the plane the asset's anchor found. - Light: the scene's light rig is scaled from the camera's ambient light estimate, as on native. Only a dim room pulls it below the authored light.
- What the web host drops:
webCapabilitieslists co-location, manual plane selection and VPS locations as before, and from 3.2.2 also photo capture and video recording functions (TAKE_PHOTO,RECORD_VIDEO) and occlusion in AR. Dragging is no longer on the list.
Very basic example
In the simplest case you can mount StudioSceneNavigator with no props at all:
import * as React from "react";
import { StudioSceneNavigator } from "@reactvision/react-viro";
export default function App() {
return <StudioSceneNavigator />;
}
With no sceneId provided, the navigator resolves a scene to load automatically from the Editor project configured in your app's manifest (RVProjectId, set when you configure the Expo plugin — see the Getting Started with ReactVision Spatial guide). It picks a scene in the following order:
- The project's opening scene, if one has been set. You can configure this in the Editor via Edit Project, where you can mark any scene in the project as the opening scene.
- If no opening scene has been set, the first scene in the project's scene list.
This is the recommended pattern for most apps: configure your project once in the Editor, set an opening scene, and let StudioSceneNavigator do the rest. You can change which scene loads first by editing the project in the Editor — no app code or rebuild required.
Basic example
For more control, you can load a specific scene by its Editor UUID and wire up lifecycle callbacks:
import * as React from "react";
import { StyleSheet } from "react-native";
import { StudioSceneNavigator } from "@reactvision/react-viro";
export default function App() {
return (
<StudioSceneNavigator
sceneId="abc-123-uuid"
onSceneReady={() => console.log("scene ready")}
onError={(err) => console.error(err)}
style={StyleSheet.absoluteFill}
/>
);
}
Opening-scene resolution order with sceneId provided:
sceneIdprop.- (
sceneIdnot provided) → the project's opening scene (set in the Editor via Edit Project). - (No opening scene set) → the first scene in the project's scene list.
The same component runs unmodified on Quest. On Quest, StudioSceneNavigator waits for the scene data to resolve before mounting ViroXRSceneNavigator — that way VRActivity launches directly into the content scene rather than a placeholder, and a loading spinner is shown in the panel until the scene is ready. As with ViroXRSceneNavigator, always wire onExitViro so the panel can navigate away after VR ends:
<StudioSceneNavigator
sceneId="abc-123-uuid"
onExitViro={() => navigation.goBack()}
/>
Meta Quest panel and in-headset menu (v3.0.3+)
On Quest the scene runs in the headset view (VRActivity) while your app's 2D panel stays behind it. VR launches once, on mount. 3.1.0+: the headset view opens as the navigator mounts, with a loading panel in front of the wearer until the scene's data arrives. A failed load shows there too, with Retry and Exit, and onError is still called. loadingView shows only on the 2D panel behind the headset view. When the wearer leaves the headset view (Back/B, Home, Settings or the system menu), Horizon OS brings the panel forward and the headset view is not reopened on its own. Instead, the panel shows an "Enter immersive view" button. Pass renderQuestPanel to show your own panel, and call enter to reopen VR:
<StudioSceneNavigator
onExitViro={() => navigation.goBack()}
renderQuestPanel={(enter) => (
<View style={styles.panel}>
<Text>Scene paused</Text>
<Button title="Back to the headset" onPress={enter} />
</View>
)}
questMenuItems={[
{ label: "Restart scene", onPress: () => setSceneKey((k) => k + 1) },
{ label: "Toggle music", onPress: toggleMusic },
]}
/>
- In-headset menu. 3.1.0+: the menu opens and closes on the left controller's menu button, or with hands a pinch with the palm facing you (either hand). B closes the menu while it is open and exits the scene otherwise, and Y goes back as B does. In 3.0.3 it opened on Y. The menu and the other Quest panels are drawn at a quarter of their 3.0.3 size, and only a trigger or pinch selects. The menu is centred where the wearer is looking. It shows the scene name, a shared session's status and join code, the items you pass in
questMenuItems(StudioQuestMenuItem = { label: string; onPress: () => void }), and Exit. Pressing an item closes the menu. Nothing 2D can be seen from inside the headset, so put your scene actions here. - HUD placed in the room. The scene HUD appears in front of the wearer and stays there instead of following the head. It shows the scene name for 5 s after the scene opens, plus a shared session's status whenever it changes, including why a session failed. Its text is sharp.
- Plane detection. Editor scenes with plane detection set to Automatic or Manual no longer crash on Quest outside a shared session (their assets render at the scene root). A plane scene opened after another AR scene now gets the room's planes.
- Loading view. A custom
loadingViewfills the window on Quest, as it does on phones. The built-in spinner stays centred. - Alerts (3.2.0+). The in-scene alert panel's button shows the alert's own label and widens to fit it, wrapping a long one onto more lines. Next on the earlier pages of a long message takes the same button. See Scene alerts below.
- Leaving VR with
exitVRScene()returns to the panel through Home, where the wearer left it.
Co-location (v3.0.2+)
Share a scene built in the Editor with other devices in the same physical space. Set the colocation prop — absent, the scene renders alone exactly as before.
import { StudioSceneNavigator } from "@reactvision/react-viro";
import { useRef } from "react";
function Host() {
const ref = useRef(null);
return (
<StudioSceneNavigator
ref={ref}
colocation={{ mode: "host" }}
onColocationStateChange={(state) => console.log(state)}
onColocationRoom={(room) => console.log(room.joinCode)}
/>
);
}
function Join({ code }: { code: string }) {
return <StudioSceneNavigator colocation={{ mode: "join", code }} />;
}
- Host scans the space and creates a room with a six-character join code. Join looks a code up and aligns to the host's space. A Quest host shares a Meta spatial anchor instead of scanning.
- A live room shares variables, visibility, tap-to-place positions (last write wins), drags (the dragging device holds the asset), and
NAVIGATE. Animation triggers and sounds play on every device while the function behind them runs on one. Collision bindings keep running when the host leaves. - Joiners that connect before the host has placed the scene report
waiting_for_host.connectTimeoutMs(default60000) fails a room that never comes up withCONNECT_TIMEOUTorHOST_TIMEOUT. - Works with an API key or an Editor session (
rvSetStudioSessionalso reaches cloud anchors and the co-location channel). From 3.0.3, requests are served by ReactVision Spatial in its database's region, falling back to unpinned if that region is down.rvSetStudioSessiontakes an optionalfunctionRegionfor a session on another platform URL. - Same-family only (phone↔phone, Quest↔Quest). On web, co-location is not available — a set
colocationvalue reportsfailedwithFRAME_KIND_UNSUPPORTED. - Built-in pill:
colocationIndicator(defaulttrue). For custom UI use<StudioColocationIndicator />oruseStudioColocation(). On Quest the status and join code also show in the in-scene HUD (placed in the room from 3.0.3) and in the Y-button menu. See Meta Quest panel and in-headset menu.
See Co-Location for the lower-level frame/channel APIs used by hand-coded scenes.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
sceneId | string | — | UUID of a specific Editor scene to load. If omitted, the navigator fetches the project from the app manifest and uses its opening scene. |
worldAlignment | "Gravity" | "GravityAndHeading" | "Camera" | "Gravity" | Forwarded to the underlying ViroXRSceneNavigator AR path. |
autofocus | boolean | true | Forwarded to the underlying ViroXRSceneNavigator AR path. |
style | ViewStyle | StyleSheet.absoluteFill | Forwarded to the underlying ViroXRSceneNavigator. |
onSceneReady | () => void | — | Fires once the Editor scene has been fetched, parsed, and mounted. |
onError | (err: Error) => void | — | Fires if the scene fetch, parse, or mount fails. If omitted, errors are logged with console.error. |
onSceneChange | (sceneId: string, sceneName: string) => void | — | Fires when navigation between Editor scenes occurs (for example via a NAVIGATION scene function built in the Editor). |
onExitViro | () => void | — | Forwarded to ViroXRSceneNavigator. Fires when exitVRScene() is called. Use this to navigate away from the screen after VR ends, otherwise it'll be blank. |
renderQuestPanel | (enter: () => void) => React.ReactNode | "Enter immersive view" button | 3.0.3+ / Meta Quest. What the 2D panel shows while the headset view is closed. Call enter to reopen VR. Passed through to ViroXRSceneNavigator. |
questMenuItems | readonly StudioQuestMenuItem[] ({ label: string; onPress: () => void }) | — | 3.0.3+ / Meta Quest. Buttons listed above Exit in the in-scene menu, opened with the left controller's menu button or a palm pinch (Y in 3.0.3). Pressing one closes the menu. |
onSceneLoaded | (sceneData) => void | — | Fired after the scene is fetched and parsed, before it is pushed. |
onPlaneDetected / onPlaneSelected | () => void | — | Threaded to the initial scene's StudioARScene (initial scene only). |
loadingView | React.ReactNode | — | Opt-in overlay until the scene mounts. Omit to show the camera feed on AR; Quest falls back to a spinner. |
renderError | (error, retry) => React.ReactNode | — | Opt-in UI for a failed load or caught render error. onError still fires. |
recordingIndicator | boolean | true | Show the built-in REC pill while a RECORD_VIDEO action is recording. |
placementIndicator | boolean | true | Show the built-in tap-to-place prompt on mobile AR. |
colocation | { mode: "host"; name?; relayUrl?; connectTimeoutMs?; credentials? } | { mode: "join"; code; relayUrl?; connectTimeoutMs?; credentials? } | — | 3.0.2+. Share the scene in the same room. See Co-location. 3.1.0+: credentials, such as a user token from createUserTokenCredentials(), authenticate the room, relay, pose channel and shared state in place of rvApiKey or the Editor session. |
colocationIndicator | boolean | true | 3.0.2+. Show the built-in co-location pill (scan guidance / Done / join code). |
onColocationStateChange | (state: StudioColocationState) => void | — | 3.0.2+. Fires as the shared session progresses (scanning, live, waiting_for_host, failed, …). |
onColocationRoom | (room: StudioColocationRoom) => void | — | 3.0.2+. Once per room: when the host has its code, or when a joiner is in. |
onMotionUnavailable | (reason: "denied" | "no-events") => void | — | 3.0.2+ / web. Motion access denied or no events. Never called on native. |
onAssetError | (asset, error) => void | — | 3.0.2+ / web. An asset's model/image/video failed to load; the scene continues. |
onRendererAbort | (err) => void | — | 3.0.2+ / web. WASM runtime aborted (often OOM); terminal until remount. |
arOptions | Record<string, unknown> | — | 3.0.2+ / web. Forwarded to the AR session (feedWidth, feedHeight, poseSmoothing, …). |
noAssetsMessage | string | — | Message when a scene has no placeable assets. |
vpsLocalization | "device" | "server" | "device" | 3.1.0+. Where a scene bound to a VPS location localises. "device" downloads the location's map. "server" sends camera frames to the VPS server, which needs a map built with server mode and is billed as Advanced VPS compute. A change restarts tracking of the scene on screen in the new mode. See ViroVPS. |
onVpsStateChange | (event: StudioVpsStateEvent) => void | 3.1.0+. VPS tracking of the scene on screen: { sceneId, locationId, state, error? }, where state is idle, searching, mapLoaded, tracking, lost, error or unsupported. The scene's plane assets show only while tracking. Failures that may pass are retried; show a Retry for error that calls retryVps(). Meta Quest and Apple Vision Pro report unsupported. |
Scenes placed in a VPS location need ViroReact 3.1.0 or later. 3.1.0 sends
x-rv-capabilities: vpswhen it loads a scene, and ReactVision Spatial refuses a placed scene to older versions with 426SCENE_REQUIRES_VPS_RUNTIME. See Advanced VPS.
Methods
Via ref (StudioSceneNavigatorHandle), 3.0.2+:
| Method | Description |
|---|---|
takeScreenshot(fileName, saveToCameraRoll) | Screenshots the renderer. On Quest captures the left eye (not passthrough); may resolve errorCode RECORD_ERROR_NOT_READY until the VR scene is rendering. |
leaveColocation() | Leave the shared session; the current colocation prop value stays set (use retryColocation to restart). |
retryColocation() | Restart the current colocation value after failure or leave. Returns false while a session is running or no value is set. Re-rendering with an equal value never restarts it. |
getColocationRoom() | Current StudioColocationRoom or null. |
finishColocationScan() | Host: end the scan and host it (same as the indicator's Done). Returns true only when canFinish is true in the scanning state. |
retryVps() | 3.1.0+. Start VPS tracking again for the scene on screen after it reported error or idle, at once. Returns false, changing nothing, when the scene is not bound to a VPS location, cannot track here (Meta Quest, Apple Vision Pro, or no endpoint it may use) or is in another state. |
Scene-to-scene navigation in content built in the Editor is still driven by its NAVIGATION actions. For imperative push/pop over a hand-coded stack, use ViroXRSceneNavigator.
See also
Updated 3 days ago