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 p