انتشارات مدیریت‌شده‌ی بازی

این سند به شما نشان می‌دهد که چگونه بازی خود را با استفاده از نصب مدیریت‌شده‌ی Play، در Google Play Games روی رایانه شخصی منتشر کنید.

با نصب مدیریت‌شده‌ی بازی (Play Managed Installation)، گوگل پلی نصب، به‌روزرسانی و حذف نصب بازی را با استفاده از فایل‌های بازی و فراداده‌هایی که شما در یک فایل بسته‌ی نرم‌افزاری ویندوز (WAB) ارائه می‌دهید، مدیریت می‌کند.

قبل از اینکه شروع کنی

کیت توسعه نرم‌افزاری بازی‌های گوگل پلی را در بازی خود ادغام کنید.

بازی خود را به صورت یک فایل WAB بسته‌بندی کنید

برای ایجاد یک فایل WAB نصب مدیریت‌شده‌ی Play، این مراحل را دنبال کنید:

  1. ابزار انتشار Play را دانلود کنید. می‌توانید این ابزار را در خط فرمان ویندوز یا 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 باشد.

    • exclusions : (اختیاری) مسیرها یا الگوهای فایل را برای فایل‌های درون PATH_TO_ROOT_FOLDER مشخص می‌کند تا از بسته حذف شوند. می‌توانید چندین عنصر file-path درون عنصر exclusions قرار دهید. یک مسیر را می‌توان به یکی از دو روش زیر نمایش داد:

      • به عنوان مسیر فایل : مسیر فایلی که باید حذف شود.
      • به عنوان یک رشته‌ی regex : تمام فایل‌هایی که با رشته‌ی عبارت منظم مطابقت دارند، از بسته حذف می‌شوند. از سینتکس RE2 استفاده کنید.

    • file-attribute : (اختیاری) ویژگی‌هایی را برای فایل‌های خاص یا فایل‌هایی که با الگوی عبارات منظم مطابقت دارند، تعریف می‌کند.

      • FILE_ATTRIBUTE_VALUE : می‌تواند یکی از موارد زیر باشد:
        • SKIP_UPDATE : در طول به‌روزرسانی، این ویژگی به سیستم می‌گوید که فقط در صورتی که فایل از قبل وجود ندارد، آن را کپی کند و هرگونه تغییری در فایل موجود را حفظ کند.
        • MODIFIED_ON_DEVICE : از این برای فایل‌هایی استفاده کنید که باید به‌روزرسانی شوند، اما می‌توانند پس از نصب روی دستگاه تغییر کنند. سیستم فایل جدید کامل را دانلود می‌کند و نسخه نصب شده را در حین به‌روزرسانی بازنویسی می‌کند. اگر این فایل در حین بررسی صحت نصب با نسخه نصب شده متفاوت باشد، نصب خراب تلقی نمی‌شود.
      • file-path : فایل‌های مربوط به این ویژگی را شناسایی می‌کند. می‌توانید چندین عنصر file-path را درون هر عنصر file-attribute قرار دهید. هر مسیر را می‌توان به یکی از دو روش زیر نمایش داد:
        • به عنوان مسیر فایل : مسیر فایلی که این ویژگی به آن مرتبط می‌شود.
        • به عنوان یک رشته regex : تمام فایل‌هایی که با رشته عبارت منظم مطابقت دارند، با مقدار ویژگی مرتبط می‌شوند. از سینتکس 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 : یک ورودی رجیستری ویندوز ایجاد یا به‌روزرسانی می‌کند.

        • BASE_KEY : کلید ریشه‌ای که در رجیستری ویندوز استفاده می‌شود را تعریف می‌کند. مقادیر پذیرفته شده: HKEY_CLASSES_ROOT ، HKEY_CURRENT_CONFIG ، HKEY_CURRENT_USER ، HKEY_LOCAL_MACHINE ، HKEY_PERFORMANCE_DATA و HKEY_USERS . هنگام انجام عملیات update-registry ، بر اساس baseKey استفاده شده requiresElevation="true" را روی install-operation والد تنظیم کنید:
          • 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 : این مسیر یک کلید خاص در رجیستری ویندوز را نشان می‌دهد که زیر کلید اصلی baseKey قرار دارد.
        • VALUE_NAME : این نام ورودی داده‌ای را که می‌خواهید در زیرکلید تعیین‌شده تغییر دهید، مشخص می‌کند.
        • REGISTRY_VALUE_TYPE : این ویژگی نوع داده مقداری که در رجیستری نوشته می‌شود را مشخص می‌کند. مقادیر پشتیبانی‌شده برای رشته STRING یا برای عدد ۳۲ بیتی DWORD هستند.
        • VALUE_TEXT : داده‌هایی که قرار است در کلید رجیستری ذخیره شوند.

    نحوه استفاده از عبارات منظم

    شما می‌توانید از عبارات منظم با سینتکس RE2 در تگ‌های file-path برای اعمال استثنائات یا ویژگی‌های فایل به گروهی از فایل‌ها استفاده کنید. به یاد داشته باشید که از اسلش‌های رو به جلو / برای جداکننده‌های دایرکتوری استفاده کنید و برای escape کردن کاراکترهای خاص عبارات منظم از \ استفاده کنید. به عنوان مثال، از \. برای مطابقت با یک نقطه تحت‌اللفظی . یا \d برای مطابقت با یک رقم استفاده کنید.

    در اینجا چند مثال رایج آورده شده است:

    • تمام فایل‌هایی که پسوند خاصی دارند (مثلاً ‎.log) را در هر دایرکتوری مطابقت می‌دهد

      برای تطبیق هر مسیری که به .log ختم می‌شود، مانند game.log یا logs/errors.log ، .*\.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>
    • فایل‌هایی با پسوند خاص در دایرکتوری‌های خاص را پیدا کنید (برای مثال، ‎.ogg در music/ یا sfx/)

      از (music|sfx)/.*\.ogg ‎ برای تطبیق هر فایل .ogg ‎ که در دایرکتوری‌های music/ ‎ یا sfx/ ‎ قرار دارند، اما در جای دیگری قرار ندارند، استفاده کنید. music/level1.ogg ‎ یا sfx/explosion.ogg ‎ مطابقت دارد، اما voice/intro.ogg ‎ مطابقت ندارد.

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

    مثال فایل پیکربندی انتشار Play

    در اینجا مثالی از play_publishing_config.xml برای بازی‌ای به نام TestGame آورده شده است: 

    <?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. ابزار انتشار Play را در خط فرمان ویندوز یا Powershell با استفاده از دستور build-bundle اجرا کنید: 

    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