BuildPatch Tool Instructions (1.5.0 - Recommended)

BuildPatch Tool （BPT）は、製品のバイナリファイルを製品の Dev サンドボックス に安全にアップロードするためのコマンドラインツールです。そして、Dev Portal の Artifacts and Binaries セクションを使用して、製品オファー用の正しいアーティファクトにバイナリを添付し、テストを実施することができます。リリース管理プロセスを使用すると、サンドボックス間で BuildPatch Tool でアップロードしたバイナリをプロモートすることができます。

BuildPatch Tool を使用する前に、以下のセクションを確認し、必要な情報を収集してください。

BuildPatch tool (BPT) は、Dev Portal の アーティファクトとバイナリのページからダウンロードすることができます。

1. Dev Portal で [Your Product (製品)] > [Epic Games Store] > [Artifacts and Binaries (アーティファクトとバイナリ) へ移動します。
2. 右上にある [Download Tool (ツールをダウンロードする)] をクリックします。
3. ダウンロードが完了したらツールをご使用のローカルマシンにインストールします。

BPT を使用するために必要な情報を確実に入手するには、以下の ID を Dev Portal で取得します。

製品のクライアント ID とクライアント シークレット

オーナー、管理者、またはストアの役割を持つ組織内のすべてのユーザーは、以下の認証情報を取得できます。

1. Dev Portal で [Your Product (製品)] > [Product Settings (製品設定)] に移動します。
2. [General (一般)] タブを選択します。
3. Build Patch Tool Credentials セクションを見つけ、クライアント ID とシークレットを保存します。

オファーのアーティファクト名と ID

1. Dev Portal で [Your Product (製品)] > [Epic Games Store] > [Artifacts and Binaries (アーティファクトとバイナリ)] に移動します。
2. リストから、認証情報を取得するオファーの名前をクリックします。
3. [Manage Artifact (アーティファクトを管理)] 画面で [Edit Details (詳細を編集)] の右側にある矢印アイコン をクリックします。
4. アーティファクトメイト ID を保存します。
5. 必要に応じて、追加のオファーについても上記の手順を繰り返します。

オファーのオファー ID

1. Dev Portal で [Your Product (製品)] > [Epic Games Store] > [Offers (オファー)] に移動します。
2. リストから、認証情報を取得するオファーの名前をクリックします。
3. [Offer Details (オファーの詳細)] 画面で ID のセクションを探し、オファー ID を保存します。
4. 必要に応じて、追加のオファーについても上記の手順を繰り返します。

コマンド プロンプトがコマンドラインで \" (バックスラッシュの直後に二重引用符が続く場合) を解釈する方法のため、BuildPatchTool 引数でパスを指定するときは、次のガイダンスの少なくとも 1 つに従う必要があります。

• ディレクトリ名の末尾にスラッシュを付けないでください。
• ディレクトリ区切り文字にはスラッシュを使用します。
• パスを引用符で囲まないでください (パスに 1 つ以上のスペースが含まれている場合、引用符は使えません)。
• 二重引用符で囲まれている場合は、トレイリングスラッシュのみを別のバックスラッシュでエスケープします (エラーが発生しやすいため、お勧めしません)。

• -BuildRoot="D:/MyFolder/"
• -BuildRoot=D:\MyFolder\
• -BuildRoot=D:\MyFolder
• -BuildRoot=D:/MyFolder/
• -BuildRoot=D:/MyFolder
• -BuildRoot="D:\MyFolder\\"

次の構文は、コマンドラインのパスを定義する際に機能 しません。

-BuildRoot="D:\MyFolder\"

BuildPatchTool ZIP ファイルの内容を、アップロードする バイナリ にアクセスできるマシンに展開します。なお、展開したマシンは Epic バックエンドと通信を行うため、インターネットにアクセスできる状態である必要があります。なお、展開したマシンは Epic バックエンドと通信を行うため、インターネットにアクセスできる状態でないといけません。

認証は、BuildPatchTool に クライアント ID と クライアント シークレット を提供することによって実行されます。これらは、コマンドライン引数を使用するすべての操作に提供する必要があります。Epic ではこの ID およびシークレットを発行し、資格情報として使用します。

Epic のバックエンド サービスとやり取りするすべての操作で、ClientId パラメータを指定する必要があります。ClientSecret パラメータまたは ClientSecretEnvVar パラメータのいずれかを使用して、クライアント シークレットを指定する必要があります。

ClientSecret パラメータを使用する場合、次のように、クライアント シークレットをパラメータの値としてそのまま文字通り渡す必要があります。

ClientSecretEnvVar パラメータを使用するときは、次のように、クライアント シークレットを含む OS 環境変数の名前を渡します。

**シークレットの値がシステム ログやコマンドライン履歴に表示されないようにするため、可能な限り ClientSecretEnvVar パラメータを使用することをお勧めします。**ベスト プラクティスは、クライアント シークレットをシークレット管理システム (Hashicorp Vault など) に格納し、実行のたびにこれをビルド マシンの環境に安全に注入することです。

「Engine/Binaries/Win64/」ディレクトリに移動します。 コマンドラインから、UploadBinary モードで「BuildPatchTool.exe」を実行し、バイナリをポイントします (以下の CLI 引数の詳細を参照)。

これにより、バイナリが処理された後、クラウド ストレージにアップロードされ、そのバイナリがバックエンドに登録されます。

指定する必要のある各パラメータの説明は以下のとおりです。また、任意のモードの後に「-help」オプションを追加して (例："BuildPatchTool.exe -mode=PatchGeneration -help")、必要な引数に関する情報を取得することもできます。

PatchGeneration モードでオプションの -FileAttributeList パラメータを使用すると、実行可能ファイルやファイルのタグ付けグループなど、バイナリ内のファイルに特別な属性を適用できます。なお、起動アプリ (AppLaunch 引数で指定) は自動的に「executable (実行可能)」としてマークされます。そのため、このコンフィギュレーション ファイルに明示的に記載する必要はありません。特別な属性を設定する必要がない場合は、FileAttributeList 引数を省略できます。

カスタム FileAttributeList ファイルは、1 つ以上の改行で区切られたエントリを含むテキスト ファイルである必要があります。各行には、次のように引用符で囲まれた (BuildRoot-relative) ファイルパスがあり、その後に、参照されるファイルに適用される 1 つ以上のスペース区切りの属性が続いている必要があります。

"<QuotedRelativePathToFile>" <list of attributes>

"Relative/Path/To/My/file.bin" executable tag:my_tag "Second/Path/To/A/file.txt" tag:txt_files

次のファイル属性フラグがサポートされています。

• executable
• tag:my_tag

ファイルのタグ付けは、Epic Games Launcher の選択的ダウンロード機能に入力を提供するために使用されます。この機能は、インストール オプション画面で表示されます。この機能は現時点ではベータであるため、使用する必要がある場合は、Epic Games の担当者までお問い合わせください。

デフォルトでは、デスクトップ ショートカット アイコンは、AppLaunch 引数で示されるアプリ実行ファイルのアイコンに設定されます。このアイコンを更新するには、次の 2 つの方法があります。

• アプリの実行ファイルに埋め込まれているアイコンを更新する
• アプリの実行ファイルと同じファイル名の別の .ico ファイルを追加する (例:実行ファイルが「launch.exe」の場合は、「launch.ico」を使用する必要があります)

チャンク化およびアップロード プロセスが完了したら、バイナリにラベルを適用して、Epic Games Launcher からアクセスできるようにする必要があります。バイナリにラベルを適用すると、ラベル名 (「Live」など) およびプラットフォーム (「Win32」など) が 1 つのバイナリ バージョンに関連付けられます。同一のバイナリに複数のラベルを割り当てることができます。

EpicGamesLauncher クライアントは、現在実行されているプラットフォームに関連付けられているバイナリのみをクエリします。たとえば、Win32 Launcher クライアントは、プラットフォームが Win32 である場合にのみクエリを実行するため、Windows または Mac のラベルが付いているバイナリを受信することはありません。また、Windows x64 クライアントは、Windows プラットフォームを使用したバイナリのみをクエリします。複数のプラットフォームに対応している単一のバイナリ (Windows および Win32 の両方に対応したバイナリなど) がある場合は、同一のバイナリに 2 つのラベル (それぞれのプラットフォームに 1 つのラベル) を適用することで、再アップロードする必要なく両方のプラットフォームで使用できます。

Note: バイナリからすべてのラベルを削除すると、バイナリは 7 日で自動的に削除されます。この削除を防ぎたい場合は、非アクティブなバイナリ セクションを見つけて、ラベルを最低 1 つ追加します。

以前設定したラベルを削除するには、LabelBinary モードで使用されたパラメータと同じパラメータで UnlabelBinary モードを使用できます。

次のようにバックエンドにクエリを実行して、 ListBinaries モードですでに登録されているバイナリのリストを取得することもできます。

バイナリを削除するには、バイナリからすべてのラベルを削除します。バイナリは 7 日で自動的に削除されます。

CopyBinary モードでは、バイナリを再アップロードする必要なく、特定のアーティファクトから別のアーティファクトにバイナリをコピーできます。これは、最終バイナリを Staging アーティファクトから Live アーティファクトに移動する場合に役立ちます。

DiffBinaries Tool モードは、アップロード済みの 2 つのバイナリの差分を計算し、2 つのバイナリ間の更新を適用するための統計情報を出力します。

v1.4.0 以降が必要

BuildPatchTool は、UploadBinary モードを使用してアップロードされたすべてのバイナリに一般的なパッチ システムを使用します。このシステムにより、Epic Games ストアは、ユーザーのマシン上の任意のバージョンのバイナリを他のバージョンに更新できるため、ダウンロードサイズを最小限に抑えることができます。

BinaryDeltaOptimise モードは、Epic Services にアップロード済みの 2 つのバイナリを取得し、これら 2 つの特定のバージョン間で更新するユーザー向けによりサイズの小さいダウンロードを生成します。これを A-to-B パッチと呼びます。このコマンドの実行はオプションですが、プレイヤーの大部分が特定のバイナリ バージョン (バイナリ「A」) を使用している場合、このコマンドを実行することで、通常よりも大きなパッチをリリースする際のユーザー エクスペリエンスを向上させることができます。

以下は、2 つのバイナリ間のデルタ パッチを改善するためのサンプルのコマンドラインです。

BinaryDeltaOptimise モードで実行されている場合、BuildPatchTool は既存のバイナリ データをクラウド ネットワークからストリーミングし、再分析して、新しい A-to-B 固有のパッチ データをアップロードします。BuildVersionA と BuildVersionB の間の元のダウンロードサイズが大きい場合、このプロセスは標準の PatchGeneration モードよりも時間がかかる可能性があります。

通常、現在の Live バイナリを BuildVersionA として使用し、次にリリースするバイナリを BuildVersionB として使用して、BinaryDeltaOptimise モードを実行することをお勧めします。ネットワークの損失などツールの実行に問題が発生した場合に備えて、リリースの数日前にこのプロセスを完了するように予定を立てておくのが理想的です。

現在の Live バイナリ バージョンを確認するには、ListBinaries モードを使用できます。 BinaryDeltaOptimise が提供された 2 つの BuildVersion 値の間ですでに実行されている場合、プロセスは出力に示されている操作を省略できます。

処理が完了すると、出力には行った改善事項が表示されます。

• "Final unknown compressed bytes, plus meta [Bytes]"
  • これは、BuildVersionA と BuildVersionB の間のパッチ適用で取得された新しいダウンロード サイズを指します。
• "Original unknown compressed bytes [Bytes]"
  • これは、最適化が実行される前の BuildVersionA と BuildVersionB 間のパッチのダウンロード サイズを指します。
• "Improvement: [Percentage]"
  • これは、どのくらい改善できたのかを表示します。パーセンテージは削減されたサイズを示し、大きいほど良いです。

Epic Games ストアは、ダウンロード可能なコンテンツ (DLC) を完全にサポートしています。BuildPatchTool の操作は、DLC の場合も、完全版のゲームと同様に、次の追加の注意点があります。

DLC の各アイテムには、独自の一意のアーティファクト ID が付与されます。それに応じて、DLC の各アイテムでは、指定された適切なアーティファクト ID を使用して実行される独自のパッチ生成プロセスが必要となります。それぞれが個別に生成されるため、DLC アイテムのパッチ生成を実行するときは、Base ゲームと他のすべての DLC アイテムが、パッチ生成プロセス中に BuildRoot パラメータで指定されたフォルダに同時に存在しないことが重要です。または、「BuildRoot」フォルダにメイン ゲームまたはその他の DLC アイテムが含まれている場合は、BuildPatchTool コマンドラインで -FileIgnoreList パラメータを指定して、生成されたバイナリに含まれないようにすることができます (詳細については、::バイナリをアップロードする方法::を参照)。

エンドユーザーのマシンにインストールすると、メインゲームと関連する DLC のすべてのアイテムが同じディレクトリにインストールされます。これにより、メインゲーム内にはファイルや共通のファイルパスを共有する DLC のアイテムが存在してはならないという制限が生じます。BuildPatchTool はこれをチェックし、このルールに違反するファイルがある場合にパッチ生成プロセスが発生しないようにします。つまり、Base ゲームはインストール場所からの相対パスによってインストールされた DLC を見つられる状態でなければならないということです。

短期的には、DLC アイテムのアーティファクト ID は Epic がお客様に割り当て、メイン ゲームと DLC アイテムの関連付けは、そのプロセスの一部としてプロビジョニングされます。将来的には、このプロビジョニングを Developer Portal でのセルフサービス操作に組み込むことを検討しています。

エラーのトラブルシューティングを行う際には、まず以下の潜在的な問題を確認してください。

• パス構文を確認します。BuildRoot="D:\MyFolder\" では機能しません。
• すべての引数の間にスペースが追加されていることを確認します。
• ビルドに含まれるファイルは、Windows MAX_PATH 制限 (260 文字の制限) が適用されます。アップロード プロセスが予期せず失敗する場合は、すべてのファイル パス位置がこの制限を超えていないことを確認してください。
• BuildPatchTool のほとんどの引数は、通常、絶対パスまたは作業ディレクトリに対する相対パスとして指定されます。ただし、AppLaunch 引数は BuildRoot 位置に対する相対パスとしてのみ指定する必要があります。
• CloudDir のコンテンツは時間の経過に伴い増加します。これは、より多くのビルドが同一マシン上で処理されるためです。ただし、このフォルダはいつでもマイナスの影響を及ぼすことなく消去できます。

BPT を使用するときは、コマンドラインが正しいことを確認してください。正確なコマンドを使用していなと、特定のエラー メッセージが表示されます。

次は一般的なエラーにすぎないことに注意してください。

意味： 使用しているクライアントの資格情報が、指定されたアーティファクトにアップロードするためのアクセスを許可していません。このエラーは、資格情報または別のパラメータのタイプミス、またはクライアントに付与されたアクセス許可に問題があって発生している可能性があります。

意味： BPT が、上記の 1 つ以上のパラメータを検出していません。このエラーは単に、パラメータが欠落しているか、正しく追加されていない可能性があって発生している可能性があります。このエラーは単に、パラメータが欠落しているか、正しく追加されていない可能性があって発生している可能性があります。

意味： BPT が、上記の 1 つ以上のパラメータを検出していません。このエラーは単に、パラメータが欠落しているか、正しく追加されていない可能性があって発生している可能性があります。このエラーは単に、パラメータが欠落しているか、正しく追加されていない可能性があって発生している可能性があります。

意味： 使用しているクライアントの資格情報が、レコードとマッチしていません。このエラーは、資格情報または別のパラメータのタイプミス、またはクライアントに付与されたアクセス許可に問題があって発生している可能性があります。

意味： 使用しているクライアントの資格情報が、指定されたアーティファクトにアクセスできません。これは、通常、クライアントに付与されている権限に問題があるためで、サービス デリバリーで対処することができます。

• 使用されているクライアント ID とクライアント シークレットは、BuildPatchTool を使用するためだけに Epic から提供されているため、EOS クライアント ID (通常、先頭が xyza) では、BuildPatchTool を使用することはできません。
• 必要なすべてのパラメータが提供されます。
• パラメータには、大文字と小文字が不正確であるといった問題やスペースの問題など、タイプミスはありません。
• スペースを含むパラメータの引用符はありません。