Avlis Persistence System / Neverwinter Nights Extender 2 4 Linux - Quick docs

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.

Table of Contents

I. Introduction - What does APS/NWNX do?
II. Installing NWNX
III. Installing and updating APS
IV. Setting up a database for NWNX
V. Running a module with APS/NWNX
VI. NWScript Examples

I. Introduction - What does APS/NWNX do ?

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
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 ). After compiling the package with the usual steps (./configure and make) copy the resulting binary nwnx.so and the file nwnstartup.sh into the directory where the nwserver binary resides. You will also need to create a file named nwnx.ini in this directory. The distribution contains an empty configuration file that you can fill out and copy there.

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

  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

Have a look at aps_include. The function prototypes contain descriptions that should help you to get started.

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.

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:

   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.

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"

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.
  1. Store some data in the table "aps"
       #include "aps_include"
       void main()
       {
       	string sSQL = "INSERT INTO aps (field1, field2) VALUES ('string1', integer1)";
       	SQLExecDirect(sSQL);
       }
    
  2. Retrieve the value stored in example 1
       #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 } }
  3. Work with multiple rows of data
    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
               // ...
           }
       }