search

microsoft / MixedRealityToolkit-Unity

This repository is for the legacy Mixed Reality Toolkit (MRTK) v2. For the latest version of the MRTK please visit https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity
https://aka.ms/mrtkdocs
MIT License
6.01k stars 2.12k forks source link

Issues During Upgrade to vNext #3596

Closed genereddick closed 5 years ago

genereddick commented 5 years ago

I have been keeping track of issues upgrading a project to the new MRTK, and to Unity 2018.3.n version. There are several specific bugs which I will also file separately. Let me know if there is a better place for this kind of documentation or if it is not useful.

I have several projects to upgrade. The first of which is fairly simple. It uses a few interactions, mostly focus and click, and a fair amount of UI elements (buttons, radios, checkboxes, text).

UPGRADE STEPS

  1. Upgrading Unity 2017.n version to Unity 2018.n Issue: In my first attempt, I tried to upgrade the project in place -- making many of the changes below -- to Unity 2018 and the new MRTK. After many inscrutable errors, crashes that took down Unity, etc., I surrendered. Fix: In my second attempt I created a new project using Unity 2018.3.n, imported the new MRTK into it, made sure all the Player Settings were correct and then copied the files from my original project's Asset folder. After that I was able to build (using Holographic Emulation and Simulate in Editor), at least without taking down Unity.

  2. Player Settings Issue: On my initial attempt to update, my project defaulted to .NET 3.5. Fix: I had to reset the Player Settings including Scripting Runtime Version, Scripting backend and API Compatibility Level. I updated these to .NET 4.x Equivalent, IL2CPP, and .NET 4.x respectively. Unity did not request a restart, but it updated script settings when I did.

  3. Updating the MRTK Issue: When I removed the previous MRTK existing objects with references to any of the original scripts (the Camera, Cursor and Input manager, and various UI buttons and other interactibles) all broke. Unity gives no indication as to what the missing scripts were so it can become quite a confusing to sort out if you aren't careful. Fix: I had a backup of the project which I kept open so I could refer to it and compare each object in the old and upgraded projects to figure out which scripts / functionality was missing. You may be able to have the old MRTK and new in the same project, but I did not try this.

  4. Default Gameobjects Issue: On upgrading the MixedRealityToolkit and MixedRealityPlayspace + Camera gameobjects did not automatically import and the Mixed Reality Toolkit menu item (with the configure setting did not show up initially. This was only true when I tried an in-place upgrade. Not an issue when starting with a new project. Fix: After a restart of Unity and/or changing the Player Settings the menu item showed and I was able to add the new default MixedRealityToolkit and MixedRealityPlayspace.

  5. Project with multiple scenes Issue: Having the Mixed Reality Toolkit and the Mixed Reality Playspace in each scene results in a duplicate toolkit error. Having just Mixed Reality Playspace in both scenes resulted in errors related to a missing gaze Transform and the gaze cursor no longer appeared in the scene. Fix: Delete the Mixed Reality Toolkit and the Mixed Reality Playspace from additional scenes. Add script with DontDestroyOnLoad to the Mixed Reality Playspace. The previous MRTK also required work to get it to play nice with multi-scene projects, so may be better to go back to additive loading of new scenes.

  6. Shaders Issue: All materials using the "Mixed Reality Toolkit/Standard" shader lost the reference. Fix: Had to manually go through each material in the project and reassign to the new version.

  7. Fonts Issue: Selawik Fonts were renamed from 3dTextSelawik... to Text3dSelawik... in the new MRTK. Fix: Had to update each reference to those fonts. There were also some odd issues with the Font Textures, where they did not show up initially. After going to the material and re-selecting the appropriate Font texture some of them reappeared (Selawik, bold, semi-light), some didn't (light and semi-bold). Still don't quite know what is going on there.

  8. References Issue: References to HoloToolkit now all broken (as expected). Fix: Find and replace every reference with new locations, new scripts, etc. Some specific changes below. For example:

IFocusable => IMixedRealityFocusHandler IInputClickHandler => IMixedRealityPointerHandler

Made the changes above, got the correct using statements and then implemented the interface and moved my code. Some of the new methods have different names, some have different signatures so had to do each of these individually as well as remove the Not-Implemented Exceptions from unused methods.

  1. 3DTextPrefab Issue: The 3DTextPrefab is missing in the new MRTK and I didn't find any direct replacement. Fix: I just wanted a TextMesh, without using a Canvas, as existed in the previous MRTK. This was easy to recreate from the earlier version, prefab it and then replace the respective objects in my project.

  2. Toggles Issue: InteractiveToggle changed Fix: Updated InteractiveToggle => Interactible InteractiveToggle.OnInputClicked => Interactible.OnPointerClicked InteractiveToggle.HasSelection => Interactible.IsToggled.

  3. InteractiveSet (Radial Toggle groups) Issue: InteractiveSet changed Fix: Updated InteractiveSet => InteractableToggleCollection

  4. Toggle Default State Selected Issue: Can't set the InteractiveToggle state to be selected at start. Fix: Must be something obvious I've overlooked.

  5. Tagalong Issue: Missing from new MRTK Fix: Did not find a replacement but maybe I missed it.

Railboy commented 5 years ago

Thank you for this detailed feedback. This is very useful information.

StephenHodgson commented 5 years ago

One thing to note about the asset references, we did attempt to regenerate them so there were not conflicts between the HTK and the MRTK. (We wanted to give developers the ability to have both in the project at the same time to ease the upgrade path.

Let us know if there's any assets guids that collide.

genereddick commented 5 years ago

@StephenHodgson That makes sense. Will do.

david-c-kline commented 5 years ago

@genereddick,

These issues are very helpful as the team writes the v2 documentation. Porting guidance is something we are actively drafting.

Yoyozilla commented 5 years ago

Closing this issue, but posting this in Stack Overflow.

Yoyozilla commented 5 years ago

https://stackoverflow.com/questions/55928369/upgrading-from-htk-to-mrtk-v2-rc1/55928452#55928452