> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Estrutura de diretórios de cabeçalhos e bibliotecas do GDKX
> Descreve o novo layout de diretórios para cabeçalhos e bibliotecas do GDKX.
> [!NOTE]
>
> A estrutura de diretórios descrita neste artigo é o **layout simplificado (multiplataforma)** introduzido com o GDK de outubro de 2025.
>
> A partir do GDK de outubro de 2026, o layout simplificado é instalado por padrão. O layout herdado continua disponível como um caminho de compatibilidade opcional e preterido para equipes que precisam de tempo adicional de migração.
>
> O layout herdado deixará de ter suporte e será removido do instalador a partir da versão do GDK de abril de 2027.
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 compilação 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, dar suporte a uma lista crescente de plataformas de destino e aprimorar o suporte tanto para as plataformas padrão do MSBuild quanto para sistemas de compilação 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\
```
```text theme={null}
GXDK\
gameKit\
Include\
XboxOne\
Scarlett\
Lib\
amd64\
XboxOne\
Scarlett\
ToolKit\
Include\
XboxOne\
Scarlett\
Lib\
amd64\
XboxOne\
Scarlett\
```
As plataformas personalizadas do MSBuild **Gaming.Desktop.x64**, **Gaming.Xbox.Scarlett.x64** e **Gaming.Xbox.XboxOne.x64** implementam toda 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 lá. Para ver um exemplo detalhado, confira a versão de abril de 2025 do [CMakeExample](https://github.com/microsoft/Xbox-GDK-Samples/tree/apr2025/Samples/Tools/CMakeExample).
As versões do GDK de outubro de 2025 e abril de 2026 incluem tanto o layout simplificado quanto o herdado. A partir do GDK de outubro de 2026, a instalação instala apenas o layout simplificado por padrão. O layout herdado ainda pode ser selecionado como uma instalação opcional, mas ele está preterido e não é mais o caminho de desenvolvimento recomendado.
O layout herdado deixará de ter suporte e será removido do instalador a partir da versão do GDK de abril de 2027.
## Novo layout de cabeçalhos e bibliotecas
A versão do GDK de outubro de 2025 agora oferece um layout alternativo para os cabeçalhos e bibliotecas que torna a integração com a plataforma muito mais fácil e capaz de acomodar plataformas adicionais ao longo do tempo.
```text theme={null}
251000\
windows\
bin\
arm64
x64\
include\
lib\
arm64
x64\
redist
xbox\
bin\
gen8\
gen9\
devpctools\
gen8\
gen9\
x64\
x64\
build\
include\
lib\
redist\
source\
```
## Usando o novo layout com plataformas personalizadas do MSBuild
As plataformas existentes **Gaming.\*.x64** do MSBuild usarão o layout antigo por padrão, mas você pode optar pelo novo layout definindo a propriedade **GDKCrossPlatform**.
```xml theme={null}
...
true
```
Isso faz com que os caminhos de include/lib apropriados sejam adicionados 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 está disponível por padrão no momento da compilação nos caminhos de include/lib.
Em seguida, o projeto precisa vincular as bibliotecas adicionais que usa. Projetos criados com base nos modelos de projeto mais antigos do GDK devem conter instruções como a seguinte.
```xml theme={null}
uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)
```
No novo layout, a propriedade **Console\_Libs** listará as principais bibliotecas necessárias.
| Plataforma | Bibliotecas principais |
| - | - |
| Gaming.\*.x64 | xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib |
| Gaming.Xbox.Scarlett.x64 | xgameruntime.lib xgameplatform.lib d3d12\_xs.lib xg\_xs.lib pixevt.lib xmem.lib |
| Gaming.Xbox.XboxOne.x64 | xgameruntime.lib xgameplatform.lib d3d12\_x.lib xg\_x.lib pixevt.lib xmem.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. Isso pode ser feito por meio de etapas de Custom Build, 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}
$(GameDKCoreLatest)$(GameDKXboxLatest)
```
> [!NOTE]
>
> `GameDKLatest` é definida apenas pelo Microsoft GDK with 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. `GameDKXboxLatest` é definida pelo Microsoft GDK with XBOX Extensions.
### Usando um 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 habilita 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 compilar com as regras mais antigas do MSBuild, ela é usada neste arquivo props como forma de habilitar algumas DLLs adicionais no layout.
```xml theme={null}
true$(GameDKCoreLatest)$(GameDKXboxLatest)Appnotify.lib;winhttp.lib;crypt32.lib;libHttpClient.lib;XCurl.lib;GameChat2.lib;PlayFabCore.lib;PlayFabServices.lib;PlayFabMultiplayer.lib;Party.lib;PartyXboxLive.lib;PlayFabGameSave.libMicrosoft.Xbox.Services.142.C.Debug.lib;$(AllExtensionLibs)Microsoft.Xbox.Services.142.C.lib;$(AllExtensionLibs)$(AllExtensionLibs);%(AdditionalDependencies)$(AllExtensionLibs);%(XboxExtensionsDependencies)
```
## Usando 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 `` para as bibliotecas de extensão, conforme detalhado em [Usando a plataforma x64 com o Microsoft Game Development Kit (GDK)](https://docs.xbox.com/pt-BR/tools/tools-pc/visualstudio/gr-vs-templates.md#using-the-x64-platform-with-the-microsoft-game-development-kit-gdk).
No novo layout, as instruções de integração são simplificadas.
```xml theme={null}
$(GameDKCoreLatest)$(GameDKXboxLatest)
```
```xml theme={null}
$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)$(GDKCrossPlatformPath)windows\Include;$(IncludePath);$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)
```
```xml theme={null}
$(GameDK)bin;$(GDKCrossPlatformPath)windows\bin\x64;$(ExecutablePath)$(GDKCrossPlatformPath)windows\Include;$(IncludePath);$(GDKCrossPlatformPath)windows\lib\x64;$(LibraryPath)
```
Adicione todas as bibliotecas de extensão necessárias a **AdditionalDependencies** junto com a lista original.
```xml theme={null}
xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)
```
As DLLs das bibliotecas de extensão habilitadas precisam ser copiadas para o diretório binário, como acima, usando uma ação de Custom Build 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.
## Usando 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**, o novo layout é habilitado com o seguinte.
```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 seguinte (supondo 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 $>,copy,true>
$ $
COMMAND_EXPAND_LISTS
)
```
## Usando o novo layout com sistemas de compilação personalizados
Compilar para Windows x64 usando o GDK requer o seguinte.
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%windows\include;%INCLUDE%
set LIB=%GameDKXboxLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%windows\bin\x64;%PATH%
```
Compilar para XBOX Series X|S (também conhecido como *Gaming.Xbox.Scarlett.x64*) requer:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\gen9;%GameDKXboxLatest%xbox\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\gen9;%GameDKXboxLatest%xbox\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen9;%GameDKXboxLatest%xbox\bin\x64;%PATH%
```
Compilar para XBOX One (também conhecido como *Gaming.Xbox.XboxOne.x64*) requer:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\gen8;%GameDKXboxLatest%xbox\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\gen8;%GameDKXboxLatest%xbox\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKXboxLatest%xbox\bin\gen8;%GameDKXboxLatest%xbox\bin\x64;%PATH%
```
## Usando o novo layout para ferramentas de conteúdo de PC
No desenvolvimento para console, alguns tipos de processamento ("cooking") de conteúdo ocorrem no PC de desenvolvimento usando APIs do XTF, a biblioteca de codificação XMA2 e/ou ferramentas personalizadas do Direct3D 12.X. Acessar esse conteúdo requer uma configuração de compilação específica:
Compilar ferramentas de PC voltadas tanto para XBOX One quanto para XBOX Series X|S requer:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDK%bin;%PATH%
```
Compilar ferramentas de PC voltadas para os gráficos do XBOX Series X|S requer:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen9;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen9;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen9;%GameDK%bin;%PATH%
```
Compilar ferramentas de PC voltadas para os gráficos do XBOX One requer:
```cmd theme={null}
set INCLUDE=%GameDKXboxLatest%xbox\include\devpctools\gen8;%GameDKXboxLatest%xbox\include\devpctools;%GameDK%\toolKit\include;%INCLUDE%
set LIB=%GameDKXboxLatest%xbox\lib\devpctools\gen8;%GameDKXboxLatest%xbox\lib\devpctools\x64;%GameDK%\toolKit\lib\amd64;%LIB%
set PATH=%GameDKXboxLatest%xbox\devpctools\bin\gen8;%GameDK%bin;%PATH%
```
## Lendo a edição da compilação de um arquivo instalado
O novo layout não contém os arquivos `grdk.ini` ou `gxdk.ini`. Para encontrar as informações da edição analisando um arquivo, use `grdk.h` ou `gxdk.h`.
Veja um exemplo em PowerShell que também funciona com versões mais antigas do GDK.
```powershell theme={null}
$result = Get-ChildItem -Path $env:GameDKXboxLatest -Filter "gxdk.h" -Recurse
if ($result.Count -eq 0)
{
$result = Get-ChildItem -Path $env:GXDKLatest -Filter "gxdk.h" -Recurse
}
if ($result.Count -eq 0)
{
Write-Error "##[error]Failed to find gxdk.h in either GameDKXboxLatest or GXDKLatest" -ErrorAction Stop
}
$content = Get-Content -Path $result[0].FullName
if (-not ([string]$content -match '#define\s+_GXDK_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+_GXDKVER_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+_GXDK_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+_GXDK_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} GXDK" -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)
```
## Compilar sem instalar (BWOI)
Os arquivos de plataforma de compilação personalizada do MSBuild que ficavam originalmente em `\flatDeployment` no layout antigo agora ficam em `\xbox\build`, com caminhos mais curtos.
Por exemplo, para configurar uma pasta de regras do MSBuild para BWOI no VS 2022, use estes comandos.
```cmd theme={null}
rd /q /s c:\temp\msbuildgdk
md c:\temp\msbuildgdk
xcopy "%VSInstallDir%\MSBuild\Microsoft\VC" /s c:\temp\msbuildgdk
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen8" c:\temp\msbuildgdk /s
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\gen9" c:\temp\msbuildgdk /s
xcopy "%GameDKXboxLatest%\xbox\build\VS2022\pc" c:\temp\msbuildgdk /s
```
Em seguida, no Directory.Build.props usado para BWOI, defina as propriedades para apontar para essa pasta combinada.
```xml theme={null}
c:\temp\msbuildgdk\v170\c:\temp\msbuildgdk\v160\
```
## Related topics
- [Estrutura de diretórios de cabeçalhos e bibliotecas do GDK](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [Novidades do Microsoft Game Development Kit (GDK)](https://docs.xbox.com/pt-BR/announcements/gdk/whats-new.md)
- [Implementação do Game Saves com o GDK de outubro de 2025](https://docs.xbox.com/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Compile e execute seu primeiro título de console com o GDKX](https://docs.xbox.com/pt-BR/home/build-first-title/first-console-title-walkthrough.md)
- [Pacotes de estrutura: instalação automática de dependências para redistribuíveis de software comuns](https://docs.xbox.com/pt-BR/build/core-features/common/packaging/packaging-framework-packages.md)