Compilación y ejecución de su primer título de consola con GDKX

Este tutorial documenta el proceso de un extremo a otro para crear un pequeño título sample-game y compilarlo para las consolas XBOX Series X|S. Después, implementará el juego completo en un kit de desarrollo de XBOX, diagnosticará errores de inicio y creará un XVC instalable. El ejemplo completado usa C++, Direct3D 12 y el GDK con extensiones de XBOX (GDKX). También usa DirectXTK12 como asistente de representación opcional. Ambas paletas están controladas por el equipo, de modo que el juego puede ejecutarse sin supervisión mientras itera en los gráficos, la jugabilidad y los efectos.

El GDK público disponible mediante GitHub o WinGet solo admite el desarrollo de juegos para PC con Windows. Para compilar e implementar un ejecutable de consola XBOX, instale el GDK con extensiones de XBOX (GDKX) desde XBOX Secure Downloads. El acceso requiere una cuenta de desarrollador de XBOX aprobada. Consulte Incorporación a ID@XBOX y Acceso a los recursos y descargas del GDK.

Lo que va a compilar

Al final de este tutorial, tendrá:

Un proyecto nativo del GDK de XBOX (no un proyecto de UWP).
Configuraciones Debug, Profile y Release para las consolas XBOX Series X|S y las consolas de la familia XBOX One.
Un juego de ejemplo con reproducción automática, con puntuación, IA predictiva de las paletas, efectos de partículas, una estela de movimiento y un disco circular con textura.
Una implementación completa de archivos sueltos en ejecución en un kit de desarrollo de XBOX.
Un XVC opcional asociado a la Store que puede instalarse y probarse en el kit de desarrollo.

Antes de empezar

Este tutorial se validó con:

Visual Studio 2022 Enterprise 17.14.
GDKX de April 2026 Update 2, edición 260402.
Gaming.XBOX.Scarlett.x64 para las consolas XBOX Series X|S.
Gaming.XBOX.XboxOne.x64 para las consolas de la familia XBOX One.
Confirmación e656d54637b2830fc6eb5ecd9b329a9c72cb87d4 de DirectXTK12.

Use la edición del GDK instalada en su PC de desarrollo en lugar de 260402 si sigue el tutorial con otra versión.

Paso 1: Cree la carpeta de trabajo

Abra PowerShell y cree una carpeta raíz vacía.

New-Item -ItemType Directory -Path D:\repos\sample-game -Force

El diseño final del proyecto usado en este tutorial es:

D:\repos\sample-game
|-- external
|   `-- DirectXTK12
|-- tools
|   `-- BuildAssets.ps1
|-- sample-game
|   |-- Assets
|   |-- DeviceResources.cpp
|   |-- DeviceResources.h
|   |-- Game.cpp
|   |-- Game.h
|   |-- GameTuning.h
|   |-- GraphicsLogo.png
|   |-- LargeLogo.png
|   |-- Main.cpp
|   |-- MicrosoftGameConfig.mgc
|   |-- ParticleSystem.cpp
|   |-- ParticleSystem.h
|   |-- sample-gameSimulation.cpp
|   |-- sample-gameSimulation.h
|   |-- pch.cpp
|   |-- pch.h
|   |-- SmallLogo.png
|   |-- SplashScreen.png
|   |-- StepTimer.h
|   |-- StoreLogo.png
|   `-- sample-game.vcxproj
`-- sample-game.sln

Visual Studio crea DeviceResources.*, Main.cpp, pch.*, StepTimer.h y los archivos PNG visuales del shell a partir de la plantilla Direct3D 12 XBOX Game. Conserve esos archivos generados al agregar el código fuente específico del ejemplo.

Paso 2: Compruebe la instalación del GDK de XBOX

Abra el XBOX Series X|S VS 2022 Gaming Command Prompt instalado con GDKX. El acceso directo suele estar en Microsoft GDK en el menú Inicio. También puede inicializar el entorno desde un símbolo del sistema normal:

call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxScarlettVS2022 260402

Compruebe que las herramientas de compilación e implementación de XBOX están disponibles:

echo %GXDKEDITION%
where msbuild
where cl
where xbconnect
where xbapp
where makepkg

La instalación del GDK no está lista para el desarrollo en consola si:

