> ## 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.

# XBOX Godot Sample v0.3.0 Release

> XBOX Godot Sample v0.3.0 中面向 PC 上的 XBOX 发布 Godot 游戏的破坏性类型重命名、新功能、改进和修复。

***发布日期:2026 年 8 月 19 日***

[XBOX Godot 示例](https://aka.ms/XBOXGodotSample) 是 GitHub 上一个公开的、仅提供源代码的参考,展示了如何构建一个 Godot 扩展,将 Microsoft GDK、XBOX 服务与 PlayFab 集成起来,让你能为 PC 上的 XBOX 构建作品。本文总结了 **v0.3.0 - Compatibility + Community Fixes** 版本中的变更。

有关完整的提交列表,参见 GitHub 上的 [v0.3.0 完整变更日志](https://github.com/microsoft/XBOX-Godot-Sample/compare/v0.2.0...v0.3.0)。要获取该版本,参见 [GitHub 上的 v0.3.0](https://github.com/microsoft/XBOX-Godot-Sample/releases/tag/v0.3.0)。

<Info>
  本版本包含一项重大变更。`godot_gdk` 附加组件中每个脚本可见类型均已重命名,因此 `GDKUser` 现为 `XboxUser`,`GDKResult` 现为 `XboxResult`,且未提供已弃用的别名。如果你在升级现有项目,参见 [重大变更:GDK addon 类型重命名](#breaking-change-gdk-addon-type-rename)。
</Info>

## 关键亮点

* **为更广的引擎兼容性所做的重大类型重命名。** 脚本可见类型被重命名,例如 `GDKUser` 变为 `XboxUser`,使该附加组件能够被引入到那些提供 XBOX Series X|S 主机平台层的 Godot 分支中,且不会与这些分支已注册的类型发生冲突。
* **更丰富的 PlayFab Party 语音与聊天。** 在 PlayFab 分支中新增了 Party 聊天指示器、语音控制、文本转语音以及网络诊断。
* **更完整的 XUser 覆盖。** 实现了缺失的 XUser API 封装,为 XR-112 合规工作提供了支持。
* **C# 导出修复。** "XBOX on PC" 导出现在会包含 C# 程序集,并将可执行文件与 `.pck` 委托给 Godot 自身的 Windows 导出路径。
* **社区反馈的修复。** 解决了与游戏存档配额查询、Release 构建链接到调试版 `godot-cpp` 以及 GDK Tutorial 3 示例相关的问题。

## 重大变更:GDK addon 类型重命名

在 v0.3.0 中,`godot_gdk` 附加组件中每个脚本可见类型都被赋予了新的名称:`GDKUser` 现为 `XboxUser`,`GDKResult` 现为 `XboxResult`,以此类推。**未提供已弃用的 `GDK*` 别名**,因此任何直接引用这些类型名称的项目都必须先更新才能加载。

### 变更内容

* GDScript 类型被重命名,例如 `GDKUser` 改为 `XboxUser`,`GDKResult` 改为 `XboxResult`,`GDKAchievement` 改为 `XboxAchievement`。
* C# 门面也随之调整:命名空间 `GodotGdk` 变为 `GodotXbox`,静态入口点类 `Gdk` 也做了相应重命名,如下所示。
* Bootstrap 自动加载从 `GDKBootstrap` 重命名为 `XboxBootstrap`。
* MSIXVC 打包转发器的环境变量从 `GDKPKG_*` 重命名为 `XBOXPKG_*`。

```gdscript theme={null}
# Before
var result: GDKResult = GDK.initialize()
var user: GDKUser = result.data

# After
var result: XboxResult = GDK.initialize()
var user: XboxUser = result.data
```

```csharp theme={null}
// Before
using GodotGdk;
GdkResult init = Gdk.Initialize();
GdkUser user = res.DataAs<GdkUser>();

// After
using GodotXbox;
XboxResult init = Xbox.Initialize();
XboxUser user = res.DataAs<XboxUser>();
```

### 变更原因

Godot 在单一扁平的 `ClassDB` 命名空间中注册扩展类,因此暴露相同类型名称的两个提供者无法在同一项目中共存。添加 XBOX Series X|S 主机支持的 Godot 分支会提供自己的平台层、导出与类型,而 `GDK` 前缀与这些分支已使用的名称相冲突。将附加组件的类型重命名后,它们保持独立,便可被引入到此类分支中。

同一份附加组件构建产物既可在 PC 上运行,也可在主机上运行。没有单独的主机编译、预设或条件定义,`godot_gdk.gdextension` 仍只声明 `windows.*.x86_64` 库。

### 未变更的内容

* 引擎单例仍以 `GDK` 名称注册。诸如 `GDK.initialize()` 和 `GDK.users.add_default_user_async()` 等调用无需修改即可继续工作。
* `addons/godot_gdk` 文件夹、`godot_gdk.gdextension` 入口点,以及 `gdk/runtime/*` 与 `gdk/packaging/*` 项目设置。
* `PlayFab*` 与 `GameInput*` 类型。重命名的范围仅限于 GDK 附加组件。
* `gdk` 导出功能标签、"XBOX on PC" 导出平台,以及 `GodotGdkCSharp` 项目与程序集名称。

<Warning>
  `ClassDB` 类名和单例名现在是两个不同的字符串。单例仍以 `GDK` 注册,但其背后的类却不是,因此像 `is_class("GDK")` 这样的检查不再匹配。请改为对照重命名后的类进行比较:

  ```gdscript theme={null}
  # Before
  if GDK.get_class() == "GDK":

  # After
  if GDK.get_class() == "Xbox":
  ```
</Warning>

### 如何迁移

示例随附了一个 codemod 以及迁移指南。请先提交你的项目,因为 codemod 会就地重写文件。

```powershell theme={null}
.\tools\migrate_gdk_to_xbox.ps1 -Path C:\path\to\your\godot\project -WhatIf
.\tools\migrate_gdk_to_xbox.ps1 -Path C:\path\to\your\godot\project
```

codemod 有意不重写单独的 `GDK` 标记,因为在大多数项目中该标记指的是不可更改的单例。它会报告发现的歧义位置,供你手动审查。

有关 GDScript 与 C# 的完整新旧名称映射表,参见示例仓库中的 [迁移到 v0.3.0](https://github.com/microsoft/XBOX-Godot-Sample/blob/main/docs/gdk/migration-v0.3.md)。

## 值得注意的变更

### 新功能

* 在 `godot_playfab` 附加组件中新增了 Party 聊天指示器、语音控制、文本转语音与网络诊断。
* 缺失的 XUser API 封装,可支持 XR-112 合规工作。
* 用于控制引擎单例名称的项目设置。

### 改进

* 重命名了 GDK 附加组件中脚本可见的类型,例如 `GDKUser` 改为 `XboxUser`,并提供迁移指南与 codemod。这是一项重大变更。
* 通过快速入门、徽章以及文案清理,并加上博客与 Discord 链接,改进了 README 的可发现性。
* 整理了文档标题结构并修复了失效的锚点。

### 修复

* "XBOX on PC" 导出现在会包含 C# 程序集。
* "XBOX on PC" 导出将可执行文件与 `.pck` 委托给 Godot 的 Windows 导出路径。
* 游戏存档配额查询现在在主线程之外运行。
* Release 构建不再静默链接到调试版 `godot-cpp`。
* 从 GDK Tutorial 3 示例中移除了 Title Storage 上传。

### 工程与 CI

* 对仅涉及文档的变更跳过 PR 门禁。

## 相关主题

* [Godot 入门](/build/gdk-and-engines/godot)
* [XBOX Godot Sample v0.2.0 Release](/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0)
* [XBOX Godot sample releases](https://github.com/microsoft/XBOX-Godot-Sample/releases)


## Related topics

- [在 Godot 中使用 GDK](/zh-CN/build/gdk-and-engines/godot.md)
- [XBOX Godot 示例 v0.2.0 发布](/zh-CN/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0.md)
- [XBOX Godot 示例 v0.1.0 发布](/zh-CN/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-1-0.md)
- [在 Unity、Unreal 及其他引擎中使用 GDK](/zh-CN/build/gdk-and-engines/gdk-and-engines.md)
- [IGameInputDevice::ReleaseExclusiveRawDeviceAccess](/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinputdevice/methods/igameinputdevice_releaseexclusiverawdeviceaccess.md)