[利用バージョン：UE5.5.4]
1. はじめに
ゲーム開発におけるビルド作業は、日々の開発において重要なプロセスですが、手動でのビルドは非効率かつミスの原因となりがちです。特に大規模なプロジェクトでは、複数のターゲットプラットフォームへのビルドや、定期的なアセットのチェック、コンパイルなどが発生するため、手作業では開発者の負担が大きくなります。
UE5.4からBetaとして登場した Horde は、自動ビルドや分散ビルドなどを備えたEpicが使用するワークフロー支援サービスのセットです。その一部には、Unreal Engineでの開発に特化した CI/CD（継続的インテグレーション/継続的デリバリー） システムもあり、ビルドやテストの自動化を支援します。
本記事ではHorde CI/CDの基本的な構成を説明します。主にローカルにサーバーを立てて、Githubから取得したエンジンコードを追加し、自動ビルドを開始できるようになるまでのセットアップ手順を解説します。
2. 参考URL
以下はHordeのセットアップおよび運用にあたり参考となる関連情報です。
- Horde Build Automation Tutorial
Horde Build Automationに関するチュートリアルについて説明しています。ドキュメントではセットアップの詳細の幾つかを省略してあるため、本記事ではこのドキュメントで示されていないが嵌りやすい点や、注意するべき点について補足しています。
- Horde Installation Tutorial
Horde Server、Horde Agent のセットアップ方法について記載されたドキュメントです。
- UE5 & Perforce Best Practices
UE5のプロジェクトでPerforceをセットアップする際のベストプラクティスを示しています。はじめてPerforceを利用する方にも分かりやすく、ステップバイステップでセットアップの手順を示しています。
3. 構成
Horde Build Automation を利用するにあたっての基本構成を以下の図で示します。
-
Horde Server
中央の管理するサーバー。ビルドジョブの受付、エージェントステータスの管理、自動ビルド操作のためのWeb UIの提供などを担当。 -
Horde Agent
ビルドを実行するマシン、作業者。各PCにインストールしてServerと連携し、ビルドジョブを受け取ってビルド作業をローカルで実行します。 -
Perforce
ソース管理システム。Horde Agent はここからコードやアセットを同期・取得してビルドします。 -
ビルドマシンPC
ローカルにサーバーを立てる際のPerforce Serverが配置されるPC。Horde ServerをインストールすることでプロジェクトのビルドをこのPCで一元管理します。 -
開発用PC
ビルドのトリガーや設定の管理を行います。開発チームがHorde UIにアクセスして状況を確認できます。時にはリモートビルドに参加して分散ビルド処理を行います。
自分の開発用PCからWebUIにアクセスして手動でビルドを行ったり、スケジュールした自動ビルドの設定などを実行できます。この構成に追加された開発PCはPerforceと同期してビルドに参加します。
本記事では以下のような最小の構成でのセットアップを行います。
注意：テストの目的でビルドマシンPC に Horde Agent をインストールしていますが、ビルドにあたってCPUやメモリ、ストレージを利用するため、理想的には Horde Server と Horde Agent を同一PCにインストールすることはおすすめしません。
4. セットアップ
ここでは、ソフトウェアの導入から自動ビルドが可能になるまでの基本的なセットアップ手順を解説します。主なセットアップ手順の概要は以下の通りです。
[手順概要]
-
ビルドマシンのPerforceセットアップ
P4D、P4V をビルドマシンPCにインストール -
プロジェクト保存用の Depot の作成とストリームの設定
Perforce でストリーム設定でDepotを作成 -
エンジンおよびソースコードの格納
GithubからソースコードをダウンロードしてPerforceにサブミット -
Horde Server のセットアップ
Horde Sever をビルドマシンPCにインストール、Horde 関連のコンフィグを設定 -
Horde Agent のセットアップ
Horde Agent をビルドマシンPC、開発用PCにインストール
この手順は以下のドキュメントの Prerequisites、Setup に該当する部分ですが、ドキュメント内の文章は非常に簡潔に書かれており、実際のセットアップにおいてはいくつかの落とし穴や事前に知っておくべき事項があるため、それをここで示します。
以降で各ステップの詳細な手順を示します。
ステップ1: ビルドマシンのPerforceセットアップ
-
Helix Core Server(P4D) をビルドマシンPCにインストールします
・P4D のインストール時に Perforce Server のデフォルトが “localhost:1666” となっていますが、他のPCからアクセスするため変更することをおすすめします。
・P4Root のディレクトリは出来るだけ短い方が理想的です。 (例) D:/P4 等
・Port はデフォルトが “1666” となっていますが、Horde関連の設定もデフォルト “1666” のコンフィグ設定となっているため、ポートを変更する際には併せて変更が必要なことをご留意ください。 -
Helix Visual Client(P4V) をビルドマシンPCにインストールします
・次のステップで Depot を作成するため P4Admin にもチェックを入れてインストールします。
ステップ2: プロジェクト保存用の Depot の作成とストリームの設定
-
P4 typemap, p4ignore を設定します
・ Using Perforce as Source Control , Perforce Best Practices でも説明していますが、これらの設定を追加します。 -
P4V でストリームで Depot を作成します
・Horde は Stream 設定 の Depot であることが前提となっています。
・最初の Depot は P4Admin で起動して"File > New… > Depot…" から作成できます。SubStreamは Depot は P4V から “File > New… > Depot…” から作成できます。
・以下は //UE5/Main というストリームを作成した後の例を示します。
ステップ3: エンジンおよびソースコードの格納
-
Githubからエンジンのソースコードをダウンロードして解凍します
-
ステップ2 で作成した Depot に解凍したファイル一式をサブミットします
・以下はUE5.5.4 のソースコードをダウンロードしてサブミットした後の Depot です。
・ここにサブミットする際には Setup.bat, GenerateProjectFiles.bat を実行しておく必要はありません。
・プロジェクトのディレクトリは必ずしもEngineフォルダの下に配置される必要はありません。
ステップ4: Horde Server のセットアップ
-
Horde Sever をビルドマシンPCにインストールします
・Horde Server のインストール方法は Horde Installation Tutorial を参照してください。
・Horde Server のインストーラーは Github からダウンロードしたエンジンコードの中にある Setup.bat を実行すると、Engine\Extras\Horde\ に配置されて利用できます。 -
Horde 関連のコンフィグを設定します
・設定する内容は Setup の項目で説明しています。
・以下の例では、ここまでのセットアップにおいて設定した、Perforce Server 、Stream の内容について設定を行っています。
・.jsonファイルは変更した内容は数秒程度ですぐに反映されるため、Serverの再起動等は必要ありません。
ファイル：C:\ProgramData\Epic\Horde\Server\globals.json
Perforce Server の 接続先を自身のサーバーの接続先に変更するため “serverAndPort” を変更しました。自動ビルドによってPerforceと同期を行う際ワークスペースを自動で作成しますが、ここではそのOwnerの名前を “userName” で変更しました。
// List of servers to access
"servers":
[
{
// DNS name and port for the server.
// If connecting using "ssl:" prefix, ensure P4 server's fingerprint/certificate is trusted (see docs for "p4 trust")
// See Horde's documentation on connecting to SSL-enabled Perforce servers.
// "serverAndPort": "perforce:1666"
"serverAndPort": "MyPerforceServer:1666"
}
],
// List of credentials for the server. The first credentials will be used by default, but can be overridden by setting the userName property in the workspace.
"credentials":
[
{
// "userName": "test.user",
"userName": "buildmachine"
// Specify either the password or ticket property below (but not both)
//"password": "password123",
// "ticket": "ticket if not using password"
}
]
ファイル：C:\ProgramData\Epic\Horde\Server\server.json
Perforce Server の 接続先を自身のサーバーの接続先に変更するため “serverAndPort” を変更しました。
"Perforce": [
{
"id": "Default",
// "serverAndPort": "perforce:1666",
"serverAndPort": "MyPerforceServer:1666",
"credentials": {
// "userName": "test.user",
// "password": "password (optional)",
// "ticket": "ticket (optional)"
}
}
],
ファイル：C:\ProgramData\Epic\Horde\Server\ue5.project.json
PerforceのDepotを “//UE5/Main” のストリームで作成したので以下のように “includePatterns” を変更しました。
"categories": [
{
"name": "General",
"row": 0,
"showOnNavMenu": true,
"includePatterns": [
// "//UE5/Release-5.5"
"//UE5/Main"
]
}
]
これら設定ファイルの内容について詳しく知りたい場合は、以下のリンクを参照してください。
ここまでの設定が正しく完了していたら、[Sever]->[Perforce Servers] 内の表示において以下のようにPerforceとの接続ステータスが “Healty” になっています。
それから以下のようにダッシュボードからストリームの選択（//UE5/Main）の表示ができるようになっています。
ステップ5: Horde Agent のセットアップ
- Horde Agent をビルドマシンPC、開発用PCにインストール
・Horde Agent のインストール方法についても Horde Installation Tutorial を参照してください。
・すでにダッシュボードにアクセスできる場合は、開発用PCのブラウザで “http://[SERVER_IP]:13440” を実行して [TOOLS]->[Downloads]から Horde Agent のインストーラを入手できます。
・ここで Unreal Toolbox をインストールすると、Toolbox のアプリの中から Horde Agent をインストールすることもできます。
・Horde Agent のインストールにおいては以下の Horde Server URLの指定を、既に配置しているビルドマシンPCのアドレスを指定してください。
- Horde Agent を Horde Server に Enroll (登録) します
・Horde Agent のインストーラからインストールした場合は、インストール完了後に自動的にEnrollするかどうかを確認するので、その手順に沿ってEnrollすることができます。
・Unreal Toolbox から Horde Agent をインストールした場合、Unreal Toolbox をPCのタスクトレイから実行して Enroll を手動でリクエストすることもできます。
ここまでの設定が正しく完了していたら、以下のように登録した Horde Agent は “Ready” 状態となりビルドに参加可能な状態となります。
5. トラブルシューティング
よくある問題と対処方法について以下に示します。
5.1. Perforce
・ダッシュボードで “Server is reporting a Peforce issue. See status page for more info.” のエラーが表示される
基本的には設定ファイルが想定していないフォーマットになっていたり、想定していない設定値がセットされているとこのエラーが出ます。global.json, server.json で変更したコンフィグの設定が正しいかご確認ください。
Perforce Sever のステータスがHealtyになっていない場合、Perforce関連の設定に問題がある可能性があります。global.json, server.json, Horde ServerのPerforce Serverの指定が期待する設定になっているかご確認ください。
・自動生成されたワークスペースが削除できない、P4Vからの操作時に無応答
PerforceにはHorde Client様々な理由により削除できないことが想定されます。
・他のアプリケーションがワークスペースを操作中であることが想定されるため、Horde Agent, Horde Serverを終了した状態で削除を実行することで正しく削除できることがあります
・ワークスペースの作成先ディレクトリがCドライブで管理者権限がなくて削除できないことが想定されるので、PCLもしくはP4Vを管理者として起動して削除することで正しく削除できることがあります
・ワークスペースにダウンロードされたファイル数が多すぎる場合、削除までに長く時間がかかることがあります
・ワークスペースのファイルの保存先パス長が長いと削除できない可能性があるので、p4 client で一度開いてから Root の場所を変更して、再度削除すると削除できることがあります
・ワークスペースが純粋に壊れている場合はファイル保存先を削除することが最終手段です
5.2. ダッシュボード
・ダッシュボードのページにアクセスできない
ファイアウォールでポートの設定（デフォルト13340）が非許可になっていないか、別のサービスで利用していないかを確認します。Horde Serverが起動していない場合はアクセスできないため、Horde Serverが起動しているかどうかを確認します。
・ ダッシュボード上でストリームが表示できない
ストリームが表示されない場合はPerforceのDepotの設定か、ue5.project.json の設定に問題がある可能性があります。これらの設定が正しいかご確認ください。
5.3. Horde Agent
・Agent が Server 上に表示されない
Horde Agent のインストール時に設定したHorde Server のURLが正しいかどうかを確認します。Unreal Toolbox からも Horde Agent が接続するHorde Server の接続先を自由に変更することも可能です。
・Agent のステータスが “Busy” となっており “Ready” に移行しない
Horde Agent と同じPCに Unreal Toolbox をインストールしている場合に発生する可能性があります。Unreal Toolbox で Mode を “Workstation” に設定している場合、マウス操作などのユーザーのオペレーションを検出してビルドに参加しない（ジョブ実行中はキャンセルする）ように、動作を制限します。この機能は “Dedicated” に変更することで停止します。
・Agent のステータスが “Updating Workspaces” となっており “Ready” に移行しない
.Net8 の Runtime をインストールすると解決する可能性があります。
Horde ServerにHorde Agentを登録すると、Perforceと接続してHorde Agentのワークスペースを更新する処理が行われます。Horde Server のインストール時に正しく Perforce Server を指定できているか、global.json, server.json での Perforce Server の指定が正しいかどうかをご確認ください。
また、Horde Agentのステータスを示す箇所で"Updating workspaces"のステータスはクリックして内容を確認することができます。ここを確認することで現在どのような状況かログで確認できるため、こちらを選択してログから対処方法を検討する必要があります。
・Horde Serverとは別のPCで動作するHorde Agentのステータスが"Updating Workspaces" となっており “Ready” に移行しない
以下のエラーが出ている場合は、ローカルの開発用PCで以下の内容を試すことで修正されることがあります。
Unhandled exception while running conform: Failed: Connect to server failed; check $P4PORT.
TCP connect to [P4_SERVER] failed.
connect: [PERFORCE_SERVER]:1666 : WSAETIMEDOUT, A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. (Generic=Comm)
・Server側でport 1666が空いているか、FWのポートチェック
・PowerShellで “Test-NetConnection [PERFORCE_SERVER] -Port 1666” を実行
・Peforceアクセスのためにコマンドプロンプトを開いて以下のコマンドを実行
p4 set P4PORT=[PERFORCE_SERVER]:1666
6. まとめ
本記事では、Horde CI/CDによる自動ビルドの概要から、実際のセットアップ手順までを解説しました。HordeはUnreal Engineの規模感に合わせて設計されており、うまく導入することでビルド工数の大幅な削減や、開発効率の向上が見込めます。
次回の記事では、デフォルトで用意されているサンプルのスクリプトについて解説し、ビルドシナリオの理解とその活用方法について掘り下げていきます。それ以降の記事では、Hordeの高度な設定方法（カスタムビルドスクリプト、マルチプラットフォーム対応、通知機能、ビルドキャッシュ活用など）について掘り下げていきます。