This documentation is © by the Avlis Team and the APS/NWNX Linux Conversion Group
Visit us at Sourceforge project page and
http://avlis.blackdagger.com
This is the short version of the documentation.
The Avlis Persistence System (APS) is a set of scripts for NWN that offer a set of functions you can use to send SQL queries to the NWN Extender (NWNX) and conveniently process the results gathered from a database.
NWNX2 is a program that loads the NWN server and injects the database functionality into the server. Setting special string variables using NWScript triggers the database requests. The resulting data can be read with the usual string functions.
The database has been tested with Microsoft Access and MySQL so far. Conceivably, any database with a decent ODBC driver will work.
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.29 as of this writing) and thus should work with upcoming releases, too. The current version has been tested on the following Linux distributions: Debian 3.0 (woody).
We have included a demo module that illustrates how to use APS/NWNX and makes creating the database tables easy, and a second module demonstrating how persistent containers can be implemented.
Licence Now edit nwnx2.ini and nwnstartup.sh and put in relevant changes for your
local settings From your nwserver directory run nwnstartup.sh by itself or
in a while loop like the following to have it autorestart on crash
Have a look at aps_include. The function prototypes contain descriptions that should
help you to get started.
Right before NWNX2 loads the server, it rotates it's own and the server's log
files. You will find directories names "logs.0.1"..."logs.0.9" below your "logs.0" directory.
The directory "logs.0.1" always contains the newest logs, and "logs.0.9" contains the oldest
logs. The directory "logs.0" will still hold the current set of logs. All log files older
than those in "9" are deleted to preserve disk space.
All SQL 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 that:
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 with:
"./nwnx2 -module MODULENAME"
APS and NWNX are distributed unter the terms of the GNU GENERAL PUBLIC LICENSE
included in licence.txt.
II. Installing NWNX
Download the file, place it in a temporary directory and untar and unzip the
file (tar xvfz
while [ nwncheck != 1 ]
do
./nwnstartup.sh
done
III. Installing and updating APS
A. Importing the erf
Import "aps2.erf" into your module. The .erf contains two scripts: aps_onload,
which shows how your module's OnModuleLoad event should look like and aps_include, which
contains all those nice functions that make APS fun to use;
B. Updating from previous versions
IV. Setting up a database for NWNX
Create an ODBC connection to your favourite database provider and name it "nwn"
(without the quotes). Create some tables you want to use for testing.
V. Running a module with APS/NWNX 4 Linux
Go to the directory where you installed nwserver and type "./nwnx2", without the quotes.
You will see some messages printed to the terminal by NWNX2 and shortly after that the
NWN server starts.
NWN Extender V.2.0.0.0
(c) 2003 by Ingmar Stieger (Papillon)
visit us at http://avlis.blackdagger.com
* Connecting to database
* NWNX2 activated.
o Got request: SELECT item, count, identified FROM containers WHERE container='PersistentChest1'
o Sent response (17 bytes): ARS_SKILLBOOK
o Sent response (17 bytes): NW_IT_BOOK018
o Sent response (18 bytes): NW_IT_TORCH001
o Empty set
* NWNX2 shutting down.
VI. NWScript Examples
This examples show you how to use the advanced features of APS. If you just want to
store and retrieve single values then have a look at the functions described in the
long documentation and in aps_include.
#include "aps_include"
void main()
{
string sSQL = "INSERT INTO aps (field1, field2) VALUES ('string1', integer1)";
SQLExecDirect(sSQL);
}
#include "aps_include"
void main()
{
int rc;
string sSQL = "SELECT field2 FROM aps WHERE field1='string1'";
SQLExecDirect(sSQL);
rc = SQLFetch();
if (rc == SQL_SUCCESS)
{
int iValue = StringToInt(SQLGetData(1));
// do something with integer iValue
}
{
// not found in database
}
}
Assume your table "tradeskills" has the following fields: player, character, skill, xp
Now let's say you want to show the player what he skills he learned so far.
#include "aps_include"
void main()
{
string sSQL = "SELECT skill, xp FROM tradeskills WHERE player='playername' AND character='charactername'";
SQLExecDirect(sSQL);
while (SQLFetch() == SQL_SUCCESS)
{
string sSkill = SQLGetData(1);
int iXP = StringToInt(SQLGetData(2));
// Tell player what he learned using the two variables above
// ...
}
}