MRTK3 環境セットアップ手順

MRTK3 の導入手順 (環境構築) について書いていきたいと思います。本記事の内容は、執筆時点 (2022/09/26) での公式ドキュメントの内容に基づいた情報となります。今後のアップデートで記載されている情報が古くなる場合があります。ご注意ください。

# MRTK3 とは？
> <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/9383ef5b-c7a3-079b-715b-c9b58bbf0ff0.png" width="500">  
>
> [Mixed Reality Toolkit 3](https://docs.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/) より画像引用

**第3世代 の Microsoft Mixed Reality Toolkit for Unity ( 略称: MRTK )** です。MRTK は Microsoft が開発を主導しているオープンソースプロジェクトで、Unity で クロスプラットフォーム に対応した MR アプリケーション開発を加速させます。MRTK3 は Unity XR Management System と XR Interaction Toolkit 上に構築されています。

> <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/beee5b99-c6a3-a458-5604-d751f171b251.png" width="500">
>
> [Architecture overview - MRTK3](https://docs.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/architecture/architecture) より画像引用

MRTK3 は 2022/06 に開催された **Mixed Reality Dev Days (#MRDevDays)** にて、Public Preview としてリリースされました。今後の正式リリース (GA) に向けたタイムラインは以下の予定です。2022年秋/冬には GA 予定なので、遅くても 2022年末頃には GA になるのかなーという印象です。

| リリース | タイムライン |
| --- | --- |
| Public Preview | 2022/06/08 |
| Preview updates | 正式リリースまでの期間、約2~4週間ごと |
| General Availability (GA) | 2022 秋/冬頃 |

**GA までのアップデート (Preview updates)** に関しては、``MRTK3 公式ページの Changelogs ページ`` から変更履歴を確認することができます。

> <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/aeda729d-c39d-8bd9-2f80-b609163c4bad.png" width="500">
>
> [Changelog for MRTK3 pre.11](https://learn.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/changelogs/mrtk3-pre-11-changelog)


## サポートデバイス
MRTK3 でサポートされているデバイスは、以下の通りです。

| プラットフォーム | サポートデバイス |
| --- | --- |
| OpenXR XR devices | Microsoft HoloLens 2<br/>Meta Quest (Experimental)<br>Windows Mixed Reality (Experimental)<br/>SteamVR (Experimental)<br/>Oculus Rift on OpenXR (Experimental)<br>Lenovo ThinkReality A3 (with Qualcomm Snapdragon Spaces - Experimental) |
| Windows | デスクトップ (Experimental) |

久しぶりに対応デバイスを見たら、Lenovo ThinkReality A3 が増えてました。公式ドキュメントには、``And more comming soon`` とあったので、近々増えそうですね。

## ソフトウェア要件

| ソフトウェア | バージョン | 備考 |
| --- | --- | --- |
| Visual Studio | 2019 Community Edition 以降 | 推奨バージョン: Visual Studio 2022 |
| Unity | 2020.3.35 以降、もしくは 2021.3.4 以降 | LTS バージョンを使用することが推奨されています。Unity バージョンに含まれる[既知の問題](https://docs.microsoft.com/en-us/windows/mixed-reality/develop/unity/known-issues)を確認してください。 | 
| Mixed Reality Feature Tool for Untiy | | MRTK3 パッケージを取得するために使用 |
| .NET 5.0 Runtime | | Mixed Reality Feature Tool 動作要件 |
| Mixed Reality OpenXR Plugin | | Mixed Reality Feature Tool 経由でインストール |

# 検証環境
- Visual Studio 2022 ``Version 17.1.3``
- Unity Hub ``3.2.0``
- Unity ``2021.3.6f1``
- Mixed Reality Feature Tool ``v1.0.2209.0 Preview``


# セットアップ手順
Unity で MRTK3 を検証する方法は2種類あります。

1. 公式サンプルプロジェクトをクローンする方法
2. Unity 新規プロジェクトに MRTK3 パッケージを追加する方法

## 1.公式サンプルプロジェクトをクローンする方法
MRTK3 を最も簡単に試す方法は、公式リポジトリの事前構成済みのプロジェクトを GitHub からクローンして、Unity で確認する方法です。まず、MRTK for Unity リポジトリをクローンして、``MRTK3`` ブランチをチェックアウトします。その後、Unity 2020.3.33f1 以降で ``MRTKDevTemplate`` プロジェクトを開きます。

既にMRTK3パッケージのインポートや初期設定が終わっているので、
手軽に MRTK3 を試すことができます。

### 1-1. MRTK リポジトリを Clone する
```
git clone https://github.com/microsoft/MixedRealityToolkit-Unity.git
```

### 1-2. ``MRTK3`` ブランチをチェックアウトする
```
git checkout -b mrtk3
```

チェックアウト後、ファイルエクスプローラーで
``MixedRealityToolkit-Unity`` フォルダを確認します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/ef2ae5ef-e31f-4535-d929-39654767db96.png" width="500">

``MixedRealityToolkit-Unity > UnityProjects``

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/818f6e7e-03de-08ee-02b3-354c5c32d783.png" width="500">

``MixedRealityToolkit-Unity > UnityProjects > MRTKDevTemplate``

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/f500857d-a9ff-7fbc-b539-70970bed38d6.png" width="500">

**MRTKDevTemplate** フォルダが MRTK3 事前構成済みの Unity プロジェクトフォルダになっているので、次の手順で Unity Hub にプロジェクトを追加します。

### 1-3. Unity で対象プロジェクトを開く

Unity Hub へプロジェクトを追加する際は、``Open`` を選択して、
追加したいプロジェクトフォルダを指定します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/b9478c25-cfff-e070-05d5-a876ea84ad6e.png" width="500">

Unity 2021.3.6f1 で MRTK3 プロジェクトを開くと、
MRTK3 のサンプルシーンを試すことができます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/ebf3fdef-d60f-3078-d661-a9800993d1d4.png" width="500">

サンプルプロジェクトのフォルダ構成
(/Assets 配下) は以下のようになっています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/af6c09ff-90e8-b73a-a87c-ed19129ed47f.png" width="300">

``Assets > Scenes`` フォルダ配下には、
20種類のサンプルシーンが含まれています。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/b23f1990-c364-702e-1a3f-5ea2c886a7bf.png" width="500">

早速サンプルシーンをデプロイしてみたいと思います。今回は HoloLens 2 のデバイスポータル経由でのリモートデプロイの方法をご紹介したいと思います。( ※ この手順を実行するには、HoloLens 2 を開発者モードにして、Device Protal を有効にする必要があります。また、開発PC と HoloLens 2 を同一ネットワークに接続している必要があります。) それではやっていきましょう！

グローバルメニューから ``File > Build Settings`` を開きます。
(ショートカット: Ctrl + Shift + B)

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/c3773b6b-7bd1-d1ca-9f39-bf49bd0ea2f1.png" width="500">

①　ターゲットプラットフォームが ``Universal Windows Platform`` に設定されていることを確認する。
②　``Add Open Scenes`` ボタンを押して、サンプルシーンを追加します。
③　ビルド設定を行います。
④ ``Build And Run`` を押して、ビルドとデプロイを実行します。

| プロパティ | 設定値 |
| --- | --- |
| Architecture | ARM 64-bit |
| Build Type | D3D Project |
| Target SDK Version | Latest installed |
| Minimum Platform Version | 10.0.18362.0 |
| Visual Studio Version | Visual Studio 2022 |
| Build and Run on | Remote Device (via Device Portal) |
| Build configuration | Release |
| - Device Portal Address | https://\<HoloLens 2 IP アドレス><br>ex. https://192.168.10.11 |
| - Device Portal Username | Device Portal のユーザー名 |
| - Device Portal Password | Device Portal のパスワード |

無事、デプロイができたら、HoloLens 2 で
アプリケーションを起動することができます。

<blockquote class="twitter-tweet"><p lang="ja" dir="ltr">HoloLens 2 実機動作の様子<br>MRTK3 pre.10 で新しく追加された<br>・Whiteboard + canvas<br>・magicWindow<br>(at HandInteractionExample)<a href="https://twitter.com/hashtag/MRTK3?src=hash&amp;ref_src=twsrc%5Etfw">#MRTK3</a> <a href="https://t.co/tIgVQsacPo">https://t.co/tIgVQsacPo</a> <a href="https://t.co/1ejc7gl4SE">pic.twitter.com/1ejc7gl4SE</a></p>&mdash; Futo Horio (@Futo_Horio) <a href="https://twitter.com/Futo_Horio/status/1567858228855468035?ref_src=twsrc%5Etfw">September 8, 2022</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

## 2.Unity 新規プロジェクトに MRTK3 パッケージを追加する方法

ここからは Unity 新規プロジェクトに対して、MRTK3 パッケージを追加する方法についてご紹介していきたいと思います。

### 2-1. 新しい Unity プロジェクトを作成する

公式ドキュメントには、Unity ``2020.3.35f1`` 以降、もしくは Unity ``2021.3.4f1`` 以降を使用することと記載されています。

本記事では、Unity ``2021.3.6f1`` を使用して手順をご紹介致します。
まず、Unity Hub を開き、右上の ``New Project`` ボタンを押します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/bc3748f5-ee95-42c6-63ab-9c5c343578bd.png" width="500">

① プロジェクトで使用する Unity バージョンを選択する
② テンプレートから **3D** を選択する
③ **プロジェクト名** と **ロケーション** を入力する

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/3d952ee3-dd35-c713-b2d7-3c4ceab83b79.png" width="500">

すべての設定を確認した後、**Create project** ボタンを押して、
新しい Unity プロジェクトを作成します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/9d6ec6a2-fe4f-43d6-1c98-6102b75004cd.png" width="300">

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/814e8eb4-5ffc-1aba-827b-8cb81c1c4e7a.png" width="500">

Unity プロジェクトの新規作成が終了すると、Unity Editor が開くので、次の手順を行う前に、Unity Editor を閉じます。


### 2-2. Mixed Reality Feature Tool から MRTK3 パッケージと依存パッケージをインポートする

Mixed Reality Feature Tool を使用して、MRTK3 パッケージをインポートします。(※ もし Mixed Reality Feature Tool をダウンロードしていない場合は、公式サイトの手順に従い、``.exe`` ファイルをダウンロードしてください。)

Mixed Reality Feature Tool が起動したら、**設定** アイコンをクリックします。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/9b0d76d6-f69c-3214-2b87-db3eeb9b6a23.png" width="500">

設定ページに遷移後、Feature タブを開き、Feature Settings の ``Show preview releases`` にチェックが入っていることを確認します。( ※ チェックが入っていない場合は、チェックを入れ、OKボタンを押してください。)

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/617c1115-b6ca-1b21-d9c0-e55fd74e52c5.png" width="500">

Select project ページに遷移後、プロジェクトパスを指定して、**Discover Features** ボタンを押します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/4bc7acef-334b-e638-67fe-d54ea01c513e.png" width="500">

Discover Features ページに遷移後、以下インポート対象のパッケージにチェックを入れ、**Get Features** ボタンを押します。

- Platform Support → **Mixed Reality OpenXR Plugin**
- Spatial Audio → **Microsoft Spatializer** (オプション)
- MRTK3 → **MRTK Input** (この手順を試す際は必須)
- MRTK3 → **MRTK UX Components**

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/19db1143-3af0-d2db-2bd2-0af649cd1cee.png" width="500">

これらの2つのパッケージとその依存関係 (Mixed Reality Feature Tool によって自動的に追加) を使用すると、さまざまな XRデバイス に展開する準備ができているプロジェクトを作成できます。MRTK3 パッケージに関する詳細情報は [Packages overview](https://learn.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/packages/packages-overview) をご覧ください。

選択したパッケージと依存パッケージ一覧を確認して、問題なければ **Import** ボタンを押下します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/8703002f-43da-0998-41c1-b785ce60710f.png" width="500">

Review and Approve ページに遷移後、**Approve** ボタンを押すと、``manifest.json`` が上書きされます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/ed9ae013-0256-372b-aa6d-f3f4e42b990d.png" width="500">

**Exit** ボタンを押して、Mixed Reality Feature Tool を閉じます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/8cde4b8e-f530-a083-a093-4a372ee0d345.png" width="500">

これで MRTK3 パッケージを Unity プロジェクトへインポートする準備が整いました。

### 2-3. Unity プロジェクトを開く

Unity Hub からさきほど新規作成した Unity プロジェクトを選択して、Unity Editor を起動します。Unity Editor 起動時に、以下2つのダイアログを表示されます。

① 新しい入力バックエンドシステムを有効にするかどうか
**A: Yes**

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/3e16dc6e-9d22-1ade-aa06-b6344d290d19.png" width="300">

② XR InteractionLayerMask をアップデートするかどうか
**A: No Thanks**

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/be599d4e-2403-b9c2-904e-0541cb1cd492.png" width="300">

このプロセス中に Unity が数回再起動する場合があります。終了するまで待ってから次のステップを実行してください。

### 2-4. MRTK プロファイルの設定を行う

MRTK3 をインポートしたら、ターゲットプラットフォームごとに、追加のプロファイル設定を行う必要があります。

1. ナビゲーション **Edit > Project Settings** を選択する
2. Project Settings 配下の MRTK3 タブを選択して、スタンドアロンタブを開く
3. MRTK3 コアパッケージに同梱されているデフォルトの MRTK プロファイルをフィールドに入力する

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/1de26132-78b4-fbbb-c275-eeedcf5c6dd8.png" width="500">

今回は UWP (HoloLens 2) ターゲットでも使用したいので、UWP タブを選択して、同様の設定を行います。

### 2-5. OpenXR に関する設定を行う

HoloLens 2 や Quest などの XRデバイスをターゲットにしている場合、MRTK3 をインポートすると、OpenXR でいくつかの設定が必要になります。

1. ナビゲーション **Edit > Project Settings** を選択する
2. Project Settings 配下の XR Plug-in Management を選択して、Standalone と UWP タブの両方で OpenXR を有効にします。それぞれのタブで **Initialize XR on Startup** にチェックを入れ、Standalone タブ,UWP タブ配下の両方で Windows Mixed Reality feature group にチェックを入れます。

**Standalone** タブ

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/30a13faf-2228-cfe1-9df9-19c2d71d08db.png" width="400">

**UWP** タブ

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/54d1a3de-7de7-9742-f8b6-f6eda46e303e.png" width="400">

OpenXR オプションをチェックした後、黄色の警告アイコンが表示される場合があります。(画像:上) そのアイコンをクリックして、OpenXR プロジェクト検証ツールを開きます。[Fix All] をクリックし、自動修正できないインタラクション プロファイルの問題を無視します。プロファイルは、次の手順で追加されます。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/339d389d-cfe8-dd41-5088-22082a5b90e7.png" width="400">

Project Settings 配下、**XR Plug-in Management > OpenXR > Interaction Profiles** を開き、次のプロファイルを Standalone と UWP へ追加します。

- Eye Gaze Interaction Profile
- Microsoft Hand Interaction Profile
- Microsoft Motion Controller Profile

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/f9ca2b48-764f-e340-491b-06b3f07f8ec4.png" width="400">

HoloLens 2 を使用する場合は、上記の Depth Submission Mode を ``Depth 16 bit`` へ設定することが推奨されています。イマーシブヘッドセットを使用する場合は、24 bit を使用することができます。[depth buffer sharing](https://learn.microsoft.com/en-us/windows/mixed-reality/develop/unity/recommended-settings-for-unity#enable-depth-buffer-sharing) については、こちらのサイトをご確認ください。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180432/53186140-a6cb-73fc-92c0-21c7784ac8f6.png" width="400">

以上の手順を実行することで、Unity 新規プロジェクトに MRTK3 を導入することができます。シーンの作成方法やコンポーネントの使い方など、次回以降の記事で紹介していきたいと思います。最後までお読みいただき、ありがとうございました。

# Refs
- [Mixed Reality Toolkit 3](https://docs.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/)
- [Initial Setup for MRTK3](https://docs.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/mrtk3-overview/setup)
- [Windows Device Portal Deployment](https://docs.unity3d.com/Manual/windowsstore-deviceportal.html)