GXDKEDITION está vacío.
Falta el acceso directo al símbolo del sistema de XBOX.
Visual Studio no muestra las plantillas de proyecto de XBOX.
La plataforma de MSBuild Gaming.XBOX.Scarlett.x64 no está disponible.
No se encuentran xbconnect ni xbapp.

Si solo están disponibles los símbolos del sistema y las plantillas de Desktop del GDK, probablemente esté instalado el GDK público para PC en lugar de GDKX.

Paso 3: Cree un proyecto de XBOX nativo

Abra Visual Studio 2022 y seleccione Create a new project

Establezca Language en C++, Platform en XBOX y Project type en Games.

Seleccione Direct3D 12 XBOX Game

Establezca el nombre del proyecto en sample-game y la ubicación en D:\repos\sample-game.

Deje desactivada la opción Place solution and project in the same directory

De este modo, la solución queda en la raíz y el proyecto en D:\repos\sample-game\sample-game.

Cree el proyecto

El flujo de trabajo admitido consiste en crear el proyecto mediante Visual Studio. Copiar manualmente los archivos de la plantilla d3d12game_gx es una técnica de recuperación, no el flujo de trabajo recomendado para nuevos proyectos.

Confirme que el proyecto no es UWP

Antes de agregar el código del juego, compruebe que el proyecto:

Contiene MicrosoftGameConfig.mgc.
Usa una plataforma de proyecto Gaming.XBOX.*.x64.
Se vincula con las bibliotecas de plataforma del GDK de XBOX.
No usa Package.appxmanifest como configuración del título.
Se creó a partir de Direct3D 12 XBOX Game, no de una plantilla de Windows universal.

Si el proyecto es UWP, elimínelo y cree un nuevo proyecto a partir de la plantilla del GDK de XBOX. Convertir el proyecto de UWP generado es más propenso a errores que empezar con la plantilla correcta.

Paso 4: Fije la edición del GDK y configure los destinos de consola

Fijar la edición del GDK evita que una futura instalación del GDK cambie de forma silenciosa la cadena de herramientas usada por el proyecto. En el grupo de propiedades principal de sample-game.vcxproj, establezca:

<XdkEditionTarget>260402</XdkEditionTarget>

Use el Administrador de configuración de Visual Studio para confirmar estas configuraciones de la solución:

Configuración	Plataforma
Debug	`Gaming.XBOX.Scarlett.x64`
Profile	`Gaming.XBOX.Scarlett.x64`
Release	`Gaming.XBOX.Scarlett.x64`
Debug	`Gaming.XBOX.XboxOne.x64`
Profile	`Gaming.XBOX.XboxOne.x64`
Release	`Gaming.XBOX.XboxOne.x64`

Si el título solo admite las consolas XBOX Series X|S, puede omitir las configuraciones de las consolas de la familia XBOX One. Consulte Desarrollo entre generaciones para publicar el mismo título en varias generaciones.

Paso 5: Compile la plantilla sin modificar

Compile la plantilla generada antes de agregar dependencias o código del juego. Esto aísla los problemas de la cadena de herramientas de los problemas introducidos por el ejemplo. Desde un XBOX Series X|S VS 2022 Gaming Command Prompt:

msbuild D:\repos\sample-game\sample-game.sln /m /restore /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

Para las consolas de la familia XBOX One, inicialice el entorno de comandos de XBOX One y compile la plataforma de XBOX One:

call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxVS2022 260402
msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.XboxOne.x64 /nologo /verbosity:minimal

No continúe hasta que la plantilla estándar de XBOX se compile correctamente.

Paso 6: Agregue DirectXTK12 como asistente opcional

DirectXTK12 no es necesario para crear un título de GDK. La plantilla del GDK de XBOX ya proporciona el dispositivo Direct3D 12, la cola de comandos, la cadena de intercambio y el bucle de juego necesarios para compilar un juego directamente con Direct3D 12. Este ejemplo usa la biblioteca independiente de código abierto DirectXTK12 de Microsoft. La biblioteca reduce la cantidad de código auxiliar de representación de bajo nivel necesario para la representación de sprites, la administración de descriptores, la carga de texturas, la carga de recursos y la administración de la memoria gráfica. Un título puede reemplazar estos asistentes por su propio motor o por una implementación directa de D3D12. Clone DirectXTK12 en el proyecto:

Set-Location D:\repos\sample-game
New-Item -ItemType Directory -Path .\external -Force
git clone https://github.com/microsoft/DirectXTK12.git .\external\DirectXTK12
git -C .\external\DirectXTK12 checkout e656d54637b2830fc6eb5ecd9b329a9c72cb87d4

