> ## 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 範例 v0.3.0 版本

> XBOX Godot 範例 v0.3.0 中的重大型別重新命名、新功能、改進和修正，用於建置發行至 PC 版 XBOX 的 Godot 遊戲。

***發行日期：2026 年 8 月 19 日***

[XBOX Godot 範例](https://aka.ms/XBOXGodotSample)是一個公開、僅限原始碼的參考，示範如何建置整合 Microsoft GDK、XBOX services 和 PlayFab 的 Godot 擴充功能，讓您可以為 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 附加元件型別重新命名](#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 匯出路徑處理。
* **社群回報的修正。** 解決了遊戲存檔配額查詢、發行組建連結偵錯版 `godot-cpp`，以及 GDK Tutorial 3 範例的相關問題。

## 重大變更：GDK 附加元件型別重新命名

在 v0.3.0 中，`godot_gdk` 附加元件中每個指令碼可見的型別都獲得了新名稱：`GDKUser` 現在是 `XboxUser`，`GDKResult` 現在是 `XboxResult`，依此類推。**不提供已淘汰的 `GDK*` 別名**，因此任何直接指名這些型別的專案都必須先更新才能載入。

### 變更內容

* GDScript 型別已重新命名，例如 `GDKUser` 改為 `XboxUser`、`GDKResult` 改為 `XboxResult`，以及 `GDKAchievement` 改為 `XboxAchievement`。
* C# 外觀也隨之變更：命名空間 `GodotGdk` 變為 `GodotXbox`，靜態進入點類別 `Gdk` 也相應重新命名，如下所示。
* 啟動程序自動載入已從 `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 匯出路徑。
* 遊戲存檔配額查詢現在會在主執行緒以外執行。
* 發行組建不再以無訊息方式連結偵錯版 `godot-cpp`。
* 從 GDK Tutorial 3 範例中移除 Title Storage 上傳。

### 工程和 CI

* 僅限文件的變更會略過 PR 閘道。

## 相關主題

* [開始使用 Godot](/zh-TW/build/gdk-and-engines/godot)
* [XBOX Godot 範例 v0.2.0 版本](/zh-TW/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0)
* [XBOX Godot 範例版本](https://github.com/microsoft/XBOX-Godot-Sample/releases)


## Related topics

- [XBOX Godot Sample v0.3.0 Release](/zh-CN/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-3-0.md)
- [Versión v0.3.0 de XBOX Godot Sample](/es/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-3-0.md)
- [XBOX Godot Sample v0.3.0 リリース](/ja-jp/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-3-0.md)
- [在 Godot 中使用 GDK](/zh-CN/build/gdk-and-engines/godot.md)
- [XBOX Godot NetRumble Sample v0.1.0 Release](/build/gdk-and-engines/godot-release-notes/godot-netrumble-release-notes-0-1-0.md)