13
10

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@toRisouP

【Unityユーザー向け】 R3入門 ~導入編~

13
Posted at

R3入門シリーズについて

過去にUniRx入門というシリーズを作成しましたが、こちらの賞味期限が過ぎつつあるため新しく書き直そうという目標で始めました。
少しずつ追加していく予定です。

この記事について

この記事ではUnity向けにR3を導入する方法を解説します。
といっても公式のREADMEに方法は書いてあるので、基本はそれを踏襲しつつ、補足が必要な部分を中心に解説します。

UnityにR3を導入するための前提

対象環境

  • Unity 2021.3以上であること
    • 今回はUnity 6.3に導入する想定とします
  • Gitがインストールされていること

R3の構成

modules.jpg

Unity向けのR3は「R3本体となるコアモジュール」と「Unity向けのR3拡張」の2つで構成されています。

  • R3コアモジュール: R3の実装の本体。
  • R3.Unity: R3のUnity向け拡張。MonoBehaviourとの連携やUnityのフレーム単位での処理実行などをサポートする。

この2つはセットで導入する必要があります。片方のみをインストールしてもエラーとなってしまうか、動作したとしても正常に動きません。

なおコアモジュールはNuGetで配布されており、Unity向け拡張はGitHubで公開されています。そのため導入には「NuGetからの導入」と「Unity Package Manager (UPM) からGit経由で導入」の2つを実施する必要があります。

補足: NuGetとは

NuGetとはなにか

