Version of this tutorial: 1.06a (this tutorial will going to evolve with versions of NWNX4)

Transcription

1 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

2 I. Presentation of NWNX What can we do with NWNX4? But how does it work?...6 II Databases Installation of MySQL on Windows...7 a. Downloading...7 b. Installation...8 c. Setting MySQL 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 NWNX Downloading NWNX What is inside the NWNX4 (version 1.06) pack...26 a. Installation of NWNX 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 Configuration of the NWNX4 elements...29 a. database...29 b. The scripts...30 c. Setting the control panel of the server with nwnx 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 3

4 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

5 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 } 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

6 /*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

7 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 : 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

8 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

9 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

10 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

11 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

12 - 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

13 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 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: which gathers a great number of firewall settings, makes it possible to help you to configure many game. Very useful! 13

14 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

15 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

16 In processus, control that you have mysql-nt.exe in the instance. Your server is ready! 16

17 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 : 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

18 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

19 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

20 Then click on NEXT. Click on Finish for finishing the installation. c. Setting SQLYog 20

21 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

22 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

23 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) : - Manitou SQL (French) : - W3school (English) : 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

24 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

25 III. Installation of NWNX4 1. Download NWNX4 You can download NWNX4 on this site : 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

26 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 : - 3.ini 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) 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

27 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

28 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

29 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

30 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 : 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