Creating a Content Patch

ACR 1.87 supports the creation and deployment of content patches, which are server-side hotfixes that are automatically deployed to live servers on startup. The content patch system is intended to make it easier to deploy important bugfixes to an already released ACR version.

Content patches can be used to perform the following tasks:

• Place a file in the Override directory for the server. Note that module and hak resources supersede "Override" resources (but Override supersedes in-box .zip files and can be used to deploy a new script that could be called by a hak, etc.). Override-targetted content patch files go in "override\ACR_ContentPatches" on each live server.
• Place an updated hak in the Hak directory for the server (for example, alfa2_acr.hak).
• Recompile module scripts.
• Patch moduledownloaderresources.xml with new hak file download information for game clients (module specific downloader resources are left as-is).

Content patches cannot be used to make client-side content changes (those must go through the standard release process). As of ACR 1.90, the content patch system can recompile all module scripts (if the RecompileModule database column is set for a content_patch_files row that required updating), if necessary. This facility can be used to update includes in the ACR hak and recompile scripts in a module that reference the include.

Content patches automatically update the downloader XML for a server. Server admins should be careful to not restage haks that have been hotfixed by the content patch system (typically, alfa2_acr.hak), but if any of the downloader XML descriptors for noticed files were incorrect, the server will correct these on next startup (incurring an additional server process restart).

Content Patch Components

A content patch contains several distinct components which must be assembled:

• The content files to patch (e.g. alfa2_acr.hak, or a free-standing file to place in the Override directory). Any number of files can theoretically be content patched, but you're encouraged to keep the set of file small. The content files must be placed on the central server vault, in a special directory, for them to be downloadable by the content patch system.
• A set of database entries in the content_patch_files table that describe what ACR hak version the patch applies to (e.g. 1.87), and what file is associated with the patch. You need a database record for each file that is contained within the content patch.
• An optional initialization script, called "acr_patch_initialize". If present, this script is run during module startup, to provide opportunity for a content patch to hook script callbacks or set things up. The script is never located in the ACR hak or the module, but should only be distributed as a content_patch_files record.

Creating a Content Patch

The following is a checklist of the steps necessary to build and deploy a content patch. Once deployed, it will be automatically picked up by live servers on their next restart. (If necessary, you can remotely restart a server using the Restart Server tool.)

1. First, create the content files to patch. For example, the fixed script or the patched ACR hak. Typically this would be done by checking out the ACR branch for the released ACR version to be patched, making the necessary changes and checking them in to the repository, and then rebuilding the hak from that branch.
2. Next, copy the patched content files to the central vault. They should go under ACR_ContentPatches\Global\<ACR_Version> on the central vault (for example ACR_ContentPatches\Global\1.87 for an ACR 1.87 patch).
3. Generate a md5 checksum of each of the patched content files. The md5sum utility (included with msysgit - http://code.google.com/p/msysgit/ - or cygwin, can do this). You'll need these checksums to insert into the database in the next step.
4. Create a database record in content_patch_files for each file present in the content patch.
   1. Set the FileName column to the name of the file to patch (with extension, no spaces, for example "alfa2_acr.hak").
   2. Set the HakVersion column based on the ACR version that is matched when deciding whether the content patch is applicable (for example, "1.87").
   3. Set the Location column to either "override" or "hak", depending on where the content file should be stored on live servers.
   4. Set the Checksum column to the md5sum value (32 hex characters) for the file that is being patched.
   5. Set the RecompileModule column to true if the module needs to have all scripts recompiled, else false if a recompile is not required. A recompile is generally only necessary if an include in the ACR HAK has been changed and the include is referenced by a script distributed with the module. This option is only supported in ACR 1.90 or higher (otherwise the module is never recompiled).
5. Connect a test server to the database and central server vault, and restart it. Check the log to make sure that the content patch applied successfully; the server should restart a second time after applying the patches. There will be server log entries containing "ModuleContentPatcher" updating you with the status of content patches as they're applied.

It is highly recommended that you test the content patch on a test server before copying the patch data to the live server. You should still verify that the patch applied correctly to a live server, however, once the patch has been deployed to production.

Content Patches and the Standard Release Process

The content patch system ensures that patches are tagged with a specific ACR version that they apply to. When a server upgrades to a new ACR version, using the standard release process, previous content patches will no longer be applicable and won't be applied anymore.

For content patch files located in the "hak" directory, no action is taken. It's expected that if the administrator did an ACR upgrade, that they have manually upgraded the haks anyway. (No new haks can be added with the content patch system, only hotfixes to existing haks.)

For content patch files located in the "override" directory, the content patch system automatically removes any patch files not applicable to the ACR version the server starts up with at startup time. Thus it's not necessary to manually clean the content patch override directory out.

Content Patch Server Log Messages

Messages in the NWN2 server log file track the progress of the content patch system. When a content patch has been successfully applied, a log message of the form "ModuleContentPatcher.ProcessContentPatches: Successfully updated content patch file <filename>." will be written to the server log. Log messages related to the content patcher can be easily identified by searching for ModuleContentPatcher in the log file. To verify that a content patch was deployed successfully, examine the server log after a server restart. Be sure to check the log message timestamp; it is usually best to start searching from the end of the server log file.

If a content patch requests a module script recompile, then the console output of the script compiler is printed to the server log file. An error message prefixed with the standard ModuleContentPatcher prefix is printed to the server log if any scripts failed to compile.