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

# Estrutura de diretórios simplificada do GDK (cabeçalhos e bibliotecas)

> Adote o layout de diretórios simplificado do GDK de outubro de 2025 com GDKCrossPlatform para MSBuild, CMake e builds personalizados, e adicione ARM64 ao seu título x64.

Nas versões atuais do Microsoft Game Development Kit (GDK), o layout foi otimizado em torno do compartilhamento de código e focado em plataformas específicas. A integração de build para esse layout dependia muito de ocultar a complexidade em plataformas personalizadas do MSBuild. No novo layout, o foco está em simplificar a integração, oferecer suporte a uma lista crescente de plataformas de destino e melhorar o suporte tanto às plataformas padrão do MSBuild quanto a sistemas de build que não são da Microsoft.

## Layout antigo de cabeçalhos e bibliotecas

O layout de arquivos existente do Microsoft GDK é resumido a seguir.

```text theme={null}
251000\
    GRDK\
        ExtensionLibraries\
            Xbox.Services.API.C\
                ExtensionLibrary.props
                DesignTime\CommonConfiguration\Neutral\
                    Include\
                    Lib\
                    Redist\
            ...
        GameKit\
            Include\
            Lib\
                amd64\
```

As plataformas personalizadas do MSBuild **Gaming.Desktop.x64** implementam a lógica para criar os caminhos de include/lib que combinam todo esse conteúdo de várias maneiras. Se você usava o CMake ou uma solução make personalizada, essa lógica também precisava ser implementada nela. Para ver um exemplo detalhado, consulte a versão de abril de 2025 do [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample).

O layout antigo ainda está presente no GDK de outubro de 2025 para oferecer suporte aos estilos antigo e novo. Ambos os layouts, novo e antigo, são instalados por padrão. A instalação do GDK agora inclui uma opção para instalar apenas o novo layout. Um GDK futuro removerá o layout antigo para reduzir o espaço ocupado no disco rígido e o tamanho geral do download. A data prevista atual para a remoção do layout antigo é de um ano a partir do lançamento do GDK de outubro de 2025.

## Novo layout de cabeçalhos e bibliotecas

Na versão de outubro de 2025 do GDK, o novo layout oferece uma alternativa de organização para os cabeçalhos e bibliotecas que facilita a integração com a plataforma e permite acomodar plataformas adicionais ao longo do tempo.

```text theme={null}
251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist
```

## Usar o novo layout com plataformas personalizadas do MSBuild

As plataformas **Gaming.\*.x64** existentes do MSBuild usam o layout antigo por padrão, mas você pode optar pelo novo layout definindo a propriedade **GDKCrossPlatform**.

```xml theme={null}
<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>
```

Isso adiciona os caminhos de include/lib apropriados ao projeto, em vez dos vários caminhos complexos usados pelo layout antigo.

Nessa nova integração simplificada, o mecanismo de bibliotecas de extensão não é mais usado. Todo o conteúdo fica disponível no momento do build, por padrão, nos caminhos de include/lib.

O projeto então precisa vincular as bibliotecas adicionais que usa. Projetos criados com base nos modelos de projeto mais antigos do GDK devem conter instruções como as seguintes.

```xml theme={null}
<AdditionalDependencies>uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)</AdditionalDependencies>
```

No novo layout, a propriedade **Console\_Libs** lista as bibliotecas principais necessárias.

| Plataforma | Bibliotecas principais |
| - | - |
| Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib |

O projeto precisa adicionar a **AdditionalDependencies** as bibliotecas de extensão que consome, porque cada uma delas é opcional ("opt-in").

| Plataforma | Bibliotecas principais |
| - | - |
| Xbox.LibHttpClient | libHttpClient.lib |
| Xbox.XCurl.API | XCurl.lib |
| Xbox.Game.Chat.2.Cpp.API | GameChat2.lib |
| Xbox.Services.API.C (Debug) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.Debug.lib |
| Xbox.Services.API.C (Release) | Appnotify.lib winhttp.lib crypt32.lib Microsoft.Xbox.Services.142.C.lib |
| PlayFab.Party.Cpp | Party.lib |
| PlayFab.PartyXboxLive.Cpp | PartyXboxLive.lib |
| PlayFab.Services.C | PlayFabCore.lib PlayFabGameSave.lib PlayFabServices.lib |
| PlayFab.Multiplayer.Cpp | PlayFabMultiplayer.lib |

