Configuring Xbox Live in Unity
The Xbox Live Unity plugin is only recommended for members of the Xbox Live Creators Program, since currently there is no support for achievements or multiplayer. See Choosing an Xbox Live developer program.
With the Xbox Live Unity Plugin, adding Xbox Live support to a Unity game is easy, giving you more time to focus on using Xbox Live in ways that best suit your title.
This article shows how to set up the Xbox Live plugin in Unity.
You will need the following before you can use Xbox Live in Unity:
- An Xbox Live account.
- Enrollment in the Partner Center developer program.
- Windows 10 Anniversary Update or later
- Unity versions 5.5.4p5 (or newer), 2017.1p5 (or newer), or 2017.2.0f3 (or newer) with Microsoft Visual Studio Tools for Unity and Windows Store .NET Scripting Backend.
- Visual Studio 2015 or Visual Studio 2017 15.3.3 (or newer) with the Universal Windows App Development Tools.
- Xbox Live Platform Extensions SDK.
If you want to use the IL2CPP scripting backend with Xbox Live, you will need Unity 2017.2.0p2 or newer and the Xbox Live Unity plugin version "1802 Preview Release" or higher.
Import the Unity plugin
To import the plugin into your new or existing Unity project, follow these steps:
- Navigate to the Xbox Live Unity Plugin release tab on https://github.com/Microsoft/xbox-live-unity-plugin/releases.
- Download XboxLive.unitypackage.
- In Unity, click Assets > Import Package > Custom Package and navigate to XboxLive.unitypackage.
(Optional) Configure the plugin to work in the Unity Editor (.NET 4.6 or IL2CPP only)
Support for changing the Scripting Runtime Version in Unity requires the Xbox Live Unity Plugin version "1711 Release" or higher for .NET 4.6 and version "1802 Preview Release" or higher for IL2CPP.
There are three settings that can be configured in Unity to define how your code is compiled:
- The scripting backend is the compiler that is used. Unity supports two different scripting backends for Universal Windows Platform: .NET and IL2CPP.
- The Scripting Runtime Version is the version of the scripting runtime that runs the Unity Editor.
- The API Compatibility Level is the API surface you'll build your game against.
The following table shows the current scripting support matrix for the Xbox Live Unity Plugin:
|Scripting Backend||Scripting Runtime Version||Supported||Minimum Unity Version Required|
|IL2CPP||.NET 3.5 Equivalent||No||N/A|
|Il2CPP||.NET 4.6 Equivalent||Yes||2017.2.0p2|
|.NET||.NET 3.5 Equivalent||Yes||Same as prerequisites|
|.NET||.NET 4.6 Equivalent||Yes||Same as prerequisites|
We've added additional scripting runtime support to the Xbox Live Unity Plugin, starting with version "1711 Release". By default, the plugin is configured to run in the Unity editor with the .NET scripting backend and scripting runtime version of .NET 3.5.
If your project is using the scripting runtime version of .NET 4.6, you will need to configure the plugin to work properly in the editor, as follows:
In the Unity project explorer, navigate to Xbox Live\Libs\UnityEditor\NET46 and select all of the DLLs in the folder.
In the Inspector window, check Editor under Include Platforms.
In the Unity project explorer, navigate to Xbox Live\Libs\UnityEditor\NET35 and select all of the DLLs in the folder.
In the Inspector window, uncheck Editor under Include Platforms.
These steps will need to be reversed if you change the scripting runtime version in your project back to 3.5.
Set Visual Studio as the IDE in Unity
Visual Studio is required to build a Universal Windows Platform (UWP) game. You can set your IDE in Unity to Visual Studio by going into Edit > Preferences > External Tools and setting the External Script Editor to Visual Studio.
Unity plugin file structure
The Unity plugin's file structure is broken into the following parts:
- Xbox Live contains the actual plugin assets that are included in the published .unitypackage.
- Editor contains scripts that provide the basic Unity configuration UI and processes the projects during build.
- Examples contains a set of simple scene files that show how to use the various prefabs and connect them together.
- Images is a small set of images that are used by the prefabs.
- Libs is where the Xbox Live libraries are stored.
- Prefabs contains various Unity prefab objects that implement Xbox Live functionality.
- Scripts contains all the code files that call the Xbox Live APIs from the prefabs. This is a great place to look for examples about how to properly call the Xbox Live APIs.
- Tools\AssociationWizard contains the Xbox Live Association Wizard, used to pull down application configuration from Partner Center for use within Unity.
Enable Xbox Live
For your title to interact with Xbox Live, you'll need to setup the initial Xbox Live configuration.
You can do this easily and inside of Unity by using the Xbox Live Association Wizard, as follows:
In the Xbox Live menu, select Configuration.
In the Xbox Live window, select Run Xbox Live Association Wizard.
In the Associate Your title with the Windows Store dialog, click Next, and then sign in with your Partner Center account.
Select the app that you want to associate with this project, and then click Select. If you don't see it there, try clicking Refresh. Alternatively, you can create a new app by reserving a name and clicking Reserve.
You will be prompted to enable Xbox Live if you have not already. Click Enable to enable Xbox Live in your title.
Click Finish to save your configuration.
To call Xbox Live services, your desktop must be in developer mode and set to the same sandbox as your title is in the Xbox Live configuration.
You can verify both by looking at the Xbox Live Configuration window in Unity:
Developer Mode Configuration should say Enabled. If it says Disabled, click Switch to Developer Mode.
Title Configuration > Sandbox should have the same ID as Developer Mode Configuration > Developer Mode.
See Xbox Live Sandboxes overview for information about sandboxes.
Build and test the project
When running your title in the editor, you will see fake data when you try to use Xbox Live functionality. For example, if you add sign in capabilities to your scene (per Sign-in in Unity through prefabs or scripting (pre-1804 release)) and try to sign in, you will see Fake User appear as your profile name, with a placeholder icon. To sign in with a real profile and test out Xbox Live functionality in your title, you'll need to build a UWP solution and run it in Visual Studio.
You can build the UWP project in Unity, as follows:
Open the Build Settings window by selecting File > Build Settings.
Add all of the scenes that you want to include in your build under the Scenes In Build section.
Switch to the Universal Windows Platform by selecting Universal Windows Platform under Platform and clicking Switch Platform.
Set SDK to 10.0.15063.0 or greater.
To enable script debugging check Unity C# Projects.
Click Build and specify the location of the project.
Once the build has finished, Unity will have generated a new UWP solution file which you will need to run in Visual Studio:
In the folder that you specified, open <ProjectName>.sln in Visual Studio.
In the toolbar at the top, select x64 and deploy to the Local Machine.
If you enabled script debugging when you built the UWP solution from Unity, then your scripts will be located under the Assembly-CSharp (Universal Windows) project.
Before using your Visual Studio build to test your game with real data, follow the checklist in Testing a Unity game build in Visual Studio to help ensure your title will be able to access the Xbox Live service.
Starting May 2018, to test your UWP title properly in Visual Studio, you must update the
package.appxmanifest.xml file. To do this:
Search the Solution Explorer for the
Right-click the file and then click View Code. If the View Code option is not available, or the
package.appxmanifestfile does not have an extension, you will need to open the file as an XML file and then continue with the remaining steps.
- In the
<Properties>section, add the following line:
- Deploy the game to the Xbox console by starting a remote debugging build from Visual Studio. To set up your title on an Xbox, see Set up your UWP on Xbox development environment.
The piece of configuration that is changed may look like it is enabling multi-player, but it is still necessary to run your game in single-player scenarios.
Try out the examples
You can now start using Xbox Live in your Unity project. Try opening scenes in the Xbox Live/Examples folder to see the plugin in action, and for examples of how to use the functionality yourself.
Running the examples in the editor will give you fake data - to sign in with your gamertag, build the project in Visual Studio and associate your Xbox Live account with the sandbox; see Authorize test accounts, for Creators.
- Try the SignInAndProfile scene for signing into your Microsoft Account.
- Try the Leaderboard scene for creating a leaderboard.
- Try the UpdateStat scene for displaying and updating stats.