Dummies Guide to Updating a Server with Git

This article presupposes that the updater has a git account and git extensions set up on their machine, as described here: [[1]]

I have made every mistake there is in learning to update the Silver Marches, ALFA003. If I haven't, I soon will. Through trial and error, this is the procedure I follow in updating TSM, and I hope it helps builders on other servers, too. Whole process takes an hour, longer if there are problems.

1. Finish building. Compile any changed scripts and save the module directory.

2. Toolset/File/Shared Content/Prepare Downloadable Files.

Tick the boxes to skip music and haks. If you do not do this, files will be included in your update that can break the autodownload (ADL) of changed .trx (walkmesh) files. After these two boxes are ticked, push the Scan button. Wait for it to scan your module to count the files it is going to have to stage. Scanning creates an .xml file called moduledownloadresources.xml inside your module directory. If you did scan music files accidentally, you will have to manually edit this .xml file later in the process, so do not scan music. This .xml file will tell the autodownloader what files to deliver to players as they log into the changed mod. You need to have this .xml file created by this scan/stage process when you get to the next step, or at the end of the process, the .xml will not be in the updated mod and the ADL will not happen.

After it finishes scanning, then push the Stage button. Staging puts all changed walkmesh files into a subdirectory called Staging, in your main NWN2 directory, on your machine. They will be put there as compressed lzma files.

3. Pull/Push to Git

Open Git Extensions. In Git Extensions, open your local master repository that was set up when you installed/configure Git. For me, that is c:Users/Wynna/Documents/Neverwinter Nights 2/modules/alfa003_Test.

Git Extensions/Commands/Pull: Pull down any changes made to the master remote repository since your own last update. It will pop up an interface with a few choices: pull from remote should be selected and set to origin. Make sure your merge options are set to 'merge remote branch into current branch'. Tag options should be 'follow tagopt...'. Click the 'Pull' button and follow prompts until you are up to date.

Git Extensions/Commands/Commit: Now put your own changes up. Choosing Commit from the File dropdown will bring up an interface and compare your local repository to the remote repository. Any changes it sees, it will list out in the upper left quadrant of your interface. Review this list to make sure that you have moduledownloadresources.xml in them as well as module.ifo and any files for edits you made to the module. Beneath the list is a lower left quadrant, currently empty. If the files all look right, click the Stage All arrow between these two windows. The files will be moved to the lower window. If you do not want certain individual files to be staged (readied), then committed (sent to the remote master module directory where they will overwrite existing versions), move them back up with the Unstage File arrow. When any individual file is highlighted, the upper right quadrant of the interface will show you the changes that git found in it as compared to the remote repository. The lower right quadrant is where you type in a brief description of the update, for instance: "Travel map updates". When you are certain that you have staged all the files that you want, click the Commit and Push button. Follow the prompts until you are told that the process was a success.

4. Download the newly updated module to the host

Some hosts are set up with Git on them at this stage. TSM does a manual download. For a manual module download, you should have remote access to the server host. If not, your HDM should get you credentials. Log in remotely to your server box. Using the Internet Explorer installed on the host box, download the zipped module from the github link provided on the main page of the github repository. Rename the old directory to get it out of the way and unpack the new one into the directory called module.

Look inside the new mod (called 'alfa003_tsm' for us) directory for a batch file called Compile. This has to be run for TSM every time. Otherwise, there will be no scripts in the mod. Double click this file and it will start to run an external compilation script in a popup command prompt window. When it has compiled every script, it will tell you. Close the command prompt window. Triple check that moduledownloadresources.xml is inside the {alfa003_tsm} module directory.

5. Upload changed .trx.lzma files to the ADL server

Install a SSH application called WinSCP. SSH is a service like FTP but more secure. The Infrastructure Admin will be able to provide login credentials to the ADL server. Navigate in WinSCP to home/alfa/public_html/NWN2/PWC/YOUR_SERVER. This is where you will upload any changed .trx.lzma files. Go to your Neverwinter Nights 2/Staging directory and look for any .trx.lzma files that were updated today during Step 1 above. If haks or music files were accidentally staged, do not upload them, here or anywhere. Upload only your changed walkmesh .trx.lzma files, overwriting any existing .lzma files with the newer versions.

6. Restart the mod

Announce a restart in chat. Check to see that everyone is off. Remote in to the server box. Click the Stop NWN2 Server Shortcut. If it doesn't work, right click on the task bar to pull up Task Manager. Manually quit the NWN2 Server process. It will wind down slowly until the process disappears. Wait a minute. Click the Start NWN2 Server Shortcut. It will wind up slowly, to use approximately 86% of memory at ~2.1 gigs in size.

7. Check the update

Once the restart is stable, log on and check that ADL is working and walkmesh changes were successful. If they were not, you will crash on entering any incorrect area. If they were...congratulations!

Troubleshooting:

A. Oh no! Music files were scanned and files from the server I play on were sent up to the server I build on!: Open the moduledownloadresource.xml in notepad. Find the bmu music files with a hash="" and delete them in the xml structure. When this happened to me, these were found at the end of my .xml file. Delete everything within and including the <resource> tags for each music file. Save. ReGit it up there. Restart the mod.

B. I started to scan my music and my haks, and now the haks insist on trying to be staged. Sometimes this comes along with an unhandled exception that crashes toolset: Shut down toolset. Remove the hak that causes the crash from the hak directory. Restart toolset. Click okay when it says it can't find the missing hak. Rescan and restage. Delete any hak.lzma files from your Staging directory. Do not upload them to the ADL server.

C. I prepared my shared .lzma files after I pushed the rest of the mod changes up to the remote repository: This means your moduledownloadresource.xml is not up there in the new mod and no ADL will occur for players logging in to the changed mod, meaning they will crash the first time they enter a changed area, because they don't have the new walkmesh. Redo the process, preparing shared files as Step #1, as above. Technically, you could prepare shared files, then push up the moduledownloadresource.xml after the fact, then just download it from the master repository to the host's {alfa003_tsm} mod directory, but the only browser on the TSM host is IE, and it won't allow download of an .xml file or even copy/pasting from the html version to create your own. It is actually easier to Git it up to the repository, then redownload the entire zipped mod and unpack it again.

D. Damaged/improper .trx: Rebake, restage the .trx. If it results in a moduledownloadresource.xml change, then Git both of them up to the remote repository. Get the revised .xml file into the mod, redownload it and unpack it. Reupload the .trx.lzma to the ADL server. Restart the mod.

E. Missing scripts: Everything seemed to work fine but when I log in to check the mod, there are no spawns, no script prompted dialogs, no chooser or creator contents. This means that you did not run Compile.bat. Compiled scripts are not stored on the master repository. If the entire mod is downloaded (as has to be done for TSM each time) then there are no compiled scripts in it. Running compile.bat solves this. After running it, restart the mod.