Neverwinter Nights Extender 2
From Nwnx
This documentation is © by the Avlis Team. Version 2.6.1 of 14.01.2005.
|
|
Introduction to NWNX
The Neverwinter Nights Extender (NWNX) is a program that has the power to push the limits on what you can do with NWN and its integrated script language.
While NWN and the toolkit are complex and powerful tools, we at Avlis often felt that some things are just too limited, in order to successfully run a large persistent world. The first incarnation of NWNX brought the community realtime database access over ODBC, giving advanced scripters access to every conceivable DB they might want to use. During the time since the first release in February 2003, I tried out various new ideas like linking servervaults with the help of NWNX, creating advanced data structures like hashmaps and linked lists, and played around with some debugging and profiling code.
NWNX actually consists of two parts: The executable, which displays the NWNX window and runs the process and gamespy watchdogs, and a dynamically linked library (DLL in the Windows version, .so in the linux version), which runs inside the NWN server.
In order to establish communication between scripts and the outside world, NWNX intercepts calls to the NWScript function SetLocalString() and examines the variable name that is passed to this function. If it begins with the string "NWNX!", NWNX parses the request and stores any resulting data into the value of that variable, which in turn can be read by a script with GetLocalString(). Easy, huh ?
After NWNX2 has loaded the server and rotated the log files, it takes over responsibility for restarting the server should it crash. It does not depend on a specific version of the server (1.65 as of this writing) and thus should work with upcoming releases, too. The current version supports all known versions of Microsoft Windows.
FAQ & Troubleshooting
Q. What is NWNX? A. NWNX2 is a program that loads the NWN server and injects the functionality contained in the various NWNX plugins into the server. Setting special string variables using NWScript triggers the NWNX requests. The resulting data can be read with the usual string functions.
Q.What are the system Requirements for NWNX? A. NWNX currently works with all Windows operating systems. If your system processor can handle running Neverwinter Nights, it can more than handle NWNX.
Q. Will there be a LINUX port? A. We have a version of NWNX2 for Linux available. Refer to our sourceforge page.
Q. Since NWNX is running the server as a child process, does the parent also have crash monitoring so it can auto-reboot the server if it crashes? A. If the child process crashes or becomes unresponsive to network traffic, NWNX will reboot it.
Q. Will I still be able to start my server up with firedaemon(or any other server crash utility)? A. NWNX will restart the server if needed. Firedaemon may possibly be able to restart NWNX instead of the server, but we have not looked into this at all.
Q. Any chance the source code will be open sourced? A. Shortly after the initial release, the complete source code was released as part of the distribution of APS/NWNX2. Licence NWNX is distributed unter the terms of the GNU GENERAL PUBLIC LICENSE included in licence.txt. NWNX uses Mathias Rauen's excellent library "madCHook" which is licensed under the terms included in licence.txt
NWNX plugins
NWNX plugins are a new concept introduced in version 2.5. Because it soon became apparent that the wide variety of possible uses for NWNX would lead to bloated and unreadable code, if all that functionality would be in a single library, Avlis team member Jeroen created a "plugin framework" around the original NWNX. Every NWNX plugin is contained in a single library (DLL), which name begins with "", e.g. "odbc.dll" for the ODBC interface.
One of the advantages of this approach is that you can choose which functionality you want to have available, and then just make use of a subset of the existing plugins. Say for example, you want to have database connectivity and a linked list implementation. Then you would just copy the two files "odbc.dll" and "llist.dll" into your NWN directory. NWNX dynamically loads these plugins on startup, enabling the functionality contained in these plugins.
Another important advantage is that now third party developers can easily extend NWNX with their own ideas and make their plugin available to others in a unified way. So instead of having many different, incompatible versions of NWNX floating around, you always have one NWN executable, one NWN main library, and as many NWNX plugins as you like.
Starting with version 2.5.4, the plugins are available as separate downloads and no longer included in the main distribution package. This will make it easier for us and our users to stay up to date with the latest releases of NWNX and the various plugins.
Available plugins
To give an overview of what is possible with NWNX, we list of some of the available plugins here. Get the latest versions of those plugins on nwnx.org. The plugins come complete with documentation and a small demo module that demonstrates their usage.
ODBC
The historically most important plugin is the ODBC interface for Neverwinter Nights. Not so long ago, there wasn't any realtime database solution for NWN, when the Avlis team released the first version of NWNX, which suddenly opened a whole new world for owners of persistent worlds. This plugin and the accompanying APS (Avlis Persistence System) script is what made NWNX known in the community.
PROFILER
The "Profiler" is a NWNX plugin that spits out statistics about running scripts. It shows how often a script has been called, how much time it took to complete, and gives some overall statistics. It also shows how much time CPU NPCs need for pathfinding.
HASHSET
This plugin implements an advanced data structure, combining a hashmap and a set. This means you can set up associations between key - value pairs (hashmap), and also cycle through all stored data (set). You can even use this like an array, although it has much more to offer than just that.
FUNCTIONS
This is an experimental plugin that gives access to some new functions to use with items. It's main purpose is to demonstrate how to modify the server's memory in order to change various properties on items.
TIME
This plugin implements a simple, yet highly accurate timer. Perfect for knowing how long your functions really take to execute.
Installing NWNX
NWNX2 has been extensively tested on MS Windows 2000 and XP. Windows 9x has also been tested and we encountered no problems with NWNX2.
Installing NWNX2 is super easy. Download the file and unzip it. Take the files "NWNX2.exe", "NWNX.INI", "nwnx-module.dll", and "madCHook.dll" and place them in the directory where your NWN installation resides (usually C:\\Neverwinternights\\NWN). Done! If you want to change the default configuration parameters of NWNX, edit the section [NWNX] in NWNX.INI accordingly.
If you have a previous version of NWNX installed, remove the files nwnx.dll and madCodeHookLib.dll.
Now copy the NWNX plugins you want to use into the NWN directory.
Running NWNX
Go to the directory where you installed Neverwinter Nights and double-click on "NWNX2.exe". You will see the small window of NWNX2 and shortly after that the NWN server starts. The NWNX2 window contains some statistics and checkboxes that control the watchdogs, i.e. the functionality which restarts the server after a crash. (you need to add the "-module" option so NWNX2 knows what module it should load after a crash). If you don't need the watchdogs, simply close NWNX2 after it started the server.
Right before NWNX2 loads the server, it rotates it's own and the server's log files. You will find directories named "1"..."9" below your "logs.0" directory. The directory "1" always contains the newest logs, and "9" contains the oldest logs. All log files older than those in "9" are deleted to preserve disk space.
All activity is logged to a file called "nwnx.txt". This file is created in your "logs.0" (or .1, .2, etc.) directory and looks like this:
NWN Extender V.2.6.1.0 (c) 2004 by Ingmar Stieger (Papillon) and Jeroen Broekhuizen visit us at http://www.nwnx.org * Loading plugins... * Plugin functions is loaded. * Plugin odbc is loaded. * NWNX2 activated.
The NWN Extender will make sure your server is restarted should the module crash. You can specify any commandline options Bioware's dedicated server understands, e.g. you can automatically load a module on startup (or restart after a crash) with: "NWNX2.exe" -module MODULENAME,
NWNX command line options
These options are understood by NWNX2. All other (i.e. unknown to NWNX2) options are passed to the server. Example command line:
C:\\Neverwinter Nights\\NWN\\NWNX2.EXE -module "My Module" -publicserver 1 -gamespywatchdog 1
| Option | Default value | Description | Example |
|---|---|---|---|
| -processwatchdog [0|1] |
|
Set to 0 to disable the process type of watchdog, 1 to enable it. | -processwatchdog 1 |
| -processinterval 1..n |
|
In seconds. How often the process watchdog will check if the NWNights server process is still there. | -processinterval 7 |
| -gamespywatchdog [0|1] |
|
Set to 0 to disable the gamespy type of watchdog, 1 to enable it. | -gamespywatchdog 1 |
| -gamespyinterval 1..n |
|
In seconds. How often the gamespy watchdog will check if the NWNights server process is still there and still responding to clients. | -gamespyinterval 60 |
| -gamespyretries 1..n |
|
How many chances the gamespy watchdog will give the server to answer. If it got no answer after this many tries, the server process is killed and restarted. | -gamespyretries 3 |
| -oldgamespyprotocol [0|1] |
|
Set to 1 if you have a pre 1.32 server and make use of the gamespy watchdog. | -oldgamespyprotocol 1 |
| -restartdelay 1..n |
|
In seconds. How long NWNX will wait before it restarts the server. | -restartdelay 5 |
NWNX.INI file
In adddition to the command line options, you can also set configuration parameters in the [NWNX] section of the NWNX.INI file, which should be in the same directory as NWNX2.EXE is. The following parameters are understood by the main program:
ServerPort = 5121 ModuleName = "aps_demo" WatchdogProcess = yes UpdateIntervalProcess = 5 WatchdogGamespy = no UpdateIntervalGamespy = 20 GamespyRetries = 5 OldGamespyProtocol = no RestartDelay = 5
(The values shown here are the default values).
These values can be overriden by command line parameters, so you could put most of your default options into the INI file, and specify special options (e.g. -port) on the command line.
