通过

Unity入门

概述

本文档介绍如何在将 GDK 组件集成到项目中时开始使用 Unity。 这将涵盖不同类型的Unity包、如何设置它们以及每个包中包含哪些功能。

Unity的最新Microsoft GDK 包由 Microsoft 和 Unity 共同开发，提供以相同的配置和代码库面向 Windows x64、Xbox Series X|S 和 Xbox One 主机设备的功能。

先决条件

若要将 Microsoft GDK 包用于Unity，需要满足以下先决条件：

有关包要求的详细信息，请参阅Unity的要求和安装文档。

Microsoft适用于Unity的 GDK 包

有多个 GDK 包在与项目和编辑器集成时提供不同的功能。 所有包都由 Unity分发，有关详细信息，请参阅其下载门户。

若要访问 Microsoft GDK Xbox 主机程序包，您必须是 Xbox 开发人员计划的成员（包括ID@Xbox），并且通过联系您的Microsoft代表请求访问Unity的 Xbox 论坛。 开始电脑开发所需的包公开提供，可 在此处找到。

包的完整列表为：

  • 适用于Unity (电脑 & 控制台) Microsoft GDK API 包
  • 适用于Unity (电脑 & 控制台) 的 Microsoft GDK 工具包
  • Microsoft适用于 Xbox 的 GDK 工具包（仅限Unity (主机) ）
  • 仅限 Unity (控制台的 GXDK 输入系统包)
  • 仅限Unity (主机的游戏核心呈现管道包)

适用于 Unity 的 Microsoft GDK API 包为跨电脑、Xbox Series X|S和 Xbox One 设备使用的本机 API 提供了必要的 C# 包装器，包括访问成就、云保存和排行榜等 Xbox 网络服务。

适用于 Unity 的 Microsoft GDK 工具包为Unity内的开发工作流提供了必要的集成，以创建Microsoft游戏配置文件，并将电脑游戏打包到 GDK，以便提交到 Microsoft 应用商店。

适用于Unity的 Microsoft GDK Tools for Xbox 包扩展了 GDK 工具包，并集成了适用于 Xbox Series X|S 和 Xbox One 设备的开发人员工作流，包括打包主机 GDK 游戏以提交到 Microsoft 应用商店。

Unity的 GXDK 输入系统包在面向Xbox Series X|S或 Xbox One 设备时，为Unity输入系统提供特定于主机的功能。

适用于 Unity 的游戏核心呈现管道包提供特定于主机的功能，以使用Unity的可脚本化呈现管道 (SRP) ，例如通用呈现管道 (URP) 或Xbox Series X|S或 Xbox One 设备上的高清晰度呈现管道 (HDRP) 。

适用于主机的Unity 编辑器加载项

若要访问生成配置文件 & 项目设置，以便能够在 Unity 内的 Xbox Series X|S 和 Xbox One 设备上配置、生成、部署和启动，需要安装 Unity 提供的编辑器加载项，以扩展编辑器以包括此功能。

这些加载项作为 .exe 安装程序提供，为每个编辑器提供附加功能。 因此，必须使用 编辑器在每台计算机上安装它们才能解锁这些功能。 成功安装加载项后，Unity中心的“安装”选项卡中关联的Unity 编辑器版本将将它们列为支持的功能。 使用该版本编辑器的任何项目现在可以启用 Xbox Series X|S 和 Xbox One GDK 项目设置和生成配置文件。

下面是安装了两个加载项的 Unity 6 版编辑器的示例：

Unity安装了两个加载项的 6 版编辑器

包、加载项、GDK 和引擎兼容性

Unity的 Microsoft GDK API & 工具包是通过Unity 编辑器包管理器中的 Unity 注册表获取的。 如果编辑器版本为 2021.3.47f1、2022.3.55f1、6000.0.31f1 或更高版本，则呈现的版本将与正在运行的 编辑器兼容。 有关 GDK & 引擎版本与用于Unity的 Microsoft GDK API 包的每个版本兼容性的详细信息，请参阅此处。 这些包支持通过 GitHub 获取的 GDK 和通过 Xbox 开发人员下载门户获取的 GDK。

Microsoft GDK Tools for Xbox for Unity 包是通过从Unity的 Xbox 论坛直接下载链接获取的。 此包与Unity 编辑器版本 2021.3.45f1、2022.3.49f1、6000.0.22f1 或更高版本兼容。 有关此程序包的要求的详细信息，请参阅此Unity Xbox 论坛文章。 此包仅支持通过 Xbox 开发人员下载门户获取的 GDK。 此包要求安装Unity 编辑器的Xbox Series X|S和 Xbox One 加载项才能在编辑器中公开。