O projeto também precisa copiar para o layout as DLLs adicionais que usa. Você pode fazer isso por meio de etapas de Build Personalizado, típicas de muitas integrações de bibliotecas DLL, ou editando o vcxproj ou adicionando um arquivo props para usar a lista de grupo de itens **ReferenceCopyLocalPaths**. O MSBuild abaixo lista todas as DLLs possíveis, mas cada projeto precisará apenas de algumas delas.

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>
```

<Note>
  `GameDKLatest` é definida apenas pelo Microsoft GDK com XBOX Extensions. Por isso, introduzimos novas variáveis de ambiente que oferecem suporte completo à instalação lado a lado das duas versões do Microsoft GDK: `GameDKCoreLatest` é definida pelo Microsoft GDK.
</Note>

### Usar um arquivo Directory.Build.props

Como forma de validar rapidamente projetos Gaming.\*.x64 existentes do GDK usando o novo layout, coloque o conteúdo a seguir em um arquivo chamado Directory.Build.props na sua árvore de código-fonte. Isso ativa o novo layout e inclui a maioria ou todas as bibliotecas de extensão, mesmo que não sejam usadas pelo projeto.

<Note>
  A propriedade **GDKExtLibNames** não é usada pelas regras do MSBuild ao compilar com **GDKCrossPlatform** definida como true. Como ela já está presente para compilação com as regras mais antigas do MSBuild, é usada nesse arquivo props como forma de incluir algumas DLLs adicionais no layout.
</Note>

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <PropertyGroup>
    <GDKCrossPlatform>true</GDKCrossPlatform>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
    <AllExtensionLibs>Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.lib</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'=='Debug'">Microsoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)</AllExtensionLibs>
    <AllExtensionLibs Condition="'$(Configuration)'!='Debug'">Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)</AllExtensionLibs>
  </PropertyGroup>

  <ItemDefinitionGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <Link>
      <AdditionalDependencies>$(AllExtensionLibs);%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>

  <!--
    Makes sure we deploy all the libs we need. We use the 'old layout' GDKExtLibNames property as a way to test
    what is requested to try to reduce the over-inclusion of unused DLLs.
  -->

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64'">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\libHttpClient.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\XCurl.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('Xbox.Game.Chat.2.Cpp.API'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\GameChat2.dll" />
  </ItemGroup>

  <ItemGroup Condition="'$(Platform)'=='Gaming.Desktop.x64' AND $(GDKExtLibNames.Contains('PlayFab'))">
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\Party.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PartyXboxLive.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabCore.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabGameSave.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabMultiplayer.dll" />
    <ReferenceCopyLocalPaths Include="$(GDKCrossPlatformPath)windows\bin\x64\PlayFabServices.dll" />
  </ItemGroup>

</Project>
```

## Como atualizar um jogo x64 para adicionar ARM64

Para adicionar suporte a ARM64 a um projeto de jogo x64 existente, siga estas etapas:

1. **Use o Visual Studio 2022.** O suporte a ARM64 requer o Visual Studio 2022. O Visual Studio 2019 não tem suporte para builds ARM64.
2. **Habilite o novo layout.** Verifique se o seu projeto usa o novo layout definindo `GDKCrossPlatform` como `true` no arquivo de projeto.
3. **Crie configurações ARM64.** Copie suas configurações x64 existentes (como Debug e Release) para criar as configurações ARM64 correspondentes.
4. **Atualize os caminhos de biblioteca.** Edite os Diretórios VC++ das suas configurações ARM64 para que o caminho de biblioteca faça referência a `lib\arm64` em vez de `lib\x64`.
5. **Atualize as referências da biblioteca XSAPI.** Atualize as instruções de vinculação de *todas* as configurações (não apenas ARM64) para usar `Microsoft.Xbox.Services.143.GDK.C.lib` em vez de `Microsoft.Xbox.Services.142.GDK.C.lib`.
6. **Atualize ReferenceCopyLocalPaths.** Verifique se há usos de `ReferenceCopyLocalPaths` no seu arquivo `.vcxproj` que precisem ser atualizados para referenciar a pasta bin `arm64` em vez de `x64`.

<Note>
  Se a inicialização do seu título falhar com o erro 0xc000007b, significa que você tentou acidentalmente carregar uma DLL no formato x64 no seu processo ARM64. Verifique no seu sistema de projeto se há itens `ReferenceCopyLocalPaths` que precisem ser atualizados.
</Note>

## Usar o novo layout com a plataforma x64 do MSBuild

Em vez de usar a plataforma **Gaming.Desktop.x64**, você pode usar a plataforma padrão **x64** para compilar para PC. No layout antigo, isso exigia adicionar instruções `<Import Project="...\ExtensionLibrary.props">` para as Bibliotecas de Extensão, conforme detalhado em Usar a plataforma x64 com o Microsoft Game Development Kit (GDK).

No novo layout, as instruções de integração são simplificadas.

```xml theme={null}
  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>
```

```xml theme={null}
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>
```

```xml theme={null}
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
  <ExecutablePath>$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)</ExecutablePath>
  <IncludePath>$(GDKCrossPlatformPath)windows\Include;$(IncludePath);</IncludePath>
  <LibraryPath>$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)</LibraryPath>
</PropertyGroup>
```

Adicione todas as bibliotecas de extensão necessárias a **AdditionalDependencies** junto com a lista original.

