Estructura de directorios de encabezados y bibliotecas del GDK

En las versiones actuales de Microsoft Game Development Kit (GDK), el diseño se optimizó en torno al uso compartido de código y se centró en plataformas específicas. La integración de compilación para este diseño dependía en gran medida de ocultar la complejidad en las plataformas personalizadas de MSBuild. En el nuevo diseño, el objetivo es simplificar la integración, admitir una lista creciente de plataformas de destino y mejorar la compatibilidad tanto con las plataformas estándar de MSBuild como con sistemas de compilación que no son de Microsoft.

Diseño anterior de encabezados y bibliotecas

El diseño de archivos existente de Microsoft GDK se resume de la siguiente manera.

251000\
    GRDK\
        ExtensionLibraries\
            Xbox.Services.API.C\
                ExtensionLibrary.props
                DesignTime\CommonConfiguration\Neutral\
                    Include\
                    Lib\
                    Redist\
            ...
        GameKit\
            Include\
            Lib\
                amd64\

Las plataformas personalizadas de MSBuild Gaming.Desktop.x64 implementan la lógica para crear las rutas de inclusión y bibliotecas que combinan todo este contenido de diversas maneras. Si usaba CMake o una solución make personalizada, esta lógica también tenía que implementarse allí. Para ver un ejemplo detallado, consulte la versión de abril de 2025 de CMakeExample. El diseño anterior sigue presente en el GDK de octubre de 2025 para admitir tanto el estilo anterior como el nuevo. Ambos diseños, el nuevo y el anterior, se instalan de forma predeterminada. La instalación del GDK incluye ahora una opción para instalar solo el nuevo diseño. Un GDK futuro quitará el diseño anterior para reducir el espacio ocupado en el disco duro y el tamaño total de la descarga. La fecha objetivo actual para quitar el diseño anterior es un año después del lanzamiento del GDK de octubre de 2025.

Nuevo diseño de encabezados y bibliotecas

En la versión de octubre de 2025 del GDK, el nuevo diseño ofrece una alternativa para los encabezados y las bibliotecas que facilita la integración de plataformas y permite incorporar plataformas adicionales con el tiempo.

251000\
    windows\
        bin\
            arm64
            x64\
        include\
        lib\
            arm64
            x64\
        redist

Uso del nuevo diseño con plataformas personalizadas de MSBuild

Las plataformas de MSBuild Gaming.*.x64 existentes usan el diseño anterior de forma predeterminada, pero puede optar por el nuevo diseño estableciendo la propiedad GDKCrossPlatform.

<PropertyGroup Label="Globals">
...
  <GDKCrossPlatform>true</GDKCrossPlatform>
</PropertyGroup>

Esto agrega al proyecto las rutas de inclusión y bibliotecas adecuadas en lugar de las diversas rutas complejas que usaba el diseño anterior. En esta nueva integración simplificada, ya no se usa el mecanismo de bibliotecas de extensión. Todo el contenido está disponible en tiempo de compilación de forma predeterminada en las rutas de inclusión y bibliotecas. A continuación, el proyecto debe vincularse a las bibliotecas adicionales que usa. Los proyectos creados con las plantillas de proyecto de GDK anteriores deben contener instrucciones como la siguiente.

<AdditionalDependencies>uuid.lib;$(Console_Libs);%(XboxExtensionsDependencies);%(AdditionalDependencies)</AdditionalDependencies>

Para el nuevo diseño, la propiedad Console_Libs enumera las bibliotecas principales necesarias.

Plataforma	Bibliotecas principales
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib

El proyecto debe agregar a AdditionalDependencies las bibliotecas de extensión que consume, ya que cada una de ellas es de “participación voluntaria”.

Plataforma	Bibliotecas principales
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

El proyecto también debe copiar en el diseño los archivos DLL adicionales que usa. Puede hacerlo mediante pasos de compilación personalizada, habituales en muchas integraciones de bibliotecas DLL, o bien editando el archivo vcxproj o agregando un archivo props para usar la lista de grupos de elementos ReferenceCopyLocalPaths. El código de MSBuild siguiente enumera todos los archivos DLL posibles, pero cada proyecto solo necesitará algunos de ellos.

  <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 solo lo establece Microsoft GDK con XBOX Extensions. Por este motivo, introdujimos nuevas variables de entorno que admiten totalmente la instalación en paralelo de ambas versiones de Microsoft GDK: GameDKCoreLatest lo establece Microsoft GDK.

Uso de un archivo Directory.Build.props

Como forma de validar rápidamente proyectos Gaming.*.x64 de GDK existentes con el nuevo diseño, coloque el siguiente contenido en un archivo denominado Directory.Build.props en su árbol de código fuente. Esto habilita el nuevo diseño e incluye la mayoría o la totalidad de las bibliotecas de extensión, aunque el proyecto no las use.

Las reglas de MSBuild no usan la propiedad GDKExtLibNames al compilar con GDKCrossPlatform establecido en true. Como ya está presente para compilar con las reglas de MSBuild anteriores, se usa en este archivo props como forma de incluir algunos archivos DLL adicionales en el diseño.

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

Cómo actualizar un juego x64 para agregar ARM64

Para agregar compatibilidad con ARM64 a un proyecto de juego x64 existente, siga estos pasos:

