BuildPatch Tool Instructions (1.4.0)

你需要在开发人员门户中找到多个ID。

产品的客户端ID和客户端密钥

1. 打开 开发人员门户操作面板（Developer Portal Dashboard）> 产品（Product）>游戏服务（Games Services）> 产品设置（Product Settings）按钮。
2. 在 产品设置（Product Settings） > SDK凭证（SDK Credentials） > BPT凭证（BPT Credentials） 中查看凭证。

商品的构件名称和ID

• 转到 产品（Product）>构件（Artifacts） 页面 > 商品构件（Offer Artifact）> 编辑细节（Edit Details） 下拉菜单。

• 构件名称和ID显示在 管理构件（Manage Artifact） 模态 > 编辑细节（Edit Details） 下拉菜单上。

商品的商品ID

• 转到 产品（Product）>“商品（Offers）”页面> 商品（Offer）。

• 商品ID位于 编辑商品（Edit Offer） 底部。

在你的组织中，任何属于所有者、管理员或商城角色的用户都可以查看产品的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\\"

在命令行中使用路径时，以下路径 无效：

-BuildRoot="D:\MyFolder\"

将BuildPatchTool ZIP 文件的内容提取到可访问待上传版本的机器。 该机器还需要能够联网，以便与Epic后端通信。

注意： ZIP文件链接始终与最新版BPT保持同步更新。如果无法访问该文件，请创建案例。

身份验证是通过向BuildPatchTool提供 客户端ID 和 客户端密钥 来执行的。必须使用命令行参数为每个操作提供这些信息。

注意: BuildPatchTool使用唯一的客户端ID和客户端密钥，独立于你的游戏可能使用的EOS客户端ID。EOS客户端ID（通常以 xyza 开头）无法用于BuildPatchTool。

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

使用 ClientSecret 参数时，客户端密钥应该一字不差地作为参数值传递：

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

我们推荐尽可能使用 ClientSecretEnvVar 参数，因为这样可防止密钥值出现在系统日志和命令行历史记录中。最好是将客户端密钥存储在密钥管理系统中（如Hashicorp Vault），并在每次运行期间将其安全地注入到你的构建机器的环境中。本文档不讨论设置方法。

找到 Engine/Binaries/Win64/ 目录。从命令行以 PatchGeneration 模式运行BuildPatchTool.exe，然后将其指向你的版本（请参阅下面的CLI参数详情）。这将处理你的版本，将其上传到我们的云存储器，并将版本注册到我们的后端：

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

• OrganizationID - 使用随凭证提供的组织ID字符串。

• ProductID - 使用随凭证提供的产品ID字符串。

• ArtifactID - 指定随凭证提供的构件ID字符串。

• ClientId - 请参阅身份验证。

• ClientSecretEnvVar - 请参阅身份验证。

• BuildRoot - 包含待读取和处理版本的目录路径。这应该是驱动器根目录中的绝对路径，而不是相对路径。此外，建议将此路径放在靠近驱动器根目录的位置，以免文件超出操作系统MAX_PATH限制（通常为260个字符）。

• CloudDir - 将在该目录中识别全部现有已处理版本数据，并且新数据将添加到该目录。

  • 与 BuildRoot 一样，这应该是驱动器根目录中的绝对路径。此位置用于缓存现有版本信息，并且应该是不同于 BuildRoot 参数的目录。此目录初始为空是没有问题的，BuildPatchTool会根据需要从Epic后端下载信息，并将其存储在 CloudDir 中。

• BuildVersion - 版本的版本字符串。每个构件的每个版本都有一个唯一值。构建版本字符串有以下限制：长度必须在1到100个字符之间，不允许有空格键，只应包含以下字符集a-z，A-Z，0-9，或.+-_

• AppLaunch - 运行游戏时应启动的应用程序可执行文件的路径，相对于BuildRoot并位于其中。对于Mac版本，这应该是.app文件夹中包含的可执行文件，通常位于 Game.app/Contents/MacOS/Game。

• AppArgs - 启动时要发送到应用程序的命令行。不需要额外参数时，可以将其设置为 “”。

• FileAttributeList （可选） - 一个文本文件的绝对路径，该文件包含一个文件列表以及应设置的对应特殊属性（例如，可执行位）。请参阅设置特殊文件属性，了解文件内容的说明。

  • 请注意，属性文件应放在 BuildRoot 之外，以免误与实际版本内容包含在一起。

