Getting started with Unity

Overview

This document describes how to get started with Unity as you integrate GDK components into your project. This will cover the different types of Unity packages, how to get them set up and what functionality is included within each package.

The latest Microsoft GDK packages for Unity, co-developed by Microsoft and Unity, provide the capability to target Windows x64, Xbox Series X|S and Xbox One Console devices with the same configuration and code base.

Prerequisites

The following prerequisites are required to utilize the Microsoft GDK packages for Unity:

• Unity Editor Version 2021.3 or newer
• Visual Studio 2019 (16.9) or newer
• Windows SDK (22000 or later)
• Windows 10 (1709 or higher) or Windows 11
• October 2023 Update 4 GDK or newer
• Valid Unity license if targeting Xbox Consoles

For more details on package requirements, please see Unity’s requirements and installation document.

Microsoft GDK Packages for Unity

There are multiple GDK packages that provide different capabilities when integrated with your project and the Editor. All packages are distributed by Unity and more information can be found on their download portal.

To access the Microsoft GDK Xbox Console packages, you must be a member of an Xbox Developer program, including ID@Xbox, and have requested access to Unity’s Xbox forums via contacting your Microsoft representative. The packages necessary to start PC development are available publicly and can be found here.

The full list of packages is:

• Microsoft GDK API package for Unity (PC & Console)
• Microsoft GDK Tools package for Unity (PC & Console)
• Microsoft GDK Tools for Xbox package for Unity (Console Only)
• GXDK Input System package for Unity (Console Only)
• Game Core Render Pipeline package for Unity (Console Only)

The Microsoft GDK API package for Unity provides the necessary C# wrappers for native APIs to be utilized across PC, Xbox Series X|S and Xbox One devices, including access to Xbox Network services such as Achievements, Cloud Saves, and Leaderboards.

The Microsoft GDK Tools package for Unity provides the necessary integration for development workflows within Unity to create a Microsoft Game Configuration file and package your PC game with the GDK for submission to the Microsoft Store.

The Microsoft GDK Tools for Xbox package for Unity extends the GDK Tools package with integration for developer workflows for Xbox Series X|S and Xbox One devices, including packaging your Console GDK game for submission to the Microsoft Store.

The GXDK Input System package for Unity provides console-specific functionality to the Unity Input System when targeting Xbox Series X|S or Xbox One devices.

The Game Core Render Pipeline package for Unity provides console-specific functionality to use Unity’s Scriptable Render Pipelines (SRP) such as the Universal Render Pipeline (URP) or the High Definition Render Pipeline (HDRP) on Xbox Series X|S or Xbox One devices.

Unity Editor Add-ons for Console

To get access to the build profiles & project settings to be able to configure, build, deploy and launch on Xbox Series X|S and Xbox One devices within Unity, you will need to install Editor Add-ons provided by Unity to extend the Editor to include this functionality.

These Add-ons are provided as .exe installers that provide additional functionality to each Editor. As such, they must be installed on each machine using the Editor to unlock these capabilities. Once the Add-ons are successfully installed, the associated Unity Editor version in the Installs tab of the Unity Hub will list them as supported capabilities. Any projects using that version of the Editor can now enable Xbox Series X|S and Xbox One GDK project settings and build profiles.

Below is an example of a Unity 6 version of the Editor with both Add-ons installed:

Package, Add-in, GDK, and Engine Compatibility

The Microsoft GDK API & Tools packages for Unity are acquired via the Unity Registry in the Package Manager within the Unity Editor. The version presented will be compatible with the running Editor, if the Editor is version 2021.3.47f1, 2022.3.55f1, 6000.0.31f1 or newer. Please see here for more information on GDK & Engine version compatibility with each release of the Microsoft GDK API package for Unity. These packages support the GDK acquired via GitHub and the GDK acquired via the Xbox Developer Downloads portal.

