> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Build and run your first console title with GDKX > End-to-end walkthrough: create a native GDKX project, add DirectXTK12, build for XBOX Series X|S, deploy to a dev kit, and produce an installable XVC. This walkthrough documents the end-to-end process for creating a small `sample-game` title and building it for XBOX Series X|S consoles. You then deploy the complete game to an XBOX dev kit, diagnose startup failures, and create an installable XVC. The completed sample uses C++, Direct3D 12, and the GDK with XBOX Extensions (GDKX). It also uses [DirectXTK12](https://github.com/microsoft/DirectXTK12) as an optional rendering helper. Both paddles are computer controlled so the game can run unattended while you iterate on graphics, gameplay, and effects. The public GDK available through GitHub or WinGet supports Windows PC game development only. To compile and deploy an XBOX console executable, install the GDK with XBOX Extensions (GDKX) from XBOX Secure Downloads. Access requires an approved XBOX developer account. See [ID@XBOX onboarding](/home/onboarding) and [Access GDK resources and downloads](/home/onboarding-access/access-resources). ## What you'll build By the end of this walkthrough, you'll have: * A native XBOX GDK project (not a UWP project). * Debug, Profile, and Release configurations for XBOX Series X|S consoles and XBOX One family consoles. * An autoplay sample game with scoring, predictive paddle AI, particle effects, a motion trail, and a textured circular puck. * A complete loose-file deployment running on an XBOX dev kit. * An optional Store-associated XVC that can be installed and tested on the dev kit. ## Before you begin This walkthrough was validated with: * Visual Studio 2022 Enterprise 17.14. * April 2026 Update 2 GDKX, edition `260402`. * `Gaming.XBOX.Scarlett.x64` for XBOX Series X|S consoles. * `Gaming.XBOX.XboxOne.x64` for XBOX One family consoles. * DirectXTK12 commit `e656d54637b2830fc6eb5ecd9b329a9c72cb87d4`. Use the GDK edition installed on your development PC instead of `260402` if you're following the walkthrough with another release. ## Step 1: Create the working folder Open PowerShell and create an empty root folder. ```powershell theme={null} New-Item -ItemType Directory -Path D:\repos\sample-game -Force ``` The final project layout used in this walkthrough is: ```text theme={null} 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 creates `DeviceResources.*`, `Main.cpp`, `pch.*`, `StepTimer.h`, and the shell visual PNG files from the **Direct3D 12 XBOX Game** template. Keep those generated files when adding the sample-specific source. ## Step 2: Verify the XBOX GDK installation Open the **XBOX Series X|S VS 2022 Gaming Command Prompt** installed with GDKX. The shortcut is normally under **Microsoft GDK** on the Start menu. You can also initialize the environment from an ordinary command prompt: ```cmd theme={null} call "C:\Program Files (x86)\Microsoft GDK\Command Prompts\GamingXboxVars.cmd" GamingXboxScarlettVS2022 260402 ``` Verify that the XBOX build and deployment tools are available: ```cmd theme={null} echo %GXDKEDITION% where msbuild where cl where xbconnect where xbapp where makepkg ``` The GDK installation isn't ready for console development if: * `GXDKEDITION` is empty. * The XBOX command-prompt shortcut is missing. * Visual Studio doesn't show XBOX project templates. * The `Gaming.XBOX.Scarlett.x64` MSBuild platform is unavailable. * `xbconnect` or `xbapp` can't be found. If only Desktop GDK command prompts and Desktop templates are available, the public PC GDK is probably installed instead of GDKX. ## Step 3: Create a native XBOX project Set **Language** to **C++**, **Platform** to **XBOX**, and **Project type** to **Games**. Set the project name to `sample-game` and the location to `D:\repos\sample-game`. So the solution is in the root and the project is in `D:\repos\sample-game\sample-game`. The supported workflow is to create the project through Visual Studio. Manually copying `d3d12game_gx` template files is a recovery technique, not the recommended new-project workflow. ### Confirm the project is not UWP Before adding game code, verify the project: * Contains `MicrosoftGameConfig.mgc`. * Uses a `Gaming.XBOX.*.x64` project platform. * Links to the XBOX GDK platform libraries. * Does not use `Package.appxmanifest` as its title configuration. * Was created from **Direct3D 12 XBOX Game**, not a Universal Windows template. If the project is UWP, delete it and create a new project from the XBOX GDK template. Converting the generated UWP project is more error prone than starting with the correct template. ## Step 4: Pin the GDK edition and configure console targets Pinning the GDK edition prevents a future GDK install from silently changing the toolchain used by the project. In the main property group in `sample-game.vcxproj`, set: ```xml theme={null} 260402 ``` Use Visual Studio Configuration Manager to confirm these solution configurations: | Configuration | Platform | | ------------- | -------------------------- | | 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` | If the title only supports XBOX Series X|S consoles, you can omit the XBOX One family consoles configurations. See [Cross-gen](/build/console-features/cross-gen/cross-gen-overview) for shipping the same title across generations. ## Step 5: Build the unmodified template Build the generated template before adding dependencies or game code. This isolates toolchain problems from problems introduced by the sample. From an **XBOX Series X|S VS 2022 Gaming Command Prompt**: ```cmd theme={null} msbuild D:\repos\sample-game\sample-game.sln /m /restore /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal ``` For XBOX One family consoles, initialize the XBOX One command environment and build the XBOX One platform: ```cmd theme={null} 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 ``` Do not continue until the stock XBOX template builds successfully. ## Step 6: Add DirectXTK12 as an optional helper DirectXTK12 isn't required to create a GDK title. The XBOX GDK template already provides the Direct3D 12 device, command queue, swap chain, and game loop needed to build a game against Direct3D 12 directly. This sample uses the separate Microsoft open-source DirectXTK12 library. The library reduces the amount of low-level rendering utility code required for sprite rendering, descriptor management, texture loading, resource upload, and graphics memory management. A title can replace these helpers with its own engine or a direct D3D12 implementation. Clone DirectXTK12 into the project: ```powershell theme={null} 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 ``` In Visual Studio: 1. Add `external\DirectXTK12\DirectXTK_GDKX_2022.vcxproj` to the solution. 2. Add DirectXTK12 as a project reference from `sample-game`. 3. Add `$(SolutionDir)external\DirectXTK12\Inc` to the include directories. 4. Build both projects for the same XBOX platform and configuration. The `sample-game` project uses this property: ```xml theme={null} $(SolutionDir)external\DirectXTK12\ ``` It then adds the include path and project reference: ```xml theme={null} $(DirectXTK12Dir)Inc;%(AdditionalIncludeDirectories) ``` ```xml theme={null} {94F17A4D-611B-4B81-8806-B6735910AB31} DirectXTK12 ``` In this project, the DirectXTK12 shader build commands were changed to invoke `CompileShaders.cmd` through an explicit project-relative path: ```xml theme={null} Command=""$(ProjectDir)Src\Shaders\CompileShaders.cmd" gxdk scarlett" ``` This avoids relying on the current command directory when MSBuild invokes the shader compiler. ## Step 7: Add the game code The sample separates gameplay state from rendering so the simulation can be tuned without changing Direct3D code. Keep the template-generated files, including `DeviceResources.*`, `Main.cpp`, `pch.*`, `StepTimer.h`, and the five shell visual PNG files. Add these sample-specific files to the project: | File | Purpose | | ------------------------------ | -------------------------------------------------------------------- | | `GameTuning.h` | Arena, paddle, puck, AI, trail, and particle constants. | | `sample-gameSimulation.h/.cpp` | Puck movement, paddle movement, collision, scoring, serving, and AI. | | `ParticleSystem.h/.cpp` | Fixed-size particle pool and impact emitters. | | `Game.h/.cpp` | DirectXTK12 resources, game update, and rendering. | | `tools\BuildAssets.ps1` | Reproducible DDS generation for the white sprite and puck. | ### Use a fixed simulation step The project uses the template's `StepTimer` with a **120 Hz fixed update**. A fixed step keeps collision response and AI behavior stable when frame times vary. The simulation contains: * Two paddle states. * One circular puck state. * Scores for the left and right sides. * A serve delay and alternating serve direction. * Impact events for paddle, wall, and goal collisions. ### Implement circular puck collision Treat each paddle as an axis-aligned rectangle and the puck as a circle: 1. Find the point on the paddle rectangle closest to the puck center. 2. Measure the squared distance from that point to the puck center. 3. A collision occurred if the distance is no greater than the squared puck radius. 4. Move the puck outside the paddle to prevent repeated overlap. 5. Calculate the outgoing angle from the hit offset and paddle velocity. 6. Increase puck speed slightly, up to a maximum. This keeps the physics circular even though the puck is drawn from a square texture. ### Add predictive autoplay Each paddle: * Predicts where the puck will intersect its horizontal position. * Reflects the predicted coordinate across the top and bottom arena walls. * Updates its target at a fixed reaction interval. * Uses acceleration and maximum-speed limits rather than snapping. * Adds a small deterministic targeting error. To allow games to score, each side occasionally enters a short mistake window and deliberately moves away from the predicted intercept. Stagger the initial mistake timers so both paddles do not miss simultaneously. ### Render the scene with DirectXTK12 Create: * `GraphicsMemory`. * A descriptor heap containing a white texture and the puck texture. * A normal-alpha `SpriteBatch`. * An additive `SpriteBatch` for particles. * DDS textures through `ResourceUploadBatch` and `CreateDDSTextureFromFile`. Draw the arena, center line, paddles, score, puck trail, and puck with `SpriteBatch`. Draw particles in the additive pass. The completed sample renders in a 1920 by 1080 virtual coordinate system and scales that scene to the output viewport. ### Keep effects restrained The final tuning used: * A short, exponentially decaying screen shake. * Smaller streak-shaped impact particles. * More particles on paddle hits than wall hits. * A stronger burst for a goal. * A low-alpha puck trail. * A brief green impact flash. These changes preserved impact feedback without making the game appear cartoon-like or making paddle collisions visually jarring. ## Step 8: Create and deploy the texture assets The sample needs: * `Assets\white.dds`: a 1 by 1 white RGBA texture used to draw rectangles and particles. * `Assets\xbox_logo.dds`: a 256 by 256 RGBA texture used for the puck. The asset script: 1. Loads the source logo. 2. Resizes it to 256 by 256. 3. Applies a feathered circular alpha mask. 4. Writes an RGBA8 DDS with a DX10 header. 5. Creates the 1 by 1 white DDS. Run it from PowerShell: ```powershell theme={null} Set-Location D:\repos\sample-game .\tools\BuildAssets.ps1 ``` Register both DDS files as deployment content in `sample-game.vcxproj`: ```xml theme={null} true Assets\%(Filename)%(Extension) true Assets\%(Filename)%(Extension) ``` A DDS file using the standard header plus a DX10 extension has **148 bytes** before the pixel data. During the original session, a custom DDS writer emitted 152 bytes and the title failed during texture loading with `0x8007000D`. If you use a custom DDS writer, validate the header layout before deployment. ## Step 9: Build the game From the XBOX Series X|S VS 2022 Gaming Command Prompt: ```cmd theme={null} msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Debug /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal ``` The loose build output is: ```text theme={null} D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug ``` Confirm that the output contains: * `sample-game.exe` * `MicrosoftGame.config` * The shell visual PNG files * `Assets\white.dds` * `Assets\xbox_logo.dds` * Required runtime DLLs * The Game OS image or other deployment metadata produced by the build The project source is named `MicrosoftGameConfig.mgc`. The GDK `MGCCompile` build item validates it and emits `MicrosoftGame.config` in the build output. Deployment and packaging both use the generated `.config` file. See [Game config](/build/core-features/common/game-config/MicrosoftGameConfig-Overview). ## Step 10: Connect to the XBOX dev kit Set the default console using its Tools IP address or host name: ```cmd theme={null} xbconnect ``` Check the stored console: ```cmd theme={null} xbconnect /B ``` Run connection diagnostics: ```cmd theme={null} xbconnect /DX ``` If the title uses a Partner Center sandbox, configure the case-sensitive sandbox ID and restart the console: ```cmd theme={null} xbconfig sandboxid= xbreboot xbconnect /WS ``` Display the current sandbox: ```cmd theme={null} xbconfig sandboxid ``` ## Step 11: Deploy the complete game Deploy the entire build output folder: ```cmd theme={null} xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug" ``` Do not copy only `sample-game.exe`. The title also needs `MicrosoftGame.config`, assets, runtime dependencies, shell images, and deployment metadata. An executable-only copy is not a valid full deployment. For a clean redeployment after changing assets or configuration: ```cmd theme={null} xbapp list xbapp terminate xbapp uninstall xbapp deploy "D:\repos\sample-game\Gaming.XBOX.Scarlett.x64\Debug" ``` Use `xbapp list` after deployment to find the registered package full name and application user model ID (AUMID). The AUMID ends with `!Game`. ## Step 12: Launch and verify the game Launch the exact AUMID reported by `xbapp list`: ```cmd theme={null} xbapp launch !Game ``` Wait for the title process: ```cmd theme={null} xbconnect /WTP:60 ``` Verify that the package is running: ```cmd theme={null} xbapp query ``` The expected result is: ```text theme={null} Package execution state: 1 (running) ``` At this point, the autoplay match should be visible on the dev kit. ## Step 13: Diagnose an immediate launch failure If the game exits immediately, do not assume that deployment succeeded because the executable was copied. ### Get the last title result ```cmd theme={null} xbapp lastgamedetails ``` ### Monitor debug output Start a debug output monitor in one command prompt: ```cmd theme={null} xbdbgmon /t /v ``` Launch the game from another: ```cmd theme={null} xbapp launch !Game ``` The sample added `OutputDebugStringA` messages around: * Game initialization. * DirectXTK12 resource creation. * Each texture load. * Sprite pipeline creation. * Texture upload completion. * Frame exceptions. The original session isolated the startup failure to loading `white.dds`. The loader returned `0x8007000D`, which identified malformed DDS data. Correcting the DDS header and performing a clean full deployment fixed the launch. For more launch diagnostics, run `xbWatson` while reproducing the failure. See also [Error handling](/build/core-features/common/async/index). ## Step 14: Iterate safely For most code-only changes: 1. Build Debug. 2. Terminate the running package. 3. Deploy the complete output folder. 4. Launch the registered AUMID. 5. Query the package state. For changes to `MicrosoftGameConfig.mgc`, assets, or deployment metadata, uninstall the old loose deployment before deploying again. This prevents stale files or registration data from hiding a fix. ## Optional: Create and test an XVC Loose deployment is the fastest development loop. Create an XVC when you need to test retail-like installation or prepare a package for Partner Center. See [Packaging](/build/core-features/common/packaging/overviews/packaging) for the full packaging reference. ### Associate MicrosoftGame.config with Partner Center Get these values from **Game setup** > **Identity details** for the product: * Package Identity Name. * Package Identity Publisher. * Publisher Display Name. * Store ID. * XBOX Title ID. * MSA App ID. Use placeholders in source-control examples. Don't copy another product's identity. For XBOX Series X|S consoles, the important structure is: ```xml theme={null} REPLACE-WITH-MSA-APP-ID REPLACE-WITH-XBOX-TITLE-ID REPLACE-WITH-STORE-ID ``` `TargetDeviceFamily="Scarlett"` is required for the XBOX Series X|S consoles package. Use a separate configuration for an XBOX One family consoles package. ### Build the Release configuration ```cmd theme={null} msbuild D:\repos\sample-game\sample-game.sln /m /p:Configuration=Release /p:Platform=Gaming.XBOX.Scarlett.x64 /nologo /verbosity:minimal ``` ### Stage the package content Copy the Release output to a staging directory, but keep `gameos.xvd` outside the content map and do not include PDB files as ordinary package content. ```powershell theme={null} $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 ``` ### Generate the layout ```cmd theme={null} makepkg genmap /f "D:\repos\sample-game\packages\Scarlett\Release\layout.xml" /d "D:\repos\sample-game\packages\Scarlett\Release\staging" ``` For this small sample, the resulting layout contains one launch chunk: ```xml theme={null} ``` ### Create a dev-kit test package Default test encryption is useful for local dev kit installation: ```cmd theme={null} 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 ``` When `StoreId` is present in `MicrosoftGame.config`, `/productid` is unnecessary for a normal Store submission. Omit it unless a documented offline or disc scenario specifically requires it. ### Use submission encryption for a Partner Center package Produce the sample-game package first with dev-kit test encryption so you can verify installation and launch. For a package that you will submit, follow the current packaging policy and use `/lk` or `/l`. The recommended repeatable `/lk` workflow is: ```cmd theme={null} 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 ``` Secure the LEKB. Do not commit it to source control. ### Install and launch the XVC ```cmd theme={null} xbapp install ".xvc" xbapp list xbapp launch !Game xbapp query ``` Terminate the package when testing is complete: ```cmd theme={null} xbapp terminate !Game ``` ## Common problems and fixes | Symptom | Cause | Fix | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Only Desktop templates are available | Public PC GDK is installed without XBOX Extensions | Install GDKX and its Visual Studio integration from XBOX Secure Downloads. | | The project contains `Package.appxmanifest` and targets UWP | The wrong Visual Studio template was selected | Recreate the project with **Direct3D 12 XBOX Game**. | | `Gaming.XBOX.Scarlett.x64` is unavailable | The XBOX GDK platform or Visual Studio extension is missing | Repair or reinstall the matching GDKX release and Visual Studio integration. | | The title launches and immediately exits | Missing deployment files or runtime initialization failure | Deploy the complete build output and inspect `xbapp lastgamedetails` and `xbdbgmon`. | | DDS loading returns `0x8007000D` | Malformed DDS header or unsupported data | Regenerate the DDS and verify the 148-byte DDS plus DX10 header. | | An asset change doesn't appear | Stale loose deployment | Terminate, uninstall, and fully deploy again. | | `makepkg` rejects the configuration | Missing or incorrect `TargetDeviceFamily` | Set `Scarlett` for XBOX Series X\|S consoles or `XboxOne` for XBOX One family consoles. | | Product identity is being supplied in more than one place | `/productid` was added even though the Store identity is already in the game config | Keep `StoreId` in the game config and omit `/productid` for a normal Store submission. | | PDB files cause package-map or validation issues | Symbols were included as game content | Exclude PDBs from staging and pass the build directory through `/symbolpaths`. | | Store-associated launch appears to fail during handshake | The title may still be starting, or diagnostics are incomplete | Launch with `/WaitToExit`, `/show:all`, and `/LogModuleLoads`, then query the package state. | ## See also * [Develop a new GDK title](/home/build-first-title/developing-new-titles) * [Install the GDK toolchain](/home/setup-install/download-install) * [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-Overview) * [Packaging](/build/core-features/common/packaging/overviews/packaging) * [Build for Series X|S](/paths/series-xs/overview) * [Cross-gen](/build/console-features/cross-gen/cross-gen-overview) ## Related topics - [Develop a new GDK title](/home/build-first-title/developing-new-titles.md) - [Getting started with packaging titles for XBOX consoles](/build/core-features/common/packaging/overviews/packaging-getting-started-for-console.md) - [Quickstart C++ for Linux](/services/playfab/sdks/playfab-cpp/quickstart-linux.md) - [Set up and install the GDK](/home/setup-install/get-started.md) - [GDK samples](/home/setup-install/samples.md)