Tuesday, 30 June 2015

Installing User Mods & Custom Content: READ THIS FIRST!

If you are new to installing users' modules or their custom content, then hopefully reading this will save you a lot of potential frustration and/or having to send emails back and forth with the authors asking them for help about getting something to work. Even if installing user material is not new to you, then maybe this article will help you be aware of any potential pitfalls you have not yet experienced.

NOTE: This article is intended for the player end-user of created material, as opposed to material created for builders to use within their own projects. It is assumed builders will already know most of what I am about to cover, although I would draw their attention to the ADVANCED section, which may help to avoid issues with accidental duplications of files.

Even if you think you understand the BASICS, please at least consider reading the ADVANCED section of this article, as that covers where most issues arise after an installation.

THE BASICS

BACKGROUND

The Neverwinter Nights PC game franchise comes with a toolset that allows users to build their own custom content for others to download, and then to install to use or play. User content can vary from relatively simple User Interface (UI) alterations (e.g. Making the "Game Paused" wording say something different when the game is paused), to building an entire module, with or without additional material. When installing user content, however, care is needed to make sure the files and folders that make up that content are placed into the correct NWN folders on your own computer.

NWN FOLDERS

From here on in, whenever I use NWN, I will be referring to the NWN2 game only, but some aspects of what I say can also be applied to the original NWN1. The main differences are that NWN2 has more places where user content files and folders can be placed.

The following also assumes a default installation on a computer running Windows 7. Please bear that in mind if you have changed the installation path or run a different operating system.

When you install NWN, the main game default installation path is:-

C:\Program Files (x86)\Atari\Neverwinter Nights 2

When installing USER CONTENT, there is NEVER any reason to alter any of the files or folders from those in the above folder. At the very most, only ever make copies of files from this installation directory, and work with the copies inside the folder mentioned next.

However, at the time of installation, a user folder for NWN is also set up here:-

C:\Users\UserName\Documents\Neverwinter Nights 2

When you are asked to install user content, it will be into the folders that are found in this folder. The most important folders to note are as follows (as found in alphabetical order):-

Campaigns
hak
modules
movies
music
override
tlk
ui

This article covers files (and/or folders) that are asked to be placed inside these folders. If you asked to place any other files into other folders in this path, then please follow the builder's instructions.

USER CONTENT PLACEMENT

When you download user content or a user module, then the builder should explain to you in a Readme.txt or similar instructions where to place the files you have downloaded. Some user content may only use one of these folders, whereas downloads (such as modules) are likely to use many or possibly most of these folders.

Hopefully, even if the builder does not give clear instructions where their files should be placed, the way they may have packed the files may help indicate where they should be placed. This is the way each folder should be used:-

Campaigns - Contains the "campaign" folder. i.e. The "global" files for one or more modules.
hak - Contains hak files: Material used to alter in-game visuals. (Primary 2da files are placed here too.)
modules - Contains a module file, or a module folder. (Differs according to builder tastes.)
movies - Contains user created movie files in bik format.
music - Contains user created music files in bmu format.
override - Contains different files or folders to help change the way a game plays.
tlk - Contains user created tlk file. Alters what text the player receives in a game. Can be original reworded or new text.
ui - Contains user altered or created primary UI XML files. (Can include supporting images & sounds.)

NB: This is a general structure. However, it is possible (and even likely in some instances) that many files (even XML or 2da format) can and will be placed in the Campaign folder. However, some primary XML and 2da files have to be treated differently and are placed elsewhere, as explained above.

ADVANCED

FAULT FINDING

