How To Migrate a Unity Project

The following migration steps are included below:

These migration steps generally assume an upgrade from one version prior unless noted otherwise. If you are migrating to a version of Vuforia Engine that is several releases ahead of your existing version, we recommend reading through the intermediate release notes for additional details. Also please refer to our articles documenting the changes in new releases:

9.7 Unity Migration Guide for Legacy Area Targets

Starting with Vuforia Engine 9.7, Area Targets created with previous versions of the Area Target Generators (ATG) will not work out of the box with the occlusion mesh and the mesh collider technology due to a future compatibility change. To work around this issue, you will have a couple of options.

The Vuforia Extension in Unity will notify if you are using a legacy Area Target with below warning. If you already have enabled the Add Occlusion Mesh and the Add Mesh Collider on your legacy Area Target, it should continue to work. However, if you wish to make changes on either, the same steps below apply.

Following options exist to resolve the compatibility issue:

  1. Add the occlusion mesh and mesh collider manually in your current Unity project – see detail explanation in the section below.
  2. If you have the original scan data, a simple option is to re-generate your Area Target from the original scan with the latest ATG and import the Area Target into your Unity project. See How to Create Area Targets.
  3. As a last resort if you are using the Area Target Creator app, you can recapture the area and generate a new dataset from it.  

Manually update mesh collider and occlusion mesh for legacy Area Targets

  1. All legacy Area Target databases include a preview model of the environment. The preview model is available at: Assets/Editor/Vuforia/<DatasetName>
  2. Drag and drop the PreviewModel.prefab from this folder into your scene.
  3. Return the PreviewModel by dragging it from the Hierarchy back into the project folder.
  4. In the pop-up window, save it as Original Prefab.

  1. Rename it OcclusionModel.prefab to not confuse it with the existing PreviewModel. Right-click the highlighted file and select Rename.

Add occlusion by changing the Material of the Mesh Renderers of the OcclusionModel.prefab to a new material

  1. Select the OcclusionModel and in the Inspector press Open Prefab.
  2. In the Hierarchy, write in the search field "primitive" to find all primitive meshes. Select them all.
  3. In the Inspector window, change the Materials' Element 0 to DepthMask.
  4. Return to the scene by pressing the arrow in the upper right corner of the Hierarchy and add the OcclusionModel.prefab as child to your Area Target or continue with the steps to add colliders.

Add colliders by setting up a Mesh Collider to every child of your OcclusionModel.prefab which have a MeshRenderer.

  1. Select the child objects of your OcclusionModel that has a Mesh Renderer. Use the same method as described above.
  2. In the Inspector, press Add Component->Mesh Collider.
  3. Return to the scene and add the OcclusionModel.prefab as child to your Area Target.

Vuforia Engine Unity Extension 9.6 Patch 1 Migration Guide

Starting with Vuforia Engine 9.6, the Unity package manager will retrieve the Vuforia Package repository from a Git repository instead of an NPM scoped registry.

For a complete guide, including an out-of-the-box script to upgrade to the latest Vuforia Engine version, please see Vuforia Engine Package Hosting in Unity.

All Versions previously hosted through an NPM scoped registry so far are also available on Git. To move from NPM to Git while staying at the same Vuforia Engine version. browse to the manifest.json file in your Unity project’s Packages folder. Remove the scopedregistries from the manifest and add the following to the “com.ptc.vuforia.engine” entry

"com.ptc.vuforia.engine": "git+https://git-packages.developer.vuforia.com#9.6.3",

Note the # tag at the end specifies the version of the Vuforia Engine Unity will retrieve. Change this tag to the specific version number you need and save the file to migrate to the Git hosted package.

The Package Manager should now display the Vuforia Engine AR package as a git repository.

Vuforia Engine Unity Extension 9.0 Migration Guide

Changes for Target Game Object Scale

Starting with Vuforia Engine 9.0, all target game objects in Unity need to have a transform scale of (1,1,1). This was already the case in previous versions for some target types (e.g. Model Targets) and has now been harmonized. Please note:

  • You are still required to set the physical size of a target, either in the dataset or via the Unity inspector. This will still affect the size of the preview image or model in the Unity scene during authoring, but it will no longer change the scale of the target game object.
  • Only the root target game object needs to have a transform scale of (1,1,1). Any child objects that add virtual content to be rendered on a target can have an arbitrary scale.

