BuildPatch Tool Instructions (1.5.0)

关于构建设置和处理的指南。

阅读时间19分钟

开始之前

如何查找凭证ID

你需要在开发者门户中找到以下这些ID。

产品的Client ID和Client Secret

  1. 点击 开发者门户仪表板 > 产品 > 游戏服务 > 产品设置
  2. 产品设置 > SDK凭证 > BPT凭证 中查看凭证**。

商品的构件名称和ID

  • 进入 产品 > 构件 页面中的 > 商品构件 > 编辑细节 下拉菜单。

  • 构件名称和ID会显示在 管理构件 模式的 > 编辑细节 下拉菜单中。

商品的商品ID

  • 点击 产品 > 商品页面 > 商品

  • 商品ID位于 编辑商品 模式的底部

查看组织的BuildPatch工具凭证

在你的组织中,任何属于所有者、管理员或商城角色的用户都可以查看产品的BuildPatch工具凭证。他们还可以将证书复制到剪贴板上。

如需查看组织的BuildPatch工具凭证:

  1. 登录开发者门户
  2. 选择你想查看证书的产品。
  3. 选择 产品设置
  4. 向下滚动到 SDK凭证 > BPT凭证
  5. 点击 复制,复制证书到剪贴板:

命令行中的路径

由于命令提示符在命令行上对 \"(反斜杠直接后跟双引号)有独特的解释方式,所以在BuildPatchTool参数中指定路径时,要遵循以下至少一个指导意见:

  • 目录名称不要附加尾部斜杠。
  • 目录分隔符用正斜杠。
  • 不要将路径括在引号内(如果路径包含一个或多个空格,这一点无法做到)。
  • 使用另一个反斜杠仅对括在双引号内的尾部反斜杠转义(不推荐,因为容易出错)

有效路径语法示例

  • -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客户端密钥 来执行的。必须使用命令行参数为每个操作提供这些信息。 Epic将为你签发此ID和密钥,用作凭证。

BuildPatchTool使用唯一的 客户端ID客户端密钥,独立于你的游戏可能使用的EOS客户端ID。EOS客户端ID(通常以 xyza 开头)无法用于BuildPatchTool。

凡是与Epic的后端服务进行交互的操作,必须提供 ClientId 参数。客户端密钥必须使用 ClientSecretClientSecretEnvVar 参数提供。

如果使用 ClientSecret 参数,客户端密钥应该一字不差地作为参数值传递:

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

如果使用 ClientSecretEnvVar 参数,你需要传递包含客户端密钥的操作系统环境变量的名称:

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>"
可选:
-FileList="<LocationOfFileList>"
-FileAttributeList="<LocationOfAttributesFile>"
-FileIgnoreList="<LocationOfIgnoreFile>"

请见下方说明,了解你必须指定的各个参数。你还可以在任意模式之后添加 "-help" 选项(例如,"BuildPatchTool.exe -mode=PatchGeneration -help"),以获取有关必需参数的信息。

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildRoot包含待读取和处理二进制文件的目录路径。它可以是驱动器根目录的绝对路径,也可以是当前工作目录的相对路径。此外,建议将此路径放在靠近驱动器根目录的位置,以免文件超出操作系统MAX_PATH限制(通常为260个字符)。
CloudDir一种目录,BuildPatchTool可以把要上传的文件保存在此目录下,每次运行时可以为空。与BuildRoot一样,这里可以是绝对路径或相对路径。(此位置用于缓存现有二进制文件的信息,并且应该是不同于BuildRoot参数的目录。此目录可以初始为空,BuildPatchTool会根据需要从Epic后端下载信息,并将其存储在CloudDir中。)
BuildVersion该构件的版本字符串。对于特定构件的每个构建,该字符串需要是唯一的。构建版本字符串有以下限制:长度必须在1到100个字符之间,不允许有空格键,只应包含以下字符集 a-z,A-Z,0-9,或 .+-_
AppLaunch运行游戏时应启动的应用程序可执行文件的路径,相对于BuildRoot并位于其中。对于Mac二进制文件,这应该是.app文件夹中包含的可执行文件,通常位于Game.app/Contents/MacOS/Game。
AppArgs启动时要发送到应用程序的命令行。不需要额外参数时,可以将其设置为“”。
FileList(可选)文本文件的路径,其中包含二进制文件中要包含的文件。这些文件必须是相对于BuildRoot。这是使用FileIgnoreList的替代方法。
FileAttributeList(可选)文本文件路径,该文件包含一个文件列表以及应设置的对应特殊属性(例如,可执行位)。请参阅“设置特殊文件属性”小节,了解文件内容的说明。请注意,属性文件应放在BuildRoot之外,以免误与上传的二进制文件包含在一起。
FileIgnoreList(可选)文本文件路径,该文件包含应从生成的补丁数据中排除的文件列表。每个条目应独占一行,并且是相对于BuildRoot的路径。应使用正斜杠(“/”)分隔符。请注意,如果忽略文件位于BuildRoot之内,则其自己的相对文件路径需要包含在忽略列表中,以免将其包含在补丁数据中。