Unity的 GXDK 输入系统包是通过从Unity的 Xbox 论坛直接下载链接获取的。 有关此程序包的要求的详细信息，请参阅此Unity Xbox 论坛文章。 此包仅支持通过 Xbox 开发人员下载门户获取的 GDK。 此包要求安装Unity 编辑器的Xbox Series X|S和 Xbox One 加载项才能在编辑器中公开。

Unity的游戏核心呈现管道包是通过从Unity的 Xbox 论坛直接下载链接获取的。 有关此程序包的要求的详细信息，请参阅此Unity Xbox 论坛文章。 此包仅支持通过 Xbox 开发人员下载门户获取的 GDK。 此包要求安装Unity 编辑器的Xbox Series X|S和 Xbox One 加载项才能在编辑器中公开。

Xbox Series X|S和用于Unity 编辑器的 Xbox One 加载项是通过Unity Xbox 论坛的直接下载链接获取的。 有关这些编辑器加载项的要求的详细信息，请参阅此Unity Xbox 论坛文章。 这些加载项仅支持通过 Xbox 开发人员下载门户获取的 GDK。

将包集成到项目中

若要开始使用适用于Unity的 Microsoft GDK API & 工具包，请执行以下步骤：

  1. 导航到“窗口”菜单并选择“包管理器”。
  2. 打开后，从右侧列中选择“Unity注册表”选项。
  3. 在搜索框中，键入 gdk 并等待列表刷新。
  4. 选择“Microsoft GDK API”包，然后单击“ 安装”。
  5. 完成后，选择“Microsoft GDK 工具”包，然后单击“ 安装”。
  6. 成功安装两个包后，关闭包管理器。

下面是在 Unity 6 中搜索Unity注册表中的包的概述：

概述在 Unity 6 的 Unity 注册表中搜索包

对于特定于 Xbox 主机的程序包，你将通过Unity Xbox 论坛下载门户获取它们。 这些包将通过以下方式在本地添加到项目中：

  1. 导航到“窗口”菜单，然后选择“包管理器”。
  2. 打开后，选择“+”，然后选择“从 tarball 添加包...”
  3. 导航到下载的 .tgz 扩展包。
  4. 选择它，然后将其安装到项目中。

下图显示了 Unity 6 中项目中本地安装的包：

包本地安装在 Unity 6 中的项目中

Unity的包与Unity项目相关联。 如果创建新的Unity项目，则需要重新获取这些包并将其再次安装到该Unity项目。 打开安装了这些包的 Unity 项目的用户无需从注册表重新下载它们即可访问此功能。

注意

Xbox Series X|S和 Xbox One 加载项需要按编辑器安装来解锁在这些设备上配置、生成、部署和启动的功能。

将项目配置为可识别 GDK

本部分将介绍要识别 GDK 的项目的初始集成。

创建 GDK 设置资产

在项目中安装用于Unity的 Microsoft GDK API & Tools 包后，你将有其他菜单选项。 其中之一是特定于 GDK 的资产集，它允许生成 GDK 设置资产。 这会向项目设置添加特定于 GDK 的设置，以便直接在Unity内配置 GDK 产品。 有关在 Unity 中管理 GDK 设置的详细信息，请参阅此处。

下面是在 Unity 6 中创建的 GDK 设置资产的示例：

在 Unity 6 中创建的 GDK 设置资产

如果安装了适用于 Xbox 的 GDK 工具包和 Xbox 加载项，则 GDK 设置将为每个平台和平台特定的设置和配置文件创建多个选项卡。 项目可能包含多个 GDK 设置资产，其中一次只能有一个资产处于活动状态。

下面是在 Unity 6 中为 Xbox Series X|S 和 Xbox One 创建的 GDK 设置示例：

正在为 Unity 6 中的 Xbox Series X|S 和 Xbox One 创建 GDK 设置

创建Microsoft游戏配置资产

创建 GDK 设置资产后，可以向项目添加Microsoft游戏配置资产。 这将生成必要的文件来配置项目以使用 GDK 特定特性和功能。 有关在 Unity 中管理Microsoft游戏配置文件的详细信息，请参阅此处。

下面是在 Unity 6 中创建Microsoft游戏配置资产的示例：

Microsoft Unity 6 中创建的游戏配置资产

将Microsoft游戏配置与 GDK 资产相关联

创建Microsoft游戏配置后，需要打开 GDK 项目设置并将Microsoft游戏配置与该项目相关联。 这将确保它在生成和打包步骤中用于该平台。

下面是在 Unity 6 中关联Microsoft Game Config 的示例：

关联 Unity 6 中的Microsoft游戏配置

编辑Microsoft游戏配置资产