The Microsoft GDK Tools for Xbox package for Unity is acquired via a direct download link from Unity’s Xbox forums. This package is compatible with Unity Editor versions 2021.3.45f1, 2022.3.49f1, 6000.0.22f1 or newer. Please see this Unity Xbox forum post for more information on requirements for this package. This package is only supported with the GDK acquired via the Xbox Developer Downloads portal. This package requires the Xbox Series X|S and Xbox One Add-ons for Unity Editor to be installed to be exposed in the Editor.

The GXDK Input System package for Unity is acquired via a direct download link from Unity’s Xbox forums. Please see this Unity Xbox forum post for more information on requirements for this package. This package is only supported with the GDK acquired via the Xbox Developer Downloads portal. This package requires the Xbox Series X|S and Xbox One Add-ons for Unity Editor to be installed to be exposed in the Editor.

The Game Core Render Pipeline Package for Unity is acquired via a direct download link from Unity’s Xbox forums. Please see this Unity Xbox forum post for more information on requirements for this package. This package is only supported with the GDK acquired via the Xbox Developer Downloads portal. This package requires the Xbox Series X|S and Xbox One Add-ons for Unity Editor to be installed to be exposed in the Editor.

The Xbox Series X|S and Xbox One Add-ons for Unity Editor are acquired via a direct download link from Unity’s Xbox forums. Please see this Unity Xbox forum post for more information on requirements for these Editor Add-ons. These Add-ons are only supported with the GDK acquired via the Xbox Developer Downloads portal.

Integrating Packages into your project

To get started with the Microsoft GDK API & Tools packages for Unity, follow these steps:

1. Navigate to the Window Menu and select ‘Package Manager’.
2. Once open, select the ‘Unity Registry’ option from the right column.
3. In the search box, type gdk and wait for the list to refresh.
4. Select the ‘Microsoft GDK API’ package and click Install.
5. Once completed, select the ‘Microsoft GDK Tools’ package and click Install.
6. Close the Package Manager once both packages have successfully been installed.

Here is an overview of searching for the packages in the Unity Registry in Unity 6:

For the Xbox Console-specific packages, you will acquire them via the Unity Xbox Forums download portal. These packages will be locally added to the project via:

1. Navigate to the Window Menu and select Package Manager.
2. Once open, select the “+” and select “Add package from tarball…”
3. Navigate to your .tgz extension downloaded package.
4. Select it and it will then be installed to your project.

Below is an image showing the packages locally installed in a project in Unity 6:

The packages for Unity are associated with your Unity project. If you create a new Unity project, you will need to re-acquire these packages and install them again to that Unity project. Users opening the Unity project with these packages installed will not need to re-download them from the registry to get access to this functionality.

Configuring your project to be GDK aware

This section will cover the initial integration of your project to be GDK aware.

Creating GDK Settings Asset

Once the Microsoft GDK API & Tools packages for Unity are installed in your project, you will have additional menu options. One of those is a GDK specific set of Assets, which allows you to generate a GDK Settings Asset. This will add GDK-specific settings to your Project Settings which will allow you to configure your GDK product directly within Unity. For more information on managing your GDK Settings in Unity, please see here.

Below is an example of a GDK Settings Asset being created in Unity 6:

If the GDK Tools for Xbox package and the Xbox Add-ons are installed, the GDK Settings will have multiple tabs for each platform and platform-specific settings and config files can be created from them. Your project might contain more than one GDK Settings asset of which only one asset can be active at a time.

Below is an example of GDK Settings being created for Xbox Series X|S and Xbox One in Unity 6:

Creating Microsoft Game Config Asset

Once your GDK Settings Asset is created, you can add a Microsoft Game Config asset to your project. This will generate the necessary files to configure your project to work with GDK specific features and capabilities. For more information on managing your Microsoft Game Config file in Unity, please see here.

Below is an example of a Microsoft Game Config Asset being created in Unity 6:

Associating your Microsoft Game Config with your GDK Asset

After your Microsoft Game Config has been created, you will need to open the GDK Project Settings and associate your Microsoft Game Config with the project. This will ensure it is used for that Platform as part of build and packaging steps.

