NWN-MySQL

APS/NWNX 1 introduced a great idea to interface a real database with NWN, and successfully implement that idea. I would never have such idea to do it, and Papillon has all my respect for that.
APS/NWNX 2 somewhat increased reliability. APS/NWNX 2 is quite easy to use, pretty reliable (but still doesn't really allow to run a server for a long period with no human intervention), but, clearly, it lacks performance optimizations.
NWN-FF is completely designed to focus on: 1/ performance 2/ server stability 3/ added functionalities. This package is specially designed to handle large Windows PW servers, which need to have very efficient access to persistent data.

With the version 4, I've decided to rename the complete package into NWN-FF, to avoid the confusion with NWN-MySQL that is just one of the components. NWN-FF 4.0 currently includes 14 different projects plus an erf importation file and a demo module.

It is very easy now, with version 4.0.3, to start using NWN-FF with a MySQL database. You can download it for free at: www.mysql.com.

NWN-FF also comes with support for those using no database (or Bioware Database) or even No DLL at all (just the monitoring tool alone to keep NWServer.exe alive).

There are 5 kinds of items in NWN-FF:
the monitoring tool - NWN-MySQL.exe, NWN-NoDB.exe or NWN-NoDLL.exe - it is used to launch the NWServer.exe, restart it when needed, and tie NWServer.exe with the proper dll. This is roughly equivalent to NWNX2.exe, except it runs in a console window and has much more possibilities. More details here.
the main dll - NWN-MySQL.dll or NWN-NoDB.dll - it provides the following functions: makes the interface with the DataBase (except NWN-NoDB.dll), loads all nwnx plugins, includes a profiler, and also gives some specific functions.
the plugins dll - you can extend NWN-FF possibilities by using all APS/NWNX plugins, except nwnx_odbc.dll and nwnx_profiler.dll (because those two are allready included in the main dll). Also don't use NWNx-FFSpeech.dll with UdpDump.exe (Talus Speech System).
Other tools - a small collection of tools, that are more or less directly related to NWN-MySQL.
Erf file - this is what you need to import into you module to use all the power of FF-NWN ;)

Database	Monitoring tool	Main dll	APS/NWNX PlugIn	Other tools	Erf file
MySQL	NWN-MySQL.exe (NWN-NoDB.exe) (NWN-NoDLL.exe)	NWN-MySQL.dll (NWN-NoDB.dll)	NWNx_MySQLSpeech.dll NWNx_FFSpeech.dll supports all the NWNX Plugins except nwnx_profiler.dll & nwnx_ODBC.dll	BinTracer.exe StoreItem.exe	NWN-FF.erf
No Database	NWN-NoDB.exe (NWN-NoDLL.exe)	NWN-NoDB.dll	NWNx_FFSpeech.dll supports all the NWNX Plugins except nwnx_profiler.dll	BinTracer.exe	(NWN-FF.erf) Only a limited part can be used without any external Database. Make sure you have USE_EXTERNAL_DATABASE=0 in FF_include.nss
No DLL	NWN-NoDLL.exe	-	-	BinTracer.exe	-
MySQL and Unix	(Get APS/NWNX2 Unix version 5.1+)	(Get APS/NWNX2 Unix version 5.1+)	(Get APS/NWNX2 Unix version 5.1+)	-	NWN-FF.erf (some limitations as APS/NWNX2 Linux version 5.1+ do not support all NWN-FF instructions. Please check here)

Installation and configuration

If you have no real Database yet

I assume then that you'll be directly using MySQL. NWN-FF does not support the other databases anymore.