When upgrading a Unity project to Vuforia Engine 9.0, you will need to adjust the scale of most targets, including Image Targets and VuMarks. Model Targets should not be affected.

This section guides you through this process.
The following image shows a target that was set up with Vuforia Engine 8.6, where the physical target size is reflected in the scale of the Image Target game object transform:

After upgrading to Vuforia Engine 9.0, you will notice that while the configured physical size is still the same, the authoring preview of the Image Target is too small and an error is displayed in the inspector:

Clicking the Fix scale button will open a dialog explaining that this will set the scale value of transform to (1,1,1) and change the scale of all child object transforms to preserve their current global scale.
After confirming this dialog, the authoring preview for the image target will again have the correct size.
The scale of the game object will be set to (1,1,1), with all content rescaled accordingly to keep its original size.

Play Mode Changes

Vuforia Engine 9.0 introduces a new Play Mode type called Simulation Mode within the Unity Editor. It can be used without a webcam. Its main purpose is for application development for Area Targets, but it is also useful in cases where targets are too large to be used continuously when testing your application or are simply unavailable. More information can be found here.

Vuforia Engine Unity Extension 8.6 Migration Guide

Starting with Vuforia Engine 8.6, the package for Unity is available through a scoped NPM (Node Package Manager) registry.
This Vuforia registry needs to be added to your Unity project for you to access the Vuforia Engine through the Unity Package Manager.

More information can be found in this article

Vuforia Engine Unity Extension 8.5 Migration Guide

1. Upgrading to Vuforia Engine 8.5

1.1 Using Package Manager in Unity 2019.2 and later

When using Unity 2019.2 or later, Vuforia can simply be upgraded in a project using the Package Manager. Open the Package Manager from Window -> Package Manager, browse to the “Vuforia Engine AR” package and Select “Update to 8.5”:

 

1.2 Using Unity 2018.4 for HoloLens development

An update installer is provided to patch your Unity 2018.4 installation with Vuforia Engine 8.5 for HoloLens development. Other platforms, including Android and iOS, are not supported with Vuforia Engine 8.5 in Unity 2018.4.
You can find the update installer at https://developer.vuforia.com/downloads/sdk

Please follow the Vuforia Update Installers for Unity to patch your Unity 2018.4 installation:

2. Platform Support 

2.2 Automatic inclusion of the ARCore library

It is no longer necessary to include the ARCore Library into the Unity project manually, instead checking the checkbox in the VuforiaConfiguration under the ARCore Requirement dropdown will automatically include it during the Gradle build. To use a custom version of ARCore, uncheck this setting and include the right library in the Unity project.

3. Removed APIs and Features

3.1 VR Support

Slot-in viewer type devices, as well as rotational device tracking, have been removed in Vuforia Engine release  8.5. Vuforia Engine will automatically determine if it is running on a handheld device or on digital eyewear (HoloLens).

In addition: the following runtime APIs have been removed from the Unity Extension:

 

  • EyewearDevice, EyewearCalibrationProfileManager and EyewearUserCalibrator
  • All classes and interfaces related to Viewer parameters
  • RotationalDeviceTracker
  • MixedRealityController
  • Some fields and methods in the DigitalEyewearARController

Migrating a Vuforia Engine Unity project to Unity 2019.2 using Package Manager

Starting with Unity 2019.2, Vuforia Engine is available through Unity’s package manager service. Vuforia no longer needs to be installed with Unity, it can be added per project using the package manager window. The Vuforia Engine package can also be added directly from the player settings.

The first Vuforia Engine version to officially support package manager is 8.3.

The following article describes how to migrate your existing Vuforia project (based on Unity 2018.4 or 2019.1) to Unity 2019.2 with Vuforia as a package.

  1. Make sure your installed Vuforia Engine version is upgraded to the latest 8.3 version.
  2. Make a backup of your project
  3. In your project, delete the “Vuforia” folder from the Assets:

  1. Close Unity
  2. Open the same project in Unity 2019.2 and confirm the upgrade dialogue

Add the Vuforia package to your project by one of the following methods:

  1. Open the Package Manager UI from Window à Package Manager and search for “Vuforia”. Add the Vuforia Engine package by clicking the “Install” button:

  1. Alternatively, you can directly add the Vuforia Engine package by selecting “Vuforia Augmented Reality Supported” from the Player Settings:

  1. Your project should now compile and build again

Vuforia Engine Unity Extension 8.3 Migration Guide

