Title Packaging, Content Updates, and Streaming-Installation Testing

This white paper describes how to create packages for streaming installation for local iteration, performance validation, pre-submission testing, and final submission. Readers will come away with a clear understanding of the steps executed by the MakePkg tool during the packaging process, as well as the recommended steps for packaging and streaming-install testing during development.

The topic has been updated to reflect several changes that have come about since it was originally published in October 2013. Specifically, the paper has been revised to:

Introduction

MakePkg.exe is a tool that places content into a binary packaged file, referred to as an Xbox Virtual Container (XVC). XVCs do not have the file name extension of .xvc; instead, the file name produced during packaging reflects the Package Full Name, as referenced by xbapp and associated development tools.

MakePkg.exe uses your title’s content and a mapping file as input to produce packages that are encrypted with either a well-known test key or a randomly generated key, depending on whether the package will be used for local testing or submission to Microsoft for publishing.

The XML in the mapping file serves two purposes. First, it specifies the location of files that will be available to the title at runtime. Second, it specifies the chunk file to which each file belongs. A set of chunks, known as the launch set, are always installed before a title is allowed to run. The remaining chunks are installed while the title is running. APIs are available to query the progress of chunk installation and to modify the installation order of chunks that aren’t yet installed.

In this topic:

Steps during packaging

The MakePkg packaging process can be broken down into several steps.

AppXManifest.xml and file-existence validation

The MakePkg command verifies that the AppXManifest.xml file located in the content source directory is valid and will successfully install on an Xbox One console that has been updated with the corresponding recovery system image.

When MakePkg is run with the appdata command, it generates an AppData.bin file, which captures information about the binaries to be registered within the GameOS. This command is automatically run if your title builds from Visual Studio. If you have a separate build system, to generate an AppData.bin file you must run MakePkg appdata against the directory that contains the AppXManifest.xml of your title build output. Your title must include this AppData.bin file in the XML map file provided to the MakePkg pack command.

When the MakePkg pack command is run, it makes sure that files referenced within the AppXManifest.xml are in the source directory and are validated to ensure that they will be packaged into the launch set. This includes binaries, image files, and any other resources.

Submission validation

MakePkg automatically runs Submission Validator (SubmissionValidator.dll) against the title files before creating the XVC, unless MakePkg was launched with the command-line option /lu, which specifies creation of an unencrypted XVC. Creating unencrypted XVCs is generally not recommended, because running from unencrypted packages will not have representative performance characteristics of the retail console and content configuration. The goal of the Submission Validator is to check for errors and mistakes that can cause problems for titles later in the ingestion, mastering, or certification processes at Microsoft or in future content updates.

When building a package for submission using the /l switch, MakePkg will not create the XVC if any submission-validation failures are detected. All detected problems will need to be corrected before a signed XVC can be generated for upload to the Xbox Developer Portal (XDP). When building a package without the /l switch, an XVC will be created even if validation failures are detected. This enables developers to identify and fix issues without blocking their local testing of test-signed XVCs.

The submission-validation process generates an XML log file detailing the nature and location of any failures. This log file will be written to the same location specified by the /pd parameter of MakePkg for output of the XVC file. This log may contain failures or warnings. Failures must be addressed before an XVC can be submitted to Microsoft. Warnings should be considered for remediation to ensure that titles comply with policy and Xbox Requirements (XR) guidance.

The submission-validation process also runs CUdiff.exe, a tool for comparing content updates, which reports the content in the submission in a format that allows easy comparison against future versions. You can compare reports from CUdiff.exe to understand the effect of content updates on your title.

Note CUdiff.exe currently does not take file-based content-update semantics into account. If you are using file-based content update, you should use the packageutil compare command against two packages to understand the size of your content update.

When an XVC is uploaded to XDP and published to the mastering process, the validation checks will run again. This ensures that the title is checked using the latest version of the Submission Validation tool and that any problems are caught as early as possible.

Submission-validation tests
Foreign files Verify that the title contains no prohibited files. Prohibited files include source and debug files (*.c, *.cpp, *.obj, *.lib, *.cs, *.h, etc.), Xbox 360 executables (*.xex), and any system files that are contained in the GameOS volume.
App manifest A variety of manifest checks not performed by MakePkg:
  • Background audio extensions.
  • Non-default link protocol registration.
  • Resolution and bit depth of logo and splash-screen images.
  • Presence of Title ID and SCID.
BinscopeVerify that the correct version of Binscope is installed on the computer on which the test is running and execute a selected set of Binscope checks applicable to the Xbox One platform.
Note
If the appropriate version of Binscope is not installed and the tests cannot be run, this will be logged as a failure and must be corrected before the title can be submitted.
Jscript shared app checksFor these applications, additional checks will be executed to detect common types of coding-practice issues.
Binary scanAll EXEs and DLLs will be scanned. Any managed-code binaries will cause a failure. Other problems that will be detected include non–Xbox One executables, 32-bit executables, and so on.

The specific tests will evolve over time as new issues are identified. Passing the Submission Validator checks should not be construed as an indication that other issues will not arise with the title submission during the ingestion and certification process. Rather, the intent is merely to reduce the time and cost of rejections resulting from foreseeable errors. Furthermore, although the Submission Validator may check for certain security-related issues, it should not be viewed as a security test for a title.

You can download the latest version of Submission Validator from the Xbox Game Developer (XGD) site. Because the tool may evolve at a different pace than the XDK releases, be sure that you are using the latest version to avoid any validation-failure rejections in the submission process. The latest version is available from Certification Tools on XGD.

For more information about Submission Validator, see Submission Validator (SubmissionValidator.dll) in this XDK documentation.

Contact your Developer Account Manager with any questions regarding the validation process.

