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

Cette procédure pas à pas 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 dev kit XBOX, diagnostiquez les échecs au démarrage et créez un XVC installable. L’exemple terminé utilise C++, Direct3D 12 et le GDK avec les XBOX Extensions (GDKX). Il utilise également DirectXTK12 comme assistant de rendu facultatif. Les deux raquettes sont contrôlées par l’ordinateur afin que le jeu puisse tourner sans surveillance pendant que vous itérez sur les graphismes, le gameplay et les effets.

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

Ce que vous allez créer

À la fin de cette procédure, vous disposerez de :

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 autoplay avec score, IA prédictive des raquettes, effets de particules, traînée de mouvement et palet circulaire texturé.
Un déploiement complet en fichiers libres (loose) s’exécutant sur un dev kit XBOX.
Un XVC facultatif associé au Store, pouvant être installé et testé sur le dev kit.

Avant de commencer

Cette procédure a été validée 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 la procédure 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 cette procédure 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 du shell à partir du modèle Direct3D 12 XBOX Game. Conservez ces fichiers générés lors de l’ajout des sources spécifiques à l’exemple.

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

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 build 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 console si :

GXDKEDITION est vide.
Le raccourci d’invite de commandes XBOX est absent.
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 est introuvable.

Si seuls 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 Créer un nouveau projet

Définissez Langage sur C++, Plateforme sur XBOX et Type de projet sur Jeux.

Sélectionner Direct3D 12 XBOX Game

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

Laisser décochée l'option Placer la solution et le projet dans le même répertoire

Ainsi, la solution est à 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 via Visual Studio. Copier manuellement les 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 du code de jeu, vérifiez que le projet :

Contient MicrosoftGameConfig.mgc.
Utilise une plateforme de projet Gaming.XBOX.*.x64.
Est lié aux bibliothèques de plateforme du GDK XBOX.
N’utilise pas Package.appxmanifest comme configuration de 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. Convertir le projet UWP généré est plus sujet aux erreurs que de repartir du bon modèle.

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

Épingler l’édition du GDK évite qu’une future installation du GDK ne change 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 Gestionnaire de configurations de Visual Studio pour confirmer les configurations de solution suivantes :

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 pour les consoles de la famille XBOX One. Consultez Cross-gen pour publier 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 du code de 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 poursuivez pas tant que le modèle XBOX standard ne se compile pas correctement.

Étape 6 : ajouter DirectXTK12 comme assistant facultatif

DirectXTK12 n’est pas nécessaire 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 swap chain et la boucle de jeu nécessaires pour développer un jeu directement avec Direct3D 12. Cet exemple utilise la bibliothèque open source distincte de Microsoft, DirectXTK12. Cette bibliothèque réduit la quantité de code utilitaire de rendu de bas niveau requise pour le rendu de sprites, la gestion des descripteurs, le chargement de textures, l’envoi (upload) de ressources et la gestion de la mémoire graphique. Un titre peut remplacer ces assistants par son propre moteur ou 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 shaders de DirectXTK12 ont été modifiées pour invoquer CompileShaders.cmd via 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 shaders.

Étape 7 : ajouter le code du jeu

L’exemple sépare l’état du gameplay 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, notamment DeviceResources.*, Main.cpp, pch.*, StepTimer.h et les cinq fichiers PNG visuels du shell. Ajoutez au projet ces fichiers spécifiques à l’exemple :

Fichier	Rôle
`GameTuning.h`	Constantes de l’arène, des raquettes, du palet, de l’IA, de la traînée et des particules.
`sample-gameSimulation.h/.cpp`	Déplacement du palet, déplacement des raquettes, collisions, score, service et IA.
`ParticleSystem.h/.cpp`	Pool de particules à 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 sprite blanc et le palet.

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 réponse aux collisions et le comportement de l’IA stables lorsque les temps de trame varient. La simulation contient :

