Migrate Unity Project from Vuforia 6.2 to 6.5

Introduction

Beginning with Unity 2017.2, Vuforia 6.5 is built into the Unity Editor. Developers no longer need to import a Unity Package to use Vuforia in Unity 2017.2. Developers looking to migrate their 6.2 Vuforia applications to 6.5 or developers looking to use Unity 2017.2 or Later, need to migrate their projects. Due of the extent of changes introduced in 6.5 / Unity 2017.2, the migration requires manual intervention. This document outlines the manual migration process.

Breaking Changes

  • Prefabs have been replaced with Vuforia GameObjects
  • AbstractBehaviour Components have been replaced with non-abstract components

Prerequisites

  • Backup your Unity Project
  • Install Unity 2017.2 and make sure that the “Vuforia Augmented Reality Support” is checked during the installation
  • Do not uninstall the previous version of Unity until migration is completed

 

Migration

  1. Backup your project
  2. Make a copy of your project folder. The original project will be referred to as “6.2 Project” and the copied folder will be referred to as “6.5 project”
    TIP: Rename the copied folder with the 6”.5” suffix so you can easily tell them apart.
Vuforia Image
  1. Copy  (using Explorer or Finder) the “Assets/Vuforia/Prefabs” folder to “Assets” folder (if you already have an “Assets/Prefabs” folder in the 6.5 project, feel free to rename the folder so there is no conflict).
  2. Open the 6.5 project directory (using Explorer or Finder) and delete the following files and folders (the associated "*.meta" files will be removed by Unity next time you open it):
    1. Assets/Vuforia/*.*
    2. Assets/Plugins/Android/Vuforia.jar
    3. Assets/Plugins/Android/VuforiaUnityPlayer.jar
    4. Assets/Plugins/Android/libs/armeabi-v7a/libVuforia.so
    5. Assets/Plugins/Android/libs/armeabi-v7a/libVuforiaUnityPlayer.so
    6. Assets/Plugins/Android/libs/armeabi-v7a/libVuforiaWrapper.so
    7. Assets/Plugins/Android/src/com/Vuforia/*.*
    8. Assets/Plugins/iOS/libVuforia.a
    9. Assets/Plugins/iOS/libVuforiaUnityPlayer.a
    10. Assets/Plugins/iOS/Vuforia.UnityExtensions.iOS.dll
    11. Assets/Plugins/iOS/Vuforia.UnityExtensions.iOS.xml
    12. Assets/Plugins/iOS/VuforiaNativeRendererController.mm
    13. Assets/Plugins/iOS/VuforiaRenderDelegate.h
    14. Assets/Plugins/iOS/VuforiaRenderDelegate.mm
    15. Assets/Plugins/iOS/VuforiaUnityPlayer.h
    16. Assets/Plugins/VuforiaWrapper.bundle/*.*
    17. Assets/Plugins/WSA/x64/Vuforia.dll
    18. Assets/Plugins/WSA/x64/VuforiaWrapper.dll
    19. Assets/Plugins/WSA/x86/Vuforia.dll
    20. Assets/Plugins/WSA/x86/VuforiaWrapper.dll
    21. Assets/Plugins/x64/VuforiaWrapper.dll
    22. Assets/Plugins/x64/VuforiaWrapper.dll.signature
    23. Assets/Plugins/x64/VuforiaWrapper.exp
    24. Assets/Plugins/x64/VuforiaWrapper.lib
    25. Assets/Plugins/x86/VuforiaWrapper.dll
    26. Assets/Plugins/x86/VuforiaWrapper.dll.signature
    27. Assets/Plugins/x86/VuforiaWrapper.exp
    28. Assets/Plugins/x86/VuforiaWrapper.lib
  3. Open the 6.2 project in the 5.x version of Unity
  4. Open the 6.5 project in the 2017.2 version of Unity. You may get a notification about the project not matching the version of Unity. Click continue.
Vuforia Image
  1. You may see some errors in the consoles regarding assets that does not exist. This is expected.
Vuforia Image
  1. Open your AR scene. At this point, you should have both the 6.2 project open in an older version of Unity and the 6.5 project open in Unity 2017.2
Vuforia Image
  1. In the 6.5 project, create new Vuforia GameObjects for your Targets by using the new “GameObject->Vuforia” menu. Name your new target(s) the same name as the previous Prefabs. Use the previous project as a reference.
    1. Note that you will receive the a message when creating your first Vuforia object. Click “Import” to continue
    2. Vuforia will also need to be enabled in the Unity Player Settings. Use the “Edit->Project Settings->Player”
    3. Enable Vuforia by checking the “Vuforia AR” option in the “XR Settings” panel within the “PlayerSettings” window:
Vuforia Image
  1. At this point, you should have GameObjects in your Hierarchy Window with the same name. One is the 6.2 prefab, the second one is the new Vuforia GameObject that you just created.
Vuforia Image
  1. Using the previous project as reference, specify the new Vuforia GameObject Target’s, Type, Database, Advanced Settings, etc
  2. Move the child objects of the legacy Prefabs onto the new Vuforia Target GameObject.
  3. If the legacy prefabs had any custom components, re-add the custom components to the new Vuforia Target GameObject. PROTIP: Use the component menu “Copy Component” on the legacy prefab and “Paste Component Values” on the new Vuforia Target GameObject to quickly move the values.
  4. Delete the legacy prefabs that correspond to the previous Targets.
  5. Create a new ARCamera GameObject by using the new “GameObject->Vuforia” menu. Rename the GameObject to be the same name as in the 5.x project (Usually ARCamera)
  6. If the legacy prefabs had any custom components, re-add the custom components to the new Vuforia Target GameObject.
  7. Delete the legacy ARCamera prefab
  8. Attempt to run/compile the 6.5 project
  9. If you get compilation errors:
    • Compilation errors related to “AbstractBehaviours” Vuforia objects can be fixed by renaming the type to remove the “Abstract” word. For instance, “VirtualButtonAbstractBehaviour” is now “VirtualButtonBehaviour”
  10. Repeat the process for your other scenes.
  11. Delete the “Prefabs” folder from step 3
  12. Select the ARCamera, click on “Open Vuforia Configuration”.
    1. Copy your license key from the legacy project to the 6.5 project
    2. Under “Datasets” confirm that all the datasets you need to use is loaded and active.