333 lines
13 KiB
HTML
333 lines
13 KiB
HTML
<html>
|
|
<head>
|
|
<title> NWNX Documentation </title>
|
|
</head>
|
|
|
|
<body style="font-family:Arial,Verdana,sans-serif;">
|
|
<h2>Neverwinter Nights Extender 2</h2>
|
|
|
|
<h4>This documentation is © by the Avlis Team. Version 2.6.1 of 14.01.2005.</h4>
|
|
|
|
<b>Visit us... </b>
|
|
<table border=1>
|
|
<tr>
|
|
<td> NWNX homepage</td>
|
|
<td> <a href="http://www.nwnx.org"> http://www.nwnx.org</a> </td>
|
|
</tr>
|
|
<tr>
|
|
<td> The Avlis homepage</td>
|
|
<td> <a href="http://www.avlis.org"> http://www.avlis.org</a> </td>
|
|
</tr>
|
|
<tr>
|
|
<td> Sourceforge project page </td>
|
|
<td> <a href="http://sourceforge.net/projects/apsnwnx/"> http://sourceforge.net/projects/apsnwnx/ </a> </td>
|
|
</tr>
|
|
<tr>
|
|
<td> NWNX2 page on NWVault </td>
|
|
<td> <a href="http://nwvault.ign.com/Files/other/data/1046636009723.shtml"> http://nwvault.ign.com/Files/other/data/1046636009723.shtml </a> </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Table of Contents:</h3>
|
|
<table>
|
|
<tr>
|
|
<td> <a href="#I">I.</a></td>
|
|
<td> <a href="#I">Introduction to NWNX</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td> <a href="#II">II.</a></td>
|
|
<td> <a href="#II">NWNX plugins</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td> <a href="#III">III.</a></td>
|
|
<td> <a href="#III">Available plugins </a></td>
|
|
</tr>
|
|
<tr>
|
|
<td> <a href="#IV">IV.</a></td>
|
|
<td> <a href="#IV">Installing NWNX</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<a name="I"></a>
|
|
<h3>I. Introduction to NWNX</h3>
|
|
|
|
<p>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.
|
|
|
|
<p>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.
|
|
|
|
<p>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.
|
|
|
|
<p>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 ?
|
|
|
|
<p>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.
|
|
|
|
<p><b>Licence</b><br> NWNX is distributed unter the terms of the GNU
|
|
GENERAL PUBLIC LICENSE included in <a href="licence.txt">licence.txt</a>. NWNX
|
|
uses Mathias Rauen's excellent library <a
|
|
href="http://www.madshi.net">"madCHook"</a> which is licensed under the
|
|
terms included in <a href="licence.txt">licence.txt</a>
|
|
|
|
|
|
<a name="II"></a>
|
|
<h3>II. NWNX plugins</h3>
|
|
|
|
<p>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
|
|
"nwnx_", e.g. "nwnx_odbc.dll" for the ODBC interface.
|
|
|
|
<p>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
|
|
"nwnx_odbc.dll" and "nwnx_llist.dll" into your NWN directory. NWNX dynamically
|
|
loads these plugins on startup, enabling the functionality contained in these
|
|
plugins.
|
|
|
|
<p>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.
|
|
|
|
<p>Starting with version 2.5.4, the plugins are available as <i>separate downloads</i>
|
|
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.
|
|
|
|
<a name="III"></a>
|
|
<h3>III. Available plugins</h3>
|
|
|
|
<p>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 <a
|
|
href="http://www.nwnx.org"> nwnx.org</a>. The plugins come complete with
|
|
documentation and a small demo module that demonstrates their usage.
|
|
|
|
<h4>A. ODBC </h4>
|
|
|
|
<p>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.
|
|
|
|
<h4>B. PROFILER </h4>
|
|
|
|
<p>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.
|
|
|
|
<h4>C. HASHSET </h4>
|
|
|
|
<p>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.
|
|
|
|
<h4>D. FUNCTIONS </h4>
|
|
|
|
<p>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.
|
|
|
|
<h4>E. TIME </h4>
|
|
|
|
<p>This plugin implements a simple, yet highly accurate timer. Perfect for
|
|
knowing how long your functions really take to execute.
|
|
|
|
|
|
<a name="IV"></a>
|
|
<h3>IV. Installing NWNX</h3>
|
|
|
|
<p>NWNX2 has been extensively tested on MS Windows 2000 and XP. Windows 9x has
|
|
also been tested and we encountered no problems with NWNX2.
|
|
|
|
<p>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.
|
|
|
|
<p>If you have a previous version of NWNX installed, remove the files
|
|
nwnx.dll and madCodeHookLib.dll.
|
|
|
|
<p><b>Now copy the NWNX plugins you want to use into the NWN directory.</b>
|
|
|
|
|
|
<a name="V"></a>
|
|
<h3>V. Running NWNX</h3>
|
|
|
|
<p>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.
|
|
|
|
<p>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.
|
|
|
|
<p>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:
|
|
|
|
<pre>
|
|
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.
|
|
</pre>
|
|
|
|
<p>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,
|
|
|
|
<h4>NWNX command line options</h4>
|
|
|
|
These options are understood by NWNX2. All other (i.e. unknown to NWNX2) options
|
|
are passed to the server. <br>
|
|
Example command line:
|
|
|
|
<pre>
|
|
C:\Neverwinter Nights\NWN\NWNX2.EXE -module "My Module" -publicserver 1 -gamespywatchdog 1
|
|
</pre>
|
|
|
|
<table border=1 cellpadding="5" width="80%">
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-processwatchdog [0|1]</td>
|
|
<td> <center>1 </td>
|
|
<td> Set to 0 to disable the process type of watchdog, 1 to enable it.</td>
|
|
<td> <nobr>-processwatchdog 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-processinterval 1..n </td>
|
|
<td> <center>5 </td>
|
|
<td> In seconds. How often the process watchdog will check if the NWNights server process is still there.</td>
|
|
<td> <nobr>-processinterval 7</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-gamespywatchdog [0|1]</td>
|
|
<td> <center>0 </td>
|
|
<td> Set to 0 to disable the gamespy type of watchdog, 1 to enable it.</td>
|
|
<td> <nobr>-gamespywatchdog 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-gamespyinterval 1..n</td>
|
|
<td> <center>20 </td>
|
|
<td> In seconds. How often the gamespy watchdog will check if the NWNights server process is still there and still responding to clients.</td>
|
|
<td> <nobr>-gamespyinterval 60</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-gamespyretries 1..n</td>
|
|
<td> <center>5 </td>
|
|
<td> 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. </td>
|
|
<td> <nobr>-gamespyretries 3</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-oldgamespyprotocol [0|1]</td>
|
|
<td> <center>0 </td>
|
|
<td> Set to 1 if you have a pre 1.32 server and make use of the gamespy watchdog.</td>
|
|
<td> <nobr>-oldgamespyprotocol 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td> <nobr>-restartdelay 1..n</td>
|
|
<td> <center>5 </td>
|
|
<td> In seconds. How long NWNX will wait before it restarts the server.</td>
|
|
<td> <nobr>-restartdelay 5</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>NWNX.INI file</h4>
|
|
|
|
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:
|
|
|
|
<pre>
|
|
ServerPort = 5121
|
|
ModuleName = "aps_demo"
|
|
WatchdogProcess = yes
|
|
UpdateIntervalProcess = 5
|
|
WatchdogGamespy = no
|
|
UpdateIntervalGamespy = 20
|
|
GamespyRetries = 5
|
|
OldGamespyProtocol = no
|
|
RestartDelay = 5
|
|
</pre>
|
|
|
|
(the values shown here are the default values).
|
|
|
|
<p>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.
|
|
|
|
<a name="VI"></a>
|
|
<h3>VI. FAQ & Troubleshooting </h3>
|
|
|
|
<p><b>Q. What is NWNX?</b><br>
|
|
|
|
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.
|
|
|
|
<p><b>Q.What are the system Requirements for NWNX?</b><br>
|
|
A. NWNX currently works with all Windows operating systems. If your system
|
|
processor can handle running Neverwinter Nights, it can more than handle NWNX.
|
|
|
|
<p><b>Q. Will there be a LINUX port?</b><br>
|
|
A. We have a version of NWNX2 for Linux available. Refer to
|
|
<a href="http://sourceforge.net/projects/apsnwnx/"> our sourceforge page</a>.
|
|
|
|
<p><b>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?</b><br>
|
|
A. If the child process crashes or becomes unresponsive to network traffic, NWNX will reboot it.
|
|
|
|
<p><b>Q. Will I still be able to start my server up with firedaemon(or any other server crash utility)?</b><br>
|
|
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.
|
|
|
|
<p><b>Q. Any chance the source code will be open sourced?</b><br>
|
|
A. Shortly after the initial release, the complete source code was released as part of the distribution of APS/NWNX2.
|
|
|
|
</body>
|
|
</html>
|