Deux états de raquette.
Un état de palet circulaire.
Les scores des côtés gauche et droit.
Un délai de service et une direction de service alternée.
Des événements d’impact pour les collisions avec les raquettes, les murs et les buts.

Implémenter la collision du palet circulaire

Traitez chaque raquette comme un rectangle aligné sur les axes et le palet comme un cercle :

Trouvez le point du rectangle de la raquette le plus proche du centre du palet.
Mesurez la distance au carré entre ce point et le centre du palet.
Une collision s’est produite si la distance n’excède pas le rayon du palet au carré.
Déplacez le palet hors de la raquette 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 raquette.
Augmentez légèrement la vitesse du palet, jusqu’à un maximum.

Cela conserve une physique circulaire même si le palet est dessiné à partir d’une texture carrée.

Ajouter un autoplay prédictif

Chaque raquette :

Prédit l’endroit où le palet croisera sa position horizontale.
Réfléchit la coordonnée prédite par rapport aux 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 aux parties de produire 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 minuteurs d’erreur initiaux afin que les deux raquettes ne ratent pas simultanément.

Rendre la scène avec DirectXTK12

Créez :

GraphicsMemory.
Un tas de descripteurs contenant une texture blanche et la texture du palet.
Un SpriteBatch alpha normal.
Un SpriteBatch additif pour les particules.
Des textures DDS via ResourceUploadBatch et CreateDDSTextureFromFile.

Dessinez l’arène, la ligne centrale, les raquettes, le score, la traînée du palet et le palet 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 du viewport de sortie.

Garder des effets sobres

Le réglage final utilisait :

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

Ces changements ont préservé le retour visuel d’impact sans donner au jeu un aspect cartoon ni rendre les collisions avec les raquettes visuellement agressives.

É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 le palet.

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

Enregistrez 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. Lors de la session d’origine, un générateur DDS personnalisé produisait 152 octets et le titre échouait au chargement des textures avec 0x8007000D. Si vous utilisez un générateur DDS personnalisé, validez la structure 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 build en fichiers libres est :

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

Confirmez que la sortie contient :

sample-game.exe
MicrosoftGame.config
Les fichiers PNG visuels du shell
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

La source du projet est nommée MicrosoftGameConfig.mgc. L’élément de build MGCCompile du GDK la valide et émet MicrosoftGame.config dans la sortie de build. Le déploiement et le packaging utilisent tous deux le fichier .config généré. Consultez Game config.

Étape 10 : se connecter au dev kit 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 les diagnostics de connexion :

xbconnect /DX

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

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

Affichez la sandbox actuelle :

xbconfig sandboxid

Étape 11 : déployer le jeu complet

Déployez l’intégralité du dossier de sortie de build :

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

Ne copiez pas uniquement sample-game.exe. Le titre a également besoin de MicrosoftGame.config, des ressources, des dépendances d’exécution, des images du shell 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 modification des ressources ou de la 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 package enregistré 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 indiqué par xbapp list :

xbapp launch <package-family-name>!Game

Attendez le processus du titre :

xbconnect /WTP:60

Vérifiez que le package s’exécute :

xbapp query <package-full-name>

Le résultat attendu est :

Package execution state: 1 (running)

À ce stade, la partie en autoplay doit être visible sur le dev kit.

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

Si le jeu se ferme immédiatement, ne supposez 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 a ajouté 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 sprites.
L’achèvement de l’envoi des textures.
Les exceptions de trame.

La session d’origine a isolé l’échec au démarrage au chargement de white.dds. Le chargeur renvoyait 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ésolu le lancement. Pour davantage 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 modifications limitées au code :

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

Pour les modifications de MicrosoftGameConfig.mgc, des ressources ou des métadonnées de déploiement, désinstallez l’ancien déploiement en fichiers libres avant de redéployer. Cela évite que des fichiers ou des données d’enregistrement obsolètes ne masquent un correctif.

Facultatif : créer et tester un XVC

Le déploiement en fichiers libres est la boucle de développement la plus rapide. Créez un XVC lorsque vous devez tester une installation de type commerciale ou préparer un package pour Partner Center. Consultez Packaging pour la référence complète du packaging.

