By: Steven Hammond, Advanced Technology Group
Updated: December 8, 2015
The manifest included in your application package provides the metadata necessary for your game to interact with the Xbox One system. This goes beyond simple display information in the dashboard. It provides the Xbox Live services with the data necessary to identify your title and grant access to your content in your sandbox. Some system resources and features are not available to title code, such as the extended NUI APIs, unless the required entries are present. Understanding the information that is in the manifest will help maximize the resources available for your game and avoid possible challenges when it comes to debugging some errors that can occur at compile time, runtime, or during deployment.
This white paper provides a detailed overview of your application manifest. There are a number of best practices to keep in mind when writing up your manifest. It is likely that you could run into challenges during development that are linked to entries in your manifest. This short debugging guide includes the most common errors encountered and how to fix them. In addition, a comprehensive reference of the contents of a manifest is included for the details about what every element should look like.
When first approaching the creation of your app manifest (the term used to describe the manifest used for both games and applications), it can appear to be a large and complex document. Although it is easy to simply copy an existing manifest for new projects, it is important to understand each element to fully leverage the available system resources.
Xbox One has a number of unique features, but not all games will use every feature available. Features such as the Kinect HD face-scanning API can be used by games to create novel gameplay experiences with relatively little engineering overhead to integrate into game code. However, these features require a non-trivial amount of system resources, such as CPU time and memory, which could otherwise be used for title processes. Use the app manifest to specify whether you want these features available for your game.
In many cases, such as with Kinect HD face-scanning, if usage is declared in the manifest, the respective API can be used at the cost of reduced system resources available for title code. If you don’t plan to use these features in your game, leaving those entries out of your manifest will allow access to more system resources. In the case of the xbox.system.resources extension, you can even annex some of the GPU and CPU time that is otherwise allocated to system processes.
It can be tempting to simply declare every extended API as being available to your game for the sake of simplicity. Instead, make sure unused features are not included to leave the maximum amount of system resources available for title processes.
When a game is deployed to a development console, it is registered with the system OS so that it can properly be displayed in the dashboard and launch correctly. The information defined in the Applications element is arguably the most fundamental information in the entire manifest. It comprises the majority of the information required to deploy and debug a game or application, so it will likely be the first element defined in your manifest.
Multiple Application entries can be made in the Applications collection in your manifest. When deployed, the system will register each Application on the console even if there is no package associated with it. This allows the flexibility of being able to use the same manifest for multiple builds of your game and differentiating between the builds based on the name of the executable.
For example, if your build system can generate a debug version of your game as well as a release version, they may be differentiated in your build tree by the name of the executable, such as “RumbleDebug.exe” and “RumbleRelease.exe.” An Application can be declared for both builds, and either one can be deployed even if the other is not present. The Applications collection may look like this:
<Applications>
<!--- Debug config -->
<!--- 'Id' is in the aumid returned from deploy -->
<!--- 'Executable' must match the .exe produced by the build -->
<Application Id="NetRumbleIIDebug"
Executable="NetRumble2Debug.exe"
EntryPoint="NetRumble2.App">
<VisualElements>
…
</VisualElements>
</Application>
<!--- Profile config -->
<!--- 'Id' is in the aumid returned from deploy -->
<!--- 'Executable' must match the .exe produced by the build -->
<Application Id="NetRumbleIIDebug"
Executable="NetRumble2Debug.exe"
EntryPoint="NetRumble2.App">
<!--- all fields except DisplayName not yet implemented -->
<VisualElements>
…
</VisualElements>
</Application>
</Applications>
The VisualElements node can contain unique information to help identify which version is associated with which build when working from the console dashboard directly. Deploying either build would register both on the console:
Package Full Name: 'NetRumble2_1.0.0.0_x64__zjr0dfhgjwvde'
115877897 bytes in 36 files over 21.4712337 seconds.
Approximate transfer speed: 5.1468758503648 MB/s.
Aumids returned for this package:
NetRumble2_zjr0dfhgjwvde!NetRumble2Debug
NetRumble2_zjr0dfhgjwvde!NetRumble2Profile
Project associated with aumid 'NetRumble2_zjr0dfhgjwvde!NetRumble2Debug'
If a package is registered but not present, it cannot be run on the console. If one package is deployed and the other is deployed at a later time, both packages will be on the console and able to be launched.
For the sake of simplicity, you can also forego multiple Application entries and allow the packaging utility MakePkg to resolve the name of your executable. This can be done by placing $targetnametoken$.exe in the executable attribute. The token will be replaced by the MSBuild task that’s invoked during the Visual Studio build process. If your build system does not use MSBuild, this may not be a viable option.
This is an example of a configuration that uses the target token name:
<!--- Config -->
<!--- 'Id' is in the aumid returned from deploy -->
<!--- 'Executable' must match the .exe produced by the build -->
<Application Id="NetRumble2"
Executable="$targetnametoken$.exe"
EntryPoint="NetRumble2.App">
<!--- all fields except DisplayName not yet implemented -->
<VisualElements>
…
</VisualElements>
</Application>
This will work regardless of the name of the executable being deployed to the console with the caveat that future deployments will overwrite the registered package. In this case, “RumbleDebug.exe” and “RumbleRelease.exe” could not be registered on the console at the same time, but it would allow the flexibility of adding new build configurations without needing to update your manifest, “RumbleDemo.exe” for example.
A manifest is a single Package element. The root element contains all of the metadata required for your game to operate correctly in the Xbox One dashboard and with Xbox online services. The attributes within the Package element should be the same across all games, but the majority of the information in other elements will be unique to your game or content package. The following sections contain information about when it’s appropriate to use optional elements, and where to obtain data for required elements:
The Package element is the root element of your manifest and should be declared at the top of the file. There should be little or no variation on this:
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest" xmlns:mx="http://schemas.microsoft.com/appx/2013/xbox/manifest" IgnorableNamespaces="mx">
The package manifest is used to define metadata in Windows packages, but this example, along with examples later in this white paper, are specific to Xbox One development.
The second namespace declared allows access to Xbox-specific extensions, and has been given the name “mx”; this namespace is prepended on Xbox-specific elements declared in your manifest. For consistency, “mx” is used throughout this section in examples.
Generally, the first child elements in the Package root element are as follows:
The Identity element provides general identifying information about a product that gets embedded in the binary of the product itself. It contains three required attributes.
| Attributes | Values | Requirements | Example |
|---|---|---|---|
| Name | 3-50 alpha numeric string | Required | Name=”Net Rumble II” |
| Publisher | 1-8192 character distinguished name. It must start with “CN=” | Required | Publisher=”CN=Contoso” |
| Version | Version quad, 4 numbers 0-65535 separated by periods | Required | Version=”1.65533.001.7” |
| ResourceId | 1-30 alpha numeric string | Optional | ResourceId=”NorthAmerica” |
| ProcessorArchitecture | “x86,” “x64,” “arm,” or “neutral” | Optional | ProcessorArchitecture=”neutral” |
The Properties element contains metadata related to the dashboard display information for your product. This includes text descriptions and paths to the images shown in the store and dashboard. The Properties tab does not allow attributes. Information is specified in child elements.
| Child elements | Values | Requirement | Example |
|---|---|---|---|
| Framework | Bool | Optional | <Framework>false</Framework> |
| DisplayName | 1-2048 character string | Required | <DisplayName>Net Rumble II</DisplayName> |
| PublisherDisplayName | 1-2048 character string | Required | <PublisherDisplayName>ATG Gaming</PublisherDisplayName> |
| Description | 1-2048 character string | Required | <Description>ATG’s newest Rumble on the Net</Description> |
| Logo | File path to the logo image | Required | <Logo>media\logos\MainLogo.png</Logo> |
The Prerequisites element contains the minimum requirements of the system for your game to run. Most Xbox One games should have identical information in this element and use only OSMinVersion and OSMaxVersionTested. There are two optional child elements, mx:ApplicationEnvironment and mx:OSName, which provide greater control over the resources that are allocated for your game. This is how it may appear in a game that uses all four child elements:
<Prerequisites>
<OSMinVersion>6.2</OSMinVersion>
<OSMaxVersionTested>6.2</OSMaxVersionTested>
<mx:ApplicationEnvironment>title</mx:ApplicationEnvironment>
<mx:OSName>era</mx:OSName>
</Prerequisites>
The Resources element contains the list of languages that your game or application supports. Upon installation of your game, the system will gather information for each language specified.
| Child elements | Values | Requirement | Example |
|---|---|---|---|
| Resource | Language-locale string pair | At least one, up to 200 | <Resource anguage=”en-us”> |
As of the August 2015 XDK, the list of recognized languages includes:
The Applications collection contains a series of Application child elements associated within the package. In general, each package contains only one application, but defining multiple applications can be very useful during development. For example, the same manifest may be used with completely different applications or different builds of the same application, which may create executable files with different names.
The attributes of an Application element are as follows.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| Id | 1-64 character string | Required | Id=”ATGRumble” |
| Executable | 1-256 character string ending with “.exe” | Required | Executable=”ATGRumble.exe” |
| EntryPoint | 1-256 character string | Required | EntryPoint=”Rumble.app” |
Along with a number of attributes, an Application element also contains child elements, each of which contains metadata used by the system to manage your game and properly begin execution when it is launched.
The child elements in each Application element are as follows:
The Ratings child element of the Application element encapsulates the ratings from various rating agencies that are appropriate for your game or application. This element does not need to be included in your manifest while developing and testing your game, but it must be included in the final package submitted for publishing.
It has one attribute, Category, which specifies whether the target package is a “game” or “application.” It may contain up to 100 Rating child elements specifying ratings from various agencies. Only ratings relevant to the locations where your game will be distributed are needed. An example of a Ratings element would look like this:
<mx:Ratings Category="game">
<mx:Rating>ESRB:T</mx:Rating>
<mx:Rating>PEGI:12</mx:Rating>
<mx:Rating>Microsoft:16</mx:Rating>
</mx:Ratings>
In this example, a game is shipping in multiple regions. If it were a dashboard app, the Category attribute would appear as Category=”application.“ It has been reviewed by ESRB for distribution in the US and by PEGI for distribution in various European territories. It also includes a Microsoft rating, which can be used for games or applications that cannot be rated or are shipping in a region without an official rating board. More information about ratings can be found in the Title Ratings for Xbox One white paper on the Game Developer Network (GDN).
The Extensions element contains a collection of Extension elements, mx:Extension elements, and mx:PackageExtension elements. It is necessary to understand every portion of this section because it is pivotal for making secure network communications.
Unlike most elements, the Extensions collection may be a child of either the Application element or the Package element. Each of the three possible child element types are further specialized by their attributes. Some of these specific types are only available depending on whether the Extensions collection is declared within an Application element or in the broader Package element.
If the Extensions collection is within an Application element, it may contain the windows.backgroundTasks category. It appears as follows:
<Extension Category="windows.backgroundTasks" EntryPoint="Tasks.SampleBackgroundTask">
<BackgroundTasks>
<Task Type="systemEvent" />
<Task Type="timer" />
</BackgroundTasks>
</Extension>
The Type attributes that are legal for the Task element are as follows:
Note Using the audio background task requires an exception. If it is included in your manifest without getting an exception then your title will not pass certification.
These are extensions that can be included in your manifest that are specific to the Xbox One platform. Each instance of the mx:Extension child element includes a Category attribute, which is used to identify the specific extension to include.
The mx:Extension element can include the following child elements:
mx:XboxLive
This element is not necessary for initial setup and testing, but it must eventually be included in the manifest for every game. When using this extension, set the Category of the parent element equal to xbox.live. The mx:XboxLive element provides information to the Xbox One system and Xbox Live services that identify your game. Incorrect or missing information in this element is one of the most common reasons you’ll see the error code 0x8015DC12 from Xbox Live service calls in game code.
The following attributes are in this element.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| TitleId | 8-digit hexadecimal without preceding “0x” | Required | TitleId=”1234ABCD” |
| PrimaryServiceConfigId | 128-bit GUID in the 8-4-4-4-12-digit pattern | Required | PrimaryServiceConfigId="45e10100-80d9-472e-8a03-224f14284938" |
| RequireXboxLive | Boolean | Optional | RequireXboxLive=”true” |
The mx:XboxLive element may also include an optional child element, mx:ConnectedStorage. This element provides the ability for other games to read cloud data saved for your game. It is a collection of mx:AllowReadFrom elements with a ServiceConfigId attribute. Any game with a SCID represented in this collection will be able to read cloud data saved for your game. This introduces the possibility for sequels to a game to be able to gather data from a player’s previous experiences, for example.
This is an example of how it may appear:
<mx:XboxLive … >
<mx:ConnectedStorage>
<mx:AllowReadFrom ServiceConfigId="45e10100-80d9-472e-8a03-224f14284938" />
</mx:ConnectedStorage>
</mx:XboxLive>
Even if you plan to use this element, it is likely that it will not be plausible to populate it with real data at the time your game is released. Instead, it is often the case that a game is updated at the time a future game is released with this collection populated. There is no limit to elements that may appear in this collection.
mx:XboxNetworkingManifest
This element is necessary for using the secure socket API for all game communication between clients and with servers. When declaring this extension, set the Category of the parent element equal to windows.xbox.networking. It encapsulates information about socket and port usage, traffic patterns and usage, and security requirements. An instance of this element contains two required child elements: mx:SocketDescriptions and mx:SecureDeviceAssociationTemplates.
mx:SocketDescriptions
This element contains a collection of mx:SecureSocketDescription elements. Each child element describes the type of information expected to be transmitted and received by sockets that use this description. These descriptions are applied to mx:SecureDeviceAssociationTemplates when they are declared in the same Xbox networking element.
Each element in this collection contains an mx:AllowedUsages collection and three required attributes.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| Name | 1-2047 character string | Required | Name=”ChatRxSocket” |
| SecureIpProtocol | “Upd” of “Tcp” | Required | SecureIpProtocol=”Udp” |
| BoundPort | Single port, or two ports separated by a hyphen | Required | BoundPort=”8000-9000” |
mx:AllowedUsages (Descriptions)
The mx:AllowedUsages collection contains a series of mx:SecureDeviceSocketUsage elements which describe the type of data to be received or transmitted with a socket. Elements in the mx:SecureDeviceAssociationTemplates collection also contain an mx:AllowedUsages collection, but they contain different information. The socket usage instances in the socket descriptions each have a single Type attribute. This collection may appear like this in your manifest:
<mx:SocketDescription Name="ChatRxSocket" SecureIpProtocol="Udp" BoundPort="8700">
<mx:AllowedUsages>
<mx:SecureDeviceSocketUsage Type="Accept" />
<mx:SecureDeviceSocketUsage Type="ReceiveChat" />
</mx:AllowedUsages>
</mx:SocketDescription>
The following values are valid types:
mx:SecureDeviceAssociationTemplates
The mx:SecureDeviceAssociationTemplates is a collection of mx:SecureDeviceAssociationTemplate elements which contain information about the type of endpoints any specific socket will communicate with.
Each instance of a template element in the collection will contain an mx:AllowedUsages collection and four attributes.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| Name | 1-2047 character string | Required | Name=”LobbyChat” |
| InitiatorSocketDescription | 1-2047 character string | Required | InitiatorSocketDescription=”ChatTxSocket” |
| AcceptorSocketDescription | 1-2047 character string | Required AcceptorSocketDescription=”ChatRxSocket” | |
| MultiplayerSessionRequirement | “Required,” “Optional,” or “None” | Required | MultiplayerSessionRequirement=”Required” |
mx:AllowedUsages (Templates)
The mx:AllowedUsages collection contains mx:SecureDeviceAssciationUsage elements that describe the type of endpoints that the socket will be used to communicate with. Elements in the mx:SecureSocketDescriptions collection each also contain a child element called mx:AllowedUsages. The valid values in the allowed usages are different depending on where the collection appears in your manifest. This is an example of how one collection may appear in your template collection:
<mx:SecureDeviceAssociationTemplate Name="LobbyChat" InitiatorSocketDescription="ChatTxSocket" AcceptorSocketDescription="ChatRxSocket" MultiplayerSessionRequirement="Required">
<mx:AllowedUsages>
<mx:SecureDeviceAssociationUsage Type="InitiateFromMicrosoftConsole" />
<mx:SecureDeviceAssociationUsage Type="AcceptOnMicrosoftConsole" />
</mx:AllowedUsages>
</mx:SecureDeviceAssociationTemplate>
The valid values for usage types are as follows:
mx:XboxSystemResources
The mx:XboxSystemResources element allows you to disable NUI services, allowing access to more CPU and GPU resources than would otherwise be available for your game code. When declaring this extension, the Category of the parent element should be set to xbox.system.resources. This element has one optional attribute and one required child element. If you do not intend to use Kinect in your game, we encourage you to include this element in your manifest. It may appear in your manifest like this:
<mx:XboxSystemResources resourceConfiguration=”extended”>
<mx:GpuAvailability>variable</mx:GpuAvailability>
</mx:XboxSystemResources>
If the resourceConfiguration attribute is included and set to “extended,” this will disable NUI speech capabilities that would otherwise be available. This will enable scheduling game threads on the 7^th^ CPU core (logical core 6). System threads may be scheduled on the extra CPU core by the operating system limiting title code to 50-80% of execution time. For this reason, threads scheduled on this core should be limited to threads that are not time-critical.
Typically, the Xbox One system may use between 0% and 3% of the GPU for rendering messages such as game invite toasts. If an application is snapped, the system will use 4% of GPU time every frame. There is no way to programmatically determine how much GPU is available to title code and how much is currently being used by the system. There are two values for the mx:GpuAvailability element that can be used to help manage this:
Each instance of an mx:PackageExtension element has one attribute, Category, specifying what kind of child element it contains. The following are valid values for the Category attribute:
The mx:PackageExtension element can have a number of different child elements. These extensions are only useful in very specific circumstances.
mx:Kinect
Since the launch of Xbox One, the NUI pipelines have been continuously updated. Unlike Xbox 360, Kinect is built into the system instead of embedded into title code in the form of static libraries. Given this, any update made to the Kinect pipelines can potentially affect games that are already released.
The mx:Kinect element gives you the option to lock the version of the pipeline versions. This means that even if the pipelines are updated, your title will continue to use the older pipelines. This will allow you to finely tune speech and skeleton data without worrying about being affected by future updates. If any of these elements are excluded, your title will use the latest available version of each pipeline even if they were a part of a system update released after your title. The element would appear like this:
<mx:PackageExtension Category="windows.kinect">
<mx:Kinect IsVersionLocked="true">
<mx:AudioPipeline Version="1.0.0" />
<mx:SpeechPipeline Version="1.0.0" />
<mx:VisionPipeline Version="1.0.0" />
</mx:Kinect>
</mx:PackageExtension>
The following versions are available for all pipelines:
The AudioPipeline element may also be set to “1.1.0.”
The IsVersionLocked attribute on the mx:Kinect element should be set to true if you use this extension. Setting it to false will revert back to the default behavior of using the latest version of each pipeline.
mx:ContentPackage
The mx:ContentPackage element is required for all DLC packages. It includes two required child elements. The first is mx:AllowedProduct, which contains a single attribute, Id. The Id attribute is set to the product ID of the parent game for which the DLC is to be used with. The product ID of your parent game can be found on the Xbox Developer Portal.
The second child element is mx:ContentPackageVisualElements. It has a number of required attributes that define how it will appear in the Xbox One dashboard. The attributes of this element are identical to the attributes of the VisualElements element found in an Application element.
This is an example of an mx:ContentPackage element:
<mx:PackageExtension Category="xbox.contentpackage">
<mx:ContentPackage>
<mx:AllowedProduct Id="0eafd21d-2911-4be5-95fb-6dc0b50b6152" />
<mx:ContentPackageVisualElements
DisplayName="ATG Rumble II DLC"
Logo="Logo.png"
SmallLogo="SmallLogo.png"
WideLogo="WideLogo.png"
Description="Add more rumbling!"
ForegroundText="dark"
BackgroundColor="#000040" />
</mx:ContentPackage>
</mx:PackageExtension>
mx:XboxStore
The mx:XboxStore element should be included in the manifest of any DLC packages. It contains one required child element, mx:RelatedProducts, and one optional child element, mx:TrialLicense.
The mx:RelatedProducts is a collection of mx:RelatedProduct elements which specify which games are able to enumerate the content.
The mx:TrialLicense contains a single attribute, SuspendOptOut, which controls how the trial timer behaves when the game that’s using the content is suspended if it is running in trial mode.
The entire element might appear like this in the mx:PackageExtensions collection:
<mx:PackageExtension Category="xbox.store">
<mx:XboxStore>
<mx:RelatedProducts>
<mx:RelatedProduct Id="0eafd21d-2911-4be5-95fb-6dc0b50b6152" />
<mx:RelatedProduct Id="00000000-0000-0000-0000-000000000000" />
<mx:TrialLicense SuspendOptOut=true"/>
</mx:RelatedProducts>
</mx:XboxStore>
</mx:PackageExtension>
In this example, the content can be enumerated by the product with the product ID “0eafd21d-2911-4be5-95fb-6dc0b50b6152” and the product associated with the zero GUID (the most recent game deployed and launched through Visual Studio).
By default, all games remain in the Constrained PLM for 10 minutes when the game is hidden from view by a dashboard app. The trial timer continues to run while the game is constrained. In this example, the trial license is set to true, which circumvents this ten-minute timer suspending the game immediately after it is hidden from view. This stops the trial timer immediately instead of potentially burning 10 minutes of trial play time for a player. However, suspending a game immediately can potentially have an adverse effect on the gameplay experience. For example, it may kick a player out of a multiplayer game immediately when the player intended to open the Friends app for only a moment. Whether this should be included in your manifest is an option that should be carefully considered for your game.
mx:Storage
The mx:Storage element should be considered for games that require storage solutions that are not accommodated by the connected storage APIs. This element allows usage of persistent local storage (PLS) on a console. It circumvents the need to sync with cloud data with the caveat that the storage will not necessarily be available on other consoles. Its usage would appear like this:
<mx:PackageExtension Category="xbox.storage">
<mx:Storage>
<mx:PersistentLocalStorage SizeInMegabytes="1000" />
</mx:Storage>
</mx:PackageExtension>
The SizeInMegabytes attribute determines the amount of local storage that will be available to your title. The value can range from 256 MB to 4096 MB.
Note The use of this extension requires an exception. Please work with your Microsoft representative if you believe your game provides sufficient business justification for using persistent local storage. If your game uses this extension, it will be rejected during certification if you do not have an exception.
The VisualElements element contains information about how the game or application should appear in the Xbox One dashboard.
The VisualElements element includes the following attributes.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| DisplayName | 1-256 character string | Required | DisplayName=”Net Rumble 2” |
| Logo | 1-256 character string ending with “.png” | Required | Logo=”logos\big.png” |
| SmallLogo | 1-256 character string ending with “.png,” “.jpg,” or “.jpeg” | Required | SmallLogo=”logos\small.jpg” |
| Description | 1-2048 character string | Required | Description=”The next evolution of Net Rumble is here! Now with better…” |
| ForegroundText | “light” or “dark” | Required | ForegroundText=”light” |
| BackgroundColor | Three-byte hexadecimal code preceded by “#” | Required | BackgroundColor=”#0000FF” |
The VisualElements element contains the following child elements:
The DefaultTile element contains information about how the game or application will appear in the collection in the Xbox One dashboard. It contains no child elements and up to three attributes. The DefaultTile element is not required, but it is highly encouraged to include it in your final build submitted.
| Attributes | Values | Requirement | Example |
|---|---|---|---|
| WideLogo | 1-256 character string ending with “.png” | Required | WideLogo=”logos\wide-480.png” |
| ShortName | 1-40 character string | Optional | ShortName=”Rumble” |
| ShowName | “allLogos,” “noLogos,” “logoOnly,” “wideLogoOnly” | Optional | ShowName=”logoOnly” |
The SplashScreen element contains information about the splash screen image displayed to the user after it is launched and before it starts running. It has no child elements and up to two attributes.
| Attributes | Values | Requirement | Example |
| ———- | —— | ———– | ——- |
| BackgroundColor | Three-byte hexadecimal code preceded by “#” | Optional | BackgroundColor=”#00FF00” |
|Image | 1-256 character string that ends with “.png” | Required | Image=”logos\splash.png” |
The mx:ViewStates element is an optional element that holds a collection of sub-elements indicating which view states are valid for a dashboard app. It is not used for games. If mx:ViewStates is present, it must contain either one or two mx:ViewState child elements. Following is an example of how it may appear:
<mx:ViewStates>
<mx:ViewState Name="snapped" />
<mx:ViewState Name="filled" />
</mx:ViewStates>
In this example, this application can be displayed in either full screen mode or as a snapped app. Removing one of the mx:ViewState entries prevents the application from running in that mode. For example, the built-in Party app would not contain the “filled” element, and it only runs as a snapped app.
After declaring your Applications element, the next element usually included in your manifest is the Capabilities element. This element does not need to be present when testing your game, but there are some capabilities that are required to pass certain Xbox Requirements (XRs), such as the kinectAudio and kinectGamechat capabilities to enable game chat.
The Capabilities element may contain a collection of up to 10 Capability and mx:Capability elements, and up to 100 DeviceCapability elements. These limits leave room for future platform growth; there are currently fewer of each type of capability than the limits. There are no attributes that can be included in this element.
The Capability and mx:Capability child elements of the Capabilities collection specify what system resources are required by the game. Each declaration of a Capability will take some system resources, CPU time, and memory, which would otherwise be available for title usage. For this reason, make sure all Capability declared is required.
Following are the capabilities that can be added to the collection.
| Values | Requirement | Example |
|---|---|---|
| internetClientServer | Conditionally required (see notes following this table) | <Capability Name=”internetClientServer”/> |
| privateNetworkClientServer | Conditionally required (see notes following this table) | <Capability Name=”privateNetworkClientServer”/> |
| kinectRequired | Optional | <mx:Capability Name=”kinectRequired”/> |
| kinectVision | Optional | <mx:Capability Name=”kinectVision”/> |
| kinectAudio | Required | <mx:Capability Name=”kinectAudio”/> |
| kinectExpressions | Optional | <mx:Capability Name=”kinectExpressions”/> |
| kinectFace | Optional | <mx:Capability Name=”kinectFace”/> |
| kinectGamechat | Required | <mx:Capability Name=”kinectGamechat”/> |
| contentRestrictions | Optional | <mx:Capability Name=”contentRestrictions”/> |
The DeviceCapability elements included in the Capabilities collection define requirements needed for your game to run. If these requirements are not present, your game will not launch. Two possible values can be included in your manifest.
| Values | Requirement | Example | Notes |
|---|---|---|---|
| 6a7e5907-885c-4bcb-b40a-073c067bd3d5 | Optional | <DeviceCapability Name=”6a7e5907-885c-4bcb-b40a-073c067bd3d5”/> | PSPSRA: This value indicates that the game or applications require PlayReady in order to operate. |
| C546B8CB-D91D-4DEE-ADE3-AAED563F105 | Optional | <DeviceCapability Name=”C546B8CB-D91D-4DEE-ADE3-AAED563F105”/> | VDKMD: This value indicates that a virtual graphics driver is required by the game. |
Application package manifests are mostly associated with the packaging and deployment of a game or app. However, neglecting to include critical information or putting inaccurate information in your manifest may result in errors generated at compile time, run time, or when deploying your game. It is important to make sure your manifest is complete and accurate for all game packages. This includes content updates and DLC as well as game packages. This section goes over some common errors that will occur if the information in your manifest is not correct.
This error code can be returned from a number of places within your title. If you’re seeing it when attempting to sign in to a test account from the dashboard, it is likely caused by issues outside of your manifest. However, if you are able to sign in to a test account in the dashboard, but are seeing this when attempting to sign in to a profile within your game or it is returned from calls to Xbox Live, it is likely an issue with your manifest.
This error code is the Xbox Live services actively rejecting queries due to sandbox restriction, also known as content isolation. This will happen when attempting to reach a resource that is associated with a certain sandbox from a game that is not associated with that sandbox.
The information specified in the xbox.live extension in your Extensions collection is responsible for making sure that the console and service know which title is running. If this is missing from the Extensions collection or there is a typo in the attributes, the service will assume that an unknown title is attempting to access data from your sandbox and will reject the query.
Pressing F5 to start debugging in Visual Studio will execute three actions: build, deploy, and execute. If there’s a problem during the compile or deploy phase, details will be displayed in the Output window in Visual Studio. Problems in the manifest caught at compile time will have specific information about the section of the manifest that is invalid. Deployment problems, however, will emit an error with very little detail:
Run this command again using the /VM flag to enable detailed manifest validation.
The most common reason for seeing this message is missing files specified in your manifest. The following files must be in the layout:
If you’ve made sure that all of the image files specified in your manifest are present, further debugging will be necessary. As the message emitted from Visual Studio suggests, using the XbApp utility to deploy the package will provide more information. Adding the /VM flag to the command line passed to the utility will increase the output verbosity and provide more information about the origin of the problem.
xbapp deploy C:\path\to\build\image /VM
This problem will crop up when attempting to install DLC or a content update for testing. If there’s a problem in the manifest, this error message will be emitted on the command line:
“The package being updated does not exist or there is a contentid or encryption mismatch. Please check that the package can be updated.”
The cause of this error is generally mismatched information in the Identity element of the manifest. This can occur if there is a problem with any of the attributes. Ensure that:
There are a few samples on GDNP that demonstrate game chat, such as In Game Chat and Positional Chat. With two consoles, headsets, and two friend test accounts, they will work with minimal setup. However, it is easy to overlook required elements in the manifest when simply copying the code into your own test project or game.
If you’re unable to capture and render game chat, make sure you have included kinectAudio and kinectGamechat in the Capabilities collection. Even though these are Kinect capabilities, they are required for chat to function over headsets. Because these are required for the chat to operate, they will need to be included in the manifest for every game to meet all XRs.
If you’re launching your game through the Xbox One dashboard, it may crash before title code even starts running. The splash screen will be displayed for a short time, but crash back to the landing page of the dashboard.
If you’re working through the command line by launching your game with the “xbapp launch” command, this error will be emitted:
“The application has exited or crashed before completing activation”
This problem can be caused by a mismatching executable name specified in your Application elements, or by attempting to launch the incorrect AUMID if there are multiple instances of Application elements in your Applications collection.
If you are not using the $targetnametoken$ specifier for the value of the Executable attribute, make sure that the spelling is an exact match for the executable generated by the build. If there are multiple Application entries, make sure that you’re launching the correct entry. The value specified in the Id attribute is used in the AUMID and will appear after the ‘!’ when the installed packages are listed on the command line. The DisplayName attribute of the VisualElements child element determines what will be displayed in the dashboard. Make sure these values are unique for each Application entry to more easily differentiate between packages.
Your application manifest is the link between your game and Xbox One. It determines how your game is presented to the user when it isn’t running, and how resources are allocated to your game when it is running. It is also the link between your game and Xbox Live. Understanding your manifest will enable you to provide accurate information and make informed decisions to better leverage the resources available to you on Xbox One.