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

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.

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

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.

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

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

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

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.

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.

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.

<?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:

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.
Habilite o novo layout. Verifique se o seu projeto usa o novo layout definindo GDKCrossPlatform como true no arquivo de projeto.
Crie configurações ARM64. Copie suas configurações x64 existentes (como Debug e Release) para criar as configurações ARM64 correspondentes.
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.
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.
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.

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.

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.

  <PropertyGroup>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKCoreLatest)</GDKCrossPlatformPath>
    <GDKCrossPlatformPath Condition="'$(GDKCrossPlatformPath)'==''">$(GameDKXboxLatest)</GDKCrossPlatformPath>
  </PropertyGroup>

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

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

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

set_property(TARGET ${PROJECT_NAME} PROPERTY VS_GLOBAL_GDKCrossPlatform "true")

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

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.

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.

$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)

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

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

Layout antigo de cabeçalhos e bibliotecas

Novo layout de cabeçalhos e bibliotecas

Usar o novo layout com plataformas personalizadas do MSBuild

Usar um arquivo Directory.Build.props

Como atualizar um jogo x64 para adicionar ARM64

Usar o novo layout com a plataforma x64 do MSBuild

Usar o novo layout com o CMake

Usar o novo layout com sistemas de build personalizados

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

​Layout antigo de cabeçalhos e bibliotecas

​Novo layout de cabeçalhos e bibliotecas

​Usar o novo layout com plataformas personalizadas do MSBuild

​Usar um arquivo Directory.Build.props

​Como atualizar um jogo x64 para adicionar ARM64

​Usar o novo layout com a plataforma x64 do MSBuild

​Usar o novo layout com o CMake

​Usar o novo layout com sistemas de build personalizados

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

Layout antigo de cabeçalhos e bibliotecas

Novo layout de cabeçalhos e bibliotecas

Usar o novo layout com plataformas personalizadas do MSBuild

Usar um arquivo Directory.Build.props

Como atualizar um jogo x64 para adicionar ARM64

Usar o novo layout com a plataforma x64 do MSBuild

Usar o novo layout com o CMake

Usar o novo layout com sistemas de build personalizados

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