Migration Guide

This will guide you through the changes coming from AR Foundation 2.x to 3.x.

Image Tracking

The image tracking manager ARTrackedImageManager has a referenceLibrary property on it to set the reference image library (the set of images to detect in the environment). Previously, this was an XRReferenceImageLibrary. Now, it is an IReferenceImageLibrary, and XRReferenceImageLibrary implements IReferenceImageLibrary. If you had code that was setting the referenceLibrary property to an XRReferenceImageLibrary, it should continue to work as before. However, if you previoulsy treated the referenceLibrary as an XRReferenceImageLibrary, you will have to attempt to cast it to a XRReferenceImageLibrary.

In the Editor, it will always be an XRReferenceImageLibrary. However, at runtime with image tracking enabled, ARTrackedImageManager.referenceLibrary will return a new type, RuntimeReferenceImageLibrary. This still behaves like an XRReferenceImageLibrary (e.g., you can enumerate its reference images), and it may also have additional functionality (see MutableRuntimeReferenceImageLibrary).

Background shaders

The ARCameraBackground has been updated to support the Universal Render Pipeline (UniversalRP) when that package is present. This involved a breaking change to the XRCameraSubsystem: the property shaderName is now cameraMaterial. It is unlikely most developers would need to access this directly. The shader name was only used by ARFoundation to construct the background material. That functionality has moved to the subsystem.

Point Clouds

The ARPointCloud properties positions, confidenceValues, and identifiers have changed from returning NativeArrays to nullabe NativeSlices. The ARPointCloud manages the memory contained in these NativeArrays, so callers should only be able to see a NativeSlice (i.e., you should not be able to Dispose of the NativeArray).

Additionally, these arrays are not necessarily present. Previously, you could check for existence with NativeArray<T>.IsCreated. NativeSlice does not have an IsCreated property, so these properties have been made nullable.

Face Tracking

The ARFaceManager's supported property has been removed. If face tracking is not supported, the manager's subsystem will be null. This was done for consistency as no other manager has this property. If a manager's subsystem is null after enabling the manager, that generally means the subsystem is not supported.

Reference Point renamed to Anchor

To align with industry standard terminology, we've renamed "Reference Points" to "Anchors":

Old class	New class
ARReferencePointManager	ARAnchorManager
ARReferencePoint	ARAnchor

When you open an existing project that used the old reference point API, Unity will prompt you with the option to automatically update your scripts to the new API.