En Visual Studio:

Agregue external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj a la solución.
Agregue DirectXTK12 como referencia de proyecto desde sample-game.
Agregue $(SolutionDir)external\DirectXTK12\Inc a los directorios de inclusión.
Compile ambos proyectos para la misma plataforma y configuración de XBOX.

El proyecto sample-game usa esta propiedad:

<DirectXTK12Dir>$(SolutionDir)external\DirectXTK12\</DirectXTK12Dir>

A continuación, agrega la ruta de inclusión y la referencia de proyecto:

<AdditionalIncludeDirectories>$(DirectXTK12Dir)Inc;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>

<ProjectReference Include="$(DirectXTK12Dir)DirectXTK_GDKX_2022.vcxproj">
  <Project>{94F17A4D-611B-4B81-8806-B6735910AB31}</Project>
  <Name>DirectXTK12</Name>
</ProjectReference>

En este proyecto, los comandos de compilación de sombreadores de DirectXTK12 se cambiaron para invocar CompileShaders.cmd mediante una ruta explícita relativa al proyecto:

Command="&quot;$(ProjectDir)Src\Shaders\CompileShaders.cmd&quot; gxdk scarlett"

Esto evita depender del directorio de comandos actual cuando MSBuild invoca el compilador de sombreadores.

Paso 7: Agregue el código del juego

El ejemplo separa el estado de la jugabilidad de la representación, de modo que la simulación pueda ajustarse sin cambiar el código de Direct3D. Conserve los archivos generados por la plantilla, incluidos DeviceResources.*, Main.cpp, pch.*, StepTimer.h y los cinco archivos PNG visuales del shell. Agregue al proyecto estos archivos específicos del ejemplo:

Archivo	Propósito
`GameTuning.h`	Constantes de la arena, las paletas, el disco, la IA, la estela y las partículas.
`sample-gameSimulation.h/.cpp`	Movimiento del disco, movimiento de las paletas, colisiones, puntuación, saques e IA.
`ParticleSystem.h/.cpp`	Grupo de partículas de tamaño fijo y emisores de impacto.
`Game.h/.cpp`	Recursos de DirectXTK12, actualización del juego y representación.
`tools\BuildAssets.ps1`	Generación reproducible de DDS para el sprite blanco y el disco.

Use un paso de simulación fijo

El proyecto usa el StepTimer de la plantilla con una actualización fija de 120 Hz. Un paso fijo mantiene estables la respuesta a las colisiones y el comportamiento de la IA cuando los tiempos de fotograma varían. La simulación contiene:

Los estados de dos paletas.
El estado de un disco circular.
Las puntuaciones de los lados izquierdo y derecho.
Un retraso de saque y una dirección de saque alternante.
Eventos de impacto para las colisiones con las paletas, las paredes y las porterías.

Implemente la colisión del disco circular

Trate cada paleta como un rectángulo alineado con los ejes y el disco como un círculo:

Busque el punto del rectángulo de la paleta más cercano al centro del disco.
Mida la distancia al cuadrado desde ese punto hasta el centro del disco.
Se produjo una colisión si la distancia no es mayor que el radio del disco al cuadrado.
Mueva el disco fuera de la paleta para evitar superposiciones repetidas.
Calcule el ángulo de salida a partir del desplazamiento del golpe y la velocidad de la paleta.
Aumente ligeramente la velocidad del disco, hasta un máximo.

Esto mantiene la física circular aunque el disco se dibuje a partir de una textura cuadrada.

Agregue la reproducción automática predictiva

Cada paleta:

Predice dónde intersecará el disco con su posición horizontal.
Refleja la coordenada prevista en las paredes superior e inferior de la arena.
Actualiza su objetivo a un intervalo de reacción fijo.
Usa límites de aceleración y velocidad máxima en lugar de desplazamientos instantáneos.
Agrega un pequeño error de puntería determinista.

Para permitir que se marquen puntos, cada lado entra ocasionalmente en una breve ventana de error y se aleja deliberadamente de la intersección prevista. Escalone los temporizadores de error iniciales para que ambas paletas no fallen simultáneamente.

Represente la escena con DirectXTK12

Cree:

