Running the XDK Samples

To complete the setup of your development environment, configure your development computer by specifying the address of the console to use, and then deploy and run some of the XDK samples on the console, as follows.

Sections:

Reading Documentation About the XDK Samples

The master list of samples is on the Xbox Game Developer (XGD) site. You’ll need to be logged into XGD to view this page.

Samples are available in the following technology areas:

Documentation about each sample is not directly shown at the Xbox Game Developer (XGD) site; instead, when you download a sample from XGD, the sample’s directory includes a Readme .docx file.

Obtaining the XDK Samples

Many of the Xbox One samples are hosted on GitHub under the MIT license. These can be obtained by cloning the Xbox-ATG-Samples repository or by downloading the entire repository as a zip from the releases area. Building these samples require an Xbox One XDK, so they still require an Xbox One Developer Agreement, but the sample source itself is freely available.

A subset of samples contain sensitive material that precludes publishing to a publicly accessible GitHub. These remain hosted on the Xbox Game Developer (XGD) site as zip files.

Specifying a Console to Use

You only need to specify a console for a particular sample if you have not specified a default console, or if you want to use a different console than the default.

To specify a console for a particular sample

  1. Get the Tools IP address of the console, as follows. On the console, view the All Apps screen of the Launcher. The All Apps screen appears after booting the console, and after exiting an app that was opened from the Launcher. Write down the Tools IP address, which is shown in the lower left. The Tools IP address is also listed in the Settings app.
  2. On your development computer, in the directory for the sample, open the .sln file in Visual Studio. For example: [path for your XDK Samples]graphics\SimpleTriangle\SimpleTriangle.sln
    The project will be set for Visual Studio 2015 (v140 Platform Toolset). If you are using Visual Studio 2017, you should retarget the solution to use the v141 Platform Toolset.
  3. In Solution Explorer, right-click the main project for the sample, such as SimpleTriangle, and then click Properties. The Property Pages dialog box appears.
  4. In the tree on the left, expand Configuration Properties, then click Xbox One. (Some samples don’t list the Xbox One property page as they are PC tools, such as the sample XTexconv.) The Xbox One property page appears.
  5. For Remote IP Address, enter the Tools IP address of the console. (Or you can try entering the hostname of the console; for more information, see “To connect to the dev kit using the hostname” in Setting a Hostname for the Console IP Address.) Then click the Close button to close the Property Pages dialog box.

Specifying an XDK Edition

The sample projects are set to use the newest XDK edition installed on the system. You can specify a particular version by editing the Xbox One property page in the project settings. Set the Xdk Edition Target value to the desired value based on your installed side-by-side Xbox One XDKs.

The DirectX Tool Kit library used by most samples makes use of prebuilt shaders for Xbox One included in the static library. These shaders are edition-specific and are built automatically the first time you build a sample. If you change the XDK edition, you may have to forcibly rebuild these:

  1. Open an Xbox Developer Command prompt.
  2. For a DirectX 11 sample: 
            cd [path for your XDK Samples]Kits\DirectXTK\Src\Shaders
        CompileShaders.cmd xbox
  3. For a DirectX 12 sample: 
            cd [path for your XDK Samples]Kits\DirectXTK12\Src\Shaders
        CompileShaders.cmd xbox

Specifying a Sandbox for LIVE Samples

Samples that use Xbox LIVE services need to run against a particular Sandbox ID.

To specify the sandbox for the LIVE samples

  1. Open up an Xbox One XDK Command Prompt.
  2. Type the following command: 
            xbconfig sandboxId=XDKS.1

To reset the console to the default of no sandbox enter:

        xbconfig sandboxId=

For more information, refer to the Configuration (xbconfig.exe) documentation.

Building, Deploying, and Running a Sample

