Translator: Neverwinter Nights - UA-ScriptEase/scriptease GitHub Wiki

To test the NWN file I/O, write a file in ScriptEase and perform the same operation operation on a separate, untouched, clone of the module file. You can then use VBinDiff to check out the problems.

When debugging, you'll end up sitting with the docs open all the time. Get used to counting bytes. Also, keep backups of all of your files that you care about. Especially the clean version.

BioWare uses Little Endian format for all of its numeric data, which means everything is backwards. This will trip you up a lot. For example, you might see the following hex bytes for a DWORD (32 bit unsigned int): 38 04 00 00. The actual value of that DWORD is 0x00000438 = 0x438 = 1080 in decimal.

As of August 2013, we still don't support some types for I/O, for example, doubles. Hopefully that doesn't come up, but it wasn't necessary for what we needed, and it was going to be a lot of time to implement.

#Accessing NWN Development Resources The File Format Documentation pdf files are available on request.

These were obtained from http://nwn.bioware.com/developers/, but you might notice that that link fails. BioWare removed the nwn.bioware.com site, but it is still accessible through the internet archive: http://web.archive.org/web/20110611110338/http://nwn.bioware.com/developers/.

There were some forums at nwn.bioware.com, but those are gone too. New forums are accessible at: http://social.bioware.com/forum/1/subindex/153. Not a lot of people will know specifics about the file formats, but it's a resource just the same.

You can now search the archived old forums here: http://23.21.191.172:8081/content/nwn/search.jsp?

#How to Read the NWN .mod File Format The File Format is very confusing. We pretty much had to reverse engineer the module files to find out how they work, and to write them correctly. I really, really hope you never have to touch this aspect of the ScriptEase II translator, but here goes. Read the previous sections before reading this. Also read the actual File format documentation from BioWare first. Seriously, just take like two hours and read those dense things. I know, it sucks and you probably won't understand half of it while you're reading it, but reading them over once before tackling each one individually will make the whole operation go much smoother.

Read about the ERF files first. .mod files are a type of ERF file. Then read about the GFF format, as every single Creature, Item, Placeable, etc is a type of GFF. An ERF file contains a collection of GFF files. It also has other things, but you hopefully won't have to deal with that. Each type of GFF is distinguished by an extension, like "UTC" for creatures. Each type has some common attributes, but also many very unique attributes.

Every single file, including ERF and GFF files, has headers. These tell the NWN parser how far to go when reading a certain part of the file. In the SEII translator, we do this by calculating what changed and adding the changed number of bytes to the header number.

Remember how everything is stored in that .mod file? You can look at it using VBinDiff. Just look at one file instead of two.

To really learn how to read the format, create a new module and add one creature to it. Save it. Open ScriptEase II, don't add any scripts, and then save the story. Now open the .mod file in VBinDiff. Restart ScriptEase II in debug mode, set a breakpoint where the module gets loaded, then step through while trying to follow along in VBinDiff. You'll see how ScriptEase II reads various bytes as headers, the active state of a creature, etc.

Oh, and one more thing: sometimes the documentation from BioWare is either wrong or outdated. There should be a couple of code comments in the translator making note of this.

#Preventing Corruption Whenever you change the way these files are saved, you need to rigorously check for corruption. To do this, start with two copies of one, simple-as-possible module file. Change whatever you needed to change using the Aurora toolset. Then on the other one, change it using SEII. Now compare the two files using VBinDiff. Any difference in the two files is generally something to worry about.

If the file created in SEII is different but still loads in the toolset, there may still be issues. I had one problem where some random scripts had their text replaced with a [] symbol. Or some letters were removed. It was an issue with the size of the offset, which I wouldn't have found without looking into the byte code.

You can also try creating another copy of the SEII saved module, then opening it in the toolset and Building it from one of the menus. Check for any errors there, then compare this copy with the SEII generated one. The built one is more correct.

It's easy to corrupt modules, so take care that you test constantly if it still works in Aurora/playing it. Sometimes it will open in Aurora, but you can't play the game. Sometimes the module will only corrupt after saving twice, although that's less likely.

#Story Point Name Format We can name Story Points whatever we want in ScriptEase II, including giving them the same name. That is why each story point also has a unique ID integer associated with it.

We use Story Points as tags in Journal categories, whose length cannot exceed 32 characters. We also use them in various other places. So it makes life much easier if we have a consistent name scheme.

To convert a Story Point to a 32 character unique name, call SE2_Story_GetUnique32CharName(string name, int uniqueID); from i_se_story.

#Visual Binary Diff

##Description Tool for viewing two sets of binary data. It displays the binary as hexidecimal strings, and simultaneously shows the ASCII interpretation of the hex. Also has searching capabilities, and other neat features.

Very handy for testing that game-specific file I/O works as intended, because it allows you to do a change in ScriptEase, and then do the same change by hand in that game's toolset and see if the products are at all different.

##Notes To run, go into the console/command prompt and run VBinDiff.exe <file1> <file2>

Hit Enter to see the next difference, F for find, PageUp/Down to scroll faster than arrow keys. There are other commands, but those will be the most used.

⚠️ **GitHub.com Fallback** ⚠️