Creating, examining, and testing content updates

Tip

Using MSIXVC2? To compare update sizes between MSIXVC and MSIXVC2, package both builds by using makepkg2. For more information, see Content updates with MSIXVC2 and Getting started with MSIXVC2 for PC.

Overview

This article explains how to deliver content updates, the tools you use to generate and measure updates, and how to test key update scenarios to ensure expected and optimal behavior.

How content updates work

Gaming services always minimize the number of bytes that need to be transferred when you provide an update to game packages. This optimization applies to both customers on gaming devices and developers when uploading packages. The system computes this difference (delta) by using algorithms that, at a high level, attempt to maximize the matches of 4-KiB segments between two packages.

The system encodes this delta as part of .xsp (update streaming plan) files. By using these files, the system knows exactly what bytes to download from the network and how to apply them to any possible existing package version.

To simulate and test accurate delta update behavior in development, use the proper makepkg options to create packages. Also, use the proper commands to install and update packages.

Create an update based on a previous package version

Use makepkg pack to create packages. To create a package that uses a previous package, use the /priorpackage parameter:

makepkg pack /f chunks_layout.xml /d [build directory] /pd .\output /priorpackage [previous version].xvc

The previous package must have the same package identity as the package you're creating, as defined in the microsoftgame.config.

The command creates an .xsp file named [new package name]_update-[old version number].[guid].xsp. For example, 41336MicrosoftATG.ATGGameHubRequiredGame_200.0.0.0_neutral__dspnxghe87tn0_xs_update-100.0.0.0.5890f4a0-b449-4c5d-80ff-b78b19ed3439.xsp

This file is the streaming plan that encodes what needs to change when updating from the old to the new package. The section on testing updates demonstrates how to use this plan.

Examine update size

When you run the preceding command, it generates two additional files with the same filename: an .html file and a .json file.

Both files contain the following information:

  1. A summary of the bytes that the update downloads
  2. A table that summarizes the amount of data that the update installs for a specific tag, language, or device type
  3. A sortable table of files that shows the number of bytes the update changes and the percentage of the overall file size this change represents
  4. For each file that isn't 100% updated, links to individual tables that show the ranges of data in each file that the update changes

Use this information to identify which files are most changed in an update. Look at the individual files to see if the proportion and location of changes are as expected. If you see files that result in a bigger update than usual, review the guidelines found in the Authoring updates efficiently section.

packageutil compare on the two .xvc files also generates these same files and provides a summary output of the package differences. This command also generates the .xsp file.

Delta uploads

Uploads to Partner Center will automatically take advantage of the delta computation algorithms. The delta between your last uploaded package (for that branch) and the uploading package is computed at the beginning so that only the changed data will be transferred from the upload machine to the ingestion service.

Testing updates

To validate the update size as seen in the system UI, perform the following steps:

  1. xbapp install [old version.xvc]
  2. xbapp update [new version.xvc] (/plan=[.xsp file])

When updating, go to the Queue in the system UI to see the friendly number of bytes that's being updated.

The /plan parameter is optional if the .xsp was previously generated by other commands and is in the same location as the .xvc files.

On PC, the wdapp command is used instead. Package files have the .msixvc file extension, and installation and update progress can be seen in the download queue section in both the Xbox app and Microsoft Store app. wdapp update doesn't support the /plan parameter. It uses the .xsp file generated for the target version if one was created.

Advertising updates

Advertising updates is slightly different from other update methods. When you advertise an update, you make the update available to the game, which results in specific system behavior.

To advertise an available update, apply the /m or /a flag to xbapp or wdapp update. This action results in the update not being applied until the game is launched. When this condition happens:

  • Console: a system dialog shows stating an update is required.
  • PC: for dev builds, no system prompt shows, and the build can freely be launched, unless the build is installed by using wdapp install or the bootstrapper. In this case, launching the game invokes the PC bootstrapper, which checks for and prompts you to install updates.

Advertising the update also results in certain XStore APIs to react, which allows the game to detect available updates. This behavior is most relevant to DLC packages. For more information, see Checking for updates.

Store package updates

The preceding examples involve installing and updating by using local packages. In some scenarios, you might want to test updates by using packages that you uploaded to Partner Center and downloaded from the Store CDN. This process validates two things: performance when updating from the Store, and utilizing the streaming plan that is generated as part of the ingestion process.

Unfortunately, you can't update from a local package to a Store package due to signing differences. What you can do, without other help, is upload a single version to Partner Center and then install that version from the Store app on one or more devkits. Then, upload the new version. When the new version is published, on the devkits with the older version installed, verify that the newer version is detected and can be updated by using the expected delta size.

To repeat this test, before updating, copy the old version installation to an external drive so you can copy it back over any new version later. If you didn’t save this version, you can request the CDN URL from which an older version can be installed by using xbapp install or wdapp install. After you install an older version, you can repeat the update test.

Hybrid disc and CDN updates

Updates also apply to optical disc installations. When you install from a disc, the installation process installs any disc contents that are unchanged relative to the latest available digital package from the disc. The installation process concurrently installs the rest of the contents from the Store CDN. This process happens automatically.

To simulate this process, use the following command:

xbapp update http://server/[latest version].xvc /p:[disc package].xvc`

Serving the update package through an HTTP server is a workaround for the fact that an installation can only have one source from the development PC's local storage.

If you burn a test disc by using the disc .xvc package, the disc package can point to the optical disc path.

See also

Content update best practices

Checking for updates

  • Last updated on