I. Introduction - What does APS/NWNX do?

APS is a set of scripts written for Neverwinter Nights that work with NWNX2 to produce reliable persistence in a module. At the heart of the APS is an include file that lists a number of custom made functions for governing persistence. These functions can be used as is in your module or changed to suit your needs.

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. It uses no hakpaks, and the only in-game NWN modification necessary is the addition of either the script for APS, or your own custom modified Structured Query Language (SQL) statements. Whenever a script wants to generate a SQL query, it calls our APS functions and the Extender pulls the query out of the memory of the NWN server. It then passes it to the database, and writes the result of the query back into the memory of the server. The database has been tested with Microsoft Access and MySQL so far. Conceivably, any database with a decent ODBC driver will work. Also, because of the nature of ODBC logistics, multiple servers can be linked up to one database file to produce reliable cross-server persistence. A variable can be set on one server and checked on another.

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 with 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.

NWNX2 has been extensively tested on Debian Linux 3.0 (woody).

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

1. Place the file "aps2.erf" into the C:\Neverwinternights\NWN\erf directory.
2. In the toolset, open up the module into which you wish to install the scripts.
3. Under the File Menu, click Import. A window will pop up.
4. Make sure the contents of the C:\Neverwinternights\NWN\erf directory are showing in the window
5. Select "aps2.erf" from the list
6. Click Import and ignore the message about the missing resource (click Yes).

B. Updating from previous versions

• N/A

C. Using the persistence functions

1. After installing according to the instructions above, go to Module Properties under the Edit menu.
2. Select aps_onload for your module OnModuleLoad event.
     OR
   Open aps_onload in the script editor and paste the contents of it into your pre-existing module's OnModuleLoad script. We only recommend doing this if you are familiar with NWScript.

void SQLInit()

Setup placeholders for ODBC requests and responses. This functions reserves memory APS and NWNX use for communication. Call this function once in the module load event.

SetPersistentString(object oObject, string sVarName, string sValue, int iExpiration=0, string sTable="pwdata")

This sets a persistent string on an object. The object can be any valid object in the game. The command works the same way the usual SetLocalString function works, except you can optionally add a little more information:

• object oObject - The object which you wish to set the persistent variable upon.
• string sVarName - The name of the persistent variable. Ex: "Quest Flag 1" or "QuestCompleted_True_False"
• string sValue - The string you want to store.
• int Expiration - (optional) The number of days after which the variable should expire, i.e. be deleted from the database. If you don't specify this parameter or pass 0 here, the variable will never be purged from the database.
• string sTable - (optional) You can specify in which database table the value should be stored. This parameter defaults to "pwdata".

SetPersistentInt(object oObject, string sVarName, int iValue, int iExpiration=0, string sTable="pwdata")

This sets a persistent integer value on an object. The object can be any valid object in the game. The command works the same way the usual SetLocalInt function works, except you can optionally add a little more information:

• object oObject - The object which you wish to set the persistent variable upon.
• string sVarName - The name of the persistent variable. Ex: "Quest Flag 1" or "QuestCompleted_True_False"
• int iValue - The integer value of the variable. 1, 2, 3... etc.
• int Expiration - (optional) The number of days after which the variable should expire, i.e. be deleted from the database. If you don't specify this parameter or pass 0 here, the variable will never be purged from the database.
• string sTable - (optional) You can specify in which database table the value should be stored. This parameter defaults to "pwdata".

SetPersistentFloat(object oObject, string sVarName, float fValue, int iExpiration=0, string sTable="pwdata")

This sets a persistent float value on an object. The object can be any valid object in the game. The command works the same way the usual SetLocalFloat function works, except you can optionally add a little more information:

• object oObject - The object which you wish to set the persistent variable upon.
• string sVarName - The name of the persistent variable. Ex: "Quest Flag 1" or "QuestCompleted_True_False"
• float fValue - The float value of the variable. 1.6, 2.542, 3.0989... etc.
• int Expiration - (optional) The number of days after which the variable should expire, i.e. be deleted from the database. If you don't specify this parameter or pass 0 here, the variable will never be purged from the database.
• string sTable - (optional) You can specify in which database table the value should be stored. This parameter defaults to "pwdata".

SetPersistentLocation(object oObject, string sVarName, location lLocation, int iExpiration=0, string sTable="pwdata")

This sets a persistent location on an object. The object can be any valid object in the game. The command works the same way the usual SetLocalLocation function works, except you can optionally add a little more information:

• object oObject - The object which you wish to set the persistent variable upon.
• string sVarName - The name of the persistent variable. Ex: "Quest Flag 1" or "QuestCompleted_True_False"
• location lLocation - The location you want to store.
• int Expiration - (optional) The number of days after which the variable should expire, i.e. be deleted from the database. If you don't specify this parameter or pass 0 here, the variable will never be purged from the database.
• string sTable - (optional) You can specify in which database table the value should be stored. This parameter defaults to "pwdata".

SetPersistentVector(object oObject, string sVarName, vector vVector, int iExpiration=0, string sTable="pwdata")

This sets a persistent vector on an object. The object can be any valid object in the game. The command works the same way the usual Set local variable functions work, except you can optionally add a little more information:

