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

# Versão v0.3.0 do XBOX Godot Sample

> Renomeação de tipos com alteração significativa, novos recursos, melhorias e correções na v0.3.0 do XBOX Godot Sample para criar jogos do Godot lançados para XBOX no PC.

***Data de lançamento: 19 de agosto de 2026***

O [exemplo XBOX Godot](https://aka.ms/XBOXGodotSample) é uma referência pública, somente de código-fonte, que mostra como criar uma extensão do Godot que integra o Microsoft GDK, os XBOX services e o PlayFab, para que você possa criar seu título para XBOX no PC. Este artigo resume as alterações da versão **v0.3.0 - Compatibility + Community Fixes**.

Para obter uma lista completa de commits, consulte o [changelog completo da v0.3.0](https://github.com/microsoft/XBOX-Godot-Sample/compare/v0.2.0...v0.3.0) no GitHub. Para obter a versão, consulte [v0.3.0 no GitHub](https://github.com/microsoft/XBOX-Godot-Sample/releases/tag/v0.3.0).

<Info>
  Esta versão contém uma alteração significativa. Todos os tipos visíveis em script no complemento `godot_gdk` foram renomeados, então `GDKUser` agora é `XboxUser` e `GDKResult` agora é `XboxResult`, e nenhum alias obsoleto é fornecido. Se você estiver atualizando um projeto existente, consulte [Alteração significativa: renomeação de tipos do complemento GDK](#breaking-change-gdk-addon-type-rename).
</Info>

## Principais destaques

* **Renomeação de tipos com alteração significativa para maior compatibilidade com mecanismos.** Os tipos visíveis em script foram renomeados, como `GDKUser` para `XboxUser`, para que o complemento possa ser incluído em forks do Godot que fornecem uma camada de plataforma de console XBOX Series X|S sem colidir com os tipos que esses forks já registram.
* **Voz e chat do PlayFab Party mais completos.** Indicadores de chat do Party, controles de voz, conversão de texto em fala e diagnósticos de rede foram adicionados à trilha do PlayFab.
* **Cobertura mais completa do XUser.** Os wrappers de API do XUser que faltavam foram implementados, o que possibilita o trabalho de conformidade com o XR-112.
* **Correções na exportação em C#.** Uma exportação "XBOX on PC" agora inclui os assemblies em C#, e o executável e o `.pck` são delegados ao próprio caminho de exportação para Windows do Godot.
* **Correções relatadas pela comunidade.** Foram resolvidos problemas relacionados a consultas de cota de salvamento de jogo, builds de versão que vinculavam o `godot-cpp` de depuração e o exemplo GDK Tutorial 3.

## Alteração significativa: renomeação de tipos do complemento GDK

Na v0.3.0, todos os tipos visíveis em script no complemento `godot_gdk` receberam um novo nome: `GDKUser` agora é `XboxUser`, `GDKResult` agora é `XboxResult` e assim por diante. **Nenhum alias obsoleto `GDK*` é fornecido**, portanto qualquer projeto que nomeie esses tipos diretamente precisa ser atualizado antes de ser carregado.

### O que mudou

* Os tipos do GDScript foram renomeados, por exemplo, `GDKUser` para `XboxUser`, `GDKResult` para `XboxResult` e `GDKAchievement` para `XboxAchievement`.
* A fachada em C# foi alterada junto com eles: o namespace `GodotGdk` passa a ser `GodotXbox`, e a classe estática de ponto de entrada `Gdk` foi renomeada de forma correspondente, conforme mostrado abaixo.
* O autoload de inicialização foi renomeado de `GDKBootstrap` para `XboxBootstrap`.
* As variáveis de ambiente do encaminhador de empacotamento MSIXVC foram renomeadas de `GDKPKG_*` para `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>();
```

### Por que mudou

O Godot registra as classes de extensão em um único namespace plano do `ClassDB`, portanto dois provedores que expõem o mesmo nome de tipo não podem coexistir em um projeto. Os forks do Godot que adicionam suporte ao console XBOX Series X|S fornecem sua própria camada de plataforma, exportações e tipos, e o prefixo `GDK` colidia com nomes que esses forks já usam. Renomear os tipos do complemento os mantém distintos para que ele possa ser incluído em um fork desse tipo.

O mesmo build do complemento é executado no PC e no console. Não há compilação, predefinição ou define condicional separados para console, e o `godot_gdk.gdextension` continua declarando apenas as bibliotecas `windows.*.x86_64`.

### O que não mudou

* O singleton do mecanismo ainda é registrado como `GDK`. Chamadas como `GDK.initialize()` e `GDK.users.add_default_user_async()` continuam funcionando sem alterações.
* A pasta `addons/godot_gdk`, o ponto de entrada `godot_gdk.gdextension` e as Configurações do Projeto `gdk/runtime/*` e `gdk/packaging/*`.
* Os tipos `PlayFab*` e `GameInput*`. A renomeação se limita ao complemento GDK.
* A tag de recurso de exportação `gdk`, a plataforma de exportação "XBOX on PC" e o nome do projeto e do assembly `GodotGdkCSharp`.

<Warning>
  O nome da classe no `ClassDB` e o nome do singleton agora são strings diferentes. O singleton ainda é registrado como `GDK`, mas a classe por trás dele não, portanto uma verificação como `is_class("GDK")` não corresponde mais. Em vez disso, compare com a classe renomeada:

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

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

### Como migrar

O exemplo inclui um codemod junto com o guia de migração. Faça commit do seu projeto primeiro, porque o codemod reescreve os arquivos no local.

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

O codemod propositalmente não reescreve um token `GDK` isolado, porque na maioria dos projetos esse token é o singleton, que não deve ser alterado. Ele relata as ocorrências ambíguas que encontra para que você possa revisá-las manualmente.

Para obter as tabelas completas de mapeamento de nomes antigos para novos para GDScript e C#, consulte [Migrating to v0.3.0](https://github.com/microsoft/XBOX-Godot-Sample/blob/main/docs/gdk/migration-v0.3.md) no repositório do exemplo.

## Alterações notáveis

### Novos recursos

* Indicadores de chat do Party, controles de voz, conversão de texto em fala e diagnósticos de rede no complemento `godot_playfab`.
* Os wrappers de API do XUser que faltavam, que possibilitam o trabalho de conformidade com o XR-112.
* Uma Configuração do Projeto que controla o nome do singleton do mecanismo.

### Melhorias

* Os tipos do complemento GDK visíveis em script foram renomeados, por exemplo, `GDKUser` para `XboxUser`, com um guia de migração e um codemod. Esta é uma alteração significativa.
* A capacidade de descoberta do README foi aprimorada com um início rápido, selos e revisão de texto, além de links para o blog e o Discord.
* A estrutura de títulos da documentação foi organizada e âncoras quebradas foram corrigidas.

### Correções

* Uma exportação "XBOX on PC" agora inclui os assemblies em C#.
* A exportação "XBOX on PC" delega o executável e o `.pck` ao caminho de exportação para Windows do Godot.
* A consulta de cota de salvamento de jogo agora é executada fora do thread principal.
* Os builds de versão não vinculam mais silenciosamente o `godot-cpp` de depuração.
* O upload para o Title Storage foi removido do exemplo GDK Tutorial 3.

### Engenharia e CI

* As verificações de PR são ignoradas em alterações somente de documentação.

## Tópicos relacionados

* [Introdução ao Godot](/pt-BR/build/gdk-and-engines/godot)
* [Versão v0.2.0 do XBOX Godot Sample](/pt-BR/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0)
* [Versões do exemplo XBOX Godot](https://github.com/microsoft/XBOX-Godot-Sample/releases)


## Related topics

- [XBOX Godot Sample v0.3.0 Release](/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)
- [XBOX Godot NetRumble Sample v0.1.0 Release](/build/gdk-and-engines/godot-release-notes/godot-netrumble-release-notes-0-1-0.md)
- [XBOX Godot Sample v0.1.0 Release](/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-1-0.md)