UnrealGameSyncを使ってみる

# UnrealGameSync

　UnrealGameSyncはEpic Gamesが推してるUnreal Engineエディタの更新システムです。Epic Games内でのFortniteの開発のために作成されたものということで、非常によくできたシステムなのですが、公式ドキュメントを読んでもなんかよくわからない、セットアップが複雑、何がメリットなの？といった意見も多く、実際に使われているケースは少ないように思えます。
　 [公式ドキュメント](https://docs.unrealengine.com/5.3/ja/unreal-game-sync-ugs-for-unreal-engine/)はこちらですが、4.27からあまり更新もされておらず、正直わかりやすいとは言えないかと思います。それもあってか、検索してもあまりヒットせず情報が少ないし、動く状態まで持っていくまで手間がかかり、システムが複雑なため非常にとっつきが悪いのですが、使ってみると感心するところも多く、面白いシステムなので、実際に使える状態まで解説してみようと思います。

 # 前提条件

　Unreal Game Syncは長いので、以下適宜UGSと表記します。Perforceもp4と表記します。UGSを運用するには以下の環境が必要です。
 - Perforce Server
 - Unreal Engineのソースコード一式
 - Windows PC(Win10以上)
 - Visual Studio

　通常ならp4サーバーと開発環境は別PCに構築しますが、この記事ではシンプルに検証目的なので一台のPCに開発環境とp4サーバーを構築して解説します。p4サーバーは5 user 20 Workspaceまでは無料で使用できます。[Helixのサイト](https://www.perforce.com/downloads/helix-core-p4d)からダウンロードしてインストールしてください。p4サーバーの構築に関してはこの記事では触れません。昔書いた[記事](https://qiita.com/dgtanaka/items/bfacaff81faf34d21538)が参考になるかもしれません。
　UEのソースコードはGitHub版でもEpic Gamesのp4サーバーから取得したものでもどちらでも構いませんが、この記事ではGitHub版で進めます。GitHubから取得してSetup.batを実行した状態を丸ごとp4に登録しておきます。ビルドしていないのでこの状態ではまだエディタは起動できません。GitHub版はSetup.batを実行しておかないとビルドに必要なファイルがインストールされないのでこれだけは実行しておいてください。UGSの動作を検証する目的なので、エディタをビルドしたバイナリをp4にサブミットはしません。UGSが最新のエディタバイナリを更新してくれる状態を目指します。
　この記事ではUEのバージョンは5.3.2、ビルドそのものは必要なのでVisual Studioの2022Community Editionを使用しています。

 ## UnrealGameSyncをビルドする手順
　Unreal Game Sync関連のファイルは *Engine\Source\Programs\UnrealGameSync\\* 以下に配置されています。
　ビルドするには **UnrealGameSync.sln**をVisual Studioで開いてビルドします。MetadataServerのビルドはエラーが出ることがあります。.NET Framework 4.6.2をインストールするとビルドできたりしますが、使わない人はとりあえずスルーしてヨシ。公式ドキュメント見ると
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/082c89da-642c-36c6-b766-6c17c3627233.png)
　とありますが、普通の個人はWindows Serverなんて持ってませんし、筆者も持ってないのでとりあえずスルーしておいても良いです。Metadata Serverに関しては後ほど触れます。

:::note warn
GitHub版でSetup.batを実行していないとUGS本体もビルドに失敗します。Setup.batでダウンロードされるアイコンなどのファイルが必要だからです。
:::

# 使ってみる
  ビルドして起動するとこんな画面が出ます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/f95370c7-2e82-b717-7b91-94b9b9a0d0e5.png)

## Application Settings
　Application Settings...をクリックしてp4サーバーの設定をします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/b7752833-6c17-8f64-cfed-10e754f96e3d.png)

:::note
Perforceの設定関係はp4 setで設定しておくとそちらが参照されます。なるべく設定しておくと手間が減ります。
p4 set P4CHARSET=utf8-bom
など、文字エンコーディングを設定しておかないと日本語のサブミットログが文字化けするので注意。
:::

### Startup and Shutdown
　起動と終了に関するオプション