Below is an example of associating your Microsoft Game Config in Unity 6:

Editing your Microsoft Game Config Asset

As part of the GDK Tools package integration, the Microsoft Game Config Asset has a specific Editor integration that can help you easily modify and configure the right GDK configuration values. This can be found in the Inspector pane when selecting the Microsoft Game Config Asset in the asset list. For more information on managing your Microsoft Game Config file in Unity, please see here.

Below is an example of editing your Microsoft Game Config in Unity 6:

Associating your GDK game with your Partner Center product

As part of the GDK Tools package integration, the Microsoft Game Config Editor enables you to use a built in Wizard to easily associate your GDK game with your Partner Center product. This requires you to sign in to your Microsoft account that has privileges to see the Partner Center product you are wanting to associate with. After successfully associating with Partner Center, the Wizard will list out what values have been mapped from Partner Center to your projects Game Config Asset automatically. For more information on creating your product in Partner Center and accessing Xbox service capabilities, please see here.

Below is an example of starting the Store Association Wizard within Unity 6:

Utilizing C# Wrappers for access APIs

As part of the Microsoft GDK API package for Unity, a set of C# wrappers of native GDK APIs are provided to directly access these APIs in your Unity project. To learn more about accessing GDK APIs, please see here.

Below is an example of the C# wrappers within the Microsoft GDK API package for Unity in the Packages window:

Utilizing Visual Studio and Unity

Visual Studio provides a Gaming Workload, as part of the Visual Studio Installer, for direct integration with Unity. To learn more about the Visual Studio Tools for Unity extension, please see here.

Utilizing Samples

There are currently two sets of Unity samples that can be acquired and used to reference code when building your project.

Unity Registry Samples

The first set of samples come with the Microsoft GDK API package for Unity, and can be found in the Samples tab within the Microsoft GDK API entry in the Unity Registry once downloaded, as seen below:

These samples demonstrate basic interactions with systems like Achievements, Cloud Saves, Game Saves, In-Game Store behavior, Leaderboards, Sign-In, Speech Synthesizer and User behavior. For more information on these samples, please see here.

Unity GDK Samples

In addition to the samples provided via the Unity Registry, there is a set of samples provided alongside the GDK download itself. These are intended to provide demonstrations of more advanced usage of APIs. The samples included are:

• UnityAchievements - Demonstrates usage of XblAchievement APIs to query and update achievement progress.
• UnityInGameStore - A complete in-game store experience that can be configured to run as any title and demonstrates the majority of XStore APIs to query catalog offerings, user entitlements, and license products.
• UnityLeaderboardsTitleManaged - Demonstrates usage of title-managed leaderboards to update and query user statistics, and to query social and global leaderboards.
• UnitySimpleMPSD - A basic multiplayer session sample that uses Multiplayer Session Directory (MPSD) and SmartMatch APIs for session management and matchmaking.
• UnityRumble – A simple multiplayer game that uses Multiplayer Manager (MPM), and PlayFab Party to create/join/matchmake/leave multiplayer sessions, update session state, share gameplay data, and communicate over chat.
• UnityRumblePlayFabMultiplayer - Like above but uses PlayFab Multiplayer for session management and matchmaking instead of Multiplayer Manager.
• UnitySimpleHttpCall - Demonstrates the use of Xbox Live Http Calls to send and receive messages as a string or byte array.
• UnitySimpleWebSockets - Demonstrates use of Http Client Web Sockets to send and receive binary or string messages to a pre-configured web socket end point.
• UnitySimplePLM - A basic sample which shows how to detect and respond to lifetime management events (constrain/suspend/resume on Console, focus lost/found on PC).
• UnitAssetWorkflow (Xbox only) - Demonstrates usage of Xbox console resources and tooling APIs to facilitate quick iteration of game assets.

These samples can be acquired from the Xbox Developer Downloads site. Here is an example of the sample name in the list of builds under the GDK file type in the download portal.

