BuildPatch Tool Instructions (1.4.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\\"

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

-BuildRoot="D:\MyFolder\"

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

注記： ZIP ファイルのリンクは常に最新バージョンの BPT の最新の状態に保たれてます。ファイルにアクセスできない場合は、 ケースを作成 してください。

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

注記： BuildPatchTool は、ゲームで使用される可能性のある EOS クライアント ID とは別に、一意のクライアント ID とクライアント シークレットを使用します。EOS クライアント ID (通常は xyza で始まります) は BuildPatchTool では使用できません。

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/」ディレクトリに移動します。コマンドラインから、 PatchGeneration モードで「BuildPatchTool.exe」を実行し、ビルドをポイントします (以下の CLI 引数の詳細を参照)。これにより、ビルドが処理された後、クラウドストレージにアップロードされ、そのビルドがバックエンドに登録されます。

Engine\Binaries\Win64>BuildPatchTool.exe

  -OrganizationId="<YourOrg>"
  -ProductId="<YourProduct>"
  -ArtifactId="<YourArtifact>"
  -ClientId="<YourClientId>"
  -ClientSecretEnvVar="<YourSecretEnvVar>"
  -mode=PatchGeneration
  -BuildRoot="<LocationOfLocalBuild>"
  -CloudDir="<YourCloudDir>"
  -BuildVersion="<YourBuildVersion>"
  -AppLaunch="<AppToRun>"
  -AppArgs="<LaunchArguments>"
  -FileAttributeList="<LocationOfAttributesFile>"
  -FileIgnoreList="<LocationOfIgnoreFile>"

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

• OrganizationID – 資格情報とともに提供された組織 ID 文字列を使用します。

• ProductID – 資格情報とともに提供された製品 ID 文字列を使用します。

• ArtifactID – 資格情報とともに提供されたアーティファクト ID 文字列を指定します。

• ClientId – 認証 を参照してください。

• ClientSecretEnvVar – 認証 を参照してください。

• BuildRoot – 読み取って処理するビルドを含むディレクトリへのパス。これは、相対パスではなく、ドライブルートからの絶対パスである必要があります。また、OS の MAX_PATH 制限 (通常は 260 文字) を超えるファイルを回避するため、このパスをドライブルートの近くに配置することをお勧めします。

• CloudDir – 既存の処理済みビルドデータが認識され、新しいデータが追加されるディレクトリ。

  • BuildRoot と同様に、これはドライブルートからの絶対パスである必要があります。この場所は、既存のビルドに関する情報をキャッシュするために使用され、BuildRoot パラメータとは異なるディレクトリである必要があります。このディレクトリが最初は空であれば問題ありません。 BuildPatchTool は、必要に応じて Epic バックエンドから情報をダウンロードし、「CloudDir」に保存します。

• BuildVersion – ビルドのバージョン文字列。この文字列は、特定のアーティファクトのビルドごとに一意である必要があります。ビルド バージョン文字列には次の制限があります。長さは 1 文字から 100 文字である必要があります。空白は使用できません。a-z、A-Z、0-9、+ と - の文字のみを含む文字セットである必要があります。

• AppLaunch – BuildRoot に関連する (および BuildRoot 内で)、ゲームの実行時に起動する必要があるアプリ実行可能ファイルへのパス。Mac ビルドの場合、これは「.app」フォルダ内 (通常は「Game.app/Contents/MacOS/Game」内) に含まれる実行可能ファイルである必要があります。

• AppArgs – 起動時にアプリに送信するコマンドライン。追加の引数が必要ない場合は、これを “” に設定できます。

• FileAttributeList (オプション) – 設定する必要のあるファイルのリストと対応する特別な属性 (実行ビットなど) を含むテキストファイルへの絶対パス。ファイルの内容の説明については、「特別なファイル属性の設定」を参照してください。

  • 実際のビルド コンテンツに誤って含まれることを防止するため、BuildRoot 内に属性ファイルを配置することは避けてください。

• FileIgnoreList (オプション) –生成されたパッチデータから除外する必要があるファイルのリストを含むテキストファイルへの絶対パス。各エントリは新しい行にあり、BuildRoot からの相対パスである必要があります。フォワードスラッシュ ("/") セパレータを使用する必要があります。

  • 無視するファイルが BuildRoot 内にある場合、そのファイル独自の相対ファイルパスを無視リストに追加して、パッチデータに含まれないようにする必要があることに注意してください。

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

ファイルのタグ付けは主に、Windows マシンに Mac ビルドをアップロードするときに実行ファイルを明示的に示すために使用されます。この機能は、Epic Games Launcher の選択的ダウンロード機能でも使用されます。この機能は、ローカライズされたアセットが大量にある限られた数のゲームのダウンロードサイズを縮小します。

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

• アプリの実行ファイルに埋め込まれているアイコンを更新する

• アプリの実行ファイルと同じファイル名の別の .ico ファイルを追加する (例:実行ファイルが「launch.exe」の場合は、「launch.ico」を使用する必要があります)

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

Engine\Binaries\Win64>BuildPatchTool.exe

  -OrganizationId="<YourOrg>"
  -ProductId="<YourProduct>"
  -ArtifactId="<YourArtifact>"
  -ClientId="<YourClientId>"
  -ClientSecretEnvVar="<YourSecretEnvVar>"
  -mode=ListBinaries

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

-help コマンドを実行して、モードに必要なすべての引数のリストを生成します。

例: C:\Users\Name.Name\Desktop\Engine\Binaries\Win64>BuildPatchTool.exe -help -mode=CopyBinary

必要な引数のほとんどは、上記のモードで使用されているものと同じです。

SourceArtifactId="" — バイナリ のコピー元の アーティファクト の ID を指定します

DestArtifactId="" — バイナリのコピー先のアーティファクトの ID を指定します

v1.4.0 以降が必要です。

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

ChunkDeltaOptimise モードは、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=ChunkDeltaOptimise
  -CloudDir="<YourCloudDir>"
  -BuildVersionA="<YourSourceBuildVersion>"
  -BuildVersionB="<YourDestinationBuildVersion>"

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

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

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

Running optimization 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]"