设置特殊文件属性

你可以将可选的 -FileAttributeList 参数与PatchGeneration模式搭配使用,将特殊属性应用于二进制文件中的文件,如可执行文件,或文件的标签组。请注意,启动应用程序(由 -AppLaunch 参数指定)会自动标记为可执行文件,不需要显式包含在此配置文件中。如果不需要设置特殊属性,可以忽略 -FileAttributeList 参数。

你的自定义 FileAttributeList 文件必须是文本文件,文件中包含一个或多个以换行符分隔的条目。每行必须包含用引号括起的(相对于BuildRoot的)文件路径,后跟要应用于所引用文件的一个或多个以空格分隔的属性:

"<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启动程序的选择性下载功能提供输入,公开在安装选项屏幕中。如果你觉得需要使用此功能,请联系Epic Games代表,因为该功能仍处于测试阶段。

设置桌面快捷方式图标

默认情况下,桌面快捷方式图标将设置为AppLaunch参数指示的应用程序可执行文件的图标。有两种方法可以更新此图标:

  • 更新应用程序可执行文件中嵌入的图标
  • 添加与应用程序可执行文件同名的单独.ico文件(例如:如果可执行文件是launch.exe,应使用launch.ico)

如何标记二进制文件

分块和上传过程完成后,你必须将标签应用到二进制文件,才可以从Epic Games启动程序访问它。将标签应用于二进制文件会将标签名称(例如“Live”)和平台(例如“Win32”)与单个二进制版本关联。你可以将多个标签分配给同一个二进制文件。

EpicGamesLauncher客户端将只查询与其当前运行的平台相关联的二进制文件。例如,Win32启动程序客户端只会使用Win32平台查询,因此它永远不会收到标有Windows或Mac的二进制文件。Windows x64客户端将仅查询使用Windows平台的二进制文件,依此类推。如果你确实有一个能与多个平台兼容的二进制文件(例如,兼容Windows和Win32),那么你可以将两个标签(每个平台一个)应用于同一个二进制文件,使其可用于两个平台,无需重新上传。

LabelBinary模式:

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>"

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildVersion应标记的二进制文件的版本字符串。此版本的二进制文件必须已经注册,否则标记操作将被拒绝。
标记(Label)应用于二进制文件的标签名称。将二进制文件设置为公开时,此标记必须是字符串“Live”。此外,字符串“Archive”可用于按平台标记单个二进制文件,即使平台不再存在也应该保留二进制文件。大约一周后,自动清理作业将删除未标记的二进制文件。
平台(Platform)与要标记的二进制文件关联的平台。目前,平台必须是以下之一:[Windows、Win32、Mac]
沙盒ID(SandboxId)用于标记此沙盒的ID。如果不提供,二进制文件会被标记为公开沙盒。

如何取消标记二进制文件

