Compiler et exécuter votre premier titre console avec le GDKX

Ce tutoriel documente le processus de bout en bout pour créer un petit titre sample-game et le compiler pour les consoles XBOX Series X|S. Vous déployez ensuite le jeu complet sur un kit de développement XBOX, diagnostiquez les échecs de démarrage et créez un XVC installable. L’exemple terminé utilise C++, Direct3D 12 et le GDK avec les extensions XBOX (GDKX). Il utilise aussi DirectXTK12 comme utilitaire de rendu facultatif. Les deux palettes sont contrôlées par l’ordinateur, de sorte que le jeu peut fonctionner sans surveillance pendant que vous itérez sur les graphismes, la jouabilité et les effets.

Le GDK public offert sur GitHub ou via WinGet prend en charge uniquement le développement de jeux pour Windows PC. Pour compiler et déployer un exécutable pour console XBOX, installez le GDK avec les extensions XBOX (GDKX) depuis XBOX Secure Downloads. L’accès nécessite un compte de développeur XBOX approuvé. Voir Intégration ID@XBOX et Accéder aux ressources et téléchargements du GDK.

Ce que vous allez créer

À la fin de ce tutoriel, vous aurez :

Un projet XBOX GDK natif (pas un projet UWP).
Des configurations Debug, Profile et Release pour les consoles XBOX Series X|S et les consoles de la famille XBOX One.
Un exemple de jeu en lecture automatique avec pointage, IA prédictive des palettes, effets de particules, traînée de mouvement et rondelle circulaire texturée.
Un déploiement complet de fichiers non empaquetés en cours d’exécution sur un kit de développement XBOX.
Un XVC facultatif associé au Store, pouvant être installé et testé sur le kit de développement.

Avant de commencer

Ce tutoriel a été validé avec :

Visual Studio 2022 Enterprise 17.14.
GDKX April 2026 Update 2, édition 260402.
Gaming.XBOX.Scarlett.x64 pour les consoles XBOX Series X|S.
Gaming.XBOX.XboxOne.x64 pour les consoles de la famille XBOX One.
DirectXTK12, commit e656d54637b2830fc6eb5ecd9b329a9c72cb87d4.

Utilisez l’édition du GDK installée sur votre PC de développement au lieu de 260402 si vous suivez le tutoriel avec une autre version.

Étape 1 : Créer le dossier de travail

Ouvrez PowerShell et créez un dossier racine vide.

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

La structure finale du projet utilisée dans ce tutoriel est :

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 crée DeviceResources.*, Main.cpp, pch.*, StepTimer.h et les fichiers PNG visuels de l’interface à partir du modèle Direct3D 12 XBOX Game. Conservez ces fichiers générés lorsque vous ajoutez le code source propre à l’exemple.

Étape 2 : Vérifier l’installation du XBOX GDK

Ouvrez l’invite XBOX Series X|S VS 2022 Gaming Command Prompt installée avec le GDKX. Le raccourci se trouve normalement sous Microsoft GDK dans le menu Démarrer. Vous pouvez aussi initialiser l’environnement à partir d’une invite de commandes ordinaire :

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

Vérifiez que les outils de compilation et de déploiement XBOX sont disponibles :

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

L’installation du GDK n’est pas prête pour le développement sur console si :

GXDKEDITION est vide.
Le raccourci de l’invite de commandes XBOX est manquant.
Visual Studio n’affiche pas les modèles de projet XBOX.
La plateforme MSBuild Gaming.XBOX.Scarlett.x64 n’est pas disponible.
xbconnect ou xbapp sont introuvables.

Si seules les invites de commandes Desktop du GDK et les modèles Desktop sont disponibles, c’est probablement le GDK PC public qui est installé au lieu du GDKX.

Étape 3 : Créer un projet XBOX natif

Ouvrir Visual Studio 2022 et sélectionner Create a new project

Définissez Language à C++, Platform à XBOX et Project type à Games.

Sélectionner Direct3D 12 XBOX Game

Définissez le nom du projet à sample-game et l’emplacement à D:\repos\sample-game.

Laisser Place solution and project in the same directory décochée

Ainsi, la solution se trouve à la racine et le projet dans D:\repos\sample-game\sample-game.

Créer le projet

Le flux de travail pris en charge consiste à créer le projet dans Visual Studio. La copie manuelle des fichiers du modèle d3d12game_gx est une technique de récupération, pas le flux de travail recommandé pour un nouveau projet.

