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 上的遊戲相關聯的專屬 ID。例如：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 元素。路徑可透過下列兩種方式表示：

      • 做為檔案路徑：要排除的檔案路徑。
      • 做為 regex 字串：系統會從套件中排除所有符合規則運算式字串的檔案。使用 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 或 32 位元數字的 DWORD。
        • 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>

    Google 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