注意: 当你把二进制文件所有标签删除时,该二进制文件会在七天后自动删除。如果你想阻止这种删除,请在 不活跃的二进制文件(Inactive binaries) 部分中找到该二进制文件,并为其添加至少一个标签

要删除先前设置的标签,你可以使用 UnlabelBinary 模式和用于 LabelBinary 模式的相同参数:

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>"

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildVersion应标记的二进制文件的版本字符串。此版本的二进制文件必须已经注册,否则标记操作将被拒绝。
标记(Label)应用于二进制文件的标签名称。将二进制文件设置为公开时,此标记必须是字符串“Live”。此外,字符串“Archive”可用于按平台标记单个二进制文件,即使平台不再存在也应该保留二进制文件。大约一周后,自动清理作业将删除未标记的二进制文件。
平台(Platform)与要标记的二进制文件关联的平台。目前,平台必须是以下之一:[Windows、Win32、Mac]
沙盒ID(SandboxId)指定二进制文件的沙盒ID。如果不提供,二进制文件将被标记为公共沙盒。

如何列出现有二进制文件

你还可以查询后端,使用 ListBinaries 模式检索你已注册的二进制文件列表:

Engine\Binaries\Win64>BuildPatchTool.exe
-OrganizationId="<YourOrg>"
-ProductId="<YourProduct>"
-ArtifactId="<YourArtifact>"
-ClientId="<YourClientId>"
-ClientSecretEnvVar="<YourSecretEnvVar>"
-mode=ListBinaries
可选:
-OnlyLabeled
-Num="<NumberOfBinariesReturned>"
-OutputFile="<OutputFileName>"

参数说明:

参数说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
OnlyLabeled(可选)仅列出与标签关联的二进制文件。
Num(可选)限制返回的二进制文件的数量。二进制文件按日期顺序返回,最新的在前。
OutputFile(可选)二进制文件列表将作为JSON数组输出到指定文件。

如何删除二进制文件

如要删除一个二进制文件,请删除二进制文件的所有标签。二进制文件将在七天后自动删除。

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildVersion应标记的二进制文件的版本字符串。此版本的二进制文件必须已经注册,否则标记操作将被拒绝。

如何复制二进制文件

CopyBinary 模式允许你在不同构件之间复制二进制文件,而无需重新上传二进制文件。如果你想要将最终二进制文件从Staging构件移至Live构件,此功能很有用。

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

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildVersion应标记的二进制文件的版本字符串。必须已经注册此版本的二进制文件,否则标记操作将被拒绝。
SourceArtifactId指定从中复制二进制文件的构件ID。
DestArtifactId指定复制二进制文件的目标构件ID。

如何对比二进制文件

DiffBinaries 工具模式将计算已上传的两个二进制文件之间的差异,并输出用于在它们之间应用更新的统计数据。

Engine\Binaries\Win64>BuildPatchTool.exe
-OrganizationId="<YourOrg>"
-ProductId="<YourProduct>"
-ArtifactId="<YourArtifact>"
-ClientId="<YourClientId>"
-ClientSecretEnvVar="<YourSecretEnvVar>"
-mode=DiffBinaries
-BuildVersionA="<FirstBuildVersionToCompare>"
-BuildVersionB="<SecondBuildVersionToCompare>"
可选:
-InstallTagsA="<FirstInstallTagSet>"
-InstallTagsB="<SecondInstallTagSet>"
-CompareTagSet="<DiffInstallTagSet>"
-OutputFile="<OutputFileName>"

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
BuildVersionA基础二进制图像的版本字符串。
BuildVersionB要更新二进制图像的版本字符串。
InstallTagsA(可选)在引号中指定BuildVersionA上使用的一系列安装标签,各个标记之间用逗号分隔。如果你想计算未标记的文件,你应该包含空字符串。省略参数将使用所有文件。InstallTagsA=""将仅是未标记的文件。InstallTagsA=",tag"将是未标记的文件加上用“标签”标记的文件。InstallTagsA="tag"将是仅用“标签”标记的文件。
InstallTagsB(可选)在引号中指定BuildVersionB上使用的一系列安装标签,各个标记之间用逗号分隔。应用与InstallTagsA相同的规则。
CompareTagSet(可选)在引号中指定一系列标签,用于计算二进制文件之间的差异统计数据,各个标签之间用逗号分隔。支持多个列表。应用与InstallTagsA相同的规则。
OutputFile(可选)差异将作为JSON对象输出到指定文件。