作为 GDK 工具包集成的一部分，Microsoft游戏配置资产具有特定的编辑器集成，可帮助你轻松修改和配置正确的 GDK 配置值。 在资产列表中选择“Microsoft游戏配置资产”时，可以在“检查器”窗格中找到这一点。 有关在 Unity 中管理Microsoft游戏配置文件的详细信息，请参阅此处。

下面是在 Unity 6 中编辑Microsoft游戏配置的示例：

在 Unity 6 中编辑Microsoft游戏配置

将 GDK 游戏与合作伙伴中心产品相关联

作为 GDK 工具包集成的一部分，Microsoft游戏配置编辑器使你能够使用内置向导轻松地将 GDK 游戏与合作伙伴中心产品相关联。 这要求你登录到Microsoft帐户，该帐户有权查看要与之关联的合作伙伴中心产品。 成功与合作伙伴中心关联后，向导将列出哪些值已自动从合作伙伴中心映射到你的项目游戏配置资产。 有关在合作伙伴中心创建产品和访问 Xbox 服务功能的详细信息，请参阅 此处。

注意

有关每个用户正确与应用商店关联的必要权限的详细信息，请参阅 此处。

下面是在 Unity 6 中启动应用商店关联向导的示例：

在 Unity 6 内启动存储关联向导

注意

必须从合作伙伴中心的“包/标识/发布者”行获取发布者信息，并将其应用到Microsoft Game Config 编辑器中的“发布者”字段，才能正确使用应用商店关联向导。

将 C# 包装器用于访问 API

作为用于Unity的 Microsoft GDK API 包的一部分，提供了本机 GDK API 的一组 C# 包装器，用于直接访问Unity项目中的这些 API。 若要详细了解如何访问 GDK API，请参阅 此处。

下面是“包”窗口中用于Unity的 Microsoft GDK API 包中的 C# 包装器示例：

Microsoft GDK API 包中的 C# 包装器，用于在“包”窗口中Unity

利用 Visual Studio 和 Unity

Visual Studio 提供游戏工作负载，作为Visual Studio 安装程序的一部分，用于与Unity直接集成。 若要了解有关 Visual Studio Tools for Unity 扩展的详细信息，请参阅此处。

利用示例

目前有两组Unity示例，可以在生成项目时获取并用于引用代码。

Unity注册表示例

第一组示例附带用于Unity的 Microsoft GDK API 包，下载后，可以在Unity注册表Microsoft GDK API 条目的“示例”选项卡中找到，如下所示：

下载后，Unity注册表中“Microsoft GDK API”条目中的“示例”选项卡

这些示例演示了与成就、云保存、游戏保存、In-Game 应用商店行为、排行榜、登录、语音合成器和用户行为等系统的基本交互。 有关这些示例的详细信息，请参阅 此处。

注意

这些示例依赖于Unity的输入系统包。 请参阅此处有关Unity的输入系统以及如何安装包的详细信息。

Unity GDK 示例

除了通过 Unity 注册表提供的示例外，GDK 下载本身还提供了一组示例。 这些示例旨在提供更高级 API 用法的演示。 包括的示例包括：

  • UnityAchievements - 演示如何使用 XblAchievement API 查询和更新成就进度。
  • UnityInGameStore - 一个完整的游戏内商店体验，可配置为作为任何游戏运行，并演示大多数 XStore API 来查询目录产品、用户权利和许可证产品。
  • UnityLeaderboardsTitleManaged - 演示如何使用游戏管理的排行榜来更新和查询用户统计信息，以及查询社交排行榜和全局排行榜。
  • UnitySimpleMPSD - 使用多人游戏会话目录 (MPSD) 和SmartMatch API 进行会话管理和匹配的基本多人游戏会话示例。
  • UnityRumble - 一款简单的多人游戏，它使用多人游戏管理器 (MPM) 和 PlayFab Party 创建/加入/matchmake/离开多人游戏会话、更新会话状态、共享游戏玩法数据以及通过聊天进行通信。
  • UnityRumblePlayFabMultiplayer - 如上所示，但使用 PlayFab 多人游戏进行会话管理和匹配，而不是多人游戏管理器。
  • UnitySimpleHttpCall - 演示如何使用 Xbox Live Http 调用以字符串或字节数组的形式发送和接收消息。
  • UnitySimpleWebSockets - 演示如何使用 Http 客户端 Web 套接字向预配置的 Web 套接字终结点发送和接收二进制或字符串消息。
  • UnitySimplePLM - 一个基本示例，演示如何检测和响应生存期管理事件， (主机上的约束/挂起/恢复、在电脑上丢失/发现焦点) 。
  • UnitAssetWorkflow (仅 Xbox) - 演示如何使用 Xbox 主机资源和工具 API 来促进游戏资产的快速迭代。

