> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 搭配 GameMaker 使用 GDK

> 使用 GMEXT-GDK 擴充功能、Visual Studio 2022、CMake 和 2024 年 6 月 GDK 版本，準備 GameMaker Studio 2 遊戲以發行至 Microsoft Store。

本文說明如何準備您的 GameMaker 遊戲以發行至 Microsoft Store。

* [安裝必要軟體](#install-the-required-software)
* [下載並安裝 GameMaker Studio 2](#download-and-install-gamemaker-studio-2)
* [GameMaker Studio 2 - Microsoft Game Development Kit (GDK) 擴充功能](#set-up-gamemaker-studio-2-gdk-extension)
* [建置 GDK 擴充功能](#build-the-gdk-extension)
* [在 Microsoft Partner Center 中建立產品](#create-a-product-in-microsoft-partner-center)
* [測試 GDK 擴充功能](#test-the-gdk-extension)
* [更新 MicrosoftGame.config](#update-microsoftgame-config)
* [將 GDK 擴充功能整合到您自己的專案中](#integrate-the-gdk-extension-into-your-project)
* [在遊戲中測試 XBOX services](#test-xbox-services-in-your-game)
* [發行](#publish-your-game)

## 安裝必要軟體

若要搭配 Microsoft Game Development Kit (GDK) 使用 GameMaker Studio 2，請下載下列軟體：

* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
* [2024 年 6 月 GDK](https://github.com/microsoft/GDK/releases/tag/June_2024_Update_2) 或更新版本
* [CMake](https://cmake.org/download/)
  * 確定 CMake 安裝程式會更新系統路徑。否則，擴充功能專案會找不到 CMake。

## 更新 Gaming Runtime Services (GRTS) 和 PC Bootstrapper

PC Bootstrapper 是 PC 遊戲啟動體驗的一部分，於 2022 年 5 月的 GRTS 版本中推出。PC Bootstrapper 相依於 GRTS，並仰賴 GRTS 才能正常運作。如果您開發 PC 上的 GRTS 已過時，登入嘗試可能會失敗並傳回 `E_FAIL` 錯誤。

如需 PC Bootstrapper 的詳細指引，包括其在遊戲啟動程序中的角色以及它如何與 GRTS 互動，請參閱 [PC Bootstrapper 概觀](/zh-TW/build/gdk-and-engines/guides/pc-bootstrapper)。

## 下載並安裝 GameMaker Studio 2

如果您尚未安裝 GameMaker Studio 2，請從 [https://www.yoyogames.com](https://www.yoyogames.com/) 下載並安裝。

## 設定 GameMaker Studio 2 GDK 擴充功能

若要搭配 GameMaker Studio 2 使用 GDK，需要 GameMaker Studio 2 GDK 擴充功能。如需擴充功能的原始程式碼和設定指示，請參閱 [https://github.com/YoYoGames/GMEXT-GDK](https://github.com/YoYoGames/GMEXT-GDK)。

請使用存放庫根目錄中 README 檔案內的步驟。這些步驟可讓您設定並建置 GameMaker Studio 2 GDK 擴充功能，以便將 XBOX services 和功能整合到 GameMaker 專案中。

複製 GDKExtension 存放庫時，請使用 `--recurse-submodules` 參數來包含子模組。否則，建置方案時會缺少必要的檔案。

如需擴充功能的相關資訊，請參閱 [https://github.com/YoYoGames/GMEXT-GDK/wiki](https://github.com/YoYoGames/GMEXT-GDK/wiki)。

## 建置 GDK 擴充功能

請使用存放庫根目錄中 README 檔案內的指示，在 Visual Studio 2022 中建置擴充功能。需要使用 GDKExtension.sln 檔案 (\<project\_root>/source/GDKExtension\_gml/extensions/GDKExtension/gdkextension\_windows/GDKExtension.sln)。如需詳細的建置指示，請參閱存放庫根目錄中 README 檔案內的建置步驟。

## 在 Microsoft Partner Center 中建立產品

若要在 Partner Center 中建立已啟用 XBOX services 的產品，請參閱[在 Partner Center 中設定應用程式或遊戲 (適用於受管理的合作夥伴)](/zh-TW/services/xbox-services/fundamentals/portal-config/live-setup-partner-center-partners)。建立產品之後，您可以測試 XBOX services，或將遊戲發行至 Microsoft Store。

## 測試 GDK 擴充功能

GDK 擴充功能存放庫包含一個範例專案，示範如何將 GDK 外掛程式與 GameMaker Studio 2 專案整合。範例專案檔案位於 `source/GDKExtension_gml/GDKExtension.yyp`。

在 GameMaker 中建置範例專案 (**Build**>**Create Executable**) 時，請選取 **Package as Zip** 以產生安裝應用程式所需的 MSIXVC 套件。如果您選取 **Package as Installer**，建置不會產生 MSIXVC 套件，應用程式也無法存取 XBOX services。

建置完成時，會開啟一個檔案總管視窗，顯示所建立的 .zip 檔案及其子目錄。該子目錄的名稱與套件相同，並包含 MSIXVC 檔案。

此外，GameMaker Studio 2 輸出視窗會顯示一行程式碼，其中包含 MSIXVC 套件的完整輸出路徑，如下列範例所示。

`C:\Users\your-user-name\XboxDeveloperExperienceTe.GamePassSampleGame_1.0.0.0_x64__pmsd8ndztetqc-pkg`

若要執行範例專案並讓它能存取 XBOX services，請使用 `wdapp install` 搭配您的套件名稱來安裝套件，如下列範例所示。

`wdapp install XboxDeveloperExperienceTe.GamePassSampleGame_1.0.0.0_x64__pmsd8ndztetqc.msixvc`

套件安裝完成後，請使用 **開始** 按鈕啟動它。

## 更新 MicrosoftGame.config

範例專案使用預設的 MicrosoftGame.config 檔案。若要使用您專案的 Partner Center 設定資訊來測試範例或您自己的 GameMaker Studio 2 專案，請更新 MicrosoftGame.config 檔案。

範例的 .config 檔案位於 source/GDKExtension\_gml/datafiles/MicrosoftGame.config。

若要使用 XBOX services 功能，請依照下列步驟，以您的 Partner Center 專案識別詳細資料更新專案的 MicrosoftGame.config。

1. 移至 [Partner Center 儀表板](https://partner.microsoft.com/dashboard/windows/overview)。
2. 從產品清單中選取您的遊戲。
3. 選取 **Game setup** 索引標籤，然後選取 **Identity details**。
4. 選取 **Show Details** 以展開 **Identity details** 區段。
5. 使用 **Identity details** 區段表格中的下列值。將這些值從 Partner Center 複製到 MicrosoftGame.config 中對應的元素和欄位。

| Partner Center 中的名稱 | MicrosoftGame.config |
| - | - |
| XBOX Title ID | TitleId |
| Package/Identity/Name | Identity->Name |
| Package/Identity/Publisher | Identity->Publisher |
| XBOX services > XBOX Settings > MSAAppId | MSAAppId |

Partner Center 識別詳細資料決定了 MicrosoftGame.config 檔案的內容，如下列範例所示。

| Partner Center 中的名稱 | 範例值 |
| - | - |
| XBOX Title ID | 64353034 |
| Package/Identity/Name | 41336MicrosoftATG.Achievements2017Redux |
| Package/Identity/Publisher | CN=A4954634-DF4B-47C7-AB70-D3215D246AF1 |
| XBOX services > XBOX Settings > MSAAppId | 0000000000000000 |

### MicrosoftGame.config 檔案摘錄範例

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>
```

如需 MicrosoftGame.config 的概觀及其值的相關資訊，請參閱 [MicrosoftGame.config 概觀](/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Overview)。

## 將 GDK 擴充功能整合到您的專案中

您的專案至少需要呼叫下列函式才能與 GDK 整合。

* 呼叫 `gdk_init` 以初始化 GDK。您必須先呼叫 `gdk_init`，才能使用任何其他 GDK 功能。
* 在 GDK 作用期間，每個畫面呼叫一次 `gdk_update`。
* 當您的專案結束且不再需要任何 GDK 功能時，呼叫 `gdk_quit` 以清除 GDK。

此外，GDK 擴充功能具有下列模組，可提供 GDK 功能的存取權。

* **Base Module：** 提供一組函式，用於控制玩家的使用者/帳戶選取。
* **Storage Module：** 提供一組函式，用於控制與使用者相關聯之資料的載入和儲存。
* **XBOX services Module：** 提供函式以使用 XBOX services 的功能，包括統計資料、排行榜、成就和 Rich Presence。
* **In-App Purchases Module：** 提供函式，透過 GDK 將 GameMaker 專案與 Microsoft Store 商務系統整合。

GDKExtension 存放庫中隨附的指南，在 GDK Extension APIs 區段中提供 GDK 函式的文件。該指南是一個 .pdf 檔案，位於 source/GDKExtension\_gml/datafiles/GDK\_Extension\_Documentation.pdf。

## 在遊戲中測試 XBOX services

若要在遊戲中測試 XBOX services 功能 (例如成就)，請使用沙箱以及可存取該沙箱的測試帳戶。

### 建立測試帳戶

若要在遊戲中測試任何 XBOX services 功能，請建立可存取您開發沙箱的測試帳戶。如需相關指示，請參閱[建立測試帳戶](/zh-TW/services/xbox-services/develop/test-accounts/live-setup-testaccounts)。

### 切換沙箱

1. 移至 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)。
2. 若要尋找您的沙箱 ID，請選取 **XBOX services**，然後選取 **Gameplay settings**。
   <Note>
     您的沙箱 ID 會顯示在 **Gameplay settings** 頁面的第一個索引標籤上。其名稱類似 "ABCDEF.0"。
   </Note>
3. 選取 **開始** 按鈕。
4. 輸入 **Microsoft GDK Command Prompts**，然後選取 **Enter**。
5. 開啟第一個命令提示字元，然後輸入 **XblPCSandbox.exe \<your sandbox ID>**。
6. 命令提示字元啟動數個應用程式之後，使用您的測試帳戶登入 XBOX 應用程式。

如果您能成功登入，就可以開始在沙箱中進行測試。

如需沙箱的詳細資訊，請參閱 [XBOX services 沙箱概觀](/zh-TW/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)。

## 發行您的遊戲

若要準備好發行遊戲，請確定您已：

* 在 GameMaker Studio 2 中使用 **Package as Zip** 建立 MSIXVC 套件。
* 使用您在 Partner Center 中建立之專案的正確值，更新 MicrosoftGame.config 檔案。
* 將 GDK 擴充功能整合到您的遊戲中。

完成本文中的步驟之後，您就可以發行遊戲了。若要提交遊戲，請移至 [Partner Center](https://partner.microsoft.com/dashboard/windows/overview)，並依照 UI 中的指示操作。


## Related topics

- [搭配 Unity、Unreal 和其他引擎使用 GDK](/zh-TW/build/gdk-and-engines/gdk-and-engines.md)
- [Godot 與社群引擎總覽](/zh-TW/paths/community-engines/overview.md)
- [移植到 XBOX GDK 的指南](/zh-TW/home/build-first-title/porting-guides.md)
- [搭配 Godot 使用 GDK](/zh-TW/build/gdk-and-engines/godot.md)
- [開發新的 GDK 遊戲](/zh-TW/home/build-first-title/developing-new-titles.md)