this tutorial will going to evolve with versions of NWNX4

Version of this tutorial: 1.06a (this tutorial will going to evolve with versions of NWNX4)
The purpose of this document is to help a beginner to install all the elements necessary to use
NWNX4. Throughout this tutorial, we will explain you for what nwnx4 is used, how to install a
MySQL database on your computer, how to consult the data, wrote by NWNX4, in your database
with a graphic interface.
We will next show you how to install NWNX4 in your computer and how to integrate it in a
module of NWN2.
In the future, we will describe you the various tables of NWNX4 (for now, NWNX4 is in version
alpha and does not create a table yet), we will explain you how to use the functions of NWNX4
with examples.
In a more advanced part, of this tutorial, we will explain you how to install an apache server with
php and mysql to allow you an access to your database on your Web site. We will also explain you
how to create your own tables to allow you to add personal functionalities to your module.
This tutorial was created by Elleslande (caloup on nwnx.org).
Member of the Babel Project and Elleslande Team
1
I.
Presentation of NWNX ..............................................................................................................4
What can we do with NWNX4 ? ...............................................................................................4
But how does it work ?.............................................................................................................6
II Databases ....................................................................................................................................7
1. Installation of MySQL on Windows .........................................................................................7
a. Downloading .......................................................................................................................7
b. Installation ..........................................................................................................................8
c. Setting MySQL.................................................................................................................10
2. Using a Graphical Interface to manage your database.........................................................17
a. Downloading SQLYog .....................................................................................................17
b. Installation of SQLYog....................................................................................................18
c. Setting SQLYog................................................................................................................20
d. Create your own database for NWNX ...........................................................................21
Presentation of SQLYog :........................................................................................................21
How to create your own database...........................................................................................23
III.
Installation of NWNX4 ........................................................................................................25
1. Downloading NWNX4............................................................................................................25
2. What is inside the NWNX4 (version 1.06) pack .....................................................................26
a. Installation of NWNX4 ....................................................................................................26
b. Edit nwnx.ini file ..............................................................................................................27
c. Edit of xp_mysql.ini file...................................................................................................27
d. Create an icon on your desktop to launch NWNX4 with control panel......................28
e. Import “erf” files in your module...................................................................................29
3. Configuration of the NWNX4 elements..................................................................................29
a. database.............................................................................................................................29
b. The scripts.........................................................................................................................30
c. Setting the control panel of the server with nwnx4.......................................................30
1.
2.
Coming soon :
IV. Using functions for database.
IV.1. Tables created by NWNX4.
IV.2. nwnx_sql script
IV.3. How to use NWNX4.
And second: "advanced topics"
Quote:
II.2. Graphical Interface and distant Access.
II.2.1. Installation of an Apache server
II.2.2. Installation of PHP.
II.2.3.Installation of phpMyAdmin.
II.3. What to do for using MySQL with NWNX4.
II.3.1. The database.
II.3.2. User.
2
3
I. Presentation of NWNX
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 tool, Alvis team often felt that some things
are just too limited, in order to successfully run a large persistent world. So they created NWNX for
NWN1. This program allows to connect a database to your module and to stock some information
say as « persistent » in those database. For NWN2, papillon and some people of the community
offer to do a similar tool named NWNX4.
In addition to be offer, the equivalent of what NWNX2 could do for NWN1, NWNX4 will be
easiest to use, easiest to install and easiest to update...
Among the innovations that would be in the final version of, we can notice :
-
An installation program, which makes setting up NWNX very easy for new users.
A web update program. I don’t know actually how it could work but it’s a project to
come
A graphical Interface.
NWNX4 can run as a Windows service.(This function is already in NWNX4 version
1.06)
Support for multiple instances of NWNX4 running multiple servers on the same
computer (This function is already in NWNX4 version 1.06)
New function “nwnx_plugin” : This function allow counting the number of plugin
installed and allow knowing their name, description…
Other principles of the program were kept. In particular, the possibility of creating your own plugin,
which will add functionalities to NWNX4.
At the present time here plugins integrated in the pack of NWNX4 1.06:
-
nwnx_timer : This plugin allow to determine the duration for launching a function, very
practical to optimize scripts
1. What can we do with NWNX4 ?
With NWNX4, it is possible to store persistent variables in the data base 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. The variables being stored in an external base, so it is possible to call them
from the module n°3 even if they were created in the module n°2.
We can also, for example, bind a trunk to a data base to store some material in a permanent way.
Thus even if the module is started again, the trunk will always contain your material!
AlthoughNWN2 has its own basic system of data base, this one can very quickly prove to be
slow…… It was not envisaged to be consulted by several users at the same time thus if you have
many players who come regularly, it is better to use a database like MySQL which it is designed to
be multi transactional. I.e. it can write several things at the same time in the base of data…
4
Among the current uses of NWNX we find:
-
Systems of Persistent trunk
Crafting systems
Table of honour system
Automatic management of treasures system…
You will realize quickly, that in certain cases it is more effective to define elements in a table and to
call them by a request in a script rather than to recreate this table by scripting because each time the
script is launched it will recreate it to produce a result for you..
For example, let us imagine that you set up a system of random treasure. You could to create your
own script like that:
void TagTreasure(int i)
{
string sTag;
switch (i)
{
case 1:
//functions to design the tag of the treasure
break;
case 2:
//functions to design the tag of the treasure
break;
case 3:
//functions to design the tag of the treasure
break;
case 4:
//functions to design the tag of the treasure
break;
case 5:
//functions to design the tag of the treasure
break;
//etc. until 12....
}
return sTag;
}
void main()
{
int i = d12();
string sTagTreasure = TagTreasure(i);
////functions to put the treasure in creature inventory
}
Thus with each time script is engaged the loop switch will be read again… what can make waste of
time…
Or you could create a table order by “id”, with “id” is a UNIQUE and integer starting by 1 to 12.
For each “id” you define a Tag for the treasure. Next you just have to use a script like that:
5
/*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
}
So the interest of NWNX4, in addition to storing persistent variables, would be also to facilitate the
scripting. We could certainly find other uses of NWNX4 but for now, it’s sufficient for me ☺
2. But how does it work ?
In order to establish communication between scripts and the outside world, NWNX intercepts calls
to the NWScript function SetLocalString() and examines the variable name that is passed to this
function. If it begins with the string "NWNX!", NWNX parses the request and stores any resulting
data into the value of that variable, which in turn can be read by a script with GetLocalString().
This is a simple example
void SQLExecDirect(string sSQL)
{
SetLocalString(GetModule(), "NWNX!SQL!EXEC", sSQL);
}
The name of the variable start with NWNX ! so the program will go to read SQL !EXEC that is
corresponding for NWNX4 to “launch a query”. This query would be sSQL…
Since we could launch a request towards the database, we could then store information there, create
tables, update them… Do you understand the principle?
But NWNX4 is not useful to just dialog with a database, in particular with its plugin system, other
functions can be added to it. For example, log’s writing witch allow having some statistics…
You are convinced? Then, here the elements you will need:
- The last version of NWNX4
- A MySQL database (NWNX4 allow to connect to SQLite but we just see MySQL here)
- A graphical interface for “ seeing” what is inside your database.
- NWN2 (of course…)
- That document !
You don’t know how install a base of data? You never installed NWNX before? Thus read what
follows…
6
II
Databases
This chapter will show you how to install a basic database server on your computer, as well as the
way of reaching it using a graphical interface named SQLYog. We will see thereafter, how to create
a new table manually with the graphical interface.
1. Installation of MySQL on Windows
a. Downloading
You could download MySQL on this site :
http://dev.mysql.com/downloads/mysql/5.0.html#downloads
On the left of the page, You can choose the version of MySQL that you which to install. NWNX4
can support version 4.1 and version 5.0. We will going to install version 5.0.
When you have chosen version 5.0, just make a click on “DOWNLOAD” bellow “MySQL
Community Server” (witch is freeware).
The link sends you bellow in the page, in the downloading zone (see picture bellow).
Click on “Download” in front of “windows essential” for downloading the auto installer package
of MySQL.
A message box will going to ask you what do you want :
7
Make “Record”, then the message bow will open this window :
Do 1 click on “Desktop” (on the left), next “Record”.
Downloading is starting…
b. Installation
When downloading is finished, go on the desktop, you should see that :
Make 2 clicks on it for starting the installation…
Windows ask you to confirm :
Click on “Execute”.
8
Make, “NEXT” in the next windows :
Choose “Typical” installation and click on “NEXT” :
In the next windows, just click on “Install” :
After the installation, a window will ask you to register:
9
Choose “Skip Set Up” and click on “NEXT”.
In the next window, notch the box “Configure the MySQL Server now” and choose “Finish”
c. Setting MySQL
When the setting window is open, click on “NEXT”
10
In the next window, choose “Reconfigure Instance” or “Create new Instance” according to if you
or not had already an installation of MySQL present on your computer…
Then click on “Next”.
To have a lot of setting option choose “Detailed Configuration”
Then click on “Next”.
You must, next, choose the purpose of your installation.
11
-
-
If you just want to do some development (many other applications will be run on your
computer) Choose: “Developer Machine”.
If you want to use your computer like a server machine and allow more memory to
MySQL (this should be your case if you want to create a persistent world) choose
“Server Machine”
If your computer is a dedicated server, this mean that few other applications will run
on your computer, choose “Dedicated MySQL Server Machine”. MySQL will take
more memory…
Then click on “Next” and you’ll see this windows :
For NWNX4, we recommend you to choose : “Multifunctional Database” and click on “Next”.
Generally, you don’t have to modify the setting here, just click on “NEXT”.
12
Here, you must choose the maximal number of player you want to have connected in same time.
Generally, you have to click on “Manual Setting” and enter your own number (30 players could be
a reasonable number)
Then click on “NEXT” . The windows bellow will be opened:
Leave the two box notched “Enable TCP/IP Networking” and “Enable Strict Mode”. In “Port
Number” section, enter the port you want that MySQL listen. Default it’s 3306, we recommend
you to leave it at 3306.
Note : For your server to be accessible since external requests to your computer,, you must set your
Firewall so that it authorizes calls Incoming and Outgoing on this port. To know how to configure
your firewall you can consult this site:http://www.portforward.com/routers.htm which gathers a
great number of firewall settings, makes it possible to help you to configure many game. Very
useful!
13
In the next windows, leave “Standard Character Set” then click on “NEXT”.
In the next windows, notch the box “Install As Windows Service” and “Launch the MySQL
Server Automatically” for allowing to the instance of MySQL to automatically launch at starting
of window …
Then, 1 clicks on “NEXT”.
In the next windows, you must create a password for root access to your database. If NWNX4 is on
the same computer than MySQL you’ll need this password to set the nwnx.ini file…
If it is you first installation of MySQL, you’ll certainly saw “Create Security Setting” in place of
“Modify Security Setting” and you just have to give your password and confirm it.
The picture bellow, show the case if you want to modify an installation already existing on your
computer, so you have to give the old password and the new and next confirm it...
14
When you have entering your password, don’t notch the box “Enable root access from remote
machines” unless you put NWNX on another computer than your MySQL server.
Don’t create an anonymous account, for security reason.
Then click on “NEXT”.
Next click on, “Execute” to launch the setting of MySQL instance.
Note: I recommend you to disallow your Firewall for that.
When it’s finished you should see a message that inform you the setting is a success, you just have
to click on “Finish”.
Restart your computer, and make CTRL+ALT+DEL. You should see this window :
15
In processus, control that you have “mysql-nt.exe” in the instance. Your server is ready !
16
2. Using a Graphical Interface to manage your database
In this chapter we will see how to download, install and setting free software called SQLYog, which
makes it possible to have a graphic interface practises to manage your base of MySQL data.
a. Downloading SQLYog
SQLYog is a freeware. You could download it at : http://www.webyog.com/en/
Click on “Download” in the SQLYog Community Edition (freeware). You should be sent to :
1 click on SQLYog Community Edition 5.2 (stable) in the Binaries. A window open, asking you
what you want to do :
Choose “Record”. A new window will open and asking you WHERE you want to record this files :
17
Make one click on “My documents” on the left, next click on “Record”.
When download is finished you should see this window :
Choose “Execute” for launching the installation. If you don’t have this window, go to “My
Documents” and make 2 clicks on the file that you have just downloaded.
If you’re on Windows XP you should see that window. Then click on “Execute”.
b. Installation of SQLYog
After you have click on “Execute”, you should see this window :
18
Just click on “NEXT” button.
In this page about the licence, choose “I accept the term…” and click on “NEXT”.
The windows bellow, ask you where you want to record the program on your computer:
Choose a destination directory, and click on “Install”.
19
Then click on “NEXT”.
Click on “Finish” for finishing the installation.
c. Setting SQLYog
20
When you’re opening for the first time SQLYog, you must set to the program to witch database you
want to connect you.
For that, make 1 click on “New”.
Enter a name for the connexion. It is just about a means of differentiating a connection for a base or
another, it is neither the identifier of connection, nor the password…
Next, click on “OK”. SQLYog will open a connexion windows to the database (see picture bellow)
You must enter those settings :
-
-
MySQL Host Address : It is about the address on the network of your server. You can,
either to return an address IP or an address URL. If the server is on the same computer
that SQLYog, you must put “localhost”.
Username : It’s the username, corresponding to “id” of the user. For example : “root”
Password : It’s the password associate to Username
Port : it’s the port number using by MySQL. Default :3306. (see chapter before)
Database : It’s the name of the database witch one you want to connect to. If you don’t
put anything here, SQLYog will show the entire database you have on the server.
When you’ve finished entering the information, you could test them in clicking on “Test
Connexion”.
When settings are correct, click on the “Save” button for saving…
d. Create your own database for NWNX
Presentation of SQLYog :
Warning, it acts to create your base of data here. We do not create « tables » that should be in there
will be automatically created by the stable version of NWNX4 (actually in the alpha version there
isn’t any table, it’s normal).
On the other hand we will see thereafter the instructions to create independent news of them so that
you integrated your personal parameters into it.
21
Click on the “Connect” button
SQLYog is opening :
A
B
C
D
Part A :
The data bases appear here. By default MySQL creates the bases
information_schema and mysql.
To have detail on the columns of a table, made 1 click on the sign + of the table and under small
“Column”. For example
22
Part B : It is here that we can write requests for manually acting on the database. The subject of this
tutorial not being to learn language SQL, I offer to you to go on these sites for more information:
-
SQL facile (French) : http://www.toutestfacile.com/phpinit.php?tef_site=sql&chap=sql1
Manitou SQL (French) : http://langagesql.free.fr/accueil.html
W3school (English) : http://www.w3schools.com/sql/sql_intro.asp
Part C : In this part you can choose what you want to be shown on part D. You have the choice
between “Result” for showing query results, “Messages” for seeing mistake messages, “Table
Data” for seeing the content of the table (this what you should use the most), “Object” For
having details about the property of the columns... At least, “History” for seeing last event on the
table.
Part D : The content of this part depend on the choice you’ve made on part C. Generally, to consult
or modify a table of your database, you should select on part C “Table Data” and you could see the
content of the table in part D. For example, this is what is inside “pwdata” table in an
nwn1 module:
How to create your own database
Make 1 right click with the mouse on root@localhost (the name depends on the account using to
connect to the database):
Make 1 click on “Create Database”
Give a name to your database. For example, “nwn2”. Next, click on “Create”
It’s the name you should use to set the MySQL.ini file of NWNX4.
23
You should obtain something like that....
Actually don’t have table is empty, it’s normal. In this version of NWNX4 the database aren’t
created. But the stable version of NWNX4 will create the table automatically. How to create other
table is an advanced subject, we will see in the « advanced topic ».
In chapter 4, we will show you the table created by NWNX4 and explain you what are their
purpose…(when the version of nwnx could allow this).
24
III. Installation of NWNX4
1. Download NWNX4
You can download NWNX4 on this site : http://www.nwnx.org/index.php?id=nwnx4
Just make 1 click on the link:
Note : If this page is not posted while clicking on the bond, it is that it is necessary that you are
recorded on the site. In this case there, go on the forum and record.
In the next window, click on «Record” :
Another window open, allowing you to choose where you want to record the NWNX4 package.
Create a repertory witch name is « NWNX4 » for example and click on “Record”.
When downloading is finished, click on “Open the repertory” :
In the next windows, make on right click on the compressed file and choose “Extract here” :
You should see, next, all the element of NWNX4…
25
2. What is inside the NWNX4 (version 1.06) pack
Here are the files that we should have :
-
NWNX4_Controler.exe, it’s the program witch will launch nwnserver
2 dlls of "hook" those files establish the communication between nwn2 and
NWNX4_Controler. (madChook.dll and NWNX4_Hook.dll)
Some dlls of plugins, actually there are 3 files :
o xp_mysql.dll : plugin for using MySQL
o xp_sqlite.dll : plugin for using SQLite
o xp_time.dll : plugin for timer (more infos here)
-
3.ini files
• nwnx.ini : For NWNX4 settings
• xp_mysl.ini : Set the plugin for MySQL
• xp_sqlite.ini : Set the plugin for SQLite
Note : Here we’ll speak only about MySQL. We recommend you to rename the files “xp_sqlite.dll”
and “ xp_sqlite.ini”. For example: “ off_xp_sqlite.dll” and “ off_xp_sqlite.ini”.
-
3.erf files contain "include" type script
•
•
•
nwnx_include.erf : allow to obtain some information about plugin
nwnx_time.erf : contain some scripts for "timer" function
nwnx_sql.erf : contain a script with several functions for managing access to
database
a. Installation of NWNX4 files
First thing to do : Copy “MadCHook.dll” file in the root repertory of your NWN2 installation
(keep one copy with the other files of nwnx4).
26
b. Edit nwnx.ini file
Comments in the nwnx.ini file are very easy to understand so i don’t figure to explain all of the
parameters but you must enter those parameters:
# Path to NWN2 installation (where nwn2server.exe is located)
# no default. You really have to specify it, currently.
nwn2 = D:\Games\nwn2
Replace “D:\Games\nwnx2” by the root directory of NWN2 on your computer.
To know this directory do 1 right click on the NWN2 launcher on your desktop, choose
“Property” and in the part “Target”, select all the string before “NWN2Launcher.exe”. You can
copy/paste those strings to your nwnx.ini :
# Command line parameters to start the server with
# default: no parameters
parameters = -module nwnx
Here, you must replace “nwnx” by the name of your module without its extension. For example if
your module’s name is “truc.mod”, you should write : “-module truc”
c. Edit of xp_mysql.ini file
class = SQL
server = localhost
user = nwn
password = nwn
schema = nwnx
;MaxLogSize = 512 ; in KByte
;LogLevel = 2 ; 0=nothing, 1=only errors, 2=everything
You should set the parameters like that :
•
server = IP Address or URL of your server. If your server is on the same computer than
nwnx, you should put “localhost”
27
•
•
•
user = It’s the username for your database access. If your server is on the same computer
than nwnx, you should put “root”.
password = It’s the password, you have defined when you have installed MySQL.
schema = Here is the name of your database
When you have done, nwnx should be able to connect to your database and launch the module.
Warning, think about to set your firewall…
d. Create an icon on your desktop to launch NWNX4 with control panel
Go to the directory where you have nwnx4 files, does 1 right click on NWNX4-Controller.exe and
choose “Send to” “Desktop (create a short cut)” :
Next, on the short cut, does 1 right click with the mouse and select “Properties”.
In the “Target” part adds “-interactive” after “NWNX4_Controller.exe” (with a space between
them) :
If, you make 2 clicks on the short cut, you’ll see the control panel appear:
28
e. Import “erf” files in your module.
-
Open the toolset and your module.
Do 1 click on “File” and “Import”
Select the file to import and click to “Open”.
Do the same for all the “erf”
You have finished the installation of NWNX4! Congratulation!
3. Configuration of the NWNX4 elements
You have installed NWNX4, it’s ready to work but you have other setting to do…
a. database
While version 1.06 of NWNX4 doesn’t create any table in your database, using NWNX4 functions
could crash your server if you do not create “pwdata” in your MySQL database.
So for the moment you should create a script in the toolset. Name it “nwnx_buildtable” for
example. Put this on the script :
#include "nwnx_sql"
void main()
{
SQLExecDirect("CREATE TABLE IF NOT EXISTS pwdata (player varchar(64) NOT
NULL default ' ',tag varchar(64) NOT NULL default ' ',name varchar(64) NOT NULL default
' ',val varchar(64),expire smallint(5) unsigned default NULL,last timestamp(14) NOT
NULL,PRIMARY KEY (player,tag,name)) TYPE=MyISAM;");
}
Note : I wrote this for MySQL 5.0 it’s the reason there isn’t any ‘ around table name…
Next, you will create a script named “OnModuleLoad” that you must place in the event of your
module name OnmoduleLoad. Put this on the script :
/*Script witch will be launch on module load*/
29
void main()
{
ExecuteScript("nwnx_buildtable",OBJECT_SELF);
ExecuteScript("x2_mod_def_load",OBJECT_SELF);
}
So when you’re launching you’re module, it create the pwdata table if it isn’t existing already.
b. The scripts
For using NWNX4 functions in your scripts, you must put this line on the beginning of your scripts
(if they are using NWNX4 function only !)
#include "nwnx_sql"
That will indicate to the compiler of NWNScript of initially reading script “nwnx_sql” where the
functions of NWNX4 are placed
c. Setting the control panel of the server with nwnx4
The control panel opened by NWNX4, launch your module but has default parameters…:
If you want to put automatically your own parameters at the launch of the control panel, you should
modify this line in nwnx.ini :
parameters = -module nwnx
Options are here : http://nwn.bioware.com/builders/winserver3.html
So you could write :
parameters = -module Elleslande2 -servername "[FR]Elleslande 2[PW]" -gametype 3
So when NWNX4 launch the control panel, you don’t have to modify the settings
30