logo logo

You are here: Documentation - About NWNX4

NWNX4 Documentation

This documentation is based on the works of caloup, and has been rewritten by Papillon in June 2007.

If you have questions or suggestions regarding this manual, please give us your feedback in the forum.

About NWNX

The NeverWinter Nights Extender (NWNX) is a program that has the power to push limits on what you can do with NWN and its integrated script language.

While NWN2 and the toolset are complex and powerful tools, we often felt that some things are just too limited in order to successfully run a large persistent world. So we created NWNX for NWN1. This program allows to connect a database to your module and to store persistent information in it. For NWN2, we planned to offer even more features.

In addition to what NWNX2 could do for NWN1, we wanted NWNX4 to be easier to use, easier to install and easier to update.

Among the innovations that should be in the final version of are :

Other principles of the program were kept. In particular, the possibility of creating plugins in C++, which can be used to add even more functionality to NWNX4.

At the present time these plugins are available for NWNX4:

1. What can I do with NWNX4 ?

With the database plugins of NWNX4, it is possible to store persistent variables in a database, which can then be recovered from one module to another. For example, if you want to divide your persistent world into 3 or 4 modules and store the variables in an external database, it would be possible to recall them from the module n°3 even if they were created in the module n°2. This works even if both modules are running at the same time.

You can also, for example, bind a chest to a database and store items in a permanent way. Thus even if the module is restarted, the chest will be able to load the items from the database again and the player will not even notice the server has reset in the meantime.

Although NWN2 has its own basic database, it can very quickly prove to be impractical… it was not designed to be used by several servers at the same time, which limits how big your world can grow if you have to stick to one module. With NWNX, you can not only access the database simultaneously, but you can also use the power of SQL to make your data storage more elegant, flexible, and reliable.

Examples for using NWNX:

 
You will quickly realize that in certain cases it can be more efficient to just load something from the database with a single command, rather than making complex calculations in NWScript.

For example, let us imagine that you set up a system of random treasure. You could create your own script like this:

void TagTreasure(int i)
{
    string sTag;
    switch (i)
    {
              case 1:
                          //functions to create the tag of the treasure
                          break;
              case 2:
                          //functions to create the tag of the treasure
                          break;
              case 3:
                          //functions to create the tag of the treasure
                          break;
              // and so on until 12....
    }
    return sTag; 
}

void main()
{
    int i = d12();
    string sTagTreasure = TagTreasure(i);

   // functions to put the treasure in creature inventory                                                           
}

Thus each time the script is run the switch will be executed again… which can be a waste of time and makes the code somewhat long and hard to read.

Alternatively, you could create a table with an “id” column, where “id” is a unique integer starting from 1 to 12. For each “id” you define a Tag for the treasure. Next you just have to use a script like this:

/*Random treasure Script */
#includes "nwnx_sql"
void main()
{
    int i = d12();
    string sSQL = "SELECT sTag FROM treasuretable WHERE id ="+IntToString(i)+";
    SQLExecDirect(sSQL);
    if (SQLFetch() == SQL_SUCCESS)
        string sTagTreasure = SQLGetData(1);

    // functions to put the treasure in creature inventory    
}

This is just a small example to illustrate the point here. We could certainly find other uses for NWNX4, but for now, this should give you an idea of what it is all about.

2. How does it work ?

Note: This chapter explains how NWNX4 works in the background. You can safely skip it and then come back later if you want to see how it works under the hood.

In order to establish communication between scripts and the outside world, NWNX attaches itself to certain scripting functions and manipulates their results. It thus creates a well defined interface between the closed NWN world and countless external systems, which can be used to do things like accessing SQL database servers, use other programming languages, connect to web services, and many others.

In the early versions of NWNX4, I used the old method of intercepting calls to the SetLocalString() function. Now that Obsidian Entertainment added the NWNX specific scripting functions, life got a bit easier and NWNX got more elegant.

In order to send a command to a NWNX plugin, you can issue a simple call like this:

NWNXSetString("TIME", "START", "MyTimer_1", 0, "");

The first parameter is the plugin's name (TIME), the second parameter is generally the command the plugin should execute (START), and the next few parameters depend on the actual plugin implementation. In this example, a timer named MyTimer_1 is started. The last two parameters are not needed for this call and are set to default values (which do not matter).

Because it would soon get tedious to remember the exact parameters of every plugin, there is usually an include file that makes it really easy to use a plugin's functions, e.g. the same command can also be called like this:

StartTimer(GetModule(), "MyTimer_1");

NWNX4 is not just useful for database access, as this example demonstrates.. With it's plugin system, other functions can be added to it. For example, the Timer plugin shown above measures times like a highly accurate stopwatch, which can be used to optimize your scripts.

Next steps

If you have read that far, you will probably want try NWNX now...

Here are the elements you will need:

 
You don’t know how install a database ? You never installed NWNX before? So read what follows…

Table of contents - Next: Installing NWNX