GraphicsMemory.
Un montón de descriptores que contenga una textura blanca y la textura del disco.
Un SpriteBatch con alfa normal.
Un SpriteBatch aditivo para las partículas.
Texturas DDS mediante ResourceUploadBatch y CreateDDSTextureFromFile.

Dibuje la arena, la línea central, las paletas, la puntuación, la estela del disco y el disco con SpriteBatch. Dibuje las partículas en la pasada aditiva. El ejemplo completado se representa en un sistema de coordenadas virtuales de 1920 por 1080 y escala esa escena a la ventanilla de salida.

Mantenga los efectos contenidos

El ajuste final usó:

Una sacudida de pantalla breve con decaimiento exponencial.
Partículas de impacto más pequeñas con forma de estela.
Más partículas en los golpes de paleta que en los golpes de pared.
Una explosión más intensa para un gol.
Una estela del disco con alfa bajo.
Un breve destello verde de impacto.

Estos cambios preservaron la respuesta de impacto sin que el juego pareciera caricaturesco ni que las colisiones con las paletas resultaran visualmente molestas.

Paso 8: Cree e implemente los recursos de textura

El ejemplo necesita:

Assets\white.dds: una textura RGBA blanca de 1 por 1 usada para dibujar rectángulos y partículas.
Assets\xbox_logo.dds: una textura RGBA de 256 por 256 usada para el disco.

El script de recursos:

Carga el logotipo de origen.
Cambia su tamaño a 256 por 256.
Aplica una máscara alfa circular difuminada.
Escribe un DDS RGBA8 con un encabezado DX10.
Crea el DDS blanco de 1 por 1.

Ejecútelo desde PowerShell:

Set-Location D:\repos\sample-game
.\tools\BuildAssets.ps1

Registre ambos archivos DDS como contenido de implementación en sample-game.vcxproj:

<CopyFileToFolders Include="Assets\white.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>
<CopyFileToFolders Include="Assets\xbox_logo.dds">
  <DeploymentContent>true</DeploymentContent>
  <DestinationFileName>Assets\%(Filename)%(Extension)</DestinationFileName>
</CopyFileToFolders>

Un archivo DDS que usa el encabezado estándar más una extensión DX10 tiene 148 bytes antes de los datos de píxeles. Durante la sesión original, un escritor de DDS personalizado emitió 152 bytes y el título falló durante la carga de texturas con 0x8007000D. Si usa un escritor de DDS personalizado, valide la disposición del encabezado antes de la implementación.

Paso 9: Compile el juego

Desde el XBOX Series X|S VS 2022 Gaming Command Prompt:

msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

La salida de la compilación suelta es:

D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug

Confirme que la salida contiene:

sample-game.exe
MicrosoftGame.config
Los archivos PNG visuales del shell
Assets\white.dds
Assets\xbox_logo.dds
Los archivos DLL en tiempo de ejecución necesarios
La imagen de Game OS u otros metadatos de implementación producidos por la compilación

El origen del proyecto se denomina MicrosoftGameConfig.mgc. El elemento de compilación MGCCompile del GDK lo valida y emite MicrosoftGame.config en la salida de la compilación. La implementación y el empaquetado usan el archivo .config generado. Consulte Configuración del juego.

Paso 10: Conéctese al kit de desarrollo de XBOX

Establezca la consola predeterminada con su dirección IP de herramientas o su nombre de host:

xbconnect <console-address>

Compruebe la consola almacenada:

xbconnect /B

Ejecute los diagnósticos de conexión:

xbconnect /DX

Si el título usa un sandbox de Partner Center, configure el identificador de sandbox (distingue mayúsculas de minúsculas) y reinicie la consola:

xbconfig sandboxid=<sandbox-id>
xbreboot
xbconnect /WS

Muestre el sandbox actual:

xbconfig sandboxid

Paso 11: Implemente el juego completo

Implemente toda la carpeta de salida de la compilación:

xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"

No copie solo sample-game.exe. El título también necesita MicrosoftGame.config, los recursos, las dependencias en tiempo de ejecución, las imágenes del shell y los metadatos de implementación. Una copia solo del ejecutable no es una implementación completa válida.

Para una reimplementación limpia después de cambiar los recursos o la configuración:

xbapp list
xbapp terminate <package-family-name-or-AUMID>
xbapp uninstall <package-full-name>
xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug"

Use xbapp list después de la implementación para encontrar el nombre completo del paquete registrado y el identificador de modelo de usuario de aplicación (AUMID). El AUMID termina con !Game.