#### Automatically run at startup
　チェックするとPC起動時に自動でUnrealGameSyncが起動します。
#### Keep program running in the system notification area when closed
　チェックするとアプリを終了しても常駐し続けます。完全に終了するにはタスクトレイから終了させる必要があります。

### Default Perforce Settings
　p4サーバーの設定です。

#### Server
　p4サーバーのURLを設定します。画像は同PCにサーバーを設定したのでポート番号のみです。
#### User
　p4のユーザーアカウントです。
#### Parallel sync threads
　p4の同期スレッド数です。この辺はp4のドキュメントを見てください。

### Updates
　UnrealGameSyncのアップデートに使用するデポを設定します。（後述）

## Open project
　次にOpen project...をクリックしてプロジェクトを指定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/909fd13b-c776-74c1-ce15-ac5b9323b8ac.png)
　WorkspaceのNameに目的のプロジェクトのワークスペース名、Pathにビルド対象のプロジェクトを指定します。ここではLyraをビルドすることにします。

　設定してOKを押すととりあえずメイン画面が表示されます。
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/c4d91409-43ba-fa88-4aeb-f67f5ed963f5.png)
　チェンジリストには、GitHub版Unreal Engineを複数回に分けてp4にサブミットして最後にReconciled Offline workで漏れが無いか確認した状態になっています。
　この状態でp4との同期とかビルドとかできます。After syncingのチェックボックスで同期後の動作を設定できます。ビルドして実行したり、Visual Studioでソリューションを開いたり、上部のリンクでExpolorerを開いたり、ひととおりの動作は可能です。個人運用ならこれでもそれなりに便利に使えます。

:::note
 　slnファイルへの関連付けがRiderになっていればRiderが開きます。筆者はRider推しです。
:::

