Upgrading to 3.1.0

ViroReact 3.1.0 rebuilds the renderer binaries on virocore 3.1.0 and was released with ReactVision Spatial 1.4.0. The web build uses @reactvision/viro-web-renderer 1.1.0. Most apps upgrade with no code changes, but check the items below.

Do this when you upgrade

Re-run prebuild. The iOS binaries moved (see below) and the Expo plugin now removes a simulator setting it used to write, so run npx expo prebuild again. The plugin now replaces its own entries in place, so --clean is not needed. Without Expo, run pod install again.
Search your scripts and Podfile for the old iOS binary paths. The binaries are now ios/dist/ViroRenderer/ViroKit.xcframework and ios/dist/lib/ViroReact.xcframework. They replace ViroKit.framework and libViroReact.a. The podspecs and the Expo plugin need nothing, but a script or Podfile that names ViroKit.framework or libViroReact.a by path needs the new ones.
Decide on the usage ping. Every scene navigator now sends one usage ping when it mounts. See Usage Data for what it carries and how to turn it off.
Quest builds: check the manifest changes listed under Meta Quest below, and test a store build.

Behaviour that changes

Emission now shows on physically based materials

A glTF emissiveFactor, or an emissive colour on a material with lightingModel: "PBR", was dropped before. A model that relied on that may now glow. Check models with an emissive factor or texture.

A `style` on a scene navigator now applies

style on ViroARSceneNavigator, Viro3DSceneNavigator, ViroVRSceneNavigator and ViroSceneNavigator was silently dropped before. It now goes on a View that wraps the native navigator. Check the layout of any navigator you pass a style. On Android, StyleSheet.absoluteFill used to leave a release build on a blank screen; it no longer does.

`cloudAnchorProvider` and `geospatialAnchorProvider` are honoured

On ViroARSceneNavigator these deprecated props are now used when provider is not set. 3.0 always overrode them with "reactvision". An app that still passes cloudAnchorProvider="arcore" now uses ARCore Cloud Anchors, which needs a Google Cloud API key. To keep ReactVision's, remove the prop or pass provider. See Provider Setup.

Text moves to where its vertical alignment puts it

Lines used to be laid out as if each line's box started at its baseline. Text in every alignment moves: in Roboto, centred text (the default) moves down by about a third of the font size, and top- and bottom-aligned text up by about a quarter. If you offset text to make up for the old position, drop the offset.

Clicks go to what is drawn on top

An object between the user and a panel drawn over the scene (a higher renderingOrder with readsFromDepthBuffer: false) took clicks aimed at the panel. Within one renderingOrder the nearest object still takes the click, so a scene that sets no renderingOrder is unaffected. A controller click on nothing reaches ViroController's onClick again, as before 3.0.0.

Editor scenes placed in a VPS location need 3.1.0

A scene bound to an Advanced VPS location in the Editor loads only in ViroReact 3.1.0 or later. ReactVision Spatial refuses it to older versions with 426 SCENE_REQUIRES_VPS_RUNTIME. Scenes that are not placed load as before. To scan and track places in your own app, see Advanced VPS.

Scenes remount once

Scenes rendered by ViroARSceneNavigator remount once after upgrading, because each is now wrapped in the provider that relays tracking updates to the navigator's new onTrackingUpdated.

Android calls that behave differently

startVideoRecording fails with error 1 when RECORD_AUDIO is denied. iOS records without sound.
takeScreenshot keeps only the last path segment of its file name ("dir/shot" saves as shot.jpg).
projectPoint and unprojectPoint on a stale view reject instead of never settling, so give them a catch.
getRecordingStatus() returns "Unsupported" (not "UNSUPPORTED") when the AR view cannot be found.

Types that changed

ViroMaterial types the colour write mask as the bridges read it: colorWriteMask, an array. The old colorWritesMask string was never read. Use colorWriteMask: ["None"] or the channels to write.
Viro360Image takes stereoMode. The old misspelling steroMode stays as a deprecated alias, and is now applied.
ViroAnimations.registerAnimations accepts animation chains (names and nested arrays) without a cast. ViroAnimationChain, ViroAnimationDict and ViroRegisterableAnimation are exported.
react is a peer dependency only (>=19.0.0). It was also listed in dependencies, which could install a second React.

Platform notes

iOS

Builds and runs in the iOS Simulator. ViroKit and the bridge ship as xcframeworks with a simulator slice (arm64 and x86_64). ARKit has no simulator support, so an AR scene still needs a device.
ViroKit targets iOS 15.1, the minimum the podspec already declared. Before, an app targeting iOS 15 could fail to launch on an iOS 15 device.
The privacy manifest ships with the pod (ViroReact_privacy resource bundle).

Meta Quest

The Expo plugin changes Quest builds (when xRMode includes "QUEST"). Run npx expo prebuild again to pick them up:

minSdkVersion is raised to 32 (android.questMinSdkVersion), and installLocation="auto" is set. The plugin only raises minSdkVersion. A value above 32 leaves out headsets on Horizon OS before v76. The Horizon Store's upload check rejects a minSdkVersion outside 29 to 34.
The Horizon OS SDK is declared as <metavr:uses-metavr-sdk> (android.questHorizonOsSdk), and the deprecated <horizonos:uses-horizonos-sdk> element from an earlier prebuild is removed.
NFC is no longer declared (the renderer declares it for Cardboard), unless your app declares it itself.
A network security config (res/xml/viro_network_security_config.xml) is written, unless your app sets its own. Plain http stays allowed in debug builds and blocked in release builds unless your manifest allows it.
The launching activity sets excludeFromRecents and the com.oculus.intent.category.2D category, and VRActivity declares Meta's recommended configChanges.

In Editor scenes, the in-headset menu now opens on the left controller's menu button (or a palm pinch), not Y, and Y goes back as B does. An app that wants the menu button to exit has to handle source 13 in its ViroController. See HorizonOS Setup Guide.

visionOS

Scenes from the Editor now render in the ImmersiveSpace. They used to be blank. No change is needed in your app.

Web

Update @reactvision/viro-web-renderer to 1.1.0. Web AR content now hides while tracking is lost. Set hideContentWhenLost: false in arOptions to keep it visible. See Web Setup Guide.

Upgrading to 3.1.1

3.1.1 is a fix release on virocore 3.1.1, with @reactvision/viro-web-renderer 1.1.1 for web. It has no API changes.

Quest builds: re-run npx expo prebuild. The plugin declares com.oculus.permission.HAND_TRACKING again, which the Horizon Store requires, and drops WRITE_EXTERNAL_STORAGE.
Check metallic models. A metallic model without a lightingEnvironment looks darker than in 3.1.0. Give it a ViroLightingEnvironment.
visionOS: check textured glTF models. They now draw their normal, metallic-roughness, occlusion and emissive maps, so they will look different (and closer to other platforms).