1. Platform Support

1.1 UWP ARM and ARM64 Support

Vuforia Engine 8.3 now supports ARM and ARM64 bit for UWP devices in Unity.

1.2 Configuring ARCore requirements for Android

In previous versions of Vuforia Engine, the requirement to use ARCore was hardcoded in the AndroidManifest.xml file. This has now changed; the setting can be configured in the Device Tracker section of the Vuforia Configuration. If the positional device tracker is enabled in the configuration, the ARCore setting is automatically set to “Optional”, but can be changed after that:

Please refer to the following page to learn more about what the different values mean:
https://developers.google.com/ar/develop/java/enable-arcore

Please note that it is still required to include the ARCore client library in your project as described here:
https://library.vuforia.com/content/vuforia-library/en/articles/Solution/arcore-with-vuforia.html

2. API and Workflow Changes

With Vuforia Engine 8.3, all model target types have been consolidated under a common API and workflow, no longer requiring the ModelRecognition GameObjects for trained targets.
A migration guide below helps you to migrate your existing projects to Vuforia Engine 8.3 in Unity.
 

  1. Select your ARCamera and navigate to Vuforia Configuration to ensure that you have updated to the Vuforia Engine Version 8.3.
  2. Locate the Game Objects of type ModelTargets and ModelRecognition in the Hierarchy. In the Inspector, you will now see that the Model Reco Behaviour is deprecated and a button to migrate the settings related to the Model Target is present. Press the Migrate Settings.

The Migrate function will deactivate the ModelRecognition GameObject and transfer the settings of the DefaultModelRecoEventHandler to the Vuforia Configuration. Additionally, by migrating to the updated Vuforia SDK 8.3, it is now possible to have multiple ModelRecognition GameObjects (now named advanced database) active at the same time.

3. Deprecated and removed APIs and Features

3.1 VR Support

Slot-in viewer type devices, as well as rotational device tracking, are deprecated. These features are removed in Vuforia Engine release 8.5. Vuforia Engine will automatically determine if it is running on a handheld device or on digital eyewear (HoloLens).

In addition: the following runtime APIs have been marked deprecated:

  • EyewearDevice, EyewearCalibrationProfileManager and EyewearUserCalibrator
  • All classes and interfaces related to Viewer parameters
  • RotationalDeviceTracker
  • MixedRealityController
  • Some fields and methods in the DigitalEyewearARController

3.2 Other deprecated APIs

The following methods in the VuforiaRenderer class have been removed in Vuforia 8.5.

  • GetRendererAPI() – use Unity’s SystemInfo.graphicsDeviceType instead.
  • SetVideoBackgroundTexture() and SetVideoBackgroundTexturePtr()
  • createNativeTexture
  • SetVideoBackgroundConfig()
  • GetVideoBackgroundConfig()
  • ClearVideoBackgroundConfig()

