A session about a new cross-platform “XDK” was spotted by Windows Central yesterday, and this looks to be all about expanding Microsoft’s Xbox Live network to more platforms including iOS, Android. Now with this, you can do some stunning things, but not at the moment because the official XDK has NOT been released so this application wont work at the moment.
The Official software development kit for the original xbox was called the XDK (Xbox Development Kit). This was only provided to developers on their Xbox Developer Services website (xds.xbox.com) and not via CD. Microsoft® SDK (System Development Kit) for Xbox (also known as the XDK) The XDK compiler is only available to Microsoft approved developers/programmers and is used together with Microsoft Visual Studio.NET to compile source code into Xbox binaries (executables) that can run on Microsoft Xbox. Now Xbox Live is about to get MUCH bigger. Xbox Live is expanding from 400M gaming devices and a reach to over 68M active players to over 2B devices with the release of our new cross-platform XDK.
-->If you have a title that was developed using the Xbox One Xbox Developer Kit (XDK), you can migrate the title's Xbox Live code to the Windows 10 Universal Windows Platform (UWP).
Part of this migration includes switching from XSAPI 1.0 (Xbox Live Services API, included in the Xbox One XDK through August 2015) to XSAPI 2.0 (included in the Xbox One XDK starting in November 2015, and also available in the Xbox Live SDK.The functionality of these APIs are virtually identical, but there are some important implementation differences.
This article also covers:
- Preparing your Windows development computer.
- Installing other APIs that are typically needed when using Xbox Live services, such as the Secure Sockets API, as well as the Connected Storage API for managing cloud-backed game saves.
Setting up and configuring your project in Partner Center
A UWP title that uses Xbox Live services needs to be configured in Partner Center.
See Adding Xbox Live to a new or existing UWP project.
Sections in that article include these steps for using Xbox Live services in your title:
- Create the UWP app project in Partner Center.
- Use Partner Center to set up your project for Xbox Live usage.
- Create developer accounts in Partner Center (required when running your Xbox Live title in your sandbox).
If your titles support multiplayer play, some additional settings may be required in your multiplayer session templates.All Windows 10 titles that use Xbox Live multiplayer and write to an MPSD (multiplayer session document) require this new field in the list of 'capabilities' found in your session templates:
userAuthorizationStyle: true
.Enabling cross-play
If you will support 'cross-play' (a shared Xbox Live configuration between Xbox One and PC games, allowing cross-device multiplayer gaming), you will also need to add this capability to your session templates: crossPlay: true.
For additional information about supporting cross-play and its configuration requirements, see the Xbox Live Programming Guide (a .chm file containing conceptual content).
Also, for some programmatic considerations, see the later section Supporting multiplayer cross-play between Xbox One and PC.
Setting up your Windows development environment
- Download the latest Xbox Live SDK and extract locally.
- Install the Xbox Live Platform Extensions SDK if you need the Secure Sockets API and/or the Game Save API (aka Connected Storage) for UWP.
- Add Xbox Live support to your Universal Windows app project in Visual Studio. You can add either the full source or reference the binaries by installing the NuGet package into your Visual Studio project. Packages are available for both C++ and WinRT. For more detail see [Adding Xbox Live to a new or existing UWP project](./get-started/setup-ide/managed-partners/vs-win10/get-started-with-visual-studio-and-uwp.md)
- Configure your development computer to use your sandbox. There's a command-line script in the Tools directory of the Xbox Live SDK that you can use from an administrator command prompt (for example: SwitchSandbox.cmd XDKS.1).
Note To switch back to the retail sandbox, you can either delete the registry key that the script modifies, or you can switch to the sandbox called RETAIL.
- Add a developer account to your development computer. A developer account created in Partner Center is required to interact with Xbox Live services at runtime when you are developing in your assigned sandbox or running samples. To add one or more accounts to Windows:
- Open Settings (shortcut: Windows key + I).
- Open Accounts.
- On the Your Account tab, click Add a Microsoft account.
- Enter the developer account email and password.
AppxManifest changes
The most common changes between the Xbox and UWP versions of the appxmanifest.xml file are:
- Package Identity matters in UWP, even during development. Both the Identity Name and Publisher must match what was defined in Partner Center for your UWP app.
- A Package Dependency section is required. For example:
- Refer to an example UWP application manifest (for example, one of the UWP samples included with the Xbox Live SDK or a default Universal Windows app project created in Visual Studio) for other sections of the application manifest that have specific requirements for UWP, such as
<VisualElements>
. - Title and SCID are defined in the xboxservices.config file (see the next section) instead of in the 'xbox.live' extension category.
- The 'xbox.system.resources' extension category is not needed.
- Secure Sockets are defined in the networkmanifest.xml file (see Secure sockets) instead of in the 'windows.xbox.networking' category.
- A 'windows.protocol' extension category must be defined in order to receive Xbox Live invites in your UWP title (see Sending and receiving invites).
- If you use the GameChat API, you'll want to add the microphone device capability inside the
<Capabilities>
element. For example:
<DeviceCapability Name='microphone'>
Define your title and SCID for the Xbox Live SDK in a config file
The Xbox Live SDK needs to know your title ID and SCID, which are no longer included in the appxmanifest.xml for UWP titles.Instead, you create a text file named xboxservices.config in your project root directory and add the following fields, replacing the values with the info for your title:
Note
All values inside xboxservices.config are case sensitive.
Include this config file as content in your project so that it is available in the build output.
Note These values will be available programmatically within your title by using the following API:
API namespace mapping
Table 1. Namespace mapping from XDK to UWP.
Xbox One XDK | UWP | API is available with.. | |
Xbox Services API (XSAPI) | Microsoft::Xbox::Services | Microsoft::Xbox::Services (no change) | Xbox Live SDK (use NuGet binary or source) |
GameChat | Microsoft::Xbox::GameChat Windows::Xbox::Chat | Microsoft::Xbox::GameChat (*no change*) Microsoft::Xbox::ChatAudio | Xbox Live SDK (use NuGet binary) |
SecureSockets | Windows::Xbox::Networking | Windows::Networking::XboxLive | Xbox Live Platform Extensions SDK |
Connected Storage | Windows::Xbox::Storage | Windows::Gaming::XboxLive::Storage | Xbox Live Platform Extensions SDK |
Multiplayer subscriptions and event handling
One of the breaking changes from XSAPI 1.0 to XSAPI 2.0 that most multiplayer titles will encounter is the move of several methods and events from the RealTimeActivityService to the MultiplayerService.
For example:
- EnableMultiplayerSubscriptions()* method
- DisableMultiplayerSubscriptions() method
- MultiplayerSessionChanged event
- MultiplayerSubscriptionLost event
- MultiplayerSubscriptionsEnabled property
Important implementation note Even though you might not be explicitly using anything else in the RealTimeActivityService after moving these events and methods over to the MultiplayerService, you must still call xblContext->RealTimeActivityService->Activate() before calling EnableMultiplayerSubscriptions() because the multiplayer subscriptions require the RTA service.
What's handled differently in UWP
Following is a very high level list of sections of code that will likely have differences between the XDK and UWP, as encountered in the new NetRumble sample (which includes both XDK and UWP versions):
- Accessing title ID and SCID info
- Prelaunch activation (new for UWP)
- Suspend/resume PLM handling
- Extended execution (new for UWP)
- Xbox User object and user-handling differences
- Sign-in and sign-out handling
- Controller pairing (only handled on Xbox)
- Gamepad handling
- Checking multiplayer privileges
- Supporting multiplayer cross-play between Xbox One and PC
- Sending game invites
- Ability to open party app from in-game - n/a on UWP
- Ability to enumerate party members from in-game - n/a on UWP
- Showing the gamer profile
- Secure Socket API surface changes
- QoS measurement initiation and result handling
- Writing game events
- GameChat: events, settings, and ChatUser object
- Connected Storage API surface changes
- PIX events (only on Xbox; not covered in this white paper)
- Some rendering differences
The following sections go into further detail on many of these differences.
Accessing title ID and SCID info
In UWP, your title ID and service configuration ID are accessed through the AppConfig property on an instance of an XboxLiveContext.
Note In the XDK, you can get these IDs by using either these new properties or the old static properties in Windows::Xbox::Services::XboxLiveConfiguration.
Prelaunch activation
Frequently-used titles in Windows 10 may be pre-launched when the user signs in.To handle this, your title should have code that checks the launch arguments for PreLaunchActivated.For example, you probably don't want to load all your resources during this kind of activation.
For more information, see the MSDN article Handle app prelaunch.
Suspend/resume PLM handling
Suspend and resume, and PLM in general, work similarly in a Universal Windows app to the way they work on Xbox One; however, there are a few important differences to keep in mind:
- There is no Constrained state on the PC—this is an Xbox One exclusive concept.
- Suspending begins immediately when the title is minimized; for a way around this, see the section Extended execution.
- The timing is different: you have 5 seconds to suspend on a PC instead of the 1 second on the console.
Another important consideration if you use connected storage is the new ContainersChangedSinceLastSync property in the UWP version of this API.When handling a resume event, you can check this property to see if any containers changed in the cloud while your title was suspended.This can happen if the player suspended the game on one PC, played elsewhere, and then returned to the first PC.
If you had read data from these containers into memory before you had suspended, you probably want to read them again to see what changed and handle the changes accordingly.
For more information about handling PLM in a UWP app on Windows 10, see the MSDN article Launching, resuming, and background tasks.
You may also find the PLM for Xbox One white paper on GDN useful because it was written with games in mind, and most of the concepts for handling the app lifecycle still apply on a PC.
Extended execution
Minimizing a UWP app on a PC typically results in it immediately starting to suspend.By using extended execution, you have the opportunity to delay this process.
Example implementation:
After the ExtensionRevokedHandler has been called, a new extension needs to be requested for future potential suspensions.The ExtensionRevokedHandler is called when there is memory pressure in the system, 10 minutes have elapsed, or the user switches back to the game while the game is minimized.
So RequestExtension() should likely be called at these times:
- During startup.
- In the ExtensionRevokedHandler when args->Reason Resumed (the user tabbed back while the game was minimized before the 10-minute timer expired).
- In the OnResuming handler (if the title was suspended due to memory pressure or the 10-minute timer).
Handling users and controllers
On Windows, you work with one signed-in user at a time.In the Xbox Live SDK, you first create an XboxLiveUser object, sign them in to Xbox Live, and then create XboxLiveContext objects from this user.
Before, on the Xbox One XDK:
- Acquire a user (from gamepad interaction, for example).
- Create an XboxLiveContext from that user:
- Handle a SignOut event:
- Handle gamepad/controller pairing using:
Now, for the UWP/Xbox Live SDK:
- Create an XboxLiveUser:
- Try to sign them in by using the last Microsoft account they used, without bothering them with UI:
- If you get SignInResult::Success in the result from this async operation, create the XboxLiveContext, and then you're finished:
- If instead you get SignInResult::UserInteractionRequired, you need to call the interactive sign-in method that brings up system UI:
- From here you may get SignInResult::UserCancel, in which case you don't have a signed-in user and you should consider providing a menu option for them to try signing in again.
Note When providing menu options, it's a good idea to give them the option to switch to a different Microsoft account:
- After you have a signed-in user, you may want to hook up the XboxLiveUser::SignOutCompleted event so that you can react to the user signing out:
- There is no controller pairing to handle in Windows 10.
This is a simplified example for C++ / WinRT.For a more detailed example, see 'Xbox Live Authentication in Windows 10' in the Xbox Live Programming Guide.You may also find the broader example at 'Adding Xbox Live to a new UWP project' helpful.
Checking multiplayer privileges
The equivalent to CheckPrivilegeAsync() is not yet available in the Xbox Live SDK.For now, you will need to search for the privilege you need in the string list returned by the Privileges property for an XboxLiveUser.
For example, to check for multiplayer privileges, look for privilege '254.'Using the XDK documentation, you can find a list of all the Xbox Live privileges in the Windows::Xbox::ApplicationModel::Store::KnownPrivileges enumeration.
See the forum post xsapi & user privileges.
Supporting multiplayer cross-play between Xbox One and PC UWP
In addition to new session template requirements in Partner Center (see Setting up and configuring your project in Partner Center), cross-play comes with new restrictions on session join ability.You can no longer use 'None' as a session join restriction.You must use either 'Followed' or 'Local' (the default restriction is 'Local').
Also, the join and read restrictions default to 'Local' because of the required userAuthorizationStyle capability for Windows 10 multiplayer.
This forum article contains additional insight: Is it possible to create a public multiplayer session.
Further information and examples can be found in the updated multiplayer developer flowcharts, the cross-play-enabled multiplayer sample NetRumble, or from your Developer Account Manager (DAM).
Sending and receiving invites
The API to bring up the UI for sending invites is now Microsoft::Xbox::Services::System::TitleCallableUI::ShowGameInviteUIAsync().You pass in a session-> SessionReference object from your activity session (typically your lobby).
You can optionally pass in a second parameter that references a custom invite string ID that's been defined in your service configuration in Partner Center.The string you define there will appear in the toast notification sent to the invited players.
What you are passing in as a parameter to this method is the ID number, and it must be formatted properly for the service.For example, string ID '1' must be passed in as '///1'.
If you want to send invites directly by using the multiplayer service (that is, without showing any UI), you can still use the other invite method, Microsoft::Xbox::Services::Multiplayer::MultiplayerService::SendInvitesAsync() from the user's XboxLiveContext.
To allow for invites coming into Windows to protocol-activate your title, you need to add this extension to the <Application> element in the appxmanifest:
You can then handle the invite as you did before on Xbox One when your CoreApplication gets an Activated event and the activation Kind is an ActivationKind::Protocol.
Showing the gamer profile card
To pop up the gamer profile card on UWP, use Microsoft::Xbox::Services::System::TitleCallableUI::ShowProfileCardUIAsync(), passing in the XUID for the target user.
Secure sockets
The Secure Socket API is included in the separate Xbox Live Platform Extensions SDK.
See this forum post for API usage: Setting up SecureDeviceAssociation for cross platform.
Note For UWP, the SocketDescriptions section has moved out of the appxmanifest and into its own networkmanifest.xml. The format inside the <SocketDescriptions> element is virtually identical, just without the mx: prefix.
For cross-play between Xbox and Windows 10, be sure that everything is defined identically between the two different kinds of manifests (Package.appxmanifest for Xbox One and networkmanifest.xml for Windows 10).The socket name, protocol, etc. must match exactly.
Also for cross-play, you will need to define the following four SDA usages inside the
<AllowedUsages>
element in both the Xbox One Package.appxmanifest and the Windows 10 networkmanifest.xml:Multiplayer QoS measurements
In addition to the namespace change in the Secure Sockets API, some of the object names and values have changed, too.The mapping for the typically-used measurement status is found in the following table.
Table 2. Typically used measurement status mapping.
Microsoft Xbox Live Account
XDK (Windows::Xbox::Networking::QualityOfServiceMeasurementStatus) | UWP (Windows::Networking::XboxLive::XboxLiveQualityOfServiceMeasurementStatus) |
---|---|
HostUnreachable | NoCompatibleNetworkPaths |
MeasurementTimedOut | TimedOut |
PartialResults | InProgressWithProvisionalResults |
Success | Succeeded |
The steps involved in measuring QoS (quality of service) and processing the results are in principle the same when you compare the XDK and UWP versions of the API.However, due to the name changes and a few design changes, the resulting code looks different in some places.
To measure the QoS for the XDK, you created a collection of secure device addresses and a collection of metrics and passed these into the MeasureQualityOfServiceAsync() method.
To measure the QoS for UWP, you create a new XboxLiveQualityOfServiceMeasurement() object, call Append() to its Metrics and DeviceAddresses properties, and then call the object's MeasureAsync() method.
For example:
For more examples, see the MatchmakingSession::MeasureQualityOfService() and MatchmakingSession::ProcessQosMeasurements() functions in the NetRumble sample.
Writing game events
Sending game events that are configured in your title's Service Configuration has a different API in UWP.The Xbox Live SDK uses the EventsService and a property bag model.
For example:
For more information, see the Xbox Live SDK documentation.
Tip: Derive a .h header file
![One One](/uploads/1/2/6/4/126483163/423876686.jpg)
You can use the xcetool.exe provided with the Xbox Live SDK (located in the Tools directory) to convert the
events.man
file that you downloaded from Partner Center into a .h header file.Use the '-x' option to generate this C++ header by using the v2 property bag schema.Microsoft Xbox One Xdk Download
This header contains C++ functions that you can call for all of your configured events; for example, EventWriteMultiplayerRoundStart().
If you prefer to use a WinRT interface, you can still refer to this .h header file to see how the properties and measurements are constructed for each of your events.
Game chat
GameChat in UWP is included with the Xbox Live SDK as a NuGet package binary.See instructions in the Xbox Live Programming Guide for how to add this NuGet package to your project.
Basic usage is virtually identical between the XDK and the UWP versions.A few differences in the API include:
Microsoft Xbox Xdk Support
- The User::AudioDeviceAdded event does not need to be hooked up by a UWP title. The underlying chat library handles device adds and removes.
- ChatUser is now called GameChatUser.
- Microsoft::Xbox::GameChat namespace remains the same, but the Windows::Xbox::Chat namespace has become Microsoft::Xbox::ChatAudio.These are the Windows XP Professional Edition boot disk images available from AllBootDisks. Download the diskette image you need, and if you need assistance creating a bootable diskette from this image, visit the how-to page.Windows xp boot disk free download - Windows XP Home Edition Utility: Setup Disks for Floppy Boot Install, Windows XP Professional Utility: Setup Disks for Floppy Boot Install, Windows XP Home.
- AddLocalUserToChatChannelAsync() takes either a XUID or a ChatAudio::IChatUser^ instead of an XboxUser.
- RemoveLocalUserFromChatChannelAsync() requires a ChatAudio::IChatUser^ instead of an XboxUser. You can get an IChatUser from a GameChatUser->User.
Connected storage
The Connected Storage API is provided in the separate Xbox Live Platform Extensions SDK.Documentation is included in the Xbox Live SDK docs.
The overall flow is the same as on Xbox One, with the addition of the ContainersChangedSinceLastSync property in the UWP version.This property should be checked when your title handles a resume event, after calling GetForUserAsync() again, to see what containers changed in the cloud while your title was suspended.
If you have data loaded in memory from one of the containers that changed, you probably want to read in the data again to see what changed and handle the changes accordingly.
Other notable differences in the UWP version include:
- Namespace change from Windows::Xbox::Storage to Windows::Gaming::XboxLive::Storage.
- ConnectedStorageSpace is renamed GameSaveProvider.
- Windows::System::User is used in GetForUserAsync() instead of an XboxUser, and the SCID is now required.
- No local 'machine' storage (that is, GetForMachineAsync() has been removed). Consider using Windows::Storage::ApplicationData instead for your non-roaming, local save data.
- Async results are returned in an exception-free *Result-type object (for example, GameSaveProviderGetResult); from this you can check the Status property, and if there is no error, read the returned object from the Value property.
- ConnectedStorageErrorStatus enum is renamed GameSaveErrorStatus and is returned in the Status property of a Result. All the old values exist, and a few new ones have been added:
- Abort
- ObjectExpired
- Ok
- UserHasNoXboxLiveInfo
![Microsoft xbox one xdk download Microsoft xbox one xdk download](https://assets.windowsphone.com/064c04fc-6851-4f96-b321-e1f515aa58fb/5f3d8dd0-9c2b-49b5-abe4-3f8dc39b3b35_491x276_InvariantCulture_Default.png)
Refer to the GameSave sample or the NetRumble sample for example usage.
Note Gamesaveutil.exe is the equivalent to xbstorage.exe (the command-line developer utility included with the XDK). After installing the Xbox Live Platform Extensions SDK, this utility can be found here: C:Program Files (x86)Windows Kits10Extension SDKsXboxLive1.0Binx64
Summary
The API changes and new requirements outlined in this white paper are ones that you are likely to encounter when porting existing game code from the Xbox One XDK to the new UWP.Particular emphasis has been given to application and environment setup, as well as feature areas related to Xbox Live services, such as multiplayer and connected storage.
For more information, follow the links provided throughout this article and in the following references, and be sure to visit the “Windows 10” section of the developer forums for more help, answers, and news.