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

> PC의 XBOX로 출시되는 Godot 게임을 빌드하기 위한 XBOX Godot 샘플 v0.3.0의 호환성이 깨지는 타입 이름 변경, 새로운 기능, 개선 사항 및 수정 사항입니다.

***릴리스 날짜: 2026년 8월 19일***

[XBOX Godot 샘플](https://aka.ms/XBOXGodotSample)은 Microsoft GDK, XBOX 서비스, PlayFab을 통합하는 Godot 확장을 어떻게 만드는지를 보여주는 공개된 소스 전용 레퍼런스로, 이를 통해 PC용 XBOX 타이틀을 빌드할 수 있습니다. 이 문서는 **v0.3.0 - Compatibility + Community Fixes** 릴리스의 변경 사항을 요약합니다.

전체 커밋 목록은 GitHub의 [v0.3.0 전체 changelog](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`이며, 더 이상 사용되지 않는(deprecated) 별칭은 제공되지 않습니다. 기존 프로젝트를 업그레이드하는 경우 [Breaking change: GDK addon type rename](#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 샘플과 관련된 이슈가 해결되었습니다.

## Breaking change: GDK addon type rename

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/*` Project Settings.
* `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>

### 마이그레이션 방법

샘플에는 마이그레이션 가이드와 함께 코드모드가 포함되어 있습니다. 코드모드가 파일을 그 자리에서 재작성하므로, 먼저 프로젝트를 커밋하세요.

```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
```

코드모드는 의도적으로 단독으로 사용된 `GDK` 토큰은 재작성하지 않습니다. 대부분의 프로젝트에서 그 토큰은 싱글톤이며, 변경되어서는 안 되기 때문입니다. 코드모드는 발견한 모호한 발생 위치를 보고하므로 수동으로 검토할 수 있습니다.

GDScript 및 C#의 전체 이전-이후 매핑 표는 샘플 리포지토리의 [Migrating to 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 적합성 작업을 지원합니다.
* 엔진 싱글톤 이름을 제어하는 Project Setting.

### 개선 사항

* 스크립트 노출 GDK 애드온 타입 이름 변경(예: `GDKUser`에서 `XboxUser`)과 함께 마이그레이션 가이드 및 코드모드 제공. 이는 호환성이 깨지는 변경입니다.
* 빠른 시작, 배지, 문구 정리와 함께 블로그 및 Discord 링크를 추가하여 README 발견 가능성을 개선했습니다.
* 문서 헤딩 구조를 정리하고 깨진 앵커를 수정했습니다.

### 수정 사항

* "XBOX on PC" 익스포트가 이제 C# 어셈블리를 함께 제공합니다.
* "XBOX on PC" 익스포트는 실행 파일과 `.pck`를 Godot의 Windows 익스포트 경로로 위임합니다.
* 게임 저장 할당량 쿼리가 이제 메인 스레드 밖에서 실행됩니다.
* 릴리스 빌드가 더 이상 디버그 `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 사용](/ko/build/gdk-and-engines/godot.md)
- [XBOX Godot Sample v0.1.0 릴리스](/ko/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-1-0.md)
- [XBOX Godot Sample v0.2.0 릴리스](/ko/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0.md)
- [IGameInputDevice::ReleaseExclusiveRawDeviceAccess](/ko/reference/input/gameinput/deprecated/interfaces/igameinputdevice/methods/igameinputdevice_releaseexclusiverawdeviceaccess.md)
- [Unity, Unreal 및 기타 엔진과 함께 GDK 사용](/ko/build/gdk-and-engines/gdk-and-engines.md)