ALFA - User contributions [en]

Creating a Content Patch

2017-06-19T06:29:48Z

Basilica: /* Content Patch Downloader Resource Updates */

[[Category:Technical Manuals]]
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 alone (those must go through the standard release process in addition). 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 (see [[#Content Patch Downloader Resources]] for how to configure new dowmloader XML information for new client-side release). 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.)

These steps assume that you have already verified that the new hak to install works correctly, and that it compiles correctly for a module. These steps are highly recommended to make sure that the patch process goes smoothly.

# 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.
# Record the existing content_patch_files contents from the database, in case a rollback is necessary.
# Next, copy the patched content files to the Azure updater using the UpdaterConnectionString (formerly, the files were placed on the central vault). They should go under ACR_ContentPatches/Global/<ACR_Version> on the updater Azure storage (for example ACR_ContentPatches/Global/1.87 for an ACR 1.87 patch). [http://aka.ms/AzCopy AzCopy] or [https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer Storage Explorer] can be used to upload content patch files. Optionally, and recommended, content patch file hosted on Azure storage can be gzip compressed with a tool like gzip.exe from msysgit, or 7-zip (append .gzip to the filename uploaded to Azure, e.g. alfa2_acr.hak.gzip after compressing with gzip.exe). Compression was not supported for updates distributed by the central vault, though that method is deprecated. Remember that Azure storage is case sensitive, so path cases must match exactly, and that the compression format must be gzip.
## Note! It is highly recommended that the previous content patch files be downloaded or saved, for any files that will be replaced, so that a rollback can be performed.
## The content patch files are stored in the alfa-nwn2-acr-updater storage container on Azure storage. By convention, the content patches are stored in the ACR_ContentPatches\Global\<hak version> directory; the latter path is drawn from the config table "ContentPatchPath" variable.
## By current convention, the ACR version is left at 1.9201 and has not been incremented for some time. The content patch system allows different patches to be selected based on the previous ACR version of the server, but it has proven more conventient in many cases to simply keep the same version number and produce a new patch content.
## Presently, the server vault and ACR updater are on the same Azure storage account, though this is not architecturally required.
# Generate a md5 checksum of each of the patched content files. The md5sum utility (included with msysgit - [http://code.google.com/p/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. If compressed files were stored on Azure storage, the checksum must be that of the uncompressed file.
# Create (or, as need be, update) a database record in content_patch_files for each file present in the content patch.
## Set the '''FileName''' column to the name of the file to patch (with extension, no spaces, for example "alfa2_acr.hak"). This should not include the .gzip appended for compressed content patches, rather it should reflect the final on disk filename of the content to update.
## Set the '''HakVersion''' column based on the ACR version that is matched when deciding whether the content patch is applicable (for example, "1.87").
## Set the '''Location''' column to either "override" or "hak", depending on where the content file should be stored on live servers.
## Set the '''Checksum''' column to the md5sum value (32 hex characters) for the file that is being patched.
## 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).
## Only one row for a specific combination of both a given '''FileName''' and '''HakVersion''' should exist in the table.
# 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.
# If a content patch needs to cause new client content to be downloaded, follow the steps for [[#Content Patch Downloader Resource Updates]] to configure the moduledownloaderresources.xml entries that will be patched on each server. Patches that only have server-side script changes do not need this, but 2DA or template or GUI updates will need client-side updates, and have to go through that process.

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.

Remember to set the RecompileModule flag on the ACR hak if any script includes that are included by the module are modified. Most script files are included by the module, so this is often necessary. Without this step, for a script update, servers may not see the update take effect.

== Troubleshooting ==
The IRC bot will send status messages in #alfa-players and #alfa-tech as an update is under way, so being present in these channels is recommended.

Detailed logging information is logged to the server log. If that is not present, stop the server, edit nwn2player.ini for the server, and make sure that "Scripts Print to Log=1" is present (the default might be "Scripts Print to Log=0"). This is required for WriteTimestampedLogEntry to log to the server log, and most diagnostics are written with that mechanism. Within the server log, search for the strings '''ModuleContentPatcher''' and '''PatchContentFiles''' to find the log messages relevant for the ACR updater.

In order for the module recompile to work, NWNScriptCompiler.exe has to be installed in the NWNX4 directory of the server. This is part of the standard server configuration and deployment process. A file not found error when launching the compiler, in the server log, may indicate that NWNScriptCompiler.exe is not properly installed. The recompile process only takes effect when the given hak is updated, so you may need to copy the old hak onto the server and start it again to cause a recompile to take, if the recompiler flag was not properly set the first time around.

If a server does not pick up an update at all, the database entries in content_patch_files are likely to be incorrect.

Client downloader resources need to be processed using the [[#Content Patch Downloader Resources]] step below, so if a client side change does not take effect, make sure that both processes have been followed.

== Content Patch Downloader Resource Updates ==
The content patch system can automatically maintain moduledownloaderresources.xml if new haks need to be pushed to client machines. There is a separate process, outlined below, to configure updates to moduledownloaderresources.xml on each server. This checklist needs to be followed in addition to the steps for [[#Creating a Content Patch]] when any .hak updates need to be downloaded by client machines. Note that this process can only update existing entries in moduledownloaderresources.xml; if an entirely new hak is created from scratch, this must be manually added to moduledownloaderresources.xml for each server, or the content patch system would need to be extended to support adding new download resources.

The database table content_download_config contains a set of rows that describe override values that are installed into each server's moduledownloaderresources.xml on startup, replacing any previous values. This provides a mechanism to update the autodownloader manifest on all servers as they deploy a content patch, and avoids the downloader resources from having picking up invalid values for ACR-controlled resources when a per-module content update is performed.

Note that this process does not replace publishing new hak files to the download server for clients to download, and that is a separate step fron the Azure ACR updater.

# First, go through the normal process to stage the new hak contents for the autodownloader using the toolset using any module that references the ACR haks after installing the new hak that will be published to the autodownloader, and take note of the specific hak files that need client updates. These are typically all haks, except that the ACR hak can be stale on the client in the case of server-side script only updates. Note that it is important to use the same hak on the client and server, so it is best to perform the steps listed in [[#Creating a Content Patch]] followed by those in this section at the same time, unless an update is a server-side only script change.
# For each hak file that needs client-side updates, take note of the following elements from the new moduledownloaderresources.xml produced by the toolset. Each of these values will need to be updated in the corresponding row of content_download_config, which is keyed off of by hak filename. Below, the name of each moduledownloaderresources.xml element is followed, in parenthesis, by the corresponding database column name in content_download_config.
## name (Name)
## hash (Hash)
## downloadHash (DownloadHash)
## dlsize (DLSize)
## size (Size)
# Record the existing content_download_config contents from the database, in case a rollback is necessary.
# Each hak that needs a new client-side update must have its corresponding content_download_config rows updated to match the new moduledownloaderresources.xml elements on the computer that you have used to stage a new ACR-controlled hak. There should be only one entry in the table for each .hak Name value.
# As normal, the staged lzma files from the toolset need to be uploaded to the download server so that clients can find them.
## Note! It is highly recommended that the previous LZMA files be downloaded or saved, for any files that will be replaced, so that a rollback can be performed.

== 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. In most cases, the ACR version is not incremented, and is kept at 1.9201, though previously it used to have been incremented. This was found to create more overhead than benefit and so the old version is

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.

Creating a Content Patch

2017-06-19T06:12:10Z

Basilica: Document some undocumented parts of content patches and downloader XML updates, and generally expand documentation for the patch process and existing conventions.

[[Category:Technical Manuals]]
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 alone (those must go through the standard release process in addition). 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 (see [[#Content Patch Downloader Resources]] for how to configure new dowmloader XML information for new client-side release). 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.)

These steps assume that you have already verified that the new hak to install works correctly, and that it compiles correctly for a module. These steps are highly recommended to make sure that the patch process goes smoothly.

# 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.
# Record the existing content_patch_files contents from the database, in case a rollback is necessary.
# Next, copy the patched content files to the Azure updater using the UpdaterConnectionString (formerly, the files were placed on the central vault). They should go under ACR_ContentPatches/Global/<ACR_Version> on the updater Azure storage (for example ACR_ContentPatches/Global/1.87 for an ACR 1.87 patch). [http://aka.ms/AzCopy AzCopy] or [https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer Storage Explorer] can be used to upload content patch files. Optionally, and recommended, content patch file hosted on Azure storage can be gzip compressed with a tool like gzip.exe from msysgit, or 7-zip (append .gzip to the filename uploaded to Azure, e.g. alfa2_acr.hak.gzip after compressing with gzip.exe). Compression was not supported for updates distributed by the central vault, though that method is deprecated. Remember that Azure storage is case sensitive, so path cases must match exactly, and that the compression format must be gzip.
## Note! It is highly recommended that the previous content patch files be downloaded or saved, for any files that will be replaced, so that a rollback can be performed.
## The content patch files are stored in the alfa-nwn2-acr-updater storage container on Azure storage. By convention, the content patches are stored in the ACR_ContentPatches\Global\<hak version> directory; the latter path is drawn from the config table "ContentPatchPath" variable.
## By current convention, the ACR version is left at 1.9201 and has not been incremented for some time. The content patch system allows different patches to be selected based on the previous ACR version of the server, but it has proven more conventient in many cases to simply keep the same version number and produce a new patch content.
## Presently, the server vault and ACR updater are on the same Azure storage account, though this is not architecturally required.
# Generate a md5 checksum of each of the patched content files. The md5sum utility (included with msysgit - [http://code.google.com/p/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. If compressed files were stored on Azure storage, the checksum must be that of the uncompressed file.
# Create (or, as need be, update) a database record in content_patch_files for each file present in the content patch.
## Set the '''FileName''' column to the name of the file to patch (with extension, no spaces, for example "alfa2_acr.hak"). This should not include the .gzip appended for compressed content patches, rather it should reflect the final on disk filename of the content to update.
## Set the '''HakVersion''' column based on the ACR version that is matched when deciding whether the content patch is applicable (for example, "1.87").
## Set the '''Location''' column to either "override" or "hak", depending on where the content file should be stored on live servers.
## Set the '''Checksum''' column to the md5sum value (32 hex characters) for the file that is being patched.
## 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).
## Only one row for a specific combination of both a given '''FileName''' and '''HakVersion''' should exist in the table.
# 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.
# If a content patch needs to cause new client content to be downloaded, follow the steps for [[#Content Patch Downloader Resource Updates]] to configure the moduledownloaderresources.xml entries that will be patched on each server. Patches that only have server-side script changes do not need this, but 2DA or template or GUI updates will need client-side updates, and have to go through that process.

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.

Remember to set the RecompileModule flag on the ACR hak if any script includes that are included by the module are modified. Most script files are included by the module, so this is often necessary. Without this step, for a script update, servers may not see the update take effect.

== Troubleshooting ==
The IRC bot will send status messages in #alfa-players and #alfa-tech as an update is under way, so being present in these channels is recommended.

Detailed logging information is logged to the server log. If that is not present, stop the server, edit nwn2player.ini for the server, and make sure that "Scripts Print to Log=1" is present (the default might be "Scripts Print to Log=0"). This is required for WriteTimestampedLogEntry to log to the server log, and most diagnostics are written with that mechanism. Within the server log, search for the strings '''ModuleContentPatcher''' and '''PatchContentFiles''' to find the log messages relevant for the ACR updater.

In order for the module recompile to work, NWNScriptCompiler.exe has to be installed in the NWNX4 directory of the server. This is part of the standard server configuration and deployment process. A file not found error when launching the compiler, in the server log, may indicate that NWNScriptCompiler.exe is not properly installed. The recompile process only takes effect when the given hak is updated, so you may need to copy the old hak onto the server and start it again to cause a recompile to take, if the recompiler flag was not properly set the first time around.

If a server does not pick up an update at all, the database entries in content_patch_files are likely to be incorrect.

Client downloader resources need to be processed using the [[#Content Patch Downloader Resources]] step below, so if a client side change does not take effect, make sure that both processes have been followed.

== Content Patch Downloader Resource Updates ==
The content patch system can automatically maintain moduledownloaderresources.xml if new haks need to be pushed to client machines. There is a separate process, outlined below, to configure updates to moduledownloaderresources.xml on each server. This checklist needs to be followed in addition to the steps for [[#Creating a Content Patch]] when any .hak updates need to be downloaded by client machines. Note that this process can only update existing entries in moduledownloaderresources.xml; if an entirely new hak is created from scratch, this must be manually added to moduledownloaderresources.xml for each server, or the content patch system would need to be extended to support adding new download resources.

The database table content_download_config contains a set of rows that describe override values that are installed into each server's moduledownloaderresources.xml on startup, replacing any previous values. This provides a mechanism to update the autodownloader manifest on all servers as they deploy a content patch, and avoids the downloader resources from having picking up invalid values for ACR-controlled resources when a per-module content update is performed.

Note that this process does not replace publishing new hak files to the download server for clients to download, and that is a separate step fron the Azure ACR updater.

# First, go through the normal process to stage the new hak contents for the autodownloader using the toolset using any module that references the ACR haks after installing the new hak that will be published to the autodownloader, and take note of the specific hak files that need client updates. These are typically all haks, except that the ACR hak can be stale on the client in the case of server-side script only updates. Note that it is important to use the same hak on the client and server, so it is best to perform the steps listed in [[#Creating a Content Patch]] followed by those in this section at the same time, unless an update is a server-side only script change.
# For each hak file that needs client-side updates, take note of the following elements from the new moduledownloaderresources.xml produced by the toolset. Each of these values will need to be updated in the corresponding row of content_download_config, which is keyed off of by hak filename. Below, the name of each moduledownloaderresources.xml element is followed, in parenthesis, by the corresponding database column name in content_download_config.
## name (Name)
## hash (Hash)
## downloadHash (DownloadHash)
## dlsize (DLSize)
## size (Size)
# Record the existing content_download_config contents from the database, in case a rollback is necessary.
# Each hak that needs a new client-side update must have its corresponding content_download_config rows updated to match the new moduledownloaderresources.xml elements on the computer that you have used to stage a new ACR-controlled hak.
# As normal, the staged lzma files from the toolset need to be uploaded to the download server so that clients can find them.
## Note! It is highly recommended that the previous LZMA files be downloaded or saved, for any files that will be replaced, so that a rollback can be performed.

== 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. In most cases, the ACR version is not incremented, and is kept at 1.9201, though previously it used to have been incremented. This was found to create more overhead than benefit and so the old version is

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.

Virtual Machine Setup

2015-10-06T05:48:37Z

Basilica: More troubleshooting documents.

[[Category:Technical Manuals]]
This document describes in rough detail the recommended checklist for setting up a new game server host VM in the standard configuration. This configuration is suitable for running nwn2server.exe as a limited user account.

== Prerequisites ==
.NET 3.5 and the DirectX End-User Runtime are optional unless the toolset will be run locally on the game server host machine.

* If running the toolset on the host is desired (optional), enable .NET 3.5 in Add/Remove Windows Features before installing DirectX
* [http://www.microsoft.com/en-us/download/details.aspx?id=35 DirectX End-User Runtime] (required only if the toolset will be used to stage content on the game server)
* [http://www.microsoft.com/en-us/download/details.aspx?id=17851 Microsoft .NET Framework 4]
* [http://www.microsoft.com/en-us/download/details.aspx?id=26347 Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC Security Update]
* [http://www.microsoft.com/en-us/download/details.aspx?id=26999 Microsoft Visual C++ 2010 Service Pack 1 Redistributable Package MFC Security Update]

== Process ==
# Install Windows Server
# Copy standard tools over
# Create SG "NWN2 Servers"
# Create SG "NWN2 Admins"
# Create user "NWN2Server"
## Add to "NWN2 Servers" SG
# Create C:\NWN2, xcopy NWN2 install over
## Grant "NWN2 Servers" create files, create folders to "This folder only"
## Grant "NWN2 Admins" modify to folder, subfolders, and files
## Import NWN2.reg
# Create C:\NWN2User
## Grant full control to "NWN2 Servers"
## Grant modify/execute/list/read/write to "NWN2 Admins"
# Runas /profile /user:NWN2Server cmd.exe
## cd /d "%userprofile%\Documents"
## mklink /j "Neverwinter Nights 2" C:\NWN2User
## putty -ssh alfa@sql.alandfaraway.org
### Confirm and accept central server public key for vault tunnel to work
# Create C:\NWNX4, xcopy NWNX4 installation over
## Grant modify/execute/list/read/write to "NWN2 Admins"
## Grant modify/execute/list/read/write to "NWN2 Servers" for:
### AuroraServerNWScript.log
### AuroraServerVault.log
### nwnx.txt
### nwnx_controller.txt
### StandardQueryLog.txt
### xp_mysql.txt
### xp_bugfix.txt
### xp_objectattributes.txt
### xp_srvadmin.txt
### xp_system.txt
### xp_time.txt
# Create C:\Users\Public\Desktop\Credentials.txt
# Copy standard links to C:\Users\Public\Desktop
# Copy standard links to C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Tools
# Copy standard scripts to C:\Scripts
# Copy standard NWN2 tools to C:\Tools
# Copy NWNServerConsole to C:\NWN2\Console
# Fix PowerShell signing
## Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy Unrestricted -Force
# Install [http://git-scm.com/ Git]
# Install [https://filezilla-project.org/ FileZilla]
# Install [http://msdn.microsoft.com/en-us/windows/apps/br229516 Win8 Performance Toolkit]
# Install [http://www.7-zip.org/ 7-zip]
# Install [http://gvim.en.softonic.com/ gvim]
# Install WinDbg for [http://www.microsoft.com/en-us/download/details.aspx?id=8279 Windows 7] or [http://msdn.microsoft.com/en-US/windows/desktop/bg162891 Windows 8.1].
# Set <code>_NT_SYMBOL_PATH</code> to <code>SRV*C:\Symbols*http://msdl.microsoft.com/download/symbols</code>

== NWNX4 Installation ==
# nwnx4_controller.exe -installservice
# Configure NWNX4-1 service to run as the "NWN2Server" user
## If using a Microsoft account (user@email) for the server user, use Computername\Username where Username is the value that %USERNAME% shows from "echo %USERNAME%" in cmd.exe and Computername is the value that %COMPUTERNAME% shows from "echo %COMPUTERNAME%" in cmd.exe. Also, in this case, you have to manually grant this user "Log on as a service" rights by going to Local Security Policy, Local Policies, User Rights Assignment, Log on as a service, and adding Computername\Username to the list. This only applies to accounts set up as a Microsoft account initially, not to local accounts that a Microsoft account was connected to afterwards.
# Get SID for NWN2Server user with PowerShell:
::: <code>([wmi]"win32_Group.Domain='$env:ComputerName',Name='NWN2 Admins'").sid</code>
# Set SD on nwnx4-1 service to allow NWN2 Admins to start/stop:
::: <code>sc sdset nwnx4-1 D:(A;;CCLCSWRPWPDTLOCRRC;;;SY)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;BA)(A;;CCLCSWLOCRRC;;;IU)(A;;CCLCSWLOCRRC;;;SU)(A;;RPWP;;;<NWN2 Admins SID from above command>)S:(AU;FA;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)</code>
# Install SSH private key to C:\NWNX4\sshfs.ppk
# Add SSH public key to alfa@sql.alandfaraway.org:~/.ssh/authorized_keys
# Set configuration in C:\NWNX4\nwnx.ini
# Set configuration in C:\NWNX4\AuroraServerNWScript.ini
# Set configuration in C:\NWNX4\xp_mysql.ini
# Set configuration in C:\NWNX4\DatabaseConnector.ini
# Set configuration in C:\NWNX4\AuroraServerVault.ini

== Module preparation ==
# If the module is being cloned directly from source control or copied from a very old backup, it may be necessary to recompile the module against a current alfa2_acr.hak to ensure that the database connection (and self-update) work at module startup. If the module never loads acr_databaseconnector in AuroraServerNWScript.log and no "DatabaseConnector" log messages in nwserverLog1.txt are seen before the ACR_OnModuleLoad: log line then this may be the problem (but also check for errors in AuroraServerNWScript.log that might indicate a misconfigured NWScript Accelerator installation).
# Make sure that alfa2_acr.hak is recent. An extremely old build predating the DatabaseConnector integration may not be able to self-update the rest of the ACR.

== Troubleshooting ==
Fixes for some problems encountered during server deployment are listed here.
# Module didn't load or server doesn't start up?
## Look at the server log file and C:\NWNX4\AuroraServerNWScript.log for errors/exceptions for next troubleshooting steps.
# Database doesn't connect, or many exceptions in server log about the database, or PCs (but not DM's) are booted at log on?
## Make sure that plink.exe was run once as the user that the NWNX4-1 service runs as in order to accept the SSH key of the central server.
# Monitor Server Uptime script closes immediately?
## Make sure that the following command was run from an administrator privileged PowerShell session: Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy Unrestricted -Force
# Game server starts with NWNX4_GUI.exe but not as a service?
## Make sure that the service is running as the right user. Go to services.msc and configure it to run as the user whose %userprofile%\Documents\Neverwinter Nights 2 has the module, server vault, etc. present.
# Toolset doesn't start/work properly?
## Make sure that .NET Framework v3.5 (sometimes called .NET Framework v2.0) is installed, and then the DirectX End-User Runtime is installed. If the DirectX End-User Runtime was installed first, it's installer has to be re-run after installing .NET Framework v3.5.
# Database or scripts don't work, or NWNX4 plugins didn't load?
## Make sure that all Visual C++ and .NET runtime dependencies were installed.
## Make sure that NWNScriptJIT.dll, NWNScriptJITIntrinsics.dll are installed in the NWN2 installation directory (not necessarily the NWNX4 installation directory).
## Make sure that plink.exe was run once as the service user (see above).
# Using a Microsoft account for the service account and the service fails to start with "The service dependency failed to start."?
## Configure the service to log on using Computername\Username and ensure that from Local Security Policy, Local Policies, User Rights Assignment, that Computername\Username was granted "Log on as a service" rights.

Virtual Machine Setup

2015-10-06T05:46:43Z

Technical Manual

2015-04-19T17:28:38Z

Basilica: Add link to Updating Azure Client Libraries page

[[Category:Manuals]]
This section is intended to help those interested in building, or just wanting to know how things like the core scripts work. Most of this information is NWN2-specific, though we will have some NWN1 technical documents listed here as well in the days to come. In the meantime, much of this information is outdated or at least in need of organization and qualification.

== For Everyone ==
* [[Reporting Bugs]]
* [[Crafting Guide]]
* [[Introduction to Git]] (How to use [https://github.com/ GitHub])

== Hosts and HDMs ==
* [[Virtual Machine Setup]]
* [[Basic Host Requirements]] - NWNx4 and nwn2server, basic requirements to host a module.
* [[Setting Up MySQL Workbench]]

== Builders ==
* [[ALFA Build Module]]
* Guide to [[Writing ACR Quests]], as well as an [[Quest Creation Example]].
* [[ALFA Base Resources]] (ABR) Basics
* [[Toolset Guide]]
* [[Using Local Variables]]
* [[Building Areas]]
** [[Creating Terrain with L3DT and YATT]]
* [[Building Doors]]
* [[Building Items]]
* [[Building Placeables]]
* [[Building Creatures]]
* [[Building Triggers]]
* [[Building Portals]]
* [[Writing Conversations & Quests]]
* [[ACR Spawn]] System: The complete manual
* [[ACR Encounter]] System
* [[ACR Rest]]ing & Healing Bonuses

== Scripters ==
* [[ALFA Core Rules]] (ACR) Basics
* [[Data Persistence]]
* [[Rewarding Experience]]
* [[Spell Scripting]]
* [[Scripting Items]]
* [[Scripting Feats]]
* [[Script Library]] (General)
* [[Developing for ALFA]]
* [[Creating CLR Programs]]
* [[Creating Instanced Areas]]
* [[Running Scripts Remotely]]

Reference Documents:
* [[GetEffectInteger]] return values

== Technical Documentation ==
* [[Core Content Release Process]]
* [[ACR and Core Content Addition Policies]]
* [[TLK]] Information
* [[2DA]] Information
* [[GUI]] Information
* [[ACR Configuration Settings]]
* [[Creating a Content Patch]]
* [[Updating Azure Client Libraries]]
* [[Release Notes]]
* [[Server Vault]]

Virtual Machine Setup

2014-08-30T17:05:24Z

Basilica:

Virtual Machine Setup

2014-08-30T17:02:25Z

Basilica:

2014-08-10T18:22:16Z

Basilica:

[[Category:Technical Manuals]]
There are several configuration settings that alter the behavior of the ACR on a global or per-module basis.

Global settings are stored in the "config" table in the database, whereas per-module settings are stored as module local variables that are intended to be configured in the toolset.

== Module local variable configuration settings ==
These settings are stored as local variables on the module. They can be set by the toolset.

; int ACR_PLAYER_LOCATIONS : If set to 1, the PC Tools button that allows a player to see what areas their party members are in is enabled. '''This feature is defunct and doesn't do anything right now.'''

; int ACR_DISABLE_STATISTICS : If set to 1, then the ACR doesn't update the stat_counters table in the database. This feature is primarily in place to allow statistics to be disabled if they proved to be a performance problem. This setting can be globally configured via the database config table.

; int ACR_HEALTHMONITOR_GAMEOBJUPDATE_BACKOFF : If set to 1, then the server will detect when responsiveness is poor due to excessive server load. If the server appears to be overloaded, then the ACR (ACR_HealthMonitor) will increase the time between game world updates sent to game clients. This frees up a significant amount of CPU time for other tasks on the server, preserving responsiveness (but players will see course corrections or other movement changes less frequently). If the server is performing well, the game world update timer is reduced to its default value. This setting can be globally configured via the database config table.

; int ACR_SERVER_IPC_DISABLE_LATENCY_CHECK : If set to 1, then the server won't periodically, about every 30 seconds, refresh the player to server ping times of connected players (players can check their ping with #ping if this feature isn't enabled).

; int ACR_MODULERESOURCEFILES : If set to 1, then the server will record each resource file present within the module proper in the server_resource_files table. This setting can be globally configured via the database config table.

=== Recommended Module Default Settings ===
: int ACR_PLAYER_LOCATIONS = 1
: int ACR_HEALTHMONITOR_GAMEOBJUPDATE_BACKOFF = 1

== Global (database config table) Configuration Settings ==
These settings are stored in the "config" table in the database, which is a key/value pair mapping. They change the behavior of all modules connected to the database.

; PlayerPassword : This setting contains the player password that is used when portaling a player between servers. It '''must''' match the configured player password value on all servers. Changing this setting doesn't actually change the player password required to connect to a server (which has to be done separately), just what password is used for outbound portals. This setting is updated every 5 minutes while a server is running.

; ACR_DISABLE_STATISTICS : If set to 1, this setting turns off stat_counters table updates on all servers by setting the ACR_DISABLE_STATISTICS module local variable to 1 during server startup. This setting is only updated at module startup time.

; GameObjUpdateBackoff : If set to 1, this setting enables game world update timer management by setting the ACR_HEALTHMONITOR_GAMEOBJUPDATE_BACKOFF module local variable to 1 during server startup. This setting is only updated at module startup time.

; RestartWatchdogTimeout : The number of second after which a remote server restart request, from the Restart Server tool, forcibly terminates the server if a clean shutdown hasn't happened yet. This setting is designed to allow a server that is deadlocked or hung to be forcibly restarted remotely (as the remote restart mechanism uses a dedicated thread that is more likely to be responsive even if the main server thread is stuck). If not set or set to zero, then the restart watchdog feature isn't used on remote restart requests. This setting is updated every 5 minutes while a server is running.

; AccountAssociationSecret : The shared secret string used to generate the URL to send the user to for linking their in-game community account with their ALFA forum account. The value can be any string (hopefully a relatively random one). The forum system uses the shared secret to validate that URLs containing account linking information were only generated by an authorized source, like a live server. More details on the account association system can be found [http://www.alandfaraway.org/forums/viewtopic.php?f=95&t=47302 here]. This setting is updated every 5 minutes while a server is running.

; ModuleResourceFiles : If set to 1, this setting enables module resource file logging by setting the ACR_MODULERESOURCEFILES module local variable to 1 during server startup. This setting is only updated at module startup time.

; AccountAssociationUrl : The base URL of the ALFA account association web service. This setting is updated every 5 minutes while a server is running.

; GetHostnameUrl : The base URL of the ALFA get hostname web service. This setting is updated every 5 minutes while a server is running.

; ContentPatchPath : The path relative to the sshfs mount point to use as the base location for content patch files. Content patch files are stored under <sshfs_mount>\ContentPatchPath\<HakVersion>\. This setting is only updated at module startup time.

; DefaultIrcGatewayId : The default IRC gateway to use for server-to-IRC messages. Typically, this should be zero, which is the IRC gateway ID customarily used by the production ALFA IRC bot. The setting is paired with an ALFA IRC Bot instance's IRCGateway config.xml entry. This setting is updated every 5 minutes while a server is running.

; DefaultIrcRecipient : The default IRC recipient (i.e. channel) to use for server-to-IRC messages. Typically, this should be #alfa-players. This setting is updated every 5 minutes while a server is running.

; WerDisabled : If set to 1, Windows Error Reporting is disabled for nwn2server.exe. This setting is only updated at module startup time.

; DisableSaveInQuarantine : If set to 1, character files are not saved by a player in quarantine (preventing a pending save from an offline server from accidentally being overwritten by logging in to the wrong server). This is updated every 5 minutes while a server is running.

; CompilerOptions : Compiler options that the content patcher system uses when a module recompile is required by a content hotfix. This is usually set to "-e -o -v1.70 -y", to match the option set used by the ACR build system (in NWScript.mk) and to continue past scripts that fail to compile, as some modules have non-compileable scripts checked in.

; NotifyServiceCid : The character ID of the dummy character that is used to send notification messages from infrastructure to the IRC gateway. Typically, this should be the dedicated NotifyService character (CID 3905). This is used, for example, by the content patcher, so as to send notifications as to server restarts due to the content patch system. If set to zero, messages are not sent to the IRC gateway. Infrastructure messages are sent to the default IRC recipient as configured by the DefaultIrcRecipient config table variable.

; ErrorNotifyIrcRecipient : The default IRC recipient (i.e. channel) to use for diagnostic and error reports sent via server-to-IRC messages. Typically, this should be #alfa-tech. This setting is updated every 5 minutes while a server is running.

; GameDifficultyLevel : The game difficulty level that all servers will be configured to. This is an integer value that should match the value of one of the GAME_DIFFICULTY_* nwscript.nss constants, and should generally be set to 3 (meaning GAME_DIFFICULTY_CORE_RULES). If a server has an incorrect difficulty level, the ACR system will automatically adjust it to the target, global difficulty level specified with this variable.

; ProtectionLevel : The anti-abuse protection level that all servers adhere to (an integer). Each protection level represents an incremental anti-abuse defense over the previous level. Protection levels can be applied in the case of an abuse event, but generally the system should run at ProtectionLevel 0 (the default, no special restrictions). Valid values correspond to the following table (the value should be set to the integer on the left, the symbolic constant in script source code is supplied in parenthesis):
# (MEMBER_PROTECTION_LEVEL_OPEN): The default, no special anti-abuse provisions for non-member accounts.
# (MEMBER_PROTECTION_LEVEL_QUARANTINE): Non-member accounts are immediately quarantined on login.
# (MEMBER_PROTECTION_LEVEL_QUARANTINE_DM_ONLY_TELLS): Non-member accounts are immediately quarantined on login and the only function permitted in-game is to send a tell to a DM (no cross-server tells, no IRC gateway use, no (non-DM) player tells, etc.).
# (MEMBER_PROTECTION_LEVEL_BOOT_5S_DELAY): Non-member accounts are quarantined, can't use tells (even to a DM), and are booted after 5 seconds. A short message explaining that the player should fill out the application form at [http://www.alandfaraway.org http://www.alandfaraway.org] is displayed before the player is booted.
# (MEMBER_PROTECTION_LEVEL_BOOT_IMMEDIATELY): Non-member accounts are immediately booted on log in and can't perform any function in-game whatsoever. No appreciable delay even to send an explanation as to what happened is allowed for, for use in extreme abuse events only.
: This setting is updated every 5 minutes while a server is running.

; VaultConnectionString : The Azure Storage connection string for the server vault. This setting is updated every 5 minutes while a server is running.

; UpdateConnectionString : The Azure Storage connection string for the ACR updater. This setting is updated every 5 minutes while a server is running.

; VerboseVaultLogging : If set to 1, detailed log messages about the Azure ServerVaultConnector are logged to the main server log file. This setting is normally left as 0. This is updated every 5 minutes while a server is running.

Creating a Content Patch

2014-08-10T06:11:33Z

Basilica:

Creating a Content Patch

2014-08-10T06:09:45Z

Basilica:

2014-08-10T03:55:48Z

Basilica:

[[Category:Technical Manuals]]
The server vault, the centralized repository for all ALFA character files, is hosted in [http://azure.microsoft.com Microsoft Azure]. Formerly, it was connected over SSHFS, but this system has been deprecated as it had reliability issues and forced the existence of two separate OS's (Windows and Linux) that had to be independently patched, managed, and maintained for each game server instance.

The VaultTransferTool, built out of the ACR repository (VaultManagement\VaultTransferTool), provides a basic set of functionality for managing the server vault, including uploading files to the vault (but only if the vault didn't have a more up to date version of the files), downloading the entire vault to a directory (but only for files that were older than the vault versions), as well as selectively deleting files from the vault.

One use of the VaultTransferTool would be to locally archive copies of the entire vault for selective restoration in case a character rollback had to be performed for technical or management reasons. Another use might be for selective BIC edits.

You can also use a tool like [http://aka.ms/AzCopy AzCopy] to copy files to and from Azure, or any [http://blogs.msdn.com/b/windowsazurestorage/archive/2014/03/11/windows-azure-storage-explorers-2014.aspx Azure Storage Explorer] tool to browse the vault interactively. These require the use of an account name and access key, which can be obtained from the connection string (see the VaultTransferTool section below for details). While it is slower for bulk transfers than AzCopy due to operating synchronously, the use of the VaultTransferTool is recommended for most operations if possible, however, as it handles case conversion properly (all files on the Azure vault must be lowercased) and automatically avoids overwriting newer files.

When deleting character files from the vault, remember to use the ALFA website's Clear Vault Cache tool to clear out any cached copies of the character file to delete.

=== VaultTransferTool ===

Build the ACR repository and then build the ACR_ManagedScripts solution in alfa2_acr.hak\ACR_ManagedScripts (or else simply build VaultManagement\VaultTransferTool\VaultTransferTool.csproj directly from MSBUILD).

All usage of the VaultTransferTool needs a connection string. Get this from the config table in the database (VaultConnectionString), and pass it on the command line with -connectionstring VaultConnectionString, in addition to the operation to perform.

Help text for the vault tool:

<tt>ALFA Azure Vault Management Tool v1.0.5334.26752

Usage: VaultTransferTool [-connectionstring <connection string>] [-download <path> | -upload <path> | -delete <path>] [-includeall]

The -connectionstring argument designates the Azure connection string to use to communicate with the vault.

One of -download <path>, -upload <path>, or -delete <path> must be specified. The -download and -upload options enable downloading files from the vault, or uploading files to the vault. The given path should be laid out like a normal server vault directory, with a subdirectory for each account name and character (*.bic) files in each subdirectory. Files are never deleted from the remote vault, only updated with -download or -upload. A file is only transferred if the source of the transfer is newer than the destination file (unmodified files aren't copied again).

To delete a file, use -delete <path> where <path> is in the form of account\character.bic. The file is permanently deleted from the Azure vault, but the cache should still be purged from each server using the purge cache tool to ensure that it is not regenerated the next time a player logs on to a server that had previously cached the character file to delete. The file to be deleted doesn't need to exist on the local machine, and is not deleted from the local machine if it did exist.

Normally, only character files (*.bic) are transferred. Use the -includeall argument to transfer all files, regardless of file extension.</tt>