Play 自管式发布

本文档介绍了如何使用 Play 自管式安装在 Google Play 游戏电脑版上发布游戏。

借助 Play 自管式安装，Google Play 可以使用您在 Windows 应用软件包 (WAB) 文件中提供的游戏文件和元数据来管理游戏的安装、更新和卸载。

准备工作

将 Google Play 游戏 SDK 集成到游戏中。

将游戏打包为 WAB 文件

如需创建 Play 自管式安装 WAB 文件，请按以下步骤操作：

1. 下载 Play 发布工具。 您可以在 Windows 命令行或 Powershell 中运行此工具。

2. 创建 Play 发布配置文件，并使用任意名称。例如，play_publishing_config.xml，格式如下：

   <?xml version="1.0" encoding="UTF-8"?>
   <play-publishing-config version="1.0">
     <!-- Application metadata: This section contains basic information about your game. -->
     <application>
       <package-name>PACKAGE_NAME</package-name>
       <version-name>VERSION_NAME</version-name>
     </application>
   
     <!-- Game files: This section specifies which game files to include in the bundle and how to treat them. -->
     <game-files>
       <file-set>
         <root-folder-path>PATH_TO_ROOT_FOLDER</root-folder-path>
         <!-- absolute or relative to the parent directory of the config xml -->
         <!-- Exclusions: A list of files or folders to exclude from the bundle.
              This is useful for removing development files, temporary data, or redundant assets. -->
         <exclusions>
           <file-path>REGEX_PATTERN_OF_EXCLUDED_FILES</file-path>
           <file-path>PATH_TO_BE_EXCLUDED</file-path>
         </exclusions>
   
         <!-- File attributes: Define special handling for certain files during installation and updates. -->
         <file-attribute value=FILE_ATTRIBUTE_VALUE>
           <file-path>PATH_TO_FILE</file-path>
           <file-path>REGEX_PATTERN_OF_FILE_ATTRIBUTE_FILES</file-path>
         </file-attribute>
       </file-set>
     </game-files>
   
     <!-- This file represents the startup process for this game. Google Play Games for PC should start
         this process when user clicks on "Play" on this game. -->
     <launch-command>
       <path>PATH_TO_LAUNCH_FILE</path>
       <arguments>ARGUMENTS</arguments>
     </launch-command>
   
     <!-- Lifecycle operations: Custom actions to be performed during the game's installation and uninstallation. -->
     <lifecycle-operations>
       <!-- Install operations: These actions run when the game is installed. 'requiresElevation="true"'
           will trigger a UAC prompt for administrator rights. There are three types of install
           operations that can be specified. An instance of each is listed below. -->
       <install-operation requiresElevation=INSTALL_OPERATION_REQUIRES_ELEVATION>
         <operation-identifier>OPERATION_IDENTIFIER_STRING</operation-identifier>
         <execute-file>
           <path>PATH_TO_INSTALL_EXECUTE_FILE</path>
           <arguments>ARGUMENTS</arguments>
         </execute-file>
       </install-operation>
   
       <install-operation requiresElevation=INSTALL_OPERATION_REQUIRES_ELEVATION>
         <operation-identifier>OPERATION_IDENTIFIER_STRING</operation-identifier>
         <update-registry baseKey=BASE_KEY>
           <sub-key>SUB_KEY_PATH</sub-key>
           <value-name>VALUE_NAME</value-name>
           <value type=REGISTRY_VALUE_TYPE>VALUE_TEXT</value>
         </update-registry>
       </install-operation>
   
       <!-- Uninstall operations: These actions run before the game is uninstalled. -->
       <uninstall-operation requiresElevation=UNINSTALL_OPERATION_REQUIRES_ELEVATION>
         <execute-file>
           <path>PATH_TO_UNINSTALL_EXECUTE_FILE</path>
           <arguments>ARGUMENTS</arguments>
         </execute-file>
       </uninstall-operation>
     </lifecycle-operations>
   </play-publishing-config>

   替换以下内容：

   • PACKAGE_NAME：游戏的软件包名称。 这是与您的游戏在 Google Play 上关联的唯一标识符。例如，com.yourcompany.yourgame。 软件包名称必须遵循以下规则：
     • 必须至少包含两段（一个或多个点号）。
     • 每段必须以字母开头。
     • 所有字符必须为字母数字或下划线 ([a-zA-Z0-9_])。
   • VERSION_NAME：游戏的版本字符串。这可以是任意字符串，但对于您游戏的所有已上传 WAB，它必须是唯一的。例如：1.0、1.0.1-beta、2025.11.24、v1.rc1。

   • PATH_TO_ROOT_FOLDER：包含游戏文件的根文件夹的路径。此文件夹中的所有文件（排除项中提及的文件除外）都会添加到软件包中。此路径可以是相对于包含 play_publishing_config.xml 文件的目录的绝对路径或相对路径。

     **注意**： 除了 PATH_TO_ROOT_FOLDER 之外，此 XML 配置文件中指定的所有文件路径都可以是相对于 PATH_TO_ROOT_FOLDER 的相对路径，也可以是绝对路径。

   • exclusions：（可选）指定 PATH_TO_ROOT_FOLDER 中要从软件包中排除的文件的文件路径或模式。您可以在 exclusions 元素中包含多个 file-path 元素。路径可以通过以下两种方式之一表示：

     • 作为文件路径：要排除的文件的路径。
     • 作为正则表达式字符串：与正则表达式字符串匹配的所有文件都会从软件包中 排除。使用 RE2 语法。

   • file-attribute：（可选）为特定文件或与正则表达式模式匹配的文件定义属性。

     • FILE_ATTRIBUTE_VALUE：可以是以下值之一：
       • SKIP_UPDATE：在更新期间，此属性会告知系统仅在文件尚不存在时复制该文件，从而保留对现有文件的任何更改。
       • MODIFIED_ON_DEVICE：用于必须更新但在安装后可能会在设备上修改的文件。在更新期间，系统会下载完整的新文件并覆盖已安装的版本。如果在安装完整性检查期间此文件与已安装的版本不同，则安装不会被视为损坏。
     • file-path：标识此属性的文件。您可以在每个 file-attribute 元素中包含多个 file-path 元素。每个路径可以通过以下两种方式之一表示：
       • 作为文件路径：要与此属性关联的文件的路径。
       • 作为正则表达式字符串：与正则表达式字符串匹配的所有文件 都会与属性值关联。使用 RE2 语法。

   • PATH_TO_LAUNCH_FILE：用于启动游戏的可执行文件的路径。

   • ARGUMENTS：（可选）命令行实参。<arguments> 元素用于将实参传递给在 <launch-command>、<install-operation> 或 <uninstall-operation> 中指定的可执行文件。 每次使用 <arguments> 元素时，它仅适用于与其一起定义的可执行文件，因此您可以为不同的可执行文件指定不同的实参。

     • 如果可执行文件有多个实参，请用空格分隔它们。
     • 如果可执行文件需要，请在实参前加上 -- 或 -。 例如：

       <arguments>--package_name --version_name</arguments>

   • lifecycle-operations：（可选）在游戏安装或卸载期间执行的自定义操作。

     • install-operation：在安装游戏时运行的操作。 您可以指定两种类型的安装操作：execute-file 和 update-registry。
     • uninstall-operation：在卸载游戏之前运行的操作。update-registry 操作会在卸载期间自动恢复。

     • INSTALL_OPERATION_REQUIRES_ELEVATION：指示安装操作是否需要以管理员权限运行。

       • “true” ：以管理员身份运行。
       警告： 向游戏玩家显示 UAC 提示。
       • “false” ：以当前用户身份运行。如果未指定，则这是默认值。

     • UNINSTALL_OPERATION_REQUIRES_ELEVATION：指示卸载操作是否需要以管理员权限运行。

       • “true” ：以管理员身份运行。
       警告： 向游戏玩家显示 UAC 提示。
       • “false” ：以当前用户身份运行。如果未指定，则这是默认值。
       注意： 如果 <install-operation> 或 <uninstall-operation> 包含 <execute-file> 操作，并且您设置了 requiresElevation="true"，则 该操作中指定的可执行文件必须使用 Authenticode 签名进行签名。

     • operation-identifier：用于标识 install-operation 的唯一字符串。

     • execute-file：运行可执行文件。

       • PATH_TO_INSTALL_EXECUTE_FILE：在安装期间运行的可执行文件的路径。
       • PATH_TO_UNINSTALL_EXECUTE_FILE：在卸载之前运行的可执行文件的路径。

     • update-registry：创建或更新 Windows 注册表条目。

       • BASE_KEY：定义要在 Windows 注册表中使用的根键。接受的值：HKEY_CLASSES_ROOT、HKEY_CURRENT_CONFIG、HKEY_CURRENT_USER、HKEY_LOCAL_MACHINE、HKEY_PERFORMANCE_DATA 和 HKEY_USERS。 执行 update-registry 操作时，请根据所使用的 baseKey 在父级 install-operation 上设置 requiresElevation="true"：
         • HKEY_LOCAL_MACHINE 或 HKEY_CURRENT_CONFIG: 设置 requiresElevation="true"。
         • HKEY_CURRENT_USER：不需要 requiresElevation="true"。
         • HKEY_CLASSES_ROOT：仅当写入到机器级 部分时才设置 requiresElevation="true"；对于用户专用部分，则不需要此设置。
         • HKEY_USERS：包含所有用户的个人资料。修改当前用户以外的个人资料（例如，其他用户或 .DEFAULT）时，请设置 requiresElevation="true"。
       • SUB_KEY_PATH：表示 Windows 注册表中特定键的路径，嵌套在主 baseKey 下。
       • VALUE_NAME：指定您要在指定子键中修改的数据条目的名称。
       • REGISTRY_VALUE_TYPE：此属性指定写入注册表的值的数据类型。支持的值为 STRING（用于字符串）或 DWORD（用于 32 位数字）。
       • VALUE_TEXT：要存储在注册表键中的数据。
   注意： 如需包含不应解析为 XML 标记的特殊字符文本块，请使用 CDATA 部分。例如：

   <file-path><![CDATA[file path with special characters <>]]></file-path>

   注意 ：验证您提供的任何游戏二进制文件是否面向在 x86 或 x64 架构上运行。不支持其他架构的二进制文件。
   重要提示：文件路径的正则表达式：

   使用正则表达式指定文件路径（例如，用于排除项或属性）时，务必使用正斜线 (/) 作为目录分隔符。这是因为无论您的操作系统是什么，该工具都会在内部将所有文件路径规范化为使用正斜线。

   反斜线 (\\) 仅应用于正则表达式中的标准 用途：转义特殊字符。

   示例：如需排除 testing 目录中的日志文件（例如 test_failed1.log、test_failed2.log）：

   正确： testing/test_failed\d\.log
   / 用于目录。
   \d 与任何数字匹配。
   \. 与字面量点匹配。

   不正确： testing\\test_failed\d\.log
   在此处使用 \\ 作为路径分隔符会与 RE2 对 \\t 和 \\d 作为转义序列的解释冲突， 从而导致意外行为。

   如需更多示例，请参阅如何使用正则表达式。

   如何使用正则表达式

   您可以在 file-path 标记中使用 RE2 语法的正则表达式，以将排除项或文件属性应用于一组文件。请记得使用正斜线 / 作为目录分隔符，并使用反斜线 \ 转义特殊正则表达式字符。例如，使用 \. 与字面量点 . 匹配，或 \d 与数字匹配。

   以下是一些常见示例：

   • 匹配任何目录中具有特定扩展名（例如 .log）的所有文件

     使用 .*\.log 匹配以 .log 结尾的任何路径，例如 game.log 或 logs/errors.log。

     <file-path>.*\.log</file-path>

   • 匹配特定文件夹（例如“temp”）中的所有文件和子目录

     使用 temp/.* 匹配以 temp/ 开头的所有路径，例如 temp/data.txt 或 temp/saves/file.sav。

     <file-path>temp/.*</file-path>

   • 匹配特定文件夹中与模式匹配的文件

     使用 assets/level\d\.dat 匹配 assets/level1.dat、assets/level2.dat，但不匹配 assets/other.dat。

     <file-path>assets/level\d\.dat</file-path>

   • 匹配路径中任何位置出现的文件夹名称

     使用 .*/cache/.* 匹配名为 cache 的任何目录下的文件，例如 game/cache/file.txt 或 temp/cache/other.log。

     <file-path>.*/cache/.*</file-path>

   • 匹配具有多个扩展名之一（例如 .ini、.cfg、.sav）的文件

     使用 .*\.(ini|cfg|sav) 匹配以 .ini、.cfg 或 .sav 结尾的任何文件，例如 settings.ini、 config.cfg 或 saves/slot1.sav。

     <file-path>.*\.(ini|cfg|sav)</file-path>

   • 匹配特定目录中具有特定扩展名的文件（例如 music/ 或 sfx/ 中的 .ogg）

     使用 (music|sfx)/.*\.ogg 匹配位于 music/ 或 sfx/ 目录下的任何 .ogg 文件，但不匹配其他位置的文件。匹配 music/level1.ogg 或 sfx/explosion.ogg，但不匹配 voice/intro.ogg。

     <file-path>(music|sfx)/.*\.ogg</file-path>

   Play 发布配置文件示例

   以下是名为 TestGame 的游戏的 play_publishing_config.xml 示例：

   <?xml version="1.0" encoding="UTF-8"?>
   <play-publishing-config version="1.0">
     <application>
       <package-name>com.test.package</package-name>
       <version-name>1.0</version-name>
     </application>
   
     <game-files>
       <file-set>
         <root-folder-path>C:\Users\Username\game-files</root-folder-path>
         <exclusions>
           <file-path>mock_game\d\.exe</file-path> <!-- exclude files using a regex -->
           <file-path>deprecated_graphics</file-path> <!-- exclude a folder -->
           <file-path>.*\.log</file-path> <!-- recursively exclude all files with .log extension -->
         </exclusions>
   
         <file-attribute value="SKIP_UPDATE">
           <file-path>settings.ini</file-path>
         </file-attribute>
   
         <file-attribute value="MODIFIED_ON_DEVICE">
           <file-path>game_assets\d\.zip</file-path> <!-- define the path using regex -->
         </file-attribute>
       </file-set>
     </game-files>
   
     <launch-command>
       <path>launcher_test_game.exe</path>
       <arguments>--launch-arg</arguments> <!-- optional -->
     </launch-command>
   
     <lifecycle-operations>
       <install-operation requiresElevation="true">
         <operation-identifier>elevated-execute-file</operation-identifier>
         <execute-file>
           <path>install_file.exe</path>
           <arguments>--arg</arguments> <!-- optional -->
         </execute-file>
       </install-operation>
   
       <install-operation requiresElevation="true">
         <operation-identifier>elevated-update-registry</operation-identifier>
         <update-registry baseKey="HKEY_LOCAL_MACHINE">
           <sub-key>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\TestGame</sub-key>
           <value-name>InstallLocation</value-name>
           <value type="STRING">C:\Program Files\TestGame</value>
         </update-registry>
       </install-operation>
   
       <uninstall-operation requiresElevation="true">
         <execute-file>
           <path>uninstall.exe</path>
           <arguments>--test-arg</arguments> <!-- optional -->
         </execute-file>
       </uninstall-operation>
     </lifecycle-operations>
   </play-publishing-config>

