> ## 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 服务](#test-xbox-services-in-your-game)
* [发布](#publish-your-game)

## 安装所需软件

要在 GameMaker Studio 2 中使用 Microsoft Game Development Kit(GDK),请下载以下软件:

* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
* [June 2024 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 概览](/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 服务与功能集成到 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 服务的产品,参见 [Setting up an app or game in Partner Center, for Managed Partners](https://learn.microsoft.com/gaming/gdk/_content/gc/services/fundamentals/portal-config/live-setup-partner-center-partners)。创建产品后,你既可以测试 XBOX 服务,也可以将游戏发布到 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 服务。

构建完成后,会打开一个文件资源管理器窗口,显示生成的 .zip 文件及其子目录。子目录与包同名,并包含 MSIXVC 文件。

此外,GameMaker Studio 2 的输出窗口会显示一行代码,给出 MSIXVC 包的完整输出路径,如下例所示。

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

为了让示例项目能够访问 XBOX 服务,请使用 `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 服务功能,请按以下步骤使用 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 overview](https://learn.microsoft.com/gaming/gdk/_content/gc/features/common/game-config/MicrosoftGameConfig-Overview)。

## 将 GDK 扩展集成到你的项目

至少,你的项目需要调用以下函数才能与 GDK 集成。

* 调用 `gdk_init` 初始化 GDK。在使用任何其他 GDK 功能之前,必须调用 `gdk_init`。
* 在 GDK 处于激活状态期间,每帧调用一次 `gdk_update`。
* 项目结束、不再需要 GDK 功能时,调用 `gdk_quit` 清理 GDK。

此外,GDK 扩展提供以下模块来访问 GDK 功能。

* **Base Module:** 提供一组用于控制玩家的用户/账户选择的函数。
* **Storage Module:** 提供一组用于加载和保存与用户关联数据的函数。
* **XBOX services Module:** 提供使用 XBOX 服务功能的函数,包括统计、排行榜、成就与富存在。
* **In-App Purchases Module:** 提供通过 GDK 将 GameMaker 项目与 Microsoft Store 商务系统集成的函数。

GDKExtension 仓库中包含的指南在 GDK Extension APIs 部分提供了 GDK 函数的文档。该指南是位于 source/GDKExtension\_gml/datafiles/GDK\_Extension\_Documentation.pdf 的 .pdf 文件。

## 在游戏中测试 XBOX 服务

要在游戏中测试 XBOX 服务功能(例如成就),请使用一个沙箱以及具有该沙箱访问权限的测试账户。

### 创建测试账户

要在游戏中测试任何 XBOX 服务功能,请创建具有开发沙箱访问权限的测试账户。有关操作说明,参见 [Creating test accounts](https://learn.microsoft.com/gaming/gdk/_content/gc/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 Sandboxes overview](https://learn.microsoft.com/gaming/gdk/_content/gc/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-CN/build/gdk-and-engines/gdk-and-engines.md)
- [在 Godot 中使用 GDK](/zh-CN/build/gdk-and-engines/godot.md)
- [在 Unity 中使用 GDK](/zh-CN/build/gdk-and-engines/unity/unity.md)
- [在 Unreal Engine 中使用 GDK](/zh-CN/build/gdk-and-engines/unreal/unreal.md)
- [在 GDK 中使用 Clang/LLVM](/zh-CN/tools/tools-pc/visualstudio/gr-vs-clang.md)