Associer MicrosoftGame.config à Partner Center

Obtenez ces valeurs dans 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 obligatoire pour le package des consoles XBOX Series X|S. Utilisez une configuration distincte pour un package 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 package

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

$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 le layout

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, le layout résultant contient un seul chunk de lancement :

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

Créer un package de test pour dev kit

Le chiffrement de test par défaut est utile pour une installation locale sur 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

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 package Partner Center

Produisez d’abord le package sample-game avec le chiffrement de test pour dev kit afin de pouvoir vérifier l’installation et le lancement. Pour un package que vous soumettrez, suivez la politique de packaging en vigueur et utilisez /lk ou /l. Le flux de travail /lk répétable 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

Sécurisez le LEKB. Ne le committez 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 package une fois les tests terminés :

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

Problèmes courants et solutions

Symptôme	Cause	Solution
Seuls les modèles Desktop sont disponibles	Le GDK PC public est installé sans les XBOX Extensions	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 GDKX correspondante et l’intégration Visual Studio.
Le titre se lance et se ferme immédiatement	Fichiers de déploiement manquants ou échec de l’initialisation du runtime	Déployez la sortie de build complète et examinez `xbapp lastgamedetails` et `xbdbgmon`.
Le chargement DDS renvoie `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 de 148 octets avec extension DX10.
Une modification de ressource n’apparaît pas	Déploiement en fichiers libres obsolète	Terminez, désinstallez et 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é produit est fournie à plusieurs endroits	`/productid` a été ajouté alors que l’identité Store figure 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 package ou de validation	Les symboles ont été inclus comme contenu du jeu	Excluez les PDB du staging 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 cours de démarrage, ou les diagnostics sont incomplets	Lancez avec `/WaitToExit`, `/show:all` et `/LogModuleLoads`, puis interrogez l’état du package.

Voir aussi

Dernière modification le 1 septembre 2026

Sujets connexes

Développer un nouveau titre GDK Ajouter des services backend avec PlayFab Documentation de développement de jeux XBOX Configurer et installer le GDK Accéder aux ressources et téléchargements du GDK

⌘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 GDK XBOX

Étape 3 : créer un projet XBOX natif

Confirmer que le projet n’est pas UWP

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

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

Étape 6 : ajouter DirectXTK12 comme assistant facultatif

Étape 7 : ajouter le code du jeu

Utiliser un pas de simulation fixe

Implémenter la collision du palet circulaire

Ajouter un autoplay prédictif

Rendre 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 dev kit 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 package

Générer le layout

Créer un package de test pour dev kit

Utiliser le chiffrement de soumission pour un package Partner Center

Installer et lancer le XVC

Problèmes courants et solutions

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 GDK XBOX

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

​Confirmer que le projet n’est pas UWP

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

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

​Étape 6 : ajouter DirectXTK12 comme assistant facultatif

​Étape 7 : ajouter le code du jeu

​Utiliser un pas de simulation fixe

​Implémenter la collision du palet circulaire

​Ajouter un autoplay prédictif

​Rendre 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 dev kit 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 package

​Générer le layout

​Créer un package de test pour dev kit

​Utiliser le chiffrement de soumission pour un package Partner Center

​Installer et lancer le XVC

​Problèmes courants et solutions

​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 GDK XBOX

Étape 3 : créer un projet XBOX natif

Confirmer que le projet n’est pas UWP

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

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

Étape 6 : ajouter DirectXTK12 comme assistant facultatif

Étape 7 : ajouter le code du jeu

Utiliser un pas de simulation fixe

Implémenter la collision du palet circulaire

Ajouter un autoplay prédictif

Rendre 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 dev kit 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 package

Générer le layout

Créer un package de test pour dev kit

Utiliser le chiffrement de soumission pour un package Partner Center

Installer et lancer le XVC

Problèmes courants et solutions

Voir aussi