可以从 Xbox 开发人员下载网站获取这些示例。 下面是下载门户中 GDK 文件类型下的生成列表中的示例名称示例。

下载门户中 GDK 文件类型下生成列表中的示例名称

生成 & 打包项目

本部分将介绍在 Unity 中生成和打包项目。

本地化和打包设置

作为 Windows 平台的 GDK 设置的一部分，可以指定是否要生成 shell 视觉对象、本地化资产，以及是否在 Unity 中的生成步骤中创建包。 不需要为 Windows 打包配置特定的“生成配置文件”设置。 有关打包设置的详细信息，请参阅 此处。

下面是在 Unity 6 中设置这些 GDK 设置值的示例：

设置 Unity 6 中的 GDK 设置值

对于主机，如果项目中包含 Microsoft GDK Tools for Xbox 包，则可以将“Shell 视觉对象模式”设置为“仅复制”，这将确保在打包前将应用商店映像复制到生成文件夹。 这样就无需手动复制映像。

若要为主机设置包加密方法，请转到“项目设置”“ > 播放器 > 发布者设置”。 Xbox 目标将包含“包加密”设置。 在使用“生成和部署”或“xbapp install”) 时，生成希望能够旁加载本地测试 (的包时，请使用“开发”。 对要上传到合作伙伴中心然后从应用商店安装的包使用“提交”。

Unity的控制台包生成是在“生成配置文件”页上配置的。 根据要为) 生成的平台，将目标平台更改为 Xbox One 或 Xbox Series (。 对于可旁加载的本地包，请将“生成类型”设置为“开发播放器”。 对于要上传到合作伙伴中心的包，请将“生成类型”设置为“主玩家”。 将 Deploy 方法更改为“Package”。

对于使用“开发”加密生成的控制台旁加载包，可以使用“生成并运行”选项部署到控制台。 这将创建松散的文件夹生成，使用测试签名运行 makepkg.exe，并在默认开发工具包上安装/启动包。

使用“提交”加密生成的包不能旁加载。 必须将其上传到合作伙伴中心，然后通过 Microsoft 应用商店进行安装。

生成配置文件

每个目标平台都有生成配置文件。 如果在 Windows GDK 设置文件中指定了包，则 Windows 平台将在生成完成后使用 GDK 设置文件并在 MSIXVC 文件夹中生成 MSIXVC 包。 有关生成配置文件的详细信息，请参阅 此处。

对于控制台，部署设置（包括打包）在特定于平台的生成设置以及其他生成、部署和调试选项中指定。 生成完成后，输出目录将在 XVC 文件夹中包含 XVC 包。

下面是在 Unity 6 中查看每个平台生成配置文件的示例：

查看 Unity 6 中的每个平台生成配置文件

在播放模式下测试项目

还有其他步骤和注意事项可确保基于 GDK 的项目在播放模式下正常工作。 有关正确使用播放模式所需步骤的详细信息，请参阅 此处。

其他信息

获取帮助

若要获取有关任何问题的帮助，请参阅 Xbox 论坛Unity。 如果你不是 Xbox 开发人员计划的一部分，并且使用的是用于 Windows 开发的公共包，请使用 Unity Windows 论坛。

如果你正在寻找与特定于 GDK 且不特定于Unity集成的主题相关的帮助，请在 Xbox GDK 论坛上发布这些内容。

已知问题

有关与适用于 Unity 的 GDK API 包相关的已知问题列表，请参阅此处。

有关与用于Unity的 GDK 工具包相关的已知问题列表，请参阅此处。

使用较旧版本的 Unity

Microsoft GDK AP & 工具包支持 Unity 2021.3 和更新版本的编辑器。 强烈建议使用受支持的Unity 编辑器版本来获取集成工具支持和功能，以跨所有平台正确生成和运行游戏。

如果使用较旧版本的 Unity，则可以引用 GDK API 包中提供的 C# 包装器，以使用 GDK 本机 API 提供自己的特定于项目的接口。 此外，你可以使用编辑器工具为游戏创建 MicrosoftGame.config、本地化和 shell 视觉对象和包。

这些过程是手动的，不提供直接编辑器集成。 如果无法升级Unity 编辑器版本，并且需要有关选项的更多指导，请联系Microsoft代表。

已弃用的包

Microsoft在 GitHub 上分发的 GDK Unity 包 (电脑仅 ) 现已弃用，并已删除，转而支持用于Unity的 Microsoft GDK API & 工具包。 如果你对 GDK Unity套餐 (电脑) 有任何疑问，请联系你的Microsoft代表。 如果你使用的是以前的 GDK Unity包 (电脑) ，并且正在寻找有关如何迁移的步骤，请参阅此处的升级指南。

有关现已弃用的Unity提供的包的详细信息，请参阅Unity Xbox 论坛文章。