Binary signing

Files in your title are scanned and signed using Xbox Code Integrity (XCI). PE headers detected in files are modified as part of this process before being written to the XVC file. If signing fails, an error message will be reported, along with a command to manually re-run xcihash.exe to gather more details about the signing failure.

Package creation

As soon as MakePkg has completed the pre-validation steps, an XVC container is created and mounted on the development PC. This step requires an XVDD driver, which is installed as part of the XDK setup. You might see a drive-arrival notification on your development machine as part of mounting this volume; it is safe to ignore this notification. MakePkg then copies the source files including the signed executables into the XVC file in the chunks specified by the XML map file.

The last step of package creation involves embedding a GameOS file (era.xvd). This file is shipped as part of the XDK and is required to be in the layout directory next to the executable for your game. The /gameos flag allows specifying an alternate source location for the GameOS file.

Encryption

This section of the document has been updated to reflect a change made in the March 2014 XDK to test-encrypt packges by default. The default behavior of MakePkg.exe now matches the previous behavior that resulted from using the command-line option /lt. You can get the previous, unencrypted behavior by using /lu, a new flag.

The default MakePkg behavior is to create test-signed packages. Test-signing encrypts the generated XVC file by using a well-known test encryption key, intended for performance testing validation, for running on Xbox One development kits (dev kits). Although the effect of real-time package decryption performed on Xbox One is designed to be transparent to the title, this flag is exposed to ensure that any possible performance issues resulting from encryption are discovered before certification and final mastering of titles. Test-signed packages are not intended to be used for cryptographically securing content, because the encryption uses a fixed key. A test-signed package can be installed on a dev kit by using xbapp install.

The MakePkg /l switch will encrypt the XVC file with a randomly generated encryption key. In addition to your title package, MakePkg /l will emit a file with a name in the format PackageFullName*licenseName*GUID.EKB. (Note the use of the underscore character.) Packages created with the /l switch cannot be installed on a dev kit, so you should test your title by using test-signed packages until the title passes all checks and pre-submission tests. After reaching that state, run MakePkg with the /l switch before final submission to Microsoft.

Recommended steps for packaging during development

For creating packages during development, we recommend the following steps:

  1. Iterate locally using test-signed packages and xbapp install from your development PC.
    MakePkg.exe pack /fMapfile/dLooseContentDir/pdOutputFolder
    To get started, see Streaming Install (Developer Education Materials > All NDA Samples), a code sample available for download from Samples on XGD.
  2. Run your title by launching from the shell or using xbapp launch.
    xbapp installlocal-XVC-path or xbapp installhttp-URI
    To test alternate options for streaming installation, see Testing of streaming-install packages, later in this document.
  3. Test title installation from the optical disc drive (ODD) by using a test-signed package burned to a BluRay disc in the root folder. After inserting the disc into the Xbox One dev kit, run:
    xbapp install XO:*XVC-file-name*
  4. Prepare your final submission using the same packaging command as your test-signed package, using the /l flag.

Testing of streaming installation packages

There are four ways to test the installation of test-signed streaming installation packages:

Stream from the development PC

Streaming from the development PC does not support any throughput throttling, so the speed of the installation will be dependent on the processor and I/O characteristics of your development machine, as well as the bandwidth of the network connection between the development machine and the dev kit. Speeds of 300 Mbps (approximately 36 MiB/s) or higher can be expected over gigabit Ethernet connections from modern development machines with mechanical hard drives.

xbapp installdev-pc-path-to-XVC

Host the package on a web server

If your web server supports configuration of bandwidth throttling, hosting the package on a web server allows simulation of different network delivery speeds. The Xbox One platform handles connection failures and retry logic, so your title should run the same when installing from an Internet source as from an optical disc, aside from speed.

xbapp installhttp-URI-to-package

Burn the package to a disc and install from a command line

Burn an optical disc with your XVC in the root directory and install the package by using the following command:

xbapp install XO:*xvc-file-name*

Burn the package to a disc and install through the shell

Burn an optical disc with a folder named MSXC that contains your package.

Insert the disc into a running dev kit. The shell will automatically start installing your title, and the dev kit will display a notification after the launch set has been installed and the title is launchable.

Best practices

Best practice

For new titles, use file-based content updates, which reduce the size of content updates. Author your package layout to ensure optimal content updates in the future.

For more information about authoring package layouts, see Designing Title Package Layouts for Updates: Best Practices and Guidelines.
Best practice

Read Xbox Requirement (XR) 034, Streaming Install Initial Play Marker, and validate that your launch set is smaller than 5 GB.

Your title’s set of launch chunks and associated metadata must be smaller than 5 GB to ensure a consistent start-up time for users. For more a complete description of XR-034, see Xbox Requirements on XGD.
Best practice

Test your title while it’s being installed from various sources and different speeds.

The xbapp command allows installing from developer-burned optical media, as well as from packages hosted on HTTP servers.
Best practice

Always use the most up-to-date version of the Submission Validator.

For more information about Submission Validator, see Submission Validator (SubmissionValidator.dll). The latest version of Submission Validator is available from Certification Tools on XGD.

Resources and guidance

This section lists some white papers, documentation, and presentations on how to implement streaming install for your title.

Samples

The following code samples are available for download from Samples on the Xbox Game Developer (XGD) site:

Xfest presentations

When viewing conference presentations, keep in mind that they might contain information about features that were still under development at the time of the conference, and that information might now be stale. Therefore, you should consider the published Xbox One XDK documentation as having the most up-to-date information.

Xbox One documentation

You may want to familiarize yourself with the following topics—useful jumping-off points in the XDK documentation:

White papers

The following white papers are available as topics in the Xbox One XDK documentation: