Zenn
📚

パッケージ用のスクリプティングAPIで何ができるのか

2021/12/09に公開
Unity
tech

Unityには、Package Managerを操作するためのAPIがありますが、何ができるのかあまり情報がなかったので整理してみました。この記事は、Unity2021.1にて動作検証を行っています。

日本語の公式ドキュメントはこちら

Client

Clientは、Package Manager APIの主要なクラスで、パッケージの追加、削除、パッケージ化、一覧の取得、検索などができます。

https://docs.unity3d.com/ja/2021.1/ScriptReference/PackageManager.Client.html

主要な関数は全てStaticで実装されているのでインスタンス化する必要はありません。

パッケージの追加

Client.Add関数を使うと、パッケージの追加ができます。以下のコードは公式サイトに掲載されているサンプルコードです。Add関数でパッケージをプロジェクトに追加しています。戻り値として、RequestというAddRequestのインスタンスを取得し、非同期で実行結果を待ち、IsCompletedがtrueになると実行結果を取得できます。サンプルコードではEditorApplication.updateイベントを使っていますが、EditorCoroutineや、UniTaskを使うと、よりシンプルに書けるかもしれません。

static void Add()
{
   // パッケージをプロジェクトに加える
   Request = Client.Add("com.unity.textmeshpro");
   EditorApplication.update += Progress;
}

static void Progress()
{
   if (Request.IsCompleted)
   {
       if (Request.Status == StatusCode.Success)
	   Debug.Log("Installed: " + Request.Result.packageId);
       else if (Request.Status >= StatusCode.Failure)
	   Debug.Log(Request.Error.message);

       EditorApplication.update -= Progress;
   }
}

Client.Add関数の引数は、name@version、git url、ファイルパスなどのパッケージマネージャーの一般的な書式で指定できます。

- To install a specific version of a package, use a package identifier ("name@version"). This is the only way to install a pre-release version.
- To install the latest compatible (released) version of a package, specify only the package name.
- To install a git package, specify a git url.
- To install a local package, specify a value in the format "file:/path/to/package/folder".
- To install a local tarball package, specify a value in the format "file:/path/to/package-file.tgz".

関数呼び出し時の注意点

Client.Add関数は、他のパッケージ追加中に呼ぶとエラーになるので、連続で追加する場合は、前のAddRequestの終了を待ってから呼びましょう。また、AddRequestが完了するたびにコンパイルが実行されて、エディタ拡張プログラムの実行が中断されてしまうので、連続で追加する場合は、EditorApplication.LockReloadAssembliesでアセンブリのリロードをロックする必要があります。(ロックしたら終了後にアンロックも忘れずに！)

AddAndRemove(Unity2021.2)

Unity2021.2からは、Client.AddAndRemoveという関数が使えるようです。未検証ですが、引数に複数のパッケージを指定できるので、AddRequestの終了待ちや、アセンブリのロックが不要になるのかもしれません。

パッケージの埋め込み

Client.Embed関数で、パッケージをプロジェクトに埋め込むことができます。こちらは、あまり使うことはなさそうですが、埋め込みパッケージに変換してパッケージの中身を編集したり、Unityプロジェクトの再配布時に便利かもしれません。

パッケージの削除

Client.Remove関数を使うと、パッケージの削除ができます。こちらもAdd関数と同じく非同期で実行されます。ClientのStatic関数は、全て非同期で実行されます。

パッケージ化

Client.Pack関数を使うと、パッケージをtgz形式(tarball)に圧縮して出力できます。出力したtarballは、パッケージマネージャーウィンドウや、Client.Add関数から追加できます。

一覧の取得

Client.List関数を使うと、インストール済みのパッケージ一覧を取得できます。

検索

Client.Search関数を使うと、Unityパッケージレジストリに登録されたパッケージを検索できます。SearchAllという引数を指定しないタイプの関数もあります。

その他の関数

以上がClientの主要な関数ですが、その他にもResetToEditorDefaults、Resolveなどの関数もあります。

まとめ

Package Manager APIを使うことによって、プロジェクト設定やパッケージ出力を自動化できるので、チーム開発や、パッケージ開発で役立つことが期待されます。便利なAPIなので、積極的に活用しましょう！

Discussion