降低更新大小

需要v1.4.0和更高版本

BuildPatchTool将通用补丁系统用于使用 UploadBinary 模式上传的所有二进制文件。系统允许Epic Games商城将用户机器上二进制文件的任意版本更新为任意其他版本,从而最大限度降低下载大小。

BinaryDeltaOptimise 模式旨在获取已上传到Epic服务的两个二进制文件,并为在这两个特定版本之间更新的用户生成更小的下载。我们将其称为A到B补丁。运行此命令是可选的步骤,鉴于大部分玩家都是使用特定的二进制版本(二进制“A”),发布比平常更大的补丁时,可以执行此步骤来改善用户体验。

下面是用于改善两个二进制版本之间的增量补丁的命令行示例:

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

参数说明:

参数名称说明
OrganizationID使用随凭证提供的组织ID字符串。
ProductID使用随凭证提供的产品ID字符串。
ArtifactID指定随凭证提供的构件ID字符串。
ClientId请参阅身份验证小节。
ClientSecretEnvVar请参阅身份验证小节。
CloudDirBuildPatchTool可以保存要上传文件的目录,每次运行时可以为空。与BuildRoot一样,这里可以是绝对路径或相对路径。(此位置用于缓存现有二进制文件的信息,并且应该是不同于BuildRoot参数的目录。此目录可以初始为空,BuildPatchTool会根据需要从Epic后端下载信息,并将其存储在CloudDir中。)
BuildVersionA基础二进制图像的版本字符串。
BuildVersionB目标二进制图像的版本字符串。
DiffAbortThreshold(可选)以字节为单位指定,供原始对比尝试提升的上限。这样允许对可能没有优势的大对比进行短路冗长优化尝试。接受的范围是n >= 1GB,默认为永不中止。

BinaryDeltaOptimise 模式下运行时,BuildPatchTool将从我们的云网络流送现有二进制数据,进行重新分析,然后上传新的A到B特定补丁数据。如果 BuildVersionABuildVersionB 之间的原始下载大小很大,此过程耗时可能超过标准PatchGeneration模式。

一般建议在运行 BinaryDeltaOptimise 模式时,将当前Live二进制文件用作 BuildVersionA,将你接下来要发布的二进制文件用作 BuildVersionB。理想情况下,应规划在发布的几天前完成此过程,以防运行工具时发生问题,如断网。

要检查当前Live二进制文件版本,你可以利用ListBinaries模式。 如果已在两个提供的BuildVersion值之间运行了 BinaryDeltaOptimise,该过程会成功将操作短路,如输出中所示。

针对从1.3.0-Windows到1.3.1-Windows的补丁操作运行优化
** 已为提供的清单完成文件块增量优化。 **
已加载优化的增量文件 E:/CloudDir/Deltas/jd63jdu7-jsg58dh58dki8dk323/a5nbd0jbweof98fvytsvnthcsvf.delta

完成处理后,输出将显示实现的改进情况。

  • "最终未知压缩字节数,加上元 [Bytes]"
    • 这指的是针对 BuildVersionABuildVersionB 之间的补丁实现的新下载大小。
  • "原始未知压缩字节数 [Bytes]"
    • 这指的是运行优化之前,BuildVersionABuildVersionB 之间的补丁的下载大小。
  • "改进:[Percentage]"
    • 这将显示实现的改进情况。该百分比指的是缩减幅度,越大越好。

示例输出:

最终未知压缩字节数,加上元 400000