Confirmer que le projet n’est pas UWP

Avant d’ajouter le code du jeu, vérifiez que le projet :

Contient MicrosoftGameConfig.mgc.
Utilise une plateforme de projet Gaming.XBOX.*.x64.
Se lie aux bibliothèques de plateforme du XBOX GDK.
N’utilise pas Package.appxmanifest comme configuration du titre.
A été créé à partir de Direct3D 12 XBOX Game, et non d’un modèle Universal Windows.

Si le projet est UWP, supprimez-le et créez un nouveau projet à partir du modèle XBOX GDK. La conversion du projet UWP généré est plus sujette aux erreurs que de repartir du bon modèle.

Étape 4 : Figer l’édition du GDK et configurer les cibles console

Figer l’édition du GDK empêche une future installation du GDK de modifier silencieusement la chaîne d’outils utilisée par le projet. Dans le groupe de propriétés principal de sample-game.vcxproj, définissez :

<XdkEditionTarget>260402</XdkEditionTarget>

Utilisez le Configuration Manager de Visual Studio pour confirmer ces configurations de solution :

Configuration	Plateforme
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 le titre ne prend en charge que les consoles XBOX Series X|S, vous pouvez omettre les configurations des consoles de la famille XBOX One. Voir Intergénérationnel pour livrer le même titre sur plusieurs générations.

Étape 5 : Compiler le modèle non modifié

Compilez le modèle généré avant d’ajouter des dépendances ou le code du jeu. Cela permet d’isoler les problèmes de chaîne d’outils des problèmes introduits par l’exemple. Depuis une invite 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

Pour les consoles de la famille XBOX One, initialisez l’environnement de commandes XBOX One et compilez la plateforme 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

Ne continuez pas tant que le modèle XBOX d’origine ne compile pas avec succès.

Étape 6 : Ajouter DirectXTK12 comme utilitaire facultatif

DirectXTK12 n’est pas requis pour créer un titre GDK. Le modèle XBOX GDK fournit déjà le périphérique Direct3D 12, la file de commandes, la chaîne d’échange et la boucle de jeu nécessaires pour créer un jeu directement avec Direct3D 12. Cet exemple utilise la bibliothèque libre distincte DirectXTK12 de Microsoft. La bibliothèque réduit la quantité de code utilitaire de rendu de bas niveau requis pour le rendu des lutins (sprites), la gestion des descripteurs, le chargement des textures, le téléversement des ressources et la gestion de la mémoire graphique. Un titre peut remplacer ces utilitaires par son propre moteur ou par une implémentation D3D12 directe. Clonez DirectXTK12 dans le projet :

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

Dans Visual Studio :

Ajoutez external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj à la solution.
Ajoutez DirectXTK12 comme référence de projet depuis sample-game.
Ajoutez $(SolutionDir)external\DirectXTK12\Inc aux répertoires d’inclusion.
Compilez les deux projets pour la même plateforme et la même configuration XBOX.

Le projet sample-game utilise cette propriété :

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

Il ajoute ensuite le chemin d’inclusion et la référence de projet :

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

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

Dans ce projet, les commandes de compilation des nuanceurs de DirectXTK12 ont été modifiées pour invoquer CompileShaders.cmd par un chemin explicite relatif au projet :

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

Cela évite de dépendre du répertoire de commande courant lorsque MSBuild invoque le compilateur de nuanceurs.

Étape 7 : Ajouter le code du jeu

L’exemple sépare l’état de la jouabilité du rendu afin que la simulation puisse être ajustée sans modifier le code Direct3D. Conservez les fichiers générés par le modèle, y compris DeviceResources.*, Main.cpp, pch.*, StepTimer.h et les cinq fichiers PNG visuels de l’interface. Ajoutez ces fichiers propres à l’exemple au projet :

Fichier	Rôle
`GameTuning.h`	Constantes de l’arène, des palettes, de la rondelle, de l’IA, de la traînée et des particules.
`sample-gameSimulation.h/.cpp`	Mouvement de la rondelle, mouvement des palettes, collisions, pointage, mise au jeu et IA.
`ParticleSystem.h/.cpp`	Réserve de particules de taille fixe et émetteurs d’impact.
`Game.h/.cpp`	Ressources DirectXTK12, mise à jour du jeu et rendu.
`tools\BuildAssets.ps1`	Génération reproductible des DDS pour le lutin blanc et la rondelle.

