Integración del GDK con un motor personalizado de C/C++

Use este tema si está preparando su juego para publicarlo en Microsoft Store en PC y su juego usa un motor basado en C/C++ que no tiene compatibilidad integrada con el GDK.

Creación de un producto en Partner Center
Integración del GDK en juegos de C/C++
Pruebas de los servicios de XBOX en su juego
Publicación

Creación de un producto en Partner Center

Antes de poder publicar un juego en Microsoft Store, debe crear su producto habilitado para los servicios de XBOX en Partner Center. Para obtener más información sobre Partner Center, consulte Configuración de una aplicación o un juego en Partner Center, para asociados administrados.

Integración del GDK en juegos de C/C++

Para integrar el GDK en un juego de C/C++, el juego necesita 4 cosas:

Los encabezados del GDK y de XBOX Services API (XSAPI) que describen las firmas de la API y las estructuras de datos.
Las bibliotecas de importación que indican al enlazador cómo resolver las referencias externas a las funciones exportadas del GDK.
Las bibliotecas estáticas de XSAPI o las bibliotecas de importación que indican al enlazador cómo resolver las referencias externas a las funciones exportadas de la DLL de XSAPI.
- XSAPI está disponible tanto en forma estática como dinámica. Consulte la tabla siguiente para obtener más información y elija entre estática o dinámica.
Las bibliotecas de vínculos dinámicos que contienen realmente la implementación en tiempo de ejecución de las funciones del GDK y XSAPI (si utiliza la versión dinámica de XSAPI).

Para que los juegos se integren con las experiencias esenciales del ecosistema de XBOX, deben interactuar con dos componentes: Gaming Runtime Services (GRTS) y XSAPI. Estos son los archivos que necesita un juego no administrado:

Componente	GRTS (solo dinámico)	XSAPI (dinámico)	XSAPI (estático)
Encabezados	Encabezados de GRTS: XUser, XGameSave, XGameUI, etc. (del GDK)	Encabezados de XSAPI: profile_c.h, achievements_c.h, etc. (del GDK)	Encabezados de XSAPI: profile_c.h, achievements_c.h, etc. (del GDK)
Biblioteca de importación	xgameruntime.lib (del GDK)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (del GDK)	Microsoft.Xbox.Services.142.GDK.C.lib (del GDK)
Biblioteca de vínculos dinámicos	xgameruntime.dll y algunas otras dll (system32, instaladas por GRTS)	Microsoft.Xbox.Services.GDK.C.Thunks.dll (del GDK, debe incluirse en el paquete del juego)	No es necesaria

Para los juegos que usan una arquitectura basada en complementos con la funcionalidad repartida entre varias DLL, recomendamos y admitimos integrar XSAPI en ellas usando la Thunks.dll. Este enfoque funciona de forma confiable tanto en la plataforma PC como en XBOX.Cuando vincula XSAPI estáticamente en varias DLL, cada DLL mantiene su propia copia del estado global. Como resultado, llamar a XblInitialize en una DLL no inicializa XSAPI en las demás. Compartir identificadores de XSAPI entre DLL con instancias estáticas separadas puede provocar bloqueos o un comportamiento impredecible.La Thunks.dll resuelve esto proporcionando una única instancia compartida de XSAPI y su estado. Esto evita la duplicación y garantiza un comportamiento coherente en todas las DLL.Aunque técnicamente es posible vincular XSAPI estáticamente en una DLL y exportar los símbolos, este enfoque es más complejo y propenso a errores. Usar la Thunks.dll es más sencillo, más seguro y totalmente compatible.

Adición de los requisitos de Gaming Runtime Services y XSAPI a su proyecto

Los pasos siguientes describen los cambios que debe realizar en su proyecto para asegurarse de que tenga todos los requisitos para usar Gaming Runtime Services y XSAPI.

