BuildPatch Tool Instructions (1.5.0)

いくつかの ID を Developer Potal で探す必要があります。

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

1. [Developer Portal Dashboard (Developer Portal ダッシュボード)] > [Product (製品)] > [Games Services (ゲーム サービス)] > [Product Settings (製品設定)] に移動します。
2. [Product Settings] > [SDK Credentials] > [BPT Credentials] で資格情報を表示します。

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

• [Product] > [Artifacts (アーティファクト)] ページ > [Offer Artifact (オファー アーティファクト)] > [Edit Details (詳細を編集)] ドロップダウンに移動します。

• [Manage Artifact (アーティファクトを管理)] モーダル > [Edit Details] ドロップダウンにアーティファクト名と ID が表示されます。

オファーのオファー ID

• [Product] > [Offers (オファー)] ページ > [Offer (オファー)] に移動します。

• オファー ID は、 [Edit Offer (オファーを編集)] モーダルの下部にあります。

オーナー、管理者、またはストア ロール を持つ組織内のすべてのユーザーは、製品の BuildPatch ツールの資格情報を表示できます。資格情報をクリップボードにコピーすることもできます。

組織の BuildPatch Tool 利用資格を表示する方法は以下のとおりです。

1. Dev Portal にサインインします。
2. 利用資格を表示したい製品を選択します。
3. [Product Settings] を選択します。
4. [SDK Credentials] > [BPT Credentials] へスクロールします。
5. 利用資格をクリップボードにコピーするには [Copy] をクリックします。

コマンド プロンプトがコマンドラインで \" (バックスラッシュの直後に二重引用符が続く場合) を解釈する方法のため、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 パラメータを使用する場合、次のように、クライアント シークレットをパラメータの値としてそのまま文字通り渡す必要があります。

Engine\Binaries\Win64>BuildPatchTool.exe
      -ClientId="<YourClientId>"
      -ClientSecret="<YourClientSecret>"

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

Engine\Binaries\Win64>set MyEpicSecret=<YourClientSecret>
Engine\Binaries\Win64>BuildPatchTool.exe
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="MyEpicSecret"

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

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

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

Engine\Binaries\Win64>BuildPatchTool.exe
    -OrganizationId="<YourOrg>"
    -ProductId="<YourProduct>"
    -ArtifactId="<YourArtifact>"
    -ClientId="<YourClientId>"
    -ClientSecretEnvVar="<YourSecretEnvVar>"
    -mode=UploadBinary
    -BuildRoot="<LocationOfLocalBuild>"
    -CloudDir="<YourCloudDir>"
    -BuildVersion="<YourBuildVersion>"
    -AppLaunch="<AppToRun>"
    -AppArgs="<LaunchArguments>"

Optional:
    -FileList="<LocationOfFileList>"
    -FileAttributeList="<LocationOfAttributesFile>"
    -FileIgnoreList="<LocationOfIgnoreFile>"

指定する必要のある各パラメータの説明は以下のとおりです。また、任意のモードの後に「-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 つのラベル) を適用することで、再アップロードする必要なく両方のプラットフォームで使用できます。

Engine\Binaries\Win64>BuildPatchTool.exe
    -OrganizationId="<YourOrg>"
    -ProductId="<YourProduct>"
    -ArtifactId="<YourArtifact>"
    -ClientId="<YourClientId>"
    -ClientSecretEnvVar="<YourSecretEnvVar>"
    -mode=LabelBinary
    -BuildVersion="<YourBuildVersion>"
    -Label="<LabelName>"
    -Platform="<Platform>"
    -SandboxId="<YourSandbox>"

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

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

Engine\Binaries\Win64>BuildPatchTool.exe
      -OrganizationId="<YourOrg>"
      -ProductId="<YourProduct>"
      -ArtifactId="<YourArtifact>"
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="<YourSecretEnvVar>"
      -mode=UnlabelBinary
      -BuildVersion="<YourBuildVersion>"
      -Label="<LabelName>"
      -Platform="<Platform>"
      -SandboxId="<YourSandbox>"

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

Engine\Binaries\Win64>BuildPatchTool.exe
      -OrganizationId="<YourOrg>"
      -ProductId="<YourProduct>"
      -ArtifactId="<YourArtifact>"
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="<YourSecretEnvVar>"
      -mode=ListBinaries

Optional:
      -OnlyLabeled
      -Num="<NumberOfBinariesReturned>"
      -OutputFile="<OutputFileName>"

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

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

Engine\Binaries\Win64>BuildPatchTool.exe
      -OrganizationId="<YourOrg>"
      -ProductId="<YourProduct>"
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="<YourSecretEnvVar>"
      -mode=CopyBinary
      -BuildVersion="<VersionToCopy>"
      -SourceArtifactId="<SourceArtifact>"
      -DestArtifactId="<DestArtifact>"

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

Engine\Binaries\Win64>BuildPatchTool.exe
      -OrganizationId="<YourOrg>"
      -ProductId="<YourProduct>"
      -ArtifactId="<YourArtifact>"
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="<YourSecretEnvVar>"
      -mode=DiffBinaries
      -BuildVersionA="<FirstBuildVersionToCompare>"
      -BuildVersionB="<SecondBuildVersionToCompare>"

      Optional:
      -InstallTagsA="<FirstInstallTagSet>"
      -InstallTagsB="<SecondInstallTagSet>"
      -CompareTagSet="<DiffInstallTagSet>"
      -OutputFile="<OutputFileName>"

v1.4.0 以降が必要

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

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

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

Engine\Binaries\Win64>BuildPatchTool.exe
      -OrganizationId="<YourOrg>"
      -ProductId="<YourProduct>"
      -ArtifactId="<YourArtifact>"
      -ClientId="<YourClientId>"
      -ClientSecretEnvVar="<YourSecretEnvVar>"
      -mode=BinaryDeltaOptimise
      -CloudDir="<YourCloudDir>"
      -BuildVersionA="<YourSourceBuildVersion>"
      -BuildVersionB="<YourDestinationBuildVersion>"

      Optional
      -DiffAbortThreshold="<UpperLimitInBytes>"

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

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

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

Running optimisation for patching 1.3.0-Windows -> 1.3.1-Windows

** Chunk delta optimization already completed for provided manifests. **
Loaded- optimised delta file E:/CloudDir/Deltas/jd63jdu7-jsg58dh58dki8dk323/a5nbd0jbweof98fvytsvnthcsvf.delta

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

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