3. 在 Windows 命令行或 Powershell 中使用 build-bundle 命令运行 Play 发布工具：

   playpublishingtool.exe build-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH
   

   如需使用同名文件覆盖现有 WAB 文件，请使用 --force 实参。

   playpublishingtool.exe build-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH --force
   

   替换以下内容：

   • PLAY_PUBLISHING_CONFIG_PATH：Play 发布配置的路径。例如，path\to\play_publishing_config.xml。
   • WAB_OUTPUT_PATH：WAB 文件的路径。 例如，path\to\output_bundle.wab。
   重要提示 ：--output 中的 WAB 文件名必须具有 .wab 扩展名。
   注意 ：--input 和 --output 路径可以是相对于当前工作目录的绝对路径或相对路径。

   如何使用 Play 发布工具

   如果您在当前工作目录的 game_files/ 中有 playpublishingtool.exe、play_publishing_config.xml 和游戏文件：

   .\
   ├── game_files/
   ├── play_publishing_config.xml
   ├── playpublishingtool.exe
   

   如需在同一目录中创建 pmi_bundle.wab，请运行：

   playpublishingtool.exe build-bundle --input=play_publishing_config.xml --output=pmi_bundle.wab
   

   当该工具构建软件包时，您会在终端上看到进度条：

   Building bundle: [====       ] 40%
   

   成功后，您应该会看到类似于以下内容的输出：

   Building bundle: [===========] 100%
   Successfully built the managed install bundle at pmi_bundle.wab
   

   在文件夹中找到 WAB 文件：

     .\
     ├── game_files/
     ├── pmi_bundle.wab
     ├── play_publishing_config.xml
     ├── playpublishingtool.exe