• これは、どのくらい改善できたのかを表示します。パーセンテージは削減されたサイズを示し、大きいほど良いです。

例:

Final unknown compressed bytes, plus meta 400000
  Original unknown compressed bytes         1000000
  Improvement:60%

Epic Games ストアは、ダウンロード可能なコンテンツ (DLC) を完全にサポートしています。

アドオンオファーのアーティファクトのダウンロードを有効にするには、[Product] > [Artifacts (アーティファクト)] > [Create New Artifact (新しいアーティファクトの作成)] を選択し、新しいアーティファクトを該当するアドオンオファーに関連付けます。したがって、DLC の各アイテムには、指定された適切なアーティファクト ID を使用して実行される独自のパッチ生成プロセスが必要となります。それぞれが別々に生成されるため、DLC アイテムのパッチ生成を実行するときは、Base ゲームと他のすべての DLC アイテムが、パッチ生成プロセス中に BuildRoot パラメータで指定されたフォルダに同時に存在しないことが重要です。または、BuildRoot フォルダにメインゲームまたはその他の DLC アイテムが含まれている場合は、BuildPatchTool コマンドラインで -FileIgnoreList パラメータを指定して、生成されたバイナリに含まれないようにすることができます。詳細は「ビルドを処理する方法」を参照してください。

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

BPT を使用するときは、コマンドラインが正しいことを確認してください。間違っている場合、発生しているエラーに関するメッセージが表示されます。

次は一般的なエラーにすぎないことに注意してください。特定のモードを使用して BPT で -help コマンドを実行すると、エラーの原因に関する詳細情報を取得できます。

• Error - Failed to retrieve list of binaries from Epic services

• Error - Missing parameters

• Error - Missing credentials

• Error - Authentication error

• Error - Unexpected error

使用されているクライアント ID とクライアント シークレットは、BuildPatchTool で使用するために特別に表示されます。正しいクライアントは、[Product Settings] ページの [Client (クライアント)] セクションに BPT Client (BPT クライアント) として一覧表示されます。EOS の機能とインターフェースで接続するために他のクライアントが存在する場合がありますが、それらクライアントは BuildPatchTool の権限を有しません。

• 必要なすべてのパラメータが提供されます。

• パラメータには、大文字と小文字が不正確であるといった問題やスペースの問題など、タイプミスはありません。

• スペースを含むパラメータの引用符はありません。

Please check your provided %OrganizationId%, %ProductId% and ArtifactId are
correct, and that you should have access to create binaries for this
artifact.
Tool exited with:6

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

CloudDir, BuildRoot, ArtifactId, BuildVersion, AppLaunch, and AppArgs
are required parameters
Tool exited with:2

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

Please ensure you have specified ClientId and also one of ClientSecret or
ClientSecretEnvVar.If using ClientSecretEnvVar, ensure the env variable
is properly set.
Tool exited with:9

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

An authentication error occurred - Check you have specified ClientId, and
either ClientSecret or ClientSecretEnvVar parameters correctly.
Message:Sorry the client credentials you are using are invalid
Tool exited with:10

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

An unexpected error occurred.Error code: errors.com.epicgames.common.missing_permission;
Error message:Sorry your login does not possess the permissions
'artifact:o-7kyv8uwtz74njnl544kbxzt5xqephw:3bc138d96fb24d9597d4bbff23b9ecee:asdfasd READ'
needed to perform the requested operation
Tool exited with:5

意味 – 使用しているクライアントの資格情報が、指定されたアーティファクトにアクセスできません。[Product Settings] ページに示されているように、正しい BPT クライアントを使用していることを確認してください。