Paso 12: Inicie y verifique el juego

Inicie exactamente el AUMID que notificó xbapp list:

xbapp launch <package-family-name>!Game

Espere al proceso del título:

xbconnect /WTP:60

Compruebe que el paquete se está ejecutando:

xbapp query <package-full-name>

El resultado esperado es:

Package execution state: 1 (running)

En este punto, la partida con reproducción automática debería verse en el kit de desarrollo.

Paso 13: Diagnostique un error de inicio inmediato

Si el juego se cierra inmediatamente, no dé por hecho que la implementación se realizó correctamente porque se copió el ejecutable.

Obtenga el último resultado del título

xbapp lastgamedetails

Supervise la salida de depuración

Inicie un monitor de salida de depuración en un símbolo del sistema:

xbdbgmon /t /v

Inicie el juego desde otro:

xbapp launch <package-family-name>!Game

El ejemplo agregó mensajes OutputDebugStringA en torno a:

La inicialización del juego.
La creación de recursos de DirectXTK12.
Cada carga de textura.
La creación de la canalización de sprites.
La finalización de la carga de texturas.
Las excepciones de fotograma.

La sesión original aisló el error de inicio en la carga de white.dds. El cargador devolvió 0x8007000D, lo que identificó datos DDS con formato incorrecto. Corregir el encabezado DDS y realizar una implementación completa limpia solucionó el inicio. Para obtener más diagnósticos de inicio, ejecute xbWatson mientras reproduce el error. Consulte también Control de errores.

Paso 14: Itere de forma segura

Para la mayoría de los cambios solo de código:

Compile Debug.
Termine el paquete en ejecución.
Implemente la carpeta de salida completa.
Inicie el AUMID registrado.
Consulte el estado del paquete.

Para los cambios en MicrosoftGameConfig.mgc, los recursos o los metadatos de implementación, desinstale la implementación suelta anterior antes de volver a implementar. Esto evita que archivos o datos de registro obsoletos oculten una corrección.

Opcional: Cree y pruebe un XVC

La implementación suelta es el bucle de desarrollo más rápido. Cree un XVC cuando necesite probar una instalación similar a la comercial o preparar un paquete para Partner Center. Consulte Empaquetado para obtener la referencia completa de empaquetado.

Asocie MicrosoftGame.config a Partner Center

Obtenga estos valores en Game setup > Identity details del producto:

Package Identity Name.
Package Identity Publisher.
Publisher Display Name.
Store ID.
XBOX Title ID.
MSA App ID.

Use marcadores de posición en los ejemplos del control de código fuente. No copie la identidad de otro producto. Para las consolas XBOX Series X|S, la estructura importante es:

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
  <Identity Name="REPLACE-WITH-PACKAGE-IDENTITY-NAME"
            Publisher="REPLACE-WITH-PACKAGE-IDENTITY-PUBLISHER"
            Version="1.0.0.0"/>

  <ExecutableList>
    <Executable Name="sample-game.exe"
                TargetDeviceFamily="Scarlett"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="sample-game"
                PublisherDisplayName="REPLACE-WITH-PUBLISHER-DISPLAY-NAME"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="sample-game"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>

  <MSAAppId>REPLACE-WITH-MSA-APP-ID</MSAAppId>
  <TitleId>REPLACE-WITH-XBOX-TITLE-ID</TitleId>
  <StoreId>REPLACE-WITH-STORE-ID</StoreId>
</Game>

TargetDeviceFamily="Scarlett" es obligatorio para el paquete de las consolas XBOX Series X|S. Use una configuración independiente para un paquete de las consolas de la familia XBOX One.

Compile la configuración Release

msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Release /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal

Prepare el contenido del paquete

Copie la salida de Release en un directorio de almacenamiento provisional, pero mantenga gameos.xvd fuera del mapa de contenido y no incluya los archivos PDB como contenido normal del paquete.

$source  = 'D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release'
$root    = 'D:\repos\sample-game\packages\Scarlett\Release'
$staging = Join-Path $root 'staging'
$output  = Join-Path $root 'output'

Remove-Item $staging, $output -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path $staging, $output -Force | Out-Null

Get-ChildItem $source -Force |
    Where-Object { $_.Name -ne 'gameos.xvd' -and $_.Extension -ne '.pdb' } |
    Copy-Item -Destination $staging -Recurse -Force