Vuforia Unity Extension 8.1 Migration Guide

  1. New Platform Support
    1. Android ARM64 Support
      Vuforia 8.1 now supports ARM64 bit on Android. Simply select IL2CPP as your scripting backend and add ARM64 to the Target Architectures in the Android player settings of your project:

    1. BitCode Support
      The iOS version of Vuforia 8.1 now contains Bitcode. Provided any other dependencies of your project also contain Bitcode, you may build with Bitcode enabled and use this for App Store submission. It is recommended to test Bitcode recompilation by making an Archive build and then exporting an Ad Hoc .ipa, selecting the "Recompile from Bitcode" option.

      Bitcode is automatically enabled by Unity when it creates the Xcode project. To build without Bitcode, edit the project and turn it off.

      Note that due to a limitation in the recompilation process, if you are going to build for Bitcode then you must embed VuforiaDL.framework in your app even if you are not using a feature that requires it. This is the default behaviour.
  2. API and Workflow Changes
    1. Model Target 3D Guide View Extraction
      With Vuforia 8.1, we have changed the mechanism for Model Target extraction in Unity. The extracted 3D models are used for guide views and editor previews of Model Targets. Previously, the 3D mesh was extracted and set up in a Unity scene once “3D guide view” was selected for a model target in that scene.
      This has now changed so that the mesh is extracted at the time a Model Target dataset is imported into a Unity project. At that time, a prefab is created on the project level in the Resources/VuforiaModels folder. This prefab is used by default for both the editor preview of a model target and when 3D guide views are used at runtime. This makes it easier to update all instances of Model Targets when importing a new version of a database into the project.
      The model extraction can be disabled in the Vuforia configuration if the extracted 3D models are not needed for guide views, preview models, augmentations or if you want to reduce the size of your application.
      If model target extraction is disabled, 3D guide views are not available for model targets in your project.
      If your Vuforia 8.0 (or earlier) project used 3D Model Target guide views, please follow these steps to migrate it to Vuforia 8.1:
      • Open the project with new Vuforia SDK 8.1 -> notice that a new folder Resources/VuforiaModels is generated
      • If your project used the extracted models for anything other than 3D guide view functionality (e.g. as augmentation assets), you’ll need to assign the guid of the old prefab to the new prefab:
        • Close the Unity editor
        • Open meta-files of old (Assets/Models/) and new (Resources/VuforiaModels/) prefab and swap the guid values of the two prefabs
        • Open Unity editor again and verify that new prefabs are used in your scene
        • Alternatively, you can manually replace all instances of 3D guide view prefabs with the new prefab by manually adding them to the scene
      • If you no longer need them, delete all previously extracted 3D models from the folder Assets/Models. There is a separate subfolder for each database.
    2. Public changes to Image class
      The Vuforia Image class has been refactored and optimized for better memory usage. This resulted in the following changes for Vuforia 8.1:
      • The enum Image.PIXEL_FORMAT is replaced by PIXEL_FORMAT. If you used that enum in your code, you’ll need to fix any compiler errors by changing to the new enum.
      • The PIXEL_FORMAT.YUV format was replaced with more explicit format YUV formats by introducing PIXEL_FORMAT.NV21 and PIXEL_FORMAT.NV12.
        If you previously used the YUV format you now need to check for the NV21 or NV12 formats.
        Please note that not all formats are supported on every platform. Rule of thumb:
        • NV12: native image format on iOS and UWP tablet devices
        • NV21: native image format on Android
          There are exceptions to this, for example the Google Pixel C device uses other YUV based formats
      • Image.IsValid() has been marked deprecated and can be replaced with the static Image.IsNullOrEmpty(Image) method.
      • Image.Clear() and Image.ClearUnmanagedData() have been removed, they are not required anymore.
  3. Removed APIs and Features
    1. Front Camera Support
      The previously deprecated front camera functionality has been removed with Vuforia 8.1. You can now only access the back camera.

      As part of this change, the reflection flag was removed as well, which was enabling mirrored rendering. If you still need to have mirror rendering due to your current setup, this is best done in a post processing effect in Unity.
    2. Model Recognition Template Mode
      The template mode for trained Model Targets has been removed with Vuforia 8.1. If you used Model Recognition in your Vuforia 8.0 Unity project, please follow these steps:
      • If you did not use template mode, just remove the template object below the Model Recognition game object in your Unity scene
      • If you did use templates in your project, please follow these steps to implement a similar mechanism on application level:
        • Keep the template game object and make sure that no dataset has been assigned to it (editor shows ---EMPTY--- dataset)
        • Create a custom ModelRecoEventHandler by copying the DefaultModelRecoEventHandler script
        • Instantiate the template object in the OnNewSearchResult method
    3. Other removed APIs
      The following methods, interfaces and classes have been deprecated in previous Vuforia versions and have now been removed with Vuforia 8.1:
      • PositionalDeviceTracker.CreateMidAirAnchor(string name, Transform transform):
        Use CreateMidAirAnchor(string name, Vector3 position, Quaternion rotation) instead.
      • DeviceTrackerARController.FusionProvider: Use VuforiaRuntimeUtilities.SetAllowedFusionProviders instead.
      • ICloudRecoEventHandler: Use IObjectRecoEventHandler instead.
      • ObjectTracker.TargetFinder: Use GetTargetFinder instead.
      • AnchorStageBehaviour: use AnchorBehaviour instead.
      • FusionProviderType. OPTIMIZE_IMAGE_TARGETS_AND_VUMARKS and OPTIMIZE_MODEL_TARGETS_AND_SMART_TERRAIN: Use ALL instead.
      • VuforiaRuntime.HasInitialized: use VuforiaRuntime.InitializationState or VuforiaManager.Initialized instead.
    4. Newly deprecated APIs
      The following field has been deprecated in Vuforia 8.1 and will be removed in a future Vuforia version:
      • TargetFinder.CloudRecoSearchResult.TargetSize