Asegúrese de que el destino sea x64. En Visual Studio, vaya a Build->Configuration Manager y establezca Active solution platform en x64.
Agregue las siguientes rutas de inclusión: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Include Donde GDK version number será un directorio nombrado según el año, el mes y el número de subversión de la versión. Por ejemplo, para el GDK de junio de 2022, el nombre del directorio sería 220600. Para Microsoft GDK (junio de 2024) o anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include y C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include En Visual Studio, agregaría estas rutas en la página de propiedades del proyecto en Configuration Properties->VC++ Directories->Include Directories.
Agregue las siguientes rutas de biblioteca para las bibliotecas de importación: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64 C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64 Donde GDK version number será un directorio nombrado según el año, el mes y el número de subversión de la versión. Por ejemplo, para el GDK de junio de 2022, el nombre del directorio sería 220600. Para Microsoft GDK (junio de 2024) o anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release y C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib En Visual Studio, agregaría estas rutas en la página de propiedades del proyecto en Configuration Properties->VC++ Directories->Library Directories.
Agregue las siguientes bibliotecas a la lista de bibliotecas vinculadas a su proyecto: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64\xgameruntime.lib C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (or Microsoft.Xbox.Services.142.GDK.C.lib, if statically linking) C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib Donde GDK version number será un directorio nombrado según el año, el mes y el número de subversión de la versión. Por ejemplo, para el GDK de junio de 2022, el nombre del directorio sería 220600. Para Microsoft GDK (junio de 2024) o anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (o Microsoft.Xbox.Services.142.GDK.C.lib, si vincula estáticamente) y C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib En Visual Studio, agregaría las bibliotecas en la página de propiedades del proyecto en Configuration Properties->Linker->Input->Additional Dependencies.
Defina _GAMING_DESKTOP y WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP. En Visual Studio, agregaría la siguiente línea en la página de propiedades del proyecto en C/C++->Command Line->Additional Options: /D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"

Cree un archivo MicrosoftGame.config y asegúrese de que se copie en el mismo destino que el .exe durante las compilaciones. Nota: si su motor admite algún tipo de funcionalidad de ejecución en el editor que use un .exe diferente al ejecutarse, copie MicrosoftGame.config también en el mismo directorio que ese .exe. Si MicrosoftGame.config no está presente en el mismo directorio que el .exe, los servicios de XBOX no funcionarán al usar la funcionalidad de ejecución en el editor. Para comenzar el desarrollo, puede usar una configuración con valores predeterminados como el ejemplo siguiente. Los valores de Identity Name, Executable Name y Executable Alias se reemplazarían por el nombre de su ejecutable.

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>
<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>
<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

Asegúrese de que las copias de Microsoft.Xbox.Services.GDK.C.Thunks.dll (si se vincula dinámicamente), XCurl.dll y libHttpClient.GDK.dll se copien en el mismo destino que el .exe durante las compilaciones. Nota: si su motor admite algún tipo de funcionalidad de ejecución en el editor que use un .exe diferente al ejecutarse, asegúrese de que ese .exe también haga referencia a estas .dll. Si el .exe no hace referencia a las .dll, los servicios de XBOX no funcionarán al usar la funcionalidad de ejecución en el editor. Si vincula dinámicamente a XSAPI, Microsoft.Xbox.Services.GDK.C.Thunks.dll se puede encontrar en la instalación del GDK en el siguiente directorio: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release] XCurl.dll se puede encontrar en la instalación del GDK en el siguiente directorio: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64 libHttpClient.GDK.dll se puede encontrar en la instalación del GDK en el siguiente directorio: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64 Donde GDK version number será un directorio nombrado según el año, el mes y el número de subversión de la versión. Por ejemplo, para el GDK de junio de 2022, el nombre del directorio sería 220600. Para Microsoft GDK (junio de 2024) o anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|Release], C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral y C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral

Como alternativa, si está integrando el GDK en un proyecto de escritorio existente de Visual Studio, puede seguir los pasos de este tema para convertir su proyecto en un proyecto del GDK: Adición del Microsoft Game Development Kit a un proyecto de escritorio existente.

Actualización de MicrosoftGame.config

El archivo MicrosoftGame.config creado en el paso anterior tiene valores predeterminados que permiten el desarrollo temprano en PC y XBOX sin configuración adicional. Solo necesita actualizar estos valores cuando empiece a usar características de Gaming Runtime, Microsoft Store y la identidad del título. Para usar la funcionalidad de los servicios de XBOX, actualice el archivo MicrosoftGame.config de su proyecto con los detalles de identidad de su proyecto de Partner Center.

Vaya al panel de Partner Center.
Seleccione su juego en la lista de productos.
Seleccione la pestaña Game setup y, después, seleccione Identity details.
Seleccione Show Details para expandir la sección Identity details.
Use los siguientes valores de la tabla de la sección Identity details y, después, copie esos valores de Partner Center en el elemento y el campo correspondientes de MicrosoftGame.config.

Nombre en Partner Center	MicrosoftGame.config
XBOX Title ID	TitleId
Package/Identity/Name	Identity->Name
Package/Identity/Publisher	Identity->Publisher
XBOX services -> XBOX Settings -> MSAAppId	MSAAppId

Por ejemplo, los siguientes detalles de identidad en Partner Center darían como resultado que su MicrosoftGame.config tuviera el aspecto del ejemplo siguiente:

Nombre en Partner Center	Valor de ejemplo
XBOX Title ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
XBOX services -> XBOX Settings -> MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>

Consulte Información general de MicrosoftGame.config para obtener información adicional sobre los valores de MicrosoftGame.config.

Inicialización del entorno de ejecución del juego y XSAPI

Los pasos siguientes muestran cómo inicializar Gaming Runtime Services y XSAPI en su juego.

Incluya el encabezado XGameRuntime y el encabezado services-c de XSAPI.
#include <XGameRuntime.h> #include <xsapi-c/services_c.h>

Llame a XGameRuntimeInitialize para inicializar el entorno de ejecución del GDK.

// Initialize the GameRuntime
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr))
{
    if (hr == E_GAMERUNTIME_DLL_NOT_FOUND || hr == E_GAMERUNTIME_VERSION_MISMATCH)
    {
        (void)MessageBoxW(nullptr, L"Game Runtime is not installed on this system or needs updating.", g_szAppName, MB_ICONERROR | MB_OK);
    }
    return 1;
}

Llame a XblInitialize para inicializar XSAPI.

 XblInitArgs xblArgs = {};
 //xblArgs.queue = queue; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here;
 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // Handle failure
 }

Anulación de la inicialización del entorno de ejecución del juego

Es necesario anular la inicialización de Gaming Runtime Services antes de que el juego se cierre. No es necesario limpiar XSAPI explícitamente antes de salir. Anule la inicialización del entorno de ejecución del GDK llamando a XGameRuntimeUninitialize.

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

Consulte Introducción a las API de los servicios de XBOX para obtener información general detallada sobre el uso de XSAPI en su juego.
Consulte Características de Game Development Kit (GDK) para obtener información general sobre la implementación de las características del GDK.

Pruebas de los servicios de XBOX en su juego

Para probar la funcionalidad de los servicios de XBOX en su juego, como los logros, debe usar un sandbox y cuentas de prueba con acceso a ese sandbox.

Creación de una cuenta de prueba

Para probar cualquier característica de los servicios de XBOX en su juego, cree cuentas de prueba que tengan acceso a su sandbox de desarrollo. Para obtener información sobre la creación de cuentas de prueba, consulte Creación de cuentas de prueba.

Cambio de sandbox

Después de haber creado una cuenta de prueba, use la cuenta para acceder a su sandbox mediante los pasos siguientes.

Para encontrar su identificador de sandbox, vaya a Partner Center.
Seleccione XBOX services y, después, seleccione Gameplay Settings.
Su identificador de sandbox está en la primera pestaña y tiene un nombre similar a “ABCDEF.0”.
Abra el menú Inicio.
Escriba Microsoft GDK Command Prompts y, después, seleccione Entrar en el teclado.
Abra el primer símbolo del sistema.
En el símbolo del sistema, escriba XblPCSandbox.exe [su identificador de sandbox].
Después de que el símbolo del sistema inicie varias aplicaciones, inicie sesión en la aplicación XBOX con su cuenta de prueba.

Si puede iniciar sesión correctamente, ha creado una cuenta de prueba y ha cambiado a su sandbox para comenzar las pruebas. Para obtener más información sobre los sandboxes, consulte Información general de los sandboxes de los servicios de XBOX.

Publicación

Para estar listo para publicar su juego, necesita:

Haber terminado de integrar su juego con el GDK
Haber creado un paquete de juego siguiendo los pasos de Introducción al empaquetado de títulos para PC mediante las herramientas de empaquetado MSIXVC

Después de completar esos dos requisitos, estará listo para publicar. Para enviar su juego, vaya a Partner Center y siga las instrucciones de la interfaz de usuario.

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Creación de un producto en Partner Center

Integración del GDK en juegos de C/C++

Adición de los requisitos de Gaming Runtime Services y XSAPI a su proyecto

Actualización de MicrosoftGame.config

Inicialización del entorno de ejecución del juego y XSAPI

Anulación de la inicialización del entorno de ejecución del juego

Pruebas de los servicios de XBOX en su juego

Creación de una cuenta de prueba

Cambio de sandbox

Publicación

​Creación de un producto en Partner Center

​Integración del GDK en juegos de C/C++

​Adición de los requisitos de Gaming Runtime Services y XSAPI a su proyecto

​Actualización de MicrosoftGame.config

​Inicialización del entorno de ejecución del juego y XSAPI

​Anulación de la inicialización del entorno de ejecución del juego

​Pruebas de los servicios de XBOX en su juego

​Creación de una cuenta de prueba

​Cambio de sandbox

​Publicación

Creación de un producto en Partner Center

Integración del GDK en juegos de C/C++

Adición de los requisitos de Gaming Runtime Services y XSAPI a su proyecto

Actualización de MicrosoftGame.config

Inicialización del entorno de ejecución del juego y XSAPI

Anulación de la inicialización del entorno de ejecución del juego

Pruebas de los servicios de XBOX en su juego

Creación de una cuenta de prueba

Cambio de sandbox

Publicación