Genere el diseño

makepkg genmap /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging"

Para este pequeño ejemplo, el diseño resultante contiene un fragmento de inicio:

<Package>
  <Chunk Id="1000" Marker="Launch">
    <FileGroup DestinationPath="."        SourcePath="."        Include="*.*" />
    <FileGroup DestinationPath=".\Assets" SourcePath=".\Assets" Include="*.*" />
  </Chunk>
</Package>

Cree un paquete de prueba para el kit de desarrollo

El cifrado de prueba predeterminado es útil para la instalación local en el kit de desarrollo:

makepkg pack /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable

Cuando StoreId está presente en MicrosoftGame.config, /productid es innecesario para un envío normal a la Store. Omítalo a menos que un escenario documentado sin conexión o de disco lo requiera específicamente.

Use el cifrado de envío para un paquete de Partner Center

Produzca primero el paquete de sample-game con el cifrado de prueba del kit de desarrollo para poder verificar la instalación y el inicio. Para un paquete que vaya a enviar, siga la directiva de empaquetado actual y use /lk o /l. El flujo de trabajo repetible recomendado con /lk es:

makepkg genkey /ekb D:\secure\sample-game.lekb
makepkg pack /lk D:\secure\sample-game.lekb /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" /pd "D:\repos\sample-game\packages\Scarlett\Release\output" /gameos "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release\gameos.xvd" /symbolpaths "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Release" /validationcritical /loggable

Proteja el LEKB. No lo confirme en el control de código fuente.

Instale e inicie el XVC

xbapp install "<path-to-package>.xvc"
xbapp list
xbapp launch <store-associated-package-family-name>!Game
xbapp query <store-associated-package-full-name>

Termine el paquete cuando finalicen las pruebas:

xbapp terminate <store-associated-package-family-name>!Game

Problemas comunes y soluciones

Síntoma	Causa	Solución
Solo están disponibles las plantillas de Desktop	El GDK público para PC está instalado sin las extensiones de XBOX	Instale GDKX y su integración con Visual Studio desde XBOX Secure Downloads.
El proyecto contiene `Package.appxmanifest` y tiene como destino UWP	Se seleccionó la plantilla de Visual Studio incorrecta	Vuelva a crear el proyecto con Direct3D 12 XBOX Game.
`Gaming.XBOX.Scarlett.x64` no está disponible	Falta la plataforma del GDK de XBOX o la extensión de Visual Studio	Repare o reinstale la versión de GDKX correspondiente y la integración con Visual Studio.
El título se inicia y se cierra inmediatamente	Faltan archivos de implementación o hay un error de inicialización en tiempo de ejecución	Implemente la salida de compilación completa e inspeccione `xbapp lastgamedetails` y `xbdbgmon`.
La carga de DDS devuelve `0x8007000D`	Encabezado DDS con formato incorrecto o datos no compatibles	Regenere el DDS y verifique el encabezado DDS de 148 bytes más DX10.
Un cambio en un recurso no aparece	Implementación suelta obsoleta	Termine, desinstale y vuelva a implementar por completo.
`makepkg` rechaza la configuración	`TargetDeviceFamily` falta o es incorrecto	Establezca `Scarlett` para las consolas XBOX Series X\|S o `XboxOne` para las consolas de la familia XBOX One.
La identidad del producto se proporciona en más de un lugar	Se agregó `/productid` aunque la identidad de la Store ya está en la configuración del juego	Mantenga `StoreId` en la configuración del juego y omita `/productid` para un envío normal a la Store.
Los archivos PDB provocan problemas de mapa de paquete o de validación	Los símbolos se incluyeron como contenido del juego	Excluya los PDB del almacenamiento provisional y pase el directorio de compilación mediante `/symbolpaths`.
El inicio asociado a la Store parece fallar durante el protocolo de enlace	El título puede estar todavía iniciándose o los diagnósticos están incompletos	Inicie con `/WaitToExit`, `/show:all` y `/LogModuleLoads` y, a continuación, consulte el estado del paquete.

Consulte también

Última modificación el 28 de agosto de 2026

Temas relacionados

Desarrollo de un nuevo título de GDK Información general de XBOX Series X|S Configuración de la autenticación de PlayFab con Facebook y Unity Creación de su primer servidor Introducción al empaquetado de títulos para consolas XBOX

⌘I

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Compilación y ejecución de su primer título de consola con GDKX