If you have followed the builder's instructions on where to place their files and you have done so correctly, then all should work fine when you start the game. However, through no-one's deliberate fault, problems can occur and are often down to duplicated files. (NB: There is an exception to this: See Some Safety Steps To Follow #4 below.)

While any file duplication can be a problem, there are two specific types of file that are more prone to duplication and are the highest likely to cause problems with your game. The two file types I refer to are the 2da and XML file formats. These two are more likely to suffer from duplication due to the high amount of alteration and testing they go through at build time, and also due to the location they are finally placed when the content is released.

For example, a single XML file may have five clear different versions (but all with the same name), spread across four different folders, with each one making a difference, subject to where it is placed. I will give an example of this in a moment, but first need to explain something about "priority" with respect to files being read for the game.

FILE PRIORITY

As far as I am aware, there are up to four folders that can affect when file priority is involved. Here follows the priority of folders from which the NWN reads and finally executes a file:

HIGHEST PRIORITY
================
HAK (PRIORITY) (*)
HAK (NORMAL) (*)
OVERRIDE
CAMPAIGN
CUSTOM UI (+)
=================
LOWEST PRIORITY

(*) NB: A game can come with more than one hak file to place inside the hak directory. Hak files have their own order of priority, subject to how they are installed by the builder, and so if a file appears duplicated in multiple haks, then only the highest priority hak version will count.

(+) This folder does, however, take the priority when you launch NWN for the first time, which is why it is used by builders to set up fonts, typefaces, opening images, etc for their module. However, once the game is loaded, it becomes the lowest priority as other folders (with files) take precedence.

So, what I am saying is, if you had, for example, an official campaign XML file with the same name (but each slightly altered in some way) in each of these directories, then the one in the HAK (PRIORITY) would be the only one to fire. If the XML file was not in the HAK (PRIORITY), then it would look at the one of next priority in the list, HAK (NORMAL), and if it were not there, it would look inside the OVERRIDE folder and so on, until it had gone through all the potential user folders.

If, after going through all the USER folders it does not find anything, then (if an official version exists) it will default to the official game version, which is installed with the game. (i.e. The ones you should NEVER alter.)

NB: I have NOT included the "module" folder, as not all files placed inside this folder have an impact. E.g. An XML file placed here will not do anything (at least in my tests). However, for the purposes of including it in the list, and if it does have any impact anywhere, then it would come below CUSTOM UI and just before the official game files. E.g. Official scripts can be altered and saved to the module by the builder, which then take priority here.

The 2da files suffer from the same kind of duplication error, as they can often be found in many places. So, if you have an old version of a 2da sitting in your override folder, which is taking priority of the one that you downloaded and comes in a campaign folder, then errors will occur.

SOME FILE INFORMATION

XML FILES: These are the files that alter the way the UI works within the game. UI are the "user interface" such as character sheets, inventories, maps, etc. It also includes some things you may not expect, like the fonts used and individual components, like scrollbars. If a font is missing, or a UI does not look correct, then the fault is likely to be with an XML file.

2DA FILES: These are two-dimensional arrays (2DA). Basically, think of a table with columns and rows, where code calls for references held within this table according to a row or column reference. If you are seeing odd behaviour with respect to some wording or missing text, especially related to character information, then it is likely to be caused by a missing or corrupt (old version) of a 2da file.

OTHER FILE TYPES: The user folders will contain a great number of other files, from new models, tilesets, terrains, images, sounds, scripts, etc, etc. And, in principle, they can all suffer from the same "duplication priority error". E.g. An old tga image file sitting in a hak, when a game is trying to use the one that comes within its campaign folder, will cause problems. However, due to the way that many of these other file types are put together at build time, they are less likely to encounter this issue. HOWEVER, if you do experience unexpected results, then do a search for the file in question among all the sub-directories of the NWN user directory.

SOME SAFETY STEPS TO FOLLOW

Here is my advice to follow when installing custom content:-

1) KEEP THE OVERRIDE EMPTY: Most user content, if properly structured, should NEVER need to have anything placed within the "override" folder. The "override" folder is a quick and messy way to fix things, or, more normally, to test things. If you have downloaded custom content that uses the override, then chances are, if you have other custom content you use, then it is likely to break that. NB: Note, however, a duplicate file in an override (even if newer) will NOT take priority over the same named file in a HAK.

2) CARE WITH CUSTOM UI FOLDER: You should take careful note of files that are added to the CUSTOM UI folder. There is nothing wrong with files being placed here, but you should be aware that files placed in this directory have the potential to alter EVERY game you play while these files are present. However, sometimes, these files NEED to be present to ensure the custom content or module work as intended, and so one must not be afraid of following the instructions to place them there. Just be advised that it is best to work with only one custom folder at a time within the CUSTOM UI. Most builders will provide a folder with their CUSTOM UI content, so it is simply a case of temporarily removing this folder to the desktop (for instance) if you intend to play a different module.

3) CAMPAIGN & MODULE FOLDERS: Files and folders can be placed into these folders without any real concern, unless, of course, somebody happened to use exactly the same name for a file or folder as you are about to copy. They can sit here indefinitely without causing any concern to any other game at all. The only caveat to be aware of, is if the builder updates their content, you may also need to update files in these folders too. (However, see THE PRIORITY HAK next.)

4) THE HAK FOLDER: Treat similar to the Campaign & Module folder. i.e. Files placed in this folder are not likely to interfere with any other module, unless they have the same name as another hak used for another module. NB: This may be important to know if you have downloaded two modules, and each uses the same hak, but the builder may have slightly altered the original hak and not renamed it. This is unlikely to happen, but may be worth noting if the builder forgot themselves.

THE PRIORITY HAK: More importantly, however, is this folder is the one that can contain what I call the "Patch Hak", which is basically a dedicated priority hak for a campaign or module. If your module comes with such a hak, then be sure to keep this hak up to date, as it contains all the latest fixes for the game in question, and any files it contains get priority over any older ones. In this case, this is where the file priority system works in our favour, as it uses (in theory) the most up to date version of the file in question, over  and above any other version found lower in the list of folder priorities. This is the one time when file duplication is expected for players who are "patching" their game. Using this method of file updating means a player does not have to restart a module, but can carry on from a saved game.

5) THE TLK FOLDER: This folder is where you place the builder's own tlk file. Once again, files placed in this folder are not likely to interfere with any other module, unless they have the same name as another tlk file used for another module. NB: The official campaign tlk file is called Dialog.tlk and is found in the installation directory. This file should NEVER be altered, and any user tlk files should use a different name and be placed in the tlk user folder.

NB: I am unaware of anybody editing the official Dialog.tlk file directly, but there would have to be good reasons for doing so. In theory, a good builder will rather supply an end user with edited 2da files and a new tlk file so that all original files are left unaltered.

6) MOVIES & MUSIC FOLDERS: Treat similar to the Campaign & Module folder. i.e. Files placed in this folder are not likely to interfere with any other module, unless they have the same name as another file used for another module.

FINAL COMMENTS

There is a great temptation for players to try to install all their favourite modifications for the many user modules available. This comes inherent with installation dangers! Often, a module contains hundreds, if not thousands of edited files. Unless you know where to look for potential file duplications, then any modification left within an override or added as another hak has huge potential to cause the game to fail. Even if you do find the clashing (duplicated files), trying to merge them without knowing the full implications, will also likely cause a broken game.

So, while the temptation may be great, I would recommend being prepared to make sure your environment is "clean" before you attempt any potential installation, and use only the files that come with the module.

Lastly, if you have done everything your end correctly, then at least you have a good understanding of what to explain to the builder with respect to the problem you are experiencing.

No comments: