このページでは、UnrealGameSync (UGS) を studio としてデプロイするための設定方法を説明します。
方法
UnrealGameSync のソース コードは Engine/Source/Programs/UnrealGameSync にあります。
UnrealGameSync ソリューションは次のプロジェクトで構成されます。
| プロジェクト | 説明 |
|---|---|
| UnrealGameSync | メイン プログラム。 |
| UnrealGameSyncLauncher | UGS のランチャー。新しいバージョンが利用可能になると、メイン プログラムの実行ファイルを自動的に更新します。 |
| MetadataServer | REST API。UGS と一緒にデプロイして、ビルドへのコメント、ビルド正常性への投票、不良ビルドのマーキング、PostBadgeStatus が送信した Continuous Integration System (CIS) 結果の表示など、完全な機能セットを有効化します。 |
| Installer | UnrealGameSync ランチャーの MSI インストーラー。これは通常、デベロッパーのマシンにランチャーを取得するために使用し、これにより開発マシンは Perforce からプログラムを自動的に更新して実行できるようになります。 |
| PostBadgeStatus | ビルド結果を MetadataServer インスタンスにプッシュするユーティリティ。 |
コンフィギュレーション
UGS のデプロイ設定は Engine/Source/Programs/UnrealGameSync/UnrealGameSync/DeploymentSettings.cs で指定します。このファイルをチーム独自の設定で変更し、配布用の実行ファイルにコンパイルできます。
この設定は次のとおりです。
| 設定 | 説明 |
|---|---|
ApiUrl |
デベロッパー向けの情報提供に使用するメタデータ サービス (以下を参照) を実行するインスタンスの URL。 |
DefaultDepotPath |
UnrealGameSyncLauncher が UnrealGameSync 実行ファイルを同期するデフォルトの Perforce デポのパス。 |
bSendTelemetry |
ビルド時間に関するテレメトリをメタデータ サービスに投稿するかどうか。 |
自動更新
バージョン管理に Perforce を活用する自己パッチ メカニズムで UGS を配布して、さまざまなブランチやプロジェクトを使用して UGS の帯域外で開発を可能にします。
ほとんど更新しないランチャー アプリケーションは、Microsoft Installer (MSI) パッケージ ('Installer' プロジェクト) を使用して、それぞれのデベロッパーのマシン (UnrealGameSyncLauncher) に手動でインストールします。これをインストールするとスタートメニュー アイコンが作成され、これを実行すると Perforce から最新の UGS 実行ファイルを同期して実行します。そのパスを監視して、新しい実行ファイルが送信された場合は、プログラムを再起動して再同期します。
ステートレスな方法で Perforce サーバーから取得するため、これらのファイルの同期にワークスペースは不要です。
インストーラーのビルドには Wix 3.8 が必要です。
UnrealGameSyncLauncher がアプリケーションの更新に使用するパスは、DeploymentSettings.cs (上記のリンク) を介してアプリケーションにコンパイルされる DefaultDepotPath 変数で指定します。このフォルダは次のようにレイアウトする必要があります (例: DefaultDepotPath = "//depot/UnrealGameSync")。
//depot/UnrealGameSync/Release/UnrealGameSync.exe
//depot/UnrealGameSync/Release/UnrealGameSync.exe.config
//depot/UnrealGameSync/Release/UnrealGameSync.pdb
//depot/UnrealGameSync/Release/Ionic.Zip.Reduced.dll
//depot/UnrealGameSync/UnstableRelease/UnrealGameSync.exe
//depot/UnrealGameSync/UnstableRelease/UnrealGameSync.exe.config
//depot/UnrealGameSync/UnstableRelease/UnrealGameSync.pdb
//depot/UnrealGameSync/UnstableRelease/Ionic.Zip.Reduced.dll
チェックインされた UnrealGameSync のコピーは 2 つあり、1 つは「Release」フォルダ配下、もう 1 つは「UnstableRelease」フォルダ配下にあります。
「Release」フォルダ配下の実行ファイルはデフォルトで使用します。一方、「UnstableRelease」フォルダは UGS の *[Application Settings (アプリケーション設定)] ダイアログを介してオプトインするユーザーにテスト ビルドを配布したり、ランチャーの起動中に Shift キーを押すことで使用できます。
UnrealGameSync の新しいバージョンは、新しい実行ファイルを送信するだけでプッシュ可能です。アプリケーションは変更の送信でフォルダをポーリングし、新しい変更がある場合はバイナリを再起動して再同期します。
メタデータ サービスを設定する
UGS は Web サービスと通信して、チーム メンバー間で情報を共有できます。これは設定なしでも実行可能ですが、その場合はより強力なコラボレーション機能の一部を利用できません。
- ビルド結果の表示とビルド破損に関するデスクトップ通知を提供する
- ユーザーが変更の評価をマークし、ビルドの問題を調査中であることを他のチームメンバーに表示する
- ユーザーごとに同期している変更を表示する
メタデータ サービスは ASP.NET で実装され、データベース バックエンドに MySQL インスタンスのセットアップが必要です。
データベース プロセスは (理想的には) 利用可能なマシン リソースをすべて消費できる必要があるため、メタデータ サーバーとデータベース バックエンドをホストする IIS インスタンスは、別のマシンでホストすることを推奨します。ただし、これは必須ではありません。
MySQL バックエンドを設定する
最低要件は MySQL 8.0 です。設定を開始する前にご確認ください。
MySQL バックエンドの設定は次の手順で実行します。
-
MySQL インストーラーの最新バージョンを https://dev.mysql.com/downloads/installer/ からダウンロードします。
-
[Choosing a Setup Type (セットアップタイプの選択)] で [Server Only (サーバーのみ使用)] を選択します。
-
[Configuration Steps (構成ステップ)] で以下を設定します。
- High Availability:スタンドアロン MySql サーバー
- Type and Networking:上記のように IIS インスタンスと共存する場合は [Server Computer]、別のインスタンス上にある場合は [Dedicated Server (専用サーバー)] を選択します。TCP/IP 構成とポートはすべてデフォルトのままにします。
- Authentication Method (認証方法):[Use Strong Password Encryption (強力なパスワード暗号化)]
- [Accounts (アカウント)] および [Roles (ロール)]:
- root のユーザー名とパスワードを選択します。
パスワードを紛失しないでください。これはデータベースのマスター アカウントです。 - IIS インスタンスが接続に使用するサービス アカウントとして、別のユーザーを追加します。
root アカウントを直接使用することはできません。
- root のユーザー名とパスワードを選択します。
- Windows Service (Windows マシンにインストールすると仮定):これらのオプションはそのままにします。
MySQL Workbench をローカルのワークステーション https://dev.mysql.com/downloads/workbench/ にインストールします。MySQL Workbench でデータベースを表示および操作できます。また、バックアップや復元などの管理タスクを実行できます。
トラブルシューティング
ONLY_FULL_GROUP_BY を無効化する
ONLY_FULL_GROUP_BY 機能が有効な場合、MySQL スクリプトの実行中にエラーが発生する可能性があります。この機能を無効化するには、コマンドを実行するか (方法 1)、MySQL オプション ファイルを変更します (方法 2)。
方法 1：コマンドを実行する
コマンドラインから MySQL サーバーを起動し、次を実行します：
mysql > SET GLOBAL sql_mode=(SELECT_REPLACE(@@sql_mode, 'ONLY_FULL_GROUP_BY', ''));
コマンドラインから MySQL サーバーを実行するのが難しい Windows ユーザーは、MySQL 8.0 リファレンス マニュアル 「Starting MySQL from the Windows Command Line」 を参照してください。
方法 2：オプション ファイルを変更する
必須： MySQL オプション ファイルの使用方法については、MySQL 8.0 リファレンスマニュアル オプション ファイルを使用する を参照してください。
- 「
my.cnf」オプション ファイルを探して開きます。 - このクエリを実行して
sql_modeを確認します。
SELECT @@sql_mode;
- クエリ結果を確認します。これは次のような値であるはずです。
ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
- 前の手順の値を次の
sql_modeステートメント ([mysqld] の下) に入力して、my.cnfを編集します。
sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
ステートメントは ONLY_FULL_GROUP_BY 値を含まないことに注意してください
- MySQL サーバーを再起動します。
詳細な情報は次の MySQL 8.0 リファレンス マニュアルのセクションをご覧ください。
- サーバーについて： [SQL Modes]](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html)
- MySQL について：[Handling of GROUP BY]](https://dev.mysql.com/doc/refman/8.0/en/group-by-handling.html)
メタデータ サービスを設定する
メタデータ サービスの設定は次の手順を実行します。
- UGS 実行ファイルを変更して ApiUrl を設定する
- ASP.NET Web Publishing ツールがインストール済みであることを確認してください。このパッケージは Visual Studio のインストールに含まれています。このパッケージをインストールしていない場合、「TransformXml task not found (TransformXml タスクが見つかりません)」というエラーでプロジェクトのビルドが失敗します。
- プロジェクトには従来の「
web.config」ファイルは付属していません。その代わりに「web.template.config.xml」が付属しており、これは「.debug」および「.release」の XML ファイルに対して変換され、動的に「web.config」を生成します。ソース管理では「web.config」ではなく「web.template.config」を確認する必要があります。 - 「
.debug」および「.release」の XML ファイルで、「Connection String」プロパティを介して MySQL データベースが存在する場所のパスを指定できます。これは MySQL 標準の接続文字列と同様です。
<add name="ConnectionString" connectionString="server=localhost;UserId=service_account_username;password=service_account_password;" providerName="MySql.Data.Client"/>
service_account_username と service_account_password は MySQL の設定プロセスで入力したアカウント認証情報です。
- データベースは、最初にサイトを起動した際に自動的にシードされます。
サーバーが正しく構成されたことを確認するには、Web ブラウザで「servername.com/api/latest」を開きます。次のような内容が表示されます。
<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>
データベースを適切に初期化するために、作成に失敗したり見つからない場合はサイトが終了します。サイトのデプロイ後に 404 エラーが発生する場合は、これが原因の可能性があります。接続文字列を確認します。別のインスタンスにある場合は、IIS インスタンスがデータベースと通信できることも確認します。
ビルド プロセスと統合する
バッジ
UGS は送信された変更リストに表示される バッジ を介して、ビルド システムの結果 (そしてビルドが「進行中」であるという通知) を表示できます。ビルドが破損した場合、最後の成功以降に送信したデベロッパーに通知が表示されます。バッジをクリックすると Web ブラウザが開き、ビルド ログを含む URL のページが表示されます。
この情報はメタデータ サービスにストアされ、PostBadgeStatus ユーティリティを使用してエントリを追加できます。
PostBadgeStatus
PostBadgeStatus コマンドラインの構文は次のとおりです。
PostBadgeStatus.exe
//(The badge name that will appear in UGS.)
-Name=Editor
//(The changelist being compiled.)
-Change=123456
//(The project to show the badge for.Note that this is the path to a folder, not the actual .uproject file.)
-Project=//UE4/Main/Samples/StarterContent
//(The base URI where UGSAPI is deployed)
-RestUrl="http://ugsapi-server.net"
//(The status of the build.Valid values are 'Starting', 'Failure', 'Warning', and 'Success'.)
-Status=Success
//(If a user clicks on a badge, this is the link that takes the user to the build log.)
-Url=http://link-to-build-log
プロジェクトをカスタマイズする
ブランディング
UGS に表示するプロジェクト ロゴを追加するには、プロジェクトを含むディレクトリに「Build \ UnrealGameSync.png」ファイルを配置します。画像は高さ 126 ピクセルに調整されます。
推奨の大きさは 200x126 ピクセルです。
この参照画像はご自由にダウンロードできます。
プロジェクトのコンフィグ ファイル
プロジェクト固有のコンフィグ ファイルで、プロジェクトをユーザーに表示する方法をカスタマイズできます。プロジェクトのコンフィグ ファイルは「<ProjectDir>/Build/UnrealGameSync.ini」として Perforce に送信する必要があります。
以下の設定を使用できます。
- デフォルトで UGS は、ビルド失敗の通知のうちプロジェクトのソースコードの変更に起因するものだけを表示します。バッジをコンテンツを送信するデベロッパーに表示する必要がある場合は、次のようにホワイトリストに追加します。
[Notifications]
+ContentBadges=Content
- クリック可能なボタンを CL の説明の列に追加する場合、対応するボタンのクリック時に CL の説明に正規表現を実行して、ユーザーを URL に誘導します。たとえば次のユースケースでは、すべての CL の横に Jira に対応する問題のリンクを含む「
##jira」タグが付いたバッジを追加します。
[Badges]
+DescriptionBadges=(Pattern="(?i)#\\s*jira\\s*:?\\s+([A-Za-z]+-[0-9]+)", Name="$1", Group="Jira", Color="#c0c0c0", HoverColor="#e0e0e0", Url="https://jira.it.yourcompany.net/browse/$1")
この例では次の属性を使用しました。
| 属性 | 説明 |
|---|---|
| Pattern | 一致する正規表現を指定します。テキストの一致する部分を取得して、これは後で置換できます。 |
| Label | バッジに表示するラベルを指定します。 |
| Group | 任意の識別子を指定して、空白で区切らずに関連するバッジをグループ化します。 |
| Color | バッジの RGB 値を 16 進数で指定します。 |
| HoverColor | バッジにホバーした際の RGB 値を 16 進数で指定します。 |
| Url | C# プロセスで開くパスを指定します。バッジをクリックしたときの呼び出しを開きます。 |
- 特定のブランチに対応するステータス パネルの色とともに「今日のメッセージ」を追加します。
[//UE4/Main/Samples/Games/ShooterGame/ShooterGame.uproject]
Message=:alert:修正の締切は **5 pm on Friday** です。このブランチに送信する必要があるのは 1.2.3 リリースの修正のみです。1/23 現在、123 件の不具合が未修正です。
StatusPanelColor=#e20000
StatusPanelColor オプションを使用するとストリームを簡単に識別できます。さらに「Message」オプションを使用する場合は、以下を含む Markdown の限定サブセットをサポートします。
[web links](http://www.google.com)
*italic*
_italic_
**bold**
__bold__
アイコンは ：icon： 構文の使用をサポートしています。ただし ：alert： が現在利用できる唯一のアイコンです。
- バッジのサイズと CIS 列での配置をカスタマイズします。
[Default]
ColumnWidth_CIS=580
+BadgeGroups=Editor
+BadgeGroups=And, Lin, PS4, XB1, Win, IOS, Mac, Swi
+BadgeGroups=Content
- プロジェクト別の同期ファイルを以下のように定義します。
[Options]
+SyncCategory=(UniqueId="d9610e2f-7f6f-4898-bc98-d39dd7053d75", Name="FirstCategory", Paths="/MyGame/Content/Foo/...")
UniqueIdはランダムに生成された GUID です。Nameは UGS UI で表示されます。Pathsはセミコロンで区切ることができます。
設定ずみのカテゴリを修正するには、.../UnrealGameSync/Workspace.cs の DefaultSyncCategories 配列にあるGUID を指定します。デフォルトで、UGS は指定したパスを既存のリストにアペンドしますが、Clear=true の設定で置換します。
プリコンパイル済みバイナリ
ユーザーがプリコンパイルされたエディタ ビルドをダウンロードできるように、必要なバイナリを含む zip ファイルを Perforce に送信します。するとローカルでコンパイルする代わりに UnrealGameSync 同期を行い抽出することができます。これを行うとローカルでコンパイルしたのと同じユーザー インターフェースを使用できますが、一致するバイナリがない変更はグレー表示になります。この構成を行うと、ユーザーは [Options (オプション)] メニューの [Sync Precompiled Binaries (プリコンパイル済みバイナリを同期する)] 項目をチェックしてプリコンパイル済みのバイナリの使用をオプトインできます。
プリコンパイル済みバイナリのパスを構成するには、プロジェクト配下に「Build\UnrealGameSync.ini」ファイルを追加し、以下のように送信先の Perforce サーバーの場所を参照します。
[//UE4/Main/Samples/Games/ShooterGame/ShooterGame.uproject]
ZippedBinariesPath=//UE4/Dev-Binaries/++UE4+Main-Editor.zip
プリコンパイル済みバイナリに対して、通常の開発ストリーム以外の場所を使用することを推奨します。これにより、このバイナリを使用しない人の混乱を防ぐことができます。個別のワークスペースを維持する必要はありません。UnrealGameSync はファイルの同期と同じログイン資格情報を使用して、ステートレスな方法でバイナリを取得します。
プリコンパイル済みバイナリを使用するために、メタデータ サーバーを設定する必要はありません。各 zip ファイルのリビジョンに対応する変更リストは、変更リストの説明 ([CL 12345678] タグで始まる必要があります) から解析します。
正しい形式でエディタ バイナリを作成して送信する方法を示すサンプル スクリプトを、以下からご利用いただけます。「Engine/Build/Graph/Examples/BuildEditorAndTools.xml」
そして、これを実行する典型的なコマンドラインを以下に示します。
Engine\Build\BatchFiles\RunUAT.bat
BuildGraph
-Script=Engine/Build/Graph/Examples/BuildEditorAndTools.xml
-Target="Submit To Perforce for UGS"
-set:EditorTarget=ShooterGameEditor
-set:ArchiveStream=//UE4/Dev-Binaries
-p4
-submit
これにより、zip ファイルを「//UE4/Dev-Binaries/++UE4+Main-Editor.zip」に送信します。ここで「++UE4+Main」は現在のブランチの名前で、「+」文字としてエスケープしたスラッシュを含みます。同じパスを「UnrealGameSync.ini」の ZippedBinariesPath の値に設定する必要があります。
「BuildEditorAndTools.xml」の使用に関する追加情報は、このファイルの先頭にあるコメントに記載されています。