すぎしーのXRと3DCG

Claude Code での Unity 開発の振り返り (2025年)

2025-12-11T12:00:00+09:00

こんにちは、すぎしーです。クラスター株式会社にジョインして4年目になります！クラスター Advent Calendar 2025 の11日目の記事です！

qiita.com

前日は @Kazuya0123 さんの「僕と地域とクラスター」でした。僕も cluster がオンラインで様々な市区町村がつながるプラットフォームとして認知されるよう、頑張っていきたいです。

note.com

さて、今回は2025年の Claude Code での Unity 開発の振り返りについてです。

世間の例に漏れず、クラスターのエンジニアたちにも AI コーディングを使った開発があっという間に浸透しました。

せっかく導入した年なので、そんな AI コーディングの1つである Claude Code を Unity で何に使ったかについて、3つほどピックアップして振り返ってみようと思います。

クラスターでの AI コーディングの開発事例については Cluster Tech Blog もどうぞ！

何に Claude Code を使った？
雑感

何に Claude Code を使った？

UnityEditor 向けツールの作成

UnityEditor 向けツールの作成がやりやすくなったのは、一番わかりやすい恩恵だったように思います。
特にいままで一番時間を要していた「Unity の API 仕様書を都度調べる時間」が大幅に削減できるという点は非常にありがたいと感じています。

以前までは EditorGUILayout, AssetDatabase, SerializedObject, EditorWindow といったお馴染みなものから [email protected]/manual/index.html">Addressables などライブラリまで、様々な API の仕様書とにらめっこしながら開発していたことが AI にツールの仕様を伝えるだけであっという間に出来上がるようになりました。とんでもない時代が来ましたね。

以下のようなツールも作ったのですが、コード行のほとんどが Claude Code による生成です。

InputAction の編集

Unity の InputSystem で用いる InputAction ですが、項目が多いと UI でポチポチするのが大変ですし、何よりミスが起きやすいです。特に VR のトラッカーは 11点 * 3要素(位置、回転、状態) の合計33点を指定する必要があるので、指定ミスしないように注意が必要でした。

そこで InputAction の中身を確認したところ JSON 形式でユニークなGUIDを各入力に紐づけるフォーマットだったので、 Claude Code に必要な項目を指定して規則性に従って編集してもらうことにしました。

少し調整はありましたが、あっという間に作ってくれました。