To build, deploy and run a sample

  1. Obtain the samples and specify the console as described above. Connect an Xbox controller to the Xbox console and make sure the screen is ready to display video from the console.
  2. On your development computer, in a sample directory, find the .sln file that is named like the sample, and open it in Visual Studio. For example: [path for your XDK Samples]graphics\SimpleTriangle\SimpleTriangle.sln
    For initial setup, the SimpleTriangle or the SimpleTriangle12 sample is recommended.
  3. If using Visual Studio 2017, right-click on the solution and select Retarget Solution, then click OK.
  4. In that same directory, view the Readme file to see any special considerations about building, deploying, and running the sample.
  5. In Solution Explorer, right-click the main project for the sample, such as SimpleTriangle, and then click Properties. The Property Pages dialog box appears.
  6. In the tree on the left, expand Configuration Properties, and then click Debugging. The Debugging property page appears.
  7. In the Debugger to launch drop-down list, make sure Microsoft Xbox One Debugger is selected. (This choice is not available in some samples, such as XTexconv.) Then click the Close button to close the Properties dialog box.
  8. Click the Debug menu, then click Start Without Debugging (Ctrl+F5) or Start Debugging (F5).
    The sample builds on the PC, deploys to the console, and then runs on the console. By design, some samples might not deploy, or might not run visibly. The sample runs immediately, even if another app was running on the console.
    In the Output pane in Visual Studio, connection messages are shown, similar to the following: 
    Push deploying 'SimpleTriangle\Durango\Layout\Image\Loose' to '<Tools IP address>'.
Calculating payload.
Transfer starting for 13 files (119515436 bytes).
Transferring 1/13: SimpleTriangle\Durango\Layout\Image\Loose\appdata.bin (16384 bytes)
Transferring 2/13: SimpleTriangle\Durango\Layout\Image\Loose\AppxManifest.xml (1986 bytes)
Transferring 3/13: SimpleTriangle\Durango\Layout\Image\Loose\era.xvd (108388352 bytes)
Transferring 4/13: SimpleTriangle\Durango\Layout\Image\Loose\lnk{2A71F60E-A45D-4BA7-8B8A-45C85D1275E3}.tmp (8794112 bytes)
Transferring 5/13: SimpleTriangle\Durango\Layout\Image\Loose\PixelShader.cso (21112 bytes)
Transferring 6/13: SimpleTriangle\Durango\Layout\Image\Loose\resources.pri (2312 bytes)
Transferring 7/13: SimpleTriangle\Durango\Layout\Image\Loose\SimpleTriangle.exe (657920 bytes)
Transferring 8/13: SimpleTriangle\Durango\Layout\Image\Loose\VertexShader.cso (32480 bytes)
Transferring 9/13: SimpleTriangle\Durango\Layout\Image\Loose\Assets\Logo.png (54793 bytes)
Transferring 10/13: SimpleTriangle\Durango\Layout\Image\Loose\Assets\SmallLogo.png (30559 bytes)
Transferring 11/13: SimpleTriangle\Durango\Layout\Image\Loose\Assets\SplashScreen.png (1383444 bytes)
Transferring 12/13: SimpleTriangle\Durango\Layout\Image\Loose\Assets\StoreLogo.png (19335 bytes)
Transferring 13/13: SimpleTriangle\Durango\Layout\Image\Loose\Assets\WideLogo.png (112647 bytes)
      
Package Full Name: 'd41ef946-f0c8-4779-8bfa-61ca1567cfb5_1.0.0.0_x64__8wekyb3d8bbwe'
119515436 bytes in 13 files over 11.259162 seconds.
Approximate transfer speed: 10.6149494962414 MB/s.
Aumids returned for this package:
   d41ef946-f0c8-4779-8bfa-61ca1567cfb5_8wekyb3d8bbwe!App
Project associated with aumid 'd41ef946-f0c8-4779-8bfa-61ca1567cfb5_8wekyb3d8bbwe!App'
Selected debugger address '<Tools IP address>.
Launch request successful.
  9. If the sample deployed to the console but isn’t running, to run the sample, do the following:
    • On the console, in the Games & Apps screen of DevHome, use the Xbox controller to select the sample. Multiple versions of the sample might be shown, such as Simple Triangle (Debug), Simple Triangle (Release), and Simple Triangle (Profile). The Debug version might be better to select, so that it stays visible and doesn’t close immediately.
    • Press A on the controller to run the sample.
  10. Operate the sample, as described in its readme file.

Exiting a Sample

To exit a sample

Searching Samples for Code

To search the downloaded samples to find sample code that uses a particular API item, you can use Visual Studio or the command prompt.

To search for an API item by using Visual Studio

  1. In Visual Studio, press Ctrl+Shift+F. The Find in Files tab appears, in the Find and Replace dialog box.
  2. In the Look in combo box, specify the directory containing your expanded downloaded samples. Visual Studio saves the path in the Look in drop-down list.

To search for an API item using a command prompt

  1. Open a command prompt. For example, in Windows, on the Start page, click the Xbox One XDK Command Prompt tile.
  2. Use a command such as findstr. For example, the following command searches for CopyResourceX. 
    cd [your samples directory]
findstr /s CopyResourceX *.cpp