Play 自管式发布

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

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

准备工作

将 Google Play Games 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：游戏的软件包名称。 这是将与您的游戏相关联的唯一标识符。例如 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 文件的目录的相对路径。

    • 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”：以管理员身份运行。
        • “false”：以当前用户身份运行。如果未指定，则此值为默认值。

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

        • “true”：以管理员身份运行。
        • “false”：以当前用户身份运行。如果未指定，则此值为默认值。

      • 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：要存储在注册表键中的数据。

    如何使用正则表达式

    您可以在 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。

    如何使用 Play 发布工具

    如果您在当前工作目录中拥有 playpublishingtool.exe、play_publishing_config.xml 和 game_files/ 中的游戏文件，请执行以下操作：

    .\
├── 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