{
        ...
        {
            "name": "Tracker",
            "id": "b6b46f2b-fb24-4481-9840-28738adcb0d6",
            "actions": [
                {
                    "name": "LeftFootPosition",
                    "type": "Value",
                    "id": "969c5f83-4d27-4f58-8deb-2b6dd6365b8e",
                    "expectedControlType": "Vector3",
                    "processors": "",
                    "interactions": "",
                    "initialStateCheck": true
                },
                {
                    "name": "LeftFootRotation",
                    "type": "Value",
                    "id": "65634ff7-fa1b-4a27-bb29-f74dc757d170",
                    "expectedControlType": "Quaternion",
                    "processors": "",
                    "interactions": "",
                    "initialStateCheck": true
                },
                {
                    "name": "LeftFootState",
                    "type": "Value",
                    "id": "c9d667fd-f506-4a68-bee8-39225817751e",
                    "expectedControlType": "Integer",
                    "processors": "",
                    "interactions": "",
                    "initialStateCheck": true
                },

余談ですが、AI に GUID の生成を任せると「GUID っぽい文字列」を作ってしまいます。例: a1b2c3d4-e5f6-g7h8-a1b2-c3d4e5f6g7h8

ちゃんとした GUID を使わせたい場合は、GUID を生成するコマンドを渡しておくと良いです。例: ./generate-guid.go → b6b46f2b-fb24-4481-9840-28738adcb0d6

GUID に限らず、AI がシンプルに使えるツールを用意することも大事ですね。

エラー通知から修正案を出させる

Claude Code に Sentry MCP Server の使用を許可して Issue のリンクを渡し、必要に応じて修正案を出させています。
補足: Sentry とは、エラー監視プラットフォームのことです。

まだすべてを任せているわけではなく、以下のような AI エージェントでも比較的解決しやすい部類の Issue をお願いする形を取っています。

HTTP レスポンスのハンドリング漏れ
例外 (IOException) などのハンドリング漏れ

修正内容の精度がまだ安定していない部分があるのでエラー通知毎にプルリクエストを提出させる形にはしていませんが、いずれはそうしていきたいなと考えています。

その他

以下のような活用をしています。

client 視点での server 側の実装調査 (重要度の低いものに限定、重要度が高い場合は server エンジニアに直接確認します)
設計、実装の壁打ち
ライブラリの詳細調査
リリース後に不要となった Feature Flag 分岐コードの廃止、及び関連して不要になったコードの削除
GitHub Actions で使用しているバージョンの一括更新
Node.js の Node バージョンの更新

雑感

というわけで Claude Code を Unity 開発でどのように活用したかについて書いてみましたがいかがだったでしょうか？

今年は AI コーディングを単に導入しただけでなく、AI がスムーズに開発できる環境づくりにも力をいれていた年だったかなと思います。

AI の進化の早さにも食らいついていって、どんどん開発を回していきたいですね。

さて、明日は @FUKUDA_concrete さんの「はじめてのUnityワールド作成のススメ」です。お楽しみに！

Visual Studio CodeでVRMを改変する

2024-12-17T19:52:22+09:00

こちらはクラスター Advent Calendar 2024 の17日目の記事です！

qiita.com

こんにちは、すぎしーです。クラスター株式会社にジョインして2年になります。

本記事のテーマは「Visual Studio CodeでVRMを改変する」になります！今回はUnityは使用しません！

改変例として「VRMのテクスチャをVSCodeで差し替える」と「VRM1.0のExpressionのOverride設定をVSCodeで変更する」も紹介しているので、よかったら参考にしてみてください。

使用するツール
前準備
- 1. VSCodeをインストール
- 2. VSCodeにglTF Toolsをインストール
補足情報: VRMはglTF拡張である
glTF ToolsでVRMをインポート
Appendix: 編集が許可されているVRMであることを確認する
VRMを編集する
glTF ToolsでVRMをエクスポート
補足: エクスポートで出力されるVRMバージョンはインポート時に従う
改変例
おまけ: VSCodeでモデルをプレビューする
雑感

使用するツール

Visual Studio Code
- 以下「VSCode」と呼称
glTF Tools (Visual Studio Codeの拡張)

前準備

1. VSCodeをインストール

Visual Studio Code からVSCodeをインストールしてください。

2. VSCodeにglTF Toolsをインストール

以下を参考にglTF ToolsをVSCodeにインストールしてください。

VSCodeのExtensionsを開く
"glTF Tools"と検索する
検索で出たglTF Toolsをクリック
Install ボタンをクリック

以上で前準備は完了です！

補足情報: VRMはglTF拡張である

VRMはglTFをいうファイルフォーマットを拡張したものになっています。そのためglTF向けのツールで改変が可能な場合が多いです。

もし深堀りしたい方は以下のクラスター Advent Calendar 2023の記事を御覧ください！

tsgcpp.hateblo.jp

この性質を利用してglTF ToolsでVRMを編集しようと思います。

glTF ToolsでVRMをインポート

まずはglTF ToolsでVRMを改変する時に毎回実施することになるインポート方法を紹介します！

編集対象のVRMを作業用のフォルダにコピーする

glTF Toolsはインポート時にVRM内のテクスチャや頂点などのバイナリデータを一気にファイル化するため、作業用フォルダを用意してそのフォルダの中にVRMファイルを置きましょう。

VSCodeで対象のVRMがある作業用フォルダを開く

VSCodeのOpen Folder...で作業用フォルダを開いてください。

対象のVRMをインポートする

以下の流れでインポートできます。

ファイル一覧を開く
編集対象のVRM上で右クリックする
"glTF: Import from GLB" をクリックする
インポートされたファイルを保存先(拡張子 "gltf"、以後「gltfファイル」と呼称)を指定する

保存先はVRMファイルとは別のフォルダでも大丈夫ですが、今回は同じ作業用フォルダに保存して説明します。

インポートが終わるとJSON形式のgltfファイルと関連するテクスチャなどのファイル群が生成されているはずです。

一緒に出力されたファイルたちはエクスポート時に必要になるので消さずに残しておいてください！

これでインポートは完了です。

Appendix: 編集が許可されているVRMであることを確認する

自身が所有者ではないVRMの場合は、glTF内の項目を確認して「このモデルを改変することを許可するか否か」を確認しておきましょう。

(VRM確認ツールでもいいですが、本記事ではトコトンVSCodeで確認します！)

VRM0.xの場合は extensions.VRM.meta.licenseName (参考: 公式仕様書 0.0/README.ja.md)
VRM1.0の場合は extensions.VRMC_vrm.meta.modification: (参考: 公式仕様書 VRMC_vrm-1.0/meta.ja.md#metamodification)

VRM1.0の場合であれば allowModification、もしくはallowModificationRedistributionであれば改変が許可されています。

ちなみに VRoid Studioで作成したアバターの場合は、エクスポート時に「改変」の項目で設定した内容が反映されているはずです。

VRMを編集する

インポートが終わったらVRMの仕様書 (vrm-specification) に従いつつ、テクスチャを変えたりgltfファイルを変更してVRMを編集することになります。

改変したgltfファイルは必ず保存(Ctrl+S)してください！

具体的な作業は「改変例」を後述しているので参考にしてみてください。

次項でひとまず改変が完了した後に実施するVRMへのエクスポート方法を紹介します。

glTF ToolsでVRMをエクスポート

以下の流れで編集したgltfファイルからVRMをエクスポートします。

エクスポート対象のgltfファイル上で右クリックする (開いているタブ上で右クリックでも可)
"glTF: Export to GLB (Binary file)" をクリックする
出力するファイルの拡張子を".vrm"にして保存先を指定する (例: "vroid_sample_ex.vrm")

エクスポート時の拡張子はデフォルトで ".glb" になっているので、
拡張子を必ず ".vrm" に変更して保存してください！

エクスポートが完了するとVRMファイルが出力されているはずです。

ここまでが VRMをインポート → VRMを改変 → VRMをエクスポートの流れになります。VSCodeでVRMを編集する場合は毎回やることになります。

補足: エクスポートで出力されるVRMバージョンはインポート時に従う

今回のやり方でエクスポートした場合、出力されるVRMバージョンはインポート時と同じになります。

というよりglTF Toolsは純粋なglTF向けツールでありVRM0.xからVRM1.0に変換するみたいな機能は特に入っていないため、gltfファイルのJSON内容はそのままで出力されるので結果としてインポート時と同じVRMバージョンが出力されます。

改変例

今回はVRoid Studioから作成した以下のVRM1.0アバターの子を使います。

改変例1: VRMのテクスチャをVSCodeで差し替える

glTF Toolsはテクスチャの入れ替えができます。やり方は簡単でインポート直後に出力されているpng画像のうち、テクスチャに使われるpng画像を差し替えるだけです。

今回は先程のアバターのシャツのテクスチャを変えて色を変えてみようと思います。

VSCodeで確認するとシャツのテクスチャの名前は vroid_sample_img13.png になっているようです。

そのテクスチャを色を変更した以下のpngに差し替えます。差し替えた後もファイル名は必ず一致させてください。

あとはgltfファイルからエクスポートするだけです。

clusterで確認してみるとアバターのシャツが差し替わっているはずです。

テクスチャを変えたいぐらいであればVSCodeだけでできちゃうのでぜひ試してみてください。

改変例2: VRM1.0のExpressionのOverride設定をVSCodeで変更する

お次はVRM1.0のExpression(表情)のOverride設定をVSCodeで変更してみようと思います。

ちなみに今回の作業内容は以下の「エモート中に口が動くようにする」をUnityを使わずVSCodeで実現するやり方になっています。

creator.cluster.mu

今回用意したVRoidStudioから出力されたアバターですが、↑の記事と同様にOverride設定がないのでエモート「笑顔」のときにまばたきが発生すると表情が崩れてしまいます。

今回はエモート「笑顔」のときにまばたきをブロックして、表情が崩れるのを回避するように設定したいと思います。

gltfファイルのJSONのから "expressions" 項目を確認する

まずは表情設定項目である "expressions" をgltf内で確認しましょう。"expressions"はVRM1.0におけるExpressionの設定項目になっています。

VSCodeでgltfファイルを開いて検索(Ctrl+F)で "expressions": と検索すると飛べます。

ここを改変することでExpressionの設定変更が可能になります。

対象のExpressionのoverrideBlink、overrideLookAt、overrideMouthを変更する

VRM1.0の仕様書のVRMC_vrm-1.0/expressions.ja.md の「プロシージャルのオーバーライド」を参照すると以下の記載があります。

つまり対象のExpressionの表情でOverride設定を指定する場合は、overrideBlink, overrideLookAt, overrideMouth それぞれに none, block, blend のいずれかを指定すれば良いことになります。

試しに改変前のgltfファイルのexpressions項目のエモート「笑顔」に該当するhappyを見てみると以下のようになっています。

      "expressions": {
        "preset": {
          "happy": {
            "morphTargetBinds": [
              {
                "node": 126,
                "index": 3,
                "weight": 1
              }
            ],
            "isBinary": false,
            "overrideBlink": "none",
            "overrideLookAt": "none",
            "overrideMouth": "none"
          },

overrideBlink, overrideLookAt, overrideMouth それぞれに none つまり「指定無し」になっているため、エモート「笑顔」中にまばたきがブロックされていなかったことがわかります。

今回はまばたきやリップシンクなどの表情切替をすべてブロックしたいので、overrideBlink, overrideLookAt, overrideMouth に block を指定します。

      "expressions": {
        "preset": {
          "happy": {
            "morphTargetBinds": [
              {
                "node": 126,
                "index": 3,
                "weight": 1
              }
            ],
            "isBinary": false,
            "overrideBlink": "block",
            "overrideLookAt": "block",
            "overrideMouth": "block"
          },

こうすることでエモート「笑顔」中は "overrideBlink": "block",によりまばたきが、"overrideMouth": "block"によりリップシンクがブロックされるので結果的に表情が崩れることを避けられます。

VRMに再エクスポートして確認する

このgltfファイルからエクスポートしてclusterで確認してみると、エモート「笑顔」中はまばたきが発生せずマイクに声を入れても口が変形しなくなっていることが確認できます。

他Expression (angry, sad, aa, ih, ou, etc..) も同様にoverrideBlink, overrideLookAt, overrideMouth を編集することでOverride設定の変更が可能です。

VSCodeとUnityのどっちがやりやすいかは人それぞれかと思いますがよかったらご活用ください！

おまけ: VSCodeでモデルをプレビューする

glTF Toolsにはモデルをプレビューする機能がついているので紹介します。

ボタンはgltfファイルを開いた状態のときにタブの右側に出現しています。

VRMのポーズを変えたりはできませんが、簡易的なモデルの確認に使えます。

雑感

去年に引き続きVRMを取り上げてみましたがいかがでしたでしょうか？

今年からクラスターでもVRM1.0アバターが使用できるようになりましたし、みなさんのVRMライフの一助になれば幸いです。

明日のクラスター Advent Calendar 2024の18日目は @MSA-iさんの記事になります。お楽しみに！

記事をご覧いただきありがとうございました！それでは～

【VRM, glTF】3Dアバターファイルフォーマット "VRM" の構造をのぞいてみよう

2023-12-06T00:00:00+09:00

こちらはクラスター Advent Calendar 2023 の1ページ目の6日目の記事です！

qiita.com

前日は @neguse_kさんの「Blenderでポーズを作ってUnityに取り込む」でした！Blenderでポーズを作成されている方はこちらの記事を参考にぜひclusterにも組み込んでみてください！

こんにちは、すぎしーです。クラスター株式会社のUnityエンジニアになってちょうど1年が経ちました。エンジニアとしてできることも増え、やりがいのある日々を送っています！

さて、本記事のテーマは「"VRM" の構造をのぞいてみよう」です。ガチな解説ではなくおおまかにVRMの中身をイメージできるぐらいで紹介したいと思います。

使用するツール

Visual Studio Code
Hex Editor
- Visual Studio Codeのエクステンションで、いわゆるバイナリエディタです。
VMagicMirror
- VRMの確認用として使用します。
- 開発者の獏星(ばくすたー)さんもアドベントカレンダーで記事を投稿されています！ → 「VRM Animation (.vrma)をUnity上で簡単に生成できるようにした話」

今回はUnityとUniVRMは使用しません！

使用するVRM

AliciaSolid_vrm-0.51.vrm
- VRMコンソーシアムから提供されているサンプルVRM
- アリシア・ソリッドちゃんのVRMになっています

VRMについて

VRMとは、VRMコンソーシアムが提唱している人型アバターを定義するファイルフォーマットとなっていて、clusterでもアバターの形式として使用されています。 VRMに対応した様々なアプリケーションでアバターを表示することができます。

例: VMagicMirrorでアリシア・ソリッドちゃんのVRMを読み込んで表示

VRM アバターを作ったり使ったりするだけならいろいろなツールが提供されているので構造を知る必要はないんですが、知っておくとさらにVRMと仲良くなれるかも？

VRMはglTF-2.0がベースになっている

VRMコンソーシアムから公開されているVRM仕様を見ると以下のように記載されています。

glTF-2.0のバイナリ形式glbをベースにした、VR向けモデルフォーマットです。

つまり結論を言ってしまうと "VRMの構造" ≒ "glTF-2.0の構造" と言えます！ということでまずはglTF-2.0の構造について簡単に紹介します。

glTF-2.0 はバイナリとJSONの2つで構成されている

glTFは3Dコンテンツ向けのファイルフォーマットでKhronos Groupから提供されています。仕様書は glTF™ 2.0 Specificationにあります。glTFファイルには主に以下の情報が1ファイル内に格納できるように設計されています。

オブジェクトのヒエラルキー
メッシュ (法線やウェイトなども含む)
テクスチャ
マテリアル
etc...

glTFはバイナリファイルですが、中身は「ヘッダ領域」を除いて「JSON領域」と「バイナリ領域」のチャンクで構成されています。

AliciaSolid_vrm-0.51.vrmをHex Editorで見ると、JSON文字列が格納されていることが確認できます。

そして、ある境界からテキスト部分ではなくバイナリ形式で格納された領域を確認することができます。

ここでJSON領域とバイナリ領域を少し深堀りします。

JSON領域

JSON領域には以下のような情報が格納されています。

項目名	説明
buffer	シンプルなバイナリ領域のアドレス情報。ほとんどのVRMは1つだけ持っている。
bufferView	bufferをさらに区分けしたもの。
image	あるbufferViewをどの画像形式でロードするかの情報を持つ。画像形式はmimeTypeで表現される。
accessor	どのbufferViewをどうやって読み込むかの情報を持つ。
mesh	メッシュを構成するための情報を持つ。プリミティブ(マテリアルを割り当てる単位)毎に頂点位置(POSITION)、法線(NORMAL)、UV座標(TEXCOORD_0)などをaccessorを介して取得する。
etc...	-

例として、以下はAliciaSolid_vrm-0.51.vrmのノード情報(nodes)のJSONの一部を整形表示したものになります。

ノードは位置や回転のほかにメッシュの有無の情報を持ちます。

Unityを知っている方向けに説明すれば、ノードはGameObjectのようなものでボーンとしても活用されたり、meshがあればMeshRenderer、さらにskinがあればSkinnedMeshRendererを持つようなイメージとなります。

"nodes": [
  {
    "name": "mesh",
    "children": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ],
    "translation": [ 0, 0, 0 ],
    "rotation": [ 0, 0, 0, 1 ],
    "scale": [ 1, 1, 1 ],
    "extras": {}
  },
  {
    "name": "body_top",
    "translation": [0, 0, 0],
    "rotation": [0, 0, 0, 1],
    "scale": [1, 1, 1],
    "mesh": 0,
    "skin": 0,
    "extras": {}
  },
  // ...
  {
    "name": "Head",
    "children": [ 77, 78, 79, 80, 81, 89, 97, 99, 101, 103, 104, 108, 109, 113, 114 ],
    "translation": [ -9.235208e-9, 0.0388788, -0.00014353916 ],
    "rotation": [ 0, 0, 0, 1 ],
    "scale": [ 1, 1, 1 ],
    "extras": {}
  },

※↑のJSONは成形したもので、VRM内のJSON領域ではスペースや改行は基本的に除外されています

バイナリ領域

バイナリ領域(Binary Buffer)は何を表しているかというと、メッシュ頂点やテクスチャ、モーフがバイナリデータとして格納されています。

実はバイナリ領域単体では何のデータかはわかりません。バイナリ領域の読み込み方ですが、JSON項目のbuffer、bufferView + 各情報から確定 させる流れになります。

JSON項目からバイナリ領域を読み込む流れ

buffer

bufferはバイナリ領域の一番大きな単位です。以下のように、バイトの長さのみでとてもシンプルです。

前述したとおり、ほとんどのVRMは1つだけ持っています。

  "buffers": [
    {
      "byteLength": 7772784
    }
  ],

bufferView

bufferViewはbufferを区切ったもので、大雑把なイメージは以下です。

以下のJSONを例にするとbufferViewの0番目は「0番目のbufferのオフセット0から344698バイト」、bufferViewの1番目は「0番目のbufferのオフセット344698から136063バイト」、...のように表現されます。

  "bufferViews": [
    {
      "buffer": 0,
      "byteOffset": 0,
      "byteLength": 344698
    },
    {
      "buffer": 0,
      "byteOffset": 344698,
      "byteLength": 136063
    },
    {
      "buffer": 0,
      "byteOffset": 480761,
      "byteLength": 1708146
    },
    // ...

あくまでbufferを区切っただけなので、bufferView単体でも何のデータとして読めばいいかはわかりません。後述するimageやaccessorなどから活用方法を確定させることになります。

image

テクスチャに使用される画像ファイルはimage項目から参照できます。
例えば"Alicia_body"というテクスチャ画像は「bufferViewの0番目をpng形式でロードする」となります。

"bufferView": 0, "mimeType": "image\/png"の場合は、「bufferViewの0番目をpng画像として読み込む」という解釈になります。

  "images": [
    {
      "name": "Alicia_body",
      "bufferView": 0,
      "mimeType": "image\/png"
    },
    {
      "name": "Sphere",
      "bufferView": 1,
      "mimeType": "image\/png"
    },
    // ...

accessor

accessorは以下のように情報を扱います。

typeで整数(int) or 浮動小数点(float)を決定
componentTypeでScalar(1個毎) or Vector3(3個毎) or Matrix4x4(16個毎) or etcを決定
- 定義はAccessor Data Typesから確認できます。5126はfloatになります。

accessorのみでは明確な用途は不明なため、さらに別の項目から使用されます。

  "accessors": [
    {
      "bufferView": 7,
      "byteOffset": 0,
      "type": "VEC3",
      "componentType": 5126,
      "count": 4804,
      "max": [
        0.614650965,
        1.31239367,
        0.150282308
      ],
      "min": [
        -0.614748538,
        0.9991788,
        -0.0840013
      ],
      "normalized": false
    },
    {
      "bufferView": 8,
      "byteOffset": 0,
      "type": "VEC3",
      "componentType": 5126,
      "count": 4804,
      "normalized": false
    },
    // ...

mesh

primitivesのattributesとして頂点位置(POSITION)や法線(NORMAL)を持っており、それらの数値がaccessorのインデックス値を表しています。
"POSITION": 0 の場合は、「accessorsの0番目を頂点位置として使用する」という解釈になります。頂点位置なのでそのaccessorのtypeはVector3(VEC3)になっているはずです。

  "meshes": [
    {
      "name": "body_top.baked",
      "primitives": [
        {
          "mode": 4,
          "indices": 5,
          "attributes": {
            "POSITION": 0,
            "NORMAL": 1,
            "TEXCOORD_0": 2,
            "JOINTS_0": 4,
            "WEIGHTS_0": 3
          },
          "material": 0
        },
    // ...

VRMはglTF拡張にVRM特有の情報を持つ

glTFは前述のとおりJSON領域を持っていますが、このJSONに追加情報を格納しても良いことになっています。この追加情報のことをglTF拡張(glTF Extensions)と呼びます。

VRMはこのglTF拡張部分にVRM特有の情報を持たせることで実現されていて、VRM0.xの場合はextensions.VRM項目に格納されています。

以下はAliciaSolid_vrm-0.51.vrmから抽出した情報ですが、一部紹介します。

拡張項目名	説明
humanoid	VRMのヒューマノイド(人型)のボーン情報
secondaryAnimation	VRMのSpringBoneの情報
etc...	-

"extensions": {
  "VRM": {
    "exporterVersion": "UniVRM-0.51.0",
    "specVersion": "0.0",
    "meta": {
      "title": "Alicia Solid",
      "version": "1.10",
      "author": "© DWANGO Co., Ltd.",
      // ...
    },
    "humanoid": { // ...
    },
    "firstPerson": { // ...
    },
    "blendShapeMaster": { // ...
    },
    "secondaryAnimation": { // ...
    },
    "materialProperties": [
    ]
  }
  // ...

ということでVRMの構造を簡単に説明してみました。もう少しglTFに詳しくなりたいな～という方は gltf20-reference-guide.pdf が図もあったりして参考になるかと思います！

VRMはglTFの仕組みをうまく利用したファイルフォーマットだったんですね～。

おまけ

バイナリエディタでVRMを編集してみよう

さて、glTFの大まかな構造が分かったところで Hex Editor でAliciaSolid_vrm-0.51.vrmを編集してみましょう！

今回は編集結果がはっきりとわかるようにマテリアルの色の乗算値を赤色に変更してみます。

VRM0.xのMToonの色の乗算値は extensions.VRM.materialProperties[*].vectorProperties._Color です。Hex Editorで文字列"_Color"を検索すると見つけられます。

乗算値は白([1,1,1,1])になっていようなので、置換処理で "_Color":[1,1,1,1], → "_Color":[1,0,0,1],に変更保存して、VMagicMirrorで確認してみましょう。

AliciaSolid_vrm-0.51.vrmからAliciaSolid_vrm-0.51_edited.vrmをコピーして作成
Hex Editorを開く
Ctrl+F → 置換モードに切替 → 置換を実施
Ctrl+Sで保存する
VMagicMirrorでAliciaSolid_vrm-0.51_edited.vrmをロード

以下が読み込んだ結果です。しっかり赤色になっていますね。

実際にバイナリエディタでVRMを編集することはほとんどないと思いますが、「VRMの構造を知ってるとこんなこともできるよ～」という紹介でした。

VRM0.x と VRM1.0 について

まだclusterではVRM1.0に対応はしていませんが、せっかくなのでVRM1.0についても少し触れようと思います。

VRM1.0はVRM0.xよりさらにglTFに準拠したフォーマットになっています。具体的に言うと以下のような変更が入りました。

UniVRM以外の一般的なglTFライブラリでもロードしやすいようにbufferViewの扱いが変更された
glTF拡張での名前は extensions.VRMC_vrm、extensions.VRMC_springBone、VRMC_materials_mtoonなどに変更された
マテリアルのパラメータはglTF標準のmaterials項目を使用するようになった
- 色の乗算値を例にすると extensions.VRM.materialProperties[*].vectorProperties._Color → materials[*].pbrMetallicRoughness.baseColorFactor のようにglTF標準のパラメータが使用されるようになった
- Unity特有のシェーダープロパティ名は使用しなくなった

変更点の詳細については VRM-1.0の変更点で確認できます。

VRM1.0はvrm-specificationにて仕様がより明確に記載され、MToonについても項目が定義されたりとUnity製アプリ以外でもVRMを利用できるように見直されています。

ハロクラで発表されているようにclusterもVRM1.0対応を進めていますため、リリースされたらぜひVRM1.0アバターでclusterを楽しんでください！

参考

雑感

VRMの構造について僕なりに紹介してみましたがいかがでしたでしょうか？
clusterのエンジニアになってプロダクト開発でもVRMに触れることも増えたので、せっかくなので知見の共有も兼ねて記事にしてみました。

VRMはVRM Meetupも開催されたりと盛り上がりを見せているので、今後も注目していきたいです！

記事をご覧いただきありがとうございました！

明日のAdvent Calendar 2023 7日目は @uzzuさんの「UnityのPlay Asset DeliveryをtargetSdk34に対応させる」です。clusterのAndroid スペシャリストの記事をどうぞお楽しみに！(Play Asset Deliveryについてはuzzuさんにとても助けられました)

それでは～

UnityでMoqを使う (Unity2021バージョン)

2022-12-17T14:08:49+09:00

こちらはクラスター Advent Calendar 2022（2ページ目）の17日目の記事です！

前日はスワンマンさん (@Swanman) の「Unityのエディタ拡張で動的にメニューを追加・削除する」でした！

まさかエンジニアではなくカスタマーサポートの方からReflectionを使ったツールの作り方を教えてもらえるとは！
Unity上でツールを作るときに知っておくと便利なテクニックになると思いますのでぜひ参考にしてください。

こんにちは、すぎしーです。クラスター株式会社のUnityエンジニアをなりました！

クラスター株式会社のエンジニアになりました！
これからもバーチャルにのめり込む所存🚀https://t.co/zkkbM0HEtE
— すぎしー (@tsgcpp) 2022年12月1日

改めてよろしくお願いします。

概要
- 変更履歴
Moqとは
UnityでMoqを導入
UnityでMoqを使用
Moqの使用例
モックライブラリを使用するメリット
簡易導入方法
余談
- Moq 4.18.2以上にする理由
雑感
クラスター Advent Calendar 2022 明日の記事の紹介

概要

今回の内容は2年前に書いた「UnityでのMoq導入方法」のUnity2021版です。
この2年でUnityもMoqもアップデートされているので、導入も前回より内容を強化した方法で紹介します！

記事の最後の方に、導入までをある程度自動化した方法も載せておきます。

ソフトウェアエンジニア向け の記事になります。

変更履歴

2022/12/18 .NET Framework向けの依存dllを追加及び "Moq 4.18.2以上にする理由"の説明を一部修正

Moqとは

Moqとは C#(.Net) 向けのモックオブジェクト作成ライブラリです。

モッククラスはUnitTestなどで依存interfaceと同じふるまい(モック)になるクラスですが、自作で実装するのはなかなか骨が折れる作業になります。
そんなときにモックライブラリを用いることで簡単にモックオブジェクトを用意でき、より高度なUnitTest (クラスの単体テスト) が可能になります。

UnityでMoqを導入

※Unity2020でも可能と思いますが、Unity2021以上推奨です！

最初に手作業でのやり方紹介します。

1. MoqとCastle.Coreのnupkgをダウンロード

NuGetからnupkgをダウンロードします。

"Api Compatibility Level" が ".Net Standard 2.1"
- Moq 4.18.2以上
- Castle.Core 5.1.0以上
- System.Diagnostics.EventLog 4.7.0以上
"Api Compatibility Level" が ".Net Framework"
- Moq 4.18.2以上
- Castle.Core 5.1.0以上
- System.Threading.Tasks.Extensions 4.5.4以上
- System.Runtime.CompilerServices.Unsafe 6.0.0以上

Moq 4.18.2以上にする理由は後述します。

ダウンロードはページ横の "Download package" から可能です。

2. nupkgを展開

nupkgの実態はzipなので7-zipなどで直接展開できます。
拡張子を .zip に変えてOS標準のzip展開でも可能です。

3. dll を Unityプロジェクト内に配置

展開したファイルのうち、以下のファイルをUnity以下に配置しましょう。
個人的なオススメのフォルダは Plugins/Moq です。

"Api Compatibility Level" が ".Net Standard 2.1"の場合
- moq.4.18.3/lib/netstandard2.1/Moq.dll
- castle.core.5.1.0/lib/netstandard2.1/Castle.Core.dll
- system.diagnostics.eventlog.7.0.0/lib/netstandard2.0/System.Diagnostics.EventLog.dll
"Api Compatibility Level" が ".Net Framework"の場合
- moq.4.18.3/lib/net462/Moq.dll
- castle.core.5.1.0/lib/net462/Castle.Core.dll
- system.threading.tasks.extensions.4.5.4/lib/net461/System.Threading.Tasks.Extensions.dll
- system.runtime.compilerservices.unsafe.6.0.0/lib/netstandard2.0/System.Runtime.CompilerServices.Unsafe.dll

以下のように配置してください。

4. Unity上でdllをTestRunner向けに調整

Moqはあくまでテスト用なので、ビルドしたアプリには含まれないように設定しましょう。

※ビルドしたアプリに混ぜる場合は再頒布となるため各dllのライセンス表記が必要となります。

以下は Moq.dll, Castle.Core.dll, System.Diagnostics.EventLog.dll全てで実施してください。

Inspectorを表示
Auto Reference を無効化
Validate References を有効化
"Define Constraints" に UNITY_INCLUDE_TESTS を指定
"Apply" ボタンをクリック

特に UNITY_INCLUDE_TESTS を指定することでEditMode及びPlayMode Test Runnerで使用できる状態で、
ビルドしたアプリ本体にはMoqと依存dllが除外されます。

以上で導入は完了です！

UnityでMoqを使用

次は導入したMoqを使ってみましょう！

※Unity Test Framework の詳細は省略します

テスト用Assembly Definitionを作成

テスト用スクリプトを配置したいフォルダで右クリック
Create -> Testing -> Tests Assembly Folder をクリック
Assembly名を指定してasmdefを作成

テスト用Assembly DefinitionにMoqの参照を追加

テスト用asmdefのInspectorを開く
"Assembly References"に Moq.dll を追加
- Castle.Core.dll と System.Diagnostics.EventLog の指定は基本的に不要 (テスト用スクリプトで直接参照することは稀なため)

テストを書いて実行

あとは普段どおりテストスクリプトを作成して、Test Runnerで実行するだけです！
Moqを使った簡易的なテストコードの例を載せておきます。

using System.Collections.Generic;
using NUnit.Framework;
using Moq;

public class TestFuncProxy
{
    public interface IFunc
    {
        bool Invoke(int number);
    }

    [Test]
    public void Invoke_ReturnsFalse_IfFuncReturnsFalse()
    {
        // Arrange
        var mock = new Mock<IFunc>();
        var target = new FuncProxy(mock.Object);

        // Note: Moqの仕様でSetupなしの場合はdefaultを返す (bool Invoke(...) の場合はfalse)
        // FYI: 実際のテストではテストパターンを明確にするために明示しましょう！

        // Act
        bool actual = target.Invoke(3);

        // Assert
        Assert.That(actual, Is.False);
    }

    [Test]
    public void Invoke_ReturnsTrue_IfFuncReturnsTrue()
    {
        // Arrange
        var mock = new Mock<IFunc>();
        var target = new FuncProxy(mock.Object);

        // Note: 引数3を渡されたらtrueを返す
        mock.Setup(m => m.Invoke(3)).Returns(true);

        // Act
        bool actual = target.Invoke(3);

        // Assert
        Assert.That(actual, Is.True);
    }
}

以下は実行結果です。

使用方法の紹介は以上です！

Moqの使用例

Moqでできることをちょっと紹介します！

SetupSequenceでコールごとの挙動を指定

SetupSequence で指定するとコールごとの戻り値を指定できます。

    [Test]
    public void Example_SetupSequence()
    {
        var mock = new Mock<IFunc>();

        // 渡された引数に関係なくfalse -> true -> false -> throw Exception
        mock.SetupSequence(m => m.Invoke(It.IsAny<int>()))
            .Returns(false)
            .Returns(true)
            .Returns(false)
            .Throws(new System.Exception("Unexpected Call"));

        Assert.That(mock.Object.Invoke(default), Is.False);
        Assert.That(mock.Object.Invoke(default), Is.True);
        Assert.That(mock.Object.Invoke(default), Is.False);
        Assert.Throws<System.Exception>(() => mock.Object.Invoke(default));
    }

コール時の引数と回数の検査

Verify を使用するとコールされたときの引数やその引数でのコール回数を検査することができます。
Moqを使う場合は一番使う機能ではないかと！

    [Test]
    public void Example_Verify()
    {
        var mock = new Mock<IFunc>();

        mock.Object.Invoke(2);
        mock.Object.Invoke(5);
        mock.Object.Invoke(2);

        // 引数2で2回コールされたことの検証
        mock.Verify(m => m.Invoke(2), Times.Exactly(2));

        // 引数関係なく3回以上コールされたことの検査
        mock.Verify(m => m.Invoke(It.IsAny<int>()), Times.AtLeast(3));
    }

不正の場合は例外(MockException)が出て、テストが失敗します。

コール時の処理を設定

Callback を使用するとコールされたときの処理を設定できます。
複数オブジェクトのコールされた順番を検査するときなどに利用できます。

    [Test]
    public void Example_Callback()
    {
        var messageList = new List<string>();

        var mock1 = new Mock<IFunc>();
        var mock2 = new Mock<IFunc>();
        var mock3 = new Mock<IFunc>();

        // コールされたら messageList に文字列を追加
        mock1.Setup(m => m.Invoke(It.IsAny<int>())).Callback(() => messageList.Add("From 1"));
        mock2.Setup(m => m.Invoke(It.IsAny<int>())).Callback(() => messageList.Add("From 2"));
        mock3.Setup(m => m.Invoke(It.IsAny<int>())).Callback(() => messageList.Add("From 3"));

        mock3.Object.Invoke(0);
        mock1.Object.Invoke(0);
        mock2.Object.Invoke(0);
        mock1.Object.Invoke(0);

        // 合計のコール回数 及び コールされた順番を検査
        Assert.That(messageList.Count, Is.EqualTo(4));
        Assert.That(messageList[0], Is.EqualTo("From 3"));
        Assert.That(messageList[1], Is.EqualTo("From 1"));
        Assert.That(messageList[2], Is.EqualTo("From 2"));
        Assert.That(messageList[3], Is.EqualTo("From 1"));
    }

モックライブラリを使用するメリット

改めてモックライブラリを使うメリットを紹介します。

モックオブジェクトを簡単に生成可能

これまで説明した通りですが、モッククラスを独自に実装する必要がなくなります。

interface を使ったモッククラスを自作する場合は結構な行数を書くことになり、何より保守コストが発生して大変です。
テストの品質を考える場合はモッククラスのテストも必要になってきます。

ちなみにちょっと実装してみましたが、実際に自作する場合はもっと機能が必要になっていきます。

using System.Linq;
...
    public class MyMockFunc : IFunc
    {
        // コールされた戻り値の設定 (直近のコールのみ)
        public bool RetNumber { get; set; }

        // コールされたときの引数の格納用リスト
        public List<int> CallHistory = new();

        // 対象の引数でコールされた回数の検査
        public bool Verify(int targetNumber, int expected)
            => CallHistory.Where(number => number == targetNumber).Count() == expected;

        // メソッドをコールされたときの処理
        public bool Invoke(int number)
        {
            CallHistory.Add(number);
            return RetNumber;
        }
    }

特別な事情がない限り、早めにモックライブラリを導入しておくとUnitTestが億劫にならなくて良いかと思います。

IDEのリファレンス検索に余計な候補がでない

モックライブラリ使う場合はモッククラスを実装するわけではないので、IDEのinterface継承クラスの検索結果にモッククラスが並びません。

以下はモッククラスが定義されたプロジェクトでinterface継承クラスの検索結果イメージです。

(interfaceがGeneric型だった場合はさらに大変なことに)

高度な検証がより簡単に実現可能

「Moqの使用例」で紹介した通り、モックライブラリを使用すると複雑な検証もやりやすくなります。

特定の引数で依存クラスのメソッドをN回コールすること
依存クラスが OperationCanceledException を返すときにはエラーにならないこと
etc...

モックライブラリの導入はUnitTest自体の敷居を下げることができるので、是非活用してみてください。

簡易導入方法

以下にある程度自動化した方法を紹介しています。

github.com

オススメは実施環境に依存しない「GitHub Acrtionsを使用する場合」です！ (Actionsのyaml設定ファイルも作成済みです)

生成されたフォルダをそのまま Assets 以下に配置すれば使用できる状態になっています。

余談

Moq 4.18.2以上にする理由

理由は".Net Standard 2.1"の依存するライブラリが削減されており、導入がより簡単になるためです。

実は4.18.1以前では System.Threading.Tasks.Extensions とその依存 System.Runtime.CompilerServices.Unsafe も一緒に入れる必要がありましたが、 4.18.2で依存が削除されました。

Removed dependency on System.Threading.Tasks.Extensions for netstandard2.1 and net6.0 (@tibel, #1274)

moq4/CHANGELOG.md at main · moq/moq4 · GitHub

追記

".NET Framework 4.x"では System.Threading.Tasks.Extensions の依存は残っているため引き続き必要となるようです。
簡易導入方法で紹介しているツールも修正済みです。

雑感

実装したクラスすべてにUnitTestが必要になるわけでは有りませんが、
恒久的に機能を保証したい場合などは強力な武器になるので、Unity開発でもMoqを活用してみてください。

クラスター株式会社にジョインして業務にも慣れてきましたが、
エンジニアに限らず様々な分野のスペシャリストやジェネラリストの方がいて、刺激的な日々を送っています。

これからもバーチャルにのめり込んでいきます！

クラスター Advent Calendar 2022 明日の記事の紹介

明日は Soraさん (@BlueRose_Sora) の「Tips：clusterで大規模な展示会をする」です！

お楽しみに！

【GitHub Actions】Composite ActionのTipsと注意点

2022-09-25T13:51:15+09:00

概要
動作環境
用語
使用するプロジェクト
Composite Actions の実装
Composite Actionの細かな仕様
Actionの補足
Composite Actionの注意点
Reusing Workflows との違い
余談、筆者が遭遇した事象
サンプルプロジェクト
雑感

概要

今回はGitHub Actionsの機能の一つである "Composite Action" について紹介します。

今回の記事は、GitHub Actionsに多少知見がある人向けの記事になります。

Composite Actionはいわゆる再利用性のあるステップをyamlファイルに集約して再利用可能にする機能です。
テンプレート的な機能、もしくはプログラミングにおける関数的なものと考えてもらっても良いと思います。

docs.github.com

Composite Actionは便利ですが、注意点もあるため紹介しようと思います。

ついでにPrivate Action (Privateなリポジトリに作成したAction) の使用方法も合わせて紹介します。

記事の最後にサンプルリポジトリも記載しておきます。

動作環境

GitHub Actions + ubuntu-latest
- デバッグモード有効化 Enabling debug logging を参照

用語

Public Action
- PublicなリポジトリにあるAction (例、 actions/checkout, actions/upload-artifactなど)
Private Action
- PrivateなリポジトリにあるAction
- 非公開のリポジトリにあるアクセスが制限されたAction

使用するプロジェクト

本題では有りませんが、ビルドのサンプル用に以下を入れています。

C# プロジェクトのビルド用サンプルプロジェクト
- Lottery という実行するたびにtrue or falseを返すだけのプログラム
- LotteryTests はUnitTest

Composite Actions の実装

Composite Actions を組み込むワークフロー

まずは Composite Actionなしのworkflowを例にしたいと思います。

# .github/workflows/build-dotnet-without-composite-actions.yml
name: "Build Dotnet without Composite Actions"

on:
  workflow_dispatch: {}

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          lfs: true

      - uses: actions/cache@v3
        with:
          path: ./Lottery/obj
          key: dotnet-${{ runner.os }}-${{ github.ref_name }}

      - uses: actions/setup-dotnet@v2
        with:
          dotnet-version: '6.0.x'
          include-prerelease: false

      - name: Restore Packages
        shell: bash
        run: dotnet restore ./GitHubActionsTestbed.sln

      - name: Build Projects
        shell: bash
        run: dotnet build ./GitHubActionsTestbed.sln --configuration Release

      - name: Test Projects
        shell: bash
        run: dotnet test ./GitHubActionsTestbed.sln --blame

      - uses: actions/upload-artifact@v3
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0
          retention-days: 3

ワークフローの詳細

リポジトリのcheckout (actions/checkout)
.Net 6.0のビルド環境の構築 (actions/setup-dotnet)
dotnet コマンドを使ったビルド (パッケージの取得、テストを含む)
Artifactとしてアップロード

実行結果は以下です。

https://github.com/tsgcpp/GitHubActionsTestbed/actions/runs/3117273807

Composite Actions 対応

Composite Actionのファイル構成

以下のようなファイル構成を取ります。

<path to action>/<composite action name>/action.yml

<composite action name> はフォルダで、ステップは action.yml に定義します。
フォルダ名はステップの流れがわかる名前にすると良いです。

例えば、「.Netのビルドの一連の流れを集約」するComposite Actionを作りたい場合は以下のようにします。

.github/composite/dotnet-build/action.yml

自分はリポジトリ専用のComposite Actionは .github/composite に置くようにしていますが、別に.github/composite 以下でなくとも問題ありません。

そして呼び出すときは以下のように uses にフォルダを指定します

- uses: ./.github/composite/dotnet-build

後述しますが、with により入力(inputs)を与えることも可能です。

      - uses: ./.github/composite/upload-artifact
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0

Composite Actionの組込方針

Composite Action は個人的には以下の活用方法があると考えています。

複数のステップを1つに集約
入力のデフォルト値を独自に定義

.Netのビルドの一連の流れを集約 (複数のステップを1つに集約)

.NetのビルドをComposite Action対応します。
フォルダ構成は固定として入力(inputs)はありません。

# .github/composite/dotnet-build/action.yml
name: 'Dotnet Build'
description: 'Restore packages, Build and Test'
runs:
  using: "composite"
  steps:
    - uses: actions/setup-dotnet@v2
      with:
        dotnet-version: '6.0.x'
        include-prerelease: false

    - name: Restore Packages
      shell: bash
      run: dotnet restore ./GitHubActionsTestbed.sln

    - name: Build Projects
      shell: bash
      run: dotnet build ./GitHubActionsTestbed.sln --configuration Release

    - name: Test Projects
      shell: bash
      run: dotnet test ./GitHubActionsTestbed.sln --blame

upload-artifactの有効日数3日をデフォルト化 (入力のデフォルト値を独自に定義)

公式の actions/upload-artifact@v3 ですが、デフォルトが90日となかなか長いです。

Composite Actionsは独自の入力 (inputs) を定義することが可能です。

ArtifactはPrivateなリポジトリの場合、使いすぎると従量課金の対象となるためデフォルトで3日ぐらいにしたい場合などは、
Composite Actionの inputs を使用することで独自のデフォルト値を定義できます。

# .github/composite/upload-artifact/action.yml
name: 'Upload Artifact'
description: 'An action to create a artifact'
inputs:
  name:
    required: true
    default: 'Artifact'
  path:
    required: true
  retention-days:
    required: false
    default: 3
runs:
  using: "composite"
  steps:
    - uses: actions/upload-artifact@v3
      with:
        name: ${{ inputs.name }}
        path: ${{ inputs.path }}
        retention-days: ${{ inputs.retention-days }}

name (Artifact名)のデフォルトを"Artifact"
retention-days (有効期限)をデフォルトを3 (3日)
path (対象のファイル群)はデフォルトなしで指定を必須化

required 一応指定しておきましょう。(ただ、個人的にはComposite Actionだと微妙にrequired機能していない印象です)

Composite Action を使用

改めて「Composite Actions を使用していないワークフロー」を改修したいと思います。

# .github/workflows/build-dotnet.yml
name: "Build Dotnet"

on:
  workflow_dispatch: {}

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          lfs: true

      - uses: actions/cache@v3
        with:
          path: ./Lottery/obj
          key: dotnet-${{ runner.os }}-${{ github.ref_name }}

      - uses: ./.github/composite/dotnet-build

      - uses: ./.github/composite/upload-artifact
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0

上記のようにビルドの流れがスッキリした見た目になりました。
また、upload-artifact は有効期限を指定していなくてもデフォルトの3日が設定されるようになっています。

実行結果は以下です。

https://github.com/tsgcpp/GitHubActionsTestbed/actions/runs/3117435297

Composite Actionの細かな仕様

以下に記載されています。

github.com

デフォルトのshellは指定できないなど、細かい仕様が書いてあります。

Actionの補足

通常のActionとComposite Actionは構成自体は同じ

実はComposite Actionのファイル構成 (<path to action>/<composite action name>/action.yml) ですが、
特殊に見えて、実は通常のActionと同じ構成になっています。

例えば、公式の actions/checkout のルートのファイルを見ると action.ymlが存在しています。

github.com

つまりGitHub Actionsで使用されるActionは、必ずaction.ymlを持ったファイル群となっています。

Actionはcheckoutしてからフォルダを指定しても実行可能

実はActionは特定のフォルダにcheckoutして、usesに指定しても使用可能です。

例えば actions/upload-artifactは一旦 ./.github/repos/actions/upload-artifactというフォルダにcheckoutして、
usesでそのフォルダを指定する形をとっても、同様の機能を得ることができます。

      - uses: actions/upload-artifact@v3
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0
          retention-days: 3

↓

      - uses: actions/checkout@v3
        with:
          repository: 'actions/upload-artifact'
          ref: v3.1.0
          path: ./.github/repos/actions/upload-artifact

      - uses: ./.github/repos/actions/upload-artifact
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0
          retention-days: 3

PrivateリポジトリのActionもcheckoutしてフォルダを指定すれば実行可能

前項と同じ原理でPrivateリポジトリもcheckoutして実行が可能です。

社内専用のActionを作って使用したい場合などにご活用ください。

      - name: Checkout tsgcpp/upload-artifact-private
        uses: actions/checkout@v3
        with:
          # actions/upload-artifact をコピーしてPrivate化したリポジトリ
          repository: 'tsgcpp/upload-artifact-private'
          ref: main
          path: ./.github/repos/tsgcpp/upload-artifact-private
          token: ${{ secrets.PAT_TOKEN }}

      - uses: ./.github/repos/tsgcpp/upload-artifact-private
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0
          retention-days: 3

対象のリポジトリにアクセス可能なPersonal Access Tokenを作成してsecretsに登録して使用する必要があるなど、多少手間があります。

Private Actionを直接 `uses` に指定できない理由

GitHub Actionsのワークフローでデフォルトで発行される GITHUB_TOKEN があるのですが、
GITHUB_TOKEN はワークフローを実行したリポジトリのみアクセス可能なトークンなので他のリポジトリにはアクセスできません。

そのため、Private Actionの場合はアクセス可能なトークンを使ってcheckoutしてから、usesに指定する必要があります。

GitHub様、Private Actionに特化したトークンの機能つくってほしいなー

ダウンロード済みのActionは再利用される

全く同じバージョンやSHAのActionがダウンロード済みの場合は、ダウンロード済みのものが再利用されます。

ダウンロード済みのActionはComposite Actionなどの外部yamlでも共有されます。

    - name: Cache actions/cache
      uses: actions/checkout@v3
      with:
        repository: 'actions/cache'
        ref: v3.0.8
        path: ${{ inputs.pathRoot }}/actions/cache

    - uses: ./.github/composite/checkout-actions

# .github/composite/checkout-actions
    # Compsite Action側
    - name: Cache actions/upload-artifact
      uses: actions/checkout@v3  # ダウンロード済みの `actions/checkout` を使用
      with:
        repository: 'actions/upload-artifact'
        ref: v3.1.0
        path: ${{ inputs.pathRoot }}/actions/upload-artifact

ちなみにデバッグモードを有効化すると、以下のログで再利用されていることが確認できます。

Getting action download info
##[debug]Action 'actions/upload-artifact@v3' already downloaded at '/home/runner/work/_actions/actions/upload-artifact/v3'.

https://github.com/tsgcpp/GitHubActionsTestbed/actions/runs/3117276928/jobs/5055819436#step:7:9

Composite Actionの注意点

Composite Action自体のcheckoutが必要

ワークフロー実行時はリポジトリの内容はcheckoutされていません。
Composite Actionは外部yamlに定義する関係であらかじめcheckoutで他ソースと一緒に取得する必要があります。

...
    steps:
      - uses: actions/checkout@v3
        with:
          lfs: true
...
      # actions/checkoutで取得したComposite Actionを使用
      - uses: ./.github/composite/dotnet-build

Publicリポジトリの場合はリポジトリ指定で実行可能

Publicなリポジトリに配置されたComposite Actionであれば、以下の様に指定できます。

      - uses: <org>/<repository>/<path to action directory>@<ref(tag or branch)>

以下は指定例です。

      - uses: tsgcpp/GitHubActionsTestbed/.github/composite/dotnet-build@main

ワークフロー本体のyamlの`uses`で指定されたActionは事前ダウンロードされる

ワークフロー本体のyaml内の uses に定義したActionですが、ワークフローの最初 (Set up job) で事前ダウンロードされます。

こちらもデバッグモードを有効化すると確認できます。

Getting action download info
Download action repository 'actions/upload-artifact@v3' (SHA:3cea5372237819ed00197afe530f5a7ea3e805c8)
##[debug]Download 'https://api.github.com/repos/actions/upload-artifact/tarball/3cea5372237819ed00197afe530f5a7ea3e805c8' to '/home/runner/work/_actions/_temp_e6a3dde4-ca19-4d00-af3a-9a6c772ea0ec/241095c2-ea32-481b-83fe-d1b6af6915ac.tar.gz'

https://github.com/tsgcpp/GitHubActionsTestbed/actions/runs/3117276928/jobs/5055819436#step:1:45

外部yamlに定義されたActionはステップ実行時に遅延ダウンロードされる

本記事の本題といっても過言ではありません！

Composite Actionを含む外部yaml内のActionは実行されるタイミングでダウンロードされます！

つまり、外部yamlのActionは遅延処理的な性質があります。

.github/workflows/build-dotnet.yml を例に取ると

actions/cacheはワークフローのはじめにダウンロードされる
- ワークフロー本体のyaml内で定義されているため
actions/setup-dotnetとactions/upload-artifactは各ステップ実行時にダウンロードされる
- Composite Actionのyaml内に定義されているため

# withは省略
      - uses: actions/cache@v3
...
      # 内部で uses: actions/setup-dotnet@v2
      - uses: ./.github/composite/dotnet-build

      # 内部で uses: actions/upload-artifact@v3
      - uses: ./.github/composite/upload-artifact
...

Actionのログを見てみると、Set up job でactions/cacheはダウンロードされていますが、 actions/setup-dotnetとactions/upload-artifactはダウンロードされていないことがわかります。

actions/setup-dotnetとactions/upload-artifactは各種ステップの実行時にダウンロードされています。

ログの全体は以下です。

github.com

遅延ダウンロードの何が問題なのか？

「大した問題じゃなくね？」って思った方もいると思いますし、実際大した問題にならないパターンも多いです。

問題になりやすい例として、完了に長時間を要するワークフローがあります。

例えば以下のようなワークフローです。

5時間かかるアプリのビルド実行
ビルド完了後に Composite Actionを使ってアプリをストアへアップロード
- Composite Action内でアプリのストアアップロード用Actionを取得して使用

ワークフロー開始時にはGitHubは正常だったのに、
5時間後のビルド時にGitHubのAPIが一部死んでいてストア用のActionのダウンロード(checkout)が失敗してビルドがパーになっちゃうパターンです。

ストア側のAPIは問題がなかった場合、予めストア用のActionをダウンロードできていれば回避できた問題ですね。。。

昨今クラウドベンダー(AWSなど)の一時インスタンスでビルドすることも多くなっていて、ビルド成果物をどこかに退避していないとサルベージも困難だったりします。

対策1 あらかじめ使用するActionすべてのcheckoutを済ませる (オススメ)

事前ダウンロードされてないなら、明示的に事前ダウンロードしてしまおうという発想です。

1例として、以下のようなセットアップ用Composite Actionを用いる方法があります。

name: 'Set Up Actions'
inputs:
  pathRoot:
    required: true
    description: 'Relative path the actions will be into'
    default: ./.github/repos
  patToken:
    required: true
    description: 'GitHub Personal Access Token to checkout private repositories.'
runs:
  using: "composite"
  steps:
    - name: Cache actions/checkout
      uses: actions/checkout@v3
      with:
        repository: 'actions/checkout'
        ref: v3.0.2
        path: actions/checkout@v3

    - name: Cache actions/cache
      uses: actions/checkout@v3
      with:
        repository: 'actions/cache'
        ref: v3.0.8
        path: ${{ inputs.pathRoot }}/actions/cache

    - name: Cache actions/upload-artifact
      uses: actions/checkout@v3
      with:
        repository: 'actions/upload-artifact'
        ref: v3.1.0
        path: ${{ inputs.pathRoot }}/actions/upload-artifact

    - name: Cache actions/download-artifact
      uses: actions/checkout@v3
      with:
        repository: 'actions/download-artifact'
        ref: v3.0.0
        path: ${{ inputs.pathRoot }}/actions/download-artifact

    - name: Cache actions/setup-dotnet
      uses: actions/checkout@v3
      with:
        repository: 'actions/setup-dotnet'
        ref: v2.1.0
        path: ${{ inputs.pathRoot }}/actions/setup-dotnet

    - name: Checkout tsgcpp/upload-artifact-private
      uses: actions/checkout@v3
      with:
        # Same with actions/upload-artifact
        repository: 'tsgcpp/upload-artifact-private'
        ref: main
        path: ${{ inputs.pathRoot }}/tsgcpp/upload-artifact-private
        token: ${{ inputs.patToken }}

後は、usesにダウンロード済みのActionを指定するだけです。

name: "Build Dotnet with Set Up Actions"

on:
  workflow_dispatch: {}

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          lfs: true

      - uses: ./.github/composite/setup-actions
        with:
          patToken: ${{ secrets.PAT_TOKEN }}

      - uses: actions/cache@v3
        with:
          path: ./Lottery/obj
          key: dotnet-${{ runner.os }}-${{ github.ref_name }}

      - uses: ./.github/composite/dotnet-build-with-setup-actions

      - uses: ./.github/composite/upload-artifact-with-setup-actions
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0

# .github/composite/dotnet-build-with-setup-actions/action.yml
name: 'Dotnet Build with Set Up Actions'
description: 'Restore packages, Build and Test'
runs:
  using: "composite"
  steps:
    - uses: ./.github/repos/actions/setup-dotnet
      with:
        dotnet-version: '6.0.x'
        include-prerelease: false

    - name: Restore Packages
      shell: bash
      run: dotnet restore ./GitHubActionsTestbed.sln

    - name: Build Projects
      shell: bash
      run: dotnet build ./GitHubActionsTestbed.sln --configuration Release

    - name: Test Projects
      shell: bash
      run: dotnet test ./GitHubActionsTestbed.sln --blame

# .github/composite/upload-artifact-with-setup-actions/action.yml
name: 'Upload Artifact with Set Up Actions'
description: 'An action to create a artifact'
inputs:
  name:
    required: true
    default: 'Artifact'
  path:
    required: true
  retention-days:
    required: false
    default: 3
runs:
  using: "composite"
  steps:
    - uses: ./.github/repos/actions/upload-artifact
      with:
        name: ${{ inputs.name }}
        path: ${{ inputs.path }}
        retention-days: ${{ inputs.retention-days }}

このやり方の利点は以下があると思っています。

複数のWorkflow間で使用するActionのバージョンを統一できる
- 特に同じActionを使う場合でも、v2とv3で指定を間違えるなども回避しやすい
Public Action, Private Actionどちらも使用時の uses への指定方法が統一される
- どちらもダウンロード済みのActionになっているため

対策2 usesで使用するActionを宣言 (非推奨)

「ダウンロード済みのActionは再利用される」の性質を利用したやり方ですね。

ただ、このやり方は公式ドキュメントにはないやり方で、仕様の裏をついたやり方なので非推奨です。
また、usesで宣言した限りステップ自体は実行されてしまうため、Actionによっては予期しない副作用が発生する可能性もあります。

事前ダウンロード時に失敗してもワークフローを継続させるために continue-on-error: true を宣言しています。

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      # actions/upload-artifactを事前ダウンロードさせる
      - uses: actions/upload-artifact@v3
        continue-on-error: true

      # actions/setup-dotnetを事前ダウンロードさせる
      - uses: actions/setup-dotnet@v2
        continue-on-error: true
        with:
          dotnet-version: '6.0.x'
          include-prerelease: false

      - uses: actions/checkout@v3
        with:
          lfs: true

      - uses: actions/cache@v3
        with:
          path: ./Lottery/obj
          key: dotnet-${{ runner.os }}-${{ github.ref_name }}

      # ダウンロード済みのactions/setup-dotnetが使用される
      - uses: ./.github/composite/dotnet-build

      # ダウンロード済みのactions/upload-artifactが使用される
      - uses: ./.github/composite/upload-artifact
        with:
          name: Lottery
          path: ./Lottery/bin/Release/net6.0

GitHub Actions側に事前ダウンロード機能として、usesの pre-download的なオプションを要望として出しても良さそうな気はしてます。

Reusing Workflows との違い

GitHub ActionsにはReusing Workflowsという機能があります。
こちらは名前の通りワークフロー全体を再利用する形になります。

docs.github.com

一方でComposite Actionは数ステップを集約して、ワークフロー(ジョブ)にステップとして組み込む機能になります。
もしワークフロー全体を再利用する場合は、Composite ActionではなくReusing Workflowsのほうが最適と言えます。

余談、筆者が遭遇した事象

「外部yamlに定義されたActionはステップ実行時に遅延ダウンロードされる」の仕様を認識するきっかけになった事象がありました。

Composite Actionを使ったCIのワークフローを運用していて、半年以上問題が発生していなかったのですが、
ある日大事な提出でビルドマシンがいつも以上にガンガン回っているときでした。

初回のcheckoutは問題なく実行されましたが、数時間のビルドを終わらせた後のComposite Action内でActionのダウンロード(checkout)が発生したとき、
なぜか急にUnauthorizedになってcheckout不可になる現象が発生するようになりました。

checkout対象はPublic Actionの uses: actions/upload-artifact だったので、なぜUnauthorizedになったのかは本当に謎でした。。。
ただ、今回の現象に関わらず外部APIにアクセスできなくなる可能性は十分に考えられます。

一番の問題は失敗時の時間的損失が大きかったことのため、
外部APIなどが関係するステップをワークフローの初回に集約し、失敗しても時間的損失を極力回避できるように組み直しました。

今回紹介した setup-actions がその一例となります。

完全なネットワーク障害などに対応しきれるわけではありませんが、あらかじめActionをダウンロードしておくことは一部ワークフローでは有効かと思いますため、
良かったら参考にしていただければと！

サンプルプロジェクト

github.com

雑感

直近はかなりドタバタしていたので、これまた久々の記事です。。。

最近はXR、非XRに限らずインフラはやはり重要だなと痛烈に感じています。
XRアプリの開発もどんどん規模が大きくなっているため、開発基盤の重要性もかなり上がっています。

Unityに限らずAndroid, iOS, Dockerを含むサーバーサイドのCI/CDを経験してきた身としては、
インフラをもっと強化していきたいと常に考えるようになりました。

そういえば「すぎしーのXRと3DCG」というブログ名ですが、そろそろ改名を考えています。
XR開発はインタラクションやグラフィックスももちろん重要ですが、それに負けないくらいクリエイターが開発に注力できる環境を用意することも大事だと思います。

これからもよろしくです！

それでは～

【Unity Localization】 GCPのサービスアカウントでプライベートSheetsと連携 (Cronジョブ対応含む)

2022-08-21T19:37:30+09:00

概要
- 前回の記事
動作環境
備考
GCPのサービスアカウント対応手順
CronによるGoogle SheetsからのStringTableCollectionの定期更新
おまけ、GitHub ActionsでSheets連携をCronジョブ対応
拡張パッケージ (Example含む)
雑感

概要

今回も前回に引き続きUnity Localizationに関するTipsです。
GCPのサービスアカウントでプライベートSheetsと連携する方法を紹介します。

Unity Localization標準のOAuth認証を使用すれば一応プライベートSheetsにアクセスすることは可能ですが、Cronジョブなどで定期更新に対応したいときに不都合があります。

そんな問題をGCPのサービスアカウントを用いて解決したいと思います！

おまけでCronジョブでGoogle SheetsからStringTableCollectionを定期更新するTipsも紹介します。

前回の記事

良かったら合わせてどうぞ！

tsgcpp.hateblo.jp

動作環境

Unity 2021.3.6f1
- Unity 2020 でも可
Unity Localization 1.3.2

備考

今回紹介する機能は拡張パッケージとしても用意しています。

記事の最後にGitHubへのリンクを記載していますため、よろしければどうぞ。

GCPのサービスアカウント対応手順

サービスアカウントの作成

GCPのCredentialsページにてサービスアカウントを作成
- GCP自体のアカウント作成などは各自調べてください

console.cloud.google.com

サービスアカウントの認証用JSON形式の鍵をダウンロード

以下のようなJSON形式の鍵がダウンロード出来ます。
JSON文字列は後述するクラスに渡すために使用します。

{
  "type": "service_account",
  "project_id": "xxx-workspace",
  "private_key_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "client_email": "[email protected]",
  "client_id": "121212121212121212121",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

※アクセス権限に使用する鍵のため、厳重に管理してください

対象のSheetsにサービスアカウントのアクセス権限を付与

Pullのみの場合は閲覧権限、Pushも行う場合は編集権限をサービスアカウントに与えてください。

GCPのサービスアカウント向けSheetsServiceProviderを作成

1.3.2時点のUnity LocalizationにはGCPのサービスアカウント連携用クラスが用意されていなかったため用意します。
いずれ公式から提供される気がしますが、今回は実装します。

    public class ServiceAccountSheetsServiceProvider : IGoogleSheetsService
    {
        private readonly string _serviceAccountKeyJson;
        private readonly string _applicationName;

        public ServiceAccountSheetsServiceProvider(
            string serviceAccountKeyJson,
            string applicationName)
        {
            _serviceAccountKeyJson = serviceAccountKeyJson;
            _applicationName = applicationName;
        }

        public SheetsService Service => GetSheetsService();

        private SheetsService GetSheetsService()
        {
            var credential = GoogleCredential.FromJson(_serviceAccountKeyJson);
            var initializer = new BaseClientService.Initializer
            {
                HttpClientInitializer = credential,
                ApplicationName = _applicationName,
            };
            var sheetsService = new SheetsService(initializer);
            return sheetsService;
        }
    }

serviceAccountKeyJson には、先程作成したサービスアカウントのJSON文字列を渡す
applicationName には GoogleSheetsService (ScriptableObject) に設定した ApplicationName を指定

GCPのサービスアカウント向けSheetsServiceProviderを使用してPull or Push

先程作成した ServiceAccountSheetsServiceProvider を用いてPull or Pushを実施
- ※以下の実装は、前回の記事で紹介したコードをServiceAccountSheetsServiceProviderに入れ替えたもの

            // 対象のStringTableCollectionを取得
            var collection = AssetDatabase.LoadAssetAtPath<StringTableCollection>("Assets/<path to StringTableCollection>");

            // GoogleSheetsExtensionをStringTableCollectionから取得
            var sheetsExtension = collection.Extensions.OfType<GoogleSheetsExtension>().FirstOrDefault();

            // *前回の記事と異なり、ここでServiceAccountSheetsServiceProviderを使用
            var serviceProvider = new ServiceAccountSheetsServiceProvider(
                serviceAccountKeyJson: "<GCPサービスアカウントのJSON形式の鍵の文字列>",
                applicationName: "<GoogleSheetsService (ScriptableObject) に設定したApplicationName>");

            // Google Sheetsアクセス用インスタンスを生成
            var sheets = new GoogleSheets(serviceProvider);

            // ※必ずSpreadSheetIdをGoogleSheetsインスタンスに指定してください！
            sheets.SpreadSheetId = sheetsExtension.SpreadsheetId;

            // 対象のStringTableCollection内の全言語(全Locale)のPullを実施
            sheets.PullIntoStringTableCollection(
                sheetId: sheetsExtension.SheetId,
                collection: collection,
                columnMapping: sheetsExtension.Columns);

上記の方法を使用することで、GCPのサービスアカウントでPull及びPushが可能となります。

以上がGCPのサービスアカウントを使用した連携方法となります。

CronによるGoogle SheetsからのStringTableCollectionの定期更新

さて、今回の実質的な本題に移りたいと思います！
今回、GCPサービスアカウントを用いた本当の理由はCron(定期ジョブ)を使ったStringTableCollection更新に対応させるためです！

そもそもなぜOAuthが使えないのか

Cron対応なしで運用する場合はそもそもGCPサービスアカウント対応は不要です。
概要で少し触れましたがプライベートのSheetsには標準のOAuth認証でも連携可能です。

Unity Localization標準のOAuthの問題は、主に以下の2点です。

認証にUnityエディタ上でのUI操作が必要
- batchモード(CLI)での認証が困難
認証後に生成される認証ファイルが Library/Google/GoogleSheetsService 以下で管理
- LibraryフォルダはUnityにおけるキャッシュフォルダでもあるため、クリーンビルドを行うCIなどと相性が悪い

というわけで、
batchモードで認証を完結させるために、JSON形式の鍵文字列を渡すだけで認証が可能なServiceAccountSheetsServiceProvider を用意した感じです。

鍵文字列をServiceAccountSheetsServiceProviderに渡す方法

サービスアカウントの鍵はアクセス権限を握るセンシティブなデータファイルなので、鍵の文字列をgitリポジトリ内で管理することはタブーです！

セキュリティを考慮して使用後はキャッシュとして残らない方法と取りましょう。

1. 環境変数で渡す

CIとも相性がよくジョブプロセス単位で管理可能なため、筆者としても環境変数を利用する方法がオススメです！

            const string EnvironmentGoogleServiceAccountKey = "UNITY_LOCALIZATION_GOOGLE_SERVICE_ACCOUNT_KEY";
            var serviceAccountKeyJson = Environment.GetEnvironmentVariable(EnvironmentGoogleServiceAccountKey);

            var serviceProvider = new ServiceAccountSheetsServiceProvider(
                serviceAccountKeyJson: serviceAccountKeyJson,
                applicationName: "<GoogleSheetsService (ScriptableObject) に設定したApplicationName>");

2. ジョブ中のみ鍵ファイルを生成

環境変数を使用できない場合は、ジョブ中のみJSON形式の鍵ファイルを生成する対応が一つの選択肢になります。

以下はbashを用いて環境変数からJSON鍵ファイルを復元する方法です。

$ echo "${UNITY_LOCALIZATION_GOOGLE_SERVICE_ACCOUNT_KEY}" > "<path to key>/service-account-key.json"

あとは、上記鍵ファイルからJSON文字列を取り出して渡すだけです。

            const string JsonKeyPath = "<path to key>/service-account-key.json";
            string serviceAccountKeyJson = File.ReadAllText(keyJsonPath);

            var serviceProvider = new ServiceAccountSheetsServiceProvider(
                serviceAccountKeyJson: serviceAccountKeyJson,
                applicationName: bundle.SheetsServiceProvider.ApplicationName);

ジョブの成否に関わらず、不要になったら生成した鍵ファイル削除を忘れずに！

$ rm "<path to key>/service-account-key.json"

余談、現時点の game-ci/unity-builder では独自の環境変数をメソッドに渡せない

GitHub ActionsでGameCIを使っている人は結構いるかと思いますが、
残念ながらgame-ci/unity-builderのbuildMethodでUnity側のメソッドを叩くときに独自の環境変数を渡せないようでした。。。 (知っている方がいたらぜひ教えてください！)

そんな経緯もあって、「ジョブ中のみ鍵ファイルを生成」という方法を紹介しました。

Pull or Push

あとは「GCPのサービスアカウント向けSheetsServiceProviderを使用してPull or Push」と同様に生成したserviceProviderを使用するだけです。

            // Google Sheetsアクセス用インスタンスを生成
            var sheets = new GoogleSheets(serviceProvider);

            // ※必ずSpreadSheetIdをGoogleSheetsインスタンスに指定してください！
            sheets.SpreadSheetId = sheetsExtension.SpreadsheetId;

            // 対象のStringTableCollection内の全言語(全Locale)のPullを実施
            sheets.PullIntoStringTableCollection(
                sheetId: sheetsExtension.SheetId,
                collection: collection,
                columnMapping: sheetsExtension.Columns);

おまけ、GitHub ActionsでSheets連携をCronジョブ対応

サンプルを用意したので、よければ参考にして下さい。

pull-localization.yml (GitHub Actionsのワークフロー)
ExampleLocalizationSynchronizationMenu.cs (Unity側のメソッド)
- コード内のregion "Service Account Key from Environment Variable" を参照

大まかな流れは以下です。

GitHub ActionsのSecrets (GOOGLE_SERVICE_ACCOUNT_KEY_JSON_BASE64) から鍵文字列をデコードしてJSONファイルを生成
- 鍵文字列のBase64対応は必須ではないですが、環境依存な文字(かっこやカンマなど)があっても対応しやすいので入れています
Unity側のメソッド PullAllLocalizationTablesFromTempKeyJson をgame-ci/unity-builderでbuildMethod経由で実行
- game-ci/unity-builderのbuildMethodの使用方法はGameCIのドキュメントを参照
Pull完了後は生成した鍵ファイルを削除
Commit, Push して Pull Request

ちなみに、サンプルでは以下のようなプルリクエストが発行されます。

github.com

拡張パッケージ (Example含む)

使用方法はREADME.mdの "Feature" を参照

github.com

雑感

Unity Localization第2弾でした。
また時間が空いてしまいました。。。

UnityとGitHub Actionsを活用したワークフローに関するノウハウも結構溜まってきたので、機会があれば紹介したいですね。
次回の記事は決まってませんが、状況が落ち着いたらまた何か書きます。

それでは～

【Unity Localization】複数のStringTableCollectionを一括PullのTips (拡張ツール提供有り)

2022-07-29T23:31:11+09:00

概要
環境
補足
- StringTableCollection
- GoogleSheetsService
Tips
拡張ツールの紹介
サンプルコード
雑感

概要

今回は Unity Localization に関するTipsです。
ついでに拡張パッケージの作ってみたのでよかったら使ってみてください。

[email protected]/manual/index.html">docs.unity3d.com

最近 Unity Localization を触りだしたのですが、リリースされてまだ日も浅いパッケージのせいかまだまだ機能に物足りなさも感じられます。
今回はUnity LocalizationでGoogle Sheetsから複数のStringTableCollection をまとめて更新するTipsを紹介します。

Unity Localization に関してはデニックさんの以下の記事をご覧ください！

xrdnk.hateblo.jp

環境

Unity 2021.3.6f1
Unity Localization 1.3.2

補足

StringTableCollection

StringTableCollectionはKey, Value形式で全言語分の翻訳テーブルをまとめているScriptableObjectです。
StringTableはRuntimeで使用可能に対して、StringTableCollectionはEditor限定の機能となります。

Google Sheetsとの対応は Extensions 項目の GoogleSheets を追加及び設定することで実現できます。
SpreadSheetsId, SheetsId (gid) を設定することで、Googleドライブ上のスプレッドシートと対応させます。

GoogleSheetsService

GoogleSheetsService (SheetsServiceProvider) は Googleのサービスとの認証関連を設定するScriptableObjectです。
今回はこちらを使用するため設定をお願いします。

認証の設定については以下のデニックさんの記事をどうぞ！

xrdnk.hateblo.jp

Tips

スクリプトで `StringTableCollection` をPullする方法

簡単に説明すると GoogleSheets.PullIntoStringTableCollection に認証済みのSheetsServiceProvider, SpreadSheetsId, SheetsId を渡すことで可能となります。

結構説明が難しいのでサンプルコードを記載します。

    // 対象のStringTableCollectionを取得
    StringTableCollection collection = AssetDatabase.LoadAssetAtPath<StringTableCollection>("Assets/<path to StringTableCollection>");

    // GoogleSheetsExtensionをStringTableCollectionから取得
    var sheetsExtension = collection.Extensions.OfType<GoogleSheetsExtension>().FirstOrDefault();

    // Google認証設定を持つSheetsServiceProviderを取得
    SheetsServiceProvider serviceProvider = AssetDatabase.LoadAssetAtPath<SheetsServiceProvider>("Assets/<path to SheetsServiceProvider>");

    // Google Sheetsアクセス用インスタンスを生成
    var sheets = new GoogleSheets(serviceProvider);

    // ※必ずSpreadSheetIdをGoogleSheetsインスタンスに指定してください！
    sheets.SpreadSheetId = sheetsExtension.SpreadsheetId;

    // 対象のStringTableCollection内の全言語(全Locale)のPullを実施
    sheets.PullIntoStringTableCollection(
        sheetId: sheetsExtension.SheetId,
        collection: collection,
        columnMapping: sheetsExtension.Columns);

sheets.SpreadSheetId = sheetsExtension.SpreadsheetId; は必ず実施してください。
どうやら1.3.2時点ではInspectorのPullを押したときしか実施されていないようです。

上記コードが StringTableCollection のInspector上のPullボタンと似た処理を実施しています。

複数のStringTableCollectionを一括でPullする方法

スクリプトでPullする方法がわかったので、あとは対象のStringTableCollectionを取得して for ループで実行するのみです。

StringTableCollectionを一括で取得するEditorコード

自分は以下のような指定のフォルダ以下のアセットをまとめて取得するスクリプトを使用しています。

AssetFinding.cs

余談、公式サンプルコードについて

上記のコードのヒントですが、Unity Localization に含まれている DocCodeSamples.Tests/GoogleSheetsSamples.cs に記載されています。

また、その他のサンプルコードも DocCodeSamples.Tests/ 以下にいくつかありますため参考にすると良いと思います！

拡張ツールの紹介

今回、以下のようなUnity Localitionの拡張ツールを用意しました。
いずれ提供される機能だとは思いますが、それまでの代用やコードの参考としてどうぞ。

github.com

StringTableCollectionBundle というScriptableObjectを設定することでまとめてPull, Pushできるようにしています。
Pullには閲覧権限、Pushには編集権限が必要となります。

詳細な使用方法は README.md を参照ください。

サンプルコード

github.com

Assets/Example 以下に実装例があります。

雑感

まさかのローカライズ系の記事になりました。

前回の記事で絶対にXR系の記事を書くと述べたのですが、
どうもいい感じのネタになっておらず一旦別の記事に逃げることにしました。。。

さて、次回は今回の延長で「Unity LocalizationでGCPのサービスアカウントを使ってプライベートなSheetsと連携」みたいな記事を書く予定です。
(ちなみにこの機能はすでに UnityLocalizationExtension に組み込んであったりします。)

それでは～

GitHub ActionsのWindows self-hostedでpwshとbashを使う方法

2022-05-20T00:38:59+09:00

概要
動作環境
pwshとbashを使用する条件
手順
詳細
活用例
- 日付を文字列として取得
- レジストリから値を取得
余談、GitHub Actionsで提供されているWindowsのRunnerでは標準でpwshとbashが使用可能
- windows-latestでpwshとbashが使用可能なことを確認
雑感

概要

今回は GitHub ActionsのWindows self-hostedでpwshとbashを使う方法を紹介します。

残念ながら素のWindowsマシンでshellとしてpwshやbashを指定しても使用することができません。

Windows上でpwshとbashが使用できるとCIで行えるフローの選択肢が大幅に増えると思いますので、ぜひ参考にしていただければと思います！

動作環境

Windows10 Pro (Homeでも可)

pwshとbashを使用する条件

簡単に言えば、以下を満たせば良いです

Git for Windows (Git Bash) と PowerShell7 (pwsh付属) をインストール
Windowsのシステム環境変数のPATHに bash.exe と pwsh.exe があるフォルダを追加

手順

詳細はあとで記載します。

1. Git for Windows と PowerShell7 をインストール

以前紹介した記事を参考にGit for WindowsとPowerShell7をインストールしてください

tsgcpp.hateblo.jp

2. システム環境変数のPATHに登録

Git for WindowsとPowerShell7をインストールしたフォルダをPATHに登録してください。
PATHを通すps1ファイル (set-git-path.ps1, set-powershell-path.ps1)も上記の記事内にて記載しています。

システム環境変数に直接以下を追加しても大丈夫です(標準のインストールフォルダの場合)。

C:\Program Files\Git\cmd;C:\Program Files\Git\bin;C:\Program Files\PowerShell\7

3. self-hostedのrunnerプロセスを再起動

環境変数をプロセスに反映させるために再起動してください。
再起動方法は以下の公式ドキュメントを参考にしてください。

docs.github.com

もし、PowerShell上でGitHub Actionsのself-hostedの .\run.cmd で起動している場合はPowerShell自体も再起動してください。

手順は以上となります！

詳細

確認用のworkflow

以下のworkflowを使って確認します。

name: Windows Shell Check

on: workflow_dispatch

jobs:
  shell-check-all:
    runs-on: self-hosted
    steps:
      - name: Check cmd
        shell: cmd
        run: |
          echo cmd ok
        if: ${{ always() }}

      - name: Check pwsh
        shell: pwsh
        run: |
          echo pwsh ok
        if: ${{ always() }}

      - name: Check bash
        shell: bash
        run: |
          echo bash ok
        if: ${{ always() }}

インストール前

以下のように cmd のみ使用可能で、それ以外は使用できません。。。

インストール後

問題なさそうですね。

活用例

せっかくなので、活用例を紹介します。

日付を文字列として取得

Bashのdateコマンドを使って取得します。

name: Get Date String

on: workflow_dispatch

jobs:
  get-date-string:
    runs-on: self-hosted
    steps:
      - name: Get Date String
        run: echo "::set-output name=DATE::$(date +%Y%m%d%H%M)"
        shell: bash
        id: get-date-string
      - name: Use Date String
        run: echo "${{ steps.get-date-string.outputs.DATE }}"

Bashは手軽に文字列を生成可能なコマンドがたくさんあります！

レジストリから値を取得

以下はレジストリに登録されたUnity 2021.3.2f1 のインストールフォルダを取得する方法です。

name: Get Unity Folder

on: workflow_dispatch

jobs:
  get-unity-folder:
    runs-on: self-hosted
    steps:
      - name: Get Unity Folder
        run: Write-Host -NoNewline ('::set-output name=UNITY_FOLDER::' + (Get-ItemProperty 'HKCU:SOFTWARE\Unity Technologies\Installer\Unity 2021.3.2f1').'Location x64')
        shell: pwsh
        id: get-unity-folder
      - name: Use Unity Folder
        run: echo "${{ steps.get-unity-folder.outputs.UNITY_FOLDER }}"

Windowsのシステムに関わる情報を取得したい場合はPowerShellのほうが適している気がします。

余談、GitHub Actionsで提供されているWindowsのRunnerでは標準でpwshとbashが使用可能

PowerShellはともかく、Bashも使用できるように用意してくれていたりします。

ドキュメントでも以下のように記載されています。
GitHub ActionsもGit for Windowsを使用しているようですね。

When specifying a bash shell on Windows, the bash shell included with Git for Windows is used.

docs.github.com

windows-latestでpwshとbashが使用可能なことを確認

先程のworkflowのrunnerにwindows-latestを指定して確認してみましょう。

jobs:
  shell-check-all:
    strategy:
      matrix:
        runner: [self-hosted, windows-latest]
    runs-on: ${{ matrix.runner }}
    steps:

結果は以下のように問題なく使用可能です！

雑感

最近Git for WindowsとPowerShell7のインストール方法を紹介した本当の目的はこちらだったりします。

私個人では開発基盤を用意する機会が増えているんですが、
pwshとbash (特にbash!)をGitHub Actionsで使えるようにしておくと何かと捗ったり、self-hostedとwindows-latestでworkflowの互換性が確保できたりします。

わざわざGitHub Marketplaceや独自アクションを使用しなくてもできることが増えると思いますので、ぜひご活用ください！

それでは～

pwshをコマンドラインでインストールしてPATHを通す方法

2022-05-18T00:50:18+09:00

概要
動作環境
変更履歴
注意事項
インストール方法
スクリプト解説
- msiexecによるインストール
- PowerShell-7.x.x-win-x64.msi のインストールオプション
雑感

概要

前回に続いて、今回はWindowsのコマンドラインで PowerShell7 をインストールする方法を紹介します。

github.com

PowerShell5はWindowsに標準で搭載されていますが、pwsh コマンドは実行できません。そこでPowerShell7を別途インストールすることで pwshコマンドとして使用可能になります。

そんなPowerShell7をコマンドライン経由でインストールしPATHを登録する方法を紹介します。

動作環境

Windows 10
- 筆者はPro版ですが、Homeでも問題ないと思います

変更履歴

2022/05/18
- タイトルを「【PowerShell】 PowerShell7をコマンドラインからインストールして、pwshコマンドにPATHを通す」→「pwshをコマンドラインでインストールしてPATHを通す方法」に変更
2023/02/05
- 「install-powershell.ps1 を実行」を PowerShell -ExecutionPolicy Bypass を使ったコマンドに修正

注意事項

以下を試す場合は自己責任でお願いします！
以下の処理は管理者権限で実行しますが、当方は事故や故障などの一切の責任を負いません！
環境変数 PATH を変更するため、変更前のPATHを記録しておくことを推奨！

上記の件、ご留意ください

インストール方法

※前回の記事 (Git for Windowsをコマンドラインからインストールする方法) と流れはほとんど同じです

Gitからps1ファイルをクローン

ps1ファイル(PowerShell スクリプト)を以下のリポジトリからクローンする

github.com

PowerShellを管理者権限で開く

※開き方は好きなやり方で問題ありません

Windows 10標準搭載のPowerShell5を使用

Windows キーを押して、「powershell」を検索
「管理者として実行する」をクリック

PowerShellでクローンしたWindowsInfrastructureExample上に移動

cd <path>\WindowsInfrastructureExample

PowerShell-7.x.x-win-x64.msi を配置

コマンドでダウンロードする場合

Invoke-WebRequest https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x64.msi -OutFile PowerShell-7.2.3-win-x64.msi

※インフラ構築のスクリプトを書く場合は、このコマンド自体をps1スクリプトに組み込んでも良い

ブラウザでダウンロードする場合

以下より PowerShell-7.x.x-win-x64.msiをダウンロードし、WindowsInfrastructureExample フォルダ以下に配置

github.com

ps1の実行を許可

Set-ExecutionPolicy RemoteSigned -Scope Process

install-powershell.ps1 を実行

> PowerShell -ExecutionPolicy Bypass .\install-powershell.ps1

エラーログが出なければ問題なく PowerShell7 のインストール完了

インストールの確認 (コマンドラインの場合)

Dir 'C:\Program Files\PowerShell\7\pwsh.exe'でエラーが出なければインストール完了

Dir 'C:\Program Files\PowerShell\7\pwsh.exe'


    ディレクトリ: C:\Program Files\PowerShell\7


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        2022/04/15     20:07         287664 pwsh.exe

(任意)PATHの追加

ローカルPCの環境変数 PATH が変更されます！ご注意ください！

PowerShell -ExecutionPolicy Bypass .\set-powershell-path.ps1

以上でインストール及び設定は完了です。

スクリプト解説

install-powershell.ps1

msiexecによるインストール

msi インストーラーは msiexec.exeを使用することで、コマンドラインからインストール可能です。

PowerShell-7.x.x-win-x64.msi のインストールオプション

詳細は以下のページに記載されています

docs.microsoft.com

INSTALLFOLDER

名前の通りインストール先のフォルダを指定。
以下のように指定すると良いです。

$InstallFolder = 'C:\Program Files\PowerShell'
(略)
msiexec.exe `
    ...
    INSTALLFOLDER=`"$InstallFolder`" `
    ...

ちなみに、C:\Program Files\PowerShell を指定した場合、pwshは‪C:\Program Files\PowerShell\7\pwsh.exeに配置されます。

また、スクリプト内でフォルダ名を`"XXX`" のように囲むのは不思議な感じがしますが、これで問題ありません。

Windowsのコマンドラインはスペースの扱いがめんどくさいですね。。。それなのに "Program Files" はスペースが有るという。。。

ADD_PATH=0

PATHに追加するかのオプションです。ADD_PATH=1 にすればパスを通してくれます。
今回はコマンドラインで諸々完結させたかったので0指定(登録しない)にしています。

USE_MU=0, ENABLE_MU=0

いわゆるMicrosoft Updateによる自動更新の設定です。
毎回コマンドラインで更新することを想定し、オフにしています。

解説は以上です！

雑感

Git for Windows, PowerShell7 のインストール方法を紹介したのは、bash, pwsh をインストールするためだったりします。

次回はこの2つを活用したCIについてお話します！
もしかしたらピンと来た方がいらっしゃるかもですね。

さらにその次は絶対にUnity + XR関連にします（そっちのほうが断然楽しいし、何よりブログのタイトル的に。。。）

PATHを変更するような手順の紹介は、試した人の環境を壊しかねないので結構神経を使いますね。。。

それでは～

【Windows, PowerShell】SETX vs. [Environment]::SetEnvironmentVariable

2022-05-17T00:47:25+09:00

概要
結論
違い
- 設定時のレジストリキーの種類が異なる
- (バグ？) SETXの場合、末尾にダブルクォーテーションが挿入されるパターンがある
簡易解説
- 環境変数の設定方法
  - ユーザー環境変数の場合
  - システム環境変数の場合
- 環境変数の確認方法
余談、PATHのREG_SZ登録をREG_EXPAND_SZに切り替える方法
環境変数の補足
雑感

概要

SETX と [Environment]::SetEnvironmentVariable の違いに躓いたので調査したことを共有します！

どちらもWindowsで環境変数を設定する手段ですが、細かいところで違いがありました。

知らずに使ってしまうと最悪Windows上でアプリが起動しなくなるかもしれないので、よかったら参考にしてください。

以下の説明はすべてはPowerShellでの実行を想定

結論

説明が長くなったので、先に結論です。

展開(%...%)を使用するなら、SETX 使って、環境変数の末尾に / を入れない
- x: C:\Program Files\Git\bin;%SystemRoot%\System32\WindowsPowerShell\v1.0\
- o: C:\Program Files\Git\bin;%SystemRoot%\System32\WindowsPowerShell\v1.0
展開(%...%)を使用しないなら、[Environment]::SetEnvironmentVariableでも可

詳しくは以下

違い

設定時のレジストリキーの種類が異なる

試しに環境変数 Foo に %SystemRoot%\System32 を登録してみます。

`SETX` の場合は `REG_SZ` と `REG_EXPAND_SZ` から適した方

SETX Foo 'C:\Windows\System32' -> REG_SZ
SETX Foo '%SystemRoot%\System32' -> REG_EXPAND_SZ

つまり、SETX は%SystemRoot% のような環境変数を展開するような書式を検知したらREG_EXPAND_SZとして登録してくれます。

`[Environment]::SetEnvironmentVariable` は `REG_SZ` 固定

つまり%SystemRoot%があろうがなかろうが REG_SZ 固定になります。

以下は [Environment]::SetEnvironmentVariable('Foo', '%SystemRoot%', [System.EnvironmentVariableTarget]::User) の場合です。

REG_SZの場合、変数が展開されません！これは PATH を設定するときは非常にまずいです！

これに関しては dotnet のGitHubのIssueでずっと議論になっているようです。

github.com

変数が展開されていないことの確認

以下のコマンドを実施する場合は echo ([Environment]::GetEnvironmentVariable('PATH', [System.EnvironmentVariableTarget]::Machine)) などで既存の変数を控えて最後に戻すようにしてください！
特に PATH は元に戻さないとアプリがおかしくなる可能性があります！

[Environment]::SetEnvironmentVariable('PATH', '%SystemRoot%\System32', [System.EnvironmentVariableTarget]::Machine) 実行して、PowerShellを再起動してPATHを確認すると、以下のように展開されていないことがわかります。
そして、もちろんパスも通らないので、PATHを使用しているアプリがおかしくなります！

> echo $Env:PATH
%SystemRoot%\System32;...

SETX /M PATH '%SystemRoot%\System32' であれば REG_EXPAND_SZで登録されるので展開されたものがPATHとして登録されます。

> echo $Env:PATH
C:\WINDOWS\System32;...

(バグ？) SETXの場合、末尾にダブルクォーテーションが挿入されるパターンがある

条件は以下で発生することを確認しています

値の中にスペースが有る
値の最後が /

例: C:\Program Files\Git\bin;C:\WINDOWS\System32\WindowsPowerShell\v1.0\

Program Filesにスペース、v1.0\で末尾がバックスラッシュみたいな場合におかしくなります。(実際に起こった事象を例にしています)。

> SETX /M PATH 'C:\Program Files\Git\bin;C:\WINDOWS\System32\WindowsPowerShell\v1.0\'

成功: 指定した値は保存されました。

> echo ([Environment]::GetEnvironmentVariable('PATH', [System.EnvironmentVariableTarget]::Machine))
C:\Program Files\Git\bin;C:\WINDOWS\System32\WindowsPowerShell\v1.0"

最後に " がなぜが挿入されます。。。 (SETXのバグじゃないかと思っています)

ちなみに、PATHに登録する場合は " がついた方のパス(上記では C:\WINDOWS\System32\WindowsPowerShell\v1.0 )がPATHから除外されてしまいます。

;区切りのパスの末尾には / は不要なので、基本的には最後は / にしないほうが安全だと思います。
結論で述べた「環境変数の末尾に / を入れない」はこれが理由になります。

ご注意ください！

簡易解説

せっかくなのでSETXと[Environment]::SetEnvironmentVariableを少し解説します。

環境変数の設定方法

例えば Foo という環境変数に値 Bar;Baz を入れる場合は以下のようにコールします。

ユーザー環境変数の場合

SETX Foo 'Bar;Baz'

[Environment]::SetEnvironmentVariable('Foo', 'Bar;Baz', [System.EnvironmentVariableTarget]::User)

システム環境変数の場合

システム環境変数とは対象のマシンのユーザー全体で共通となる環境変数のことです。
実行には管理者権限が必要となります。

SETX /M Foo 'Bar;Baz'

[Environment]::SetEnvironmentVariable('Foo', 'Bar;Baz', [System.EnvironmentVariableTarget]::Machine)

環境変数の確認方法

コマンドライン (混合)

※環境変数設定後はPowerShellの再起動が必要

echo $Env:Foo

コマンドライン (個別)

# ユーザー環境変数の場合
echo ([Environment]::GetEnvironmentVariable('Foo', [System.EnvironmentVariableTarget]::User))

# システム環境変数の場合
> echo ([Environment]::GetEnvironmentVariable('Foo', [System.EnvironmentVariableTarget]::Machine))

レジストリエディタ

レジストリエディタを開く
ユーザー環境変数の場合は コンピューター\HKEY_CURRENT_USER\Environment
システム環境変数の場合は コンピューター\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

システムのプロパティ -> 環境変数

Windowsキーを押す
"env" と検索
システム環境変数の編集 をクリック

環境変数 をクリック

余談、PATHの`REG_SZ`登録を`REG_EXPAND_SZ`に切り替える方法

途中までは「システムのプロパティ -> 環境変数」と同様

システム環境変数の編集 をクリック
環境変数 をクリック
変数 Path を選択して、編集をクリック
- ユーザー変数とシステム変数どちらも同様
"環境変数名の編集" の OK をクリック
"環境変数" の OK をクリック

以上

どうやら、"環境変数名の編集" の OK を押したときに REG_EXPAND_SZ で登録される処理が発生するようです。
もし、PATHに %SystemRoot% を使用していて展開されていない場合は試してみてください。

環境変数の補足

Windows上では %SystemRoot% = C:\Windows です。

ちなみに %USERPROFILE%は現在のユーザーのホームフォルダを表します。
エクスプローラーで以下のように入力するとホームフォルダに移動することができます。

雑感

前回の記事で、Git for Windowsの設定するときのコマンドでSetEnvironmentVariable使ってたのですが、
%SystemRoot%が展開されないことに気づいて急遽記事を書きました。

もし、前回の記事を試してローカルがおかしくなった方がいたらごめんなさい。。。「余談、PATHのREG_SZ登録をREG_EXPAND_SZに切り替える方法」を実施すれば解消すると思います 🙇‍♂️

「GetEnvironmentVariable使うなら、対のSetEnvironmentVariableでしょ！」って感じで使ってたらこんな罠があったとは。。。

ご参考になれば幸いです。

それでは～

Git for Windowsをコマンドラインからインストールする方法

2022-05-15T16:12:14+09:00

概要
動作環境
注意事項
変更履歴
2022/05/16 23:00以前のExampleを試した方は以下を実施を推奨
インストール方法
スクリプト解説
余談、今回の調査で躓いたところ
雑感

概要

今回はWindowsのコマンドラインでGit for Windows (Git Bash) をインストールする方法を紹介します。

Git for WindowsはWindows上でGitやBashを使用する場合にインストールしておくと何かと役に立つパッケージですが、
GUI経由でのインストールは必要オプションの取捨選択が必要であったり、なによりインストール状態の再現性に乏しいところがあります。

コマンドライン経由のインストール方法を確立することで、再現性があり開発環境インフラ構築などにも応用させることができますためよかったらご活用ください！

動作環境

Windows 10
- 筆者はPro版ですが、Homeでも問題ないと思います

注意事項

以下を試す場合は自己責任でお願いします！
以下の処理は管理者権限で実行しますが、当方は事故や故障などの一切の責任を負いません！

上記の件、ご留意ください

変更履歴

2022/05/17
- 「2022/05/16 23:00以前のExampleを試した場合は以下を実施をお願いします」を追加
- 「(任意)PATHの追加」に注意文を追記
2023/02/05
- 「install-git.ps1 を実行」を PowerShell -ExecutionPolicy Bypass を使ったコマンドに修正

2022/05/16 23:00以前のExampleを試した方は以下を実施を推奨

環境変数の設定に使用していたコマンド ([Environment]::SetEnvironmentVariable) に少し難点がありました。
WindowsInfrastructureExample 上のスクリプトは修正済みです。

もし、すでに試していてパスが通らなくなったり、コマンドが実行できなくなった方は以下の「余談、PATHのREG_SZ登録をREG_EXPAND_SZに切り替える方法」を試してみてください。

余談、PATHのREG_SZ登録をREG_EXPAND_SZに切り替える方法

詳細も上記記事に記載しています。

インストール方法

インストールオプションについて

以下のコマンドでのGit for Windowsのインストールオプションは筆者が普段使用しているオプションを使用
- 詳細は後述しますが、各自で git-for-windows.inf 都合の良いように改変してください

Gitからps1ファイルをクローン

ps1ファイル(PowerShell スクリプト)を以下のリポジトリからクローンする

github.com

PowerShellを管理者権限で開く

※開き方は好きなやり方で問題ありません

今回はWindows 10標準搭載のPowerShellを使用

Windows キーを押して、「powershell」を検索
「管理者として実行する」をクリック

PowerShellでクローンしたWindowsInfrastructureExample上に移動

> cd <path>\WindowsInfrastructureExample

Git-2.x.x-64-bit.exe を配置

コマンドでダウンロードする場合

> Invoke-WebRequest https://github.com/git-for-windows/git/releases/download/v2.36.1.windows.1/Git-2.36.1-64-bit.exe -OutFile Git-2.36.1-64-bit.exe

※インフラ構築のスクリプトを書く場合は、このコマンド自体をps1スクリプトに組み込んでも良い

ブラウザでダウンロードする場合

以下より Git-2.x.x-64-bit.exeをダウンロードし、WindowsInfrastructureExample フォルダ以下に配置

github.com

install-git.ps1 を実行

> PowerShell -ExecutionPolicy Bypass .\install-git.ps1

エラーログが出なければ問題なく Git for Windowsのインストール完了

インストールの確認 (コマンドラインの場合)

Dir 'C:\Program Files\Git\cmd\git.exe'でエラーが出なければインストール完了

> Dir 'C:\Program Files\Git\bin\git.exe'


    ディレクトリ: C:\Program Files\Git\bin


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        2022/05/09     13:28          45584 git.exe

(任意)PATHの追加

(追記)ローカルPCの環境変数 PATH が変更されます！ご注意ください！

> .\set-git-path.ps1

以上でインストール及び設定は完了です。

スクリプト解説

install-git.ps1

InnoSetup

Git for WindowsはInnoSetupというフリーのWindows向けインストーラーが使用されています

パラメータの詳細は Setup Command Line Parameters で確認できます

jrsoftware.org

/ALLUSERS はその通りWindows上の全部のユーザーにインストール
/VERYSILENT はダイアログなどを抑制
/Log xxx.log でログ出力
- 標準出力に直接ログを流し込めなかったため、一度ログファイルに落として最後に出力に流しています

/LOADINF

/LOADINF=git-for-windows.inf

オプションファイルの指定で、実質的にGit for Windowsのオプション指定方法になります

Gitのcommit時の改行にLFを指定 (CRLFOption)
Credential Managerの使用 (UseCredentialManager)
コマンドプロンプトでgitを使用可能にするかの指定 (PathOption)
etc...

手順で使用したファイルは git-for-windows.inf となります

後述の SAVEINF からオプションファイルを作成できます。

自分はインストーラーのスクリプト (install.iss) から割り出してました。。。

余談、git-for-windows.inf の方針

CLI特化
UNIX系と互換性を意識
- OpenSSHの使用
- LFOnly指定など
Credential Manager を有効化
- これがあるとGitHubとの連携が楽になります！ (別記事でいずれ紹介します！）
デフォルトブランチ名はmain (昨今の流れを汲み取って)
git LFS を有効化

/SAVEINF

/LOADINF=git-for-windows_save.inf

※install-git.ps1では非使用

今回は直接は使用していませんが、指定するとインストール時のオプションを確認可能です！

| Out-Null

コマンドの最後に | Out-Null を入れることで、インストール完了までコマンド終了待ちになります。
PowerShellだとメジャーなテクニックのようです。

余談、今回の調査で躓いたところ

PowerShellで変数に実行ファイルを仕込む場合は & ./$PackageFileのように記載
- &なしで ./$PackageFile とするとエラーになる
Set-ExecutionPolicy を実行しないと PowerShell上でps1ファイルが実行できない
オプションの探し方
- Foo.exe /? or Foo.exe /HELP などで確認できる場合があるようです
- Windowsのダイアログ出でるのでコピーできないなど面倒。。。
別ps1ファイルのfunctionをコールする方法

自分は元々UNIX系のエンジニアだったので、WindowsとPowerShellのコマンドライン化には結構手こずりました。
再現性のあるインフラの構築にはIaC (Infrastructure as Code) は欠かせないのですが、Windowsに慣れていないせいかほとんどPowerShell調査みたいになってしまいました。

雑感

前回の記事投稿から2ヶ月経ってしまいましたね。。。

しかも今回はXRと3DCGから程遠いCLIに関する記事に。

「3DCGとかUnityやる気あるの？」と思われた方もいらっしゃるかもしれませんが、ちゃんと普段は触ってます！
地味なことですが、再現性のある開発環境の構築方法は何かと便利だったりします。

また、Git for Windowsってインストールしておくと、UnityのPackage ManagerでGitHub経由のパッケージが取得しやすくなったり、
GitHubのHTTPS経由での連携が安定したりと、何気に非エンジニアの方にもメリットがあったりします！

さて、次回は「PowerShell7をコマンドラインからインストールする方法」にする予定です！

それでは～

【Unity, XR】Single Pass Instanced向けURP Render FeatureのTips 【2020.3, 2021.2】

2022-03-23T01:13:30+09:00

概要
追記
略語
動作環境
Tips Unity 2020
雑感

概要

UnityのUniversal Render Pipelineには Render Feature という描画処理を差し込む機能があります。
この Render Feature ですが、XRのSingle Pass Instanced 対応をする場合はクセがあります。

今回はそんなSingle Pass Instanced向けのRender FeatureのTipsを共有します。

追記

2022/03/27 「おまけ、IntermediateTextureMode.Alwaysの指定なしでも機能させる方法」項目を追加

略語

用語が長いので、以下では略語で紹介します。

用語	略語
Universal Render Pipeline	URP
Render Feature	RF
Single Pass Instanced	SPI
Render Texture	RT

動作環境

Unity 2020.3.30f1 + Universal RP 10.8.1
Unity 2021.2.16f1 + Universal RP 12.1.6

Tips Unity 2020

ポストエフェクトでは cmd.Blit は使用不可で cmd.DrawMesh を使用

詳細は以下のドキュメントに記載されています。

[email protected]/manual/renderer-features/how-to-fullscreen-blit-in-xr-spi.html">docs.unity3d.com

※以下、上記ドキュメントを「SPI Blit Example」と呼びます

NOTE: Do not use the cmd.Blit method in URP XR projects because that method has compatibility issues with the URP XR integration.

互換性の問題でSPIでは cmd.Blit は正しく機能しないようで、
もし、ポストエフェクト的なことを実施したい場合は cmd.DrawMesh + _CameraColorTarget から画面キャプチャを取得して Blit を実現します。

サンプルのColorBlitRenderFeature について

ちなみに SPI Blit Example の ColorBlitRenderFeature のサンプルは描画の緑成分を抽出するポストエフェクトになっています。

↓

(2021.2以降) SwapBufferはSPIでは実質的に使用不可

Unity 2021.2 ではRFでポストエフェクトを実装しやすいようにSwapBufferという機能が追加されています。

残念ながらSwapBufferはSPIでは使用できません。。。(もし使用できる場合は教えていただけるとありがたいです！！)。
原因はSwapBufferの処理が隠蔽されていること、SwapBufferを使用するBlitメソッドが cmd.Blit を使用するためです。

※SwapBufferについては以下の動画をご参照ください。

www.youtube.com

画面キャプチャは不透明オブジェクトのみ

さて、ポストエフェクトと言いましたが、URP + SPIにおいては欠点があります。

不透明オブジェクトの描画結果しか取得できません

これは、シェーダーに渡されるテクスチャの名前 (_CameraOpaqueTexture) の通り、
不透明オブジェクトのみ描画した画面キャプチャが渡されるためです。

↓

renderPassEvent = RenderPassEvent.BeforeRenderingPostProcessing の場合

renderPassEvent = RenderPassEvent.BeforeRenderingTransparents の場合

SwapBufferも使用できないため、残念ながらSPIでのポストエフェクトは透過オブジェクトを対象にできないなど制限が強いです。。。

完全な描画結果が取れない理由

SPIにおいて、スクリーン向けRTにアクセスする術がないためです。

ScriptableRenderer.GetCameraColorFrontBuffer が internalメソッドのためアクセスできない
(2021.2以降)SwapBuffer用のRTにアクセスできない

Unity 2021.2以降でのポストエフェクトにはIntermediateTextureMode.Alwaysの指定が必要

Unity2021.2から IntermediateTextureMode という設定項目が追加されました。

IntermediateTextureMode.Alwaysを指定しないとSPI Blit Exampleの ColorBlitRenderFeature は機能しません！

[email protected]/api/UnityEngine.Rendering.Universal.IntermediateTextureMode.html">docs.unity3d.com

名前の通り、中間テクスチャ(IntermediateTexture)を使用するかの指定になります。

IntermediateTextureMode.Alwaysの指定が必要な理由

指定していない場合は cmd.DrawMesh の描画先が中間テクスチャではなくスクリーンのRTに直接描画されるのですが、
その後、FinalBlitPassによってスクリーンのRTが上書きされてしまうためです。

以下のコードにIntermediateTextureModeによる条件分岐があります。 github.com

SPI Blit Example には、注意書きがないのでIntermediateTextureMode.Alwaysの指定を忘れると Unity 2021.2 では実質的に描画結果に現れません。

判明するまで数時間かかりました。。。一応Report投げときました。

ちなみに非SPI(Multi Pass) や NonXRではSwapBufferが使用可能なので問題になりません。

Unity 2020.3 以前での中間テクスチャ

Unity 2020.3 + Universal RP 10 では IntermediateTextureMode は有りませんが、
実は RF が Forward Rendererに1つでも追加されている場合に、中間テクスチャが自動で有効になっていたようです。

以下のコードの rendererFeatures.Count != 0 という判定からわかります。

github.com

おまけ、IntermediateTextureMode.Alwaysの指定なしでも機能させる方法

※IntermediateTextureMode.Alwaysを指定する方が確実と思われますが、一応紹介します。

SPI Blit ExampleのColorBlitPassを以下のようにrenderingData.cameraData.renderer.cameraColorTargetを指定することで、 IntermediateTextureMode.Alwaysを指定していない場合でも機能させることができます。

--- a/Assets/ColorBlitPass.cs
+++ b/Assets/ColorBlitPass.cs
@@ -34,7 +34,7 @@ internal class ColorBlitPass : ScriptableRenderPass
         using (new ProfilingScope(cmd, m_ProfilingSampler))
         {
             m_Material.SetFloat("_Intensity", m_Intensity);
-            cmd.SetRenderTarget(new RenderTargetIdentifier(m_CameraColorTarget, 0, CubemapFace.Unknown, -1));
+            cmd.SetRenderTarget(new RenderTargetIdentifier(renderingData.cameraData.renderer.cameraColorTarget, 0, CubemapFace.Unknown, -1));
             //The RenderingUtils.fullscreenMesh argument specifies that the mesh to draw is a quad.
             cmd.DrawMesh(RenderingUtils.fullscreenMesh, Matrix4x4.identity, m_Material);
         }

IntermediateTextureMode.Alwaysの指定なしでも機能する理由

renderingData.cameraData.renderer.cameraColorTargetは基本的に中間テクスチャとなっているため
- 以下のコードを読む限りcreateColorTextureがtrueの場合に中間テクスチャが描画先にになるのですが、スクリーン(非SceneView)向け描画は基本的にtrueになるみたいです

github.com

createColorTexture == falseになる(中間テクスチャを描画先にしない)パターンのほうが珍しいですが、
SPIの場合で中間テクスチャを描画先にする場合は、renderingData.cameraData.renderer.cameraColorTargetを使用するならIntermediateTextureMode.Alwaysを指定する方が確実だと思います。

URP + SPI で可能な表現の例

不透明オブジェクトの描画結果を使用したポストエフェクト

透明オブジェクトは対象にできませんが、不透明オブジェクトならポストエフェクトをかけることができます。

アルファブレンドによるフェードイン・フェードアウト

シェーダーのアルファブレンドは問題なく使用できるため、フェードイン・フェードアウトは実現できます。

            Blend SrcAlpha OneMinusSrcAlpha
...
            half4 frag (Varyings input) : SV_Target
            {
                UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(input);
                return half4(0, 0, 0, saturate(_Intensity));
            }

Single Pass Instanced向けURP RenderFeatureでアルファブレンドが機能することの確認 pic.twitter.com/RH3MDPJwq2
— すぎしー (@tsgcpp) 2022年3月22日

雑感

なんとか3月中に1つ記事が書けました！本当はAddressablesに関する記事を書いていたんですが、検証の自動テストがGameCIで実現できず。。。

Unity2020でRFを使用すると中間テクスチャが必ず使用されるようになるのも知るきっかけになってよかったです（RF使用する場合のパフォーマンスの懸念自体は増えましたが）。

世間は卒業シーズン、新卒入社で新生活を始める人も多そうですね。これからUnity、XR始める人にも興味を持っていただければ幸いです！

それでは～

【Moq】Moqはメソッドチェーンでまるごとモック化できるよ

2022-03-09T00:58:42+09:00

メソッドチェーンのモック化
- 何が起こっているの？
- Setupで指定しない場合はdefault
検証コード
雑感

メソッドチェーンのモック化

IFoo -> IBar -> IBaz のようにinterfaceのプロパティが連結されている場合、以下の2つのモック化は同等になります。

            // setup
            var fooMock = new Mock<IFoo>();
            var barMock = new Mock<IBar>();
            var bazMock = new Mock<IBaz>();

            // when
            fooMock.Setup(m => m.Bar).Returns(barMock.Object);
            barMock.Setup(m => m.Baz).Returns(bazMock.Object);
            bazMock.Setup(m => m.Message).Returns("Hello Redundant");

            // then
            IFoo target = fooMock.Object;
            Assert.That(target.Bar.Baz.Message, Is.EqualTo("Hello Redundant"));
            Assert.That(target.Bar.Baz, Is.Not.Null);

↓

            // setup
            var fooMock = new Mock<IFoo>();

            // when
            fooMock.Setup(m => m.Bar.Baz.Message).Returns("Hello Chain");

            // then
            IFoo target = fooMock.Object;
            Assert.That(target.Bar.Baz.Message, Is.EqualTo("Hello Chain"));

上部(以後Aパターン)のようにわざわざ、IFoo, IBar, IBazのMockを作る必要はなく、

下部(以後Bパターン)の fooMock.Setup(m => m.Bar.Baz.Message).Returns("Hello Chain"); のようにIFooからメソッドチェーンでまとめてモック化してくれるという話でした。

何が起こっているの？

どうやらAパターンの宣言でBパターンと同等になるようです。

後で検証コードを記載しますが、
target.Bar に Mock<IBar>.Object, target.Bar.BazにMock<IBaz>.Objectのインスタンスが割り当てられていました。

Setupで指定しない場合はdefault

以下の用にSetupを実施しない場合はdefault、つまりnullを返します。

            // setup
            var fooMock = new Mock<IFoo>();

            // when
            // fooMock.Setup(m => m.Bar.Baz.Message).Returns("Hello Chain");

            // then
            IFoo target = fooMock.Object;
            Assert.That(() => target.Bar.Baz.Message, Throws.TypeOf<NullReferenceException>());

検証コード

NUnitで検証
IFoo, IBar, IBaz のinterfaceも定義

github.com

雑感

Moqを使ったことない同僚の方に、自分のコードを参考にMoqを使ってもらったら、
上記のようにメソッドチェーンでまるごとモック化する使い方をされていて発覚しました。

Moq使いだして2年以上、全然気づきませんでした。。。先入観って怖いですね(笑)。

それでは～

【Unity, VSCode】Visual Studio Code Editor 1.2.5 への更新のススメ

2022-02-12T19:54:18+09:00

概要
対象Unity
1.2.4の問題
1.2.5のススメ
雑感

概要

Visual Studio Code Editor 1.2.5 が 02/09 (日本だと2/10) に公開されたため、 1.2.4の問題と合わせて、1.2.5を紹介したいと思います。

今回はVSCode愛用者向けの記事となります。

対象Unity

Unity 2020 or later
Unity 2021 or later

1.2.4の問題

Windowsの場合に Package Manager経由で取り込んだ(Packages/ 以下の)ソースコードへの参照が機能しないバグがあったこと！

github.com

Find All Referencesなどでinterfaceや実装の確認もできず、コードのSuggestionも機能しないため、 VSCodeユーザーにとって、コーディングの効率を損なう問題がありました。。。

一応、1.2.3 にダウングレードすれば上記問題は回避はできましたが、
ただ、最新のUnity2020とUnity2021では標準で1.2.4がインストールされるため、煩わしさがありました。

ちなみにですが、1.2.4は 2021/09/01 にリリースされたので5ヶ月は放置されていた問題になります。。。

1.2.5のススメ

っということで結論として1.2.5へ更新しましょう！

ちゃんとWindowsで参照の問題が解決されていました。

パッケージ更新後は Preferences -> External Tools -> Regenerate project files を忘れずに！

ちなみに以下のプルリクが問題の修正箇所です。

github.com

この1行の修正を5ヶ月待ったことになります。。。

雑感

今Addressablesに関する記事を書いているんですが、資料をまとめるのに時間がかかりそうなので、1つ軽めの記事を書いてみました。

多分、この記事のタイトル見て「さっさとRiderにしたら？」って思った方もいらっしゃるかもですね。

正直VSCodeに出会ってから、VSCodeの魅力に取りつかれて手放せなくなっています。

ちなみに僕のVSCodeを主な用途は以下です。

Unity含むC#のコーディングとデバッグ
テキストファイル(mdなど)の編集
GitHub Actionsのymlファイル作成
BlenderのAddon(Python)作成

特にBlenderのアドオンの作りやすさは感動を覚えるレベルです！

もちろん、豊富なアドオンがあることも理由の一つですね。

そんなVSCodeですが、Unityでのバグが数ヶ月放置されていたのでやっと解消されてホッとしてます。

みなさんも、良いVSCodeライフを！

それでは～

【Unity】TransparentシェーダーレンダリングTips (RenderQueue編)

2021-12-27T23:56:52+09:00

概要
動作環境
検証対象のTransparentシェーダー
Transparentシェーダーの特徴
Transparentシェーダーパフォーマンス
サンプルプロジェクト
雑感

概要

UnityにおけるTransparentシェーダー(透過シェーダー)に関するTipsです。

Transparentシェーダーは3DCGにおいてよく使われる一方で昔から非常に悩ましい存在であったりします。
特に描画順の関係で思ったような絵にならなかったというのはよくあるパターンだと思います。

Unityでの透過オブジェクトを利用する場合の参考にしていただければと思います。

動作環境

Windows 10
Unity 2021.2.6f1
Universal RP 12.1.2

検証対象のTransparentシェーダー

Shader Graphを使用
_Color プロパティのみを持ち、アルファも使用

Transparentシェーダーの特徴

アルファブレンドの場合、描画の順番で結果が異なる

デフォルトのブレンド設定であるアルファブレンド(Blending Mode が Alpha)の場合、オブジェクトの描画順で結果が異なります。

アルファ0.4の赤と緑のシェーダーを使ったオブジェクトを描画順を変えて見てみましょう。

緑 -> 赤

赤 -> 緑

上記のように描画順で描画結果が異なります。

Transparentシェーダーはアルファブレンドの場合に描画順で結果が変わるということを覚えておきましょう！
基本的なことですが、とても重要な性質になります。

アルファブレンドは描画順で結果が変わる理由

簡単に説明するとアルファブレンドの計算式のためです。

R * a + G * (1 - a) => 0.4R + 0.6G (緑 -> 赤の順番)

G * a + R * (1 - a) => 0.6R + 0.4G (赤 -> 緑の順番)

※上記はイメージのための計算式で実際は R * Ra + (G * Ga + Dest * (1 - Ga)) * (1 - Ra) のような計算

加算ブレンドのみの場合、描画の順番に関わらず結果が同じ

加算ブレンド(Blending Mode が Additive)のマテリアル同士の場合は描画順に関わらず結果が同じになります。
加算ブレンドのみの場合ということに注意してください。

アルファの乗算色を単純に加算するため、計算の順番で結果が変わらないからです。

R * Ra + G * Ga(緑 -> 赤の順番) = G * Ga + R * Ra(赤 -> 緑の順番)
* Ra: 赤のアルファ値, Ga: 緑のアルファ値

RenderQueueが2501以上の場合、ソートが発生

RenderQueue 2501以上かつ同一のRenderQueueの場合はカメラから遠いオブジェクトから近いオブジェクトの順番で描画する処理が発生します。

透明オブジェクトはカメラから遠いオブジェクトから近いオブジェクトの順番で描画したほうが結果が安定します。
Unityはデフォルトでソートを実施して、遠->近の順番でオブジェクトを描画してくれています。

UnityのTransparentシェーダー + BlendingMode AlphaでRenderQueueを変えたときの描画結果 pic.twitter.com/PjsRwgjHBz
— すぎしー (@tsgcpp) 2021年12月26日

※どちらもアルファは1.0

ポイントは以下です。

RenderQueue 2501以上かつ同一のRenderQueueのマテリアルを持つRendererが複数ある場合はソートが発生
- カメラから見て遠いオブジェクトから近いオブジェクトの順番で描画
- ソートの基準位置はオブジェクトのTransformのposition (オブジェクトのピボット)
異なるRenderQueueのマテリアル間ではソートは発生しない
- 異なる場合はRenderQueueが小 -> 大の順番で描画
RenderQueue 2500以下の場合はソートは発生しない
- 不透明オブジェクトはデプステストにより基本的に描画結果が安定するため

TransparencySortMode の説明にも以下のように記載されています。

By default, perspective cameras sort objects based on distance from camera position to the object center;

おまけ1: BlendingMode Additiveの場合

描画順に関わらず結果が一定になります。

BlendingMode Additive の場合。ずっと同じ pic.twitter.com/u7BRj6ph5I
— すぎしー (@tsgcpp) 2021年12月26日

※どちらもアルファは1.0

おまけ2: 赤がAlpha, 緑がAdditiveの場合

全体がAdditiveではない場合は結果が不安定になります。

マテリアルにBlendingMode Alphaが存在する場合はRenderQueueを意識する必要があります。

おまけ、赤がAlphaで緑がAdditiveの場合 pic.twitter.com/HQyGzn35lV
— すぎしー (@tsgcpp) 2021年12月26日

※どちらもアルファは1.0

デプス (深度) を通常は書き込まない

Transparentシェーダーはデプスを書き込まないように設定することが一般的です。
こちらも描画順で結果が不安定になるためです。

Transparentシェーダーはデフォルト(Depth Write: Auto)の場合はデプスを書き込まない
意図的に書き込むことは可能
- ZWrite On (Depth Write: ForceEnabled) をシェーダー or マテリアルで指定

デプスを書き込まない場合と書き込む場合との違い

例えば以下のようにオブジェクトを配置した場合を見てみましょう。

赤Cubeと緑Sphereを重なるように配置
両マテリアルのアルファは0.4
両マテリアルのRenderQueueは3000
緑Sphereのほうがカメラに近い
- 遠い赤Cube -> 近い緑Sphereの順番で描画

デプスを書き込まない場合

デプスを書き込む場合

デプスを書き込んだ場合、重なった部分の緑側が描画されていません。
これは赤 -> 緑と描画されて、赤側でデプスが書き込まれたため後続の緑側の深度テストによりピクセルシェーダーがスキップされたためです。

意図的にこちらの現象を利用することもありますが、基本的にはTransparentシェーダーはデプスを書き込まないのが一般的です。

Transparentシェーダーパフォーマンス

※本記事では詳しくは取り上げません。

ここまで読んだ方の中にはパフォーマンス面が気になった方もいらっしゃるかもしれません。
Transparentシェーダーはピクセルシェーダー処理が発生しやすい性質上、パフォーマンス面で注意が必要です。

簡単に言えばオーバードローという現象が確実に発生するようなものです。
安易にUIやパーティクルなどで使用すると描画負荷が一気に上がりますためご注意ください！

また、ソート処理も発生するためCPU側にも影響があると考えられます。

パフォーマンスに関しては別の機会に取り上げようと思います。

サンプルプロジェクト

github.com

雑感

今年最後の技術ブログになります。
今回は自分の復習も兼ねて3DCGっぽい記事にしてみました。

というかここ数ヶ月、3DCGっぽくない記事が多かったですね。。。

昔のUnityでは透明マテリアルはRenderQueue 2450だった気がしますが、いつの間にか3000になってましたね。
パフォーマンス面については別の機会に紹介しようとは思いますが、いつになることやら。。。

Unity 2021.2ではShader Graphに Allow Material Override でBlending Modeを切り替えれたり、URPでVFXが使えたりと2020.3と比べて一気に使いやすさが上がっている気がしています。

そういえば、サンプルプロジェクトにTimelineでマテリアルをいじる簡易的なカスタムTrackも入れているので良かったら参考にどうぞ(Preview機能とか色々微妙ですが)。

来年もUnityを追求していきたいです！

それでは、良いお年を～

【Unity C#】 IReadOnlyListとアロケーション

2021-11-21T00:19:27+09:00

概要
環境
IReadOnlyList のアロケーション発生ポイント
Unity Test Runnerによるアロケーション確認
サンプルコード
- 追記
参考
雑感

概要

今回はIReadOnlyListとアロケーションについて深堀りしようと思います。

前回の記事でも述べましたが、IReadOnlyListはアロケーションを回避したい場合は注意が必要なinterfaceになっていたりします。
そんなIReadOnlyListのアロケーションについて調べたので共有します。

IReadOnlyListについては前回の記事で少し紹介していますので合わせてどうぞ！

tsgcpp.hateblo.jp

環境

Unity 2021.2.2f1
Mono
.Net Framework (API Comptibility Level)

IReadOnlyList のアロケーション発生ポイント

foreach使用時などのIEnumerable.GetEnumerator

ListをIReadOnlyList に変換してforeachに回すと使用するたびにアロケーションが発生します。

        List<Foo> list = new List<Foo>();
        foreach (var item in list) { }  // アロケーションは発生しない

        IReadOnlyList<Foo> readonlyList = list;
        foreach (var item in readonlyList) { }  // アロケーションが発生する

アロケーションの原因

Listの場合はEnumerable(値型)のboxingが原因です。

        public Enumerator GetEnumerator() {
            return new Enumerator(this);
        }

list.cs,569 より

ListのGetEnumeratorが返すEnumerableは値型のため、Listを直接使用する場合はアロケーションは発生しません。

一方で、IReadOnlyListに変換した場合のGetEnumeratorはIEnumerableとしてEnumerableを返します。

        IEnumerator<T> IEnumerable<T>.GetEnumerator() {
            return new Enumerator(this);
        }

list.cs,574 より

この戻り値のEnumerableからIEnumerableは値型から参照型への変換、つまりboxingが発生するためアロケーションが発生します。

アロケーションの回避方法

foreach ではなく for を使用すれば回避可能です。

        for (int i = 0; i < readonlyList.Count; ++i)
        {
            var item = readonlyList[i];
        }

IEnumerableと異なりIReadOnlyListはlist[i]が配列の要素に直接アクセスする形となっています。

list.cs,1107

ListをIEnumerable(or IReadOnlyCollection)に変換してしまうとforが使用不可でGetEnumeratorによるアロケーションは避けられなくなりますが　 IReadOnlyListへの変換であれば読込専用を保ちつつforが使用可能なため結果的にアロケーションの回避が可能です。

コーディングの煩わしさはありますが、メモリ的には優しくなります。

IEquatable<T>を実装しない値型(struct)でEquals

IEquatable<T>を継承していない値型はEqualsの挙動によりアロケーションが発生するパターンが多いです。

IReadOnlyListとは直接は関係ありませんが、後述するLinq.Enumerable.Containsに関わってくるため紹介します。

    public struct SimpleData
    {
        public int value;
    }

アロケーションの原因

C#の型に定義されているValueType.Equals(Object)は引数にobject型を受け取ります。

docs.microsoft.com

つまり、このEqualsに値型を渡すと値型から参照型への変換でboxingが発生しアロケーションに繋がります。

アロケーションの回避方法

主に2つあります。

structにIEquatable<T>を継承して実装
- Equals(T value)で型指定となるためboxingが発生しない
IEqualityComparer<T>を継承したオブジェクトを実装して使用
- Equals(T x, T y)で型指定となるためboxingが発生しない

    public struct EquatableData : IEquatable<EquatableData>
    {
        public int value;

        public bool Equals(EquatableData other)
        {
            return this.value == other.value;
        }
        ...
    }

IReadOnlyListでLinq.Enumerable.Contains

using System.Linq;
...
        readonlyList.Contains(item);

IReadOnlyListは残念ながらContainsメソッドを持っていません(List.Containsは定義されている)。
拡張メソッドLinq.Enumerable.Containsを使用することで同様の機能を使用できます。

しかし、Linq.Enumerable.Containsはアロケーションが発生するパターンが多いです。

docs.microsoft.com

アロケーションの回避方法

Linq.Enumerable.Contains のアロケーションは細かい話が多いため先に回避方法を紹介します。
これに関してはIReadOnlyList向けのContainsを実装する必要がありました。

github.com

後述する「アロケーションの原因」をアロケーション回避の検証も含めUnitTestも作成しています。

余談ですが、汎用性を保つためwhere T : structのような制約は入れていません。
その代わりtypeof(T).IsValueTypeによる条件分岐が入っています。

アロケーションの原因

共変性変換のIReadOnlyListに対してLinq.Enumerable.Contains

「共変性を使用したIReadOnlyList」とは要するにList<Foo> -> IReadOnlyList<IFoo>みたいな変換のことです。共変性については前回の記事を参照。

ポイントは共変性を利用して変換したIReadOnlyList にあります。

実は List<Foo> -> IReadOnlyList<Foo> のように不変(TをFooのまま変換)の場合はアロケーションは発生しません。
共変性変換の場合にアロケーションが発生する要因はLinq.Enumerable.Containsの定義にあります。

       public static bool Contains<TSource>(this IEnumerable<TSource> source, TSource value) {
            ICollection<TSource> collection = source as ICollection<TSource>;  // ICollectionは不変性のため、IReadOnlyList<IFoo>へのキャストは不可のためnullを返す
            if (collection != null) return collection.Contains(value);
            return Contains<TSource>(source, value, null);
        }
 
        public static bool Contains<TSource>(this IEnumerable<TSource> source, TSource value, IEqualityComparer<TSource> comparer)
        {
            if (comparer == null) comparer = EqualityComparer<TSource>.Default;
            if (source == null) throw Error.ArgumentNull("source");
            foreach (TSource element in source)  // <- GetEnumerator使用によりboxingによるアロケーションが発生
                if (comparer.Equals(element, value)) return true;
            return false;
        }

Enumerable.cs,1364 より

ICollection<T>は共変性(out T)を持たず不変性のため、List<Foo> -> ICollection<IFoo>は不可となります。
よって IReadOnlyList<IFoo> -> ICollection<IFoo>の変換も不可のため、上記Containsのコードでsource as ICollection<TSource>はnullを返します。

その後foreachにたどり着き、「foreachなどIEnumerableを必要とする処理」で述べたアロケーションが発生します。

逆にIReadOnlyList<Foo>は不変性を満たすためICollection<Foo>にキャストができforeachに到達しないためアロケーションが発生しません。

なんともややこしい。。。

IEquatable<T>非継承のstructを型とするListでLinq.Enumerable.Contains

IEquatable<T>非継承のstructをLinq.Enumerable.Containsに使用した場合はアロケーションが発生します。

        private static EqualityComparer<T> CreateComparer() {
            ...

            if (typeof(IEquatable<T>).IsAssignableFrom(t)) {
                return (EqualityComparer<T>)RuntimeTypeHandle.CreateInstanceForAnotherGenericParameter((RuntimeType)typeof(GenericEqualityComparer<int>), t);
            }

            ...

            return new ObjectEqualityComparer<T>();
        }

equalitycomparer.cs,40 より

IEquatable<T>継承の場合は型指定のEqualityComparer<T>が生成されますが、
IEquatable<T>非継承の場合はObjectEqualityComparer<T>が使用されてboxingが発生するんですね。

IEqualityComparer<T>指定有りでLinq.Enumerable.Contains

Linq.Enumerable.Containsはオーバーロードで第2引数にIEqualityComparer<T>指定可能なメソッドがあります。
Equalsのboxingは回避できるんですが、残念ながらその後で使用されるforeachのboxingは回避できません。。。

Enumerable.cs,1370

「アロケーションの回避方法」にて記載したコードには、IEqualityComparer<T>指定可能なContainsも実装して記載しています。

Unity Test Runnerによるアロケーション確認

今回のアロケーション有無の検証ですがUnity Test Runnerを利用しました。

github.com

実装開始時はIs.AllocatingGCMemory()とIs.Not.AllocatingGCMemory()を使い分けていましたが、再利用性(TestBaseクラスからの派生)と視認性のためにIs.Not.AllocatingGCMemory()指定で統一しました。

以下の例だと✅でアロケーション発生無し、🚫でアロケーション発生有りという見方になります。
テストコード的にはおかしいですが、一旦視認性を重視しました(別の視認性が確保しやすい方法が思いついたら修正しておきます)。

また、1st, 2ndはインスタンスごとの初回と2回目でアロケーションの変化があるかを確認するために入れています。

List<Foo>

List<Foo> -> IReadOnlyList<Foo>

foreach のみで発生

List<Foo> -> IReadOnlyList<IFoo>

foreach および共変性変換のためLinq.Enumerable.Containsで発生

List<SimpleData> -> IReadOnlyList<SimpleData>

IEquatable非実装のstruct

List<EquatableData> -> IReadOnlyList<EquatableData>

IEquatable実装のstruct

サンプルコード

github.com

IReadOnlyList向けContainsなども含む

追記

Package Manager対応版を用意しました。

github.com

参考

雑感

世間ではFacebookからMetaへと社名変更、新しいOculusが発表、メタバースへの注目など、
XR界隈で目まぐるしい変化が来そうなときに、
「なんでXRとは程遠いC#の話してるの？」って言われそうですねｗ。

アプリケーションの楽しさに直接関連するものでは確かに有りませんが、
一方で快適なXRアプリケーションの実現において、過剰なアロケーションの回避や削減は大事な要素であると考えています。

もちろんUnityにおいて完全にアロケーションを避けることは難しいため、
こだわり過ぎず、避けれるなら避けるぐらいがちょうど良いのではと思います。

マニアックな話では有りましたが、少しでも面白いと思っていただけたなら幸いです。
それでは～

【Unity C#】 IReadOnlyListの紹介

2021-10-30T18:45:07+09:00

概要
IReadOnlyList について
- 注意事項
追記
Unityでの使用例
- MonoBehaviourやScriptableObjectを依存逆転の法則を当てはめて提供
関連
雑感

概要

今回の主役は IReadOnlyList です！

docs.microsoft.com

Listでもなく、IReadOnlyCollectionでもありません！

個人的には パフォーマンス と ポリモーフィズムを併せ持った良いinterfaceだと思っています。

しかし、アロケーションの発生を避けたいときにはなかなか注意が必要 な存在だったりします。。。
そんなIReadOnlyListを紹介していきたいと思います。

ちなみにアロケーションについては別記事にする予定です。

IReadOnlyList について

注意事項

ダウンキャスト (readonlyList as List<>など)は禁止という前提で説明
- ダウンキャストを許した場合は読込専用が簡単に崩壊するため

追記

2022/02/25

「Unityでの使用例」で共変性を利用したアップキャストになるようにコード例を修正

2022/02/26

「【Unity C#】 IReadOnlyListとアロケーション」へのリンクを追加

IReadOnlyListは読込専用のList

名前の通り 読込専用のList 向けinterface
- 標準配列(Array)やListなどが継承している
各要素の変更が不可になっており list[0] = default などはコンパイルエラーとなる
主な利用用途は変更不可のListとして提供したいときなど

    [Tooltip("ラベル一覧")]
    [SerializeField] private List<string> _labelList;

    // 読込専用としてラベル一覧をクラス外に提供
    public IReadOnlyList<string> LabelList => _labelList;

C#標準の一次元配列はIReadOnlyListにキャスト可能

        string[] strList = new string[] { "foo", "bar", "baz" };
        IReadOnlyList<string> readonlyStrList = strList;

公式ドキュメントにも「一次元配列は IList<T> と IEnumerable<T> を実装している」と明記されている
- Single-dimensional arrays also implement IList<T> and IEnumerable<T>.

docs.microsoft.com

IReadOnlyCollectionとの違いは index指定で要素にアクセスが可能なこと

list[i]がList同様に使用可能
そもそもT this[int index] { get; }の定義は IReadOnlyList由来
IReadOnlyCollectionと異なりindexさえわかれば O(1)の計算量でアクセス可能

※個人的にパフォーマンス的観点で有効性を感じるところ

IReadOnlyListのTに値型を宣言すれば要素含め読込専用となる

    [SerializeField] private List<Vector3> _vectorList;
    public IReadOnlyList<Vector3> VectorList => _vectorList;

上記のようにTが値型でIReadOnlyListに変換した場合は完全な読込専用として提供される

IReadOnlyListは参照型の要素を読込専用にはしない

IReadOnlyListはあくまでList自体の変更を不可にしたもので、要素本体はT型に従う
- 要素の方がGameObjectの場合は引き続きnameやtransformを変更することは可能

        IReadOnlyList<GameObject> readonlyObjectList = new List<GameObject> { ... };
        readonlyObjectList[0].name = "Renamed_" + readonlyObjectList[0].name;

但し、後述する共変性を利用することで参照型の要素本体も読込専用としての提供も可能

IReadOnlyList<out T>のため共変性持つ

public interface IReadOnlyList<out T> : System.Collections.Generic.IEnumerable<out T>, System.Collections.Generic.IReadOnlyCollection<out T>

上記のように out T で宣言されているため、IReadOnlyListは共変性がある

例えば以下のような参照型クラスFoo、interface INameHolder があったとする。

public interface INameHolder
{
    string Name { get; }
}

public class Foo : INameHolder
{
    public string Name { get; set; } = "Default Name";
}

上記Foo使ったList<Foo>は共変性を使って以下のような変換が可能。

        IReadOnlyList<INameHolder> readonlyNameHolderList = new List<Foo> { ... };

        // コンパイルエラー(INameHolderはget_Nameのみ提供のため)
        readonlyNameHolderList[1].Name = "Melon";

readonlyの継承型として提供することで参照型要素もreadonlyとして提供可能。

Unityでの使用例

MonoBehaviourやScriptableObjectを依存逆転の法則を当てはめて提供

Unityとは疎結合にしたまま、Unityの機能を利用した読込専用データ群を配布に利用するなど

※以下はあくまで実装イメージ

[CreateAssetMenu(fileName = nameof(ScriptableObjectNameHolder), menuName = "ScriptableObjects/" + nameof(ScriptableObjectNameHolder), order = 1)]
public sealed class ScriptableObjectNameHolder : ScriptableObject, INameHolder
{
    [SerializeField] private string _name;

    // ScriptableObject側で定義された名前を読込専用として提供
    public string Name => _name;
}

以下の様に List<ScriptableObjectNameHolder> から IReadOnlyList<INameHolder> に変換し、Unityとは疎結合なインスタンス公開が可能。

    [SerializeField] private List<ScriptableObjectNameHolder> _nameHolders;

    // 共変性を利用してUnityの存在を隠蔽し、読み込み専用として公開
    public IReadOnlyList<INameHolder> NameHolders => _nameHolders;

インスタンスの公開はExtenjectやVContainerなどを利用することが多いですが詳細は割愛。

雑感

久々の投稿です。
最近、環境が変わって色々ドタバタしていました。

世間ではFacebookのMetaへ社名変更、新しいQuestが発表、メタバースへの注目など、
XR界隈で目まぐるしい変化が来そうなときに、
「なんでC#の話してるの？」って言われそうですねｗ。

IReadOnlyListはUnityでの開発でも結構役立つことが多いと感じています。
DI, SOLID原則, テスタビリティ, etc...

ちなみに今回の記事は前座で本題は次回の「IReadOnlyListのアロケーション(関連にリンク)」だったりします！
なんでアロケーションなんかを調べたのかは次回にお話できればと思います。

それでは～

【Extenject】Composite Installer を紹介！

2021-08-15T13:10:29+09:00

概要
Compsote Installer について
- Compositeパターン
- Compsote Installer の活用術
Compsote Installer の使い方
Composite Installer 開発小話
Composite Installerを試したい場合
クレジット
雑感

概要

今回は Extenject に追加された Compsote Installer について紹介します！

github.com

ちなみにPullRequestを出したのは私です（欲しかったので）。

github.com

まだComposite Installerが同梱されているリリースバージョンはありませんが、せっかくなので活用方法と、ついでにマージされるまでの小話について記事にしようと思います。

記事の最後にunitypackageとタグへのリンクを記載していますので、使ってみたいと思った方はご利用ください！

今回の記事は Extenject にある程度慣れている方向けの内容です。

Compsote Installer について

Composite Installer とは Compositeパターンを使った Extenject のInstaller です。

Compositeパターン

Extenject観点で説明しますと、 Composite InstallerをDIContainerに登録するだけで、そのComposite Installerに登録されているすべてのInstallerで InstallBindings()が実施されます。

また、Composite Installer に別のComposite Installer を登録することも可能です。

Compositeパターンはメジャーなデザインパターンのため、解説記事もたくさんあります。
詳しくは検索してみてください。

Compsote Installer の活用術

1. 再利用可能なInstallerグループを作成可能

Compositeパターンの通り複数のInstallerを1つのComposite Installerにグループとして集約することで、再利用性のあるInstallerとしての管理が可能になります。

機能ごとにInstallerのグループとして管理
機能ごとにComposite Installerを作成しシーンごとに取捨選択して利用

Extenjectを利用してかつ Pure C# が増えてくると比例してInstallerクラスも増えてくると思いますが、
そんなときに目的や機能ごとにComposite InstallerにInstallerグループを分割登録して管理すると良いと思います！

2. 疎結合Installer, 抽象Installerとして活用

特定のInstallerの前にComposite Installerをレイヤーとして設けることで、ContextとInstaller間を疎結合化することができます。

特定のInstallerに依存しない形で各Contextに登録可能
ContextのPrefabを編集することなく登録Installer群を変更可能

特にComposite Scriptable Object Installerはオススメです！

ContextはアセットをGUID経由で取り込む形になるため、
特定の機能にInstallerを追加したい場合はContextを編集せずComposite Scriptable Object Installerアセットに新しいInstallerを登録するだけで済みます。

3. 特定の機能提供向けInstallerとして配布

複数のチームでExtenjectを利用している場合の連携に活用できると思います。

特定の機能を集約したComposite Installerをパッケージに含めて共有可能
Composite Installerへの修正やInstaller追加もパッケージの更新のみで配布先に反映することが可能

Compsote Installer の使い方

以下にドキュメントページがあります。
こちらも私の方で作成して一緒にPullRequestに出しました(ガバガバな英語で恐縮ですが）。

CompositeInstaller.md

せっかくなので、簡単にではありますが日本語でも使い方を紹介します。

CompositeMonoInstaller

名前の通り MonoInstaller の Compositeパターン版です。

コンポーネントはすでにExtenjectの中に含まれていますので、他のMonoBehaviourと同様にAdd Component可能です。

また、Prefab化することで Prefab Installerとしても利用することができます。

CompositeScriptableObjectInstaller

名前の通り ScriptableObjectInstaller の Compositeパターン版です。

Create -> Zenject -> Composite Scriptable Object Installer をクリックすることで作成可能です。

先程も述べましたが、個人的には ScriptableObjectInstaller をよく使うので特にオススメしたいです！

FYI: 循環参照の検知

Compositeパターンは性質上、循環参照ができてしまいます(詳細は後述)。
指定ミスによるヒューマンエラーを回避するために、循環参照を検知したときはInspector上のプロパティが赤くなるEditorも用意しました。

ちなみにこの状態で起動すると例外(ZenjectException)が飛びます。

Composite Installer 開発小話

標準搭載化

ありがたいことにPullRequestを出したところ、CollaboratorのMathijs-Bakkerさんに「標準的な機能になるから標準フォルダに移動してもいいんじゃないか？」とコメントをいただけました。

実質的に標準搭載化となったため追加修正を加えた上でマージされることになりました。
そのおかげで5日ぐらいは修正に費やすことになりましたけど、正直に嬉しかったのでモチベは高かったですw。

「プルリクって普通標準搭載になるもんじゃないの？」って思われた方もいるかもしれないので補足すると、
Extenject (Zenject) には OptionalExtras というオプション的機能を詰め込んだフォルダがあります。
当初はこちらに拡張機能としてComposite InstallerのPullRequestを出していたのですが、上記のようなご提案をいただけたため標準搭載となりました。

みなさんの開発の手助けになれば嬉しいです。

そういえば、PullRequestですがmergeじゃなくてrebaseで取り込まれたのは若干気になりました。
ソースコード自体はそのまま取り込まれたので問題ないと思いますけど。

循環参照対策

Compositeパターンは循環参照に注意する必要があることを知っていたので、循環参照対策も主に2つ入れています。

循環参照があるComposite Installer があった場合は例外を出す
エディタ上で循環参照を検知したらInspectorに赤く表示する

こちらを導入するに当たり循環参照の検証処理も少し工夫したので共有します。

循環参照が起こるケース

Compositeパターンにおける循環参照は以下のケースがあります。

自分自身への参照を持つ場合

葉要素(子孫)が自身への参照を持つ場合
- 以下の例では Self と Leaf06 で循環参照

葉要素(子孫)同士が循環参照している場合
- 以下の例では Leaf06 と Leaf07 が互いに循環参照

循環参照の検証方法

以下の手順で行います

葉要素がCompositeではないこと
- Compositeパターンの葉要素は元となったinterfaceなのでダウンキャスト(as)でCompositeかどうかの判定が必要
葉要素がCompositeである場合は自身でないこと
自身ではない場合は先祖一覧の中に子要素がないこと
自身を先祖一覧に登録
先祖一覧を用いて子要素すべてで同様の検証を実施

上記をComposite Installer の子要素が見つからなくなるまで行うことで循環参照を検知することができます。

先祖一覧を記録しながら探索することになるため、可変Listが必要になります。

また、デザインパターンなどを考慮するとダウンキャストはアンチパターンになり得ますが、
今回は広く利用されることを想定し循環参照問題の回避を優先してダウンキャスト込みの検証方法にしました。

ちなみに検証コードは以下となります。

CompositeInstallerExtensions.cs

検証処理のアロケーションの削減

私は余計なアロケーションは極力避けたい性質なので、アロケーションをなくしたい欲が出ました。
一応、RuntimeだけでなくEditor上でもInspectorの更新毎に検証処理が動いてしまうため、ある程度アロケーションを回避したかったという理由もあります。

結論を述べますと 4連結までの検証はアロケーションが回避される ようになっています。

やり方は単純で先祖1つ、先祖2つ、先祖3つ、先祖4つで検証するメソッドを用意して連結するテクニック（つまり面倒くさいやり方）で対応しました！
見たほうが説明が早いと思いますので以下のコードを御覧ください。

CompositeInstallerExtensions.ValidateAsComposite

4連結まで対応したのは「多くても3連結ぐらいかな？」と思ったためです。

4連結以上の場合はアロケーションが発生しますので、「いやもうちょっとアロケーション発生しないようにしたい」って人は上記のコードを参考にPullRequestを出してください。

もちろん、テスト (TestCompositeInstallerExtensions) も追加してあげてください！

stackallocとかいうunsafeコードを使うことも一瞬考えたけど流石にすぐ却下しましたｗ

余談: 循環参照対策なしの場合

循環参照のあるComposite Installerに対してInstallBindingsをコールした場合、以下の現象が発生しました。

PlayではStackOverflowException or エディタ自体が落ちる
- どちらになるかはPlay毎に異なり、StackOverflowException 確定ではありませんでした
Zenject Validate では落ちることなくフリーズし、エディタが入力を一切受け付けなくなる

どちらにしてもInstallBindings の初めに検証(Assert)を入れる必要がありました。

アロケーション発生させたくないとか言ってられない！

そもそもなぜ作ろうとおもったのか

Installer群を一括でContextに登録する機能がほしかったから
- Installerが増えて管理しづらかったので
- 1つのInstallerクラス内にすべてのBind処理を書くと保守性が悪化するため避けたかった
開発におけるワークフローを考えてみたときにComposite Installerがあればいろいろと応用が効くと思ったから
- 具体的には「Compsote Installer の活用術」で述べた通りです

他に良さそうな活用方法があればぜひ教えて下さい！

Composite Installerを試したい場合

9.2.0 にrebaseでComposite Installerのcommitを取り込んだタグを用意しました。
もともと拡張として作成していたこともあってExtenjectの基本機能に変更はありません(Inspector表示用のEditorに少し変更が入ったぐらいです)。

metaファイルも同じなのでリリースバージョンが出てもCompositeMonoInstaller, CompositeScriptableObjectInstallerはそのまま使えると思います。
MITライセンスなので言う必要はないと思いますが、自己責任でお願いします！

github.com

フォークしたリポジトリ(tsgcpp上)にタグを登録していますが、本体にはすでに取り込まれている内容なためtsgcppの記名は不要です。

クレジット

draw.io @diagrams.net
- 図形の作成に利用させていただきました

雑感

まさかの3ヶ月ぶりの投稿です。。。
個人開発を優先していたらあっという間に月日が流れていました。

記事を書いた理由はそろそろ情報発信しないとなと思ったことと、
Extenjectを使ったワークフローの提案的なことをやってみたいと思ったからです。

Extenjectに限らずDIコンテナはゲームやアプリケーションを面白くするための仕組みではありませんが、
工夫次第で幅広いシステムに対応させることが可能になると思います。

UnityでSOLID原則などを取り入れる上でも欠かせない存在かな思いますので、ぜひ活用してください！

それでは～

【GitHub Packages for Unity】限定配布も可能, GitHub Packages で Unity アセット配布

2021-08-14T12:20:48+09:00

概要
記事内でのキーワード略称
GitHub Packages について
アップロードまでの流れ
UPM経由でのパッケージのインストール
GitHub PackageでUnityパッケージを配布するメリット
GitHub PackageでUnityパッケージを配布するデメリット
- Unity Package Manager のパッケージ検索機能が使用不可
- Packages以下で displayName で表示されない
GitHub Package を使用する場合の諸注意
サンプル
参考
雑感

概要

今回はUnity向けにGitHub Pakcagesでアセットを配布する方法を紹介します。

社内やチーム内でUnityのパッケージを限定配布できたりもするので、
良かったら活用してみてください！

記事の最後にサンプルを記載しています。

記事内でのキーワード略称

GitHub Packages -> GHP
GitHub Actions -> GHA
Unity Package Manager -> UPM

GitHub Packages について

簡単に言えば「パッケージ公開サービス」でGitHubから提供されています。

github.com

様々なパッケージ形式に対応

npm, gradle, docker container などあらゆるパッケージ形式に対応

docs.github.com

GitHubの仕組みでパッケージのアクセス権限を制御可能

リポジトリの Manage access がそのままパッケージにも適用
Privateリポジトリにパッケージを登録することで限定配布も可能

Publicは無料、Privateは従量課金制

Publicパッケージは無料で配布可能
Privateパッケージでも Free, Team, Enterpriseそれぞれにも無料枠有り
- ストレージ枠とデータ転送枠が使用されます
billing ページにて使用状況を確認可能
- Data transfer out がデータ転送枠

docs.github.com

GitHub Actions 経由でリポジトリからアップロード

Repository -> Actions -> Packages の流れでアップロード

今回は GHA での簡単なアップロード例を紹介します

アップロードまでの流れ

まずはパッケージをアップロードするまでを紹介します！

Package Manager形式でアセットを用意

UPM向けにアセットを用意
- アセット + package.json
meta ファイルも必ず生成
- UPMで必須、存在しないと取り込んだときエラー

サンプルコードにも簡単なパッケージ用アセットを4つ用意しています。

package.json の name について

nameの推奨文字は a-z0-9.-_ で大文字は非推奨
com.<org>.<name>(.<sub name>) のようにドメインを含めること推奨
- UPMで使用する際の Scoped Registries はドメイン部分でアクセス先を制御するため
- jp.co, jp.ne などでも可

com.tsgcpp.unitygithubpackageexample.integration
com.tsgcpp.tscubemapgenerator
jp.co.tsgcpp.groupname.categoryname

package.json について

publishConfig 項目が必須
- UserもしくはOrganizationの前には @ が必須
- すべて小文字 (アカウント名がSampleAccの場合は@sampleacc)
- パッケージをアップロード先として使用される
- 余談: GitHub上ではアカウント名は tsgcpp も TsGCpP も同じ扱い
unity 項目もUnity向けのため必須
それ以外は通常のUPMと同様
- Creating custom packages

"publishConfig": {
        "registry": "https://npm.pkg.github.com/@<user or organization>"
    }

サンプルの全体は以下となります

{
    "name": "com.tsgcpp.unitygithubpackageexample.integration",
    "version": "1.2.3",
    "displayName": "Integration Package Example",
    "description": "Integration Package Example for UnityGithubPackageExample",
    "unity": "2019.4",
    "keywords": [
        "tsgcpp",
        "main"
    ],
    "license": "UNLICENSED",
    "dependencies": {
        "com.tsgcpp.unitygithubpackageexample.script": "2.3.4",
        "com.tsgcpp.unitygithubpackageexample.prefab": "3.4.5"
    },
    "author": {
        "name": "tsgcpp",
        "url": "https://github.com/tsgcpp"
    },
    "scripts": {
        "test": "exit 0"
    },
    "repository": {
        "type": "git",
        "url": "git+https://github.com/tsgcpp/UnityGithubPackageExample.git"
    },
    "bugs": {
        "url": "https://github.com/tsgcpp/UnityGithubPackageExample/issues"
    },
    "publishConfig": {
        "registry": "https://npm.pkg.github.com/@tsgcpp"
    }
}

アップロード用アクションを定義

GHA の Yaml を定義
- サンプルでは .github/workflows/release-package.yml に定義
packagePath にパッケージの相対パスを指定(複数可)
actions/setup-node のstepは必須
npm publish でパッケージをアップロード

せっかくGHAを使うので、アップロード処理前にテストも組み込みましょう！

name: Unity Example Packages Publish

# release tagを発行時にアップロード
on:
  release:
    types: [created]

jobs:
  # Unity Test Runner の実行 (GameCIのunity-test-runnerを利用)
  test:
    name: Test in ${{ matrix.testMode }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        projectPath:
          - .
        unityVersion:
          - 2020.3.14f1
        testMode:
          - all
    steps:
      - uses: actions/checkout@v2
        with:
          lfs: true
      - uses: game-ci/unity-test-runner@v2
        id: tests
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          unityVersion: ${{ matrix.unityVersion }}
          projectPath: ${{ matrix.projectPath }}
          testMode: ${{ matrix.testMode }}
          artifactsPath: ${{ matrix.testMode }}-artifacts
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          checkName: ${{ matrix.testMode }} Test Results
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: Test results for ${{ matrix.testMode }}
          path: ${{ steps.tests.outputs.artifactsPath }}

  # アップロード処理の実施
  publish:
    needs: test
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        packagePath:
          - ./Assets/Plugins/Script
          - ./Assets/Plugins/Material
          - ./Assets/Plugins/Prefab
          - ./Assets/Plugins/Integration
    permissions:
      packages: write
      contents: read
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 12
          registry-url: https://npm.pkg.github.com/
      - run: npm publish ${{ matrix.packagePath }}
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

余談 .npmrc はUnityの場合は不要(node.jsプロジェクトではないため)

パッケージのアップロード

masterにアセット, package.json, GHAのYamlを追加
リポジトリの Releases ページの Draft a new release より release tag を発行
- release tagの発行がアクションのトリガーのため
アクションが正常に完了すると Packages に登録される
- 初回のみ反映されるまで若干時間がかかる可能性有り

サンプルリポジトリは記事の最後に記載しています。

UPM経由でのパッケージのインストール

次はアップロードされたパッケージのUPM経由でのインストール方法を紹介します！

アクセストークンの発行

アクセストークンはAPI経由などでGitHubのコンテンツにアクセスするためのトークンになります。

GHPのアクセスにはアクセストークンが必要
public, private にどちらでも必要

アクセストークンの注意点

発行する前にアクセストークンの注意点についてです。

トークンの発行はパッケージにアクセスする本人のアカウントで実施
発行したトークンは第三者へは非公開にし、基本的に本人のみ使用する
(任意)期限 (Expiration) を指定して定期的に更新 (セキュリティ観点)

GitHub上でアクセストークンを発行

Settings -> Developer Settings -> Personal access tokens のページに進む
- URL: https://github.com/settings/tokens
"Generate new tokens" のボタンをクリック

Note 項目に任意の名前を指定 (ex: Package Access)
(任意) 期限(Expiration)を設定
read:packages をチェック
- パッケージアクセスのみであれば read:packages のみで問題有りません

ページ下部の "Generate token" ボタンで発行
発行されたトークンをコピー
- ページを閉じると再確認できません！

.upmconfig.toml ファイルを作成

.upmconfig.toml は UPM におけるアクセス設定ファイル
- https://docs.unity3d.com/Manual/upm-config.html
- ファイルパスも上記ページの "User configuration file location" を参照
アクセス先(npmAuth)とそのアクセストークンを記載

[npmAuth."https://npm.pkg.github.com/@<user or organization>"]
token = "<ACCESS TOKEN>"
alwaysAuth = true

以下は記入イメージ

[npmAuth."https://npm.pkg.github.com/@tsgcpp"]
token = "ghp_hogehogehogehogehoge"
alwaysAuth = true

これでUnityのパッケージインストール時にアクセストークンが使用されます

Unity で Scoped Registries とインストールパッケージを設定

Packages/manifest.json をエディタで開く
scopedRegistries 項目に記載
- url には https://npm.pkg.github.com/@<user or organization>
- scopes にドメイン部分を記載

以下は記入例で、com.tsgcppとついたパッケージは GHP の @tsgcpp 経由で取得されます。

{
  "scopedRegistries": [
    {
      "name": "tsgcpp public",
      "url": "https://npm.pkg.github.com/@tsgcpp",
      "scopes": [
        "com.tsgcpp"
      ]
    }
  ],
  "dependencies": {
    "com.tsgcpp.unitygithubpackageexample.integration": "1.2.3",
    ...
  }
}

補足: com.tsgcpp.unitygithubpackageexample.integration (サンプルパッケージ) の依存グラフについて

今回 integration, script, prefab, material のパッケージは以下の依存関係
com.tsgcpp.unitygithubpackageexample.integration のみの取り込みで他3パッケージも取得

インストールの確認

Unityエディタ上で Packages 項目を確認しましょう

以上がGHP経由での取込までの流れとなります！

ちなみに紹介したとおりに .upmconfig.toml と manifest.json を設定すれば、
私が用意したサンプルパッケージ (public) が取り込まれます。

残りは GHP を使用する場合のメリット、デメリットを紹介します！

GitHub PackageでUnityパッケージを配布するメリット

package.json の dependencies に依存を定義可能

GHPにアップロードされたパッケージは dependencies 項目で依存パッケージを指定可能
UPMで取り込んだ場合は依存パッケージも合わせて取り込まれる
- Git URL 経由では難しかった依存パッケージの同時取込が可能

{
    "name": "com.tsgcpp.unitygithubpackageexample.integration",
    "version": "1.2.3",
    "displayName": "Integration Package Example",
    "description": "Integration Package Example for UnityGithubPackageExample",
    "unity": "2019.4",
    ...
    "dependencies": {
        "com.tsgcpp.unitygithubpackageexample.script": "2.3.4",
        "com.tsgcpp.unitygithubpackageexample.prefab": "3.4.5"
    },
    ...
}

Privateリポジトリでのパッケージ配布が容易

リポジトリにアクセス可能な人限定での配布も可能
GitHub向けのアクセストークンを利用することで実現

補足: Git URLでもPrivateリポジトリから取り込みは一応可能

最近のUnityではGit URL経由の場合も、専用のアクセストークンを勝手に作ってくれたりします。

ただ、アクセストークンの削除が面倒だったり、WindowsとMacで動作が異なったり、
チーム内での厳密な運用には若干向かない印象があります。

GitHubアカウントの仕組みでアクセス権限を制御可能

GitHubの Manage Access でパッケージのアクセス範囲を制御可能
- 限定配布が容易になる理由の１つ

独自のnpmレジストリが不要

privateな独自のregistryの作成、保守、運用が不要

GitHub PackageでUnityパッケージを配布するデメリット

Unity Package Manager のパッケージ検索機能が使用不可

GHP側に検索API endpoint (/-/all, /-/v1/search)が提供されていない
UPMでパッケージ検索が発生すると毎回エラーログが出てしまう
- UPMウィンドウを開いたときなどに scopedRegistries に登録されたレジストリ全体で検索が実施される仕様のため

ビルド自体には影響しません

Packages以下で displayName で表示されない

パッケージの使用自体は問題ない (と思います)

原因不明、検索機能が使えないことが原因？
displayName 自体は認識されている
Add package from git URL... の場合は問題なく displayName で表示される

GitHub Package を使用する場合の諸注意

privateの場合はストレージ枠に注意
- アップロードされたパッケージ毎にストレージ枠を消費
- 巨大なファイルをアップロードする場合は特に注意 (3Dモデル, サウンドファイル、動画ファイルなど)
パッケージ削除は一応可能ですが、基本的に削除しない方針を推奨
- 作業コストとヒューマンエラーにつながる
- 特にパッケージが大量になったときの手作業は担当者が地獄を見ます

おサイフと相談しましょう！ご利用は計画的に！

サンプル

サンプルリポジトリ

github.com

サンプルパッケージ

github.com

サンプルパッケージ発行時のアクション

github.com

参考

forum.unity.com

雑感

GitHubにサンプルを作成してからちょっと遅れてしまいました。

今週はちょっとドタバタしていたので、今日は集中して記事にしてみました！

GHP経由の場合は検索機能がありませんが、依存パッケージを定義できたりアクセス制御もGitHubの仕組みを流用できたりで運用上もメリットがあると思います！

あと、displayNameが反映されない問題は気になるのであとでUnityに報告しておきます(公開パッケージがあったほうが報告しやすかったので)。

それでは～

(旧)【GitHub Packages for Unity】限定配布も可能, GitHub Packages で Unity アセット配布

2021-08-01T00:16:06+09:00

以下にページに移行しました

tsgcpp.hateblo.jp

【感想】 Adaptive Code のススメ

2021-07-05T21:08:23+09:00

概要
知見
サンプル
雑感

概要

今回は「Adaptive Code C#実践開発手法第2版」を読み終わったので、
そこで得た知見から特に感銘を受けた部分を３つ共有しようと思います。

www.nikkeibp.co.jp

Unity開発者なので、UnityとC#を題材にして紹介します。

本当は数か月前には読み終わってたんですが、記事にできていませんでした。。。復習の意味も込めて記事にします。

知見

リスコフの置換原則 (Liskov Substitution Principle) の保証

以下 LSP と呼称します。

LSPの概要

平たく言うと
"サブクラス、継承クラスはベースクラスに置き換え可能でなければならない"
というSOLID原則の1つですね。

本には「コントラクト(ルール定義)」として事前条件、事後条件、データ不変条件などといった重要な要素も紹介されています。

この本から得られたのは単なるリスコフの置換原則の知識ではなく、

「如何にしてリスコフの置換原則を保証するか」

という部分でした。

LSPの保証方法

結論を述べるとテストクラスを活用します

ベースのテストクラスを定義
継承クラスのテストはベースのテストを継承

つまり、単に「LSPを満たすように実装する」だけではなく、
「LSPを機械的に保証する」をテストクラスで実現することになります。

LSP保証のテストクラスのサンプル

テスト対象のinterface

今回の題材は「数値の丸め処理を行うメソッド」とします。
以下の IRounder.Round の事前条件、事後条件をベースのテストクラスで定義しましょう。

public interface IRounder
{
    float Round(float value, float interval);
}

ルール定義

事前条件
- intervalに0は指定不可
- intervalに負の値は指定不可
事後条件
- 引数のvalueとintervalが同じ値の場合はintervalを返すこと

ベースのテストクラスを定義

ベースのテストクラスのポイントとして

abstractクラスとして定義
abstractメソッドとして生成メソッドを定義
- 継承クラスのインスタンス生成を定義可能にするため
ルールを満たすことを確認するテストを定義

using NUnit.Framework;

public abstract class TestRounderBase
{
    // abstract指定により対象オブジェクトのインスタンス生成を継承テストクラスで定義
    public abstract IRounder CreateTarget();

    IRounder _target;

    [SetUp]
    public void SetUp() => _target = CreateTarget();

    // 事前条件1: intervalに0は指定不可として、例外を出すこと
    [Test]
    public void Round_ThrowsExceptionIfIntervalIsZero()
    {
        Assert.Throws<RounderException>(() =>
        {
            _target.Round(1f, interval: 0f);
        });
    }

    // 事前条件2: intervalに負の値は指定不可として、例外を出すこと
    [Test]
    public void Round_ThrowsExceptionIfIntervalIsLessThanZero()
    {
        Assert.Throws<RounderException>(() =>
        {
            _target.Round(1f, interval: -1f);
        });
    }

    // 事後条件1: 引数のvalueとintervalが同じ値の場合はintervalを返すこと
    [Test]
    public void Round_ReturnsIntervalIfValueIsEqualToInterval()
    {
        Assert.AreEqual(1f, _target.Round(1f, interval: 1f));
        Assert.AreEqual(2f, _target.Round(2f, interval: 2f));
        Assert.AreEqual(10f, _target.Round(10f, interval: 10f));
    }
}

継承クラスのテストを作成

ベースクラスを継承したテストクラスを作成。
ベースクラスを継承して、継承クラスのインスタンス生成メソッドを定義する。

public class TestNearestRounder_LSP : TestRounderBase
{
    public override IRounder CreateTarget() => new NearestRounder();
}

ちなみに NearestRounder の定義は以下です。

using System;

public sealed class NearestRounder : IRounder
{
    public float Round(float value, float interval)
    {
        if (interval <= 0f)
        {
            throw new RounderException("\"interval\" is 0 or less");
        }

        return (float)Math.Round(value / interval) * interval;
    }
}

テスト全体は TestNearestRounder.cs で確認できます。
また、こちらのサンプルには NearestRounder特有のテストも別クラスとして記載しています。

テストの実行

IRounderの継承クラスがLSPを満たしていることをUnitTestで確認。

また、以後ルールを追加したい場合はベースクラスに追加することで、
継承クラスも常にルールを満たしていることが検証されるようになります。

LSPのまとめ

ベースとなるテストクラスでLSPのルールを定義することで、より強固なLSPを守るフローを構築することが可能になります。

interfaceのコメントに「intervalは0以上を必ず指定させること」などを記載してもプログラム上では何の影響もありませんが、テストクラスを再利用することで保守する上でも保証することが可能になります。

abstractなテストクラスを利用する発想があまりなかったので、目からうろこでした。

投機的な一般化(Speculative Generality)

書籍には "投機的な一般化" と記載されていましたが文字だけだとなんのこっちゃ感がありますね(笑)。

原文は"Speculative Generality"です。

ちなみに書籍では「開放／閉鎖の原則」を意識するための要素として紹介されています。

投機的な一般化の概要

ここは私自身の解釈も含まれますが、端的に言えば

"あると良さそうと思って拡張可能に実装した、でも結局使わなかった"

的なことです。

interfaceを使った抽象化を身に着けたばかりのプログラマーによくある行動として、
「あらゆるものをinterface化して、意図しない拡張性を持たせてしまう」というものがり、これが投機的な一般化となる可能性があります。

「すべての設計は明確な意図をもって行うべき」との説明があり、
投機的な一般化はそれに反する行いのことです。

予想されるバリエーション

「予想されるバリエーション」とは「何が拡張できて、何が拡張できないのかを明確にすべきである」と説明があります。
投機的な一般化の対比となり、設計は「投機的な一般化」ではなく「予想されるバリエーション」となるようにするべきということになります。

投機的な一般化の問題

拡張ポイント特有の実装が無駄になってしまう
- interfaceで抽象化されたメソッドを使用する場合、そのメソッドのあらゆる結果の対策が必要となる
- 例: そのメソッドが異常系を返すパターン、例外を出すパターンなどの考慮が必要となり、結果的に開発コストが高くなる。
意図しない継承クラスが作成されてしまう可能性がある
- 継承クラスが作成された場合は継承クラス特有の考慮が必要になる
- アセンブリ(Unityにおけるasmdef)に継承クラスが分散し、むやみにinterfaceを変更できなくなる

投機的な一般化の回避例

修飾子(sealed, internalなど)を指定

修飾子はコンパイラが解釈する要素となります。
つまりクラスのルールをコンパイルレベルで定義することが可能になります。

クラスにsealedを指定し、派生クラスの作成を制限
- もし派生クラスを想定していないのであれば基本的にsealedを付けて保守範囲を限定する
- 余談: C#はデフォルトで非sealed (派生クラスの作成可能)
クラスにinternalを指定し、異なるアセンブリでの派生クラス発生の回避
- internalクラスはアセンブリ内でのみアクセス可能なので、自分の管轄外での派生クラスの発生を回避できます
- 余談、もしinternalクラスのUnitTestをしたい場合は InternalsVisibleToAttribute を活用すると良いです

ちなみにKotlinだとデフォルトでは派生不可(非open)で、僕がKotlinを好きな理由の１つだったりします。

プロダクトの拡張ポイントを見極める

ここはノウハウや経験に基づくものになります。

「投機的な一般化」は拡張部分に焦点を絞ったテーマのため少し話はずれてしまいますが、
以下のことを意識してみるとよいかもしれません。

もし自身が企画者である場合は「この拡張が必要な理由が明確になっている」かを考慮する
もし自身が実装する立場であった場合は、企画した人が「とりあえずあると良さそうな部分を提案する」といった性質がある場合は、そのアイデアを深堀して必要性を明確化する

「15分程度で終わる議論をせず、5日かけて実装したけどやっぱりいらなかった」みたいなことは極力避けましょう。

拡張ポイントを作るということは、それだけ保守範囲も増えるということを意識すると良いと思います。

投機的な一般化のまとめ

「すべての設計は明確な意図をもって行うべき」という言葉にはなかなか考えさせられるものがありました。

意図をしない部分があるということは、言ってしまえばあらゆることが起こってしまうと可能性を秘めているということです。
だからこそノウハウを蓄積して、予測できなかった事象を少しでも減らしていきましょう。

私もクラスを作るとき、派生を想定していない場合は sealed を忘れないようになど小さなところから意識するように心掛けていきたいです。

コナーセンス(Connascence)

コナーセンスの概要

コナーセンスとは「コードにおける依存度合(結合度)を図る指標」のことです。
依存関係の尺度を見極めるうえで意識すると役立つ概念となります。

コナーセンスにはレベルがあり、高いものほど処理との結合度が強いということになります。

コナーセンスの結合度

結合度を考える場合に簡単な判断として、
「ある要素を変更した際の影響度合い」と考えても良いと思います。

具体例を2つほど出します

名前のコナーセンス

"名前" のコナーセンスは、結合度が高いです。

ここでいう名前とは、クラス名やメソッド名など"コンパイラが解釈する名前"のことです。
注意として、メソッド名に使用されている単語自体の意味は関係ありません。

とあるメソッド名を変更したときは、そのクラスを使っていた部分も修正しないとコンパイルエラーが発生しますよね？

    public float Calc() => ...

    public void Main()
    {
        var result = Calc();
        ...
    }

上記のコードで、もし Calc() -> Calculate()とリネームした場合は、Main関数内も修正が必要になります。
クラス名やメソッド名は名前を変えると、それだけで使用者に影響を与えるため強い結合度を持っていると言えます。

値のコナーセンス

"値" のコナーセンスは、結合度が低いです。

これは身近ないい例があります。
よく「マジックナンバーは定数化しましょう」みたいなことを聞きませんか？

なぜ定数化するかというと、定数名に意味を込めて意図が伝わりやすいようにするためという側面もあります。
(もちろん、共通の定数を再利用するといった理由もあります)

    public float CalcArea(float radius) => radius * radius * 3.141592f;

例えば上記のように3.14...とみると大体の人は「円周率だ！」となると思います。
しかし、すべての値がそれだけで意図が伝わるとは限りません。

    public int CheckCode(int code) => code == 200 ? 0 : -1;

上記のコードは見慣れた人には「ああ、HTTPステータスかな？」となると思いますが、
見慣れない人には人には暗号のように見えると思います。

コードを書いた人は「HTTPステータスコードによってエラーコードを返すようにした」つもりで書いても、
第三者には伝わらりづらいコードになるかもしれませんので、以下のように定数名に意味を込めてあげましょう。

    private const int HttpOk = 200;
    private const int ValidValue = 0;
    private const int InvalidValue = -1;

    public int CheckCode(int code) => code == HttpOk ? ValidValue : InvalidValue;

プログラム的にも 200 -> 100 に置き換えても別にコンパイルは通ってしまいますが、
それだと意図しない挙動になってしまいます。

値のコナーセンスのように結合度の低い場合は、定数化するなどの工夫が求められることが多いです。

コナーセンスのまとめ

コナーセンスはコード自体の品質を図るうえで非常に役立つ指標になります。

書籍には「インターフェイスのコナーセンス」という非公式なコナーセンスが紹介されています。
インターフェイスは継承するオブジェクトの必須要素やクライアントの依存部分を定義することが可能で、
意味を込めるうえでは非常に有用な要素といえます。

書籍を読むまではコナーセンスという単語自体は知りませんでしたが、
「interfaceで要素を定義する」などは意識していたこともあって、より具体的な概念として知ることができました。

コナーセンスの要素として10個ほど紹介されており、それぞれに特有の観点がありますので気になったら確認してみてください！

サンプル

LSPについてのサンプルコードは以下にあります。

github.com

雑感

今回は技術書の感想という形で記事にしてみました。

こんな1ページの記事では紹介しきれないぐらいたくさんの知見について記述されています。

何気にアジャイル開発やスクラムについても簡易的に紹介されていますので、
アーキテクチャやコーディングだけでなく、ワークフローについても勉強になる本だと思います。

SOLID原則をより深堀したい人にはとてもオススメなのでよかったら手に取ってみてください！
それでは～

【Unity】OculusIntegrationがPackageManager対応しやすくなりました！

2021-06-25T00:50:29+09:00

概要
環境
追記
Meta公式によるPackage Manager対応 (2022/10/12 追記)
PackageManager対応方法
パッケージの取り込み方
対応しやすくなった理由
- そもそもなぜ対応が難しかったのか
  - 暫定対応
- PackageManagerで取り込まれた場合の考慮が28.0以降で追加
PackageManager対応するメリット
雑感

概要

Oculus Integration SDK がいつの間にかUnity Package Managerに対応させやすくなっていたのでちょっと紹介します。

巷では、Oculus Quest向けのSplash Screen が指定可能になったことで話題でしたが、何気にPackageManager対応しやすくなったのも見過ごせないと思っています！

※Splash Screenについての公式ツイート

Introducing Instant Runtime-driven Splash Screens. Get people into your Quest apps faster than ever. Check out our blog post for how to implement: https://t.co/XLKZy3ukM6 pic.twitter.com/kkcSJrMvik
— Oculus Developers (@Oculus_Dev) 2021年5月13日

環境

Oculus Integration SDK 28.0 (1.60) 以降

追記

2022/10/12
- Meta公式によるPackage Manager対応

Meta公式によるPackage Manager対応 (2022/10/12 追記)

Meta公式からMeta XR Integration (旧Oculus Integration) v44 から Pacakge Managerによるインストール方法がアナウンスされています。

Import Individual SDKs from Unity Package Manager | Oculus Developers

レジストリは https://npm.developer.oculus.com/ とのこと。

packages are hosted on Meta’s scoped registry: https://npm.developer.oculus.com/.

現時点では基本機能 (Oculus/VR) のみのようですが、順次対応されるようです。

How Unity Package Manager Can Help You Manage Integration SDKs

Meta Quest Proの発表もあったので、対応が進められたのかもしれません。

こちらの記事を公開してから1年4ヶ月は経ってるので、あまり「そのうち」ではありませんでしたね（笑）

PackageManager対応方法

1. Oculus Integration パッケージ化専用のUnityプロジェクトを作成

パッケージ用のUnityのプロジェクトを作成

2. Oculus Integrationをインストール

Asset Store or アーカイブページからOculusIntegrationをダウンロードおよびインストール
- 必要なアセットにチェックを入れて "Import"

※今回は基本機能のみをインストールするため Oculus/VRのみ指定

3. gitignoreにOculus向け設定ファイルを追加

commitから除外するために.gitignoreにOculus向け設定ファイルを追加
- パッケージ対応したOculusIntegrationを取り込むと自動的に生成されます
- パッケージ側からは除外しておきましょう

# Oculus Assets
/[Aa]ssets/[Oo]culus/OculusProjectConfig.asset
/[Aa]ssets/[Oo]culus/OculusProjectConfig.asset.meta
/[Aa]ssets/Resources/OVRPlatformToolSettings.asset
/[Aa]ssets/Resources/OVRPlatformToolSettings.asset.meta

4. package.json を作成

Package Managerに対応させるため Assets/Oculus/package.json を作成
- nameなどはプロジェクトに合わせて適宜修正してください

{
    "name": "com.tsgcpp.oculusintegration",
    "version": "1.61.0",
    "displayName": "OculusIntegration",
    "description": "The Oculus Integration SDK (private).",
    "unity": "2019.4",
    "keywords": [
        "oculus"
    ],
    "dependencies": {}
}

5. Assets/Oculusをcommit

.gitignore を commit
Assets/Oculus と Assets/Oculus.meta をcommit
- package.jsonも併せてcommit

6. Private用のGitリポジトリにpush (任意)

※Publicにすると再配布になるため注意が必要

Private用のGitリポジトリにpushしましょう
- Gitリポジトリにpushすることで、Git経由でPackage Managerで取り込みが可能となります

フォルダ構成

パッケージの取り込み方

通常のPackageManagerでの取り込みと同様となります

Add package from git URL...

https://<git url>/<org>/<repository>.git?path=Assets/Oculus#<tag or branch> のように指定
- i.e. https://github.com/tsgcpp/OculusIntegration.git?path=Assets/Oculus#1.61.0 (リポジトリ名: OculusIntegration, タグ名: 1.61.0 の場合)

Add package from disk...

Assets/Oculus/package.json を指定

取り込み後に設定ファイルが生成される

対応しやすくなった理由

そもそもなぜ対応が難しかったのか

Oculus Integration SDK 27.0 (1.59) 以前の話となります

原因は Assets/Oculus/VR/Editor/OVRProjectConfig.cs
- OculusProjectConfig.asset(Oculus向けの設定アセット) を自動生成するEditorスクリプト
自動生成するパスの指定方法に問題があり、PackageManager経由で取り込んだ場合にエラーが発生
- 端的に言うとOVRProjectConfig.csの親の親フォルダが生成先
PackageManagerで取り込んだ場合はAssets/以下ではなく、Packages/以下が生成対象となってしまっている
- Packages/com.tsgcpp.oculusintegration/VR/Editor/OVRProjectConfig.cs に配置されているため
- AssetDatabase.CreateAssetでScriptableObject(OVRProjectConfig)の生成先にPackages/以下を指定するとエラー (Assets/以下ではない場合にエラー)

暫定対応

Oculus Integration SDK 27.0 (1.59) 以前の話となります

Assets/Oculus以下のEditorフォルダすべてをunitypackageにExport
Assets/Oculus以下にあるEditorフォルダ以下をすべて削除
OculusIntegrationを使用するメインプロジェクトに上記unitypackageでEditor群を取り込み
- OculusProjectConfig.assetを使用するにはEditor以下のスクリプトが必要なため

上記の方法で暫定的に対応することは可能でした。
ただ、Editorスクリプトのみ直接取り込む形となるため、結構残念な感じになってました。

PackageManagerで取り込まれた場合の考慮が28.0以降で追加

SDK 28.0 (1.60) で以下の考慮が追加されました
OVRPluginUpdaterStub.IsInsidePackageDistribution は assetPath.StartsWith("Packages/" の判定を実施
Packages/以下だった場合は、Assets/Oculus/OculusProjectConfig.asset を生成先に変更

    private static string GetOculusProjectConfigAssetPath()
    {
        ...

        if (OVRPluginUpdaterStub.IsInsidePackageDistribution())
        {

つまり、PackageManagerで取り込まれた場合でもAssets/Oculus以下に設定ファイルが生成されるようになりました。
これがOculus IntegrationがPackageManager対応しやすくなった理由です！

PackageManager対応するメリット

「別に直接プロジェクトに取り込んでもよくない？？？」って思った方もいらっしゃると思いますので、
メリットについても補足しようと思います。

OculusIntegrationを管理するGitリポジトリを分割可能
- GitHubなどの容量制限にひっかかるのを回避可能
- OculusIntegrationは単体でもかなり容量が大きく、追加するアセットによってはあっさり100MBを超えます
- Assets/Oculus/VRのみでも60MBあります (29.0の場合)
アセットのバージョン管理と更新が容易
- Package Managerでアセットを取り込むと更新が容易になります(バージョンを更新するのみ)
  - Asset Store(unitypackage)で取り込んだ場合、一度アセットをすべて削除する必要がある場合が多い
- hookされるEditorスクリプトがあるため再起動はどちらにしても推奨

雑感

今回はOculus関連にテーマを絞ってみました。
Oculus Quest2がかなり売れているので、OculusIntegrationの更新もかなり加速している感じがします。

もしかしたら、そのうちUnity Package ManagerでOculus Integrationが提供されるのかもしれませんね。

Unity向けだけじゃなくて、Unreal向けも加速しているような気がします。
Splash Screenも追加できるようになったので、これを機に追加しても良さそうですね。

みなさんのOculus向けアプリケーション開発の助けになれば幸いです。
それでは～。

【Unity】Physics.SyncTransforms の特性調査

2021-04-28T22:10:38+09:00

経緯
検証環境
前知識
登場人物
検証方法
検証結果
判明した特性
考察
検証プロジェクト
雑感

今回は Physics.SyncTransforms の特性を調査したため共有します。

経緯

Colliderの物理エンジンへのFlushを通常のタイミングとは別で実施したい
Flushを任意のタイミングで実行するにはPhysics.SyncTransforms をコールする必要があった
Physics.SyncTransformsを通常のFlushとは別に実施する場合にパフォーマンスなどが気になったため調査

※Flushとは実際にデータを反映する処理のこと(ここでは物理エンジン用メモリ領域への反映)

検証環境

Unity 2020.3.4f1
- Mono
- .Net Standard 2.0
Physics.autoSyncTransforms = false
Oculus Quest 2 (Android)
Development Build 有り(Profiler用)

前知識

物理オブジェクトの物理エンジンへのFlush

ColliderのTransformが物理エンジンに反映されるタイミングはFixedUpdate後 (Physics.autoSyncTransforms がfalseの場合)
- 厳密にはExecutionOrder でいう "Internal Physics Update" がFlushのタイミングと考えられる
Flushタイミングは TestPhysicsSyncTiming.cs で確認

Physics.SyncTransforms

上記「物理オブジェクトの物理エンジンへのFlush」を任意のタイミングで発動させるメソッド
今回の主役

Physics.autoSyncTransforms

ColliderのTransformが変更された際に即座に物理エンジンに反映するかの設定
Unity 2019以降はデフォルトでfalse
- つまりデフォルトではFixedUpdate後にFlushが実施されると同義
ProjectSettingsのPhysicsからも設定可能

Physics.autoSyncTransforms によるとtrueにするとパフォーマンスの低下の可能性がある

When autoSyncTransforms is set to true, repeatedly changing a Transform and then performing a physics query can cause performance loss.

Physics.autoSyncTransforms = trueにする場合はオーバーヘッドに注意
- 物理演算の正確性とパフォーマンスがトレードオフとなる

今回は Physics.autoSyncTransforms = false の場合をメインに調査

Flushの発生条件

ColliderのTransformが変更された場合
- Dirtyフラグが付き、後述の「Flushの発生タイミング」で物理エンジンに反映
こちらのUnity Pro Tips によれば移動する物理オブジェクトがない場合はオーバーヘッドはほとんどないとのこと
- つまり移動しないオブジェクトに関しては static かどうかにかかわらず Flush が発生しない

Flushの発生タイミング

Physics.autoSyncTransforms = false であれば FixedUpdate後 or Physics.SyncTransforms コール時点
- Dirtyフラグが付いた物理オブジェクトのみ
Physics.autoSyncTransforms = true であればColliderのTransformが変更された時点

-- ここまでが前知識 --

登場人物

PlayerColliders

CapsuleCollider + BoxCollider 64個 (4 x 4 x 4) をアニメーション
LateUpdate(Animation Update後として) にて Physics.SyncTransforms を実施し時間を計測
すべての検証環境で使用

www.youtube.com

AnimationColliders

BoxColliderを大量(64000個)に配置してプレイヤー同様にアニメーション
- AnimatorのUpdate Mode は Normal

www.youtube.com

PhysicsAnimationColliders

AnimationColliders の Update Mode を Animate Physics に変更したもの

DisabledAnimationColliders

AnimationCollidersのコライダー群のルートのGameObject(ColliderRoot)をオフにしたもの

DisabledAnimationColliders + CapsuleCollider

DisabledAnimationCollidersのColliderRootと同階層に1つのCapsuleColliderを配置したもの

ColliderDisabledAnimationColliders

ColliderRoot以下のすべてのColliderに対してCollider.enabled = false にしたもの
- ColliderRootオブジェクト自体はアクティブのまま

Static Colliders

10000個のstaticのBoxCollider群

検証方法

後述する「登場人物」を組み合わせた状態で Physics.SyncTransforms をコールして実行時間の変化を計測
- コールはLateUpdate時 (Animatorが終了した後として)

検証結果

※おおよその平均

注目したい部分は色付き

検証対象	時間 (ms)
PlayerColliders x1	0.07
PlayerColliders x2	0.10
PlayerColliders x4	0.19
PlayerColliders x1 (Animator disabled)	0.00
PlayerColliders + AnimationColliders	21.01
PlayerColliders + PhysicsAnimationColliders	0.07
PlayerColliders + DisabledAnimationColliders	0.07
PlayerColliders + DisabledAnimationColliders + CapsuleCollider	0.41
PlayerColliders + ColliderDisabledAnimationColliders	0.08
PlayerColliders + StaticColliders	0.07

クリックで展開：各調査ごとのProfiler

PlayerColliders x1

PlayerColliders x2

PlayerColliders x4

PlayerColliders のみ (Animatorをオフ)

PlayerColliders + AnimationColliders

PlayerColliders + PhysicsAnimationColliders

PlayerColliders + DisabledAnimationColliders

PlayerColliders + DisabledAnimationColliders + CapsuleCollider

PlayerColliders + ColliderDisabledAnimationColliders

PlayerColliders + StaticColliders

注意事項

今回は Physics.SyncTransforms に主眼を置くためCPU Usageはあまり考慮しない
XR環境のためCPU Usageに表示されている時間の大部分は Gfx.WaitForRenderThread

判明した特性

Physics.SyncTransformsの時間はコール時点のFlushされていないオブジェクト数に依存
- FixedUpdate直後からPhysics.SyncTransformsをコールするまでにTransformが変更されたオブジェクトが対象
Flush済みのオブジェクトはPhysics.SyncTransformsの時間には大して影響はしない
- つまりTransformが変更されたオブジェクトがなければオーバーヘッドは小さい
通常Flushとそれ以外でFlushする対象は分けることは一応可能
- ただし「特定のオブジェクトのみFlushしたい」の様なコントロールは不可
  - Unity側に機能が用意されていない（と思われる、ご存じの方がいたら教えてください！）
非アクティブなCollider(コンポーネントのenabled=false含む)はFlushの対象外
- アクティブ化した後のFixedUpdate後 or Physics.SyncTransforms で改めてFlush
同階層にアクティブと非アクティブ両方のColliderが存在する場合は特殊なFlushとなる可能性あり(詳細は不明)
- "DisabledAnimationColliders + CapsuleCollider" の時間を見るとCapsuleCollider1つだけFlushされるにしては時間がかかっている

考察

Physics.SyncTransforms 時にFlushされるCollider数をうまくコントロールすれば、パフォーマンスへの影響をコントロールできそう
UpdateやFixedUpdateなで移動するColliderが多い場合は実行時間に注意が必要になると思われる
- あまりに多いと Physics.SyncTransforms 時スパイクが発生

検証プロジェクト

2022/06/19変更
- [email protected]/manual/index.html">Performance Testing Extension for Unity Test Frameworkを使用した検証の自動化のためmainブランチには大幅に変更されています
- このブログ記事当初の検証プロジェクトは tag 1.0.0 をご参照ください

github.com

雑感

ちょっと個人的な事情があって検証、ついでにドキュメント化してみました。
Flush対象を明示的に指定できないのはちょっと残念ですね。。。
ただ、物理で動くものとそれ以外で分けるのは一応できそうってとこでしょうか。

また、別の機会に Physics.SyncTransforms を利用したものを作ってみようと思います。

それでは～

(旧)【Extenject】Composite Installer を紹介！

2021-02-21T19:12:26+09:00

以下にページに移行しました

tsgcpp.hateblo.jp

【Moq】UnityでのMoq導入方法と MoqのTips集を紹介！

2020-11-27T22:14:11+09:00

概要
Moqの導入
Moqによるモック作成サンプル
Moqを使ったTips集
サンプルプロジェクト
雑感

Unity 2021以降の場合は以下をどうぞ！ tsgcpp.hateblo.jp

概要

今回は Moq というC#向けモックライブラリをUnityに導入する方法と、Moqを使ったテクニックをいくつか紹介しようと思います。

UnitTestにおいてモック化はかなり重要な立ち位置になると思いますが、自作モックは何かと保守コストが高かったり機能面が微妙になったりと悩みどころがあります。
そこでオススメなのが今回紹介する Moq となります。

他の言語のモックライブラリ同様、モック化だけでなくSpy機能(メソッドがコールされたかの確認機能)も結構充実していますので、
ぜひUnity もしくは C# のUnitTestに活かしていきましょう！

今回の記事はある程度UnitTestを知っていることが前提となりますが、UnitTestのサンプルコードにもできる限り説明を入れています。
チートシートにもなっていると思いますのでよかったら参考にしてください。

Moqの導入

Github

※今回はソースコードを直接取り込みません

github.com

MoqのソースコードはC# 8.0で書かれており、現在のLTSであるUnity 2019.4 ではコンパイルできません。

よって、後述するコンパイル済みのdllをダウンロードして使用することになります！

Moqの依存ライブラリとそのライセンスについて

使用する前に必ずライセンスを確認してください(特に業務で使用する場合は要注意です！)

Moq: BSD 3-Clause License
Castle.Core: Apache License Version 2.0
- Moqが依存するライブラリ
System.Threading.Tasks.Extensions: MIT
- Moqが依存するライブラリ (Microsoft 提供)
System.Runtime.CompilerServices.Unsafe: MIT
- System.Threading.Tasks.Extensionsが依存するライブラリ

上記4つを取り込む必要があります。

MoqをUnityに導入する方法

Moqおよび依存ライブラリのダウンロード

今回はMoqと依存ライブラリ3つをNugetからダウンロードしましょう。

以下の用に"Download package"からnupkgをダウンロード可能です。

www.nuget.org

nupkgを展開

nupkgの実体はzipファイルなので拡張子を ".zip" にするだけで大体のOSの標準で展開できると思います。

7-zipなどを使用すれば拡張子を変えなくても展開できると思います。

dllファイルの取り出し

展開したフォルダのうち、以下のパスにあるdllをUnityのAssets以下のフォルダにコピーしましょう。

Api Compatibility Level に従ってdll を選択してください。

.NET Standard 2.0

Moq: moq.4.X.X/lib/netstandard2.0/Moq.dll
Castle.Core: castle.core.4.X.X/lib/netstandard1.5/Castle.Core.dll
- .Net Standard2.0向けがないためこちらで代用
System.Threading.Tasks.Extensions: system.threading.tasks.extensions.4.X.X/lib/netstandard2.0/System.Threading.Tasks.Extensions.dll
System.Runtime.CompilerServices.Unsafe: system.runtime.compilerservices.unsafe.5.0.0/lib/netstandard2.0/System.Runtime.CompilerServices.Unsafe.dll

.NET 4.x or .NET Framework

Moq: moq.4.X.X/lib/net45/Moq.dll
Castle.Core: castle.core.4.X.X/lib/net45/Castle.Core.dll
System.Threading.Tasks.Extensions: system.threading.tasks.extensions.4.X.X/lib/net461/System.Threading.Tasks.Extensions.dll
System.Runtime.CompilerServices.Unsafe: system.runtime.compilerservices.unsafe.5.0.0/lib/net45/System.Runtime.CompilerServices.Unsafe.dll

Unityのプロジェクトへの配置は以下を参考にしてください

dllのプラットフォームの指定

Moqはあくまでテストのみに使用するため、ビルドする実行ファイルには含まれないように設定しておきましょう！大抵のOSSは再頒布するとラインセス表記が必要なります。

特に Moq と Castle.Coreは実行ファイルには不要なのでInclude PlatformsをEditorのみにしておきましょう！

System.Threading.Tasks.Extensions と System.Runtime.CompilerServices.Unsafe のプラットフォーム指定について

System.Threading.Tasks.Extensions と System.Runtime.CompilerServices.Unsafe も不要であれば同様に設定してください。

ただ、ZLogger など一部メジャーなOSSも依存していたりするので、その場合は逆に設定しないように注意してください。

テスト用Assembly Definitionにdllを取り込み

以下を参考にテスト用Assembly Definitionの"Assembly References"に追加して"Apply"して下さい。

以上でMoqおよび依存ライブラリの取り込みは完了です！

Moqによるモック作成サンプル

せっかく取り込んでみたので、少し使い方を解説しようと思います。

モック化するinterface

// 戻り値有りのメソッドを持つinterface
public interface IGetter
{
    object Get();
}

// プロパティを持つinterface
public interface IHolder
{
    object Value { get; }
}

// 引数を持つinterface
public interface ILogger
{
    void Log(string message);
}

モック化の例

モックオブジェクトの作成

Mock<IGetter> mock = new Mock<IGetter>();

モックオブジェクトから元となる型を取り出し

var getterMock = new Mock<IGetter>();

// モックオブジェクトからIGetterインスタンスとして取り出し
IGetter mockAsGetter = getterMock.Object;

メソッドの戻り値を指定

var getterMock = new Mock<IGetter>();

// Getメソッドのモック化("Hello Moq!"を返すように仕込み)
getterMock.Setup(m => m.Get()).Returns("Hello Moq!");

プロパティの戻り値を指定

var holderMock = new Mock<IHolder>();

// Valueプロパティのモック化("Hi Moq!"を返すように仕込み)
holderMock.Setup(m => m.Value).Returns("Hi Moq!")

特定のメソッドがコールされたかの確認(Spyとしての利用)

メソッドがコールされたかを検知するモックオブジェクトをSpyと呼ぶことがあります。

MoqのMockクラスは生成するだけでSpyとしても使用することが可能です！

また、「特定の引数が渡されたこと」、「任意の引数でコールされたこと」なども確認することが可能です。

// ILoggerのモックオブジェクトの作成
var loggerMock = new Mock<ILogger>();
var mockAsLogger = loggerMock.Object;

// 複数回(3回)コール
mockAsLogger.Log("One");
mockAsLogger.Log("Two");
mockAsLogger.Log("Two");

// 3回コールされたことの確認
loggerMock.Verify(m => m.Log(It.IsAny<string>()), Times.Exactly(3));

// 複数回(1回以上)コールされたことの確認
loggerMock.Verify(m => m.Log(It.IsAny<string>()), Times.AtLeastOnce());

// "One"でコールは1回であることの確認
loggerMock.Verify(m => m.Log("One"), Times.Once());

// "Two"でコールは2回であることの確認
loggerMock.Verify(m => m.Log("Two"), Times.Exactly(2));

Moqを使用したサンプルの全体

Moqの使用例の全体は以下のテストクラスで確認できます！

[https://github.com/tsgcpp/UnityMoqSample/blob/master/Assets/Tests/MoqExamples/TestMoqSample.cs

モック化するメソッド、プロパティの注意点

モック化するメソッドやプロパティはオーバーライド可能である必要があります。
オーバーライド不可の場合はモック化することはできません。。。

以下のMockTargetクラス(非interface)の場合、FuncVirtualとFuncAbstractはモック化できますがFuncはオーバーライド不可のためモック化できません(例外System.NotSupportedExceptionが飛びます)。

public abstract class MockTarget
{
    public object Func()
    {
        return 1;
    }

    public virtual object FuncVirtual()
    {
        return 2;
    }

    public abstract object FuncAbstract();
}

Moqに限らずモックライブラリ全般に言えますが、モック化の対象は基本的にinterfaceを使用することをオススメします！

https://github.com/tsgcpp/UnityMoqSample/blob/master/Assets/Tests/MoqExamples/TestMoqException.cs

Moqを使ったTips集

in, ref指定の構造体を引数として持つメソッドの任意の引数でのVerify

以下のように引数にinが指定されたメソッドのことです。

public interface IInCaller
{
    void Call(in Parameter parameter);
}

ちなみにParameterは以下です。

public struct Parameter
{
    public int x;
}

さて、このinが指定されたメソッドのVerifyですが、なんとIt.IsAny<T>()だとSpyが機能しなくなります。。。

target.Verify(m => m.Call(It.IsAny<Parameter>()), Times.Once());

inやrefが指定されている場合は以下の It.Ref<T>.IsAny を使用しましょう！

target.Verify(m => m.Call(It.Ref<Parameter>.IsAny), Times.Once());

Moq自体の仕様なのでご注意ください。

細かい使用確認は以下のテストコードで実施しています。よかったらこちらもどうぞ！

https://github.com/tsgcpp/UnityMoqSample/blob/master/Assets/Tests/MoqExamples/TestMoqRefVerify.cs

in, refどちらも指定されていない場合

It.IsAny<T>()で確認しましょう。
こちらは逆にIt.Ref<T>.IsAnyが機能しなくなります。

指定ミスの対策

コンパイルエラーにならない関係でヒューマンエラーが起きそうですよね？

特にTimes.Never()を使用する場合、コールなし or 指定ミスどちらなのか分からなくなってしまいます。

target.Verify(m => m.Call(It.Ref<Parameter>.IsAny), Times.Never());

オススメなのはIt.IsAny<T>() もしくは It.Ref<T>.IsAnyを用いるテストを実施する場合は、正常系のテストに以下のTimes.Once()など "1回以上コールされたことの検証を混ぜ込むことです。

target.Verify(m => m.Call(It.Ref<Parameter>.IsAny), Times.Once());

Times.Once()やTimes.Exactly(N)でテストが通る = 機能しているということになりますので！

Callbackの活用例

Callbackの紹介

Moqにはモックオブジェクトのメソッドがコールされたときにコールバック(イベント)を仕込むことが可能です。

// コールバック時のパラメータ格納用List
var messageList = new List<string>();

// ILoggerのモックオブジェクトの作成
var loggerMock = new Mock<ILogger>();

// モックオブジェクトにコールバックを仕込む
loggerMock
    .Setup(m => m.Log(It.IsAny<string>()))
    .Callback<string>(message => messageList.Add(message));

上記のCallbackはLogメソッドに渡された引数をコールバックにより取り出すことが可能になります。

MoqのCallbackでUnityのExecutionOrderとUniTaskの実行順序の検証

さてコードを書いていると時々「絶対この順番でメソッドがコールされていることを保証したい」ということ有りませんか？

そんなときにCallbackを活用するとテストにコール順の検証を組み込むことができます(Moqを使用するので各メソッドがモック化可能なことが前提となります)。

今回はCallbackを活用して、UnityのExecutionOrderとUniTaskを混合した実行順序のテスト化をやってみたいと思います。

具体的にはDefaultExecutionOrderを指定したコンポーネント, UniTask.Yieldに指定したPlayerLoopTimingそれぞれが同時に存在する場合に実行順序を確認するテストを作成します。

確認用コンポーネントとテストコードについて

IRunner型のインスタンスを渡し、Run()メソッドをコールさせる構成を取ります。

DefaultExecutionOrderを指定したコンポーネント

DefaultExecutionOrderを指定する以外は共通のためベースクラスを作成し、それを継承したクラスを用意しました。

以下は int.MaxValueを指定した場合の例です。

using UnityEngine;

/// <summary>
/// MonoBehaviourによるRunner実行 (order: int.MaxValue)
/// </summary>
[DefaultExecutionOrder(int.MaxValue)]
public class ProcessorOrderMaxValue : BaseProcessOrder
{
}

/// <summary>
/// MonoBehaviourによるRunner実行のベース
/// </summary>
public abstract class BaseProcessOrder : MonoBehaviour, IProcessor
{
    public IRunner Runner { get; set; } = null;

    public IRunner LateRunner { get; set; } = null;

    protected virtual void Update()
    {
        Runner?.Run();
    }

    protected virtual void LateUpdate()
    {
        LateRunner?.Run();
    }
}

UniTaskを使用したクラス

using UnityEngine;
using Cysharp.Threading.Tasks;

/// <summary>
/// UniTaskによるRunner実行
/// </summary>
public class ProcessorUniTask : IProcessor
{
    public IRunner Runner { get; set; } = null;

    // 未使用
    public IRunner LateRunner { get; set; } = null;

    public PlayerLoopTiming Timing { get; set; } = PlayerLoopTiming.Update;

    /// <summary>
    /// Runnerの非同期実行
    /// </summary>
    public void Process()
    {
        ProcessAsync().Forget();
    }

    private async UniTask ProcessAsync()
    {
        await UniTask.Yield(Timing);
        Runner?.Run();
    }
}

テストコード

結構コードが長くなってしまったので全体は以下のGithubのコードをご確認ください。

https://github.com/tsgcpp/UnityMoqSample/blob/main/Assets/Tests.UniTask/ExecutionOrder/TestExecutionOrder.cs

大まかに言うとIRunnerのモックオブジェクトを各コンポーネントごとに作成し、対象のコンポーネントごとにコールバック時のメッセージを仕込みます。
各コンポーネント内のUpdate(), LateUpdate() および UniTaskのawait後にIRunner.Run()がコールされると順番にリスト_callbackMessageListにメッセージが追加されていきます。

var runnerMock = new Mock<IRunner>();

// MockのIRunner.Run()がコールされた際にメッセージを登録するように仕込む(いわゆるSpy)
runnerMock
    .Setup(mock => mock.Run())
    .Callback(() => _callbackMessageList.Add(message))

最後に1フレーム動かして、_callbackMessageListにAddされたメッセージの順番を確認することで実行順序を確認します。

yield return new WaitForEndOfFrame()
Assert.AreEqual(18, _callbackMessageList.Count);

Assert.AreEqual("UniTask PlayerLoopTiming.PreUpdate", _callbackMessageList[0]);
Assert.AreEqual("UniTask PlayerLoopTiming.LastPreUpdate", _callbackMessageList[1]);
Assert.AreEqual("UniTask PlayerLoopTiming.Update", _callbackMessageList[2]);
Assert.AreEqual("ProcessorOrderMinValue Update", _callbackMessageList[3]);
Assert.AreEqual("ProcessorOrderM1 Update", _callbackMessageList[4]);

// 以下略

TestRunnerを実行してみました。

問題なさそうですね。

このテストを組み込んでおくことでUnityやUniTaskの更新で実行順序が変わった場合に検知することができたりはするかなと思います。

「Debug.Logで良くない？」と言われるとその通りなんですけどねｗ

個人的に詳細な実行順序を調べたかったというのもあったので、ついでにCallbackに使用する題材にしてみました。

サンプルプロジェクト

github.com

雑感

1ヶ月半ぶりの投稿です。

ネタはいっぱいあるんですが、今やってることに熱中しちゃってなかなかブログを書けませんでしたｗ。

次こそは3DCG系のネタをやりたいかなと思います。

なんかブログを出すこと自体が目的になってるようなとこがあるので、焦らずやっていこうかなと思います。

それでは～

【Extenject】AsTransient, AsCached, AsSingle を使い分けよう！

2020-10-10T16:27:16+09:00

概要
動作環境
関連
前知識
- ContractType と ResultType について
- Zenjectによるインスタンス生成
  - コンストラクタが複数ある場合
  - WithArguments の引数の数について
Scope (AsTransient, AsCached, AsSingle)
簡単なまとめ
サンプルプロジェクト
雑感

概要

今回はZenjectのインスタンス生成の Scope である AsTransient, AsCached, AsSingle の使い分けについて解説します。

この３つは生成されるインスタンスに明確なルール付けをすることができるので、上手に利用してあげてください！

例によって記事の最後にサンプルプロジェクトを置いておきます。

動作環境

Unity 2019.4.12f1
Extenject 9.2.0
- 例によって現在保守されているExtenjectの方を使用

前知識

ContractType と ResultType について

Zenjectには ContractType と ResultType という概念があります。

ContractType は Bind<>に指定する型
ResultType は To<> に指定する型

以下を例にすると IRandomizer がContractType, FixedRandomizerがResultTypeです。

Container
    .Bind<IRandomizer>()
    .To<FixedRandomizer>()

Scopeを考える上でこの ContractType と ResultType は重要なので意識しておいてください！

Zenjectによるインスタンス生成

Containerにバインドすると基本的にZenjectはResultTypeのインスタンスを必要なときに生成してくれます。

public interface IGreeter
{
    string Greeting { get; }
}

public class ResultTypeGreeter : IGreeter
{
    private string _greeting;

    public ResultTypeGreeter(string message, string target)
    {
        _greeting = string.Format("{0} {1}!", message, target);
    }

    public string Greeting => _greeting;
}

Container
    .Bind<IGreeter>()
    .To<ResultTypeGreeter>()
    .AsTransient()
    .WithArguments("Hey", "Guys");

この例の場合、ResultTypeGreeter のコンストラクタの第１引数に"Hey"、第２引数に"Guys"が渡されてインスタンス生成されます。
結果、Zenjectによって生成されたResultTypeGreeterのプロパティ Greeting は "Hey Guys!" を返します。

FromInstanceで直接インスタンスを渡したりすることもできますが、Scopeのメリットが弱くなってしまいます(理由は後述)。

Scopeを使用する場合において、このインスタンス生成してくれる機能は非常に重要な意味を持ちます。

コンストラクタが複数ある場合

[Inject]で使用するコンストラクタをZenjectに明示してください。

コンストラクタが１つの場合は不要です。

ResultTypeGreeter.cs

以下のテストコードで動作確認してます。

ResultTypeGreeterZenjectConstructionTest.cs

ResultType に複数のコンストラクタがある場合はいずれかのコンストラクタ(大抵は一番上に宣言したコンストラクタ)が使用されます。
予期せぬ動作になるかもしれないのでコンストラクタが複数ある場合は[Inject]で明示したほうが良いと思います。

また、この[Inject]ですが複数のコンストラクターに指定した場合はエラーになります。

つまり、Zenjectがインスタンス生成に利用するコンストラクタは1つ ということになります。

WithArguments の引数の数について

基本的に使用するコンストラクタの引数と同じ数を指定する必要があります。

    public ResultTypeGreeter(string message, string target)
    {
        _greeting = string.Format("{0} {1}!", message, target);
    }

以下のようにコンストラクタの引数とWithArgumentsの数が一致していないとエラーになります。

    // エラー
    Container
        .Bind<IGreeter>()
        .To<ResultTypeGreeter>()
        .AsTransient();
        // WithArgumentsなし
    Container.Inject(this)

    // エラー
    Container
        .Bind<IGreeter>()
        .To<ResultTypeGreeter>()
        .AsTransient()
        .WithArguments("Hi");  // 引数1つ指定
    Container.Inject(this)

    // 正常
    Container
        .Bind<IGreeter>()
        .To<ResultTypeGreeter>()
        .AsTransient()
        .WithArguments("Hey", "Guys");  // 2つ指定
    Container.Inject(this)

ただし、デフォルト引数が指定されている場合はエラーにならないようです。

    [Inject]
    public ResultTypeGreeter(string message = "Hello", string target = "Everybody")
    {
        _greeting = string.Format("{0} {1}!", message, target);
    }

ご参考までに。

Scope (AsTransient, AsCached, AsSingle)

いよいよ本題です！ ZenjectのScopeについて見ていきましょう。

Scope(スコープ)と聞くとやはりプログラミングにおけるスコープが思い当たりますが、Zenjectのスコープもほぼ同じ意味です。
インスタンスのスコープ、つまり参照される範囲を指定 することになります。

Scopeの違い

	AsTransient	AsCached	AsSingle	備考
Context毎のインスタンス数	DI先のクラスごと	BindしたContractType(WithId指定有りの場合はさらにID毎)に1つ	Context毎に1つ	Contextごとに管理

それぞれ掘り下げて見ましょう。

AsTransient

AsTransient は DI先のクラス毎に異なるインスタンスとして渡されます。
渡されたインスタンスはすべて別物なので好き勝手に変更しても、他のDI先には影響しないことになります。

AsTransient確認用UnitTest

以下のような用途に使えます。

メモリ使用量を気にしないからとりあえずDIで挙動を変更したい
DI先ごとに別のインスタンスとして持たせたい(他に影響させたくない)

AsTransient の利用例

DI先にはICollectionとして使用してもらい、バインドでList や LinkedListなどを切り替えるなどの使用方法が考えられます。

    // ListをDIしたい場合
    Container
        .Bind<ICollection<int>>()
        .To<List<int>>()
        .AsTransient();
    Container.Inject(this);

    // LinkedListをDIしたい場合
    Container
        .Bind<ICollection<int>>()
        .To<LinkedList<int>>()
        .AsTransient();
    Container.Inject(this);

    // SortedListをDIしたい場合
    Container
        .Bind<ICollection<int>>()
        .To<SortedList<int>>()
        .AsTransient();
    Container.Inject(this);

DI先のコードを変更することなく性能(LinkedList)や機能(SortedList)を変えることができます。

ICollectionを使用したAsTransientサンプル

AsCached

AsTransient は DI先のクラス毎に同一のインスタンスとして渡されます。
WithIdを指定している場合はIDごとに異なるインスタンスとなります。

AsCached確認用UnitTest

インスタンスの単位は細かくは以下のようになります。

ContractType毎に1つ
ID指定無しは「ID指定無しのグループ」として1つ生成
ID指定有りの場合は、IDごとに1つ生成

    // ID指定無し向けのインスタンス
    Container
        .Bind<IGreeter>()
        .To<ResultTypeGreeter>()
        .AsCached();

    // ID_01向けのインスタンス
    Container
        .Bind<IGreeter>()
        .WithId("ID_01")
        .To<ResultTypeGreeter>()
        .AsCached();

    // ID_02向けのインスタンス
    Container
        .Bind<IGreeter>()
        .WithId("ID_02")
        .To<ResultTypeGreeter>()
        .AsCached();

以下のような用途に使えます。

ResultTypeは同じだけど、DI先のグループごとに異なるインスタンスにしたい
- 後述しますが、AsSingleの場合はResultTypeは1つしか作成されません

AsCachedの使用例

今回はとあるメッセージキューをグループに分けてインジェクションさせてみましょう。

    Container
        .Bind<Queue<string>>()  // Queueは残念ながら専用interfaceなし
        .WithId(Group01)
        // .To<Queue<string>>()  // ContractTypeとResultTypeが同じならToは不要
        .AsCached();

    Container
        .Bind<Queue<string>>()
        .WithId(Group02)
        .AsCached();

インスタンスを受け取る先は引数にId を指定

    public class DITarget01
    {
        private Queue<string> _queue;

        // MonoBehaviourでない場合はIdは引数で指定
        public DITarget01([Inject(Id = Group01)] Queue<string> queue)
        {
            _queue = queue;
        }

        public void Enqueue()
        {
            _queue.Enqueue("Hello");
        }
    }

メッセージキューをグループで別インスタンスとして管理することが可能になります。

Queueを使用したAsCachedサンプル

AsSingle

AsSingle は ResultTypeのインスタンスが単一であることを保証するScopeです。
Singleという単語がついている通りですね。

どう保証するのかというと、同じResultTypeがバインドされたときに例外(ZenjectException)を出すようになっています。

    Container
        .Bind<IGreeter>()
        .To<ResultTypeGreeter>()
        .AsSingle();

    // IDを指定しようが、AsTransientを指定しようが例外を出す
    Container  
        .Bind<IGreeter>()
        .WithId(Identifier01)
        .To<ResultTypeGreeter>()
        .AsTransient();

以下のような用途に使うと良いと思います。

複数のインスタンスを作成したくないResultTypeのバインド
- 複数インスタンスが存在するとおかしくなる(通信に関わる部分など)
- メモリを無駄に消費したくない
複数のインスタンスを作る必要がないもの
- 引数に対して必ず同じ結果を返す(副作用のない)メソッド(関数)を持つResultType
- Strategyパターン、Factoryパターンのクラスなど
Singletonパターンからの移行(理由は後述)

ちなみにですが、FromInstanceを使用するとAsSingleの恩恵がなくなってしまうので、
インスタンスの単一性を保証したいのであればTo<>を使用して、Zenjectにインスタンスを管理させましょう。

個人的には疎結合化がZenjectの主な使用目的のため、AsSingleを一番使用しています。

AsSingleの使用例

いろいろな使用例があるのですが、今回はシンプルに疎結合化の実現で使ってみましょう。

前回の記事の IRandomizerのようにインスタンスは全体で１つのみでいいようなResultTypeに使用すると良いと思います。

余談：Singletonパターンからの移行

AsSingleを見て「Singletonパターンで良くない？」って思った方もいるかもしれません。
DIにすることで様々な恩恵があると考えていますので取り上げたいと思います。

Singletonパターンのデメリット

参照先のクラスと密結合になりテスタビリティが損なわれる
- 参照先の挙動をUnitTest時に変更できない
- 例: StaticClass.Instance.Method()の場合はStaticClassと密結合
Unityで同一シーンの読み込み毎に前回の状態に引きずられてしまう
- 1回目と2回目以降で動作が変わるリスクが生まれる
- 実装が簡単だが、シーンの切り替え毎にリセット処理など注意する点が多い
生成したインスタンスがいつまでも残り続ける(static変数として使用する場合)
- staticオブジェクトが解放されない
- ヒープ領域の整理の際に障害になり得る(極稀な話だと思いますが)
インスタンス生成のタイミングが不定(個人的に嫌いな性質)
- 大抵は初回アクセス時にインスタンス生成
  - if (_instance == null) _instance = new StaticClass();

色々と書きましたが「実装は簡単だけど、注意がかなり必要」なデザインパターンだと考えています。

特にUnityやiOS, Androidのネイティブアプリのように "ライフサイクル" を持つアプリケーション開発においては特に注意が必要です。

Zenject + AsSingleでSingletonの問題を解決

さて、このSingletonパターンですが大体はDIによる移行が可能だと考えています。

Singletonパターンを使う理由の大体は「同一のインスタンスにアクセスしたい」だと思います。

Zenjectを使っているならResultTypeをAsSingleでバインドしてDIすることで、上記デメリットを解消した上で同一インスタンスにアクセスするという要望を満たせると思います。

どうしてもSingletonでないといけないパターンがあるかもしれませんが、
Singletonを使用する理由が「簡単だから」であれば、一度DIの使用を検討してみてください。

プロジェクトが大きくなると密結合のSingletonパターンは。。。

AsSingleの注意点

ExtenjectのREADMEにも記載されていますが、AsSingleは同一のContainer(Context)毎にインスタンスが管理されます。

ProjectContext と SceneContext両方に同じResultTypeをバインドしても例外はでないのでご留意ください。

サンプルシーン Assets/Scenes/GreeterDISample.unity に ProjectContext と SceneContext両方でGreeterをAsSingleでバインドしています。
よかったら動かしてみてください。

簡単なまとめ

AsTransientは挙動は変えたいけど、インスタンスは共有したくないとき
AsCachedはIDグループ毎にインスタンスを共有したいとき
AsSingleはResultTypeのインスタンスを必ず1つだけにしたいとき

に使うといい気がします(超大雑把)

サンプルプロジェクト

github.com

雑感

久々の記事投稿です。
ポートフォリオに集中してたんですが、さすがにネタが溜まりすぎて来たので簡単なやつを１つでも解消したいと思い記事にしました。

Zenjectは使ってて本当に気持ちいいですね～。

Zenjectを使ってて思ったメリットとして「UnityでDIが実現できる」だけじゃなくて「UnityでMonoBehaviour以外のクラスが使いやすくなる」っていうのもあると思います！疎結合にできるライブラリですが、自分自身はZenjectに密結合になっちゃってますね～。

それでは良いUnityライフを！

【Unity】Shader Graphで走査線っぽいもの

2020-09-11T01:06:09+09:00

概要
動作環境
今回作るもの
- 実装機能
シェーダーテクニック
完成形
サンプルプロジェクト
雑感

概要

今回は Shader Graph で走査線っぽいもの作り方を紹介します。併せてシェーダーを作るときの考え方も解説したいと思います！

動作環境

Unity 2020.1.4f1
- Universal RP 8.2.0

今回作るもの

以下の動画の様にスクロールする走査線を作ります。

www.youtube.com

実装機能

せっかくのシェーダなので、パラメータで以下のものを調整できるようにしましょう。

走査線の色
走査線の幅
走査線の速度
走査線の出現頻度
UV座標のV方向に走査線が移動(理由は後述)

シェーダーテクニック

シェーダーを実装する前にいくつかテクニックを紹介します。

UVノードと分離(Split)

[email protected]/manual/UV-Node.html">UVノードは文字通りUV座標を取り出すことができます。
R要素にはU座標、G要素にはV座標が含まれています。

UV座標は[0, 1]の範囲のため、Splitノードで要素をU, Vに分離することでグレースケールのグラデーションを作ることができます。

V要素に関して言えば下方(0の方)が黒、上方(1の方)が白というグレースケールを取り出すことができます。

Fraction

[email protected]/manual/Fraction-Node.html">Fractionノードというものがあります。
「入力数値の小数点を取り出す」ノードとなります。

グラフで表すと以下のような一次関数を並べた感じになります。

Fractionのグラフ(横軸: 入力、縦軸: 出力)

簡単に言うと 0 から 1 (厳密には0.999...) を繰り返すノードを作成することができます。

www.youtube.com

Time + UV + Split + Fraction

www.youtube.com

所謂「UVスクロール」です。

UVをSplitノードで分離することでU or V方向にスクロールするノードとなります。
また、AddノードとSubtractノードでスクロール方向が反転する性質があります。

三角波

www.youtube.com

所謂「三角波ノード」です。

このノード、見た目はシンプルですが 「走査線の幅」の調整とかなり相性が良かったりします。

...クリックで展開：三角波作成の流れ

三角波のイメージ

Fractionを[0, 1] → [-1, 1]に変換して絶対値を取ると、0 → 1 → 0...を繰り返す三角波を実現できます。

三角波 + Step

先程作成した三角波ノードをStepに渡すと以下のようなノードになります。

www.youtube.com

何が言いたいかというと「波の幅をパラメータで設定しやすい」ということです！

...クリックで展開：三角波とStepのイメージ

三角波 + Smoothstep

今回の主役ノードです！

www.youtube.com

三角波はSmoothstepとも相性が良いです。
グラデーション付きの波をシームレスに作ることができます。

余談：Time + Fraction + Smoothstep

stepをであれば"Time + fraction"で十分ですが、 Smoothstepの場合は残念ながらシームレスになりません。
三角波を作った理由は「シームレスな波が必要」だったからなんですね。

波の出現の周期を変える

www.youtube.com

これはUVスクロールの値を周期数で割り、StepのEdgeも同様に周期数で割れば実現できます。

※UVスクロールの値だけだと走査線になる部分の幅が広がってしまいますので、幅も割って調整します。

UVスクロールのスピードを遅らせるということですね。

完成形

上記のテクニックを組み合わせて、プロパティで調整可能にしてアルファ(不透明度)に使用したのが今回のシェーダになります！

www.youtube.com

Githubのプロジェクトに完成形を置いておきますので、良かったらどうぞ。

サンプルプロジェクト

github.com

雑感

今回はShader Graphを題材にしてみました。
記事を書いていて思ったのは「これ、音声解説 + 動画のほうが絶対わかりやすいだろ」でした。。。

別にAviutl使えないわけじゃないんですがちょっとトークに自信がないです。。。
ただ動画のほうが情報をたくさん詰め込めますし、僕みたいに字だとわからなくても動画だと理解しやすい人のほうが多いと思いますのでいつか挑戦してみたいです。

次回ですが、そろそろ以前から考えていたポートフォリオに本格的に集中しようと思いますので、しばらくは投稿頻度は下がると思います。

それでは～。

【C#】え、Generic Interfaceでメソッド引数を設定すれば構造体のBoxingを回避できるの？

2020-08-22T18:29:43+09:00

概要
Constraints on type parameters について
- 例：structで制約を付けた場合
interfaceを継承した構造体のboxing
- intefaceを引数としたメソッドに渡した場合のBoxing
- なぜBoxingが発生したのか
Generic Interfaceによる構造体のBoxingの回避
余談：なぜBoxingが必要なのか
雑感

どうも、最近GC Allocにおびえているすぎしーです。
今日はUnityじゃなくてC#がメインの話題です。

概要

今回はGeneric Interfaceと値型のBoxing回避についてお話します！
Boxingは余計なGC Allocが発生してしまいますが、回避が難しいパターンも存在します。

ただ、一見変わった方法でそのBoxingを回避する方法があったので紹介したいと思います！

Constraints on type parameters について

要するにGenericで指定される型に制約を付けられるC#の機能のことです。

docs.microsoft.com

C#では、where句を使うことでGenericの型に制約を付けることができます。

例：structで制約を付けた場合

例えば、以下のようにwhere T : structとつけると、Tの指定をstruct(構造体)のみに制限させることができます。

public class GenericData<T> where T : struct
{
    T Value { get; }
}

以下のようなコードで確認することができます。

// エラーなし
GenericData<StructSample> structData;

public struct StructSample
{
}

// エラー: The type 'ClassSample' must be a non-nullable value type in order to use it as parameter 'T' in the generic type or method 'GenericData<T>'
GenericData<ClassSample> classData;

public class ClassSample
{
}

// エラー: The type 'IInterfaceSample' must be a non-nullable value type in order to use it as parameter 'T' in the generic type or method 'GenericData<T>'
GenericData<IInterfaceSample> interfaceData

public interface IInterfaceSample
{
}

interfaceを継承した構造体のboxing

C#の構造体はinterfaceを継承することができます。

// ILoggerを継承した構造体
public struct Data : ILogger
{
    public int value;

    public void Log()
    {
        Debug.Log("I am `Data`");
    }
}

public interface ILogger
{
    void Log();
}

さて、このinterfaceを継承した構造体ですが意図しないBoxingがあっさり発生します。。。

var data = new Data { value = 0, };

// ILogger型の変数に構造体Dataを渡す
ILogger logger = data;

...クリックで展開：Boxing発生の確認

UnityのProfilerを使えば簡単に確認できます。

var data = new Data { value = 0 };

Profiler.BeginSample("Profile: Data to ILogger variable");
ILogger logger = data;
Profiler.EndSample()

intefaceを引数としたメソッドに渡した場合のBoxing

先述したBoxingですが、引数の型がinterfaceのメソッドに引数として渡しても発生します。

var data = new Data { value = 0 };

Func(data);  // 引数として渡す

// 引数の型がinterfaceのメソッド
public void Func(ILogger logger)
{
    // 何もしない
}

...クリックで展開：Boxing発生の確認

var data = new Data { value = 0 };

Profiler.BeginSample("Profile: Data as a ILogger variable");
Func(data);
Profiler.EndSample()

public void Func(ILogger logger)
{
    // 何もしない
}

なぜBoxingが発生したのか

そもそも「Boxingは参照型の変数に値型のデータを渡すことで発生」します。

var data = new Data { value = 0 };

// 参照型変数のloggerに値型を渡すためBoxingが発生
ILogger logger = data

interfaceの変数もclass, delegate同様参照型として扱われます。

docs.microsoft.com

interfaceを継承している構造体であって、参照型にするにはBoxingを行って参照型に変換してやる必要があります。

※「なぜBoxingが必要なのか」を後述しています。

Generic Interfaceによる構造体のBoxingの回避

さて、いよいよ本題です！

先述の「intefaceを引数としたメソッドに渡した場合のBoxing」に限っては回避方法があります！
それはFunc(ILogger logger)メソッドを以下のように書き換えるだけです。

public void Func<T>(T logger) where T : ILogger
{
    // 何もしない
}

ポイントは where T : ILogger の部分で"Generic Interface"と呼ばれるものです。

...クリックで展開：Boxing非発生の確認

var data = new Data { value = 0 };

Profiler.BeginSample("Profile: Data as a arg of Generic Interface");
Func(data);
Profiler.EndSample();

public void Func<T>(T logger) where T : ILogger
{
    // 何もしない
}

Generic Interfaceとは

Generic InterfaceはGenericの制約にinterfaceを指定したもののことです。

docs.microsoft.com

上記参考ページでも以下のような記述があり、Generic Interfaceを使うことでBoxingの回避が可能なことがわかります。

The preference for generic classes is to use generic interfaces, such as IComparable<T> rather than IComparable, in order to avoid boxing and unboxing operations on value types.

なぜBoxingが回避されたのか

Generic型の引数は渡されたデータの型になります。

where T : ILoggerとinterfaceの制約が付いたとしてもFunc<T>(T logger)のTはあくまで引数の型、つまり構造体Dataになります。

つまり、「引数Tが値型となり、参照型への変換がそもそも不要のため、Boxingも発生しなかった」ということになります。

逆にFunc(ILogger logger)の場合は引数は参照型で固定のため、値型を渡してしまうとBoxingが発生してしまったということだったんですね。

Generic InterfaceでのBoxing回避はメソッド限定　

この回避方法はメソッドのみ限定で可能です。
後述していますが「メソッドのコールスタック」と「メソッドの引数」は基本的にスタック領域に置かれます。

Generic型に値型を指定した場合、Tは参照型に変換されることなくそのままスタック領域の格納され、メソッドからはその領域のデータにアクセスされます。
メソッドもその引数もスタック領域に置かれているため、実現できた回避方法と言えそうです。

余談: OpCodes.Constrained Field

さらに細かく話すとGeneric Interfaceの場合、以下の特殊なオペコードが使われるようになりスタック領域のデータが参照されるようです。
気になる方はどうぞ～。

docs.microsoft.com stackoverflow.com

余談：なぜBoxingが必要なのか

Boxingは値型のデータを参照型として扱うために必要な機能と言えます（意図しないBoxingの場合は別ですが）。

参照型(objectなど)と値型(struct)の大きな違いとして、その「データを格納する領域」に違いがあります。

	データの格納場所
値型(Value Type)	スタック領域（一時領域）、ヒープ領域（永続領域）の両方
参照型(Reference Type)	基本的にヒープ領域（永続領域）のみ
関数のコールタック(余談)	スタック領域（一時領域）

スタック領域は一時的、ヒープ領域は永続的にデータを保持します。
そして、Boxingは「一時的なスタック領域にある値型」を「ヒープ領域に移して参照型にする」ために行います。

コードとイメージは以下のような感じです。

// ヒープ領域に確保
var loggerHolder = new LoggerHolder();

// ローカル変数のためスタック領域
var data = new Data() { a = 1f, b = 2f, c = 3f, d = 4f, e = 5f };

// dataのBoxingを行い、ヒープ領域確保、データをコピーして永続化
loggerHolder.logger = data

参照型はいつ参照しても期待するデータにアクセスできないといけません。
interfaceの変数は参照型のため、構造体が対象のinterfaceを継承していたとしても必ずヒープ領域に持っていって参照型にしておく必要があります。

これがBoxingが発生する主理由の1つと言えます。 (他にもスタック領域は急に領域を確保できないからヒープ領域を使うなど有りますが、細かくは割愛しますｗ)。

参考: Boxing and Unboxing

雑感

1つのGC Allocの回避を紹介するのに、ずいぶんと長文になってしまいました。。。

記事を１週間以上投稿しなかったのは、夏バテが原因だった気がします（言い訳）。

まあ、使命感でやってるわけではないので気長にやっていきます。

皆さんのC#の知識向上につながれば幸いですー。それでは～。

【Unity】指のポーズをブレンドしてハンドジェスチャーを作ろう

2020-08-10T19:05:02+09:00

概要
動作環境
使用アセット
ポーズの用意
- ポーズの条件
- 用意するポーズ
  - HandOpened
  - ThumbClosed, FingerClosed
ポーズの簡単な作り方
UnityでFBXをImport
- 非ループ化
- Animation Clipから不要なキーフレームを削除
Avatar Mask の作成
AnimatorControllerを作成
動作確認
Additive Reference Pose について
サンプルプロジェクト
雑感

概要

今回は手の指を曲げるアニメーションを組み合わせてハンドジェスチャーの作ってみたいと思います。

UnityにはBlendTreeというアニメーションをブレンドする機能があります。
今回はそのBlendTreeと指のアニメーションを組み合わせることでハンドジェスチャーを実現したいと思います。

動作環境

Unity 2020.1.1f1
Blender 2.83

動作確認可能なプロジェクトを記事の最後に記載します。

使用アセット

Unity-Chan! Model

ポーズの用意

Blenderでモデルを読み込んで、以下のポーズ(BlenderではActions)を作成。

1ポーズに左右の手両方のキーフレーム登録をオススメします。。
後述するAvatar Maskで左右の手のアニメーションを分離できます。

※ポーズの作り方については後述

ポーズの条件

0フレーム目はデフォルトの状態
- 0フレーム目は必ずデフォルト(曲げる前)の状態のキーフレームを登録すること
1フレーム目は対象の指を曲げた状態
- 例えば "IndexFingerClosed" であれば、人差し指のみ曲げた状態

用意するポーズ

HandOpened (いわゆるパーのポーズ、デフォルトのポーズ)
ThumbClosed (親指のみ閉じたポーズ)
IndexFingerClosed (人差し指のみ閉じたポーズ)
MiddleFingerClosed (中指のみ閉じたポーズ)
RingFingerClosed (薬指のみ閉じたポーズ)
PinkyFingerClosed (子指のみ閉じたポーズ)

HandOpened

手がパーのポーズ、いわゆるデフォルトポーズ

ThumbClosed, FingerClosed

5本の指それぞれを個別に閉じている状態のポーズを用意。

※親指、中指、薬指、小指は省略

ポーズの簡単な作り方

※Blenderをある程度触ったことがある人向けです。

以下の流れで、それぞれの指のポーズを作成できます。

初めにグーのポーズを作る
グーのポーズから対象の指以外をデフォルトに戻す

グーから作ることによって、すべての指のポーズをブレンドした時にきれいなグーになると思います。

パーからグーを作る方法

...クリックで展開

Blender グーから一部の指をデフォルトに戻す

...クリックで展開

アニメーションをExport

以下の手順でBlenderからFbxを算出

Export対象のモデルを選択
File -> Export -> FBX(.fbx)
"Selected Objects"を有効にし、"Object Types"を"Armature"のみする
- 今回はスケルトンポーズ(アニメーション)のみを出力したいため、メッシュは除外
Export FBX

UnityでFBXをImport

HumanoidとしてImportして、AnimationをHumanoid向けに変換しましょう。

"Animation Type" を "Humanoid"に変更
"Apply"

非ループ化

Loop Timeなどは無効のままにしてください。
ブレンド中におかしくなってしまいます。

Animation Clipから不要なキーフレームを削除

必須ではありませんが、HumanoidでImportするとすべてのMuscleのキーフレームが登録されてしまいます。
Animation Clipのサイズが削減できるので不要なキーフレームは削除しておきましょう。

HandOpened は指以外のキーフレームを削除
各FingerClosedは対象の指以外のキーフレームを削除

HandOpened のキーフレーム（修正後）

IndexFingerClosed のキーフレーム（修正後）

Avatar Mask の作成

UnityではAvatar Maskを使ってアニメーションの適用範囲をマスクで制限することができます。

"Project"上で右クリック -> "Create" -> "Avatar Mask"
アニメーションはループさせない(Loop Time チェックボックスをオフ)
- プレイ中に大変なことになります
左右の手それぞれの Avatar Mask を作成

左手用 Avatar Mask

右手用 Avatar Mask

AnimatorControllerを作成

前置きが長かったですがいよいよ本題です。
これまで用意したAnimation(ポーズ)をブレンドするAnimationControllerを用意して、ハンドジェスチャーを作っていきます。

ブレンドの方針

AnimatorControllerのレイヤーを使用
"Blending" を "Additive" にし、ベースポーズからの加算によってポーズの組み合わせを実現

簡単に言えば"パー" から"指を曲げるポーズ"を加算することで、ジェスチャーを実現する方針になります。

ベースポーズ用レイヤーを作成

レイヤーを追加
Weightを1, Maskに左手用Avatar Mask, BlendingをOverrideに設定
DefaultStateのアニメーションに "HandOpened" を指定

これでBase Layerの左手のアニメーションが常にパーに上書きされる形になります。

加算用レイヤーを作成

レイヤーの作成

レイヤーを追加
Weightを1, Maskに左手用Avatar Mask, BlendingをAdditiveに設定
DefaultStateにBlendTreeを指定

BlendTreeの設定

ParametersにCloseThumb_L, CloseIndex_L... の様に左手の指ごとのパラメータをfloatで用意
- 右手の指の場合はCloseThumb_R, CloseIndex_R...
"BlendType" に "Direct" を指定
Motionを5つ追加し、各指のアニメーションとパラメータを指定

動作確認

それでは作ったAnimatorControllerをユニティちゃんのAnimatorに入れて動作確認してみましょう！

www.youtube.com

うまくいきました！

Additive Reference Pose について

Blenderでアニメーションを作る際、「0フレーム目はデフォルトの状態」という条件を加えました。実はこれ、"Additive Reference Pose"というものが関係しています。

Additive Reference Pose とは

平たく言えば「Additive(レイヤー)で使用する際にベースとなるポーズ」のことです。

残念ながら"Additive Reference Pose"の明確なドキュメントは見つかりませんでした。。。(知っている方いらっしゃいましたら教えてください！！！)

デフォルトのAdditive Reference Pose

AnimationUtility.SetAdditiveReferencePoseのページにこんな説明があります。

By default any animation clip used in an additive layer use the pose at time 0 to define the reference pose

つまり、"Additive Reference Pose"はデフォルトではそのAnimation Clipの0フレーム目のポーズになるということです。

これが「0フレーム目はデフォルトの状態」という条件にした最大の理由になります。

余談：Additive Reference Pose を明示的に指定する方法

一応、Additive Reference Pose は明示的に指定する方法があります。

ただ、どれも扱いやすいとは言えないと個人的には思います。。。
ブレンド前提のAnimation Clip は素直にベースのポーズを0フレーム目に指定したほうが良いと思います。

FBXのImport時に指定

以下の方法を使用すると、同一Animation Clip内で0フレーム目以外を"Additive Reference Pose"として指定できます。

FBXをInspectorで確認し、"Animation"タブを開く
下部に"Additive Reference Pose" のチェックボックスをオンにする
Pose Frameを指定

Debug Inspectorで指定

実はDebug Inspectorにすると、Animation ClipのInspectorに"Additive Reference Pose"を指定する欄が表示されます。

InspectorをDebug化
"Additive Reference Pose Clip" と "Additive Reference Pose Time" を指定
"Has Additive Reference Pose"のチェックボックスをオン
- オンにしていないと"Additive Reference Pose"が有効になりません

AnimationUtility.SetAdditiveReferencePoseを使って指定

※個人的には非推奨

AnimationUtility.SetAdditiveReferencePose を使うことで指定できます。
別のAnimation Clipも指定可能です。

AnimationUtility.SetAdditiveReferencePose(targetClip, referenceClip, poseTime);

メソッド呼び出しの結果を確認したい場合は、前述したDebug Inspectorで確認して下さい。

また、以下のようなツールも作ってみました(プロジェクトにいれています)。
複数のAnimationClipでまとめて"Additive Reference Pose"を指定できます。

ツールの注意点

Set/Reset を繰り返すと以下のようなエラーを吐くことがあります。
こうなるとUnityを再起動しないとうまく動作しません。。。

原因不明なので何か知っている人は良かったら教えてください。

サンプルプロジェクト

github.com

雑感

今回はBlender, Animator, Animation Clip, Additive Reference Poseと詰め込みすぎ感がありますねｗ。
有料アセット使えばUnity内で完結できたと思うんですが、無料でできるようにしたかったのでBlenderも入れてみました。

今回の記事の経緯は手のアニメーション作ってるときに「あれ、これアニメーションの組み合わせでできんじゃね？」と思ったことですね。

Animationの用意やAnimatorの調整など、面倒な部分もありますがモデルに適したAnimation Clipを使えることがメリットでしょうか。
AnimatorControllerOverrideを使えばモデルごとにAnimationClipを設定することも可能です。

"Additive Reference Pose"についてはいいドキュメントが見つからなかったので調べるのがちょっと大変でした。

今のところ手のジェスチャー以外にいい組み合わせは思いつかないですが、何かよさげな応用例があれば教えてください！

それでは～。

【UniRx】UniRxのDelayFrameが初回だけ1フレーム余計に遅延する問題と解決方法

2020-08-07T21:12:25+09:00

概要
UniRxについて
DelayFrameの問題について
- 現象の確認方法
問題の原因
- 簡単に言うと
- 詳細に言うと
バグではないの？
- 制限事項とする理由
- 余談：修正できないの？
問題の回避
余談2：起動したコルーチンはどうなるの？
雑感

概要

UniRxでストリームを遅延させるDelayFrameを使用した場合に初回だけOnNextが1フレーム余計に遅延する現象がありました。
今回はその現象と解決方法を紹介したいと思います。

UniRxについて

github.com

Unityで使用可能なReactive Extensionsライブラリ。

Reactive Extensionsについては今回は詳しく触れませんが、
独特のクセがあり慣れない人には最初戸惑うと思いますが、使えるといろいろと捗ります！！！

DelayFrameの問題について

現象を詳しく説明すると

Subject.DelayFrame(N)によりNフレーム遅延するSubject(Observable)を生成
上記SubjectをSubscribeする
Subject.OnNext(...)により値を流す
初回のOnNextのみ「N+1」フレーム遅延して値が流れてくる
- 2回目以降のOnNextは指定通り「N」フレーム遅延

現象の確認方法

以下のコードを使用してSubscribe, OnNextを意図的に発生させて確認

...クリックでコードを展開

Aで`Subscribe`, Z, Xで`OnNext`

using System;
using UnityEngine;
using UniRx;

public class DelayFrameTest : MonoBehaviour
{
    private Subject<string> subject = new Subject<string>();

    private IObservable<string> observable;

    private IDisposable disposable;
    
    void Start()
    {
        observable = subject.DelayFrame(1);
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.A)) {
            Debug.Log(Time.frameCount + ": Subscribe Start");
            disposable = observable.Subscribe(s => {
                Debug.Log(Time.frameCount + " onNext: " + s);
            });
            Debug.Log(Time.frameCount + ": Subscribe End");
        }

        if (Input.GetKeyDown(KeyCode.Z)) {
            Debug.Log(Time.frameCount + ": Inputed Z Start");
            subject.OnNext("Input Z");
            Debug.Log(Time.frameCount + ": Inputed Z End");
        }
    }
}

DelayFrame(1)で1フレーム遅延を指定しています。

上記コードをA -> Z -> Z と入力した時の結果です。
Z入力が1021、OnNextがコールされたのが1023 と2フレームの差がついています。

問題の原因

簡単に言うと

UniRxは裏側でUniRx専用のDispatcher(スレッドの処理を管理するオブジェクト)を使用
そのDispatcher生成は遅延処理などが必要になったときに実施
Dispatcherの仕事は生成したフレームの次フレームから行われる

簡単に言えばこのような動きになるため、初回のみ1フレームずれます

詳細に言うと

初めてDelayFrameなどの遅延処理が発生した時にMainThreadDispatcherというオブジェクトが生成される
- Hierarchyで確認可能(DontDestroyOnLoad以下に存在)
- アプリケーション終了まで存続
DelayFrameなどの遅延処理が初めて発生した時にMainThreadDispatcher.StartCoroutineがコールされる
- UniRxのDispatcherはMonoBehaviourのコルーチンを使用して実現している
コルーチンはwhile(true)とyield return nullでRun()のループ処理を行う
- Run()内で遅延処理、および遅延後のOnNextをコールする
- yield return null -> Run() の順番でループする(コードはこちら)

StartCoroutineした直後にyield return nullがあり、
次のフレームから遅延処理が始まるため、
初回のみ1フレーム遅れる現象が起きます。

バグではないの？

バグではあると思います。

ですが、個人的には
「制限事項」としてとらえたほうが良いと思います。

制限事項とする理由

これはUniRxなりの気遣いの結果、生まれてしまった問題だと思ったからです。
コードを読むと「遅延処理を必要としないならDispatcherは生成しない」という設計が見て取れます。

また、「初回だけなら気にしない」もしくは「1フレームぐらいずれてもいい」という場合にも問題にはなりません。

そして、後述しますが問題の回避が簡単です。

余談：修正できないの？

難しいと思います。

というのもUniRxという使われる側からすると初回のDelayFrameなどが「どこからコールされるかわからない」からです。

コルーチンを使っている関係で、FixedUpdate, Update, LateUPdateなど、どこから呼ばれるかによって初回の処理のみ差異が生まれてしまいます。

だったら初回のみ特別扱いせず、1フレーム後からRun()を開始したほうがよほど合理的だと思います。

問題の回避

この問題、結構簡単に解決できます。

Dispatcherの生成を真っ先に行えば良いだけです。
以下に紹介するMonoBehaviourをオブジェクトにアタッチして初期シーンに配置すれば問題を回避できます。

方法1. `MainThreadDispatcher.Initialize()`をコール

見た目の通りMainThreadのDispatcherを初期化します。
コール時にStartCoroutineも実施されるため、DelayFrameする前に初期化を完了できます。

using UnityEngine;
using UniRx;

public class UniRxThreadStarter : MonoBehaviour
{
    void Start()
    {
        MainThreadDispatcher.Initialize();
    }
}

方法2. `Scheduler.SetDefaultForUnity()`をコール

※個人的には非推奨

これも結果としてMainThreadのDispatcherを初期化することになります。
こちらはもっと広い範囲でスレッド周りの初期化を行います。
主にUnitTestで使われているようです。

ただ、注意点としてWebGLだとおかしくなるかもしれません。
こちらのような記述があるのですが、上記メソッドだとそれに反するスレッドが使用されてしまいます。

using UnityEngine;
using UniRx;

public class UniRxThreadStarter : MonoBehaviour
{
    void Start()
    {
        Scheduler.SetDefaultForUnity();
    }
}

方法3. Scheduler, Dispatcherが初期化されるPropertyを呼び出し

以下のPropertyは初回呼び出し時にScheduler, Dispatcherが初期化されるようになっています。
予めいろいろな初期化を済ませておきたい人にはオススメのやり方かなと思います。

using UnityEngine;
using UniRx;

public class UniRxThreadStarter : MonoBehaviour
{
    void Start()
    {
        // Propertyの初期呼び出しで初期化が実施される
        var immediate = Scheduler.Immediate;
        var currentThread = Scheduler.CurrentThread;
        var mainThread = Scheduler.MainThread;
        var threadPool = Scheduler.ThreadPool;
    }
}

回避策の結果

初回のOnNextも2回目以降と同様に指定通りの遅延になりました。

余談2：起動したコルーチンはどうなるの？

少なくともUniRx v7.1.0 時点ではアプリケーションが終了するまで残り続けます。
StopCoroutineなどコルーチンを止める処理も見当たりませんでした。

再起動がないなら割り切ってさっさと起動させてしまうのも手かなと思います。

雑感

今回はUniRxを取り上げてみました。

個人的には厳密なフレーム単位の遅延を考えるのが好きだったりするので、今回の現象は興味深くもありすごく気になる部分でもありました。

初期化処理はなんだかんだ特殊な処理が生まれるので、
UniRxにも諸々の初期化を実施してくれるメソッドがあってもいいかなと思ったりしました。

何にしろこれからもお世話になるライブラリかなと思います！（最近更新されてないのが気になりますが）

それでは～