Utiliser un pas de simulation fixe

Le projet utilise le StepTimer du modèle avec une mise à jour fixe à 120 Hz. Un pas fixe maintient la stabilité de la réponse aux collisions et du comportement de l’IA lorsque les temps de trame varient. La simulation contient :

Deux états de palette.
Un état de rondelle circulaire.
Les pointages des côtés gauche et droit.
Un délai de mise au jeu et une direction de mise au jeu alternée.
Des événements d’impact pour les collisions avec les palettes, les murs et les buts.

Implémenter la collision d’une rondelle circulaire

Traitez chaque palette comme un rectangle aligné sur les axes et la rondelle comme un cercle :

Trouvez le point du rectangle de la palette le plus proche du centre de la rondelle.
Mesurez la distance au carré entre ce point et le centre de la rondelle.
Une collision s’est produite si la distance n’est pas supérieure au rayon de la rondelle au carré.
Déplacez la rondelle hors de la palette pour éviter les chevauchements répétés.
Calculez l’angle de sortie à partir du décalage d’impact et de la vitesse de la palette.
Augmentez légèrement la vitesse de la rondelle, jusqu’à un maximum.

Cela maintient une physique circulaire même si la rondelle est dessinée à partir d’une texture carrée.

Ajouter une lecture automatique prédictive

Chaque palette :

Prédit l’endroit où la rondelle croisera sa position horizontale.
Réfléchit la coordonnée prédite sur les murs supérieur et inférieur de l’arène.
Met à jour sa cible à un intervalle de réaction fixe.
Utilise des limites d’accélération et de vitesse maximale plutôt qu’un positionnement instantané.
Ajoute une petite erreur de ciblage déterministe.

Pour permettre à des parties de se conclure par des buts, chaque côté entre occasionnellement dans une courte fenêtre d’erreur et s’éloigne délibérément de l’interception prédite. Décalez les minuteries d’erreur initiales pour que les deux palettes ne ratent pas simultanément.

Faire le rendu de la scène avec DirectXTK12

Créez :

GraphicsMemory.
Un tas de descripteurs contenant une texture blanche et la texture de la rondelle.
Un SpriteBatch en alpha normal.
Un SpriteBatch additif pour les particules.
Des textures DDS par l’intermédiaire de ResourceUploadBatch et CreateDDSTextureFromFile.

Dessinez l’arène, la ligne centrale, les palettes, le pointage, la traînée de la rondelle et la rondelle avec SpriteBatch. Dessinez les particules dans la passe additive. L’exemple terminé effectue le rendu dans un système de coordonnées virtuel de 1920 par 1080 et met cette scène à l’échelle de la fenêtre d’affichage de sortie.

Garder des effets sobres

L’ajustement final utilisait :

Une courte secousse d’écran à décroissance exponentielle.
Des particules d’impact plus petites en forme de traînées.
Plus de particules lors des impacts sur les palettes que sur les murs.
Une explosion plus marquée pour un but.
Une traînée de rondelle à faible alpha.
Un bref éclair d’impact vert.

Ces changements ont préservé la rétroaction d’impact sans donner au jeu une apparence caricaturale ni rendre les collisions avec les palettes visuellement dérangeantes.

Étape 8 : Créer et déployer les ressources de texture

L’exemple a besoin de :

Assets\white.dds : une texture RGBA blanche de 1 par 1 utilisée pour dessiner les rectangles et les particules.
Assets\xbox_logo.dds : une texture RGBA de 256 par 256 utilisée pour la rondelle.

Le script de ressources :

Charge le logo source.
Le redimensionne à 256 par 256.
Applique un masque alpha circulaire adouci.
Écrit un DDS RGBA8 avec un en-tête DX10.
Crée le DDS blanc de 1 par 1.

Exécutez-le depuis PowerShell :

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

Inscrivez les deux fichiers DDS comme contenu de déploiement dans 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 fichier DDS utilisant l’en-tête standard plus une extension DX10 comporte 148 octets avant les données de pixels. Durant la session originale, un rédacteur DDS personnalisé a émis 152 octets et le titre a échoué au chargement des textures avec 0x8007000D. Si vous utilisez un rédacteur DDS personnalisé, validez la disposition de l’en-tête avant le déploiement.

Étape 9 : Compiler le jeu