• object oObject - The object which you wish to set the persistent variable upon.
• string sVarName - The name of the persistent variable. Ex: "Quest Flag 1" or "QuestCompleted_True_False"
• vector vVector - The vector you want to store.
• int Expiration - (optional) The number of days after which the variable should expire, i.e. be deleted from the database. If you don't specify this parameter or pass 0 here, the variable will never be purged from the database.
• string sTable - (optional) You can specify in which database table the value should be stored. This parameter defaults to "pwdata".

GetPersistentString(object oObject, string sVarName, string sTable="pwdata")

This function works in the same manner as GetLocalString. It gets the persistent string from object oObject.

• object oObject - This is the object from which you are retrieving the value of the variable.
• string sVarName - This is the name of the variable that will be retrieved off of oObject. Ex: "Quest Flag 1"
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

GetPersistentInt(object oObject, string sVarName, string sTable="pwdata")

This function works in the same manner as GetLocalInt. It gets the persistent integer value from object oObject.

• object oObject - This is the object from which you are retrieving the value of the variable.
• string sVarName - This is the name of the variable that will be retrieved off of oObject. Ex: "Quest Flag 1"
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

GetPersistentFloat(object oObject, string sVarName, string sTable="pwdata")

This function works in the same manner as GetLocalFloat. It gets the persistent float value from object oObject.

• object oObject - This is the object from which you are retrieving the value of the variable.
• string sVarName - This is the name of the variable that will be retrieved off of oObject. Ex: "Quest Flag 1"
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

GetPersistentLocation(object oObject, string sVarName, string sTable="pwdata")

This function works in the same manner as GetLocalLocation. It gets the persistent location value from object oObject.

• object oObject - This is the object from which you are retrieving the value of the variable.
• string sVarName - This is the name of the variable that will be retrieved off of oObject. Ex: "Quest Flag 1"
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

GetPersistentVector(object oObject, string sVarName, string sTable="pwdata")

This function works in the same manner as the other get local variable functions. It gets the persistent vector value from object oObject.

• object oObject - This is the object from which you are retrieving the value of the variable.
• string sVarName - This is the name of the variable that will be retrieved off of oObject. Ex: "Quest Flag 1"
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

void DeletePersistentVariable(object oObject, string sVarName, string sTable="pwdata")

This function deletes a variable from the database.

• object oObject - This is the object on which the variable has been stored.
• string sVarName - This is the name of the variable that will be deleted.
• string sTable - (optional) You can specify in which database table the value can be found. This parameter defaults to "pwdata".

void SQLExecDirect(string sSQL)

Executes a SQL statement. If the statement returns a result set, you can read the data with the next two functions.

int SQLFetch()

Position cursor on next row of the resultset. Call this function before using SQLGetData().
Returns

• SQL_SUCCESS if there is a row
• SQL_ERROR if there are no more rows

int SQLFirstRow() (*deprecated*)

Function is deprecated but still there for backward compability. Simply calls SQLFetch().

int SQLNextRow() (*deprecated*)

Function is deprecated but still there for backward compability. Simply calls SQLFetch().

string SQLGetData(int iCol)

Return value of column iCol in the current row of result set sResultSetName.

Comments

• Make sure you include aps_include in every script where you want to use these functions, i.e. add the line

      #include "aps_include"
  

  at the top of your script.

IV. Setting up a database for NWNX

A. For Access

1. Create an ODBC connection
   NWNX tries to connect to a so called ODBC DSN with the name "nwn" on startup. Here is how to create this connection: Go to Windows control panel, choose Administrative Tools, choose Data Sources (ODBC). In the window that pops up, go to the second tab (System DSN) and click "Add". Choose "Microsoft Access Driver (*.mdb)" from the list and hit "Finish".

   A new window "ODBC Microsoft Access Setup" will appear where you have to make some settings. The data source name has to be "nwn" (without the quotes). The description can contain any text you like. Next, select "Create..." and browse to the location where you want your new database to be stored. Type in a name (e.g. nwn.mdb) and hit OK. The new database has now been created and all settings have been made. Click OK again to close the "ODBC Microsoft Access Setup" window.

2. Database format
   You now have an empty database. In order to store data in it, you have to create some tables in the database. The included module "aps_demo.mod" makes this easy.

   Start NWNX/APS according to the instructions in Section V.1 (see below) and load "aps_demo" in the server. Next connect to your server with the Neverwinter Nights client. You will see several different signs in front of you (from left-to-right): Create Tables, Store variable in database, and Load variable from database. Each sign performs an action when you click on it:

   • Create tables: Issues a database command that creates tables in an MS Access database
   • Store variable in database: Tries to save a test variable named "demoName" with the value "testValue" in the database
   • Load variable from database: Tries to retrieve the variable "demoName" from the database and prints the results in the server message window.

   Now click every sign once, starting with the one on the left (Create Tables).

   If the last sign sends you the message "Retrieved variable from database: testValue" your setup is ok and you're ready to start using APS. Note: This is the most basic setup. We encourage you to use more sophisticated databases and data structures if you feel confident to do so (see below).

B. For other databases

As there is an almost unlimited amount of different databases out there, we can't give detailed instructions for all of them. If you want to use a database server like MySQL or MSSQL, try to follow the steps described above accordingly:

    SQLExecDirect("CREATE TABLE pwdata (" +
        "player varchar(64) default NULL," +
        "tag varchar(64) default NULL," +
        "name varchar(64) default NULL," +
        "val text," +
        "expire int(11) default NULL," +
        "last timestamp(14) NOT NULL," +
        "KEY idx (player,tag,name)" +
        ")" );