Migrating Unity Projects to Vuforia Engine 7.2

Extended Tracking

In Vuforia Engine 7.2, the Extended Tracking API has been deprecated. The functional equivalent continues in the form of the Device Tracker.  Developers can enable Extended Tracking functionality by enabling the Positional Device tracker.

Developers migrating applications which use Image Targets, VuMarks, Multi-Targets, Cylinder Targets or Object Targets and are looking for equivalent Extended Tracking functionality as pre 7.2 should follow these steps:

  1. Open the Vuforia Configuration panel (Windows> Vuforia Configuration or Ctrl+Shift+V)
  2. Check the "Track Device Pose" option under the "Device Tracker" section
  3. Confirm that the Tracking Mode is set to "POSITIONAL"
  4. Select "Optimize for Image Targets and VuMarks" for "Fusion Mode"

The following APIs have been deprecated:

  • Target.StartExtendedTracking()
  • Target.StopExtendedTracking()

Instead of calling these APIs for each target, call TrackerManager.Instance.InitTracker<PositionalDeviceTracker>() once to enable Extended Tracking functionality on all targets. Be sure to start the Device Tracker.

For more information on Extended Tracking, please refer to the Extended Tracking documentation.

Device Tracker

The Device Tracker no longer requires a specific World Center Mode. Device Tracker can work alongside all World Center Modes.

Targets will continue to report pose information when the target is out of view and Device Tracking is enabled. If Device Tracking is not enabled and the target goes out of view, tracking will be lost (NO_POSE).

Device Tracking can be enabled in the Vuforia Configuration Panel as seen in the previous screenshot.

Device Tracking can also be enabled via code:

void Awake() {
     VuforiaARController.Instance.RegisterVuforiaInitializedCallback  (OnVuforiaInitialized); 
 } void OnVuforiaInitialized() {
     deviceTracker = TrackerManager.Instance.InitTracker<PositionalDeviceTracker>(); 
 }

The device tracker can now be started/stopped anytime at runtime without the need to re-initialize the camera with:

deviceTracker.Start();

and

deviceTracker.Stop();

For more information on the Device Tracker, please refer to Using the Device Tracker document

Vuforia Fusion

Also part of Vuforia Engine 7.2, we are updating the Device Tracker to leverage Vuforia Fusion. Vuforia Fusion refers to the internal techniques used by the Vuforia Engine to take advantage of the best platform enablers (such as ARCore and ARKit) while still providing developers with the broadest reach of devices.

Vuforia Fusion works by choosing the best technology for Device Tracking. Please refer to the following list for default priority:

Vuforia Fusion Default Priority:

  1. Platform Enablers (ARKit/ARCore)
  2. Vuforia VISLAM
  3. Vuforia SLAM

Due to addition of support for platform enablers, it is important that AR content, targets, and physical objects all have their coordinate scale in meters. Objects that do not have their scale set appropriately may not track well.

For more information about Vuforia Fusion, please refer to the Vuforia Fusion documentation.

World Center Mode

  • DEVICE - The camera now moves if the device tracker is enabled. If the device tracker is not enabled, the camera will stay fixed at the last position. Targets always moves in this mode.
  • FIRST_TARGET / SPECIFIC_TARGET - The first Target or the specified target will be at the last position and not move

If your experience uses physics or otherwise requires a GameObject to remain static for performance reasons, consider using SPECIFIC_TARGET.

ARCore

To enable ARCore support in Unity, please refer to Using ARCore with Vuforia document.

Front Facing Camera

Front-facing camera support has been deprecated in Vuforia Engine 7.2.

Vuforia Engine Initialization

Vuforia Engine 7.2 has made some changes to the initialization process that may impact the flow of your application. The default initialization behavior of Vuforia Engine 7.2 is to download the latest device profile in order to deliver the best experience on the device.  Depending on the speed of the user's internet, this could add several seconds to application load. This only occurs the very first time the user launches the app and will not impact application loading in future launches of the app.

It is strongly recommended to allow the Vuforia Engine to fetch the latest device profile. Developers looking to disable this behavior should set the following hint before initializing Vuforia Engine: VuforiaUnity.SetHint(VuforiaUnity.VuforiaHint.HINT_ASYNC_FETCH_OF_LATEST_CALIBRATION, 1);

Earlier Versions

 

Can this page be better?
Share your feedback on our community forum