• FileIgnoreList （可选） - 一个文本文件的绝对路径，该文件包含应从生成的补丁数据中排除的文件的列表。每个条目应独占一行，并且是相对于BuildRoot的路径。应使用正斜杠（“/”）分隔符。

  • 请注意，如果忽略文件位于 BuildRoot 之内，则其自己的相对文件路径需要包含在忽略列表中，以免将其包含在补丁数据中。

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

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

条目示例：

支持以下文件属性标记：

• executable

• tag:my_tag

文件标签主要用于在Windows机器中上传Mac版本时显式指示可执行文件。Epic Games启动程序的选择性下载功能也使用了这个功能，它可为包含较多本地化资产的有限数量的游戏降低下载大小。

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

• 更新应用程序可执行文件中嵌入的图标

• 添加与应用程序可执行文件同名的单独.ico文件（例如：如果可执行文件是launch.exe，应使用launch.ico）

你还可以查询后端，使用 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服务的两个二进制文件，并为在这两个特定版本之间更新的用户生成更小的下载。我们将其称为A到B补丁。运行此命令是可选的步骤，鉴于大部分玩家都是使用特定版本（版本“A”），发布比平常更大的补丁时，可以执行此步骤来改善用户体验。

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

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

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

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

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

• "最终未知压缩字节数，加上元 [Bytes]"

• 这指的是针对BuildVersionA和BuildVersionB之间的补丁实现的新下载大小。

• "原始未知压缩字节数 [Bytes]"

• 这指的是运行优化之前，BuildVersionA和BuildVersionB之间的补丁的下载大小。

• "改进：[Percentage]"

• 这将显示实现的改进情况。该百分比指的是缩减幅度，越大越好。

示例输出：

Epic Games商城提供了对可下载内容(DLC)的全面支持。

你可以选择产品（Product）> 构件（Artifacts）> 创建新构件（Create New Artifact），然后将新构件与你的附加商品关联，从而为相关附加商品启用构件下载。相应地，DLC的每个项目都需要各自的补丁生成过程，才能通过指定的合适构件ID执行。由于每个项目会单独生成，在为DLC项目执行补丁生成时，应务必确保基础游戏及所有其他DLC项目不同时出现在补丁生成过程中 BuildRoot 参数指定的文件夹中。或者，如果 BuildRoot 文件夹确实包含主游戏或其他DLC项目，则可以在BuildPatchTool命令行上指定 -FileIgnoreList 参数，在生成的二进制文件中将其排除。请参阅如何处理版本，了解详情。

安装在最终用户的机器上时，主游戏和相关DLC的所有项目将安装到同一个目录。这将造成如下限制：主游戏或DLC的所有项目中不得有文件使用相同的文件路径。BuildPatchTool将检查此情况，并且在有文件违反此规则时阻止补丁生成过程发生。这意味着，基础游戏必须能够按相对于安装位置的路径找到安装的DLC。

使用BPT时，请确保你的 命令行是精确的。如果存在偏差，你将收到消息，指出你遇到的错误。

请注意，这些只是常见错误。你可以在BPT中使用特定模式运行 -help 命令，详细了解可能导致错误的原因。

• 错误 - 从Epic服务检索二进制文件列表失败

• 错误 - 缺少参数

• 错误 - 缺少凭证

• 错误 - 身份验证错误

• 错误 - 意外错误

所使用的客户端ID和客户端密钥专用于BuildPatchTool；正确的客户端在“产品设置（Product Settings）”页面的“客户端（Clients）”分段中列为 BPT客户端（BPT Client）。可能存在其他客户端，用于与EOS功能交互，但它们没有BuildPatchTool权限。

• 提供了所有需要的参数

• 参数没有拼写错误，包括不正确的首字母大小写或空格问题

• 包含空格的参数缺少引号

含义 - 你所使用的客户端凭证并未授权上传到指定的构件。这可能是由于凭证或其他参数中有拼写错误，或者授予客户端的权限有问题。

含义 - BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数，或者未正确添加这些参数。

含义 - BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数，或者未正确添加这些参数。

含义 - 你所使用的客户端凭证与我们的记录不匹配。这可能是由于凭证或其他参数中有拼写错误，或者授予客户端的权限有问题。

含义 - 你所使用的客户端凭证无权访问你指定的构件。请确保你使用的是“产品设置（Product Settings）”页面上所指示的正确BPT客户端。