Compile e execute seu primeiro título de console com o GDKX

Este passo a passo documenta o processo de ponta a ponta para criar um pequeno título sample-game e compilá-lo para consoles XBOX Series X|S. Em seguida, você implanta o jogo completo em um dev kit XBOX, diagnostica falhas de inicialização e cria um XVC instalável. O exemplo concluído usa C++, Direct3D 12 e o GDK com XBOX Extensions (GDKX). Ele também usa o DirectXTK12 como auxiliar de renderização opcional. As duas raquetes são controladas pelo computador, para que o jogo possa rodar sem supervisão enquanto você itera em gráficos, gameplay e efeitos.

O GDK público disponível pelo GitHub ou WinGet oferece suporte apenas ao desenvolvimento de jogos para Windows PC. Para compilar e implantar um executável de console XBOX, instale o GDK com XBOX Extensions (GDKX) a partir do XBOX Secure Downloads. O acesso exige uma conta de desenvolvedor XBOX aprovada. Consulte Integração com o ID@XBOX e Acessar recursos e downloads do GDK.

O que você vai criar

Ao final deste passo a passo, você terá:

Um projeto nativo do XBOX GDK (não um projeto UWP).
Configurações Debug, Profile e Release para consoles XBOX Series X|S e consoles da família XBOX One.
Um jogo de exemplo em autoplay com pontuação, IA preditiva de raquete, efeitos de partículas, um rastro de movimento e um disco circular texturizado.
Uma implantação completa de arquivos soltos (loose) em execução em um dev kit XBOX.
Um XVC opcional associado à Store que pode ser instalado e testado no dev kit.

Antes de começar

Este passo a passo foi validado com:

Visual Studio 2022 Enterprise 17.14.
GDKX April 2026 Update 2, edição 260402.
Gaming.XBOX.Scarlett.x64 para consoles XBOX Series X|S.
Gaming.XBOX.XboxOne.x64 para consoles da família XBOX One.
DirectXTK12 commit e656d54637b2830fc6eb5ecd9b329a9c72cb87d4.

Use a edição do GDK instalada no seu PC de desenvolvimento em vez de 260402 se você estiver seguindo o passo a passo com outra versão.

Etapa 1: Crie a pasta de trabalho

Abra o PowerShell e crie uma pasta raiz vazia.

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

O layout final do projeto usado neste passo a passo é:

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

O Visual Studio cria DeviceResources.*, Main.cpp, pch.*, StepTimer.h e os arquivos PNG visuais do shell a partir do modelo Direct3D 12 XBOX Game. Mantenha esses arquivos gerados ao adicionar o código-fonte específico do exemplo.

Etapa 2: Verifique a instalação do XBOX GDK

Abra o XBOX Series X|S VS 2022 Gaming Command Prompt instalado com o GDKX. O atalho normalmente fica em Microsoft GDK no menu Iniciar. Você também pode inicializar o ambiente a partir de um prompt de comando comum:

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

Verifique se as ferramentas de build e implantação do XBOX estão disponíveis:

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

A instalação do GDK não está pronta para desenvolvimento de console se:

GXDKEDITION estiver vazio.
O atalho do prompt de comando do XBOX estiver ausente.
O Visual Studio não mostrar modelos de projeto XBOX.
A plataforma MSBuild Gaming.XBOX.Scarlett.x64 não estiver disponível.
xbconnect ou xbapp não puderem ser encontrados.

Se apenas os prompts de comando do Desktop GDK e os modelos Desktop estiverem disponíveis, provavelmente o GDK público de PC está instalado em vez do GDKX.

Etapa 3: Crie um projeto XBOX nativo

Abra o Visual Studio 2022 e selecione Create a new project

Defina Language como C++, Platform como XBOX e Project type como Games.

Selecione Direct3D 12 XBOX Game

Defina o nome do projeto como sample-game e o local como D:\repos\sample-game.

Deixe Place solution and project in the same directory desmarcado

Assim, a solução fica na raiz e o projeto em D:\repos\sample-game\sample-game.

Crie o projeto

O fluxo de trabalho com suporte é criar o projeto pelo Visual Studio. Copiar manualmente os arquivos do modelo d3d12game_gx é uma técnica de recuperação, não o fluxo recomendado para um novo projeto.

Confirme que o projeto não é UWP

Antes de adicionar o código do jogo, verifique se o projeto:

Contém MicrosoftGameConfig.mgc.
Usa uma plataforma de projeto Gaming.XBOX.*.x64.
Faz o link com as bibliotecas de plataforma do XBOX GDK.
Não usa Package.appxmanifest como configuração do título.
Foi criado a partir de Direct3D 12 XBOX Game, não de um modelo Universal Windows.

Se o projeto for UWP, exclua-o e crie um novo projeto a partir do modelo do XBOX GDK. Converter o projeto UWP gerado é mais propenso a erros do que começar com o modelo correto.

Etapa 4: Fixe a edição do GDK e configure os alvos de console

Fixar a edição do GDK impede que uma instalação futura do GDK altere silenciosamente a cadeia de ferramentas usada pelo projeto. No grupo de propriedades principal em sample-game.vcxproj, defina:

<XdkEditionTarget>260402</XdkEditionTarget>

Use o Configuration Manager do Visual Studio para confirmar estas configurações da solução:

Configuração	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`

Se o título oferecer suporte apenas a consoles XBOX Series X|S, você pode omitir as configurações dos consoles da família XBOX One. Consulte Cross-gen para lançar o mesmo título em várias gerações.

Etapa 5: Compile o modelo sem modificações

Compile o modelo gerado antes de adicionar dependências ou código do jogo. Isso isola problemas da cadeia de ferramentas de problemas introduzidos pelo exemplo. A partir de um 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 consoles da família XBOX One, inicialize o ambiente de comando do XBOX One e compile a plataforma 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

Não continue até que o modelo padrão do XBOX seja compilado com sucesso.

Etapa 6: Adicione o DirectXTK12 como auxiliar opcional

O DirectXTK12 não é obrigatório para criar um título GDK. O modelo do XBOX GDK já fornece o dispositivo Direct3D 12, a fila de comandos, a swap chain e o loop de jogo necessários para compilar um jogo diretamente com o Direct3D 12. Este exemplo usa a biblioteca separada de código aberto da Microsoft DirectXTK12. A biblioteca reduz a quantidade de código utilitário de renderização de baixo nível necessário para renderização de sprites, gerenciamento de descritores, carregamento de texturas, upload de recursos e gerenciamento de memória gráfica. Um título pode substituir esses auxiliares por sua própria engine ou por uma implementação direta em D3D12. Clone o DirectXTK12 dentro do projeto:

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

No Visual Studio:

Adicione external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj à solução.
Adicione o DirectXTK12 como referência de projeto a partir de sample-game.
Adicione $(SolutionDir)external\DirectXTK12\Inc aos diretórios de include.
Compile ambos os projetos para a mesma plataforma e configuração XBOX.

O projeto sample-game usa esta propriedade:

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

Em seguida, ele adiciona o caminho de include e a referência de projeto:

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

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

Neste projeto, os comandos de build de shaders do DirectXTK12 foram alterados para invocar CompileShaders.cmd por meio de um caminho explícito relativo ao projeto:

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

Isso evita depender do diretório de comando atual quando o MSBuild invoca o compilador de shaders.

Etapa 7: Adicione o código do jogo

O exemplo separa o estado de gameplay da renderização para que a simulação possa ser ajustada sem alterar o código Direct3D. Mantenha os arquivos gerados pelo modelo, incluindo DeviceResources.*, Main.cpp, pch.*, StepTimer.h e os cinco arquivos PNG visuais do shell. Adicione ao projeto estes arquivos específicos do exemplo:

Arquivo	Finalidade
`GameTuning.h`	Constantes de arena, raquete, disco, IA, rastro e partículas.
`sample-gameSimulation.h/.cpp`	Movimento do disco, movimento das raquetes, colisão, pontuação, saque e IA.
`ParticleSystem.h/.cpp`	Pool de partículas de tamanho fixo e emissores de impacto.
`Game.h/.cpp`	Recursos do DirectXTK12, atualização do jogo e renderização.
`tools\BuildAssets.ps1`	Geração reproduzível de DDS para o sprite branco e o disco.

Use um passo de simulação fixo

O projeto usa o StepTimer do modelo com uma atualização fixa de 120 Hz. Um passo fixo mantém a resposta de colisão e o comportamento da IA estáveis quando os tempos de quadro variam. A simulação contém:

Dois estados de raquete.
Um estado de disco circular.
Pontuações para os lados esquerdo e direito.
Um atraso de saque e direção de saque alternada.
Eventos de impacto para colisões com raquete, parede e gol.

Implemente a colisão do disco circular

Trate cada raquete como um retângulo alinhado aos eixos e o disco como um círculo:

Encontre o ponto do retângulo da raquete mais próximo do centro do disco.
Meça a distância ao quadrado desse ponto até o centro do disco.
Ocorreu uma colisão se a distância não for maior que o raio do disco ao quadrado.
Mova o disco para fora da raquete para evitar sobreposições repetidas.
Calcule o ângulo de saída a partir do deslocamento do impacto e da velocidade da raquete.
Aumente ligeiramente a velocidade do disco, até um máximo.

Isso mantém a física circular mesmo que o disco seja desenhado a partir de uma textura quadrada.

Adicione autoplay preditivo

Cada raquete:

Prevê onde o disco cruzará sua posição horizontal.
Reflete a coordenada prevista nas paredes superior e inferior da arena.
Atualiza seu alvo em um intervalo de reação fixo.
Usa limites de aceleração e velocidade máxima em vez de saltar diretamente.
Adiciona um pequeno erro de mira determinístico.

Para permitir que haja pontuação, cada lado ocasionalmente entra em uma curta janela de erro e se move deliberadamente para longe do ponto de interceptação previsto. Escalone os temporizadores de erro iniciais para que as duas raquetes não errem simultaneamente.

Renderize a cena com o DirectXTK12

Crie:

GraphicsMemory.
Um heap de descritores contendo uma textura branca e a textura do disco.
Um SpriteBatch com alfa normal.
Um SpriteBatch aditivo para as partículas.
Texturas DDS por meio de ResourceUploadBatch e CreateDDSTextureFromFile.

Desenhe a arena, a linha central, as raquetes, a pontuação, o rastro do disco e o disco com SpriteBatch. Desenhe as partículas na passada aditiva. O exemplo concluído renderiza em um sistema de coordenadas virtual de 1920 por 1080 e dimensiona essa cena para o viewport de saída.

Mantenha os efeitos contidos

O ajuste final usou:

Um tremor de tela curto, com decaimento exponencial.
Partículas de impacto menores em formato de risco.
Mais partículas em impactos de raquete do que em impactos de parede.
Uma explosão mais forte para um gol.
Um rastro do disco com alfa baixo.
Um breve flash verde de impacto.

Essas mudanças preservaram o feedback de impacto sem fazer o jogo parecer caricato ou tornar as colisões com a raquete visualmente incômodas.

Etapa 8: Crie e implante os assets de textura

O exemplo precisa de:

Assets\white.dds: uma textura RGBA branca de 1 por 1 usada para desenhar retângulos e partículas.
Assets\xbox_logo.dds: uma textura RGBA de 256 por 256 usada para o disco.

O script de assets:

Carrega o logotipo de origem.
Redimensiona-o para 256 por 256.
Aplica uma máscara de alfa circular com bordas suavizadas.
Grava um DDS RGBA8 com cabeçalho DX10.
Cria o DDS branco de 1 por 1.

Execute-o a partir do PowerShell:

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

Registre ambos os arquivos DDS como conteúdo de implantação em 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>

Um arquivo DDS que usa o cabeçalho padrão mais a extensão DX10 tem 148 bytes antes dos dados de pixels. Durante a sessão original, um gravador de DDS personalizado emitiu 152 bytes e o título falhou durante o carregamento de textura com 0x8007000D. Se você usar um gravador de DDS personalizado, valide o layout do cabeçalho antes da implantação.

Etapa 9: Compile o jogo

A partir do 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

A saída da build solta (loose) é:

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

Confirme que a saída contém:

sample-game.exe
MicrosoftGame.config
Os arquivos PNG visuais do shell
Assets\white.dds
Assets\xbox_logo.dds
As DLLs de runtime necessárias
A imagem do Game OS ou outros metadados de implantação produzidos pela build

O código-fonte do projeto se chama MicrosoftGameConfig.mgc. O item de build MGCCompile do GDK o valida e emite MicrosoftGame.config na saída da build. A implantação e o empacotamento usam o arquivo .config gerado. Consulte Game config.

Etapa 10: Conecte-se ao dev kit XBOX

Defina o console padrão usando o endereço IP de Ferramentas (Tools IP) ou o nome do host:

xbconnect <console-address>

Verifique o console armazenado:

xbconnect /B

Execute diagnósticos de conexão:

xbconnect /DX

Se o título usar um sandbox do Partner Center, configure o ID do sandbox (que diferencia maiúsculas de minúsculas) e reinicie o console:

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

Exiba o sandbox atual:

xbconfig sandboxid

Etapa 11: Implante o jogo completo

Implante toda a pasta de saída da build:

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

Não copie apenas sample-game.exe. O título também precisa de MicrosoftGame.config, assets, dependências de runtime, imagens do shell e metadados de implantação. Uma cópia apenas do executável não é uma implantação completa válida.

Para uma reimplantação limpa após alterar assets ou configuração:

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 após a implantação para encontrar o nome completo do pacote registrado e o application user model ID (AUMID). O AUMID termina com !Game.

Etapa 12: Inicie e verifique o jogo

Inicie exatamente o AUMID informado por xbapp list:

xbapp launch <package-family-name>!Game

Aguarde o processo do título:

xbconnect /WTP:60

Verifique se o pacote está em execução:

xbapp query <package-full-name>

O resultado esperado é:

Package execution state: 1 (running)

Neste ponto, a partida em autoplay deve estar visível no dev kit.

Etapa 13: Diagnostique uma falha imediata na inicialização

Se o jogo sair imediatamente, não presuma que a implantação foi bem-sucedida só porque o executável foi copiado.

Obtenha o último resultado do título

xbapp lastgamedetails

Monitore a saída de depuração

Inicie um monitor de saída de depuração em um prompt de comando:

xbdbgmon /t /v

Inicie o jogo a partir de outro:

xbapp launch <package-family-name>!Game

O exemplo adicionou mensagens OutputDebugStringA em torno de:

Inicialização do jogo.
Criação de recursos do DirectXTK12.
Cada carregamento de textura.
Criação do pipeline de sprites.
Conclusão do upload de texturas.
Exceções de quadro.

A sessão original isolou a falha de inicialização no carregamento de white.dds. O carregador retornou 0x8007000D, o que identificou dados DDS malformados. Corrigir o cabeçalho DDS e realizar uma implantação completa limpa resolveu a inicialização. Para mais diagnósticos de inicialização, execute o xbWatson enquanto reproduz a falha. Consulte também Tratamento de erros.

Etapa 14: Itere com segurança

Para a maioria das alterações somente de código:

Compile o Debug.
Encerre o pacote em execução.
Implante a pasta de saída completa.
Inicie o AUMID registrado.
Consulte o estado do pacote.

Para alterações em MicrosoftGameConfig.mgc, assets ou metadados de implantação, desinstale a implantação solta antiga antes de implantar novamente. Isso evita que arquivos ou dados de registro obsoletos escondam uma correção.

Opcional: Crie e teste um XVC

A implantação solta (loose) é o ciclo de desenvolvimento mais rápido. Crie um XVC quando precisar testar uma instalação semelhante à de varejo ou preparar um pacote para o Partner Center. Consulte Empacotamento para a referência completa de empacotamento.

Associe o MicrosoftGame.config ao Partner Center

Obtenha estes valores em Game setup > Identity details do produto:

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

Use espaços reservados em exemplos no controle de origem. Não copie a identidade de outro produto. Para consoles XBOX Series X|S, a estrutura importante é:

<?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" é obrigatório para o pacote de consoles XBOX Series X|S. Use uma configuração separada para um pacote de consoles da família XBOX One.

Compile a configuração Release

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

Prepare o conteúdo do pacote (staging)

Copie a saída Release para um diretório de staging, mas mantenha gameos.xvd fora do mapa de conteúdo e não inclua arquivos PDB como conteúdo comum do pacote.

$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

Gere o layout

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

Para este pequeno exemplo, o layout resultante contém um único chunk de inicialização:

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

Crie um pacote de teste para dev kit

A criptografia de teste padrão é útil para instalação local no dev kit:

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

Quando StoreId está presente em MicrosoftGame.config, /productid é desnecessário para um envio normal à Store. Omita-o, a menos que um cenário documentado de disco ou offline o exija especificamente.

Use criptografia de envio para um pacote do Partner Center

Produza primeiro o pacote do sample-game com a criptografia de teste do dev kit para poder verificar a instalação e a inicialização. Para um pacote que você vai enviar, siga a política de empacotamento vigente e use /lk ou /l. O fluxo de trabalho /lk repetível recomendado é:

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 o LEKB. Não o envie ao controle de origem.

Instale e inicie o XVC

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

Encerre o pacote quando o teste estiver concluído:

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

Problemas comuns e correções

Sintoma	Causa	Correção
Apenas os modelos Desktop estão disponíveis	O GDK público de PC está instalado sem as XBOX Extensions	Instale o GDKX e sua integração com o Visual Studio a partir do XBOX Secure Downloads.
O projeto contém `Package.appxmanifest` e tem como alvo UWP	O modelo errado do Visual Studio foi selecionado	Recrie o projeto com Direct3D 12 XBOX Game.
`Gaming.XBOX.Scarlett.x64` não está disponível	A plataforma do XBOX GDK ou a extensão do Visual Studio está ausente	Repare ou reinstale a versão correspondente do GDKX e a integração com o Visual Studio.
O título inicia e sai imediatamente	Arquivos de implantação ausentes ou falha na inicialização do runtime	Implante a saída completa da build e inspecione `xbapp lastgamedetails` e `xbdbgmon`.
O carregamento de DDS retorna `0x8007000D`	Cabeçalho DDS malformado ou dados sem suporte	Gere o DDS novamente e verifique o cabeçalho DDS de 148 bytes mais DX10.
Uma alteração de asset não aparece	Implantação solta obsoleta	Encerre, desinstale e implante novamente por completo.
`makepkg` rejeita a configuração	`TargetDeviceFamily` ausente ou incorreto	Defina `Scarlett` para consoles XBOX Series X\|S ou `XboxOne` para consoles da família XBOX One.
A identidade do produto está sendo fornecida em mais de um lugar	`/productid` foi adicionado mesmo com a identidade da Store já presente na configuração do jogo	Mantenha `StoreId` na configuração do jogo e omita `/productid` para um envio normal à Store.
Arquivos PDB causam problemas de mapa de pacote ou validação	Os símbolos foram incluídos como conteúdo do jogo	Exclua os PDBs do staging e passe o diretório de build por meio de `/symbolpaths`.
A inicialização associada à Store parece falhar durante o handshake	O título ainda pode estar iniciando, ou os diagnósticos estão incompletos	Inicie com `/WaitToExit`, `/show:all` e `/LogModuleLoads` e, em seguida, consulte o estado do pacote.

Consulte também

Última modificação em 1 de setembro de 2026

Tópicos relacionados

Desenvolva um novo título GDK Visão geral do XBOX Series X|S Documentação de desenvolvimento de jogos XBOX Exemplos do GDK Configure e instale o GDK

⌘I

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Compile e execute seu primeiro título de console com o GDKX

O que você vai criar

Antes de começar

Etapa 1: Crie a pasta de trabalho

Etapa 2: Verifique a instalação do XBOX GDK

Etapa 3: Crie um projeto XBOX nativo

Confirme que o projeto não é UWP

Etapa 4: Fixe a edição do GDK e configure os alvos de console

Etapa 5: Compile o modelo sem modificações

Etapa 6: Adicione o DirectXTK12 como auxiliar opcional

Etapa 7: Adicione o código do jogo

Use um passo de simulação fixo

Implemente a colisão do disco circular

Adicione autoplay preditivo

Renderize a cena com o DirectXTK12

Mantenha os efeitos contidos

Etapa 8: Crie e implante os assets de textura

Etapa 9: Compile o jogo

Etapa 10: Conecte-se ao dev kit XBOX

Etapa 11: Implante o jogo completo

Etapa 12: Inicie e verifique o jogo

Etapa 13: Diagnostique uma falha imediata na inicialização

Obtenha o último resultado do título

Monitore a saída de depuração

Etapa 14: Itere com segurança

Opcional: Crie e teste um XVC

Associe o MicrosoftGame.config ao Partner Center

Compile a configuração Release

Prepare o conteúdo do pacote (staging)

Gere o layout

Crie um pacote de teste para dev kit

Use criptografia de envio para um pacote do Partner Center

Instale e inicie o XVC

Problemas comuns e correções

Consulte também

​O que você vai criar

​Antes de começar

​Etapa 1: Crie a pasta de trabalho

​Etapa 2: Verifique a instalação do XBOX GDK

​Etapa 3: Crie um projeto XBOX nativo

​Confirme que o projeto não é UWP

​Etapa 4: Fixe a edição do GDK e configure os alvos de console

​Etapa 5: Compile o modelo sem modificações

​Etapa 6: Adicione o DirectXTK12 como auxiliar opcional

​Etapa 7: Adicione o código do jogo

​Use um passo de simulação fixo

​Implemente a colisão do disco circular

​Adicione autoplay preditivo

​Renderize a cena com o DirectXTK12

​Mantenha os efeitos contidos

​Etapa 8: Crie e implante os assets de textura

​Etapa 9: Compile o jogo

​Etapa 10: Conecte-se ao dev kit XBOX

​Etapa 11: Implante o jogo completo

​Etapa 12: Inicie e verifique o jogo

​Etapa 13: Diagnostique uma falha imediata na inicialização

​Obtenha o último resultado do título

​Monitore a saída de depuração

​Etapa 14: Itere com segurança

​Opcional: Crie e teste um XVC

​Associe o MicrosoftGame.config ao Partner Center

​Compile a configuração Release

​Prepare o conteúdo do pacote (staging)

​Gere o layout

​Crie um pacote de teste para dev kit

​Use criptografia de envio para um pacote do Partner Center

​Instale e inicie o XVC

​Problemas comuns e correções

​Consulte também

O que você vai criar

Antes de começar

Etapa 1: Crie a pasta de trabalho

Etapa 2: Verifique a instalação do XBOX GDK

Etapa 3: Crie um projeto XBOX nativo

Confirme que o projeto não é UWP

Etapa 4: Fixe a edição do GDK e configure os alvos de console

Etapa 5: Compile o modelo sem modificações

Etapa 6: Adicione o DirectXTK12 como auxiliar opcional

Etapa 7: Adicione o código do jogo

Use um passo de simulação fixo

Implemente a colisão do disco circular

Adicione autoplay preditivo

Renderize a cena com o DirectXTK12

Mantenha os efeitos contidos

Etapa 8: Crie e implante os assets de textura

Etapa 9: Compile o jogo

Etapa 10: Conecte-se ao dev kit XBOX

Etapa 11: Implante o jogo completo

Etapa 12: Inicie e verifique o jogo

Etapa 13: Diagnostique uma falha imediata na inicialização

Obtenha o último resultado do título

Monitore a saída de depuração

Etapa 14: Itere com segurança

Opcional: Crie e teste um XVC

Associe o MicrosoftGame.config ao Partner Center

Compile a configuração Release

Prepare o conteúdo do pacote (staging)

Gere o layout

Crie um pacote de teste para dev kit

Use criptografia de envio para um pacote do Partner Center

Instale e inicie o XVC

Problemas comuns e correções

Consulte também