　この状態でもp4のワークスペース同期ツールとして使えますが、UnrealGameSyncの目玉機能、Precompiled Binariesを使えるようにしたいので、ここからはそのための作業を解説します。
　OptionsからUGSの様々な設定ができるのですが、Sync Precompiled Binariesがグレーアウトしていて選択できません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/21c96259-81fe-6a72-000b-00fa65ab4ae0.png)
　使えるようにするには、p4にバイナリ更新用のデポを作成してビルドバイナリーをサブミットする必要があります。
　Precompiled Binariesに関しては[公式ドキュメント](https://docs.unrealengine.com/4.27/ja/ProductionPipelines/DeployingTheEngine/UnrealGameSync/PrecompiledBinaries/)に詳しく書かれていますが、これを参考にLyraのフォルダSamples\Games\Lyra\Build\UnrealGameSync.iniを修正します。自前のプロジェクトのUGS設定が必要な場合は参考にしてBuildフォルダにUnrealGameSync.iniを作成してください。

```UnrealGameSync.ini
[Default]
BuildHealthProject=Lyra

[//test/UE5.3/Samples/Games/Lyra/Lyra.uproject]
;Message=:alert: You can put a message here, including [hyperlinks to docs](http://example.com)
;StatusPanelColor=#9b49cc
ZippedBinariesPath=//test/Dev-Binaries/++test+UE5.3-LyraEditor.zip
```
[//test/UE5.3/Samples/Games/Lyra/Lyra.uproject]
の部分は自分のp4サーバーのパスに合わせて修正します。
ZippedBinariesPath=//UnrealEngine/Dev-Binaries/++UnrealEngine+GitUE-LyraEditor.zip
はPrecompiled BinariesのZipファイルのp4 Stream上のパスを指定しますが、後半の+は/に置換されます。
++UnrealEngine+GitUE+LyraEditor.zipは実際のエディタバイナリが作られるStreamの名前の/を+に置き換えたものを指定します。この辺少しわかりづらい。詳しく説明するとこの場合はPrecompiled Binariesをzipにアーカイブしたファイル名がLyraEditor.zipで、そのzipを作成するStreamが//UnrealEngine/GitUEで、zipがアップロードされるStreamが//UnrealEngine/Dev-Binariesということです。ファイル名に/を含めることができないため+を/に変換するという実装になっていると思われます。
　Precompiled Binariesが無事p4に登録されるとこんな感じになります。
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/7c4166a2-6349-0514-27b1-1f7fefd6bb8e.png)

:::note
　今回不要なので、Messaage=とStatusPanelColor=をコメントアウトしていますが、これを設定しておくとUGSの画面にチーム向けのメッセージが表示できます。p4で同期しているので、プロジェクト開発状況にあわせてMessageを変更してメンバーに情報を通知できます。URLも仕込めるので開発ホームページへ誘導できたりとなかなか便利です。
:::

　さて、実際にPrecompiled BinariesをビルドしてzipにしてStreamにアップロードする一連の作業が必要になるのですが、あらかじめBuildGraphのスクリプトが用意されているのでそれを使用すれば簡単に実行できます。その前に、ビルドがアップロードされるStreamはp4サーバーにあらかじめ作成しておきます。Streamを作成したら
```
Engine\Build\BatchFiles\RunUAT.bat BuildGraph -Script=Engine/Build/Graph/Examples/BuildEditorAndTools.xml -Target="Submit To Perforce for UGS" -set:EditorTarget=LyraEditor -set:UProjectPath=Samples/Games/Lyra/Lyra.uproject -set:ArchiveStream=//test/Dev-Binaries -p4 -submit
```
　Engineフォルダがある場所で上記コマンドを実行します。

::: note info
エディタにCrashReportClientを含めたい場合は
-set:AdditionalTools=CrashReportClientEditor
を加えると良いみたいです。
:::

::: note info
BuildGraphは後で説明しますが、xmlに記述したスクリプトを使ってビルドや自動作業ができる便利なものです。
詳しくは[公式ドキュメント](https://docs.unrealengine.com/5.3/ja/buildgraph-for-unreal-engine/)を参照してください。
:::

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/44a5e4b6-8b36-ed27-9818-b832884d7eb4.png)
　これが出る場合はpdbcopy.exeがインストールされていないので、Windows Driver Kitをインストールしましょう。
[Windows Driver Kit (WDK) のダウンロード](https://learn.microsoft.com/ja-jp/windows-hardware/drivers/download-the-wdk)
　のページの **手順 3: WDK をインストールする** のリンクからダウンロードできます。インストールするだけで、パスを通したりは不要です。
　pdbcopyはデバッグシンボルのプライベートシンボルを削除してシンボルファイルを軽量化するものです。詳しいデバッグ情報は取れなくなりますが、コールスタックは取れます。必須では無いですが、シンボルファイルはそのままだとエディタ全体で数百メガバイトになったりするので配布用のバイナリのシンボルを軽量化する目的で使用されています。
　ビルドが成功するとコンパイルされたバイナリがzipにまとめられてStreamにアップロードされます。
　ここまでうまく設定とビルドができていれば、Unreal Game Syncでリビジョンを選択して同期することでコンパイル済みのバイナリを適用することができるようになります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/dc45acc2-4c83-0c94-6470-4d67c5e8e02e.png)
　画面中央の領域はPerforceのチェンジログが表示されていて、リビジョン番号やサブミット時のコメントなどが確認できます。左端のTypeのところに、CodeとContentのどちらか、または両方が表示されていますが、Codeはソースコードがサブミットされたチェンジリスト、Contentはソース以外のアセットなどがサブミットされたチェンジリストを表します。Codeがサブミットされるとエディタのビルドとバイナリの更新が必要なので、Precompiled Binariesが作成されていないとそれ以上新しいリビジョンへの同期ができなくなります。つまりビルドされていないエディタより新しいリビジョンに更新することはできません。この機能のおかげでアーティストなどが正しく動くエディタで作業できるというわけです。
　MetaDataServerまでセットアップされていれば、リビジョンにコメントやビルドの正常性をマークしてチームで共有することができます。複数のリビジョンで作業する場合には非常に有用ですが、やや導入難易度が高いです。一応このあとでトライします。
 　Precompiled Binariesの作成もJenkinsなどで自動更新されるようにしておけば、常に最新のエディタ環境に更新でき、Perforceにビルドしたバイナリをサブミットする必要が無いのでコンパクトな運用が可能になります。筆者の業務ではソースコードがサブミットされたらTeamcityでPrecompiled Binariesのビルド処理が走るようにしています。
# Unreal Game Syncは何をしている？
　さて、ここまでで一応UGSが動作するようになったので、UGSがどういう風に動作しているかを解説します。
## Precompiled Binariesの生成
　Build GraphはUGSの機能では無いですが、UUGS用のPrecompiled Binariesを生成するにはBuild Graphを使用します。ビルドの流れは以下のようになっています。詳しい流れはBuild Graphのスクリプトファイルを読むのが良いのですが、おおざっぱに解説すると
### 1. Update Version Files
　バージョンファイルを更新します。具体的にはEngine/Build/Build.versionファイルを更新します。こんな内容のファイルです。
```Build.version
{
	"MajorVersion": 5,
	"MinorVersion": 3,
	"PatchVersion": 2,
	"Changelist": 0,
	"CompatibleChangelist": 0,
	"IsLicenseeVersion": 1,
	"IsPromotedBuild": 1,
	"BranchName": "++UnrealEngine+GitUE"
}
```
　エンジンのバージョン番号と追加の情報がいくつかあります。
　ChangeListとComapatibleChangelistはアセットのバージョンを細かく管理するものです。ChangeListがエディタがビルドされたときのリビジョンで、CompatibleChangeList移行のアセットに対応しているといった感じのようです。厳密なりビジョン管理には有用ですが、面倒なら0にしておけば無視されます。
　IsLicenseeVersionはUEの商用版かどうかのフラグ。EpicGamesLauncerやGitHubから取得したUEには付いていないみたいです。
　IsPromotedBuildはビルド済みで配布されるかどうかのフラグ。EpicGamesLauncherからインストールしたUEなどはこのフラグが有効になっているみたいです。
　BranchNameは通常このエンジンのPerforce上のStreamパスが入ります。エディタ起動時のスプラッシュや、エディタ起動後に右上に表示されたりします。エディタ右上に表示される場合は+は/に変換されます。
　IsLicenseeVersionなどはビルド時のBuild Graphスクリプトのオプションで設定できたりします。Build.versionに関しても色々と知っておいた方が良い内容があるのですが長くなるのと調査中なのでまた改めて記事にしたいと思います。

:::note warn
Build.versionはPrecompiled Binariesのパッケージに含まれないので、プロジェクトの運用にあわせてカスタマイズしてサブミットしておくと良いです。
:::
 
### 2. Compile Tools Win64
　エディタの実行に必要なツール系のビルドをします。シェーダーをコンパイルするときに使用するShaderCompileWorkerなどが該当します。

### 3. Compile Editor
　エディタをコンパイル・ビルドします。

### 4. Tag Output Files
　必要なファイルにタグを付与してリストアップします。

### 5. Submit To Perforce For UGS
　4でリストアップされたファイルを作業用フォルダにコピーし、シンボルをストリップしてzipファイルにアーカイブしてPerforceにアップロードします。

　以上の手順でエディタ起動に必要なバイナリファイルがビルドされ、zipに固められてPrecompiled BinariesとしてPerforceにサブミットされます。UGSはサブミットされたビルド済みバイナリのコメントからリビジョン番号を読み取り画面の表示を更新します。
 
## UGSで同期
　UGSがプロジェクトを同期する際は以下の流れになります。

### 1. コンテンツの同期
　p4から指定のリビジョンのファイルをワークスペースに同期します。
### 2. Precompiled Binariesの同期
　ビルドされたコンパイル済みバイナリをPerforceからダウンロードし、ワークスペースにコピーします。
 
　以上の動作でワークスペースに含まれていない、リビジョンの実行ファイルやdllなどのバイナリが展開されます。これでエディタのコンテンツと実行ファイルなどが目的のリビジョンに同期されて、エディタが起動して作業できる状態になります。

# UGSを使う利点と欠点
　UGSを使うと何が嬉しいかという点をまとめると以下のようになります。（嬉しいを使ってみたかった）

 - ビルド環境が無いアーティストなどのPCでも安定したビルド済みのエディタを同期して起動できるようになる
 - 複数のリビジョンを切り替えることも可能、不安定なバージョンの場合を避けて作業したい場合など
 - エディタのリビジョンとコンテンツのリビジョンを同期することができるので、正しい組み合わせのエディタとコンテンツで作業ができる
 - コンパイル済みのバイナリがzipファイルにまとめられているので、同期するファイル数が少なくて済むため、同期時間やストレージが節約できる
 - エンジン配布時やプラグイン構成を変えたときに必要なバイナリファイルの変更を考慮する必要がなくなる。プラグインを追加したけどバイナリをサブミットするのを忘れたり、Binaries/DotNETフォルダのファイルをどこまでサブミットするべきかとか悩まなくて良いのは楽ちん
 - UGSは起動中に自動更新されるので、新しいリビジョンがサブミットされたり、他のメンバーの作業がリアルタイムに確認できる

　反面、欠点としては

 - UGSの操作がわかりにくい。ドキュメントも少ないのでとっつきにくい
 - Precompiled Binariesが作られていないと、新しいコンテンツと同期できない
 - BuildGraphについてある程度の理解が必要など、環境構築のハードルが高い

　などが挙げられます。とは言え多くは慣れの問題かと思うので、使い方に慣れてしまえば非常に便利で合理的に最新のエディタが使用できます。使えるようになるまでのハードルが高く、何やって良いかわからないので敬遠されているのでは無いかと思います。Wizardとかでもっと簡単に導入できれば普及するかもしれないですね。
 
# Unreal Game Syncのインストーラーを作成する
　UGSの配布用のインストーラーを生成することができます。
 Engine\Source\Programs\UnrealGameSync\Installerフォルダに移動し、Build.batを実行することでインストーラーが生成されるので、これを各メンバーに配布することでUGSを共有できます。
　ただし、実はインストーラーに含まれるのはUnrealGameSyncでは無く、UnrealGameSyncLauncherという、UGSを更新して起動するためのプログラムです。UGS本体は指定したp4のデポから取得されます。なのであらかじめビルドしたUGS一式をデポに登録しておく必要があります。具体的には適当なデポを作成してEngine\Source\Programs\UnrealGameSync\UnrealGameSync\bin\Release\net6.0-windows\
内のファイルをすべて登録しておけば良いです。UGSのドキュメントには
```
//depot/UnrealGameSync/Release/UnrealGameSync.exe
//depot/UnrealGameSync/Release/UnrealGameSync.exe.config
//depot/UnrealGameSync/Release/UnrealGameSync.pdb
//depot/UnrealGameSync/Release/Ionic.Zip.Reduced.dll
```
と指定されていますが、ドキュメントが古いみたいでファイル構成が一致しません。なので不要なファイルが含まれているかもしれませんが、上記フォルダのファイルをすべてサブミットしておくのが無難かなと思います。ここでは//test/UnrealGameSyncというStreamを作成して、Releaseフォルダに上記フォルダのファイルをすべてサブミットしています。
　UGSが登録されているパスはソースコードに直接設定しておくと起動時に自動で取得されます。
 ```DeploymentSettings.cs
 		public string? DefaultDepotPath => "//test/UnrealGameSync";
```
　取得された最新のUGSは
   C:\Users\ユーザー名\AppData\Local\UnrealGameSync\Latest\
　に保存され、ここから起動します。
　インストーラーを作成する前に上記設定をしておくと良いです。
  その他UnrealGameSyncの設定も上記のフォルダのひとつ上の階層に保存されます。

:::note warn
　UnrealGameSync.msiでインストール時にキャンセルするとインストールはされるけど設定はされてない状態になり、以後UnrealGameSync.msiを実行しても何も起きない状態になることがあります。そんなときはWindowsのメニューからUnrealGameSyncを検索してアンインストールしてから再度実行してみましょう。
:::

　インストーラーを使ってインストールするとWindowsのスタートメニューに登録されるので、スタートメニューからUnreal Game Syncを起動することができるようになります。
 
 # UnrealGameSyncCmd
 　UGSのコマンドラインバージョンもあります。こちらもなかなか機能豊富でバッチ処理やインハウスツールから呼び出すのに良さそうですが、ドキュメントが無いので自分で使い方を調べる必要がありそうです。この記事では深くは触れません。
## ビルド
　UGSのソリューション内のプロジェクト:UnrealGameSyncCmdをビルドすると、ugs.exeが出来上がります。ugs.exeを実行すると次のようなヘルプが表示されます。

```ugs.exe
 Usage:

  ugs init [stream-path] [-client=..] [-branch=..] [-project=..] [-server=..] [-user=..]
    Create a client for the given stream, or initializes an existing client for use by UGS.

  ugs switch [project name|project path|stream] [-force]
    Changes the active project to the one in the workspace with the given name, or switches to a new stream.

  ugs changes [-count=..] [-lines=..]
    List recently submitted changes to the current branch.

  ugs config [-server=..] [-user=..]
    Updates the configuration for the current workspace.

  ugs filter [-reset] [-include=..] [-exclude=..] [-view=..] [-addview=..] [-removeview=..] [-allprojects|-onlycurrent]
        [-gpfallprojects|-gpfonlycurrent] [-global]
    Displays or updates the workspace or global sync filter

  ugs sync [change|'latest'] [-clean] [-build] [-binaries] [-nogpf|-noprojectfiles] [-clobber] [-refilter] [-only]
    Syncs the current workspace to the given changelist, optionally removing all local state.

  ugs clients [-server=..] [-user=..]
    Lists all clients suitable for use on the current machine.

  ugs run
    Runs the editor for the current branch.

  ugs build [id] [-list]
    Runs the default build steps for the current project, or a particular step referenced by id.

  ugs status [-update]
    Shows the status of the currently synced branch.

  ugs login
    Starts a interactive login flow against the configured Identity Provider

  ugs version
    Prints the current application version

  ugs upgrade [-check] [-force]
    Upgrades the current installation with the latest build of UGS.
```

　色々機能があるし、設定難しそうに見えますが、一番手っ取り早いのは実際のワークスペースのフォルダに移動して、そこでugs.exeを実行することです。そうすれば諸々勝手に判定して動いてくれます。まずはワークスペースに移動して
 [ugsのパス]\ugs.exe status
 [ugsのパス]\ugs.exe changes
 とか実行してみましょう。いろいろできそうですが、今回はここまで。

 # Metadata Server
 　UGS本体は概ね使えるようになりました。せっかくなのでMetadata Serverも試してみたいと思います。とは言え筆者はWeb系の経験があまりないので手探りです。
　ドキュメントにはWindows Serverと書いてあるのですがとりあえずローカルPCのWindows 11でも動かすことができました。Web DeployというサーバーにWebアプリを発行する仕組みがWindows Server相手じゃないとダメなのでWindows Serverを指定されているみたいですが、Metadata Serverを起動するPCでビルドして同じPCにデプロイ（発行）するならWindows Serverでなくても運用できるみたいです。
　Metadata Serverがあると、UGS上から各リビジョンにGood/Badのバッジをつけることができ、コメントを加えることもできます。安定したビルドなのか問題があるのかをチーム内に共有することができる便利なものです。PostBadgeStatusというツールでステータスを送ることもできるので、ビルドサーバーでビルド失敗したCLに失敗マークを付けることでメンバーが失敗したビルドを取得することを防ぐことができます。これを使って自動テストをパスしたCLをマークしたりするのも良さそうです。
　Metadata Serverを機能させるには２つの技術が必要になるので簡単に説明します。細かい用語は各自調べてください。要するにインストールが必要なものが２つあるということです。

 ## IIS
　IISはWindowsに組み込まれているWebサーバーシステムです。Windows PCをWebサーバーとして設定することでネットワーク内の他のPCやインターネットごしに制御することができます。デフォルトでは無効になっているので有効化してください。

## MySQL
　MySQLはリレーショナルデータベースを構築できるシステムです。インストールすることでWindows上でデータベースが使用できます。

　IISとMySQLはどちらもWindows ServerがインストールされたPCにセットアップすることが想定されています。チーム内の各メンバーがそのPCにネットワーク越しにアクセスすることでUGS上でのビルドのステータスを共有する目的です。ということで本来は別PCにインストールするものですが、ここではUGSと同じPCにセットアップしてみます。
 　Metadata Serverの構築まで触れている記事はほとんど無く、[こちら](https://github.com/p4misc/memo/blob/master/MetadataServerMemo.md)が数少ない貴重な資料で参考にさせていただきました。IISのセットアップも参考になります。とは言え、ちょっと古い記事なので今のUGSとは少々変わっているところもあるので改めて解説します。

## IISのインストール
　こちらは詳しく説明しません。難しくないので適当にググってください。ASP4.8の有効化も必要です。
## MySQLのインストール
　こちら注意が必要なのはUE5.3時点では最新バージョンをインストールするとうまく動かなかったことです。これでかなりの時間を消費してしまいました。なので問題のなかったバージョンをインストールする手順を示します。
[MySQLのダウンロードページ](https://dev.mysql.com/downloads/installer/)を開き、Archivesタブを選択します。Product Versionで8.0.26を選択して、Downloadをクリックしてインストーラーをダウンロードします。
　あとは普通にインストールしてください。
　もう一つ注意点としては、公式ドキュメントの[トラブルシューティング](https://docs.unrealengine.com/5.3/ja/unreal-game-sync-reference-guide-for-unreal-engine/#%E3%83%88%E3%83%A9%E3%83%96%E3%83%AB%E3%82%B7%E3%83%A5%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0)を読むと**ONLY_FULL_GROUP_BY を無効化する**という指示がありますが、これの指示に間違いがあります。
>mysql > SET GLOBAL sql_mode=(SELECT_REPLACE(@@sql_mode, 'ONLY_FULL_GROUP_BY', ''));

　とありますが、SELECT REPLACEが正しく、間のアンダースコアがあるとエラーになります。MySQLを知ってればすぐ気づいたんでしょうが、筆者はここでも詰まりました。

## Metadata Serverの発行
　Metadata Serverのビルド、発行はVisual Studio上から行うのですが、Visual Studioを管理者権限で起動する必要があるので注意してください。
　まずはDeploymentSettings.csにMetadata Serverをインストールするサーバーの設定を書き込みます。

 ```DeploymentSettings.cs
 		/// <summary>
		/// SQL connection string used to connect to the database for telemetry and review data.
		/// </summary>
		public string? ApiUrl => "http://localhost/MetadataServer";
```
　外部サーバーにセットアップする場合はlocalhostの部分を目的のサーバーに書き換えてください。この設定はUGS関連の他のアプリケーションも共通して使用するので、書き換えたらUnrealGameSync.exeなど他のアプリもビルドが必要です。
　MetadataServerフォルダのWeb.template.configを編集してMySQLサーバーの情報を書き込みます。

 ```Web.template.config
	<connectionStrings>
		<add name="ConnectionString" connectionString="localhost;UserId=ugsadmin;password=xxxxxxxx;" providerName="MySql.Data.Client"/>
	</connectionStrings>
 
 ```
 こちらもlocalhostの部分をMySQLサーバーのURL、UserIdとpasswordをMySQLサーバーに設定したものに変更してください。今回はIISもMySQLもUGSも同じPCに構築しているのでどちらもlocalhostですが、他のPCからも使えるようにするためには別のPCにIISとMySQLをセットアップしてネットワーク越しにアクセスできるように設定しましょう。IISとMySQLは同じPCにセットアップしても構いません。その場合はMySQLのパスはlocalhostで良いです。要はMySQLのパスはMetadata Serverから参照するパスです。
　MetadataServerを右クリックしてビルドを実行します。ビルドするとMetadataServerフォルダにWeb.configファイルが生成されるので、そのファイルをNotForLicenseesというフォルダを作成してそこにコピーします。この辺も公式ドキュメントと動作が変わっているので注意です。
 
　実際の発行はVisual StudioからMetadataServerを右クリックして「発行」を選択します。
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/72ee1e70-0860-0a14-45d3-d656513ccc62.png)
　Web サーバーを選択、次の画面ではWeb 配置を選択。さらに次の画面
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/4e822f69-2e45-60fb-423f-3cdb303ab49e.png)
　これで発行が成功すれOKです。
　無事発行に成功したらブラウザで http://localhost/Metadataserver/api/latest を開いてみます。localhostの部分は外部サーバーに設定した場合は適宜書き換えてください。

```
<LatestData xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/MetadataServer.Models">
  <LastBuildId>0</LastBuildId>
  <LastCommentId>0</LastCommentId>
  <LastEventId>0</LastEventId>
</LatestData>
```
　のように表示されたらMetadataServerが無事起動しています。ここが404になったりエラーが出ている場合はなにか設定がうまくいっていないので、MySQLのバージョンを上記のものになっているか、ConnectStringの設定が間違えていないか、IISの設定など見直してみてください。

### うまくいかないときは
　筆者がMySQLとかWebアプリに慣れてないのもありますが、けっこうあちこちで引っかかって無事動くところまでは苦労しました。以下うまくいかないときのチェックポイントです。
 - IISの設定をいろいろ見直す
 - MySQLのバージョンを変えてみる
 - 発行がうまくいったら、MySQLにugs_dbというデータベースが作成されるので、それが作成されているか確認する。
 - dbができてるけど動作してるかよくわからない場合はMySQLにログインしてデータベースの状態を確認してみる。レコードが登録されていれば機能はしてるはず。
## MetadataServerを使ってみる
　これでMetadataServerと連携できるようになりました。DeploymentSettigns.csを修正したのでUGSもビルドしなおしてください。
 　とりあえず簡単に試せるのは、特定のCLを右クリックして開くメニューから
- Mark as good
- Mark as bad
- Leave comment
- Add star
あたりを試してみます。
　Mark as goodを実行すると左端の◯が緑色になります。Mark as badだと赤色になります。チームメンバーにそのビルドが安定しているかどうかを共有するための機能です。エディタがクラッシュした場合などにbadにするとかですね。
　Leave commentを実行するとStatusの名前の後に入力したコメントが表示されます。欄が狭いのでちょっと見にくいのが難点です。
　Add starは左端に星マークが付きます。「みんなこのビルドで作業してね」といった感じでしょうか。
　その他にはStatusの部分にそのCLを同期したメンバーの名前が表示されるので、誰がどのリビジョンのエディタを使っているかわかります。
　実際に画面に反映されるまでには数秒から十数秒くらいかかることがあります。即時反映されなくても慌てないでください。

## PostBadgeStatus
　CIS欄にバッジを貼り付ける機能を提供するのがPostBadgeStatusです。外部コマンドからMetadataServerにバッジを送信してUGSに表示します。どういう目的に使うかというと、Jenkinsなどの自動ビルドでビルドした結果、ビルドが失敗したとか成功したといった情報を表示することができます。このバッジにはURLを設定でき、バッジをクリックしたらそのURLが開きます。ビルド失敗時にビルドログを開いたりできます。
　PostBadgeStatusをビルドして、コマンドラインから実行してみます。

```
>PostBadgeStatus.exe -Name=BuildOK -Change=19 -Project=//test/UE5.3/Samples/Games/Lyra -RestUrl="http://localhost/MetadataServer" -Status=Success -Url=file://D:/work/UE5.3/Samples/Games/Lyra/README.md
```
　この例ではCL番号19にBuildOKというバッジが表示され、クリックするとLyraのドキュメントが表示されます。

　最終的なUGSの画面はこんな感じになりました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/147177/6f58e258-b806-1596-a4ad-b70c08e17469.png)
CL19にいろいろMetadata Server機能が反映されています。左端から順に
- 同期したCLであることを示す矢印
- Mark as goodでgoodビルドであることをマークした事で緑の丸が表示
- CISにBuildOKのバッジ。Successなので緑、Warningは黄色、Failureなら赤になります
- Statusにコメント

　ついでに前述のMessage機能も有効にしてみました。複数プロジェクトを扱う場合はプロジェクトごとに色やメッセージの設定ができます。

# まとめ
　Unreal Game Syncについて導入から使用までまとめてみました。どうでしょうか、使ってみようと思える人が増えれば幸いです。
　UGSは機能豊富で、Filterで細かいCL表示のフィルタリングができたり、ビルドステップを追加してUnreal Insightをビルド、起動したりといった機能など、説明しきれない様々な機能があるのでぜひ触ってみて使いこなして欲しいと思います。
　公式がもうちょい親切なドキュメントを用意してくれれば良いんですけどね・・・筆者のチームでは業務としてUnreal Game Syncを活用し始めています。慣れれば便利ですよ。