Depuis l’invite 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 sortie de la build non empaquetée est :

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

Confirmez que la sortie contient :

sample-game.exe
MicrosoftGame.config
Les fichiers PNG visuels de l’interface
Assets\white.dds
Assets\xbox_logo.dds
Les DLL d’exécution requises
L’image Game OS ou les autres métadonnées de déploiement produites par la build

Le fichier source du projet se nomme MicrosoftGameConfig.mgc. L’élément de build MGCCompile du GDK le valide et émet MicrosoftGame.config dans la sortie de la build. Le déploiement et l’empaquetage utilisent tous deux le fichier .config généré. Voir Configuration du jeu.

Étape 10 : Se connecter au kit de développement XBOX

Définissez la console par défaut à l’aide de son adresse IP Tools ou de son nom d’hôte :

xbconnect <console-address>

Vérifiez la console enregistrée :

xbconnect /B

Exécutez le diagnostic de connexion :

xbconnect /DX

Si le titre utilise un sandbox de Partner Center, configurez l’identifiant de sandbox (sensible à la casse) et redémarrez la console :

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

Affichez le sandbox actuel :

xbconfig sandboxid

Étape 11 : Déployer le jeu complet

Déployez le dossier de sortie de build en entier :

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

Ne copiez pas uniquement sample-game.exe. Le titre a aussi besoin de MicrosoftGame.config, des ressources, des dépendances d’exécution, des images de l’interface et des métadonnées de déploiement. Une copie limitée à l’exécutable n’est pas un déploiement complet valide.

Pour un redéploiement propre après un changement de ressources ou de configuration :

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"

Utilisez xbapp list après le déploiement pour trouver le nom complet du paquet inscrit et l’identifiant de modèle utilisateur d’application (AUMID). L’AUMID se termine par !Game.

Étape 12 : Lancer et vérifier le jeu

Lancez l’AUMID exact rapporté par xbapp list :

xbapp launch <package-family-name>!Game

Attendez le processus du titre :

xbconnect /WTP:60

Vérifiez que le paquet est en cours d’exécution :

xbapp query <package-full-name>

Le résultat attendu est :

Package execution state: 1 (running)

À ce stade, la partie en lecture automatique devrait être visible sur le kit de développement.

Étape 13 : Diagnostiquer un échec de lancement immédiat

Si le jeu se ferme immédiatement, ne présumez pas que le déploiement a réussi parce que l’exécutable a été copié.

Obtenir le dernier résultat du titre

xbapp lastgamedetails

Surveiller la sortie de débogage

Démarrez un moniteur de sortie de débogage dans une invite de commandes :

xbdbgmon /t /v

Lancez le jeu depuis une autre :

xbapp launch <package-family-name>!Game

L’exemple ajoutait des messages OutputDebugStringA autour de :

L’initialisation du jeu.
La création des ressources DirectXTK12.
Chaque chargement de texture.
La création du pipeline de lutins.
La fin du téléversement des textures.
Les exceptions de trame.

La session originale a isolé l’échec de démarrage au chargement de white.dds. Le chargeur retournait 0x8007000D, ce qui identifiait des données DDS mal formées. La correction de l’en-tête DDS et un déploiement complet propre ont réglé le lancement. Pour plus de diagnostics de lancement, exécutez xbWatson pendant la reproduction de l’échec. Voir aussi Gestion des erreurs.

Étape 14 : Itérer en toute sécurité

Pour la plupart des changements limités au code :

Compilez en Debug.
Terminez le paquet en cours d’exécution.
Déployez le dossier de sortie complet.
Lancez l’AUMID inscrit.
Interrogez l’état du paquet.

Pour les changements à MicrosoftGameConfig.mgc, aux ressources ou aux métadonnées de déploiement, désinstallez l’ancien déploiement non empaqueté avant de déployer à nouveau. Cela évite que des fichiers ou des données d’inscription périmés masquent un correctif.

Facultatif : Créer et tester un XVC

Le déploiement de fichiers non empaquetés est la boucle de développement la plus rapide. Créez un XVC lorsque vous devez tester une installation semblable à la vente au détail ou préparer un paquet pour Partner Center. Voir Empaquetage pour la référence complète sur l’empaquetage.

Associer MicrosoftGame.config à Partner Center

Obtenez ces valeurs depuis Game setup > Identity details pour le produit :

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

