Estructura de directorios simplificada del GDK (encabezados y bibliotecas)

Se espera que el nuevo diseño del Microsoft Game Development Kit (GDK) para encabezados y bibliotecas que se describe en este artículo se publique en el GDK de octubre de 2025. Póngase en contacto con su administrador de cuentas de Microsoft si le interesan las compilaciones preliminares de este GDK.

En las versiones actuales del Microsoft Game Development Kit (GDK), el diseño estaba optimizado en torno al uso compartido de código y centrado en plataformas específicas. La integración de compilación para este diseño dependía en gran medida de ocultar la complejidad en 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 del 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 include/lib que combinan todo este contenido de diversas formas. Si usaba CMake o una solución de 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 antiguo como el nuevo. Tanto el diseño nuevo como el anterior se instalan de forma predeterminada. El programa de instalación del GDK ahora incluye una opción para instalar solo el nuevo diseño. Un GDK futuro eliminará 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 eliminar el diseño anterior será un año después del momento en que se publique el GDK de octubre de 2025.

Nuevo diseño de encabezados y bibliotecas

Para la versión del GDK de octubre de 2025, el nuevo diseño ofrece un diseño alternativo para los encabezados y las bibliotecas que facilita la integración de plataformas y permite dar cabida a 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 include/lib 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 include/lib. A continuación, el proyecto debe vincularse a las bibliotecas adicionales que use. Los proyectos basados en las plantillas de proyecto del GDK más antiguas deberían contener instrucciones como la siguiente.

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

En el nuevo diseño, la propiedad Console_Libs enumera las bibliotecas básicas necesarias.

Plataforma	Bibliotecas básicas
Gaming.*.x64	xgameruntime.lib d3d12.lib dxguid.lib dxgi.lib gameinput.lib

El proyecto debe agregar a AdditionalDependencies las bibliotecas de extensión que consuma, porque cada una de ellas es de participación voluntaria (“opt-in”).

Plataforma	Bibliotecas básicas
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 las DLL adicionales que use. Puede hacerlo mediante pasos de compilación personalizados (Custom Build), habituales en muchas integraciones de bibliotecas DLL, o editando el archivo vcxproj o agregando un archivo props para usar la lista del grupo de elementos ReferenceCopyLocalPaths. El código de MSBuild siguiente enumera todas las DLL posibles, pero cada proyecto individual solo necesitará algunas de ellas.

  <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 el Microsoft GDK con XBOX Extensions. Por ello, hemos introducido nuevas variables de entorno que admiten totalmente la instalación en paralelo de ambas versiones del Microsoft GDK: GameDKCoreLatest lo establece el Microsoft GDK.

Uso de un archivo Directory.Build.props

Como forma de validar rápidamente proyectos Gaming.*.x64 del GDK existentes mediante el nuevo diseño, coloque el contenido siguiente en un archivo llamado Directory.Build.props en su árbol de código fuente. Esto activa el nuevo diseño e incluye la mayoría de las bibliotecas de extensión, o todas, 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 más antiguas, en este archivo props se usa como una forma de habilitar algunas 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 las compilaciones ARM64.
Habilite el nuevo diseño. Asegúrese de que su proyecto use el nuevo diseño estableciendo GDKCrossPlatform en true en el archivo del proyecto.
Cree configuraciones ARM64. Copie sus configuraciones x64 existentes (como Debug y Release) para crear las configuraciones ARM64 correspondientes.
Actualice las rutas de bibliotecas. Edite los directorios de VC++ de sus configuraciones ARM64 para que la ruta de bibliotecas haga referencia a lib\arm64 en lugar de a lib\x64.
Actualice las referencias a la biblioteca XSAPI. Actualice las instrucciones de vinculación de todas las configuraciones (no solo ARM64) para usar Microsoft.Xbox.Services.143.GDK.C.lib en lugar de Microsoft.Xbox.Services.142.GDK.C.lib.
Actualice ReferenceCopyLocalPaths. Compruebe el uso de ReferenceCopyLocalPaths en su archivo .vcxproj que podría necesitar actualizarse para hacer referencia a la carpeta bin arm64 en lugar de a x64.

Si el inicio de su título falla con el error 0xc000007b, significa que ha intentado cargar accidentalmente una DLL con formato x64 en su proceso ARM64. Compruebe si en su sistema de proyecto hay elementos ReferenceCopyLocalPaths que podrían necesitar 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, tal como se detalla en Uso de la plataforma x64 con el Microsoft Game Development Kit (GDK). En el nuevo diseño, las instrucciones de integración se han simplificado.

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

Las 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 (Custom Build) o mediante el grupo de elementos ReferenceCopyLocalPaths para el diseño final. Las instrucciones restantes para PreprocessorDefinitions y para administrar el archivo .mgc con los recursos de imagen permanecen sin cambios.

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 las DLL de extensión utilizadas.

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

Compilar para Windows x64 mediante el GDK 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 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 simplificada del GDK (encabezados y bibliotecas)

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