开始之前
如何查找凭证ID
你需要在开发人员门户中找到多个ID。
产品的客户端ID和客户端密钥
- 打开 开发人员门户操作面板(Developer Portal Dashboard)> 产品(Product)>游戏服务(Games Services)> 产品设置(Product Settings)按钮。
- 在 产品设置(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工具凭证:
- 登录开发者门户:
- 选择你想查看证书的产品。
- 选择 产品设置。
- 向下滚动到 SDK凭证 > BPT凭证。
- 点击 复制,复制证书到剪贴板:
命令行中的路径
由于命令提示符在命令行上对 \"
(反斜杠直接后跟双引号)有独特的解释方式,所以在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
中。
- 与 BuildRoot 一样,这应该是驱动器根目录中的绝对路径。此位置用于缓存现有版本信息,并且应该是不同于 BuildRoot 参数的目录。此目录初始为空是没有问题的,BuildPatchTool会根据需要从Epic后端下载信息,并将其存储在
-
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]"
-
这将显示实现的改进情况。该百分比指的是缩减幅度,越大越好。
示例输出:
可下载内容(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服务检索二进制文件列表失败
含义 - 你所使用的客户端凭证并未授权上传到指定的构件。这可能是由于凭证或其他参数中有拼写错误,或者授予客户端的权限有问题。
错误-缺少参数
含义 - BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数,或者未正确添加这些参数。
错误-缺少凭证
含义 - BPT未检测到上面所列的一个或多个参数。这可能就是因为缺少这些参数,或者未正确添加这些参数。
错误-身份验证错误
含义 - 你所使用的客户端凭证与我们的记录不匹配。这可能是由于凭证或其他参数中有拼写错误,或者授予客户端的权限有问题。
错误-意外错误
含义 - 你所使用的客户端凭证无权访问你指定的构件。请确保你使用的是“产品设置(Product Settings)”页面上所指示的正确BPT客户端。