Lo que va a compilar

Antes de empezar

Paso 1: Cree la carpeta de trabajo

Paso 2: Compruebe la instalación del GDK de XBOX

Paso 3: Cree un proyecto de XBOX nativo

Confirme que el proyecto no es UWP

Paso 4: Fije la edición del GDK y configure los destinos de consola

Paso 5: Compile la plantilla sin modificar

Paso 6: Agregue DirectXTK12 como asistente opcional

Paso 7: Agregue el código del juego

Use un paso de simulación fijo

Implemente la colisión del disco circular

Agregue la reproducción automática predictiva

Represente la escena con DirectXTK12

Mantenga los efectos contenidos

Paso 8: Cree e implemente los recursos de textura

Paso 9: Compile el juego

Paso 10: Conéctese al kit de desarrollo de XBOX

Paso 11: Implemente el juego completo

Paso 12: Inicie y verifique el juego

Paso 13: Diagnostique un error de inicio inmediato

Obtenga el último resultado del título

Supervise la salida de depuración

Paso 14: Itere de forma segura

Opcional: Cree y pruebe un XVC

Asocie MicrosoftGame.config a Partner Center

Compile la configuración Release

Prepare el contenido del paquete

Genere el diseño

Cree un paquete de prueba para el kit de desarrollo

Use el cifrado de envío para un paquete de Partner Center

Instale e inicie el XVC

Problemas comunes y soluciones

Consulte también

​Lo que va a compilar

​Antes de empezar

​Paso 1: Cree la carpeta de trabajo

​Paso 2: Compruebe la instalación del GDK de XBOX

​Paso 3: Cree un proyecto de XBOX nativo

​Confirme que el proyecto no es UWP

​Paso 4: Fije la edición del GDK y configure los destinos de consola

​Paso 5: Compile la plantilla sin modificar

​Paso 6: Agregue DirectXTK12 como asistente opcional

​Paso 7: Agregue el código del juego

​Use un paso de simulación fijo

​Implemente la colisión del disco circular

​Agregue la reproducción automática predictiva

​Represente la escena con DirectXTK12

​Mantenga los efectos contenidos

​Paso 8: Cree e implemente los recursos de textura

​Paso 9: Compile el juego

​Paso 10: Conéctese al kit de desarrollo de XBOX

​Paso 11: Implemente el juego completo

​Paso 12: Inicie y verifique el juego

​Paso 13: Diagnostique un error de inicio inmediato

​Obtenga el último resultado del título

​Supervise la salida de depuración

​Paso 14: Itere de forma segura

​Opcional: Cree y pruebe un XVC

​Asocie MicrosoftGame.config a Partner Center

​Compile la configuración Release

​Prepare el contenido del paquete

​Genere el diseño

​Cree un paquete de prueba para el kit de desarrollo

​Use el cifrado de envío para un paquete de Partner Center

​Instale e inicie el XVC

​Problemas comunes y soluciones

​Consulte también

Lo que va a compilar

Antes de empezar

Paso 1: Cree la carpeta de trabajo

Paso 2: Compruebe la instalación del GDK de XBOX

Paso 3: Cree un proyecto de XBOX nativo

Confirme que el proyecto no es UWP

Paso 4: Fije la edición del GDK y configure los destinos de consola

Paso 5: Compile la plantilla sin modificar

Paso 6: Agregue DirectXTK12 como asistente opcional

Paso 7: Agregue el código del juego

Use un paso de simulación fijo

Implemente la colisión del disco circular

Agregue la reproducción automática predictiva

Represente la escena con DirectXTK12

Mantenga los efectos contenidos

Paso 8: Cree e implemente los recursos de textura

Paso 9: Compile el juego

Paso 10: Conéctese al kit de desarrollo de XBOX

Paso 11: Implemente el juego completo

Paso 12: Inicie y verifique el juego

Paso 13: Diagnostique un error de inicio inmediato

Obtenga el último resultado del título

Supervise la salida de depuración

Paso 14: Itere de forma segura

Opcional: Cree y pruebe un XVC

Asocie MicrosoftGame.config a Partner Center

Compile la configuración Release

Prepare el contenido del paquete

Genere el diseño

Cree un paquete de prueba para el kit de desarrollo

Use el cifrado de envío para un paquete de Partner Center

Instale e inicie el XVC

Problemas comunes y soluciones

Consulte también