Build an application with the Microsoft GDK API package

Understand how to use the GDK API package to build a project for the Windows platform.

Note

The GDK API package does not create or manage the MicrosoftGame.config file. Consider using the Microsoft GDK Tools package (com.unity.microsoft.gdk.tools) to make best use of the GDK API package for an improved workflow.

Set up and build a project using the GDK API package

To set up and build a project using the GDK API package, complete the following tasks:

Import a sample

The GDK API package provides some samples for you to explore the Microsoft Xbox services services. Use the following steps to import one of the samples:

  1. Create a new Unity Project.
  2. In the main menu, go to Window > Package Manager.
  3. In the packages list view, select the Microsoft GDK API package.
  4. In the Package details view, select Samples.
  5. Locate the Sign-in sample and select Import. Unity imports the selected package sample into Assets/Samples/Microsoft GDK API/<package version>/Sign-in.
  6. Double click the SignIn scene asset to load the sample scene.

Include the sample scene in the build

  1. In the main menu, go to File > Build Settings and select the Windows platform.
  2. Add the sample scene by selecting Add Open Scenes.
  3. Select Build to create a player in your target folder. Don’t use Build & Run as the XGameRuntime will fail to initialize due to a missing MicrosoftGame.config.
Note

If using Unity version 2023.3, Build Settings are now part of Build Profiles.

Add the Microsoft Game Configuration file

Your project must contain a valid Microsoft game configuration file for your game to run. The GDK API package itself doesn’t provide you tools to create or maintain this file.

  1. In the Project window, navigate to Assets/Samples/Microsoft GDK API/<package version>/Sign-in/MicrosoftGameConfig.
  2. Copy the GdkSignInSample.mgc to the resulting build folder where the built player is located. You can locate the Microsoft Game Config file using the right-click menu option, Show in Explorer.
  3. Rename the file copied in the earlier step to MicrosoftGame.config.

For more information about the MicrosoftGame.cofig file, refer to MicrosoftGame.config.

Note

For the best experience it’s recommended to use the Microsoft GDK Tools package. This package makes working with Microsoft Game Configuration files easier, as you don’t need to maintain this file manually during the build process.

Run the project

At this point you can either run the built application executable directly from the output folder or within the Unity Editor using the Build And Run option with the same output location. Don’t clean the build folder on build, or the MicrosoftGame.config file will be removed.

Build a sample using the Microsoft GDK Tools package

Using both the Microsoft GDK API and Microsoft GDK Tools packages together is the recommended approach when developing for GDK. The GDK Tools package provides support that you don't get with the standalone GDK API package.

To build and run a sample using the Microsoft GDK Tools package, use the following steps:

  1. Follow the previous steps to:
  2. Install the Microsoft GDK Tools package.
  3. In the Project window, navigate to Assets/Samples/Microsoft GDK API/<package version>/Sign-in/.
  4. Double click on the GDKSignInSample.gdksettings.asset to activate it.
  5. In the main menu, go to File > Build Settings and select the Windows platform.
  6. Ensure the sample scene is still selected in the Scenes In Build section.
  7. Select Build And Run. The GDK Tools package will automatically create the MicrosoftGame.config based on the GDK Settings provided by GDKSignInSample.gdksettings.asset.

MicrosoftGame.config

Consider the following important points relating to the MicrosoftGame.Config file:

  • Your project must include a valid MicrosoftGame.Config file for the correct initialization of the GDK API at runtime.
  • The MicrosoftGame.Config file must be included in the same folder as the executable that initializes the GDK API. The executable can be a built game executable or Unity.exe if you’re using the built-in Player of Unity Editor. In case of built game executable, make sure to save the MicrosoftGame.Config file in the same folder as your project build.
  • The MicrosoftGame.Config file must be correctly configured, with valid settings for elements such as TitleID and MSAAppId. For more information, refer to MicrosoftGame.config overview.
  • Pass the correct SCID in the call to SDK.XBL.XblInitialize().
  • If your project doesn't include a MicrosoftGame.Config file, you will get the error 0x87E5001F (E_GAME_MISSING_GAME_CONFIG).

Additional resources