The syntax for invoking MakePatch via the command line is described below:

make_patch.py [options] <source-path> <dest-path> <patch-output-path>

The three required arguments (one source path for each source version that the patch will support) are described below:

The available options are described below:

The MakePatch tool generates a patch archive, which is a tarfile with the following:

The directory tree versions are given names indicating their version (e.g., bw_res-1.9.0). The only requirement for a version is that they be a string - they do not have to conform to any convention, but it may be wise to have some scheme where the target trees are identified by name and a version string appended to the target name.

Currently, you can specify more than one source version to provide changes against the destination version. This could be used to make a patch multi-versioned, that is, supporting multiple released versions by combining their changes from each supported source version into a single patch archive. However, this is discouraged, as it is much better for the CheckVersion script or equivalent to handle selection of individual patches to download from the versions file (for details on CheckVersion, see CheckVersion).

The changes for a particular version consist of the following:

The manifest file contains instructions on which files to add, modify or delete, as well as checksum information. By default, checksums are generated for modified files only. However, you can use the --use-checksums-if-unmodified option to have checksums generated for every file encountered in the source directory tree. If checksums are present in the manifest file, then they will each be checked.

MakePatch supports patch files that contain changes for multiple sources, intended against either multiple targets and/or versions.

This means that for a group of targets, changes for each target from one version to another can be bundled into the same patch archive.

This also means that for a particular target the changes for multiple versions of that target can be contained within the same patch archive. Typically, however, it is more advantageous to have a single-version patch files for each released version, and rely on VersionCheck and the versions file to drive the patching client to download a single-version patch. This is more flexible and saves on download bandwidth.

Changes for multiple sources can be added at the archive creation, or they can be added to an existing patch archive by re-running MakePatch with the same patch archive as the patch output path.

The syntax for invoking ApplyPatch via the command line is described below:

apply_patch.py [options] <patch-path> <target-path> <target-version>

-h, --help            show this help message and exit
--debug-level=LOGLEVEL one of DEBUG, INFO, WARNING, CRITICAL, ERROR

The three required arguments are described below:

The available options are described below:

The syntax for invoking CheckVersion via the command line is described below:

usage: check_version.py [options]

options:
-h, --help            show this help message and exit
-c CONFIGPATH, --config=CONFIGPATH
                      The patcher configuration file that contains the
                      versions.xml URL. Defaults to "patcher_config.xml".
-s STATEPATH, --state=STATEPATH
                      The state file. Defaults to "state.xml".
--debug-level=DEBUGLEVEL
                      The logging debug level. Defaults to "INFO".

This file contains upgrade paths for past released versions to upgrade to the current version. Functionality for parsing this XML document is supplied via the VersionsXML class (for details, see The versions module).

The versions file is downloaded from a URL contained within the configuration file, defaulting to a patcher_config.xml in the current working directory, and is parsed using the simple Config class in check_versions.py. Developers may wish to change this scheme when developing their own update client.

An example versions file is supplied in bigworld/tools/misc/offline_patcher/examples/versions.xml.

The example file below describes an upgrade path from a past released version of a theoretical game from an initial version 1.0 to a new current version 1.1. In the example, there are three targets for which there are patches for:

<?xml version="1.0"?>
<root>
  <currentVersion>1.1</currentVersion>
  <property name="baseURL">http://update.yourgame.com/downloads</property>
  <supportedVersions>
      <version>
          <name>1.0</name>
          <property name="updateInfoURL">info/test.php</property>
          <targets>
              <target>
                  <name>your_game_res</name>
                  <path>../your_game_res.zip</path>
                  <sourceVersion>1.0</sourceVersion>
                  <destVersion>1.1</destVersion>
                  <patch>
                      <transferType>http</transferType>
                      <name>your_game_res.1.0-1.1.patch</name>
                      <property name="url">patches/your_game_res.1.0-1.1.patch</property>
                      <property name="md5sum">00112233445566778899aabbccddeeff</property>
                  </patch>
              </target>
              <target>
                  <name>your_game_bin</name>
                  <path>.</path>
                  <sourceVersion>1.0</sourceVersion>
                  <destVersion>1.1</destVersion>
                  <patch>
                      <transferType>http</transferType>
                      <name>your_game_bin.1.0-1.1.patch</name>
                      <property name="url">patches/your_game_bin.1.0-1.1.patch</property>
                      <property name="md5sum">00112233445566778899aabbccddeeff</property>
                  </patch>
              </target>
              <target>
                  <name>bigworld_res</name>
                  <path>../bw_res.zip</path>
                  <sourceVersion>1.9.3.0</sourceVersion>
                  <destVersion>1.9.4</destVersion>
                  <patch>
                      <transferType>http</transferType>
                      <name>bw_res.1.9.3.0-1.9.4.patch</name>
                      <property name="url">patches/bw_res.1.9.3.0-1.9.4.patch</property>
                      <property name="md5sum">00112233445566778899aabbccddeeff</property>
                  </patch>
              </target>
          </targets>
      </version>
  </supportedVersions>
</root>

Example versions file

Note that version 1.1 of the overall game uses 1.9.4 BigWorld resources over version 1.0's usage of 1.9.3 BigWorld resources. This illustrates that the versioning of the individual targets is independent from the overall game versioning.

This is only an example layout for a theoretical game. Game developers must take into account the requirements of their game when partitioning their resources into suitable resource trees.

<property name="key_name">value</property>

The state file specifies for each target which version is currently installed on the end-user's distribution. This is only a simple implementation - developers may choose to implement persistence of target state in another way as part of their launcher process (e.g., Windows Registry keys). Other implementations should implement the Python State interface for reusing the rest of the CheckVersions script and the versionslib library.

An example state file is supplied in bigworld/tools/misc/offline_patcher/examples/state.xml. It corresponds to the supplied example versions.xml versions file.

Functionality for parsing the state XML file is supplied in the form of the StateXML class defined in the versionslib.state module (for details on this class, see The state module).

<?xml version="1.0"?>
<root>
  <currentVersion> 1.0 </currentVersion>
  <targets>
      <target name="your_game_res"> 1.0 </target>
      <target name="your_game_bin"> 1.0 </target>
      <target name="bigworld_res"> 1.9.4.0 </target>
  </targets>
</root>

The CheckVersion script relies on patcherlib for applying patches to targets. Deploying this may involve compiling all the .py files to .pyc or .pyo files, then adding them in a ZIP archive and placing in the Python library path.

The game launcher must run script methods for checking against a versions file to verify that its version is up-to-date. This requires that a Python interpreter be involved at some point in the game launch process, which implies that the launcher is itself a Python script or an executable that is linked against the Python runtime library.

There is currently only one method of transport for patches: HTTP. However, the versions file syntax can allow for more transport schemes (such as BitTorrent, for example). Transport schemes are specified as part of the delivery element in the versions document - e.g., consider the following example versions file fragment:

<patch>
 <transferType>           http                             </transferType>
 <name>                   bw_res-1.9.4.0-1.9.x.ypatch         </name>
 <property name="url">    patches/bw_res-1.9.4.0-1.9.x.y.patch </property>
 <property name="md5sum"> c166772f145bcc59ac714b7995e52c2a </property>
</patch>

The transferType tags describes how to download a patch file from a URL via HTTP. This transfer handler supports resuming of partial downloads with a small amount of rollback, that is, resuming will occur at a point (by default 4K) before the end of the received file fragment. In order to detect possible file corruption, the newly downloaded portion corresponding to the rollback amount is checked against what was downloaded previously, and the download will restart from the beginning if corruption is detected.

Properties for a patch transfer are specified using the property tags. The HTTP transfer type defines the following properties:

You can add your own transfer type by specifying properties that describe how to retrieve a patch file. You will need to modify the CheckVersions script and create and register a new PatchTransferHandler class.