Utilisez des espaces réservés dans les exemples versionnés. Ne copiez pas l’identité d’un autre produit. Pour les consoles XBOX Series X|S, la structure importante est :

<?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" est requis pour le paquet des consoles XBOX Series X|S. Utilisez une configuration distincte pour un paquet destiné aux consoles de la famille XBOX One.

Compiler la configuration Release

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

Préparer le contenu du paquet

Copiez la sortie Release dans un répertoire de préparation, mais gardez gameos.xvd hors de la carte de contenu et n’incluez pas les fichiers PDB comme contenu ordinaire du paquet.

$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

Générer la disposition

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

Pour ce petit exemple, la disposition résultante contient un seul segment de lancement :

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

Créer un paquet de test pour kit de développement

Le chiffrement de test par défaut est utile pour l’installation locale sur un kit de développement :

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

Lorsque StoreId est présent dans MicrosoftGame.config, /productid est inutile pour une soumission normale au Store. Omettez-le, sauf si un scénario documenté hors ligne ou sur disque l’exige spécifiquement.

Utiliser le chiffrement de soumission pour un paquet Partner Center

Produisez d’abord le paquet sample-game avec le chiffrement de test pour kit de développement afin de pouvoir vérifier l’installation et le lancement. Pour un paquet que vous allez soumettre, suivez la politique d’empaquetage en vigueur et utilisez /lk ou /l. Le flux de travail /lk reproductible recommandé est :

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

Protégez le fichier LEKB. Ne le versionnez pas dans le contrôle de code source.

Installer et lancer le XVC

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

Terminez le paquet lorsque les tests sont terminés :

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

Problèmes courants et correctifs

Symptôme	Cause	Correctif
Seuls les modèles Desktop sont disponibles	Le GDK PC public est installé sans les extensions XBOX	Installez le GDKX et son intégration à Visual Studio depuis XBOX Secure Downloads.
Le projet contient `Package.appxmanifest` et cible UWP	Le mauvais modèle Visual Studio a été sélectionné	Recréez le projet avec Direct3D 12 XBOX Game.
`Gaming.XBOX.Scarlett.x64` n’est pas disponible	La plateforme XBOX GDK ou l’extension Visual Studio est manquante	Réparez ou réinstallez la version correspondante du GDKX et l’intégration à Visual Studio.
Le titre se lance et se ferme immédiatement	Fichiers de déploiement manquants ou échec d’initialisation à l’exécution	Déployez la sortie de build complète et examinez `xbapp lastgamedetails` et `xbdbgmon`.
Le chargement du DDS retourne `0x8007000D`	En-tête DDS mal formé ou données non prises en charge	Régénérez le DDS et vérifiez l’en-tête DDS plus DX10 de 148 octets.
Un changement de ressource n’apparaît pas	Déploiement non empaqueté périmé	Terminez, désinstallez, puis redéployez complètement.
`makepkg` rejette la configuration	`TargetDeviceFamily` manquant ou incorrect	Définissez `Scarlett` pour les consoles XBOX Series X\|S ou `XboxOne` pour les consoles de la famille XBOX One.
L’identité du produit est fournie à plus d’un endroit	`/productid` a été ajouté alors que l’identité Store se trouve déjà dans la configuration du jeu	Conservez `StoreId` dans la configuration du jeu et omettez `/productid` pour une soumission normale au Store.
Les fichiers PDB causent des problèmes de carte de paquet ou de validation	Les symboles ont été inclus comme contenu du jeu	Excluez les PDB de la préparation et transmettez le répertoire de build via `/symbolpaths`.
Le lancement associé au Store semble échouer pendant la négociation	Le titre est peut-être encore en démarrage, ou les diagnostics sont incomplets	Lancez avec `/WaitToExit`, `/show:all` et `/LogModuleLoads`, puis interrogez l’état du paquet.

Voir aussi

Dernière modification le 1 septembre 2026

Sujets connexes

Développer un nouveau titre GDK Ajouter des services dorsaux avec PlayFab Documentation de développement de jeux XBOX Configurer et installer le GDK Aperçu de XBOX Series X|S

⌘I

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Compiler et exécuter votre premier titre console avec le GDKX

Ce que vous allez créer

Avant de commencer

Étape 1 : Créer le dossier de travail

Étape 2 : Vérifier l’installation du XBOX GDK

Étape 3 : Créer un projet XBOX natif

Confirmer que le projet n’est pas UWP

