NWN Module Packing/Unpacking Utilities

Note: These tools require Java to run. I've only tested it on Java 1.4 and above. Go here and download the latest J2SE if you don't already have Java installed.

Also Note: This is currently alpha software, which for me means that it should theoretically work but I've only tested it on a handful of modules. So, make sure to keep backups of your work... just in case. Good advice anyway.

Introduction

ModPacker/ModUnpacker

Included are two simple tools that will pack and unpack module files. This is similar to what the Neverwinter Nights toolset will do, but alot faster and command line driven.

I wrote these tools for when I'm editing the scripts of a large module. It can be quite painful to save a 62+ megabyte module from the Bioware toolset every time I make a minor change to a script. On my system, the module packer tool will rebuild the module file in about 8 seconds. The same module takes almost a minute to save with the toolset.

Combined with Torlack's commandline-based script compiler, I can edit scripts, build them, and roll them back into a module without ever having to run the bioware toolset... and I can do it all from the command line.

ModToXml/XmlToGff

Also included are some tools for converting modules and/or their packed GFF files into XML files and back again. This makes it easier to store module "source" files in a CVS repository and collaborate with other developers. Sometimes it's a nice way to do quick edits to a file too without booting up the bioware toolset.

Installation

Make sure you have Java installed.

Unzip the modpacker.zip file to a directory somewhere.

Run the setup.cmd script that is in this directory. This script will create six other scripts called: setpath.cmd, ModPacker.cmd, ModUnpacker.cmd, ModToXml.cmd, GffToXml.cmd, and XmlToGff.cmd.

Whenever you want to use the tool, run the setpath.cmd to setup your environment in the command line within which you will be working. After that, you should be able to run ModPacker, ModUnpacker, etc. from wherever you want.

You can check your installion by running either ModPacker.cmd or ModUnpacker.cmd with no arguments. If things are working correctly, you should see the simple help message explaining the tool's usage.

Example:

C:\>modpacker
Usage: ModPacker <directory> <mod file>

Where: <directory> is the location of the files to pack.
    and <mod file> is the file to create.

ModUnpacker

This will extract the resources from a module file and save them to a directory. The Bioware toolset does the same thing when you open a module, but with ModUnpacker you can specify which directory to dump the files.

To run, type ModUnpacker mymodule.mod mydirectory where mymodule.mod is the name of the module to unpack and mydirectory is where you want the files dumped. You must have already created the directory ahead of time.

Example:

ModUnpacker FizWorld.mod testdir

The above will unpack the FizWorld module and store all of the files into the directory testdir.

ModPacker

This will use the contents of a directory to create a module file. It will ignore sub-directories and file types it doesn't know how to deal with. Other than that, it will try to pack everything so don't put strange files into the directory.

To run, type ModPacker mydirectory mymodule.mod where mymodule.mod is the name of the module you wish to create and mydirectory is the location of the module resources you wish to bundle.

Note: this tool will happily write over existing module files without a care. So be careful and backup your work in case of mistakes.

Example:

ModPacker testdir UpdatedFizWorld.mod

The above command will repack the module we unpacked in the ModUnpacker example above. In the ideal case, if we've made no changes then FizWorld.mod and FizWorldUpated.mod would be identical except for the internal date stamp. The size should be the same in any case.

ModToXml

This will extract the resources from a module file and save the GFF-based files as XML representations of the data. This is similar to the ModUnpacker utility except that you'll end up with a bunch of XML files for the .are, .gic, .itp, etc. files.

To run, type ModToXml mymodule.mod mydirectory where mymodule.mod is the name of the module to unpack+convert and mydirectory is where you want the files dumped. You must have already created the directory ahead of time.

Example:

ModToXml FizWorld.mod xml_testdir

The above will unpack the FizWorld module and store all of the converted and copied files into the directory xml_testdir.

XmlToGff

Unfortunately, at the time of this release, the only way to get your XML files back into a module is to convert them to binaries using XmlToGff and then run ModPacker on them. So it's a two step process.

Also note, XmlToGff (and GffToXml) has its command line arguments backwards from what one might expect after using the other tools. It takes the destination directory as the first argument and then a list of files for the following arguments.

To run, type XmlToGff mydirectory myfiles/* where mydirectory is where you want the converted files to be stored and myfiles/* is the set of files to be converted. Non-XML files will simply be copied. You must have already created the directory ahead of time.

Example:

XmlToGff testdir xml_testdir/*

The above will convert all of the files in xml_testdir and store them into the direct testdir... copying any non-xml files as it goes.

From there you could run ModPacker to make a module as:

ModPacker testdir UpdatedFizWorld.mod

GffToXml

For symmetry, a GFF to XML converter has also been included. It functions pretty much the same say that XmlToGff does except in reverse.

To run, type GffToXml mydirectory myfiles/* where mydirectory is where you want the converted files to be stored and myfiles/* is the set of files to be converted. Non-GFF files will simply be copied. You must have already created the directory ahead of time.

Example:

GffToXml xml_testdir testdir/*

The above will convert all of the files in testdir and store their XML counterparts into the direct xml_testdir... copying any non-convertable files as it goes.

Typical XML conversion workflows

Simple workflow:

  1. Step 1: Unpack the module as XML and native files.
  2. ModToXml FizWorld.mod xml_testdir

  3. Step 2: Edit the XML files as you see fit.
  4. Step 3: Reconvert the files to binaries.
  5. XmlToGff testdir xml_testdir/*

  6. Step 4: Repack the module.
  7. ModPacker testdir UpdatedFizWorld.mod

Advanced workflow (for those that always want the intermediate binaries):

  1. Step 1: Unpack the module as native files.
  2. ModUnpacker FizWorld.mod testdir

  3. Step 2: Convert the binaries to XML.
  4. GffToXml xml_testdir testdir/*

  5. Step 3: Edit the XML files as you see fit.
  6. Step 4: Reconvert the files to binaries.
  7. XmlToGff testdir xml_testdir/*

  8. Step 5: Repack the module.
  9. ModPacker testdir UpdatedFizWorld.mod

The advanced workflow is useful if you are using tools that can determine when files need to be reconverted and when they don't (like if you're using a build tool like make or ant). I think the NWN-tools tools are fast enough that this really only makes a big difference for extremely large modules... and even then, only if you find you're repacking frequently.

Non-windows Users

All of the above holds true except you may need/want to write your own shell scripts based on the Windows .cmd script files.

Preemptive Answers

A few answers to questions that may be asked.

Q: Who will find these tools useful?
A: Anyone that prefers to do module development outside the Bioware toolset when possible.

Q: Is the source code available?
A: Yes, most certainly. See the sourceforge CVS at http://nwntools.sf.net/

Q: Why did you write this in Java instead of <insert super-elite language here>?
A: Because it's the language I use the most and it allowed me to cobble the original packer/unpacker tools together in a few hours.

Q: Why did the install size grow with this release?
A: Well, with the XML conversion utilities now included I depend on a couple other projects including Meta-JB and in some cases Log4j. I tried to keep it trimmed down though.