BuildPatch ツール (BPT) インストラクション 1.4.0

セットアップと処理 - クローズドベータ

クローズド ベータのパートナーですか? クローズド ベータ版 リリースに参加していない場合は、Epic Games アカウントを使用して ナレッジベースにサインインする と、ドキュメントにアクセスできます。

始める前に

資格情報 ID を探す方法

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

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

  • [Developer Portal Dashboard (Developer Portal ダッシュボード)] > [Product (製品)] > [Games Services (ゲーム サービス)] > [Product Settings (製品設定)] ボタン に移動します。

  • クライアント ID とクライアント シークレットは、[Product Settings] > [SDK Credentials (SDK 資格情報)] セクション に表示されます。

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

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

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

オファーのオファー ID

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

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

コマンドラインのパス

コマンド プロンプトがコマンドラインで \" (バックスラッシュの直後に二重引用符が続く場合) を解釈する方法のため、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 – ビルドのバージョン文字列。この文字列は、特定のアーティファクトのビルドごとに一意である必要があります。また、? や / などのフォルダ名またはファイル名で許可されていない文字を含めることはできません。

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

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

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

    • 実際のビルド コンテンツに誤って含まれることを防止するため、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

バイナリを削除する方法

次のように DeleteBinary モードを使用して、以前にアップロードしたバイナリを削除できます。

    Engine\Binaries\Win64>BuildPatchTool.exe

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

バイナリをコピーする方法

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

Developer Potal 公開ツールの 別のアーティファクトへ複製する 機能を使用することもできます。

-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 固有のパッチデータをアップロードします。BuildVersionABuildVersionB の間の元のダウンロードサイズが大きい場合、このプロセスは標準の PatchGeneration モードよりも時間がかかる可能性があります。

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

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

    Running optimization for patching 1.3.0-Windows -> 1.3.1-Windows
    ...
    ** 提供されたマニフェストのチャンク デルタ最適化はすでに完了しています。 **
    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%

ダウンロード可能なコンテンツ (DLC)

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 コマンドを実行すると、エラーの原因に関する詳細情報を取得できます。

確認事項

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

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

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

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

Error - Failed to retrieve list of binaries from Epic services (Epic サービスからバイナリのリストを取得できませんでした)

    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

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

Error - Missing parameters (パラメータがありません)

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

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

Error - Missing credentials (資格情報がありません)

    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 つ以上のパラメータを検出していません。このエラーは単に、パラメータが欠落しているか、正しく追加されていない可能性があって発生している可能性があります。

Error - Authentication error (認証エラー)

    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

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

Error - Unexpected error (予期せぬエラー)

    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 クライアントを使用していることを確認してください。