nwscript.nss - Playing with Fire and Custom Constants

Introduction


Editors Note: nwscript.nss is no longer in the override directory. Since version 1.29, you can include your own versions of the nwscript.nss when distributing a module without ruining the NWN installation. That solves the problem of sharing your custom constants used in your module with others. The only downside to this is that when you build the module, it will attempt to compile nwscript.nss as well. It, of course, fails and the build log gives an error. However, all the actual module scripts still compile fine with the new constants defined in your custom nwscript.nss file.


This is a short tutorial on how to get custom constants to appear in the 'Constants' section of the Toolset editor. Along the way, I'll describe the nwscript.nss file, how you can manipulate it, and some of the many dangers of doing so.


Lasciate ogni speranza, voi ch'entrate - Abandon All Hope, Ye Who Enter Here


Warning: it is entirely possible to knacker your nwscript.nss sufficiently to make using the Script Editor impossible, and your game unpatchable. (I know, I've done both). If you're going to play with nwscript.nss - and why not - BACK IT UP NOW... and back it up with your current patch version, too. From here on out, I'm going to assume you have a backup for your current and every future patch, know how to recover it, and wouldn't dream of whining to me when your installation goes tits-up and has to be reinstalled from scratch. Trust me, you won't like my response.


What Is It, Where Do I Find It?


nwscript.nss is a special NWNScript source file, that's used by the Aurora Toolset for two principal purposes:

  1. Function descriptions - all that helpful text that appears in the Script Editor when you've highlighted a function in the browser pane comes from nwscript.nss. You'll demonstrate this to yourself in a minute.
  2. Constant declarations - all the 'built-in' constants that appear in the Script Editor browser when you press the 'Constants' button come from nwscript.nss. Any supposedly invariant constants you want to create in include files just get lumped in with all your other variables.

Unlike every other script that comes with the game, however, nwscript.nss is not compiled. Yes, you read correctly, its never compiled. In fact the game engine itself doesn't even need it. You can test this out pretty easily. Since the first patch the game's used the copy of nwscript.nss that you'll find in the /override folder. Delete everything in the file except any single constant definition, and save it again, still in the /override folder. Now play the game... it plays fine. The same can't be said for the Script Editor, however, which is now a little bit reluctant to compile your scripts. Restore the backup you took before deleting. [See section with oh-so-erudite, and not-at-all-cliched heading above if you didn't take a backup.]


Some of the Comments Could Use Some Expansion


Boy, could they ever. I'm hugely grateful that BioWare produced the game, and totally understand that writing documentation is utterly, utterly boring, especially for a cool project where you could be writing code involving EffectDeath instead; that's what the NWN Lexicon project is all about - spreading the documentation load amongst hopeless fanboys (present company included). Happily, you can replace any comment you like by editing nwscript.nss. It's as simple as that. Why not pick a function and try it? Since these are just comments, there's not much to go wrong here (but see below), so knock yourself out. Note: there's a possibility that the NWN Lexicon project may, in future, produce an 'enhanced' nwscript.nss. Maybe. You're probably better off just using the .chm help file, though.


So why isn't the file compiled? After all, there are all these commented function declarations. Well, those functions are all built-in to the engine, compiled in Edmonton, buried in the code functions. You can't change them. Unlike those pesky nw_i0_generic-type included functions, they're graven in stone (until the next patch) and you don't get to see the source, either, unless Muzyka and Zeschuk are writing your paycheck.


Constants, Constants, Show me the Constants


One of the minor irritations I found with the script editor is that manifest constants defined in included libraries appear in the 'Variables' section of the browser, behave like variables (which they are, I guess). There's no way to make them real replace-them-at-compile-time constants. Officially. But nwscript.nss is where the Toolset compiler gets its list of constants, and nwscript.nss is just another text file, so you can add your own.

Why is this not a horribly bad idea?
Because all the constants are replaced by their values at compile-time, it's perfectly safe to do this with your custom constants if you want to distribute your module to the general NWN populace.
Why does this suck a bit?
Because no-one else can compile your source code without your custom nwscript.nss, making it hard to evolve or reuse your work, bugfix or treat it like the open source that it ought to be.
Why does it suck less than it might?
It's a good idea to keep a copy of any constant you add into your nwscript.nss to an includable script as well... partly because you're probably going to have to recreate nwscript.nss after a patch, but mostly because then you can include a commented '#include' statement in your source code, so all the nice re-users of your fine code can re-use your code.
Is there anything else to do with this?
You could implement a half-hearted copy-protection with this, but you would be a plonker to bother.

Details! Details! I want Details!

  1. Open nwscript.nss.
  2. Add a constant, like: int ISK_MASK_WITLESS = 0x1;
  3. Save nwscript.nss.
  4. Use your constant in your other scripts.
  5. Er... that's it.

So What Can Go Wrong?


Aside from inconveniencing re-users of your code, there's only a couple of ways to really mess yourself up (that I've found, anyway). First, you can render the Script Editor incapable of compiling. Easily fixed: restore your backup. The less obvious, and more irksome problem is that the updater is incremental (that's how it patches 30Mb of files with a 3Mb patch). To be able to patch a file, the updater has to verify that the old version is exactly the same as the version it expects to patch... otherwise things could go horribly, horribly wrong. If you've gone and edited nwscript.nss, and those lovely folks at BioWare implement some new engine function (SetMapVisible(FALSE), please), the updater will barf when it gets to your munged file. Easily fixed: restore your backup to the patch target version.


Conclusion


That's all folks. It turned out there wasn't a lot to say about nwscript.nss, except "you can change it", and "be careful". Never mind, I had fun writing this, hope you enjoyed reading it. If you have any feedback (positive, negative or bipolar), you can reach me as Iskander on the NWN boards.




 author: Iskander Merriman, editor: Charles Feduke, additional contributor(s): Diego Chiodini, Joseph Berkley, Andrew Hart
 Send comments on this topic.