Información general
Este artículo describe cómo integrar los componentes de Microsoft Game Development Kit (GDK) en su proyecto de Unreal Engine. Abarca los distintos tipos de complementos de Unreal Engine y extensiones de plataforma, cómo configurarlos y qué funcionalidad se incluye en los complementos y extensiones proporcionados. Epic Games mantiene y distribuye las GDK Platform Extensions y los complementos asociados.Requisitos previos
Para usar las GDK Platform Extensions y los complementos del GDK para Unreal Engine, necesita los siguientes requisitos previos.- Unreal Engine 4.27 o posterior (se recomienda Unreal Engine 5.8 o posterior; los complementos del GDK están disponibles públicamente a partir de la versión 5.8, o disponibles con la versión 5.7 a través de las GDK Platform Extensions)
- Visual Studio 2019 (16.9) o posterior
- Windows SDK (22000 o posterior)
- Windows 10 (1809 o posterior) o Windows 11
- Microsoft GDK (instálelo con
winget install Microsoft.GDK)
Complementos de Microsoft GDK para Unreal Engine
Cada complemento del GDK proporciona funcionalidades diferentes cuando lo habilita para su proyecto. Los complementos de esta sección forman parte de las extensiones de plataforma del GDK que distribuye Epic Games. A partir de Unreal Engine 5.8, los complementos del GDK están disponibles públicamente con el motor. Puede adquirirlos a través del Epic Games Launcher o del código fuente de Unreal Engine en GitHub. No se necesita ninguna solicitud de acceso independiente. Para obtener una guía sobre las distintas formas de adquirir estos complementos, consulte Creación de juegos de XBOX con los nuevos complementos del GDK de Unreal Engine. En Unreal Engine 5.7, existen los mismos complementos, pero forman parte de las GDK Platform Extensions, que requieren pertenecer a un programa para desarrolladores de XBOX, como ID@XBOX, y una solicitud de acceso independiente. Solicite acceso mediante este formulario de solicitud de acceso. Tras la aprobación, obtendrá acceso al código fuente de Unreal Engine que incluye las GDK Platform Extensions.Para Unreal Engine 5.7, es necesario unirse a un programa para desarrolladores de XBOX y solicitar acceso a los complementos del GDK y a las GDK Platform Extensions para el desarrollo en PC, XBOX Series X|S y XBOX One. Este requisito de acceso se ha eliminado en Unreal Engine 5.8 y versiones posteriores, donde los complementos están disponibles públicamente. Si tiene algún problema, póngase en contacto con su representante de Microsoft para obtener ayuda.
Microsoft GDK Runtime Plug-in for Unreal Engine: proporciona acceso a la funcionalidad en tiempo de ejecución del GDK, como los guardados de juego compatibles con XBOX y la selección de usuario de XBOX. En Unreal Engine 5.7, este complemento se encuentra en la carpeta de las GDK Platform Extensions como
MSGamingRuntime. En Unreal Engine 5.8, se ha movido a Engine\Plugins\Runtime\Windows\MSGamingRuntime.
Microsoft GDK Store Plug-in for Unreal Engine: proporciona la generación automática de paquetes .msixvc para su envío a la aplicación XBOX para PC. En Unreal Engine 5.7, este complemento se encuentra en la carpeta de las GDK Platform Extensions como MSGameStore. En Unreal Engine 5.8, se ha movido a Engine\Plugins\Runtime\Windows\MSGameStore.
Online Subsystem GDK: proporciona la integración del GDK con el Online Subsystem de Unreal. Este complemento es una capa de abstracción del motor que proporciona llamadas de interfaz comunes para características clave como logros, amigos y emparejamiento (matchmaking). En Unreal Engine 5.7, este complemento se encuentra en todas las carpetas de plataforma, incluida la carpeta GDK para la compatibilidad con Win64, como OnlineSubsystemGDK. En Unreal Engine 5.8, el complemento de Win64 se ha movido a Engine\Plugins\Online\Microsoft\OnlineSubsystemGDK.
Si ya ha habilitado estos complementos para su proyecto, los nombres de los complementos siguen siendo los mismos entre Unreal Engine 5.7 y 5.8. La configuración del proyecto se conserva al actualizar. Las rutas de las carpetas solo importan si navega directamente por el código fuente del motor.
Los complementos Game Input (Windows), Game Input Base y XBOX Common Game Input proporcionan la integración con la funcionalidad de
GameInput dentro de Unreal Engine. Estos complementos se estructuran de la siguiente manera.
- GameInput (nombre descriptivo: Game Input Base)
- Contiene la funcionalidad principal y una interfaz que implementan los complementos que aparecen más abajo en esta lista
- Plataforma: Win64
- GameInput_WinGDK, GameInput_XB1 y GameInput_XSX extienden el complemento GameInput para agregar compatibilidad con sus plataformas respectivas (sin diferencias de código respecto al elemento primario)
- Plataforma: Win64
- Contiene la funcionalidad principal y una interfaz que implementan los complementos que aparecen más abajo en esta lista
- GameInputWindows (nombre descriptivo: Game Input (Windows))
- Depende de GameInput e implementa la interfaz del complemento GameInput
- Plataforma: Win64
- GameInputWindows_WinGDK extiende GameInputWindows para agregar compatibilidad con la plataforma WinGDK (sin diferencias de código respecto al elemento primario)
- XboxCommonGDKGameInput (nombre descriptivo: XBOX Common GameInput)
- Depende de GameInput e implementa una interfaz del complemento GameInput
- Plataforma: ninguna especificada
- Equivalente a GameInputWindows, pero para las dos plataformas de XBOX y con una implementación de interfaz diferente (debido a las diferencias de GameInput entre plataformas)
- XboxCommonGDKGameInput_XB1 y XboxCommonGDKGameInput_XSX extienden XboxCommonGDKGameInput para agregar compatibilidad con sus plataformas respectivas (sin diferencias de código respecto al elemento primario)
Engine\Platforms\GDK\Plugins. En Unreal Engine 5.8, se ha movido a Engine\Plugins\Runtime\Microsoft\GDKPackageChunkInstall. Los complementos específicos de plataforma con el sufijo de plataforma para WinGDK, XBOX One y XBOX Series X|S existen dentro de sus carpetas de plataforma respectivas.
El complemento GDK Virtual Keyboard y el complemento Windows Virtual Keyboard proporcionan funcionalidad para invocar un teclado virtual como parte de su juego. Esta funcionalidad es especialmente importante cuando se consideran escenarios de mando en dispositivos portátiles.
El complemento GDK Virtual Keyboard usa una API específica del GDK para habilitar esta funcionalidad. En Unreal Engine 5.7, el complemento compatible con Win64 se encuentra en la carpeta Engine\Platforms\GDK\Plugins. En Unreal Engine 5.8, se ha movido a Engine\Plugins\Runtime\Microsoft\GDKVirtualKeyboard. El complemento Windows Virtual Keyboard se encuentra en Engine\Plugins\Runtime\Windows\WinVirtualKeyboard en Unreal Engine 5.8. Los complementos específicos de plataforma con el sufijo de plataforma para WinGDK (_WinGDK), XBOX One (_XB1) y XBOX Series X|S (_XSX) existen dentro de sus carpetas de plataforma respectivas.
Unreal Engine y las GDK Platform Extensions
El código específico del GDK dentro de Unreal Engine forma parte de las GDK Platform Extensions. Estas extensiones se agregan al código fuente base del motor y le permiten compilar su juego mediante el GDK para PC, XBOX One y XBOX Series X|S. Las extensiones incluyen un conjunto de plataformas del GDK y de complementos del GDK que funcionan con el motor para extender la funcionalidad necesaria. En Unreal Engine 5.7, las GDK Platform Extensions son una descarga independiente que requiere la pertenencia a un programa para desarrolladores de XBOX. Necesita el GDK con extensiones de XBOX (GDKx) independientemente de su plataforma de destino. Las extensiones incluyen código fuente enEngine\Platforms con las siguientes plataformas específicas del GDK:
- WinGDK
- XBOX One
- XBOX Series X|S
Engine\Plugins\. La descarga de las GDK Platform Extensions ya no es necesaria para el desarrollo exclusivo para PC. El desarrollo para consolas XBOX (XBOX One, XBOX Series X|S) sigue requiriendo las GDK Platform Extensions.
Las carpetas GDK y XboxCommon proporcionan código compartido entre plataformas. El código de GDK se comparte entre todas las plataformas, y el código de XboxCommon se comparte entre las plataformas XBOX One y XBOX Series X|S. Puede encontrar los complementos de cada plataforma en la carpeta Plugins dentro de cada plataforma en la descarga de las GDK Platform Extensions.
Para obtener más información sobre las configuraciones de XBOX One y XBOX Series X|S, consulte la documentación del GDK de Epic Games.
Si usa Unreal Engine 4, aparece XboxOneGDK en lugar de XB1. Epic Games cambió el nombre de esta plataforma a XB1 en Unreal Engine 5.
Compatibilidad entre el GDK y el motor
Cada versión de Unreal Engine incluye notas de la versión que especifican qué versión principal del GDK admite el Unreal Editor. El equipo de Unreal Engine prueba esta versión para validar la compatibilidad con el motor. Por ejemplo: Figura 1. Notas de la versión de Unreal Engine. El archivo de configuración que define esta compatibilidad y el intervalo de versiones del GDK admitidas es el archivoGDK_SDK.json. La ubicación de este archivo varía según la versión del motor:
- Unreal Engine 5.7 y anteriores:
Engine\Platforms\GDK\Config\GDK_SDK.json - Unreal Engine 5.8:
Engine\Config\Microsoft\GDK_SDK.json
Actualizaciones del proyecto para trabajar con las GDK Platform Extensions
Después de adquirir el código fuente de las GDK Platform Extensions, actualice los archivos de su proyecto para acceder a las plataformas específicas del GDK en su IDE. Para obtener más información, consulte Actualizar archivos de proyecto. Ejecute el archivo GenerateProjectFiles.bat en el directorio raíz de su versión del motor. Cuando termine este paso, verá opciones para compilar para cada plataforma en la lista desplegable IDE Solution Platform. Figura 2. Plataformas del GDK de Unreal Engine en el IDE de Visual Studio. Después de recompilar el editor, verá estas opciones y configuraciones de plataforma disponibles en el Unreal Editor. Para probar esta característica, seleccione la lista desplegable Platforms y confirme que WinGDK, XB1 y XSX existen en la lista. Figura 3. Plataformas del GDK de Unreal Engine en el Unreal Editor. Para obtener más información, consulte Compilación de Unreal Engine desde el código fuente.Adición de los complementos del GDK a su proyecto
Un subconjunto de los complementos del GDK se habilita automáticamente de forma predeterminada para XBOX One y XBOX Series X|S. Para obtener más información, consulte
UEBuildXboxCommon.cs en el código fuente de la Unreal Build Tool (UBT).Configuración de los complementos del GDK con datos específicos del título
Después de configurar los complementos del GDK y las extensiones de plataforma del GDK, actualice la configuración de Platform y Plugin en el menú Project Settings. Puede encontrar las plataformas XBOX One y XBOX Series X|S en Platform Settings. Los complementos de Microsoft GDK para Unreal Engine están en Plugin Settings. Figura 5. Configuración de Platform y Plugins del GDK de Unreal Engine. Cada plataforma y complemento contiene un conjunto similar de opciones que le ayudan a configurar su archivo MicrosoftGame.config y la configuración de empaquetado. Figura 6. Configuración del proyecto de los complementos del GDK, parte 1. Su MicrosoftGame.config local necesita la información de su producto, comoTitle ID y Store ID, para funcionar correctamente con el GDK y los servicios de XBOX. Use la opción Associate with Partner Center para iniciar sesión con una cuenta Microsoft que tenga acceso al Centro de partners de Microsoft. Esta opción agrega automáticamente los detalles de su producto al archivo MicrosoftGame.config local, de modo que no necesita introducirlos manualmente.
Además de la configuración de MicrosoftGame.config, configure las opciones de empaquetado e instalación.
Figura 7. Configuración del proyecto de los complementos del GDK, parte 2.
Más allá de la configuración de Platform y Plugin, asegúrese de que su DefaultEngine.ini tenga la información necesaria. Las opciones del complemento MS Gaming (PC GDK) escriben automáticamente esta información en la sección. Este es un ejemplo del DefaultEngine.ini que usa los complementos del GDK como referencia.
Para especificar cualquier invalidación en el archivo .ini de motor de la plataforma (por ejemplo, WindowsEngine.ini), modifique ese archivo manualmente.
Uso del Online Subsystem GDK
El complemento Online Subsystem GDK proporciona una abstracción del motor de las API clave de los servicios de XBOX para simplificar el código del juego escrito para realizar acciones similares en muchas tiendas y plataformas (por ejemplo, inicio de sesión, compras en la tienda, logros, amigos, emparejamiento). Use el Online Subsystem si está creando un juego con el GDK. Para configurar el Online Subsystem GDK, edite su DefaultEngine.ini (o el archivo .ini de motor de la plataforma) con detalles adicionales para asegurarse de que funciona correctamente para su juego. Este es un ejemplo para el WindowsEngine.ini.Achievements.json en el directorio platforms\GDK\Config\OSS\ de su proyecto (tenga en cuenta que la ruta podría no existir y que podría tener que crearla usted mismo). Achievements.json contiene una asignación de los nombres de logros a sus identificadores del Centro de partners. Por ejemplo, si su proyecto tiene 10 logros llamados achievement 1 a achievement 10, Achievements.json tiene este aspecto.
Achievements.json, pase GDK_SUBSYSTEM en sus llamadas a Online::GetSubsystem().
El Online Subsystem GDK usa Microsoft Azure PlayFab Party directamente a través de los complementos PlayFabParty del GDK como Socket Subsystem.
Uso de Visual Studio y Unreal Engine
Visual Studio proporciona funcionalidad adicional, como parte del instalador de Visual Studio, para una mejor integración con Unreal Engine. Esta funcionalidad se incluye en la carga de trabajo Desarrollo de juegos con C++. Dos componentes de instalación opcionales, denominados Visual Studio Tools for Unreal Engine y Visual Studio debugger tools for Unreal Engine, proporcionan compatibilidad nativa conuplugin y la capacidad de depurar la lógica de Blueprint desde Visual Studio.
Figura 8. Visual Studio Tools for Unreal Engine en el instalador de Visual Studio.
Para obtener más información sobre las Visual Studio Tools for Unreal Engine, consulte Instalación de Visual Studio Tools for Unreal Engine.
Compilación, procesamiento (cook) y empaquetado del proyecto
Use la Unreal Automation Tool para compilar, procesar (cook) y empaquetar automáticamente su juego para cada plataforma del GDK. Esta herramienta también crea un paquete para su integración de los complementos del GDK mediante la plataforma Win64. Para usar esta herramienta, siga la sintaxis proporcionada.Pruebas del proyecto
También puede usar la Unreal Automation Tool para implementar e iniciar su compilación. Para hacerlo, use estas marcas.Hay algunas limitaciones conocidas con la plataforma WinGDK y la compatibilidad con PIE. Recomendamos pruebas con compilaciones independientes y empaquetadas para esta plataforma.
Prueba del juego de forma remota mediante las XBOX PC Remote Tools
A partir de Unreal Engine 5.8, Remote Windows Deployment le permite compilar, procesar (cook), implementar e iniciar su juego en un PC con Windows independiente, incluido hardware de Windows en Arm64, directamente desde el Unreal Editor o desde la línea de comandos. Esta característica está respaldada por las XBOX PC Remote Tools. Después de instalar el XBOX PC Toolbox tanto en su equipo de desarrollo como en el dispositivo de destino y emparejarlos, registre el destino en la configuración del motor y, a continuación, selecciónelo en el menú Launch On de la barra de herramientas del editor, o pase-deploy -run -device=<DeviceName> a RunUAT BuildCookRun.
Para conocer los pasos de configuración, consulte la guía de inicio rápido de las XBOX PC Remote Tools. Para la configuración del lado del motor y ejemplos de línea de comandos, consulte Remote Windows Deployment en Unreal Engine en la documentación de Epic Games.
Información adicional
Uso de Microsoft Azure PlayFab con Unreal Engine
Para obtener más información sobre cómo trabajar con PlayFab, que incluye integración directa y complementos para trabajar dentro de Unreal Engine, incluida la compatibilidad con el Online Subsystem, consulte la página Inicio rápido de PlayFab para Unreal Engine.Detección de dispositivos portátiles de Windows
Unreal Engine 5.7 admite la detección de dispositivos portátiles de Windows medianteFPlatformMisc::IsDeviceHandheld(). Esta función devuelve true o false según el estado del dispositivo.