1/ You first need to install MySQL 4.1 database (you can download it for free on their website: http://dev.mysql.com/downloads/mysql/4.1.html). It's currently version 4.1.11, but it should be fine with any 4.0.X version of MySQL.

You may also want to download and install MySQL Control Center, it's a GUI that will simplify your task if you're not familiar with MySQL. You can grap it for free here: http://dev.mysql.com/downloads/mysqlcc.html. Or you may prefer MySQL Administrator http://www.mysql.com/products/administrator/ and MySQL Query Browser http://www.mysql.com/products/query-browser/ instead.

Make sure MySQL server is running before you're launching NWN-MySQL.exe. Check here if you don’t know how to do that.

2/ You don’t need to create a database or any table in MySQL: NWN-FF will do that automatically for you (at least in the case of a MySQL database)

3/ You may first try the demo module: NWN-FF.mod. So you'll make sure that all is running well before changing your own module.

If you are switching from APS/NWNx

If you’re already using APS/NWNX on Windows, then it’s very easy to upgrade your server with NWN-FF.

You can keep your database and your module unchanged. No need to even recompile it to start with NWN-FF.

Let’s start

4/ Uncompress all the NWN-FF package in a directory (you have probably allready done that as you're reading this), then select you components you're going to need from bin\ sub-directory. If you're not sure, you can start with just bin\NWN-MySQL.exe, bin\NWN-MySQL.dll, bin\libmySQL.dll and bin\madCodeHookLib.dll: copy those 4 files into your Neverwinter Nights directory (where you start NWServer.exe from). Also copy the demo module (NWN-FF.mod) into your modules\ subdirectory.

5/ Then you need to create and edit the configuration file as needed (see below). The default configuration file is NWN-FF.ini. If no configuration file exists, a new one will be automatically created with default values. This default configuration file should be fine to start with; it will ask the monitoring tool to start the demo module NWN-FF.mod.

6/ Launch NWN-MySQL.exe

Note: The monitoring tools provided with NWN-FF (all 4 versions) use advanced process monitoring functions that are only provided on Windows NT 4, 2000, XP or 2003. So they won’t probably run on Win95, Win98 or Me. If you’re using those OS, then you have to use NWNX2.exe from APS/NWNX2 package, but still can use all other parts from NWN-FF (included all main dlls and plugins). In this case, simply rename the main dll you want to use into nwnx.dll so NWNX2 will use it.

Add speech support

Thanks to Lanthar, NWN-FF comes with great speech processing functionnalities. In order to get this running, you just need to do the following:

1/ Run WinPcap_3_1.exe from the "Third Part Install\" directory. This will install the IP interception driver that is used by NWNx-FFSpeech.dll.

2/ Copy NWNx-FFSpeech.dll from the bin\ directory to NWN main directory (same directory as NWN-MySQL.exe and NWServer.exe).

3/ Launch the NWserver using NWN-MySQL.exe again

4/ Login as a player on your server from a distant PC using the Internet (it won't work if you run client and server on the same PC)

5/ Just say *Help* to check if it works. If it does, you should have a list of available commands you can type.

If it doesn't work, check the configuration file and NWNx-FFSpeech section to check what may be wrong.

Adaptation of your own module in order to use NWN-FF

Before starting: If you're using APS/NWNx with an adapted version of APS-include.nss, then you'll need to backup this old file (rename it into something else before importing the NWN-FF erf file), manually edit the new aps-include file to add all your specific content.

Also, it is strongly advised to backup your module before doing importing any erf file.

Import NWN-FF.erf

Overwrite all your existing files, including aps_include.nss.

Ignore all errors about missing .ncs files

After the importation, save your module, reload it.

Edit your module and areas events

A/ First step (fast start)

1/ Edit your module events (Edit/Module properties/Events)

Note: if you have existing scripts on those events and want to be able to easily upgrade with next versions of NWN-FF, it is suggested to call ff_on_XXX script with ExecuteScript from your existing event script. Check here.

a. OnModuleLoad : ff_on_mod_load (you may need to add )

b. (only needed if you want to use speech processing with NWNx_FFSpeech.dll) OnHeartbeat : ff_on_heartbeat

c. OnClientEnter : ff_on_cl_enter (you may need to adapt the script to fit your needs)

d. OnClientLeave : ff_on_cl_leave

e. OnActivateItem : ff_on_activate (or add its content into your existing script)

2/ Edit the first part of FF_include script to fit your needs

3/ Then make a complete rebuild of your module and save.

4/ You can then try you module

(don't forget to change NWN-FF configuration file Module= parameter to load the proper module)

B/ Second step

1/ Edit each area OnEnter Event

It's advised to put, for each of your areas OnEnter event: OnEnter: ff_onenterarea

2/ Adapt some module event scripts

It's also strongly advised to edit your module OnPlayerRest, OnPlayerDeath and OnPlayerRespawn module events,

a. add #include "ff_include"

b. use ff_FlushData(oPC) in it (oPC need to be properly initialized with the proper value).

(you can check ff_oO_death, ff_oO_respawn and ff_playerrest scripts in NWN-FF demo module to see an example)

3/ Use all the NWN-FF instructions where needed in your module

You just have to add #include "ff_include" at the 1st line of your script, to be able to use the complete set of NWN-FF instruction

4/ Adapt the speech processing part to fit your needs

You can add or remove supported actions by editing the script ff_modhb_inc.nss

Configuration file

Each component within NWN-FF is configured via the same configuration file. You can simple edit this with any text editor (like Notepad). If you start a component with a configuration file that is missing or incomplete, then defaults values will apply for all missing fields, and the complete configuration file will be regenerated.

By default, the configuration file is NWN-FF.ini. You can explicitly provide another configuration file for the 4 monitoring tools, on the command line. But all the dlls and the other tools will always use the default configuration file.

When you want to use another configuration file, be sure to provide a complete name including the path (absolute or relative). Otherwise it will be searched into the Windows directory.

NWN-MySQL .\debug.ini

Here is a sample of the configuration file (please note that all lines starting with a semi-column are comments and will be ignored):

;***********************************************

;* File NWN-FF.INI - the configuration file of NWN-FF *

;***********************************************

;******************************************************************************************************

; Parameters in the Global section apply to several NWN-FF components

;******************************************************************************************************

[Global]

; This parameter tells NWN-FF where to put all log files. This subdirectory will be created if needed. No trailing \ needed

; You can use some date/time parameters in the name (%y for year, %m for the month, %d for the day).

; Parameters are the same as in strftime C instruction, so you can check C documentation

LogDirectory=.\\logs\\%y_%m_%d

; If you set this to 1, the monitoring tool and NWServer won’t be visible at all on your PC.

HideAllWindows=0

;******************************************************************************************************

; Options specific to the monitoring tool

; (NWN-MySQL.exe, NWN-NoDB.exe or NWN-NoDLL.exe)

; NWN Server configuration

;******************************************************************************************************

[NWNServer]

;StartDir gives the directory where NWNServer.exe can be found (default: current directory)

StartDir=C:\Jeux\NWN

;If for some reason your NWN Server application has a different name, then you can put it here (without the .exe extension).

;Default is NWServer. (It may be used for instance when you're running 2 servers on the same computer, to avoid that NWN-FF attaches on the wrong one)

NWServerExeName=NWServer

;Module gives the name of the module to load

Module=NWN-FF

;Default difficulty level

Difficulty=3

;Level range accepted on the server

MinLevel=1

MaxLevel=20

;Max number of players allowed to connect on the server

MaxClient=64

;IP of the server (used so that NWN-MySQL.exe can monitor it, using Gamespy protocol) ;** Note: In most cases, the default value 127.0.0.1 works fine. You should change this ONLY if 127.0.0.1 doesn't work **

IP=127.0.0.1

;NWNServer.exe port used

Port=5121

;Player auto-save enabled? It’s suggested to disable this and better handle saves inside your module (as shown in NWN-FF.mod)

Autosave=0

;** Note: changing Priority setting has most chance to make lag much WORST. **

; For instance, if you increase Priority of NWServer when it allready use over 50% of your CPU, then MySQL will run much slower as a result.

; And if you put a lower Priority, then any other application running on your PC will be served first.

;Set here the priority of NWN Server. Beware: only use this if you really know what you’re doing, it may very well crash your computer or make NWN Server stop running at all.

;Keeps the default 0 value if you’re not sure.

; -2 = IDLE_PRIORITY_CLASS Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.

; -1 = BELOW_NORMAL_PRIORITY_CLASS Windows 2000/XP: Indicates a process that has priority higher than IDLE_PRIORITY_CLASS but lower than NORMAL_PRIORITY_CLASS.

; 0 = NORMAL_PRIORITY_CLASS Indicates a normal process with no special scheduling needs (default value)

; 1 = ABOVE_NORMAL_PRIORITY_CLASS Windows 2000/XP: Indicates a process that has priority higher than NORMAL_PRIORITY_CLASS but lower than HIGH_PRIORITY_CLASS.

; 2 = HIGH_PRIORITY_CLASS Indicates a process that performs time-critical tasks. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the system. Use extreme care when using the high-priority class, because a CPU-bound application with a high-priority class can use nearly all available cycles.

; 3 = REALTIME_PRIORITY_CLASS: Specified for a process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.

Priority=0

;Can store any additional parameter that you want to put on the NWServer.exe command line. Please only use it for the parameters that are not already explicitly in the NWN-FF configuration file.

;(check this link for the description of NWServer.exe command line: http://nwn.bioware.com/builders/winserver3.html )

OtherServerParam= –elc 1 –ilr 0

; This is the name of your server, as shown in GameSpy

ServerName=NWN-FF Server

;NWN-FF monitoring tools optionally stores some binary data for performance/usage tracking of the server.

;BinTracer, a tool now provided with NWN-FF V4 and up, can graphically display the content of those files.

;Is you want those files to be written, put 1 here. 0 (default) otherwise.

StoreBinaryData=1

;How often does NWN-FF check NWServer status/performance. Default is 20 (seconds). If you server fails to start within 1 minute, you should increase this value to prevent NWN-FF to stop and restart it.

;On the other side, an higher value means that NWN-FF will need more time to react when the server crashes.

TimeSlice=20

;Says how often the server will restart (note: TimeSlice has also an effect on this). Default is 30000

;A smaller value means the server will be restarted more often

MaxCounter=30000

;If 1, will try to handle Server restarts at best, taking into account how many player are connected, the lag level (CPU used) and other parameters.

;If it’s 0, the server will only be restarted when hanged or when time (TimeSlice * MaxCounter seconds) elapsed.

WithAdvancedHeuristics=1

;You can disable all computing done by NWN-MySQL.exe done on nwserverLog1.txt files. (default is 1)

; if LogProcessing = 0, then no all_logs.txt file will be created and nwserverLog1.txt log files won't be deleted.

LogProcessing=1

;If using a Database (that is, NWN-MySQL.exe), you may want to change those SQL request used to calculate the number of players and the number of DM connected (those default settings work fine with NWN-FF demo module or when you properly import and use NWN_FF.erf)
SQL_PlayerCount=SELECT COUNT(*) FROM idplayer WHERE Actif=1

SQL_DMCount=SELECT COUNT(*) FROM idplayer WHERE Actif=1 AND DM=1

;Here comes the name of the main dll that will be used. If you need to use APS/NWNx dll, put nwnx.dll here.
;You may also mix different kind of NWN-FF component, like for example the NWN-NoDB monitoring tool with a NWN-MySQL.dll. Default value is OK most of the time.

DllName=NWN-MySQL.dll

; This value is the delay the monitoring tool should wait (in seconds) to let the server and module initialize properly. Normal monitoring restarts after this delay each time NWServer restarts.

; Default value is 60, minimum is 30, maximum is 3600 (1 hour).

; Note that no monitoring at all is done during this initial period of time

InitialDelayS=60

; Says if you want to use active exchanges between the module and the monitoring tool, or don’t need that.

; If you have turned WithAdvancedHeuristics off because your server restarted when low activity on it in NWN-FF prior to 4.11, then you should turn it on again and keep this option on.

; if this value is 1 and the server restarts from time to time with no reason, then make sure that your module uses at least one SetLocalString NWNScript instruction from time to time (either NWN-FF instruction, like DB access, speech processing or whatever, or any other SetLocalString usage outside NWN-FF). You may for instance put this simple script on your Module HB script (as shown in ff_on_heartbeart.nss):

; void main() { SetLocalString(GetModule(), "NWNX!VERSION”, “xxxxxxxx”); }

; default value is 1

bModuleFeedBack=1

;******************************************************************************************************

; Configuration section of the profiler

;******************************************************************************************************

[Profiler]

; 0 to disable the profiler. 1 to enable it.

; Please note that the impact on global performance is very limited, so you can keep it ON all the time.

UseProfiler=1

; 0 to only use the synthetic .csv result file. 1 to write the detailed text file either.

WriteDetailedTextFile=1

; CSV separator used by Excel depends on the local settings of your computer. Usually, it’s "," in English-speaking countries.

; It’s ";" in France. It may be something else in other places. It also depends somewhat on the exact version of Excel you’re using

CSV_Field_Separator=","

;*******************************************************************************************************

; Options specific to MySQL: used by all NWN-FF component using direct MySQL support

;*******************************************************************************************************

[MySQL]

; Put Debug=0 to have only critical errors logged. Debug=1 will log all warnings. Debug=2 provides very detailed log file (all requests are dumped). Beware, as those detailed log file will significantly reduce performances.

Debug=0

;Name of the server hosting the MySQL database (provide here an IP or keep the default 'localhost' if MySQL is running on the same PC)

host=localhost

;Keep port=0 as default, except if you really need to change it

port=0

;Name of the user in MySQL (has to be properly configured in MySQL, root is the default)

user=nwnuser

;Password for that user (default = no password)

password=

;Name of the database used with nwn (nwn is the default)

database=nwn

;*******************************************************************************************************

; Options specific to the speech processing tools

;*******************************************************************************************************

[FFSpeech]
; Put Debug=0 for only critical errors, Debug=1 to get detailed information on FFSpeech initialization and NIC selection, Debug=2 for detailed log file (all what is said on any channel will be stored in the log file). And Debug=3 will log all packet processed. Beware, as those detailed log file will significantly reduce performances. Debug=0 removes most logs, only serious errors will be shown.

Debug=1

; If you have several network interfaces on your server, you need to provide here the range of the interface to be used. If you’re unsure, remove this line and run Speech-MySQL.exe. It will display you the list of the interfaces available on your server with the number to be used for each.
NetworkInterface=0

; Experimental option. Better keep 1 here for better performances.
FilterserverIP=1

; This parameter is an alternative to NetworkInterface parameter, very useful if you have several NIC and don’t know which to use.
; If this parameter is a valid IP and one of the NIC has this IP as a first address, then this NIC will be automatically selected, no matter
; the value of NetworkInterface parameter
NIC_IP=0.0.0.0

The monitoring tool

nwn-MySQL.exe / nwn-NoDB.exe / nwn-NoDLL.exe

Basically, all 4 monitoring tools keeps the main APS/NWNX 2.0.3 functionalities (mainly to link nwnx.dll with NWServer.exe), with those additions:

1. Improved monitoring of NWN Server. Many different rules have been established to assure that NWN Server is running fine. It has been specially designed for largest PW with lot of players.

1. makes sure that NWN Server process is running properly

2. check that the Server is accessible via Internet, using GameSpy protocol

3. assure that total cumulative load of the server is acceptable. Reload the Server if cumulative load over long period of time is too high (to prevent excessive lag on the Server)

4. and some other heuristic rules that helps keeping Server is the best possible shape, reloading only when really necessary (usually every 2h on heavily loaded server, avg players in 60-64 range. Around every 10 hours if only around 10 players connected).

2. Improved crash recovery system

1. when the server crashes or need to be reloaded, always try first to stop it cleanly (giving a chance to save properly character files), and then try successively higher stressing methods, making sure nothing is preventing the server from stopping. Same apply when trying to start it.

3. Detailed and centralized Log files, showing CPU usage, number of players, exceptional events (crashes...) and precise reason of each reload.

4. Performance are also logged in binary format, with CPU usage, Memory, Number of players..., to be displayed graphically with BinTracer.exe.

5. Those executable can be used with APS/NWNX2 nwnx.dll file, for those that for some reason only want improved monitoring and logs, but don't want optimised main dll provided with NWN-FF.

6. All needed parameters for the complete NWN-FF package are in a single configuration file: nwn-FF.ini (check Configuration file for more information).

7. A global clean log file all_logs.txt (in NWN main directory) is generated from all logs.0\nwserverLog1.txt files written by nwnserver.exe. All unwanted lines (mainly Bioware Debug strings) are stripped during this process, to keep this global log file smaller.

8. There is only one parameter on the command line, and it is optional: it’s the name of the configuration file to be used. Exemple:

Nwn-MySQL .\AltServer.ini

Note: you should either provide a full path to the configuration file (either relative or absolute), or it will be searched into Windows directory. By default, the configuration file is .\nwn-ff.ini.

The main DLL

nwn-MySQL.dll / nwn-NoDB.dll

Basically, NWN-MySQL dll retains all functionalities of APS/NWNX 2.0.3, with those additions:

1. Initialization changed, simplified. Log simplified, clarified. A log file with complete untruncated error messages (inc. date and time info)

2. A second log file (Timing.txt) provides precise statistic information of usage of NWNX and MySQL (number of transactions of each kind, elapsed time in the process, % CPU used within NWNX and MySQL...).

3. (note: those two unique log files are in the starting folder)

4. There are two versions of the main dll: one is optimised for MySQL. As it uses directly MySQL API, it is very fast but only works with MySQL database. The second provides the same features except the Database support.

5. Five new instructions provided, to add features and improve performance even more (but you have to explicitly use those new instructions into your module if you want to take advantage of them). You can either directly use those though correct calls to SetLocalString, or use the set of functions provided in aps_include2.nss.

NWNX!ODBC!EXEC_AND_FETCH

It is the exact equivalent of a NWNX!ODBC!EXEC followed by a NWNX!ODBC!FETCH. It will be somewhat faster than successive calls of those two former functions.

Example of use:

string SQLExecAndFetchSingle(string sSQL) // FASTEST possible function, but can only be used if: result size is smaller than the request

// AND ONLY ONE VALUE RETURNED

{

SetLocalString(GetModule(), "NWNX!ODBC!EXEC_AND_FETCH", sSQL);

return GetLocalString(GetModule(), "NWNX!ODBC!EXEC_AND_FETCH");

}

NWNX!ODBC!DEBUG
This instruction will allow you to change the debug level of nwn-MySQL.dll or nwn-ODBC.dll from the scripts. It may be useful for instance when you want to get full debug information for only some specific parts of your script. A value of 0 will put the old value back ([MySQL] Debug).
Example of use:

SetLocalString(GetModule(), "NWNX!ODBC!DEBUG", “2”); // Full debug info

MySuspectCode();

SetLocalString(GetModule(), "NWNX!ODBC!DEBUG", “0”); // Back to default value

NWNX!RLDATE

Returns the number of micro-second since the DLL is loaded. It can be used to very precisely benchmark any NWN Script.

Example of use:

string SQLGetRLDate() // Returns the number of second since January 1st 2001 (in RL world)

{

SetLocalString(GetModule(), "NWNX!RLDATE", "000000000000000000000000000000000");

return GetLocalString(GetModule(), "NWNX!RLDATE");

}

NWNX!VERSION

Returns a 8 chars string with the version number of NWN-MySQL (empty string if running APS/NWNX).

Example of use:

string SQLGetVersion() // Returns version string for NWN-MySQL

{

SetLocalString(GetModule(), "NWNX!VERSION", "APS/NWNX");

return GetLocalString(GetModule(), "NWNX!VERSION");

}

NWNX!RUN

With this function, you can run any external executable from your NWN scripts.

Example of use:

SetLocalString(GetModule(), "NWNX!RUN", "command.com /c del c:\\fic.txt");

if (GetLocalString(GetModule(), "NWNX!RUN")=="") // Error!

{

// Error processing

}

NWNX!TIMER

Returns the number of micro-second since the NWNServer.exe is started. It can be used to very precisely benchmark any NWN Scripts.

Example of use:

int SQLGetTime() // Gives the number of micro-seconds since NWServer started

{

SetLocalString(GetModule(), "NWNX!TIMER", "000000000000");

return StringToInt(GetLocalString(GetModule(), "NWNX!TIMER"));

}

NWNX!DMREBOOT

This will ask the monitoring tool to restart the server.

Example of use:

int Reboot() // Gives the number of micro-seconds since NWServer started

{

SetLocalString(GetModule(), "NWNX!DMREBOOT", GetName(OBJECT_SELF));

}

NWNX!DLL

Will tell you if a specific library (NWN-FF plugin) is properly loaded.

Example of use:

int IsSpeechAvailable() // returns 1 if NWNx-FFSpeech if currently loaded and running, 0 otherwise

{

SetLocalString(GetModule(), "NWNX!DLL", “FFSPEECH”);

Return StringToInt(GetLocalString(GetModule(), "NWNX!DLL"));

}

NOTE: This dll will also work with existing modules using NWNX2.exe with no change. EXEC_AND_FETCH should be used to improve performances a little bit, but it's not mandatory (EXEC and FETCH are still available separately). BUT this dll is mandatory to use most of the NWN-FF functionalities provided in NWN-FF.erf

NWNx_FFSpeech.dll

This plugin can be used with any NWN-FF 4.0 main dll, but also on an existing APS/NWNx server because it is a compatible plug-in. It will provide you easy and very efficient Speech processing instruction on your module. It doesn't need any Database.

You also need to install the proper driver

This dll supports the following set of instructions. Please check the demo module or the NWN_FF.erf import file for an example of use (check ff_modhb_inc script).

NWNX!FFSPEECH!HASSPEECH

This will say if some Speech data is available for processing. It returns “0” if no data is waiting. “1” if some data is waiting (see the example below)

NWNX!FFSPEECH!GETSPEECH

This is used to actually retrieve the Speech data. So it’s the most important instruction to be used. All speech data is kept in a buffer until they are retrieved with this function. Up to 65535 bytes of speech data can be kept in the NWNx_FFSpeech buffer (when this buffer is full, then new speech data is ignored). You should use a buffer big enough to hold the data for this instruction, otherwise it will be truncated. A good idea is to reuse the big buffer already defined within aps_include (as in the example below). It’s convenient to put the result in the predefined LOCAL_BUFFER string global variable. This will allow you to use very efficient SQLLocalEatData() NWN-FF instructions to extract informations from the resulting buffer (as in the example below).

Example:

SetLocalString(oSpeech, "NWNX!FFSPEECH!HASSPEECH", "0");
if (GetLocalString(oSpeech, "NWNX!FFSPEECH!HASSPEECH")!="0")
   {
   string sBuf = GetLocalString(GetNWNMySQLWP(), "NWNX!ODBC!SPACER");
   SetLocalString(oSpeech, "NWNX!FFSPEECH!GETSPEECH", sBuf);
   LOCAL_BUFFER = GetLocalString(oSpeech, "NWNX!FFSPEECH!GETSPEECH");

   while (GetStringLength(LOCAL_BUFFER)>2)
      {
      string sName = SQLLocalEatData(); // Not really SQL data, but the string has the same format
      string sSpeech = SQLLocalEatData(); // Not really SQL data, but the string has the same format

   …. (do your processing here)
       }
   }

NWNX!FFSPEECH!VERSION

This will return the current version of NWNx_FFSpeech. number It is the exact equivalent of a NWNX!ODBC!EXEC followed by a NWNX!ODBC!FETCH. It will be somewhat faster than successive calls of those two former functions. It can also be used to check if the plugin is properly running.

Example:

SetLocalString(GetModule(), "NWNX!FFSPEECH!VERSION", "xxxxxxxxxxxxxxxxxxxxxxxx");

string sVersion = GetLocalString(GetModule(), "NWNX!FFSPEECH!VERSION");

if (sVersion=="xxxxxxxxxxxxxxxxxxxxxxxx")

WriteTimestampedLogEntry("NWNx_FFSpeech.dll NOT LOADED!!");

else

WriteTimestampedLogEntry("NWNx_FFSpeech.dll version "+sVersion+" LOADED!!");

NWNX!FFSPEECH!FILTER

To make speech processing as fast as possible, you can ask NWNx-FFSpeech.dll that you only want to receive the strings that are enclosed with a given character.
For instance, in the demo module and is it comes in the NWN-FF.erf, all commands need to be enclosed with stars ‘*’. So it’s of no need to keep all other texts, and they can be ignored.

SetLocalString(GetModule(), "NWNX!FFSPEECH!FILTER", "*");

Then, if some says for instance “Nice to meet you *bows*”, then only the string enclosed with * will be kept, that is just “*bows*”. If you have several part enclosed by starts, then all will be stored as if the PC would have said each of them separately:

“Nice to meet you! *bows* *waits* Let’s go now *follows*”
Will do as if the PC just said *bows* then *waits* and then *follows*. This makes string processing in NWScript much simpler.

If you want to remove any filtering, so that all what is said will be available for the NWNscripts, then simply use an empty string as a filter:

SetLocalString(GetModule(), "NWNX!FFSPEECH!FILTER", "");

NWNX!FFSPEECH!DEADCANSPEAK

If you’re using some filter, then when the sentence said by a PC do not include anything to be kept (For instance, if filter is ‘*’, and someone says “Hello, how goes today?”), then NWNx-FFSpeech.dll may simply ignore that sentence and do not report anything to the module. But in some cases it may be convenient to always know when a PC says something, no matter what exactly is said. For instance, you may want to track PC activities, and for this matter just get the information: he’s not afk. Or, on FastFrench, dead PC are not allowed to speak. So when a PC says something (no matter if it’s filtered or not), I need to be able to detect it.

Note that this instruction is needed in order to use NWN_FF.erf. That's the reason you can't use most parts of NWN_FF.erf without using a NWN-FF dll.

ff_include.nss

Introduction

In APS/NWNX, the file aps_include.nss needs to be included in all scripts using APS/NWNX. It provides the set of functions that is needed for database accesses. For compatibility reasons, NWN-FF provides the same file, but with some optimizations.

To get the full set of functions of NWN-FF, you need to include FF-include.nss in all your scripts, instead of aps_include (you don't need to include both).

You need to use NWN-FF version of aps_include.nss file (so overwrite your old version), or won't be able to use any part of NWN-FF specific features.

-> If you’re not already using APS/NWNX2, then you can directly use the files included in one of the Starter sub-directories (they already contain an aps_include.nss file compatible with APS/NWNX – except the version included in Starter\Expert subdirectory that has only optimised functions ): C) aps_include.nss

For those already using APS/NWNX2, it is suggested that you simply include aps_include2.nss in your aps_include.nss script:

From the script editor of the Aurora toolset, either A) copy/past content of aps_include2.nss in your existing aps_include.nss file, or B1) create a new script file called aps_include2.nss in Aurora script editor, B2) copy/past content of aps_include2.nss in it and B3) add the following line at the beginning of your existing aps_include.nss:

#include “aps_include2”

If you don’t feel at ease with scripting or don’t have at least some basic knowledge in SQL, then better leave those advanced optimizations away. You don’t have to include this file and use those new functions to take advantage of NWN-FF: you can keep your module absolutely unchanged.

But if you really want to go ahead in the optimization process, then you need it, and have to use those functions properly. In order to get the best possible optimization of you module, I strongly suggest NOT to use the default aps_include set of function at all, specially the last part (SetPersistentXXX/GetPersistentXXX). Those are easy to use because they simulate Bioware Get/Setlocal functions, but they are really slow.

If you really can’t completely get ride of those SetPersistentXXX/GetPersistentXXX functions, then you can still get some improvement if you just replace SetPersistentString/GetPersistentString by the optimized version here: MySQL\update_aps_include.txt

List of functions provided

aps_include

This set of functions is of the 1^st generation and mainly provided for compatibility with APS/NWNX 2. Those functions as provided with NWN-FF are, for most of them, significantly optimized over the same function as it is in APS/NWNX 2. And the behaviour of each of them should be exactly the same. This set of function is supported by NWN-MySQL.dll but also by the NWN-FF version of NWNx_ODBC.dll plug-in dll. Most of those functions are now obsolete.

For faster and more convenient functions, you should use those specific to NWN-FF here (3^rd generation).

Setup placeholders for ODBC requests and responses. You need to call this before starting to use any NWN-FF function
void SQLInit();

Execute statement in sSQL
void SQLExecDirect(string sSQL);

Position cursor on next row of the resultset
Call this before using SQLGetData().
returns: SQL_SUCCESS if there is a row
SQL_ERROR if there are no more rows
int SQLFetch();

Return value of column iCol in the current row of result set sResultSetName
string SQLGetData(int iCol);

Return a string value when given a location
string APSLocationToString(location lLocation);

Return a location value when given the string form of the location
location APSStringToLocation(string sLocation);

Return a string value when given a vector
string APSVectorToString(vector vVector);

Return a vector value when given the string form of the vector
vector APSStringToVector(string sVector);

Set oObject's persistent string variable sVarName to sValue
Optional parameters:
iExpiration: Number of days the persistent variable should be kept in database (default: 0=forever)
sTable: Name of the table where variable should be stored (default: pwdata)
void SetPersistentString(object oObject, string sVarName, string sValue, int iExpiration =0, string sTable = "pwdata");

Set oObject's persistent integer variable sVarName to iValue
Optional parameters:
iExpiration: Number of days the persistent variable should be kept in database (default: 0=forever)
sTable: Name of the table where variable should be stored (default: pwdata)
void SetPersistentInt(object oObject, string sVarName, int iValue, int iExpiration =0, string sTable = "pwdata");

Set oObject's persistent float variable sVarName to fValue
Optional parameters:
iExpiration: Number of days the persistent variable should be kept in database (default: 0=forever)
sTable: Name of the table where variable should be stored (default: pwdata)
void SetPersistentFloat(object oObject, string sVarName, float fValue, int iExpiration =0, string sTable = "pwdata");

Set oObject's persistent location variable sVarName to lLocation
Optional parameters:
iExpiration: Number of days the persistent variable should be kept in database (default: 0=forever)
sTable: Name of the table where variable should be stored (default: pwdata)
This function converts location to a string for storage in the database.
void SetPersistentLocation(object oObject, string sVarName, location lLocation, int iExpiration = 0, string sTable = "pwdata");

Set oObject's persistent vector variable sVarName to vVector
Optional parameters:
iExpiration: Number of days the persistent variable should be kept in database (default: 0=forever)
sTable: Name of the table where variable should be stored (default: pwdata)
This function converts vector to a string for storage in the database.
void SetPersistentVector(object oObject, string sVarName, vector vVector, int iExpiration =0, string sTable = "pwdata");

Get oObject's persistent string variable sVarName
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
* Return value on error: ""
string GetPersistentString(object oObject, string sVarName, string sTable = "pwdata");

Get oObject's persistent integer variable sVarName
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
* Return value on error: 0
int GetPersistentInt(object oObject, string sVarName, string sTable = "pwdata");

Get oObject's persistent float variable sVarName
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
* Return value on error: 0
float GetPersistentFloat(object oObject, string sVarName, string sTable = "pwdata");

Get oObject's persistent location variable sVarName
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
* Return value on error: 0
location GetPersistentLocation(object oObject, string sVarname, string sTable = "pwdata");

Get oObject's persistent vector variable sVarName
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
* Return value on error: 0
vector GetPersistentVector(object oObject, string sVarName, string sTable = "pwdata");

Delete persistent variable sVarName stored on oObject
Optional parameters:
sTable: Name of the table where variable is stored (default: pwdata)
void DeletePersistentVariable(object oObject, string sVarName, string sTable = "pwdata");

(private function) Replace special character ' with ~
string SQLEncodeSpecialChars(string sString);

(private function)Replace special character ' with ~
string SQLDecodeSpecialChars(string sString);

ff_include

Here are all low-level and optimized functions provided with NWN-FF. Those all need the use of one of the NWN-FF main dll. Please keep those functions unchanged: to keep good compatibility with other NWN-FF modules and also simplify update process with next versions of NWN-FF, better make changes in the other server-specific files.

Part1: Non-database related functions

Those functions do not need any Database, and as such work with NWN-MySQL.dll but also NWN-NoDB.dll

int SQLGetTime(); // Gives the number of micro-seconds since NWServer started (can be used for precise Benchmarks)

string SQLGetVersion(); // Returns version string for NWN-FF

int SQLGetRLDate(); // Returns the number of second since january 1st 2001 (in RL world)

void SQLSetIGDate(); // This function can be put in OnModuleLoad event to automatically synchronize IG and IRL times

This conversion functions are not compatible with their APS equivalent, but should be used if you don’t really need to either read old APS/NWNX data or write data that could be read by another module that only uses APS/NWNX. They convert location into strings that are much smaller.

string ff_LocationToString(location lLocation);

location ff_StringToLocation(string sLocation);

string ff_VectorToString(vector vVector);

vector ff_StringToVector(string sVector);

Part2: Database related functions (2nd generation: they can be freely mixed with APS/NWNX functions)

Those functions need a MySQL database. They work with NWN-MySQL.dll or even NWN-FF MySQL plugin (NWNx_ODBC).

// SQLExecAndFetchDirect is roughly equivalent to SQLExecDirect immediately followed by SQLFetch (but faster)
// It can be used for result sets up to 4KB long (4096 characters)
int SQLExecAndFetchDirect(string sSQL);

// When you’re doing a request that returns several values, using SQLGetData may be very inefficient.
// Better use SQLEatData (and, if you don’t need to use all data as they are returned, SQLSkipData to ignore some of them). SQLEatData read the next unread Data.
// but if you really need something really fast, then use the next set of functions (SQLLocalExecAndFetchDirect/SQLLocalEatData…)
string SQLEatData();

void SQLSkipData();

Part3: Database related functions (3rd generation: the fastest, but can’t be mixed together with APS/NWNX functions)

Those functions do need a MySQL database. They work with NWN-MySQL.dll or even NWN-FF MySQL plugin (NWNx_ODBC).

Because all SQLLocalXXXX functions share a global variable, all such functions related to the same request should better be used within a single script. Avoid for instance to call SQLLocalExecAndFetchDirect in a function and then corresponding SQLLocalEatData within other functions called with AssignCommand, ExecuteScript or DelayCommand. Except in this case, you should always try to use this set of function instead of those described within previous sections.

Similar to the 2^nd generation SQLExecAndFetchDirect function, this one is to be used with the other SQLLocalXXXX functions.
int SQLLocalExecAndFetchDirect(string sSQL);

If you’re waiting for several answers (rows) after a request, then either use
SQLExec then SQLLocalFetch for each row, until it returns SQL_ERROR
Or, use SQLLocalExecAndFetchDirect for the first row, and then SQLLocalFetch for each following.
int SQLLocalFetch();

Similar to SQLEatData(), use this one after SQLLocalExecAndFetchDirect or SQLLocalFetch to retrieve each value as a string (column).
string SQLLocalEatDataString();

Same but for other type of data (int, float, location or vector)
int SQLLocalEatDataInt();
float SQLLocalEatDataFloat();
location SQLLocalEatDataLocation();
vector SQLLocalEatDataVector();

Similar to SQLSkipData, to be used if there is a column you don’t need.
void SQLLocalSkipData();

Part4: Database related functions (still 3rd generation: those used to store or retrieve a single value)

Very fast set of function used to store or retrieve a single value.

This function take a SQL request as a parameter (plus an optional default value, used if the request fails). It returns the result of the request as a string. It is much optimized, but should only be used for relatively short results: the size of the result string needs to be smaller than the size of the request.
string SQLExecAndFetchSingle(string sSQL, string DefaultValue="");

Similar to SQLLocalEatData except it directly returns an int.
int SQLExecAndFetchSingleInt(string sSQL, int DefaultValue=0);

Those 11 optimized functions are used to very easily store, retrieve or delete a single value (string, int, float, location or vector). Other kind of data can be easily supported by using conversion routines. You can optionally specify the name of the table and the default value returned on ff_GetPersitentXXX functions when the data do not exist (except for ff_SQLGetPersistentLocation).
string ff_GetPersistentString(string ValueName, string sTable="global", string DefaultValue="");
int ff_GetPersistentInt(string ValueName, string sTable="global", int DefaultValue=0);
float ff_GetPersistentFloat(string ValueName, string sTable="global", float DefaultValue=0.0);
location ff_GetPersistentLocation(string ValueName, string sTable="global");
vector ff_GetPersistentVector(string ValueName, string sTable="global");
void ff_SetPersistentString(string ValueName, string sValue, string sTable="global");
void ff_SetPersistentInt(string ValueName, int iValue, string sTable="global");
void ff_SetPersistentFloat(string ValueName, float fValue, string sTable="global");
void ff_SetPersistentLocation(string ValueName, location lValue, string sTable="global");
void ff_SetPersistentVector(string ValueName, vector vValue, string sTable="global");
void ff_DeletePersistentVariable(string ValueName, string sTable="global");

Those 11 optimized functions are used to very easily store, retrieve or delete a single value for a given PC (string, int, float, location or vector). Other kind of data can be easily supported by using conversion routines. Those can only be used if you use the default login mechanism provided with NWN-FF.erf.
string ff_GetPCPersistentString(object oPC, string ValueName);
int ff_GetPCPersistentInt(object oPC, string ValueName);
float ff_GetPCPersistentFloat(object oPC, string ValueName);
location ff_GetPCPersistentLocation(object oPC, string ValueName);
vector ff_GetPCPersistentVector(object oPC, string ValueName);
void ff_SetPCPersistentString(object oPC, string ValueName, string sValue);
void ff_SetPCPersistentInt(object oPC, string ValueName, int iValue);
void ff_SetPCPersistentFloat(object oPC, string ValueName, float fValue);
void ff_SetPCPersistentLocation(object oPC, string ValueName, location lValue);
void ff_SetPCPersistentVector(object oPC, string ValueName, vector vValue);
void ff_DeletePCPersistentVariable(object oPC, string ValueName);

Part5 Database related functions, dealing with objects

// Store an object for that PC on a specific Placable (chest...)
void ff_SetPersistentObject(object oOwner, object oObject, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

// Retrieve the first object for that PC on a specific Placable (chest...)
object ff_GetPersistentObjectFirst(object oOwner, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

// Retrieve the next objects ('til return NULL)
object ff_GetPersistentObjectNext(object oOwner, object oPlacable=OBJECT_INVALID);

// Remove all objects associated with that player on a given placable
void ff_CleanPersistentObject(object oOwner, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

And the following functions are provided for NWNx/APS compatibility:
object GetPersistentObject(object oObject, string sVarName, object oOwner = OBJECT_INVALID, string sTable = "pwobjdata");
void SetPersistentObject(object oOwner, string sVarName, object oObject, int iExpiration = 0, string sTable = "pwobjdata");

Plus this bonus function, very useful to handle persistent inventories (chests…)

void DeleteAllPersistentObject(object oObject, string sTable = "pwobjdata");

Part6 New helper set of functions, coming with NWNx functions plugin.

void ff_SetGoldPieceValue(object oObject, int iValue);
void ff_SetName(object oObject, string NewName);
void ff_SetDescription(object oObject, string NewDescription);
string ff_GetDescription(object oObject);
void ff_SetBodyPart(object oPlayer, int nPart, int nType);
int ff_GetBodyPart(object oPlayer, int nPart);
void SetLockDC(object oChest, int DC);
void ff_ChangePlayerAppearance(object oPlayer, int nPart, int nType);
void ff_ChangePlayerAppearance(object oPlayer, int nPart, int nType);
void ff_DeleteThisChar(object oPC);

ff_inc_server

The functions provided here may be adapted to meet your needs. Consider the implementation provided with NWN-FF as a working and optimized starting point, from which you can build your own way.

log helper. Those two functions are used to replace the Log feature provided by Default with Neverwinter Nights. Those log information are stored into a database, and if you’re using the different keys properly (sCategorie and sSubCategorie), it should be easy to make efficient searches/sorts when you’re looking for something.
void pwWriteLog(object oPlayer, string sCategorie, string sSubCategorie, string sTexte);
void pwWriteLogCon(object oPlayer, string sCategorie);

This function is pretty important to keep all important data related to each PC up to date. You should call it on most important events (death, respawn, area transition, all healing spells, rest, NPC death…
void ff_FlushData(object oPlayer);

This one two is critical, and really is a must for all NWN-FF modules. It handle the PC login process (identification, some checking, log of informations…).
int ff_SelectPersistentChar(object oPlayer);

You may want to adapt this couple of function in order to use your own rules for name validation and initial values to be set at PC creation.
void InitValues(object oPlayer);
int HasValidName(object oPlayer);

ff_inc_addons

This script comes empty with NWN-FF, you can put here any specific additional code. For instance, if you need to add some functions to FF-NWN for a specific 3^rd part package, please includes your own files within this script. ff_inc_addons content will be available for all scripts starting with #include “ff_include”.

ff_include_other

You’ll find here some other useful general-purpose functions. They’re stand-alone and do not need any NWN-FF or APS/NWNX binaries.
Those functions should be used on Linux servers too. The most important function provided here is ff_Colorize.

This replaces all occurences of textes inclosed with brackets by something else as defined with SetLocalString(GetObjectByTag("cmdLiteColors"), OldString, NewString)
Mainly used to add colors in the textes, with colors [r], [db]... (check complete list in initColor() function)
You need to call InitColor in OnModuleLoad and have proper placables in your module in order to get this function working. NWN_FF.erf do that for you.
string ff_Colorize(string sText);

Example: SendMessageToPC(oPC, ff_Colorize(“[g]I’m sorry but you’re [r]DEAD[g]!”));

This will display the following to oPC: I’m sorry but you’re DEAD!

Those 5 functions are used in NWN-FF:
int ff_IsUpperCase(string oS);
int ff_IsLowerCase(string oS);
void ff_JumpToObject(object oPC, object oDest);
void ff_JumpToLocation(object oPC, location lDest);
string ff_GetResRef(object oItem);

APS/NWNX 2 and NWN-FF compatibility

NWN-FF is based on APS/NWNX. The concept and even a good part of the source codes, come from APS/NWNX.
But it's also adds significant improvements on the APS/NWNX functionalities, and adds some.
One of the strength of NWN-FF, it's that it keeps a very good compatibility with APS/NWNX, at all the levels:

Binary compatibility

There are three layers in APS/NWNX:
A/ the monitoring tool, NWNX2.exe,
B/ the main dll, nwnx-module.dll
C/ the plug-in, nwnx_*.dll

NWN-FF 4.0 provides the same 3 layers, and they are interchangeable with APS/NWNX.
A/ the monitoring tool, NWN-MySQL.exe, NWN-NoDB.exe or NWN-DLL.exe (depends on the functionalities you need)
B/ the main dll, NWN-MySQL.dll, NWN-NoDB.dll (depends on the kind of database you're using, if any)
C/ the plug-ins: all APS/NWNx plug-in are supported, except those that are allready included in the main dll (profiler and database support are included in the main dll, for simplicity and performance issues).

For instance, NWN-FF monitoring tools do not work on Win98 (but all the dll should do), so you may want to use the executable from APS/NWNX with all other component provided with NWN-FF. In that case, simply use NWNX2.exe and rename the main dll you want to use from NWN-FF package into nwnx-module.dll (the name NWN2.exe uses for its main dll).
Also, you may prefer to use NWN-MySQL.exe but want to keep APS/NWNX dlls (for some obscure reasons I can't guess J). All combinations are possible, just make sure to rename the different dll as needed (and include libmysql.dll, if you're using any MySQL component).

And, last point, NWN-FF 4.0 comes with several (3 in 4.0.3, probably I'll do some more at a later time) plug-in for APS/NWNX. The first one should replace NWNx_ODBC.dll and provides both direct MySQL support and some of NWN-FF added functionalities. The two other allow easy speech processing inside your module.

Script/module compatibility

NWN-FF comes with an extended set of functions, but all APS functions are still supported. So you can keep your module unchanged, and do not even need to recompile it when you use NWN-FF binaries (dll and/or exe).
Now of course, if you're using NWN-FF specific functionalities (provided in NWN-FF.erf), then it may not work with APS/NWNX binaries anymore (except, in some cases, if you're using NWN-FF version of NWNx_ODBC.dll as a plugin for APS/NWNX)

Data compatibility

You can update APS/NWNX into NWN-FF (or just any part of it) and keep your database data unchanged.
NWN-FF comes with a set of suggested tables, but they are all automatically created as needed (at least with a MySQL database, you may need to do some changes in the scripts if using another database).
Also NWN-FF may update your pwdata table structure, but no data will be lost or altered in the process.

Fast?

It's a complete upgrade, on all 3 components: NWNX2.exe, NWNx.dll and aps_include.nss. And none of them is minor.

I first designed those tools for my own use, and as it seems that LAG is a major concern for larges servers, I finally decided to make it more configurable and release it to everyone who may need it.

I reduced by a factor of 130 the lag introduced with DB access, starting at 20% CPU usage with 64 player and APS/NWNX2 and default data structures down to 0.15% CPU usage now. Today, I’m using MySQL so much that FastFrench (the server) couldn’t probably handle more than 40 players with an APS/NWNX interface, or maybe 3 or 4 players at most with Bioware Database. We reached with version 1.62 up to 82 players connected, and there is very limited lag up to 50 players. On a PIV 3GHz, the average time for a NWN-MySQL transaction on an empty server is between 100µS and 300µS. The steps to optimisation are (from the easiest to the hardest – you can stop at any step)

1/ using NWN-MySQL binaries.

2/ import NWN-FF and overwrite your old aps_include.nss file.

2/ using optimised functions I provide in ff_include.nss (SQLlocalXXX set)

3/ optimise the design of your tables to all requests used in your module (for instance, try got get tables as light as possible, and optimal keys).

4/ trying to reduce number of requests, by grouping data into more complex MySQL instructions.

You can contact me (FastFrench) through e-mail: fastfrench@laposte.net, on our forum http://fastfrench.eskysse.com or on NWN Vault : http://nwvault.ign.com/Files/other/data/1057237614460.shtml

Source codes are included in NWN-FF 4.0 package. Please give me some feed-back on the usage of NWN-FF and how well it performs for you.

How much it was tested?

I started to write the monitoring tools of NWN-MySQL by the end of 2002. Since April 2003, I’m using NWN-MySQL with its direct API support, and some of the first specific functions. So, the core functions of NWN-FF are very well tested, at least on my context: WinXP pro and MySQL. The monitoring tool is now very reliable, and probably the best available to keep a Windows server alive.

Component	Testing level	Comment
NWN-MySQL.exe	Very good	I’m using this on FastFrench, our server that reached up to 82 players ;)
NWN-NoDB.exe	Very limited	Just tried it a couple of time.
NWN.NoDLL.exe	Correct	I’m using this on FastFrench, for a debugging module.
NWN-MySQL.dll	Very good	I’m using this on FastFrench.
NWN-NoDB.dll	Very limited	Just tried it a couple of time.
NWNx_ODBC.dll	Correct	I’ve experimented it for some time, and it were tried on some other servers.
BinTracer.exe	Correct	I’m using this somewhat. Not critical usage, I will improve it if the need arises. Dirty coding, dirty look, but works fine.
StoreItem	Correct	I’m using this from time to time, with each major update of my module. You’ll need this only if you want to import some data for all your items into a MySQL Database. Dirty coding but works fine.
NWNx_FFSpeech.dll	Very Good	I’m using this right now on FastFrench.

NWN_FF.erf	Limited	I’ve just experimented it a little bit. Waiting for feed-back from users.
NWN-FF.mod	Correct	I’ve experimented it for some time.

What do NWN_FF.erf do?

First of all, NWN_FF.erf provides you access to all the functions included in FF_include.

But it also provides some higher level functionality already coded, that you can either keep unchanged or consider as a good starting point to begin with.

Here are the functionalities that are available in NWN-FF.erf:
-> A complete PC login process.
-> Aps_include compatibility file, so that APS/NWNX module will still work (but faster) after importation of the erf file.
-> All the other FF_include specific added functions.
-> Module Onload processing, including automatic creation, optimization and repair for all default tables, and also some automatic cleaning ideas.
-> Optimized speech processing example. Includes several advanced actions, like sending RP messages to another player (using pigeons), and, for DMs, the ability to drop personalized hint scrolls.
-> Login automatic actions. You can program into the database all the actions that will be automatically launched at module startup or when a specific PC logs in.
-> ff_Colorize: simple function to be used (thanks to Buu for the idea) to put more colors into your texts.
-> Simple tracking mechanism for some PC data (hp, location, and connect time). Scripts provided for some module or area events, and a function provided that can be called whenever you want (death of NPC, some spells, rest event...).
-> A sample dialog to display some Server stats for the PC and/or DM.
-> It also populates a database table with, for each area, a counter showing how often a PC enters it. It's a very useful information for builder, to know exactly what areas are much used and which one are not.

When does the monitoring tool decide to restart the NWN Server?

It appears clearly in the NWN-FF that I should clarify the rules that are used by the monitoring tools to take the decision of restarting the NWN Server.

So here is a very detailed and exhaustive list for all possible reason of a restart, depending on the current parameters set in the configuration file. Also, for each case, I give the exact message that will be written in the log file.

Note: time slice duration is defined by TimeSlice value in configuration file. Default value is 20 seconds.

If WithAdvancedHeuristics is set to 1, the server restarts when one of those conditions is met:

1/ Server OverLoaded for a long period of time:

It means CPU > 99% over 100 times slices

Note: the message displayed and logged in that case is «NWServer saturated over 100 times... force restart!»

2/ Server has been somewhat heavily used, and is now empty:

Has been well loaded for some time (means over 20 players during more than 20 time slices) AND is now empty for a long time (less than 4 players for over 40 time slices).

Note: the message displayed and logged in that case is «Better restart now, as NWServer has few players... force restart!»

3/ Current load counter is down to 0

The initial load counter is set to MaxCounter parameter in the configuration file (default is 30 000).

At each server restart, the current load counter is set to the initial load counter

At the end of each time slice, the current load is subtracted from the current load counter.

The current load is computed as follow:

- Current number of players if CPU load < 94%

- Current number of players x2 if CPU is between 94% and 98%

- Current number of players x4 if CPU is > 98%

Note: the message displayed and logged in that case is «NWServer got enough cumulative load for this run, force restart!»

If WithAdvancedHeuristics is set to 0

3bis/ Current load counter is down to 0

The initial load counter is set to MaxCounter parameter in the configuration file (default is 30 000).

At each server restart, the current load counter is set to the initial load counter

At the end of each time slice, the current load is subtracted from the current load counter.

The current load is 1 all the time (when WithAdvancedHeuristics is set to 0)

Note: the message displayed and logged in that case is «NWServer got enough cumulative load for this run, force restart!»

If WithAdvancedHeuristics is set to 1 AND (bModuleFeedBack is set to 0 OR NWN-NoDLL.exe is used)

4/ CPU stay for some time at 0%, despite several players seems to be connected

At the end of each time slice, (3+NbPlayer)/5 is added to the idle counter

Whenever the CPU comes over 0.01%, the idle counter is reset

When this idle counter reaches 10, the server restarts

Note: the message displayed and logged in that case is «CPU=0.0 for too long, certainly hanged... force restart!»

If bModuleFeedBack is set to 0 OR NWN-NoDLL.exe is used

5/ NWN Server seems to be hanged (After an initial delay of InitialDelayS seconds)

Either the corresponding process is not in “STILL_ACTIVE” state anymore (crashed, or stopped for any reason).

Or NWN Server didn’t process user messages for over 20 seconds.

Note: the message displayed and logged in that case is «NWServer is hanged... force restart!»

If bModuleFeedBack is set to 1 AND a main DLL is used (meaning you’re NOT using NWN-NoDLL.exe)

6/ After an initial delay of InitialDelayS seconds, no activity is detected by the monitoring tool.

After this InitialDelayS seconds delay, the monitoring tool remains in a “no activity tolerant state” for up to 30 additional time slices (So, with default values, 10 minutes)

As soon as a SetLocalString instruction is used for the first time, or when this “no activity tolerant state” expires, then the module scripts should call SetLocalString at least once in each time slice, or the server will restart.

Note: the message displayed and logged in that case is «No activity detected on the server, force restart!»

No matter what the options are, here are 2 additional possible reasons for a restart:

7/ A script asked for a reboot with NWNX!DMREBOOT instruction

Note: the message displayed and logged in that case is «DM reboot!»

8/ Someone pressed the “R” key on the server console

Note: the message displayed and logged in that case is «Key R pressed: force restart!»

Changelog

Changelog for NWN-FF

18.10.2005: v 4.1.0

With this version 4.1.0, NWN-FF now supports saving and retrieving objects from a MySQL database (RCO/SCO). This new feature is an adaptation of NWNx/APS equivalent, with of course some additional optimizations.

All rarely used parts of NWN-FF have been removed: mainly all ODBC stuff, so now NWN-FF only works either with MySQL or no database. Also FF_translator.exe and the archaic versions of Speech support (only NWNx_FFSpeech is now provided and supported).

In this version, I’ve mainly integrated all the interesting points from NWNX/APS into NWN-FF, the same way NWNX/APS included several features first introduced into NWN-FF.

Thanks to Papillon, Xildjian, Dazzle, Isilweo for their work.

I’ve also added the several functions from NWNX/APS into NWNX_Functions plug-in : SetDescription (only usable for items and placeables) and SetName (Item, placeables and MapNotes). I’ve also included many new functions, written by different NWN community member (thanks to Xildjian, xildjian@comcast.net for DeleteChar, Isilweo for SetName / SetDescription, Dazzle and NWNx team for most of the other functions).

I’ve also included in the package (both demo module and erf importation file), a ready-to-use persistent chest. All you have to do is to get it from the palette (magical chest) and put it on the map. If you want to have several chests, better give a unique tag for each one.

As I’ve found it convenient, I’ve also included Papillon’s NWNx_Resman.dll. This is the exact original, I’ve done no adaptation on this one. Like all NWNx plugins, it works with no trouble on NWN-FF.

Here is the list of all new functions coming with NWN-FF:

Database related functions, dealing with objects

// Store an object for that PC on a specific Placable (chest...)
void ff_SetPersistentObject(object oOwner, object oObject, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

// Retrieve the first object for that PC on a specific Placable (chest...)
object ff_GetPersistentObjectFirst(object oOwner, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

// Retrieve the next objects ('til return NULL)
object ff_GetPersistentObjectNext(object oOwner, object oPlacable=OBJECT_INVALID);

// Remove all objects associated with that player on a given placable
void ff_CleanPersistentObject(object oOwner, object oPlacable=OBJECT_INVALID, string sTable = "RCO_SCO");

//And the following functions are provided for NWNx/APS compatibility:
object GetPersistentObject(object oObject, string sVarName, object oOwner = OBJECT_INVALID, string sTable = "pwobjdata");
void SetPersistentObject(object oOwner, string sVarName, object oObject, int iExpiration = 0, string sTable = "pwobjdata");

//Plus this bonus function, very useful to handle persistent inventories (chests…)
void DeleteAllPersistentObject(object oObject, string sTable = "pwobjdata");

New helper set of functions, coming with NWNx functions plugin.

15.4.2005: v 4.0.15

Thanks to Garrath suggestion, SQLDecode/SQLEncode changed to work faster: SQLEncode is as slow as before, but SQLDecode is now very fast (it does nothing at all J ). If you have existing tables which are not NWN-FF standard, and if you use fields with texts that may have quotes in them (or “~”), then you may need to edit the end of ff_buildtable.nss and add some new FixQuotes instruction to convert those fields into the new NWN-FF 4.0.15+ format. If you may prefer to do it manually, you may use this SQL instruction for each text field that may have quotes (replace TableName and FieldName with the proper value). In that case, do it just before launching the new version of your module:

UPDATE TableName SET FieldName = REPLACE(FieldName,'~', '\'') WHERE LOCATE('~', FieldName)>0

Some bugs reported by Hacknisty are fixed (errors in a couple of SQL instructions).

The following nss files have changed: aps_include.nss, ff_buildtable, ff_include

The option [FFSpeech] Debug will now trace the detail of all speech only for a Debug value of 2 or higher. (before, was 1 or 2 for more details).

Here is the meaning for each value: 0 = only critical errors traced. 1 = details on Interface selection and some important warnings. 2 = detailed traced, including all text contents. 3 = very detailed traces.

Some new tries to avoid that @@@ error message when NWServer.exe is restarted. Unfortunately this message still sometimes occurs.

A new instruction NWNX!ODBC!DEBUG. This instruction will allow you to change the debug level of nwn-MySQL.dll or nwn-ODBC.dll from the scripts. It may be useful for instance when you want to get full debug information for only some specific parts of your script. A value of 0 will put the old value back ([MySQL] Debug).

The instruction NWNX!DLL introduced in version 4.0.14 didn’t work properly. It’s now fixed.

The plug-ins dll had sometimes a wrong name when compiled (nwnx-* instead of nwnx_*). This is fixed.

When no module activity is detected, the server still do not restart now until CPU usage drops to 0%.

15.4.2005: v 4.0.14

New function: NWNX!DLL that allows to check if a given plug-in is available.

I’ve found and corrected a bug in NWNx-FFSpeech. Now it should better take into account the NIC_IP option in [FFSpeech] section.

I forgot to mention another change in 4.0.13: BinTracer, the application that you can use to display binary performance traces (*.bi4 files), as a much better interface now.

13.4.2005: v 4.0.13

Some parts of the code rewritten to be cleaner (no compiler warnings anymore, smaller code with less redundancy) and faster (some more optimizations).

Now fully support MySQL 4.1, with all new functionalities coming with it (subqueries…). Also the script part should be much more compatible with non-MySQL Databases (Access, PostgresSQL… via ODBC).

Some improvements in the monitoring tools, to make the parameters more obvious and coherent.

Documentation: More points covered within the F.A.Q. and a complete new chapter “When does the monitoring tool decide to restart the NWN Server?”

Script changes:

ff_pc_loops.nss and ff_inc_options.nss: added a new option, FF_PLAYERFILE_SAVE, used to avoid the periodical saving of the players files (mainly for local vault servers).

ff_inc_other.nss: removed ff_GetResRef(object oItem); declaration (was never defined or used). Thanks to “The Guardian of Orlanthia” for reporting this.

Aps_include.nss, ff_include.nss, ff_inc_server.nss and ff_inc_options.nss: added the options, FF_MYSQL_4_1, that will enable specific MySQL 4.1 optimizations and FF_MYSQL that (if set to 0) will replace all MySQL specific instructions with more standard (but slower) equivalents.

ff_inc_options, ff_on_cl_enter.nss, ff_buildtable.nss, ff_inc_server.nss: FF_NO_BAN option. If you set this one, NWN-FF won’t ban or reject any player, for any reason. Use this one at your own risk: you renounce to all NWN-FF coherency checking by setting this option.

8.9.2004: v 4.0.12

New option in [Global] section: HideAllWindows, allow you to keep all NWN Windows invisible (useful if you don’t want people to see what is running on your PC, like if you’re running a server from work). That is: the monitoring Windows won’t be displayed, neither will NWServer window itself.

Script changes:

ff_buildtable.nss, ff_inc_options.nss (the table ‘deleted’ is not needed anymore and cleaning is now configurable with options in ff_inc_options),

ff_pc_loops.nss (PC are not saved anymore while shapechanged or polymorphed)

ff_on_heartbeart.nss (a bit more efficient)

30.6.2004: v 4.0.11

As it seems that the check of CPU activity is not reliable enough with few or no players (in some cases, with very few players quite inactive, CPU stays at 0.0% and NWServer.exe restarts the module after a while. So I’ve changed this, and added some active communication between the module itself and the monitoring tool.). The monitoring tools (NWN-MySQL.exe and NWN-ODBC.exe) have changed. You may disable this new feature with [NWNServer] bModuleFeedBack=0

NWN-NoDB.exe now should properly load NWNx plug-ins (thanks to Layane for reporting this)

NWNx_FFSpeech.dll has been upgraded in an attempt to avoid error messages when closing the NWserver.exe.

New parameter in configuration file: [NWNServer] InitialDelayS

This delay, in seconds, will tell the monitoring tool how long it waits before resuming normal monitoring when the server restarts. Default value is 60, minimum is 30.

New instruction to be called from NWNScripts: NWNX!DMREBOOT => This will ask the monitoring tool to cleanly reboot the server.

The directory used for all the log files can now use time/date variables. Check here.

No change in the scripts, but the demo module have been adapted to show how to reboot the server (a lever in it can be used to immediately reboot the server)

3.6.2004: v 4.0.10

Some more FAQ added in documentation.

FF_PCC_CLERIC_NEED_DEITY option added (0 by default, will prevent booting PC at creation when they play a cleric or a paladin and have not specified any Deity)

Some fixes in NWNx-FFSpeech.dll, where some name were corrupted (those with quotes).

V 4.0.9 monitoring tools were still sometimes restarting NWServer.exe when it’s not really needed. It may happen when at least one player where connected and the NWServer process reported 0.0% CPU used. This should be better fixed with version 4.0.10.

Some pigeon’s eggs added in the demo module, to make the experimentation of *write to <name>: <message>* speech command easier.

26.5.2004: v 4.0.9

V 4.0.8 monitoring tools sometimes restarted NWServer.exe when it’s not really needed. It may happen when at least one player where connected and the NWServer process reported 0.0%CPU used. This happened sometimes when only 1 or 2 players were connected but with very low activity level.

25.5.2004: v 4.0.8

Fixed a problem with NWNx_FFSpeech (that in many cases didn’t work properly since version 4.0.5)

Also improved the monitoring tools to handle an additional case where it didn’t detect NWServer.exe malfunction.

The demo and module are still unchanged since v4.0.5.

19.5.2004: v 4.0.7

Easier and more reliable configuration of NWNx_FFSpeech for servers with several NICs. A new option added in NWN-FF.ini : NIC_IP. Default value is 0.0.0.0.

One more tool: NIC_Testing.exe. It can be used to check the existing NIC on the PC, so you can easily setup NWNx_FFSpeech.
If the database is not available when the monitoring starts, it will now wait up to 50 seconds before failing. This is done to help auto-start or starting as a service.

No changes in the scripts

Some improvement in NWN-FF log files when using MySQL (thanks to buu)

Documentation better explain how to use NWN-FF with Unix.

14.5.2004: v 4.0.6

One more FAQ added to get starting with MySQL.

11.5.2004: v 4.0.5

Some minor adjustments were done to make channel support easier when using NWNX_FFSpeech.dll.

A couple of FAQ added.

9.5.2004: v 4.0.4

Some minor adjustments have been done, to take into account some user remarks.

More options added in ff_include (and all previous options renamed, starting now with FF_)

Some default behaviors changed to make NWN_FF.erf easier to start with (default parameters are set for an easy start).

New instructions added in NWNx_FFSpeech.dll, to optionally provide IP, Port and channel information.

An aps_include2.nss script file added to make the upgrade from NWN-MySQL 3.20 easier (it just includes one useful line: #include “ff_include”).

ff_inc_addons.nss script file added: it comes empty with NWN-FF, and will remain empty with all future versions. You can put here any additional code you want.

ff_inc_options.nss script now contents all parameters you can change in NWN-FF.

26.4.2004: v 4.0.3

Documentation updated.
Many new functions added for being easier to use and more exhaustive: now NWN-FF provides a set of 82 functions.

Several bugs fixed in the tools and scripts.

With MySQL, the database is now automatically created. So now, starting to use MySQL with NWN-FF is really very easy: you just need to install MySQL and copy the needed files from bin\ to your NWN directory.

I’ve removed the need to have a dedicated area in the erf file. Now all WP and placeables needed by NWN-FF are automatically created.

4.0.3 will be the first public release of NWN-FF.

12.04.2004: v 4.0.2

Documentation updated.

NWNx_FFSpeech.dll and NWNx_MySQLSpeech.dll added.

Added area counters in scripts, script speech part optimized and adapted for NWNx_FFSpeech.dll.

04.04.2004: v 4.0.1

Documentation updated.

All tables are automatically created when needed.

First version of demo module and NWN_FF.erf import file completed.

20.03.2004: v 4.0.0

It’s a major update. I won’t detail all the changes: there’re too many. 2/3 of this documentation reflects those changes. Many new projects added in the package.

NWN-FF supports APS/NWNX 2 plug-in, and also comes with erf file and demo module.

The tools and scripts automatically create all the tables they need.

GameSpy is not used anymore by the monitoring tools, and replaced by Script/MySQL communication: it’s more reliable and won’t be dependant on next changes from Bioware on the protocols they use.

Now NWN-FF will be provided with all source codes.

Changelog for NWN-MySQL

(Please note that NWN-MySQL is not related at all with Papillon or Avlis team. FastFrench is the only author of this update)

* 22.09.2003: v 3.2.0

1. After the release of APS/NWNX 2.5, I’ve included and improved the APS/NWNX Profiler. NWN-MySQL profiler is better optimised, gives more reliable statistics, and also cumulates all results from different sessions of NWNServer. Each time NWNServer starts, NWN-MySQL reload previous results and starts from this point. So you can get profiling results over a very large period of time (On FastFrench, my own server, it’s right now running over 6 days, with a total of nearly 30 millions scripts called). Also recursive calls, are properly handle. A nwnx_profiler.csv file is automatically generated, that can easily be open using Excel (or probably several other applications). I’ve send the source code to the author of APS/NWNX, so thoses changes may be added in next version of APS/NWNX.

2. You can now disable GameSpy protocol in NWN-MySQL.exe (using NoGameSpy parameter, with a value different of 0)

3. A minor limitation fixed: you can now use SQLFetch() after such functions as SQLLocalExecAndFetchDirect, when several results exist.

4. Minor bug fix: “! NWNX!ODBC!SPACER: command unknown!!” won’t appear anymore in the log files.

5. A possible bug fixed where default IP were 192.0.0.1 instead of 127.0.0.1

6. SQLSetIGDate() is now supported on Unix version too, it’s not dependant on NWN-MySQL binaries anymore: runs with APS/NWNX as well with no change.

* 28.07.2003: v 3.1.3

7. A small bug fixed in APS_include2.nss, that makes a compile error.

8. A new high level function in aps_include2.nss: void SQLSetIGDate() You just need to insert a call to this function in your Module OnLoad script (after SQLInit()), and the time and date on your module will magically becomes persistent and coherent with real time. Note that you don’t need any specific table in your database for this to work. How fast the time will run in your world (compare to RL time) depend on your module parameter. If you set 10 minutes per hour, then time will run exactly 6 times faster in your module. If you set 1 minute per hour, then time will run 60 times faster in your world (1 day IG = 24 minutes IRL). Also the 1^st January 2001 0:0:0 in RL will coincide with the 1/1/1001 IG 0:0:1.

9. Many changes and fixes in this documentation, I hope it will be easier to understand.

10. Started a FAQ section in documentation.

11. Two different versions of update_aps_include.txt are now in MySQL and ODBC directories (as those are Database-specific)

12. I’ve added 3 versions of aps_include.nss in .\Starter\ sub-directory, so APS/NWNX2 package is not needed anymore, and it’s easier to directly start using NWN-MySQL package.

* 24.07.2003: v 3.1.2

- Added several error messages and debug information in log file

- Added two new options in [NWNServer] section of nwn-mysql.ini:

MaxCounter => says how often the server will be restarted. Default is 30000, smaller value means server will restart more often.

- New Plug-in support: now you can launch any application from NWN scripts with the new function NWNX!RUN.

For instance, SetLocalString(GetModule(), "NWNX!RUN", "command.com /c del c:\\fic.txt"); will immediately delete your file c:\fic.txt. *

23.07.2003: v 3.1.1

- Changed the way destruction is done, as NWServer couldn't be stopped on some computers (have to reboot)

- New function callable from NWN: ODBC!NWNX!VERSION returns the version of NWN-MySQL (i.e.: "ODBC311")

* 21.07.2003: v 3.1.0

- Changed the way initialization is done, as it didn't work on some computers (NWServer didn't start)

* 16.07.2003: v 3.0.9

- Added more detailed error messages in ODBC version of nwnx.dll.

- Added a new parameter: Debug, that will put detailed information on each transaction in the logfile.

* 14.07.2003: v 3.0.8

- Changed the way initialization is done, as it seems to involve problems in some cases.

* 08.07.2003: v 3.0.7

1. Now includes an ODBC version of nwnx.dll. This version will have exactly the same behavior as its MySQL counterpart, simply without the performance boost due to the use MySQL API won’t be here. So: same logs and same added functions as in MySQL. It means also that all the added specific functions included in aps_include2.nss and in update_aps_include.txt CAN now be used, even with Access or Oracle for instance. As ODBC has its own configuration process, the [MySQL] part of the configuration file is ignored with the ODBC version. With those 2 versions (ODBC and MySQL) of the dll, you can now very easily do comparison of the performance with ODBC and MySQL API. Please send me any result you may get for the gain of performance between both versions. Also if you have some comparison between different ODBC databases, those are very welcome.

2. Timing.txt format has been changed. Better erase or rename your existing timing.txt before first using the V3.0.7 version, in order to get better display.

3. With this version come also some optimizations accessible to Unix users.

* 07.07.2003: v 3.0.6

1. Finished translation of remaining French messages into English.

2. Configuration file is now local (don’t have to be located in Windows directory anymore)

3. Documentation much more complete, and all packed into a single HTML file - easier to read. Also includes a short example of optimised data access code.

4. NWNX3.exe renamed into NWN-MySQL.exe

5. Now includes two new parameters in configuration file:

1. Priority. Can be used to fix priority of NWServer.exe (Warning: don’t mess with this parameter if you don’t really know what you’re doing.)

2. OtherServerParam : Can store any additional parameter that you want to put on the NWServer.exe command line. Please only use it for the parameters that are not already explicitly in the NWN-MySQL configuration file.

(check this link for the description of NWServer.exe command line: http://nwn.bioware.com/builders/winserver3.html )

6. Now also includes a new optimised version of GetPersistentString and SetPersistentString for those who want to get best possible optimisation with very limited modification in the module and no change in the database.

7. In order to support running multiple NWN servers on a single computer, you can now optionally put the name of the configuration file to be used on the command line of NWN-mysql.exe

Nwn-MySQL .\AltServer.ini

Note: you should either provide a full path to the configuration file, or it will be searched into Windows directory. By default, the configuration file is .\nwn-mysql.ini.

* 03.07.2003: v 3.0.5

1. Better documentation,

2. Changed the name into NWN-MySQL, to avoid confusion with official APS/NWNX

3. Added TimeSlice parameter in configuration file.

4. Include aps_include in the package.

* 01.07.2003: v 3.0.4

5. Added all MySQL parameter into the configuration file

6. First public release of NWN-MySQL

* 15.06.2003: v 3.0.3

7. As some experimentations with NWNScript time functions gave very poor results (the function that retrieve millisecond doesn’t work properly), I’ve added a high performance chronometer in NWN-MySQL to help tuning performance of NWNScripts.

8. Allowed further performance increase with a new NWN-MySQL function, that combines an EXEC and a FETCH in a singe command (EXEC_AND_FETCH).

9. Added corresponding functions in aps_include.nss (both in ‘normal’ and optimized ‘local’ form)

* 5.05.2003: V 3.0.2

10. Added a new set of optimized ‘local’ versions for most of aps_include core functions. Those are much faster, as they reduce calls to GetLocalString / SetLocalString to the very strict minimum. Can be used in most cases, only restriction: you have to use the old non-local functions when all transactions related to a MySQL requests are not all in a single .nss file (for instance, Exec in a script from a given .nss file, and the corresponding Fetch, GetData or EatData or whatever from another .nss file).

* 5.05.2003: V 3.0.1

11. Added optimized ‘EatData’ set of functions in aps_include. This significantly improve speed and ease of use when you have several data to read after a single request.

* 12.04.2003: V 3.0.0

12. nwnx.dll completely rewritten to directly use MySQL API instead of ODBC, for better performance

13. Several bug fixes, new logs…

* 16.03.2003: Integration of the APS/NWNX 2.0.2 into my tools

* 17.02.2003: Experimentation and integration of APS/NWNX into my own monitoring tool.

* Jan. 2002: Added several text and binary log files, to store information about the frequentation and usage of the Server. Used to design a heuristic system that reduce lag of the server, restarting it when needed. My server – FastFrench – started to hit 64 players regularly from that time.

* Dec. 2002: Added GameSpy protocol usage in the monitoring tool

* Nov. 2002: After experimenting all the existing solution, I decided to start my own monitoring tool to keep my NWN Server up during long period with no human intervention.

License

license.txt

F.A.Q.

1/ What is NWN-FF?

It’s a set of tools that is specially designed to run large Persistent Worlds on a Neverwinter Nights server, with very fast persistent data access and some nice added functionalities.

2/ I’m currently using APS/NWNX2 on my server. How can I easily switch to NWN-FF?

The easiest way to switch is simply to put all appropriate files in NWN directory (Check Here) and edit the configuration file properly. You don’t need to change anything in your module or your database.

3/ Do I need APS/NWNX2 to use NWN-FF?

APS/NWNX2 may be needed in the following cases:

· Unix/Linux: For Unix servers, there’s only a Beta2 version of APS/NWNX2 available. NWN-FF provides no binary files for Unix, only some script optimisations.

· Win95/98/Me: the monitoring tools (NWN-MySQL.exe, NWN-NoDB.exe or NWN-NoDLL.exe) won’t run on those OS. You have to get NWNX2.exe from APS/NWNX package. All other parts of NWN-FF package can be used with Windows 95/98/Me.

In all other cases, you can directly start with NWN-FF, as explained in: NWN-FF Installation and configuration.

With the version 4, it should in fact be much easier to start directly with NWN-FF than trying to start with APS/NWNX2, at least if you’re using Windows and MySQL.

4/ I’m running a Linux (or other Unix) server, can I use NWN-FF?

Thanks to PlasmaJohn, starting with version beta 5.1-pre4, the Unix version of APS/NWNX 2 now partially support NWN-FF extended set of functions. You can get it here: http://sourceforge.net/projects/apsnwnx/

So, even if NWN-FF binaries are only provided for Windows Server, by using this last version of APS/NWNX 2 for Unix, you can use a large port of NWN-FF scripts (NWN_FF.erf) and be compatible with most NWN-FF products .

If you’re running APS/NWNX 2 Unix version 5.1, then you need to config NWN-FF this way:

In ff_inc_options, set

FF_UNIX = 1

FF_USING_NWN_SPEECH = 0

FF_SYNCHRONIZE_TIME = 0

Those two last functionalities are not currently supported in APS/NWNX 2 Unix v 5.1.

Also, the following functions won’t work with Linux:

int SQLGetTime() // Gives the number of micro-seconds since NWServer started

string SQLGetVersion() // Returns version string for NWN-MySQL

int SQLGetRLDate() // Returns the number of second since january 1st 2001 (in RL world)

void SQLSetIGDate()

And the NWNX!XXXX NWN-FF specific functions won’t work either (TIMER, RUN, VERSION, RLDATA…).

Also, you won’t benefits of the ease of use provided by NWN-FF (like automatic creation of the database, Server statistics and all advanced NWN-FF features provided by the binary files won’t be avalaible).

But those missing functions are still pretty limited, and you can use what is the main strength of NWN-FF: very fast and extended set of functions for MySQL database. Please report your results in NWN-FF guild if you’re doing some testing with Linux.

5/ My Character were rejected, why?

Coming with NWN-FF 4.0.13, you have a quick and dirty option to fix this in most cases: set the FF_NO_BAN to 1 in ff_inc_options.nss. I do not advise to fix this problem this way, as you should better try to understand WHY your character is banned. If you want to fix that the clean way, then carefully read what follows…

If you’re rejected, please do the following, in that order:

ü Make sure the server is started since more than 60 secondes (or GDelayStart value, if you changed it in the global table)

ü Make sure you're not rejected for some other reason, not related with NWN-FF (password, IP or key BAN...)

ü Check the 'idplayer' table: write down the Id value for your PC, and check if Ban is 1 (if it is, you can put it to 0 and remove your Id from deleted table). The Id will be needed as a key for most of the other tables.

A/ I can’t find my character in the table idplayer

If you can't find your character in this idplayer table, then you're PC has been rejected for one of those reasons:

A1/ MySQL (or the database + ODBC) is not properly running: either MySQL is not installed, or MySQL server is not running. In this case, you'll have the following message in logs.0\nwserverLog1.txt log file: "MySQL Database is not available. Check if MySQL server is running and configuration file properly set."

A2/ NWN-FF is not setup properly: some dll are missing, or your some parameters are wrong in your configuration file. In this case, you'll have the following message in logs.0\nwserverLog1.txt log file: "MySQL Database is not available. Check if MySQL server is running and configuration file properly set."

A3/ you're rejected before NWN-FF can 'see' you. Check the following Ban lists in nwnplayer.ini:

[Banned Ips]

[Banned Players]

[Banned CD Keys]

A4/ make also sure that your character is not rejected because of legal chararacter or IRL check boxes are checked in NWServer.

B/ I can find your character, and can see that Ban is set to 1.

That means that for some reason NWN-FF rejected your character. You can find the reason into different other tables: using the Id of your character, check the table 'log'. It will tell you why your character has been rejected. If you want to allow your character to login, then set the Ban value at 0, and make sure that you removed his Id from the 'deleted' table (if you can find it in it, just delete the row). Possible reasons include: name already used for another PC, bad name, character unused for a long time, character were banned by a DM, you’re playing a cleric or a paladin but set no Deity…. Most of those features can be disabled in FF_inc_options.nss script.

C/ I can find your character in IdPlayer table, and can see that Ban is set to 0.

It means that NWN-FF did probably not reject your PC. Still check log table to see if you can find some explanation, and also NWServer log files.

NWN-FF version 4.0.4 changes a little bit the default behavior, so that rejection won't happen so often with default parameters (you have to activate the proper options in ff_inc_options.nss to get the advanced options activated in version 4.0.3).

6/ How can I detect that a dead PC says something?

Here is how to do it starting with NWN-FF V4.0.5, using NWNx_FFSpeech.dll:
1/ In ff_inc_options, set FF_SPEECH_DEADCANSPEAK to 0
2/ If you want to make something different depending on the channel used, set FF_SPEECH_GETCHANNEL to 1 in ff_inc_options,
3/ In ff_inc_server, edit the function ff_TalkingDead to do what you want: this function is called each time a dead character is talking. The iCanal parameter will always be 0 if FF_SPEECH_CHANNEL is set to 0. Otherwise, possible values are defined in ff_include

7/ I’ve downloaded MySQL, but what do I do next?

Many helps exist on the web to learn how to install and configure MySQL. So here are a few link that better explain it than I probably could (select the link you prefer, no need to use them both):

Official MySQL doc: http://dev.mysql.com/doc/mysql/en/Windows_installation.html

Alternative: http://www.devside.net/web/server/windows/mysql-bin

If you don't know what to select, I suggest you start MySQL as a service (if you're using NT/2000 or XP) and select mysqld-opt version.

Also, you don't have to bother with accounts, passwords, database creation, table creation, ODBC... all those are automatically handled by NWN-FF.

After this installation of MySQL, just follow the instructions provided in this documentation here. Should really be very simple to start with it, at least I've designed it to be as easy as possible.

8/ How do I incorporate the ff_on_mod_load on my module on enter event? I already have a code on there.

The easier way is probably to call ExecuteScript(“ff_on_mod_load”, OBJECT_SELF); just at the beginning of your main() function, after the {

Void main()

{

ExecuteScript(“ff_on_mod_load”, OBJECT_SELF);

…. //Your existing code continues here

The same applies for all the other events. Doing it this way will make the upgrade with new versions of NWN-FF a breeze.

9/ Can I use MySQL 4.1 version with NWN-FF?

Yes. You just have to take the file libmySQL.dll usually in C:\MySQL\bin directory once you’ve installed MySQL 4.1, and overwrite the file libmySQL.dll that is in your NWN main directory (where you put NWN-MySQL.exe and NWN-MySQL.dll).

Starting with NWN-FF version 4.0.13, MySQL 4.1 is fully supported and becomes the recommended version of MySQL you should use.

10/ My server restarts from time to time when there is no player

You may try the following, in this order (try again after each step):

è 1/ in configuration file, set bModuleFeedBack = 1 and WithAdvancedHeuristics=1

è 2/

Either you put this option to 0, or make sure the you keep some minimum NWN-FF activity during each time slice (Please check bModuleFeedBack option for more details).

11/ When I log with some characters, they are not properly teleported back to their location when they last leaved.

Make sure that each area has a different tag in your module.

12/ My server restarts every few minutes, before my module has a chance to be fully loaded

1/ Increase InitialDelayS value. It’s the time, in seconds, that the module needs to fully initialize. For example InitialDelayS=600 means that the monitoring tool will do no control during an initial period of 10 minutes after the NWN server starts.

2/ If your server still restarts after this InitialDelayS, then try to set bModuleFeedBack=0

13/ How can I ask the monitoring tool NOT to restart the server periodically?

Simply set a very high value for MaxCounter. For example MaxCounter = 2000000000 means practically to restart only once every 60 years… if it doesn’t crash before.