Mixed Reality Toolkit V2.3.0のリリース情報について

# Mixed Reality Toolkit V2.3.0が提供されました。

順調に新機能をリリースしながら拡張が進むMRTKことMixed Reality Toolkitですが、先日v2.3.0がリリースされました。新機能は試験的なものが多く便利なのですが、特に気になる点としてUnity 2019.3で導入されたXR platformへの対応ではないかと思います。
今回は気になるいくつかの機能について解説したいと思います。

1. [環境/デバイス](#1%E7%92%B0%E5%A2%83%E3%83%87%E3%83%90%E3%82%A4%E3%82%B9)
2. [V2.2.0からのアップグレード](#2v220%E3%81%8B%E3%82%89%E3%81%AE%E3%82%A2%E3%83%83%E3%83%97%E3%82%B0%E3%83%AC%E3%83%BC%E3%83%89%E6%96%B9%E6%B3%95)
3. [新機能](#3%E6%96%B0%E6%A9%9F%E8%83%BD)  
    1. [Support for Unity 2019.3 new XR platform (Experimental)](#31-support-for-unity-20193-new-xr-platform-experimental)
    2. [MS Build for Unityに関するいくつかの改善](#32-ms-build-for-unity%E3%81%AB%E9%96%A2%E3%81%99%E3%82%8B%E3%81%84%E3%81%8F%E3%81%A4%E3%81%8B%E3%81%AE%E6%94%B9%E5%96%84)
        1. Assets/Dependencies folder
        2. .Dependencies.msb4u
    4. [Hand physics extension service](#34-hand-physics-extension-service)
    5. [Non-native keyboard (Experimental)](#35-non-native-keyboard-experimental)
    6. [Hand coach (Experimental)](#36-hand-coach-experimental)
    7. [Follow solver (Experimental)](#37-follow-solver-experimental) 
    8. [Pinch Slider orientation](#38-pinch-slider-orientation)
    9. [UnityAR package contents moved into Foundation](#39-unityar-package-contents-moved-into-foundation)
4. [既知の問題](#4%E6%97%A2%E7%9F%A5%E3%81%AE%E5%95%8F%E9%A1%8C)
    1. [Unity 2019.3 infinite loop when switching build target](#41-unity-20193-infinite-loop-when-switching-build-target)
    2. [NuGet packages are not supported with Unity 2019](#42-nuget-packages-are-not-supported-with-unity-2019)
    3. [CS0579: Duplicate 'AssemblyVersion' attribute](#43-cs0579-duplicate-assemblyversion-attribute)
    4. [NU1101: Unable to find package MSBuildForUnity](#44-nu1101-unable-to-find-package-msbuildforunity)
    5. [MRTK Configurator dialog does not show 'Enable MSBuild for Unity' in Unity 2019.3](#45-mrtk-configurator-dialog-does-not-show-enable-msbuild-for-unity-in-unity-20193)
    6. [Issues with the Unity 2019.3 new XR platform on Windows Mixed Reality](#46-issues-with-the-unity-20193-new-xr-platform-on-windows-mixed-reality)
    7. [Windows Mixed Reality gesture support on Unity 2019.3 when using the new XR platform](#47-windows-mixed-reality-gesture-support-on-unity-20193-when-using-the-new-xr-platform)
    8. [Specifying the Depth Reprojection mode in the Windows Mixed Reality Camera Settings Provider is not supported on Unity 2019.3 and Windows XR plugin](#48-specifying-the-depth-reprojection-mode-in-the-windows-mixed-reality-camera-settings-provider-is-not-supported-on-unity-20193-and-windows-xr-plugin)
    9. [Mixed Reality Capture setting](#49-mixed-reality-capture-setting)
    10. [Long paths](#410-long-paths)
    11. [Runtime profile swapping](#411-runtime-profile-swapping)
    12. [Unity 2018: .NET Backend and AR Foundation](#412-unity-2018-net-backend-and-ar-foundation)

以上をトピック的に整理。

## 1.環境/デバイス
### 1.1.対応デバイス

V2.3.0の対応デバイスは以下の通り。

* Microsoft HoloLens 2
* Microsoft HoloLens (1st gen)
* Windows Mixed Reality Immersive headsets
* OpenVR
* (Experimental) Unity 2019.3 XR platform
* (Experimental) Mobile AR
 * Android
 * iOS

前回同様、Mobile ARは試験的な導入となっています。ただ、V2.3.0ではFoundationの機能に収まっています。
このため、AR Foundationはモジュールとして必須になっています。
今回は新たなプラットフォームとしてUnity 2019.3のXR platformが追加されています。
詳細は新機能の方で説明しますが、MRTK V2のコンセプトにもあるクロスプラットフォーム対応を、
Unityが整備したものです。考え方はほとんど同じで抽象レイヤーを挟んでXRデバイスとその機能を分離して
構成し、実アプリの実装レイヤーはデバイスを意識しない開発を可能にする技術です。
### 1.2.開発環境

開発環境は以下の通り

* Microsoft Visual Studio (2017 or 2019) Community Edition or higher
* Windows 10 SDK 18362 or later (installed by the Visual Studio Installer)
* Unity 2018.4 LTS, 2019(2019.3以降推奨)
* NuGet for Unity 2.0.0 or newer(任意)

開発環境としては以下の3つはセットアップしていたので試した形では問題なく動作。
* Unity 2019.1.10f1
* Unity 2019.3.0f5
* Unity 2018.4.6f1

## 2.V2.2.0からのアップグレード方法

基本的には V2.2.0のモジュールを丸ごと入替える。

### 移行手順

unitypakageとNugetでの対応方法。
スムーズに移行したかったら手順は守ってねということらしい。

#### unitypackage使ったパターン

1. アップグレードしたいプロジェクトをUnityで開いていたら閉じる
2. MixedRealityToolkitに関連するフォルダをエクスプローラ上で削除する  
注：追加したAsset等は、念のためバックアップ取っておく  
<font color=red><B>とても重要！！！MixedRealityToolkit.Generatedは絶対消しちゃダメ</B></font>  
 * MixedRealityToolkit
 * MixedRealityToolkit.Examples
 * MixedRealityToolkit.Extensions
 * MixedRealityToolkit.Providers
 * MixedRealityToolkit.SDK
 * MixedRealityToolkit.Services
 * MixedRealityToolkit.Tools
3. プロジェクトフォルダ内のLibraryフォルダを削除
4. Unityで再度プロジェクトを開く
5. 新しいMRTK V2.2.0のunity packagesを<B>以下の手順</B>でインポートする。  
補足：追加したAsset等は再インポートが必要になる場合がある  
 * Foundation - Import this package first
 * (Optional) Tools
 * (Optional) Extensions
 * (Optional) Examples
6. Unityを閉じてプロジェクトのLibraryフォルダを削除する. （AssetのデータベースやCustomProfileを強制的に読込ませるために実施）
7. Unityを開いて、プロジェクトの内の各シーンを開き以下の修正を行う。  
 * [hierarchy]に[MixedRealityToolkit]と[MixedRealityPlayspace]があれば削除する
 * メニューから[MixedRealityToolkit] > [Add to Scene and Configure]を選択(コンポーネントの再構成)
 * メニューから[MixedRealityToolkit] > [Utilities] > [Update] > [Controller Mapping Profiles]を選択 (一度だけ実行)  
この操作を行うことで、V2.2.0で修正されたカスタムコントローラーマッピングプロファイルが更新されます。なお、カスタム割当てした入力アクションはそのまま残ります。

#### NuGet for Unityでの更新

プロジェクトがNuget for Unityと使った[Mixed Reality Toolkit NuGet packages]をインポートしている場合は以下の手順で反映します。

1. メニューから[NuGet] > [Manage NuGet Packages]を選択
2. [Online]タブを選択し[Reflesh]ボタンを押します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/ad77acef-f12a-04b4-6c08-8b8aaf136e6f.png)

3. [Installed]タブを選択
4. インストールしたパッケージ毎にUpdateボタンをクリック
 * Microsoft.MixedReality.Toolkit.Foundation
 * Microsoft.MixedReality.Toolkit.Tools
 * Microsoft.MixedReality.Toolkit.Extensions
 * Microsoft.MixedReality.Toolkit.Examples
5. Unityプロジェクトを再度開きなおす


## 3.新機能  

まずは全体紹介を中心に。個別に調べたものもあるので別途記事をわけます。

### 3.1. Support for Unity 2019.3 new XR platform (Experimental)

Unity 2019.3で追加された XR Platformに対応しました。XR platformについては以下のブログがわかりやすいかと。

[Unity blog - Unity XR platform updates](https://blogs.unity3d.com/2020/01/24/unity-xr-platform-updates/)

使い方としてはXRデバイスの1つとしてProviderに定義する形になっています。
つまり、Mobile AR、Windows MRと同列でXR Platformの設定します。
実は若干不自然なのですがあくまでExperimemtalなのでそこはこれからでしょう。
XR Platformは図に示すようなアーキテクチャ構造を持っています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/be336f6a-89f1-f51f-ba19-4a13f6ad20b2.png)
[[引用元：https://blogs.unity3d.com/2020/01/24/unity-xr-platform-updates/]](https://blogs.unity3d.com/2020/01/24/unity-xr-platform-updates/)

見るとわかるのですが、Mixed Reaity Toolkitのアーキテクチャや概念とほぼ同じ考え方に基づいています。

* <font color="red">Unity XR SDK部分</font>が各XRデバイスの製造元提供するSDKを参照し、実際のデバイスとの処理を担う
* <font color="Red">XR Subsystems</font>はXRコンテンツ開発に必要な制御機能を持ち上位層に機能を提供する。実際のデバイスへの制御はUnity XR SDK経由で各XRデバイスにアクセスする
* <font color="red">上位層（ピンク色より上層）</font>はXR SubSystemsを参照して汎用的なライブラリ機能やXRコンテンツを作成

XR platrofmと連携している場合のMRTKはこのスタックでいう「XR Interaction Toolkit」の位置づけになる形ですね。
現実的にはXR Subsystemsに関する機能もMRTKの場合持っているので現状は一部が競合する形になっています。
厳密には違うのですがイメージしやすい例としてMRTKのInput Systemのイメージで考えてみます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/152548/de791c55-1369-d5f4-1f26-adcd8ffedc54.png)
[引用元:MRTK-GuidesArchitectureInput SystemTerminology](https://microsoft.github.io/MixedRealityToolkit-Unity/version/releases/2.3.0/Documentation/Architecture/InputSystem/Terminology.html)

Unity XR SDKと呼ばれる部分はMRTKでは Data Provider相当の機能といえる形です。
XR subsystemsはController～Cursor相当の機能になるのだと。実際にはXR subsystemsはController相当だと思うのですが、Raycast等MRTKでのPointerに相当する部分もあるようなので、概念的な位置づけとして分けています。
Input SystemとってもXR PlatformとMRTKのアーキテクチャ構成が似ていることがなんとなく理解できるかと思います。

なお、導入する場合は2019.3系で追加のセットアップが必要になります。
手順については以下に説明があります。

[Getting started with MRTK and XR SDK](https://microsoft.github.io/MixedRealityToolkit-Unity/version/releases/2.3.0/Documentation/GettingStartedWithMRTKAndXRSDK.html)

1. XR SDK上でWindows Mixed Realityをサポートするために、Unityの[Package Manager]から以下のコンポーネントをインストールします。
    * XR Management
    * Windows XR Plugin
    * XR Legacy Input Helpers
1. メニューの[Edit]-[Project Settings]を選択
1. [Project Settings]ウィンドウの[XR Plugin Management]タブを選択
1. [Universal Windows Platform]のタブを選択し、[+]ボタンを押して、[Windows MR Loader]を選択します。
1. [Initialize on Startup]にチェックを入れます
1. (任意) Windows Mixed Reality tab under XR Plugin Management and create a custom settings profile to change the defaults.


### 3.2. MS Build for Unityに関するいくつかの改善

MS Build for Unityに関するいくつかの改善が入りました。MS Build for UnityではMS Build実行時に必要な依存ライブラリを管理する機能があります。例えば、DotNetWinRTなどになります。実はV2.2.0ではこのような依存系ライブラリがMRTKのコンポーネント内に存在したため、同じコンポーネントを要求する別のUnityパッケージと競合してビルドできない問題がありました。
具体的にはAzure Spatial Anchors V2.1.1とMRTK V2.2.0は両コンポーネントともDotNetWinRTを参照する必要があるのですが、Unityプロジェクト上はMRTKのモジュールで参照されており、Azure Spatial Anchorsも同じモジュールを利用するため競合が発生することがありました。
V2.3.0からはMS Build for Unityが処理する依存ライブラリはルートの要素として[Assets/Dependencies]に保存されるようになりました。これで競合関係のいくつかの問題を解消しています。この機能改善により[.Dependencies.msb4u]と[Nuget.config]が自動的に生成されるようになっています。
これらは自動で生成されるため構成管理上は対象外にしても問題ありません。

### 3.4. Hand physics extension service
拡張機能として提供されたサービスで、ハンドドラッキングで検出した手に物理演算に関する機能が追加されます。つまり手に当たり判定をいれる機能です。これによって空間の物体を殴って飛ばすとかそういう面白いことができるはずです。

### 3.5. Non-native keyboard (Experimental)
試験的に追加された機能で、OSの機能に依存しないキーボードになります。形状はHoloLensのキーボードに近いレイアウト構成でOS機能に依存しないため汎用的に利用できます。

### 3.6. Hand coach (Experimental)

過去MRDLで存在していたHand Coachです。非常に便利だと思っていたものがMRTK V2でも試験的に追加されました。
Mixed Reality ToolkitやMR関連のUXデザインは別途検討されておりそのプロジェクトがMixed Reality Design Labsです。このプロジェクトでは新しいUXの形を検討するためのサンプルや機能を試験的に実践しています。
過去のHand Coachを含むプロジェクトは以下にあります。この機能については別記事で紹介します。

[MRDL_Unity_LunarModule](https://github.com/microsoft/MRDL_Unity_LunarModule)

### 3.7. Follow solver (Experimental) 
試験的に追加されたSolverでHololens 2のShellスタイルに近い動きをするsolverになります。

### 3.8. Pinch Slider orientation
Pinch Slider(スライダーコントロール)の見た目の表現が変更できるようになりました。縦か横かの指定が可能になっています。

### 3.9. UnityAR package contents moved into Foundation
V2.2.0で追加されたAR FoundationによるMobile AR機能ですが、必要なコンポーネントがFoundationに移動しました。
統合されただけなので、内容は特に変わっていません。

## 4.既知の問題
すでにわかっている問題は以下の通りです。

### 4.1. Unity 2019.3 infinite loop when switching build target
Unity 2019.3上でPlay modeの終了時やビルドターゲットの変更時に無限ループになる。
多分MSBuild周りの問題で発生しているのでは？というかんじです。
2019.3ではなく2019系で起きている可能性もありそうです。2019.1で試していた時に同じ問題に遭遇したことがあるので。
もし発生したら以下の手順をためてみてください。

1. プロセスを強制的に切る
2. Unityをリスタートし、プロジェクトをロードする
3. play modeに入らずにビルドターゲット変更する

### 4.2. NuGet packages are not supported with Unity 2019

現在Nuget.org上のMRTKはUnity 2018.4としてプリコンパイルされているため、2019で利用できない。将来的には2019用の提供予定。

### 4.3. CS0579: Duplicate 'AssemblyVersion' attribute
MSBuild for Unityを有効にした後、[Player Settings] > [Other Settings] > [API Compatibility Level]を変更すると、大量のエラーが発生することがある。特に「CS0579 errors stating that there is a duplicate AssemblyVersion attribute.」が発生することが多いとのこと。
これは[API Compatibility Level]の設定でMSBuild for Unityが必要な依存ライブラリをセットアップするためと思われます。このプロパティは.NET Standard 2.0と.NET4.Xの2種類が設定可能で、実際切替えるとMS Build for UnityがDependenciesに展開します。

* .NET Standard 2.0の場合、Dependencies\netstandard20がセットアップされる
* .NET 4.xの場合、Dependencies\net46がセットアップされる。

この仕組みの影響で、切替えを行うとnetstandard20とnet46が両方セットアップされることで同名のDLLが複数存在し、参照エラーが発生します。
解決策としては、[API Compatibility Level]を変更後はDependenciesフォルダ内の不要な方を削除します。

### 4.4. NU1101: Unable to find package MSBuildForUnity
NuGet for Unityを使用している場合、プラットフォームをUWPに切り替えた後にMRTK Configure Settingsを適用すると、NU1101エラーが生成される場合があります。これは、MSBuild for Unityの問題で、パッケージソースが正しく追加されていないためです。
このエラーを解決するには次の手順を実施します。
1. メニューから[NuGet for Unity]-[新しいソースを追加]を選択します。
2. Unityの新しいソースをMSBuildで置き換えます  
    source_pathをhttps://pkgs.dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_packaging/UnityDeveloperTools/nuget/v3/index.jsonに変更します。
3. ウィンドウの下部の[Save]をクリックします。
4. [Project]ウィンドウで[Sources]を展開し、.Dependencies.msb4uを選択します。
5. [Inspector]ウィンドウで、[Rebuild]をクリックします

### 4.5. MRTK Configurator dialog does not show 'Enable MSBuild for Unity' in Unity 2019.3

2019.3でUnity用のMSBuildを有効にすると、パッケージを復元する無限ループが発生する問題が存在します。
この影響でダイアログに表示がされないことがあるとのこと。
Microsoft.Windows.DotNetWinRTパッケージをNuGet for Unity経由でインポートしておけば表示されます。

### 4.6. Issues with the Unity 2019.3 new XR platform on Windows Mixed Reality

XR Platform利用時Unity 2019.3でのジェスチャーについては以下の条件で課題があります。
Windows XR Plugin v2.0.4-preview.3とXR Platformを使用している場合、以下の問題があります。

* HoloLens(両方とも)AirTapが動作しない
* HoloLens2 と Immersive HMDのPointerの座標系が誤っており正しい制御ができない

問題はプラグインにあるらしいので、まめにアップデート状況を確認して修正を待つ方向になるそうです。

### 4.7. Windows Mixed Reality gesture support on Unity 2019.3 when using the new XR platform

XR Platformに関する機能追加は現時点ではMRTKとしてはしていない。今後のリリースでの対応を検討している。

### 4.8. Specifying the Depth Reprojection mode in the Windows Mixed Reality Camera Settings Provider is not supported on Unity 2019.3 and Windows XR plugin

Depth Reprojection modeの設定についてはUnity 2019.3とWindows XR Pluginでサポートされていない。この件については今後のリリースで改善予定とのこと。

### 4.9. Mixed Reality Capture setting
この機能はUnity 2019.3.0f6上では機能していないとのこと。従来のXR Platform及び、従来のXR設定両方ともに影響があります。

### 4.10. Long paths
プロジェクトの開始パスが長いと一部のパスが長すぎて処理できなくなります。
（これ自体は別にMRTK関係なく良くある話ですが・・・）
これ自体は利用者が意識して注意する以外に回避策がないと思うので、できるだけ浅いパスで開発しましょう。

### 4.11. Runtime profile swapping
現状、Profileの動的変更には対応していません。Profileは静的な設定となっています。ただ、現状はそこまで困らないと思います。ProfileはマルチデバイスようにProviderを複数デバイスごとに割り当てて定義できるなどかなりの配慮がすでにありますし。
ただ、動的変更をやりたいと思ったときは現状できないことを理解しておきましょう。

### 4.12. Unity 2018: .NET Backend and AR Foundation
Unity 2018で.NET scripting Backendを使ってUWPをビルドしようとするとAR Foundationのインストールに失敗します。
これを回避するには以下の2つのいずれかの対応が必要。

IL2CPPでビルドする
[Build Settings]内の設定で[Unity C# Projects]のチェックを外す
要はVisual Studio上のUnityのコード（CSharp-Assemblyプロジェクト）をビルドしない状況を作ればいいということです。
まぁ、これはUWPではAR Foundationが不要とはいえ、仕組み上はライブラリをリンクするからモバイル用のライブラリをUWPでは
使えないでしょ？と言われたら、さほど違和感はないんですが。。。


## まとめ

ということで、MRTK V2.3.0のリリースノートを読み解いてみました。
試験的な新機能はなかなか面白いものが多い印象です。Hand CoachやHand physics extension service、Non-native keyboardは個人的に興味があるので、別記事で紹介したいと思います。また今後、注目に値しそうなものがXR Platformだと思います。MRTKがXR Platformとうまく融合すると
クロスプラットフォーム開発可能なライブラリとしてさらにいい方向に進むと思うので楽しみです。