Use Visual Studio 2022. La compatibilidad con ARM64 requiere Visual Studio 2022. Visual Studio 2019 no es compatible con compilaciones ARM64.
Habilite el nuevo diseño. Asegúrese de que el proyecto use el nuevo diseño estableciendo GDKCrossPlatform en true en el archivo de proyecto.
Cree configuraciones ARM64. Copie las configuraciones x64 existentes (como Debug y Release) para crear las configuraciones ARM64 correspondientes.
Actualice las rutas de bibliotecas. Edite los directorios de VC++ de las configuraciones ARM64 para que la ruta de bibliotecas haga referencia a lib\arm64 en lugar de a lib\x64.
Actualice las referencias de la biblioteca XSAPI. Actualice las instrucciones de vinculación de todas las configuraciones (no solo de ARM64) para usar Microsoft.Xbox.Services.143.GDK.C.lib en lugar de Microsoft.Xbox.Services.142.GDK.C.lib.
Actualice ReferenceCopyLocalPaths. Compruebe si en el archivo .vcxproj hay usos de ReferenceCopyLocalPaths que deban actualizarse para hacer referencia a la carpeta bin arm64 en lugar de a x64.

Si el inicio de su título produce el error 0xc000007b, significa que intentó cargar por accidente un archivo DLL de formato x64 en su proceso ARM64. Compruebe si en el sistema de proyectos hay elementos ReferenceCopyLocalPaths que deban actualizarse.

Uso del nuevo diseño con la plataforma x64 de MSBuild

En lugar de usar la plataforma Gaming.Desktop.x64, puede usar la plataforma estándar x64 para compilar para PC. En el diseño anterior, esto requería agregar instrucciones <Import Project="...\ExtensionLibrary.props"> para las bibliotecas de extensión, como se detalla en Uso de la plataforma x64 con Microsoft Game Development Kit (GDK). En el nuevo diseño, las instrucciones de integración se simplifican.

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

Agregue todas las bibliotecas de extensión necesarias a AdditionalDependencies junto con la lista original.

<AdditionalDependencies>xgameruntime.lib;gameinput.lib;d3d12.lib;dxgi.lib;dxguid.lib;uuid.lib;kernel32.lib;user32.lib;%(AdditionalDependencies)</AdditionalDependencies>

Los archivos DLL de bibliotecas de extensión de participación voluntaria deben copiarse en el directorio de binarios como se indicó anteriormente, mediante una acción de compilación personalizada o mediante el grupo de elementos ReferenceCopyLocalPaths para el diseño final. Las instrucciones restantes para PreprocessorDefinitions y para controlar el archivo .mgc con recursos de imagen no cambian.

Uso del nuevo diseño con CMake

Cuando use los generadores de Microsoft Visual Studio con CMake y las plataformas personalizadas de MSBuild Gaming.*.x64, habilite el nuevo diseño con el código siguiente.

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

En CMakeGDKExample, quite el uso de VS_GLOBAL_GDKExtLibNames y reemplácelo por el código siguiente (suponiendo CMake 3.21 o posterior) para copiar en el diseño los archivos DLL de extensión utilizados.

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
    )

Uso del nuevo diseño con sistemas de compilación personalizados

Para compilar para Windows x64 con el GDK se requiere lo siguiente.

set INCLUDE=%GameDKCoreLatest%windows\include;%INCLUDE%
set LIB=%GameDKCoreLatest%windows\lib\x64;%LIB%
set PATH=%GameDK%bin;%GameDKCoreLatest%windows\bin\x64;%PATH%

Lectura de la edición de compilación desde un archivo instalado

El nuevo diseño no contiene el archivo grdk.ini. Para encontrar la información de la edición analizando un archivo, use grdk.h. Este es un ejemplo en PowerShell que también funciona con versiones anteriores del 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

Estructura de directorios de encabezados y bibliotecas del GDK

Diseño anterior de encabezados y bibliotecas

Nuevo diseño de encabezados y bibliotecas

Uso del nuevo diseño con plataformas personalizadas de MSBuild

Uso de un archivo Directory.Build.props

Cómo actualizar un juego x64 para agregar ARM64

Uso del nuevo diseño con la plataforma x64 de MSBuild

Uso del nuevo diseño con CMake

Uso del nuevo diseño con sistemas de compilación personalizados

Lectura de la edición de compilación desde un archivo instalado

​Diseño anterior de encabezados y bibliotecas

​Nuevo diseño de encabezados y bibliotecas

​Uso del nuevo diseño con plataformas personalizadas de MSBuild

​Uso de un archivo Directory.Build.props

​Cómo actualizar un juego x64 para agregar ARM64

​Uso del nuevo diseño con la plataforma x64 de MSBuild

​Uso del nuevo diseño con CMake

​Uso del nuevo diseño con sistemas de compilación personalizados

​Lectura de la edición de compilación desde un archivo instalado

Diseño anterior de encabezados y bibliotecas

Nuevo diseño de encabezados y bibliotecas

Uso del nuevo diseño con plataformas personalizadas de MSBuild

Uso de un archivo Directory.Build.props

Cómo actualizar un juego x64 para agregar ARM64

Uso del nuevo diseño con la plataforma x64 de MSBuild

Uso del nuevo diseño con CMake

Uso del nuevo diseño con sistemas de compilación personalizados

Lectura de la edición de compilación desde un archivo instalado