BuildPatch Tool (BPT)说明1.4.0

介绍设置和处理方法(封闭测试版)

你是封闭测试伙伴吗?如果你未参加 封闭测试 版本,可以使用你的Epic Games账号登录知识库来访问文档。

开始之前

如何查找凭证ID

你需要在开发人员门户中找到多个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工具凭证。他们还可以将证书复制到剪贴板上。

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

  1. 登录开发者门户

  2. 选择你想查看证书的产品。

  3. 选择 产品设置

  4. 向下滚动到 SDK凭证 > BPT凭证

  5. 点击 复制,复制证书到剪贴板:

copy14.png

命令行中的路径

由于命令提示符在命令行上对 \"(反斜杠直接后跟双引号)有独特的解释方式,所以在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 参数。客户端密钥必须使用 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/ 目录。从命令行以 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 - 包含待读取和处理版本的目录路径。这应该是驱动器根目录中的绝对路径,而不是相对路径。此外,建议将此路径放在靠近驱动器根目录的位置,以免文件超出操作系统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的)文件路径,后跟要应用于所引用文件的一个或多个以空格分隔的属性:

    "<用引号括起的文件相对路径>" <属性列表>

条目示例:

    "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启动程序的选择性下载功能也使用了这个功能,它可为包含较多本地化资产的有限数量的游戏降低下载大小。

设置桌面快捷方式图标

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

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

  • 添加与应用程序可执行文件同名的单独.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 构件,此功能很有用。

你还可以在开发人员门户发布工具中使用 复制到其他构件(Duplicate to another artifact) 功能。

运行 -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"),发布比平常更大的补丁时,可以执行此步骤来改善用户体验。

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

    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到B特定补丁数据。如果 BuildVersionABuildVersionB 之间的原始下载大小很大,此过程耗时可能超过标准PatchGeneration模式。

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

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

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

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

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

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

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

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

  • "改进:[Percentage]"

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

示例输出:

    …
        最终未知压缩字节数,加上元 400000
        原始未知压缩字节数         1000000
        改进:60%

可下载内容(DLC)

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

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

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

常见错误的故障排除

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

常见错误

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

要检查的事项

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

  • 提供了所有需要的参数

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

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

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

    请检查提供的OrganizationId、ProductId和ArtifactId是否
    正确,以及你是否应该有权为此构件创建
    二进制文件。
    工具退出时返回:6

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

错误-缺少参数

    CloudDir、BuildRoot、ArtifactId、BuildVersion、AppLaunch和AppArgs
    是必需的参数
    工具退出时返回:2

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

错误-缺少凭证

    请确保你指定了ClientId,以及ClientSecret或
    ClientSecretEnvVar。如果使用ClientSecretEnvVar,请确保env变量
    已正确设置。
    工具退出时返回:9

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

错误-身份验证错误

    发生身份验证错误 - 请检查你是否正确指定了ClientId,以及
    ClientSecret或ClientSecretEnvVar参数。
    消息:抱歉,你所使用的客户端凭证无效
    工具退出时返回:10

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

错误-意外错误

    发生意外错误。错误代码:errors.com.epicgames.common.missing_permission;
    错误消息:抱歉,你的登录名不具备权限
    'artifact:o-7kyv8uwtz74njnl544kbxzt5xqephw:3bc138d96fb24d9597d4bbff23b9ecee:asdfasd READ'
    ,无法执行请求的操作
    工具退出时返回:5

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