NuGetは.NET(C#)向けのパッケージ配布・管理の仕組みです。Unityを用いない純粋なC#開発ではNuGetを用いてライブラリの配布や導入を行うのが一般的です。

Unityは標準機能ではNuGetに対応していません。そのためUnityでNuGetで配布されているライブラリを使いたい場合は「UPMを経由する」か「NuGetForUnityなどのエディタ拡張を用いる」といった方法が必要です。

R3の導入方法

UnityにR3を導入する方法ですが、今回はNuGetForUnityを使いnuget.orgから直接パッケージをインストールする方法を紹介します。

（別の方法としてUnityNugetを使うという方法もありますが、これは最後の補足の部分で解説します）

NuGetForUnityを使った導入手順

今回はR3のREADMEで推奨されているNuGetForUnityを使った方法を解説します。
導入の流れは次のとおりです。

  1. 事前準備: Gitのインストール
  2. NuGetForUnityを導入する
  3. R3コアモジュールをNuGetForUnity経由で導入する
  4. R3.UnityをUPMから導入する
  5. （必要に応じて）R3.Unityをasmdefに追加する

0.事前準備: Gitのインストール

GitHubからUnity Package Managerを用いてパッケージを導入する場合は、PCにGitがインストールされている必要があります。インストールされていない場合は先にこちらをインストールしてください（とくにWindowsの場合は事前にインストールが必要かも）

1. NuGetForUnityを導入する

NuGetをUnityで使えるようにするためにまずNuGetForUnityの導入を行います。

導入はUPMから行うことができます。

Unity Editorの [Window] -> [Package Management] -> [Package Manager] より Unity Package Managerのウィンドウを開きます。

nugetforunity.jpg

Package Managerのウィンドウが開いたら 左上の[+]を押し、Install package from git URL... をクリックします。

from git.jpg

出てきた入力欄に次のURLを入力してInstallを押してください。

https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity

導入に成功していた場合はIn Projectの項目にNuGetForUnityが追加されています。

NugetForUnityPackage.jpg

（必要に応じて） NuGetForUnityの設定変更

NuGetForUnityは導入したNuGetパッケージの保存先を指定することができます。

Project Settings ->NuGetForUnity -> Placementより指定できます。

preference.jpg

項目 保存先 補足
Custom Within Assets /Assets/Packages デフォルトはこちら
In Packages Folder /Packages/nuget-packages こちらを推奨

/Assets以下にパッケージが配置されると管理が煩雑になりやすいので、ここの設定はIn Packages Folderにしておくことをおすすめします。

（必要に応じて） .gitignoreの設定

NuGetで導入したdllをGit管理下におくことは一般的には推奨されません。

Git管理したくない場合は.gitignoreで次のような指定をするとよいでしょう。
（NuGetForUnityの設定でPlacementをIn Packages Folderに指定していた場合の指定方法）

/Packages/nuget-packages/InstalledPackages*

2. R3コアモジュールをNuGetForUnity経由で導入する

NuGetForUnityの導入ができたらNuGetよりR3のコアモジュールを導入します。

Unity Editorの [NuGet] -> [Manage NuGet Packages] より NuGetForUnityのウィンドウを開きます。

managenuget.jpg

nugetwindow.jpg

NuGetForUnityのウィンドウが開いたら上部のタブでOnlineを選択。検索バーにR3と入力してSearchを押します。 すると検索結果にR3が出てくるのでInstallを押します。

search.jpg

※ 必ずパッケージの発行元がCysharpになっていることを確認してからInstallしてください。

これでR3のコアモジュールの導入は完了です。

3. R3.UnityをUPMから導入する

続いてR3のUnity拡張であるR3.Unityを導入します。

手順1の手順と同様に、 Unity Package Managerのウィンドウを開き、**Install package from git URL...**より次のURLを入力して導入してください。

https://github.com/Cysharp/R3.git?path=src/R3.Unity/Assets/R3.Unity

r3unity.jpg

導入に成功した場合はIn Projectの一覧にR3が追加されています。

以上でR3の導入は完了です。UnityプロジェクトでR3を使えるようになりました！

4. （必要に応じて）R3.Unityをasmdefに追加する

手順3でR3の導入は完了しているため、Unityプロジェクト上でR3が動作する状態にはなっています。
そのためasmdefを定義せずに使っている場合は以下の手順は省略して構いません。

ですがasmdefを定義してモジュールを分割している場合は注意が必要です。
R3のコア機能の部分は.NET向けライブラリのdllとして扱われるため、何も設定せずとも呼び出しが可能です（ユニットテスト時は別途設定が必要、後述）。

しかしR3.UnityについてはUnityパッケージとして扱われているため、この機能を明示的に呼び出したい場合はR3.Unityをasmdefに登録する必要があります。

R3asmdef.jpg

R3.Unityが提供する機能抜粋

  • MonoBehaviourのObservable化（this.UpdateAsObservable()など）
  • uGUIのObservable化（button.OnClickAsObservable()など）
  • ObserveOnMainThread
  • SerializableReactiveProperty
  • UnityEventのObservable化
  • UnityTimeProvider/UnityFrameProvider 
using R3; // ← こっちはR3のコアモジュールでasmdef登録不要で呼び出せる
using R3.Triggers; // ← こっちはasmdefにR3.Unityの登録が必要
using UnityEngine;
using UnityEngine.UI;

namespace Example
{
    public class Sample : MonoBehaviour
    {
        [SerializeField] private Button _button;
        
        void Start()
        {
            // このようなコードを書きたいならR3.Unityが必要
            this.UpdateAsObservable()
                .Subscribe(_ =>
                {
                    Debug.Log("Update!");
                });

            _button.OnClickAsObservable()
                .Subscribe(_ =>
                {
                    Debug.Log("Clicked!");
                })
                .AddTo(this);
        }

    }
}

(補足) XRI拡張 / TextMeshPro拡張

XR Interaction Toolkit(XRI)およびTextMeshProのObservable化パッケージも用意されていますが、これらはR3.Unityとはまた別のパッケージとして定義されています。必要に応じてasmdefに追加してください。

textmeshpro.jpg

（TMP_InputFieldのObservable化がしたいならR3.Unity.TextMeshProの導入も必要）

注意点

テストでR3を使いたい場合

Unity Editor上のユニットテストなどでR3を利用したい場合は、テスト用のasmdefにR3のdllを参照に追加する必要があります。

TestAsmdef.jpg

またR3.Unityが必要であればそれも追加で登録してください。

R3のバージョンを更新したい場合

R3のバージョンを更新する場合は「コアモジュール」と「R3.Unity」の両方を同時に更新してバージョンを揃える必要があります。一方のバージョンが異なっていると正常に動作しない可能性があります。

コアモジュールの更新方法

NuGetForUnityのウィンドウを開き、Updatesの欄よりパッケージを更新できます。

R3UpdateNuget.jpg

R3.Unityの更新方法

UnityのPackage Managerより更新できます。

R3UpdateUPM.jpg

Unityプロジェクトを開いたときにエラーが出た場合

git cloneした直後にプロジェクトを開くとコンパイルエラーが出る場合があります。

原因はNuGetのパッケージがダウンロードされておらず、R3が読み込めないためです。

Unity Editorを開き直せば自動的に復元(restore)される場合もありますが、されない場合はNuGetForUnity.Cliを用いてコマンドライン上で復元を実行する必要があります。

また、JenkinsやGitHub ActionsなどのCI環境でUnityプロジェクトをビルドしたい場合は、このNuGetForUnity.Cliによるrestoreをフローに組み込んでおくとよいでしょう。

グローバルに導入して実行する場合

# 導入
dotnet tool install --global NuGetForUnity.Cli

# Unityプロジェクトのディレクトリを指定して復元
nugetforunity restore <PROJECT_PATH>

ローカルに導入して実行する場合

cd  <PROJECT_PATH>
dotnet new tool-manifest
dotnet tool install NuGetForUnity.Cli
# パス指定を省略するとカレントディレクトリ指定になる
dotnet tool run nugetforunity restore

まとめ

  • R3をUnityで使う場合は「コアモジュール」と「R3.Unity」の2つが必要
  • コアモジュールはNuGet、R3.UnityはUPMで導入する必要あり
  • NuGetパッケージの導入としてNuGetForUnityを用いた方法を紹介した

なお、OpenUPM経由でR3のコアモジュールを導入する方法もあります。

補足）OpenUPMとUnityNuGet

OpenUPMとは、UPM向けのOSSパッケージを配布できるレジストリサービスです。OSSコミュニティにより運営されています。

UnityNuGetは、OpenUPMとはまた別のプロジェクトであり、nuget.orgが提供するNuGetパッケージの一部をキュレーションしてUPMで利用できるように配布しているリポジトリです。

そしてこの両者を繋いでいるサービスがOpenUPMが提供するUnityNuGet uplinkです。
UnityNuget uplink機能により「OpenUPMからNuGetパッケージを直接導入できる」ようになっています。

このuplink機能を用いることで、UPM経由でもR3の導入が可能です。導入手順もNuGetForUnityを使うより容易です。

こちらの手法は導入が楽で管理も簡単ではありますが次のような欠点もあります。

  • OpenUPMやUnityNugetへの依存が増えてしまう
    • 可用性・継続性にリスクがある（急な仕様変更で動かなくなる可能性あり）
    • UnityNugetのuplink機能自体が実験的であり仕様が維持されるとは限らない
  • すべてのNuGetパッケージが扱えるとは限らない
    • UnityNugetがキュレーションしたNuGetパッケージしか扱えない
    • （R3の導入のみが目的なら気にしなくていい）
  • 依存関係の調整や衝突の回避が難しい
    • 複数のNuGetパッケージを導入する場合にDLL同士の依存関係の調整が行いにくい
    • （R3の導入のみが目的なら気にしなくていい）

逆にいうと上記の内容にデメリットを感じないのであればOpenUPM経由での導入を検討してもよいでしょう。

13
10
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
13
10

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?