Adding Xbox Live Support To Your UWP Projects

When developing UWP apps for Xbox, you are required to have set up a minimum level of Xbox Live support - specifically, signing a user in to Xbox Live and getting their gamer tag. Note that this is only a requirement for UWP on Xbox One, but Xbox Live sign-in will also work on the UWP "Desktop" family of devices, so you can set it up and use it regardless of the final target if you wish.

Before continuing, please ensure that your game can run on an Xbox One. For full setup and testing instructions, please see the following article:

 

Create An App Listing

To prepare your game to use Xbox Live functionality (as well as to publish your game to the Xbox One) you will need to have a Microsoft Developer Account, which you can create from the MS Dev Center:

Once you have signed-up and set up your account (or signed in if you already have an MS dev account), you will need to create a new app listing for the game you want to publish, which you can do by clicking the button "Create A New App":

UWP_Create_App.png

This will take you to the Name Reservation screen:

UWP_ReserveName.png

Here you give the title name of your project as you want it to be published and then check to make sure that the given name is available. Once the check is completed you can edit the name and try again if the initial choice is not available, before continuing on to press the "Reserve Product Name" button.

This will take you to the App Overview screen, and before going any further you will need to tell Microsoft that you want this app to be part of the Xbox Live Creators Program. This is done from the Services > Xbox Live section of the app overview:

UWP_EnableCreators.png

Clicking "Enable" will open the following window, where you give the App Name and choose which device family to target:

UWP_CreatorSetup.png

Clicking "Confirm" will enable the Creators Program for the app (this may take a few moments) and then you'll be taken to an Xbox Live Creators Program overview screen.

UWP_CreatorDetails.png

Take note of the Sandbox ID, Title ID and SCID (Service Configuration ID) shown on this screen, as we will shortly use them to setup the Xbox Live Sandbox for testing our project.

 

Device Portal

Once you have created your app listing and set it as part of the Xbox Live Creators Program, you have to go back to your Windows 10 computer and set up the Device Portal so that the Xbox Live functions will work correctly while testing. To do this you need to open Windows' Settings app, then go to Update and Security, and click the For Developers section (you should already have set this up when you first set up the UWP platform).

On this page, you need to scroll down to the Enable Device Portal section and then click on the ethernet link:

UWP_DeveloperPortal.png

Clicking this will open the Device Portal in your browser, and you need to navigate to the Xbox Live section. Here you should see the Xbox Live Sandbox set to RETAIL. You need to change this to the Sandbox ID that you took note of earlier:

UWP_DevicePortal.png

Once that has been done, you can move on to opening GameMaker Studio 2 to set up your game.

NOTE: If this page shows an error or is "Limited" it means there may be an issue with the XBox Live service itself. You can check this from the following link: http://support.xbox.com/en-GB/xbox-live-status

NOTE: If this page shows an error about being unable to restart the authentication manager, simply wait a few seconds and try the Change button again

 

Xbox Live Functionality In GameMaker

The first thing to do with your project in GameMaker Studio 2 is set up the Game Options. Here you need to add the correct Package Name for your project. This name can be found from the MS Developer store page for your app, under the App Management > App Identity section:

UWP_AppIdentity.png

Copy this into Game Options > UWP > General, overwriting any Package Name value you have currently:

UWP_GameOptions_General.png

You then need to associate the app PFX file with the project from the Packaging section. If you haven't yet created a PFX for the project then you should do that now before adding it (see the section Create Your PFX Signing Certificate in this article if you don't know how to do this):

UWP_Packaging.png

Don't forget to click the Install button and follow the onscreen prompts before clicking the Apply button.

Finally, you need to go to the Xbox Live section and fill out the details required there. You will need to enter the Title ID and the SCID that you took note of earlier when you enabled the Xbox Live Creators Program and you will also need to check the two checkboxes to enable the Xbox Live integration:

UWP_Options_XBoxLive.png

Click Apply/OK. We can now add the code required for the Xbox Live connectivity.

 

Xbox Live Code

As mentioned earlier, your game must have a minimum level of functionality around using the Xbox Live interface if you want to submit to the Xbox One through the Creators Program. Specifically, it will need to have a user signed-in and permit the user to be changed and sign out. This section explains how to set up a "listener" object to control this process in your games.

Again, all UWP apps that are destined for the Xbox One must have this functionality.

UWP_Xbox_Controller.png

To start with, you'll need to create a new object and call it something like "obj_Xbox_Controller" (or add the following into some other persistent controller object in your project). For simplicity, we'll make this object persistent since it's only going to be created once at the start of the game and will run in the background. This object will be used to listen for sign-in/out callbacks, so add a Social Asynchronous Event with the something like the following code:

var _type = async_load[? "event_type"];
switch(_type)
{
case "user signed in": 
    global.PlayerTag = xboxlive_gamertag_for_user();
    break;
case "user sign in failed":
case "user_signed_out":
    xboxlive_show_account_picker();
    // Pause the game if required
    break;
}

All this code does is check to see if the game has detected a user as signed in and if it has, it stores the Gamer Tag of the user in a global variable. If it fails to sign in, or the game detects that no user is signed in, then the Xbox Account Picker is shown.

NOTE: The above code will lock the player into a loop if they sign out and not let them back into the game if they don't sign in again. This may not be desired behaviour on Desktop, but for XBox One, you are required to have a user signed in when playing your game.

There are also functions available that can be used to detect signing in and out of players so you can create a button in your game to open the account picker (for example):

if !xboxlive_user_is_signed_in()
    {
    if !xboxlive_user_is_signing_in()
        {
        xboxlive_show_account_picker();
        }
    }

It's important to note that bringing up the account picker will NOT pause the game, and that this can happen at any time, therefore you should have some code in place to call any pause functions/scripts that your game has should the account picker be opened.

Once you have this object in your game, you have met the minimum requirements for a UWP app to pass through the Creators Program certification. Note that if you want further functionality, like cloud saving or leaderboards, then you will need an ID@Xbox account as well as the additional Xbox extension for GameMaker Studio 2 (which requires the Console Licence).

 

Test Your Project

Once you have all this set up you can test the project on any Windows 10 PC or on your Xbox and you should now get the login screen:

XBox_Live_SignIn.png

You can now continue to test your game and then publish it to the MS App Store for Desktop and Xbox One.

Have more questions? Submit a request

0 Comments

Article is closed for comments.