```xml theme={null}
<AdditionalDependencies>xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)</AdditionalDependencies>
```

As DLLs das bibliotecas de extensão opcionais precisam ser copiadas para o diretório de binários, como mostrado acima, usando uma ação de Build Personalizado ou o grupo de itens **ReferenceCopyLocalPaths** para o layout final.

As demais instruções para **PreprocessorDefinitions** e para o tratamento do arquivo .mgc com ativos de imagem permanecem inalteradas.

## Usar o novo layout com o CMake

Ao usar os geradores do Microsoft Visual Studio com o CMake e as plataformas personalizadas do MSBuild **Gaming.\*.x64**, habilite o novo layout usando o código a seguir.

```text theme={null}
set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")
```

No [CMakeGDKExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeGDKExample), remova o uso de `VS_GLOBAL_GDKExtLibNames` e substitua-o pelo código a seguir (considerando o CMake 3.21 ou posterior) para copiar as DLLs de extensão usadas para o layout.

```text theme={null}
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E $<IF:$<BOOL:$<TARGET_RUNTIME_DLLS:${PROJECT_NAME}>>,copy,true>
    $<TARGET_RUNTIME_DLLS:${PROJECT_NAME}> $<TARGET_FILE_DIR:${PROJECT_NAME}>
    COMMAND_EXPAND_LISTS
    )
```

## Usar o novo layout com sistemas de build personalizados

Compilar para Windows x64 usando o GDK requer o seguinte.

```cmd theme={null}
set INCLUDE=%GameDKCoreLatest%windows\include;%INCLUDE%
set LIB=%GameDKCoreLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKCoreLatest%windows\bin\x64;%PATH%
```

## Ler a edição do build a partir de um arquivo instalado

O novo layout não contém o arquivo `grdk.ini`. Para encontrar as informações da edição analisando um arquivo, use `grdk.h`.

Veja a seguir um exemplo em PowerShell que também funciona com versões mais antigas do GDK.

```powershell theme={null}
$result = Get-ChildItem -Path $env:GameDKCoreLatest -Filter "grdk.h" -Recurse
if ($result.Count -eq 0)
{
    $result = Get-ChildItem -Path $env:GRDKLatest -Filter "grdk.h" -Recurse
}
if ($result.Count -eq 0)
{
    Write-Error "##[error]Failed to find grdk.h in either GameDKCoreLatest or GRDKLatest" -ErrorAction Stop
}

$content = Get-Content -Path $result[0].FullName

if (-not ([string]$content -match '#define\s+_GRDK_EDITION\s+([0-9][0-9][0-9][0-9][0-9][0-9])')) {
    Write-Error "##[error]Failed to find edition define" -ErrorAction Stop
}

$xbld_edition = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDKVER_PRODUCTBUILDVER_FULL\s+([0-9]+\.[0-9]+\.([0-9]+)\.[0-9]+)')) {
    Write-Error "##[error]Failed to find full version define" -ErrorAction Stop
}

$xbld_full_productbuild = $Matches[1]
$xbld_build = $Matches[2]

if (-not ([string]$content -match '#define\s+_GRDK_MM_NUM\s+([0-9]{1,2})')) {
    Write-Error "##[error]Failed to find month define" -ErrorAction Stop
}

$month = $Matches[1]

if (-not ([string]$content -match '#define\s+_GRDK_FULLYY\s+([0-9]{4})')) {
    Write-Error "##[error]Failed to find full year define" -ErrorAction Stop
}

$year = $Matches[1]

Write-Output ("_xbld_name={0} {1} GRDK" -f (Get-Culture).DateTimeFormat.GetMonthName([int]$month), $year)
Write-Output ("_xbld_edition={0}" -f $xbld_edition)
Write-Output ("_xbld_full_productbuild={0}" -f $xbld_full_productbuild)
Write-Output ("_xbld_build={0}" -f $xbld_build)
```


## Related topics

- [Estrutura XTFCONSOLEDATA](/pt-BR/reference/tools/xtf/xtfconsolemanager/structures/xtfconsoledata-xtfconsolemanager-xbox-microsoft-t.md)
- [Migrar do SDK autônomo v1 do PlayFab para o SDK unificado v2](/pt-BR/services/playfab/sdks/unified-sdk/migrating-from-v1.md)
- [Estrutura XTF_OUTPUT_DEBUG_STRING_DATA](/pt-BR/reference/tools/xtf/xtfdebugmonitor/structures/XTF_OUTPUT_DEBUG_STRING_DATA-xtfdebugmonitor-xbox-microsoft-t.md)
- [Implementação do Game Saves com o GDK de outubro de 2025](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Estrutura GAMEPAD_REPORT](/pt-BR/reference/tools/xtf/xtfinput/structures/GAMEPAD_REPORT-xtfinput-xbox-windows-t.md)