Building & packaging your project

This section will cover building and packaging your project in Unity.

Localization and Packaging Settings

As part of your GDK settings for your Windows platform, you can specify if you will be building shell visuals, localized assets and if you will create a package as part of the build step in Unity. There are no specific ‘Build Profiles’ settings that need to be configured for Windows packaging. For more information on packaging settings, please see here.

Below is an example of setting those GDK Settings values in Unity 6:

For Console, if you have the Microsoft GDK Tools for Xbox package included in your project, you can set ‘Shell Visuals Mode’ to ‘Copy Only’ which will ensure that your Store images are copied to the build folder before packaging. This will eliminate the need for you to manually copy images over.

To set the package encryption method for Console, go to Project Settings > Player > Publisher Settings. The Xbox targets will include a 'Package Encryption' setting. Use 'Development' when building a package that you want to be able to side-load for local testing (when using 'Build and Deploy' or 'xbapp install'). Use 'Submission' for packages that you'll upload to Partner Center and then install from the Store.

Unity's package generation for Console is configured on the 'Build Profiles’ page. Change your target platform to Xbox One or Xbox Series (depending on which one you're building for). For a local package that you can side-load, set 'Build Type' to 'Development player'. For a package that you want to upload to Partner Center, set 'Build Type' to 'Master player'. Change the Deploy Method to 'Package'.

For a Console side-loadable package built with 'Development' encryption, you can use the 'Build and Run' option to deploy to your console. This will create a loose folder build, run makepkg.exe with test signing and install/launch the package on your default devkit.

A package built with the 'Submission' encryption cannot be side-loaded. It must be uploaded to Partner Center and then installed via the Microsoft Store.

Build Profiles

Build profiles exist for each of your target platforms. The Windows platform will consume the GDK settings files and generate an MSIXVC package in an MSIXVC folder after the build has completed if a package was specified in the Windows GDK Settings file. For more information on build profiles, please see here.

For Console, the settings for deployment, inclusive of packaging, are specified in the platform specific build settings alongside additional build, deployment and debugging options. The output directory will include an XVC package in an XVC folder after the build has completed.

Below is an example of viewing each platforms build profiles in Unity 6:

Testing your project in Play Mode

There are additional steps and considerations to ensure GDK based projects work properly in Play Mode. For more information on the steps required to properly use Play Mode, please see here.

Additional Information

Getting Help

To get help with any issues hit, please see the Unity Xbox forums. If you are not part of the Xbox Developers program and are using the public packages for Windows development, please use the Unity Windows forums.

If you are looking for help related to GDK-specific topics that are not specific to Unity integration, please post these on the Xbox GDK forums.

Known Issues

For a list of known issues related to the GDK API package for Unity, please see here.

For a list of known issues related to the GDK Tools package for Unity, please see here.

Using older versions of Unity

The Microsoft GDK AP & Tools Packages support Unity 2021.3 and newer versions of the Editor. It is strongly recommended to use supported versions of the Unity Editor to get integrated tools support and capabilities to properly build and run your title across all platforms.

If you are using an older version of Unity, you can reference the C# wrappers provided in the GDK API package to provide your own project-specific interfaces with GDK native APIs. In addition, you can use out of Editor tools to create your MicrosoftGame.config, localization and shell visuals and package for your game.

These processes are manual, and do not provide direct Editor integration. If you are unable to upgrade your Unity Editor version and need more guidance on options, please reach out to your Microsoft representative.

Deprecated Packages

The GDK Unity Package (PC Only) that was distributed on GitHub by Microsoft is now deprecated and has been removed in favor of the Microsoft GDK API & Tools packages for Unity. If you have any questions regarding the GDK Unity Package (PC Only), please reach out to your Microsoft representative. If you are using the previous GDK Unity Package (PC Only) and are looking for steps on how to migrate, please see the upgrade guide here.

Please refer to the Unity Xbox forums post for more information on Unity-provided packages that are now deprecated.