Étape 4 : Figer l’édition du GDK et configurer les cibles console

Étape 5 : Compiler le modèle non modifié

Étape 6 : Ajouter DirectXTK12 comme utilitaire facultatif

Étape 7 : Ajouter le code du jeu

Utiliser un pas de simulation fixe

Implémenter la collision d’une rondelle circulaire

Ajouter une lecture automatique prédictive

Faire le rendu de la scène avec DirectXTK12

Garder des effets sobres

Étape 8 : Créer et déployer les ressources de texture

Étape 9 : Compiler le jeu

Étape 10 : Se connecter au kit de développement XBOX

Étape 11 : Déployer le jeu complet

Étape 12 : Lancer et vérifier le jeu

Étape 13 : Diagnostiquer un échec de lancement immédiat

Obtenir le dernier résultat du titre

Surveiller la sortie de débogage

Étape 14 : Itérer en toute sécurité

Facultatif : Créer et tester un XVC

Associer MicrosoftGame.config à Partner Center

Compiler la configuration Release

Préparer le contenu du paquet

Générer la disposition

Créer un paquet de test pour kit de développement

Utiliser le chiffrement de soumission pour un paquet Partner Center

Installer et lancer le XVC

Problèmes courants et correctifs

Voir aussi

​Ce que vous allez créer

​Avant de commencer

​Étape 1 : Créer le dossier de travail

​Étape 2 : Vérifier l’installation du XBOX GDK

​Étape 3 : Créer un projet XBOX natif

​Confirmer que le projet n’est pas UWP

​Étape 4 : Figer l’édition du GDK et configurer les cibles console

​Étape 5 : Compiler le modèle non modifié

​Étape 6 : Ajouter DirectXTK12 comme utilitaire facultatif

​Étape 7 : Ajouter le code du jeu

​Utiliser un pas de simulation fixe

​Implémenter la collision d’une rondelle circulaire

​Ajouter une lecture automatique prédictive

​Faire le rendu de la scène avec DirectXTK12

​Garder des effets sobres

​Étape 8 : Créer et déployer les ressources de texture

​Étape 9 : Compiler le jeu

​Étape 10 : Se connecter au kit de développement XBOX

​Étape 11 : Déployer le jeu complet

​Étape 12 : Lancer et vérifier le jeu

​Étape 13 : Diagnostiquer un échec de lancement immédiat

​Obtenir le dernier résultat du titre

​Surveiller la sortie de débogage

​Étape 14 : Itérer en toute sécurité

​Facultatif : Créer et tester un XVC

​Associer MicrosoftGame.config à Partner Center

​Compiler la configuration Release

​Préparer le contenu du paquet

​Générer la disposition

​Créer un paquet de test pour kit de développement

​Utiliser le chiffrement de soumission pour un paquet Partner Center

​Installer et lancer le XVC

​Problèmes courants et correctifs

​Voir aussi

Ce que vous allez créer

Avant de commencer

Étape 1 : Créer le dossier de travail

Étape 2 : Vérifier l’installation du XBOX GDK

Étape 3 : Créer un projet XBOX natif

Confirmer que le projet n’est pas UWP

Étape 4 : Figer l’édition du GDK et configurer les cibles console

Étape 5 : Compiler le modèle non modifié

Étape 6 : Ajouter DirectXTK12 comme utilitaire facultatif

Étape 7 : Ajouter le code du jeu

Utiliser un pas de simulation fixe

Implémenter la collision d’une rondelle circulaire

Ajouter une lecture automatique prédictive

Faire le rendu de la scène avec DirectXTK12

Garder des effets sobres

Étape 8 : Créer et déployer les ressources de texture

Étape 9 : Compiler le jeu

Étape 10 : Se connecter au kit de développement XBOX

Étape 11 : Déployer le jeu complet

Étape 12 : Lancer et vérifier le jeu

Étape 13 : Diagnostiquer un échec de lancement immédiat

Obtenir le dernier résultat du titre

Surveiller la sortie de débogage

Étape 14 : Itérer en toute sécurité

Facultatif : Créer et tester un XVC

Associer MicrosoftGame.config à Partner Center

Compiler la configuration Release

Préparer le contenu du paquet

Générer la disposition

Créer un paquet de test pour kit de développement

Utiliser le chiffrement de soumission pour un paquet Partner Center

Installer et lancer le XVC

Problèmes courants et correctifs

Voir aussi