Hercules Wiki - User contributions [en]

Generate HPM Hook with HPMHookGen.pl

2016-09-16T18:59:11Z

Haru: Marked as outdated. The correct way to do this is to use the Makefile (make hooks).

{{outdated}}

== Generate HPM Hook on windows. ==

First you need to download and install Doxygen and Perl.

Doxygen: http://www.stack.nl/~dimitri/doxygen/download.html

Perl: http://www.activestate.com/activeperl/downloads

1. Run "Doxygen GUI frontend"

2. Click on "File" -> "Open"

3. Go on your Hercules folder -> "tools" -> "HPMHookGen" and select "doxygen.conf"

4. Now in the interface you will see Run, go on it.

5. Just click on "Run doxygen" and just close it.

6. Go on the "HPMHookGen" folder then run HPMHookGen.pl

{{obsolete|type=script command|when=long time ago}}

== Syntax ==
* [[menu]] "<option_text>",<target_label>{,"<option_text>",<target_label>,...};

== Description ==
This command will create a selectable menu for the invoking character. Only one menu can be on screen at the same time.

Depending on what the player picks from the menu, the script execution will continue from the corresponding label (it's string-label pairs, not label-string).

Options can be grouped together, separated by the character ':'.
menu "A:B",L_Wrong,"C",L_Right;

It also sets a special temporary character variable @menu, which contains the number of option the player picked. (Numbering of options starts at 1.) This number is consistent with empty options and grouped options.

== Examples ==
[[menu]] "A::B",L_Wrong,"",L_Impossible,"C",L_Right;
L_Wrong:
// If they click "A" or "B" they will end up here
// @menu == 1 if "A"
// @menu == 2 will never happen because the option is empty
// @menu == 3 if "B"
L_Impossible:
// Empty options are not displayed and therefore can't be selected
// this label will never be reached from the menu command
L_Right:
// If they click "C" they will end up here
// @menu == 5

If a label is '-', the script execution will continue right after the menu command if that option is selected, this can be used to save you time, and optimize big scripts.

[[menu]] "A::B:",-,"C",L_Right;
// If they click "A" or "B" they will end up here
// @menu == 1 if "A"
// @menu == 3 if "B"
L_Right:
// If they click "C" they will end up here
// @menu == 5

Both these examples will perform the exact same task.

If you give an empty string as a menu item, the item will not display. This can effectively be used to script dynamic menus by using empty string for entries that should be unavailable at that time.

You can do it by using arrays, but watch carefully - this trick isn't high wizardry, but minor magic at least. You can't expect to easily duplicate it until you understand how it works.

Create a temporary array of strings to contain your menu items, and populate it with the strings that should go into the menu at this execution, making sure not to leave any gaps. Normally, you do it with a loop and an extra counter, like this:

[[setarray]] @possiblemenuitems$[0],<list of potential menu items>;
[[set]] @j,0; // That's the menu lines counter.

// We loop through the list of possible menu items.
// @i is our loop counter.
[[for]]( [[set]] @i,0; @i<[[getarraysize]](@possiblemenuitems$) ; [[set]] @i,@i+1 )
{
// That 'condition' is whatever condition that determines whether
// a menu item number @i actually goes into the menu or not.

[[if]] (<condition>)
{
// We record the option into the list of options actually available.

[[set]] @menulist$[@j], @possiblemenuitems$[@i];

// We just copied the string, we do need it's number for later
// though, so we record it as well.

[[set]] @menureference[@j],@i;

// Since we've just added a menu item into the list, we increment
// the menu lines counter.

[[set]] @j,@j+1;
}

// We go on to the next possible menu item.
}

This will create you an array @menulist$ which contains the text of all items that should actually go into the menu based on your condition, and an array @menureference, which contains their numbers in the list of possible menu items. (Remember, arrays start with 0.) There's less of them than the possible menu items you've defined, but the menu command can handle the empty lines - only if they are last in the list, and if it's made this way, they are. Now comes a dirty trick:

// X is whatever the most menu items you expect to handle.
[[menu]] @menulist$[0],-,@menulist$[1],-,....@menulist$[<X>],-;

This calls up a menu of all your items. Since you didn't copy some of the possible menu items into the list, it's end is empty and so no menu items will show up past the end. But this menu call doesn't jump anywhere, it just continues execution right after the menu command. (And it's a good thing it doesn't, cause you can only explicitly define labels to jump to, and how do you know which ones to define if you don't know beforehand which options will end up where in your menu?) But how do you figure out which option the user picked? Enter the @menu.

'''@menu''' contains the number of option that the user selected from the list, starting with 1 for the first option. You know now which option the user picked and which number in your real list of possible menu items it translated to:

mes "You selected "+@possiblemenuitems$[@menureference[@menu-1]]+"!";

* @menu is the number of option the user picked.
* @menu-1 is the array index for the list of actually used menu items that we
made.
* @menureference[@menu-1] is the number of the item in the array of possible menu items that we've saved just for this purpose.

And @possiblemenuitems$[@menureference[@menu-1]] is the string that we used to display the menu line the user picked. (Yes, it's a handful, but it works.)

You can set up a bunch of 'if (@menureference[@menu-1]==X) goto Y' statements to route your execution based on the line selected and still generate a different menu every time, which is handy when you want to, for example, make users select items in any specific order before proceeding, or make a randomly shuffled menu.

Kafra code bundled with the standard distribution uses a similar array-based menu technique for teleport lists, but it's much simpler and doesn't use @menu, probably since that wasn't documented anywhere.

See also '[[select]]', which is probably better in this particular case. Instead of menu, you could use 'select' like this:

[[set]] @dummy, [[select]](@menulist$[0],@menulist$[1],....@menulist$[<X>]);

For the purposes of the technique described above these two statements are perfectly equivalent.

== See Also ==
* [[Menus]]

[[Category:Script Command]]

{{obsolete|type=script command|when=r9788}}

== Syntax ==
* [[menu]] "<option_text>",<target_label>{,"<option_text>",<target_label>,...};

== Description ==
This command will create a selectable menu for the invoking character. Only one menu can be on screen at the same time.

Depending on what the player picks from the menu, the script execution will continue from the corresponding label (it's string-label pairs, not label-string).

Options can be grouped together, separated by the character ':'.
menu "A:B",L_Wrong,"C",L_Right;

It also sets a special temporary character variable @menu, which contains the number of option the player picked. (Numbering of options starts at 1.) This number is consistent with empty options and grouped options.

== Examples ==
[[menu]] "A::B",L_Wrong,"",L_Impossible,"C",L_Right;
L_Wrong:
// If they click "A" or "B" they will end up here
// @menu == 1 if "A"
// @menu == 2 will never happen because the option is empty
// @menu == 3 if "B"
L_Impossible:
// Empty options are not displayed and therefore can't be selected
// this label will never be reached from the menu command
L_Right:
// If they click "C" they will end up here
// @menu == 5

If a label is '-', the script execution will continue right after the menu command if that option is selected, this can be used to save you time, and optimize big scripts.

[[menu]] "A::B:",-,"C",L_Right;
// If they click "A" or "B" they will end up here
// @menu == 1 if "A"
// @menu == 3 if "B"
L_Right:
// If they click "C" they will end up here
// @menu == 5

Both these examples will perform the exact same task.

If you give an empty string as a menu item, the item will not display. This can effectively be used to script dynamic menus by using empty string for entries that should be unavailable at that time.

You can do it by using arrays, but watch carefully - this trick isn't high wizardry, but minor magic at least. You can't expect to easily duplicate it until you understand how it works.

Create a temporary array of strings to contain your menu items, and populate it with the strings that should go into the menu at this execution, making sure not to leave any gaps. Normally, you do it with a loop and an extra counter, like this:

[[setarray]] @possiblemenuitems$[0],<list of potential menu items>;
[[set]] @j,0; // That's the menu lines counter.

// We loop through the list of possible menu items.
// @i is our loop counter.
[[for]]( [[set]] @i,0; @i<[[getarraysize]](@possiblemenuitems$) ; [[set]] @i,@i+1 )
{
// That 'condition' is whatever condition that determines whether
// a menu item number @i actually goes into the menu or not.

[[if]] (<condition>)
{
// We record the option into the list of options actually available.

[[set]] @menulist$[@j], @possiblemenuitems$[@i];

// We just copied the string, we do need it's number for later
// though, so we record it as well.

[[set]] @menureference[@j],@i;

// Since we've just added a menu item into the list, we increment
// the menu lines counter.

[[set]] @j,@j+1;
}

// We go on to the next possible menu item.
}

This will create you an array @menulist$ which contains the text of all items that should actually go into the menu based on your condition, and an array @menureference, which contains their numbers in the list of possible menu items. (Remember, arrays start with 0.) There's less of them than the possible menu items you've defined, but the menu command can handle the empty lines - only if they are last in the list, and if it's made this way, they are. Now comes a dirty trick:

// X is whatever the most menu items you expect to handle.
[[menu]] @menulist$[0],-,@menulist$[1],-,....@menulist$[<X>],-;

This calls up a menu of all your items. Since you didn't copy some of the possible menu items into the list, it's end is empty and so no menu items will show up past the end. But this menu call doesn't jump anywhere, it just continues execution right after the menu command. (And it's a good thing it doesn't, cause you can only explicitly define labels to jump to, and how do you know which ones to define if you don't know beforehand which options will end up where in your menu?) But how do you figure out which option the user picked? Enter the @menu.

'''@menu''' contains the number of option that the user selected from the list, starting with 1 for the first option. You know now which option the user picked and which number in your real list of possible menu items it translated to:

mes "You selected "+@possiblemenuitems$[@menureference[@menu-1]]+"!";

* @menu is the number of option the user picked.
* @menu-1 is the array index for the list of actually used menu items that we
made.
* @menureference[@menu-1] is the number of the item in the array of possible menu items that we've saved just for this purpose.

And @possiblemenuitems$[@menureference[@menu-1]] is the string that we used to display the menu line the user picked. (Yes, it's a handful, but it works.)

You can set up a bunch of 'if (@menureference[@menu-1]==X) goto Y' statements to route your execution based on the line selected and still generate a different menu every time, which is handy when you want to, for example, make users select items in any specific order before proceeding, or make a randomly shuffled menu.

Kafra code bundled with the standard distribution uses a similar array-based menu technique for teleport lists, but it's much simpler and doesn't use @menu, probably since that wasn't documented anywhere.

See also '[[select]]', which is probably better in this particular case. Instead of menu, you could use 'select' like this:

[[set]] @dummy, [[select]](@menulist$[0],@menulist$[1],....@menulist$[<X>]);

For the purposes of the technique described above these two statements are perfectly equivalent.

== See Also ==
* [[Menus]]

[[Category:Script Command]]

Adding a Script

2016-09-16T18:53:09Z

Haru: Marked as outdated (old config syntax)

{{outdated}}

== Adding and Activating Scripts ==
Scripts are usually kept in the ''npc'' folder for the sake of organization even though scripts can contain more than a mere NPC. All files are saved as text files. Scripts cannot be loaded on to the server unless their text file is activated in a *.conf file.

=== A New Script ===
New scripts must be saved as a text file first. The file may be located anywhere in the Hercules directory, but is in the ''npc'' folder by default.

=== Configuration Files ===
Any text editor may be used to edit *.conf files. The ''npc/*.conf'' files are used to determine which script text files should be loaded. There are about a dozen *.conf that handle different groups of scripts for the purpose of organization. It does not matter which *.conf holds your custom scripts as long as the path is correct.

Typical *.conf entry layout:
npc: npc/path/to/yourscript1.txt
// npc: npc/path/to/yourscript2.txt
Note how the second line is preceded with a double slash. Content on the same line after double slashes will not be parsed. In other words, ''script2.txt'' will not be loaded. The slashes can be used to write comments.

{{git|npc/pre-re/scripts_main.conf}} or {{git|npc/re/scripts_main.conf}} determines which of the *.conf will be read by the server.
import: npc/path/to/configuration.conf

=== The NPC in Game ===
After adding the script, it must be loaded before the script contents take effect in game. There are a few ways to do this.
* The map server can be rebooted. This is generally the safest route though not the most convenient for active servers.
* The GM command '''@reloadscript''' maybe used in game, though this may cause monster spawn bugs.
* If a script needs to be reloaded because it has been edited, the GM commands '''@loadnpc''' and '''@unloadnpc''' may be used. This method is not convenient for script texts that contain multiple NPCs.

== Client Side ==
The NPC name used in examples is "Teddy".
===Lua===
The two files you will need to open and edit are "jobname.lua" and "npcidentity.lua". Jobname.lua will look like:

[jobtbl.NPCNAME] = "NPCNAME",
Example:
[jobtbl.TEDDY] = "TEDDY",
npcidentity.lua will look like:
["NPCNAME"] = NPCID,
Example:
["TEDDY"] = 587,
If your NPC has spaces in its name, its best to either remove them or replace them with underscores. So if the NPC's name was Brown Teddy the sprite's name would be Brown_Teddy.spr or BrownTeddy.spr and the lua files would be BROWN_TEDDY or BROWNTEDDY. Whatever ID you choose for your sprite, either NPC Sprite name(Case-Sensitive, In Capital Letters) or ID will be use in the script. The beginning of my script will look like:

xmas_in,111,107,3 script Teddy 587,{
xmas_in,111,107,3 script Teddy TEDDY,{

===Sprite===
The sprite part is straightforward, just Teddy.spr is fine, you don't need Teddy_m.spr or anything like that, but if you want to add m for male to the name you can do that, but it won't effect its functionality in-game. NPC sprites are located in data/sprite/npc.

== Tips & Hints ==
* If you are copy/pasting a script from a forum, be sure to check that the tabs are still intact.
* Remember that paths and file names are case sensitive.
* Remember to save after editing.
* Create your own NPC folder and *.conf file. This will make it much easier to keep track of your own scripts and can reduce the hassle when merging new revisions of Hercules. Follow the basic layout of the other *.conf files and remember to import the *.conf in {{git|npc/scripts_main.conf}}

[[Category:Scripting]]

Basic Scripting

2016-09-16T18:47:38Z

Haru: Severely outdated syntax

{{outdated}}

==The Basics==

Scripts control all NPCs, warps, mob spawns, shops, and quests you will find in the game--and nearly everything else! Clearly they play a large part in customizing a server, but learning isn't very hard.

Scripts are built up of predefined script commands, all of which can be found in {{git|doc/script_commands.txt}} (for explanations, see [[:Category:Script_Command|Script Commands]]). Every line should begin with a command and the argument it takes, and must end in a semicolon (or you'll get mapserver errors!). Arguments are usually separated by commas, and are sometimes contained in parentheses () or curly brackets {}. Tabs and proper indentation are standard scripting measures.

Scripts are saved as text (*.txt) files, so all code can be written in Notepad. There are also a lot of scripting programs to use: the most recent and comprehensive one is [http://rathena.org/board/topic/56484-enpc-script-editor/ Vince's eNPC]. All defined functions are highlighted, with an autocomplete feature included, and pressing "F1" will display the corresponding explanation for any command.

==Structure==

===NPC===
A '''Script NPC''' will look something like the following:
prontera,156,145,4 <tab> script <tab> Test NPC <tab> 58,{

The first section is the map location of the NPC, followed by its coordinates in x,y and the direction the NPC will face. Direction numbers are counted counterclockwise in 45º increments, with 0 being the center: 

[1][0][7] 
[2][  ][6] 
[3][4][5] 

After the first tab, the type of script is defined. For our purposes, it'll stay "script" for now, but can also be function, shop, or cashshop, for starters. 
The name of the NPC is next. You can use up to 24 characters, so make it unique! Any duplicates will cause warnings or errors, and the NPC will just be automatically renamed anyway. 
The last number is for the sprite (Ai4rei's sprite list can be found [http://nn.ai4rei.net/dev/npclist/ here]). It's followed by a comma and open curly bracket, marking the beginning of the script contents. Of course, the script must also end in a curly bracket. 

===Function===
A '''Function script''' will look almost identical to:
function <tab> script <tab> Function Name <tab> {

The words "function" and "script" won't change; the name must also be unique. All functions can be called using the "callfunc" command. 

===Shop===
A '''Shop''' starts like a normal script:
prontera,156,145,4 <tab> shop <tab> Fruit Store <tab> 58,512:-1,513:1000

The first section defines the map, coordinates, and direction. The word "shop" replaces "script" (alternately, "cashshop" will use Cashpoints instead of Zeny). The name and sprite ID follow, then a comma. 
Items in the shop are defined in an ID:Price format. A price of -1 uses the default price in item_db.txt. Be sure the price is not too low, or a you will open a Zeny exploit in your server! 

==Fundamentals==

You can always look up commands that you need--even the best scripters don't have everything memorized. There are a few fundamentals that you should know by heart, though, since they are so commonly used.

===Message===

*mes "<string>";
This is the most basic command. Start the line with the word mes, then enter the message in quotes (don't forget the semicolon at the end!). 
To add color, simply add ^ and the hex code anywhere in the message. A list can be found [http://www.immigration-usa.com/html_colors.html here]. 

''As an example:''
mes "[^FF0000Test NPC^000000]";
mes "Hello!";

''Will display:''
[Test NPC]
Hello!

===Labels, Goto, and End===

To create a label, type a label name and a colon at the start of a line. If the label does not end with an "end;" command, everything following the label will be read, so don't forget it between labels! 
To go to a label, use the simple "goto" command:
*goto <label>;

''Note that there are "special" labels that trigger whenever a specific event occurs. The name usually makes it obvious, but you can find explanations in script_commands.txt. Here is a brief sampling:''
OnClock<hour><minute>:
OnInit:
OnAgitStart:
OnAgitEnd:
OnTouch:
OnPCLoginEvent:
OnPCLogoutEvent:
OnPCBaseLvUpEvent:
OnPCJobLvUpEvent:
OnPCDieEvent:
OnPCKillEvent:
OnNPCKillEvent:
OnPCLoadMapEvent:

===Menus, Close, and Next===
{{EntirePage|Menus}}

*menu "<option_text>",<target_label>{,"<option_text>",<target_label>,...};
*close;
*next;
Menus create a set of options, which trigger labels when selected. The text in quotes is what will be displayed, followed by its respective label. Enter as many choices as you want, and end the last one with a semicolon instead of a comma. 
"Close" will close any message window that is open (from "mes" commands). 
"Next" will clear the message window, bringing up a fresh screen. 

''For example:''
mes "[Test NPC]";
mes "How are you doing today?";
menu "I am doing okay!",doingokay,"Not doing too well",bad;

doingokay:
mes "Glad to hear it!";
close;
end;

bad:
mes "Aww, I'm sorry about that.";
close;
end;

===Conditions, Variables, and Set===
{{EntirePage|Variables}}

*if(condition) {<script>;}
*else {<script>;}
Conditional statements "if" and "else" are the same as anywhere else. Multiple conditions can be specified: || means ''or'', while && means ''and''. == is ''equal'', != is ''not equal''. Inequalities can be used as well (<, >, <=, >=). 
The "else" can be omitted, and the brackets aren't necessary unless multiple commands follow a conditional statement. 

The type of variable used is defined in the name. There are permanent and temporary variables, as well as scope (temporary NPC), character, global, and global account. The default type is an integer, and adding $ as a suffix creates a string. 
Here are some example types, taken from script_commands.txt:
name - permanent character integer variable
name$ - permanent character string variable
@name - temporary character integer variable
@name$ - temporary character string variable
$name - permanent global integer variable
$name$ - permanent global string variable
$@name - temporary global integer variable
$@name$ - temporary global string variable
.name - NPC integer variable
.name$ - NPC string variable
.@name - scope integer variable
.@name$ - scope string variable
#name - permanent local account integer variable
#name$ - permanent local account string variable
##name - permanent global account integer variable
##name$ - permanent global account string variable

The "set" command is used to give a value (or string) to a variable:
*set <variable>,<expression>;

''The following script will pick a random number, store it as the temporary scope variable .@random, and display two different messages depending on the result:''
set .@random, rand(1,2);
if (.@random == 1) { mes "I like you! :D"; }
else { mes "I don't like you. Get out of here!"; }
close;

===Duplicating===

It would be a huge waste of time and space to code the same NPC over and over again. By duplication, an NPC can be created in multiple locations. 

Take a look at our old Test NPC:
prontera,156,145,4 <tab> script <tab> Test NPC <tab> 58,{
To be able to duplicate this, we will change the heading to this:
- <tab> script <tab> Test NPC#01::testnpc <tab> 58,{
The location doesn't need to be defined in the NPC, since it will be in the duplicates. 
The displayed name remains "Test NPC". But since NPC names must be unique, adding #01 separates this one from the rest, which will be #02, #03, etc. Lastly, ::testnpc is the reference name used for duplicating NPCs; this part is not displayed on the screen. 

After creating the base NPC, duplicates can be added anywhere to any file, so long as you use the same NPC name:
spl_fild03,150,150,7 <tab> duplicate(testnpc) <tab> Test NPC <tab> 58
niflheim,50,50,2 <tab> duplicate(testnpc) <tab> Test NPC <tab> 58
tha_scene01,140,190,4 <tab> duplicate(testnpc) <tab> Test NPC <tab> 58
The first part is ''map,x,y,direction'', as you're probably used to by now. 
To define a duplicate, the word "duplicate" followed by the NPC, in parentheses, is needed. The last two parameters are the display name and sprite ID (yes, you can change these, too!).

==Finished Product==

Here is an example using the features explained above:

prontera,156,145,4 script Test NPC::test 589,{
mes "Hello, how are you?";
mes "I am fine, how are you?";
menu "I am doing okay!",-,"Not doing too good",bad;
mes "That's good, I'm glad to hear that";
close;

bad:
mes "Awww, that makes me a bit ^FF0000sad^000000. Sorry to hear that.";
next;
mes "Would you like some zeny to help yourself feel better?";
next;
menu "Sure, give it to me!",L_zeny,"Naw, No zeny for me",-;
close;

L_Zeny:
mes "I can only give you zeny if you have 10,000 or less.";
if (Zeny > 10000) goto toomuch;
mes "You have 10,000 zeny or less, I see.";
set Zeny,Zeny+10000;
next;
mes "Hope you feel better!";
close;

toomuch:
mes "You have over 10,000 zeny, you must feel really good about yourself!";
close;
}

lhz_dun01,157,285,4 duplicate(test) Test NPC 859
hu_fild05,186,210,4 duplicate(test) Test NPC 859
yuno_fild07,221,179,4 duplicate(test) Test NPC 859
tha_scene01,139,194,1 duplicate(test) Test NPC 859

==Adding Scripts==
{{EntirePage|Adding a Script}}
For an NPC to be loaded, it needs to be added to a .conf file. This is typically ''npc/scripts_custom.conf''. 
Add a line, and enter your NPC file in the following format:
npc: npc/path/to/script.txt
That's it! You're finished!

==External Links==
'''Reference Manuals for scriping commands'''
* {{git|/doc/script_commands.txt}} Original documentation

'''Sprite lists'''
* http://nn.ai4rei.net/dev/npclist/

'''Color Charts'''
* http://www.immigration-usa.com/html_colors.html
* http://www.december.com/html/spec/colorcodes.html
* [[wikipedia:Hex_triplet|Hex triplet]]
* http://www.colorschemer.com/online.html

'''Support, Request and Release'''
* [http://herc.ws/board/forum/22-script-support/ Scripting support on Hercules Boards]
* #Hercules on irc.rizon.net : Main Hercules channel.

[[Category:Scripting]]

Adding Script

2016-09-16T18:44:54Z

Haru: Marked as outdated (old syntax)

{{outdated}}

== Adding and Activating Scripts ==
Scripts are usually kept in the ''npc'' folder for the sake of organization even though scripts can contain more than a mere NPC. All files are saved as text files. Scripts cannot be loaded on to the server unless their text file is activated in a *.conf file.

=== A New Script ===
New scripts must be saved as a text file first. The file may be located anywhere in the Hercules directory, but is in the ''npc'' folder by default.

=== Configuration Files ===
Any text editor may be used to edit *.conf files. The ''npc/*.conf'' files are used to determine which script text files should be loaded. There are about a dozen *.conf that handle different groups of scripts for the purpose of organization. It does not matter which *.conf holds your custom scripts as long as the path is correct.

Typical *.conf entry layout:
npc: npc/path/to/yourscript1.txt
// npc: npc/path/to/yourscript2.txt
Note how the second line is preceded with a double slash. Content on the same line after double slashes will not be parsed. In other words, ''script2.txt'' will not be loaded. The slashes can be used to write comments.

{{git|npc/scripts_main.conf}} determines which of the *.conf will be read by the server.
import: npc/path/to/configuration.conf
{{git|npc/re/scripts_main.conf}} Loads the renewal NPCs if RENEWAL is enabled.
{{git|npc/pre-rere/scripts_main.conf}} Loads the pre-renewal NPCs if RENEWAL is disabled.

=== The NPC in Game ===
After adding the script, it must be loaded before the script contents take effect in game. There are a few ways to do this.
* The map server can be rebooted. This is generally the safest route though not the most convenient for active servers.
* The GM command '''@reloadscript''' maybe used in game, though this may cause monster spawn bugs.
* If a script needs to be reloaded because it has been edited, the GM commands '''@loadnpc''' and '''@unloadnpc''' may be used. This method is not convenient for script texts that contain multiple NPCs.

== Client Side ==
The NPC name used in examples is "Teddy".
===Lua===
The two files you will need to open and edit are "jobname.lua" and "npcidentity.lua". Jobname.lua will look like:

[jobtbl.NPCNAME] = "NPCNAME",
Example:
[jobtbl.TEDDY] = "TEDDY",
npcidentity.lua will look like:
["NPCNAME"] = NPCID,
Example:
["TEDDY"] = 587,
If your NPC has spaces in its name, its best to either remove them or replace them with underscores. So if the NPC's name was Brown Teddy the sprite's name would be Brown_Teddy.spr or BrownTeddy.spr and the lua files would be BROWN_TEDDY or BROWNTEDDY. Whatever ID you choose for your sprite will be the one you use in the script, so since Teddy has the sprite ID of 587, the beginning of my script will look like:

xmas_in,111,107,3 script Teddy 587,{

===Sprite===
The sprite part is straightforward, just Teddy.spr is fine, you don't need Teddy_m.spr or anything like that, but if you want to add m for male to the name you can do that, but it won't effect its functionality in-game. NPC sprites are located in data/sprite/npc.

== Tips & Hints ==
* If you are copy/pasting a script from a forum, be sure to check that the tabs are still intact.
* Remember that paths and file names are case sensitive.
* Remember to save after editing.
* Create your own NPC folder and *.conf file. This will make it much easier to keep track of your own scripts and can reduce the hassle when merging new revisions of Hercules. Follow the basic layout of the other *.conf files and remember to import the *.conf in {{git|npc/scripts_main.conf}}

[[Category:Scripting]]

Connecting

2016-09-16T18:41:43Z

Haru: Marked as outdated - contains info about old txt conf files

{{outdated}}

This article covers taking the configuration steps to ensure a successful connection to your servers. You are required to know the in and outs of your OS,
as well as what a [[wikipedia:Local area network|LAN IP]] and a [[wikipedia:Wide area network|WAN IP]] are.

==Basics of the three servers==
===Login Server===
The login server handles all login packets from the client. The client sees the login server first and connects to it first. The login server listens on the
port 6900 by default and usually reads data from the login table. The login server connects directly to the character server and passes it's information
to it once the client has successfully logged in. If your login server won't connect, your players cannot login in, but can play.

===Character Server===
The character server handles all character selection and character loading for the map server. The character server receives commands to primarily display characters
once the client has logged in. The character server listens on the port 6121 by default. It also handles the loading and saving of most character data.
If the character server becomes disconnected, character data saving is not possible.

===Map Server===
The map server handles all map functions, including, but not limited to, mob functions, map functions, NPC loading and unloading, as well as NPC processing.
the map server is your bread and butter and allows people to play on your server. It listens on the port 5121 by default.

If the character server becomes disconnected from your map server, it's likely the mapserver will disconnect everyone from it. This is not the case when the
MySQL server loses its connection to Hercules, as Hercules currently does not restore this connection.

===Port Forwarding===

If you intend to let your players play from an external internet connection, you ''must'' forward ports 6900, 6121, and 5121 respectively in your router's control panel. Simply forwarding port 6900 is not enough to allow clients to connect, and traffic will not be passed solely through your login server, even though they can communicate with one another internally on your localhost address.

==Configuring Hercules for use==
After you have finished [[compiling]] Hercules, you can set it up for use. There will be four files that we will concentrate on. Any settings we change in these files should '''always''' be moved to the relevant import folder files. If your compiler hasn't already made a copy of the {{git|conf/import-tmpl}} folder and named it /conf/import do that now.

=====Using the /conf/import/ folder ({{git|conf/import-tmpl/}})=====
In this folder, you can 'import' your settings into each of the respected files. All you need is each parameter. When you do this, your settings will never be overwritten when you need
to update your GIT, as the import folder is built once. You can throw all of your settings in here and they will remain as they are, and will read AFTER the
main settings, which means these settings will take priority.

===Step 1. Interserver Communication Passwords===
First, you will need to set an intercommunication password and user. This is one of the most important steps to securing your server.

In order for the char-server to accept commands and packets from the login server, and for the map-server to accept commands and packets from the char-server they have to 'log-in' to each other, using the Server Communication passwords.
You MUST set these to something other than defaults, but you can set them to random characters, as long as they are the same in the three places they appear in, which are: {{git|conf/char-server.conf}}, {{git|conf/map-server.conf}} and your login sql table.
They are defaulted to s1/p1, and '''MUST''' be changed.

Changes must be made to the import folder to ensure proper upgradability. A good habit to get into when working with GIT.
Simply copy and paste the lines you wish to alter from the .conf file to the relevant .txt file in the import folder.
Your /conf/import/char_conf.txt ''and'' /conf/import/map_conf.txt files should look as follows, with ''no'' changes made to {{git|conf/char-server.conf}} or {{git|conf/map-server.conf}}: 
<code><pre>// Server Communication username and password.
userid: [new user]
passwd: [new password]</pre></code>

Your login table should match. Use this SQL query (or make the changes using your favourite SQL gui):
<code><pre>use databasename_rag;
UPDATE login
set `userid` = "[new user]", `user_pass` = "[new password]" where `account_id` = 1;</pre></code>

After the user and password is set, you can move on down the page.

===Step 2. {{git|conf/login-server.conf}}===
Usually there is nothing to be done here in terms on connection.
You may want to edit your login_port to something other than default, but it must be an unused port by your OS.

You can find this out by starting all the services that you need on the server and issuing the following commands to your console:

'''If using Windows:''' 
Goto Start, then click 'Run'. Type 'cmd' and press enter. Run the following command:
<code><pre>netstat -a</pre></code>
'''If using *nix:'''
<code><pre>$ lsof -i</pre></code>

Once you have selected a port if you're going to change it, your /conf/import/login_conf.txt file should look as follows, with ''no'' changes made to {{git|conf/login-server.conf}} (again just copy pasting the lines we want to change from one file to the other): 
<code><pre>// Login Server Port
login_port: [new port]</pre></code>

===Step 3. {{git|conf/char-server.conf}}===
This file sets parameters for the char-server to read.
When you open this up, there are a few things we need to do in here.

Firstly we should name our server:

When setting server_name, be sure to not use spaces as it says.
<code><pre>// Server name, use alternative character such as ASCII 160 for spaces.
// NOTE: Do not use spaces in the name, or guild emblems won't work client-side!
server_name: [new server name]</pre></code>

<code><pre>// Wisp name for server: used to send wisp from server to players (between 4 to 23 characters)
wisp_server_name: [new server name]</pre></code>

Usually, Hercules will auto-detect your external and internal IP if the IP fields are [[comments|commented out]], but let's go ahead and remove the two slashes (//) from login_ip and char_ip.

The login_ip will point to the IP address where the login server will be running. Usually this is the localhost, or 127.0.0.1.
If the login-server is to be located on the same network as the char-server (but on a different PC), use the LAN IP of the login server's machine.
If you are running a dedicated machine in a datacenter, or you know your IP is not going to change, you can set this to your WAN IP.

<code><pre>// Login Server IP
// The character server connects to the login server using this IP address.
// NOTE: This is useful when you are running behind a firewall or are on
// a machine with multiple interfaces.
login_ip: [new ip here]</pre></code>

The char_ip parameter will '''ALWAYS''' be your WAN IP, no exceptions. This is the IP that the char-server will accept connections with.

<code><pre>// Character Server IP
// The IP address which clients will use to connect.
// Set this to what your server's public IP address is.
char_ip: [your wan ip here]</pre></code>

If you changed the login_port in login-server.conf, this setting here will need to match it.
<code><pre>// Login Server Port
login_port: [new port]</pre></code>

Make sure to make any changes in the import folder as always.

===Step 4. {{git|conf/map-server.conf}}===
This file sets parameters for the map-server to read.

The char_ip will point to the IP address where the login server will be running. Usually this is the localhost, or 127.0.0.1.
If the char-server is to be located on the same network as the map-server (but on a different PC), use the LAN IP of the char server's machine.
If you are running a dedicated machine in a datacenter, or you know your IP is not going to change, you can set this to your WAN IP.

<code><pre>// Character Server IP
// The map server connects to the character server using this IP address.
// NOTE: This is useful when you are running behind a firewall or are on
// a machine with multiple interfaces.
char_ip: [new ip here]</pre></code>

The map_ip parameter will '''ALWAYS''' be your WAN IP, no exceptions. This is the IP that the map-server will accept connections with.

<code><pre>// Map Server IP
// The IP address which clients will use to connect.
// Set this to what your server's public IP address is.
map_ip: [your wan ip here]</pre></code>

Make sure to make any changes in the import folder as always.

===Step 5. {{git|conf/inter-server.conf}}===
About midway down this file, you will find your SQL settings. These will be set as accordingly.

* The 'sql.db' settings control what the login-server reads for it's database settings.
* Hostname is the IP of the SQL server.
* Username is the username you use to login. For security, this should '''NEVER''' be root!
* Password is the password that the user will login with.
* The database is set to whatever the database name will be. Usually, this is just 'ragnarok'.

If you make any changes in here, copy paste the lines you change into /conf/import/inter_conf.txt and modify them there.

==Starting Hercules==
When you're all done configuring Hercules, you can start it up. You can do this by simply running each of the three servers, or athena-start.

==Client Side==
===Diff your client===
See [[Hexing#Creating_custom_RagRE_client_using_a_DIFF_patcher|Hexing]].

===Data Folder===
#Download the most recent data folder [http://svn6.assembla.com/svn/ClientSide/ here].
#Edit your [[Clientinfo|clientinfo.xml]] as needed.

===Connect===
Execute your exe.

==Trouble Shooting==
Its always best to post in the [http://herc.ws/board/forum/31-client-side-support/ client support] sub-forum for things that go wrong with the client, and [http://herc.ws/board/forum/14-general-server-support/ server support] sub-forum for things that go wrong with Hercules connecting or if errors pop up in your server log.

===CHARACTER_INFO size error!!===
To fix this, locate the src/common folder and open mmo.h in notepad. Find the following line:
<code><pre>#ifndef PACKETVER
#define PACKETVER 20110609
</pre>
Edit this Part, put:
<pre>#define PACKETVER YOURCLIENTDATE</pre>

So if my client was 2011-10-25aRagexeRE it would look like:
<pre>#define PACKETVER 20111025</pre>

[[Category:Configuration]]

Db2sql

2016-09-16T18:37:29Z

Haru: Added mob_db to the list of converted files

== Files Converted ==
* {{git|db/pre-re/item_db.conf}} (only in pre-renewal mode)
* {{git|db/re/item_db.conf}} (only in renewal mode)
* {{git|db/item_db2.conf}}
* {{git|db/pre-re/mob_db.conf}} (only in pre-renewal mode)
* {{git|db/re/mob_db.conf}} (only in renewal mode)
* {{git|db/mob_db2.conf}}

== Description ==
This plugin converts the item database configuration files for use with SQL servers.

== Compiling ==
The plugin needs to be compiled. If you've already compiled your server and/or other plugins, input these commands:
./configure
make plugin.db2sql

=== Windows ===
In Windows, compile the '''db2sql''' plugin in Visual Studio.

== Enabling db2sql ==
Next, the plugin needs to be enabled in {{git|conf/plugins.conf}}:
plugins_list: [
/* Enable HPMHooking when plugins in use rely on Hooking */
//"HPMHooking",
"db2sql",
//"sample",
//"other",
]

== Usage ==
To use the converter, update your changes in the desired item database (using {{git|db/item_db2.conf}} for customisations is recommended); then, run this command:
./map-server --db2sql

=== Windows ===
In Windows, run {{git|db2sql.bat}} in the root directory.

== Output ==
The resulting files will be output in the {{git|sql-files}} folder as {{git|sql-files/item_db.sql}}, {{git|sql-files/item_db_re.sql}}, and {{git|sql-files/item_db2.sql}}.

[[Category:Tools]]

Gettime

2016-09-16T18:31:24Z

Haru: Marked as outdated. Should use constants

{{outdated}}

==Syntax==
*'''gettime'''(<type>);

==Description==
This function retrieves current system time and date values depending on parameter ''type'':
#Seconds (0 - 59)
#Minutes (0 - 59)
#Hours (0 - 23)
#Day of Week (0: Sunday - 6: Saturday)
#Day of Month (1 - 31)
#Month (1 - 12)
#Year (1970 - 2038)
#Day of Year (1 - 366)
Any other value will cause the function to return -1. Only numbers are returned.

==Examples==
[[if]](gettime(4)==6)
{
[[mes]] "It's a Saturday. I don't work on Saturdays.";
[[close]];
}

==See Also==
* [[gettimestr]]
* [[gettimetick]]

[[Category:Script Command]]

Isnight

2016-09-16T18:27:49Z

Haru: removed isday info

==Syntax==
*'''isnight'''();

==Description==
These functions determine whether server day or night cycle is currently in effect or not. If the server night is in effect, isnight will return true, otherwise false.

==Examples==
[[if]](!isnight())
{
[[mes]] "I do not work at day, come again tomorrow.";
[[close]];
}

if(isnight())
{
mes "I do not work at night, come again tomorrow.";
close;
}
These two script fragments achieve the same effect.

[[Category:Script Command]]

Isnight

2016-09-16T18:26:16Z

Haru: Haru moved page Isday to Isnight over redirect: The isday() command was removed. Only isnight() stays.

==Syntax==
*'''isday'''();
*'''isnight'''();

==Description==
These functions determine whether server day or night cycle is currently in effect or not. If the server night is in effect, isday and isnight will return 0 and 1, otherwise 1 and 0 respectively.

==Examples==
[[if]](!isday())
{
[[mes]] "I do not work at day, come again tomorrow.";
[[close]];
}

if(isnight())
{
mes "I do not work at night, come again tomorrow.";
close;
}
These two script fragments achieve the same effect.

[[Category:Script Command]]

Itemskill

2016-09-16T18:24:52Z

Haru: Marked as outdated. The page shows a txt-style item database entry

{{outdated}}

==Syntax==
*'''itemskill''' <skill id>, <skill level>;
*'''itemskill''' <"skill name">, <skill level>;

==Description==
This command meant for item scripts to replicate single-use skills in usable items. It will not work properly, if there is a visible dialog window or menu. If the skill is self or auto-targeting, it will be used immediately otherwise a target cursor is shown.

==Examples==
605,Anodyne,Anodyne,11,2000,0,100,,,,,10477567,2,,,,,{ itemskill 8,1; },{}
When Anodyne is used, it will cast Endure (8), Level 1, as if the actual skill has been used from skill tree.

[[Category:Script Command]]

Import folder

2016-09-16T18:24:25Z

Haru: Marked as outdated. Should be updated with the libconfig-style config info

{{outdated}}

=Import folder Introduction=
The Import Folder is used to import virtually all of your configuration changes and settings into the core of the Hercules emulator without ever making changes to any .conf files after it is initially configured. This is very helpful when Creating a New Server Build, Compiling , or Updating to the Latest version this will allow retention of all the settings you previously configured without having to deal with possible overwrite conflicts from a git pull or change over to a New Server Build.

=How it works=
So, It works as such; Once you have configured all of the files you wish to configure within the Conf directory of your server side you will take those same settings and copy them to the corresponding import directory files. For Example: Lets say you make the following changes to;

'''conf/battle/client.conf''' ---> Make your desired changes, in this case we are changing hair and dye settings.
// Valid range of dyes and styles on the client.
min_hair_style: 0
max_hair_style: 27 ----> Changing to 40
min_hair_color: 0
max_hair_color: 8 ----> Changing to 200
min_cloth_color: 0
max_cloth_color: 4 ----> Changing to 100

'''conf/battle/client.conf''' ---> We then simply copy only the changed setting lines into ---> conf/import/client_conf.txt

max_hair_style: 40
max_hair_color: 200
max_cloth_color: 100

Since these three settings were the only ones we changed in this example these are the only configuration lines to copy from the .conf file into the corresponding import.txt file. This will now allow the server to directly import these changed settings. This can be done with any of the configuration files. The server reads .confs files within the conf directory first, however any settings configured within the /import/ folder will be read second, thus overwriting default settings. Please note over time settings have changed, so please compare Import.txt Files to any New Server Configuration Settings.

=Commonly Imported Settings=

The most common use of these files is for the following parameters: 
'''/conf/login_athena.conf''' -> /conf/import/login_conf.txt
login_port: 6900
account.engine: auto
account.sql.db_hostname: 127.0.0.1
account.sql.db_port: 3306
account.sql.db_username: ragnarok
account.sql.db_password: ragnarok
account.sql.db_database: ragnarok

'''/conf/char_athena.conf''' -> /conf/import/char_conf.txt
userid: s1
passwd: p1
server_name: Hercules
login_port: 6900
char_ip: 127.0.0.1
char_port: 6121
start_point: new_1-1,53,111

'''/conf/map_athena.conf''' -> /conf/import/map_conf.txt
userid: s1
passwd: p1
char_ip: 127.0.0.1
char_port: 6121
map_ip: 127.0.0.1
map_port: 5121

'''/conf/inter_athena.conf''' -> /conf/import/inter_conf.txt
sql.db_hostname: 127.0.0.1
sql.db_port: 3306
sql.db_username: ragnarok
sql.db_password: ragnarok
sql.db_database: ragnarok
char_server_ip: 127.0.0.1
char_server_port: 3306
char_server_id: ragnarok
char_server_pw: ragnarok
char_server_db: ragnarok
map_server_ip: 127.0.0.1
map_server_port: 3306
map_server_id: ragnarok
map_server_pw: ragnarok
map_server_db: ragnarok
log_db_ip: 127.0.0.1
log_db_port: 3306
log_db_id: ragnarok
log_db_pw: ragnarok
log_db_db: ragnarok
log_login_db: loginlog
use_sql_db: no

=Conclusion=
The Import Folder is a powerful tool and is often overlooked by amateur developers, but it saves a lot of time and effort it is highly recommended to use. The import.txt files can be saved and used in any new build, just ensure you double check the pathways and corresponding configuration settings. The import folder is often incomplete or blank when downloading latest revisions, you will have to add the necessary files or overwrite the blank template files.

[[Category:Configuration]]

Menus

2016-09-16T18:20:18Z

Haru: Marked as outdated. The section about 'menu' should be gone, only select and prompt are to be used

{{outdated}}

=Menus=

==Menu Command==
The menu command is hardly used anymore, but can be helpful for a few quick setups.

* menu "<menu option>",<label>{,"<menu option>",<label>,...}; // Thanks to Dj-Yhn

This command has two parts to it, the menu option (which is what the users see to select) and the label (where the menu option takes them if they select it)

===Example 1.1 - Standard Menu Command Setup===
menu "Option 1",L_GoToOption1,"Option 2",L_GoToOption2;

L_GoToOption1:
mes "You chose option 1";
close;

L_GoToOption2:
mes "You chose option 2";
close;

While this is nice, there is also a nifty little trick to this command.
Notice that L_GoToOption1 is directly under the menu command itself? We don't need to use a label for this option, because we can tell the menu command to simply continue to the line down by replacing the label name in the menu line with a -.

===Example 1.2 - Optimizing the Menu Command===
menu "Option 1",-,"Option 2",L_GoToOption2;

mes "You chose option 1";
close;

L_GoToOption2:
mes "You chose option 2";
close;

Now we have a simplified menu command that only uses one label, rather than two.

----

==Select Command==
The Select command followed by the Prompt command are now usually the top two contenders for menu selection.
* select "Option"{,"Option",...,"Option"}; // Thanks to Dj-Yhn
* select "Option 1:Option 2";

Rather than selecting an option and then moving to a label, you get a returned value for the option selected.
@menu is a character variable that is set after selecting an option.

===Example 2.1 - Standard Select Command Setup===
select "Option 1","Option 2";

if (@menu == 1) { mes "You chose option 1"; }
else { mes "You chose option 2"; }
close;

This can be further broken down into an even more efficient method.

===Example 2.2.1 - Optimizing the Select Command===
if (select("Option 1","Option 2") == 1) { mes "You chose option 1"; }
else { mes "You chose option 2"; )
close;

Select also has a different setup than the Menu Command. Notice that there are no labels anymore? That's because we use values returned rather than going to different places.

In the second example, you will notice that the select command can run with a single string separated by a colon for each option. This can be quite handy with arrays and dynamic menu setups, however that will come in a more later discussion.

For a simple method, I will demonstrate how to include a GM Option to your menu that only GM Players can see.

===Example 2.2.2 - Optimizing the Select Command===
switch(select("Option 1:Option 2")) {
case 1:
mes "You chose option 1";
break;

case 2:
mes "You chose option 2";
}
close;

You can also jump right into the switch statement with the Select() command. Rather than using the predefined @menu variable, you can simply switch the command itself.

===Example 2.3 - Using a Unique Variable for Returning an Option Choice===
set .@playerChoice, select("Option 1:Option 2");
set .@myOtherChoice, select("Option 1:Option 2");

By looking at these, if we were to only use the standard @menu, they would overwrite each other, simply for the fact that each one of them would attempt to store @menu as the index chosen. By placing a set and a variable before to the select returned value, we can now distinguish between the two menu options selected.

===Example 2.4 - Simple Dynamic Menu using Select===
set .@menu$, "Player Option 1:Player Option 2";

if (getgmlevel() >= 99) { set .@menu$, .@menu$ + ":GM Menu"; }

switch(select(.@menu$)) {
case 1:
mes "Player Option 1";
close;

case 2:
mes "Player Option 2";
close;

case 3:
mes "GM Menu";
close;
}

Normal players will not be allowed to choose the case 3 option of GM Menu, because it is not added to the menu list unless they meet the criteria of being a level 99 GM.

This can be tricky when trying to add more than a single added option based on criteria due to the fact that the case might not be in order, if you don't add the options. This will be discussed in the "Advanced Scripting" area later.

----

==Prompt Command==
The Prompt command followed by the Select command are now usually the top two contenders for menu selection.
* prompt "Option"{,"Option",...,"Option"}; // Thanks to Dj-Yhn
* prompt "Option 1:Option 2";

The prompt command works exactly like the select command however a value of 255 is passed back to the script if the user decides to choose the CANCEL button that is automatically generated by menus.

===Example 3.1 - Quick Example of the Prompt Command===
prompt "Click Me:No Click Me";

if (@menu == 255) { mes "You should not have closed the menu... BAD BOY!"; close; }

[[Category:Scripting]]

Monster

2016-09-16T18:18:43Z

Haru: Marked as outdated (doesn't use constants)

{{outdated}}

{{OtherUse|the script command|the game object|Mob}}
==Syntax==
*'''monster''' <"map name">, <x>, <y>, <"display name">, <mob id>, <amount>[, <"event label">];

==Description==
This command spawns a monster at given map and coordinates, using given class and amount. Monsters spawned with this command will not re-spawn after being killed.

To address the map, on which the running [[NPC]] resides, ''map name'' can be set to "this". Spawning the monster on random coordinates is accomplished by setting parameters ''x'' and ''y'' to 0. The parameter ''display name'' specifies the in-game name of the monster, which is not necessary required to be the actual name, such as "Prontera minion". The ''display name'' accepts also two magic names, "--ja--" and "--en--", which are replaced by the server with the value of the kROName and iROName mob db columns of the given ''mob id'', respectively. Setting the ''mob id'' to -1, -2 or -3 will spawn a random monster from the dead branch, poring box or bloody branch list respectively.

Optionally an ''event label'' can be specified, which has the form "NpcName::OnLabel" and is run upon the monster's death. If the killer was a player, [[RID#Usage|it will be attached]] to the invoked script.

==Example==
[[mes]] "I will spawn 5 Porings for you!";
[[close2]];
'''monster''' "this",0,0,"Poring 1",1002,1,[[strnpcinfo]](0)+"::OnPoring1Dead";
'''monster''' "this",0,0,"Poring 2",1002,1,strnpcinfo(0)+"::OnPoring2Dead";
'''monster''' "this",0,0,"Poring 3",1002,1,strnpcinfo(0)+"::OnPoring3Dead";
'''monster''' "this",0,0,"Poring 4",1002,1,strnpcinfo(0)+"::OnPoring4Dead";
'''monster''' "this",0,0,"Poring 5",1002,1,strnpcinfo(0)+"::OnPoring5Dead";
[[end]];

OnPoring1Dead:
mes "You killed Poring 1";
[[close]];
OnPoring2Dead:
mes "You killed Poring 2";
close;
OnPoring3Dead:
mes "You killed Poring 3";
close;
OnPoring4Dead:
mes "You killed Poring 4";
close;
OnPoring5Dead:
mes "You killed Poring 5";
close;
This will spawn 5 Porings randomly distributed on the map of the invoking character with the names "Poring 1" to "Poring 5". Each time the player kills one of them, it triggers the given event label in the NPC, which will say "You killed Poring X"

[[Category:Script Command]]

Server Modification

2016-09-16T18:09:36Z

Haru: Marked as outdated (does not mention plugins and the HPM)

{{outdated}}

You can find here some information to start making server-side source modifications.

== How Hercules works ==
Hercules has a multi-process architecture. It runs three different processes: '''login-server''', '''char-server''' and '''map-server'''.

=== Login Server ===
'''Login server''' ''':''' receives the login packet, checks if account exists and if the password is correct. If all is OK, the connection is then passed to the '''char-server'''.

=== Char-Server ===

'''Char-server''' ''':''' controls all the character related, Guild, party, pet, inventory etc.

=== Map-Server ===
The last one is the '''map-server''', which controls char and NPC position, chats, skills, exp etc.

== Source Modifications ==
Before you start modifying [[Hercules]], you should better take a look first on [[:Category:Source_Functions]].
Remember, it's necessary to [[Compiling|re-compile]] [[Hercules]] after a source modification.
You can also find information about [[packets]].

=== Pre-Made Modifications ===
Also can take a look at modifications made by other users.
* [[:Category:Source Snippets|Source Snippets]]
* [[Customizing Sheet]]

[[Category:Customization]]

Setlook

2016-09-16T18:07:56Z

Haru: Marked as outdated (missing constants)

{{outdated}}

== Syntax ==
* [[setlook]] <look type>,<look value>;
* [[changelook]] <look type>,<look value>;

== Description ==
[[setlook]] will alter the look data for the invoking character. It is used mainly for changing the palette used on hair and clothes: you specify which look type you want to change, then the palette you want to use. Make sure you specify a palette number that exists/is usable by the client you use. [[changelook]] works the same, but is only client side (it doesn't save the look value).

// This will change your hair(6), so that it uses palette 8, what ever your
// palette 8 is, your hair will use that color

setlook 6,8;

// This will change your clothes(7), so they are using palette 1, whatever
// your palette 1 is, your clothes will then use that set of colors.

setlook 7,1;

Here are the possible look types:
* 0 - Base sprite
* 1 - Hairstyle
* 2 - Weapon
* 3 - Head bottom
* 4 - Head top
* 5 - Head mid
* 6 - Hair color
* 7 - Clothes color
* 8 - Shield
* 9 - Shoes

Whatever 'shoes' means is anyone's guess, ask Gravity - the client does nothing with this value. It still wants it from the server though, so it is kept, but normally doesn't do a thing.

Only the look data for hairstyle, hair color and clothes color are saved to the char server's database and will persist. The rest freely change as the character puts on and removes equipment, changes maps, logs in and out and otherwise you should not expect to set them. In fact, messing with them is generally hazardous, do it at your own risk, it is not tested what will this actually do - it won't cause database corruption and probably won't cause a server crash, but it's easy to crash the client with just about anything unusual.

However, it might be an easy way to quickly check for empty view IDs for sprites, which is essential for making custom headgear.

Since a lot of people have different palettes for hair and clothes, it's impossible to tell you what all the color numbers are. If you want a serious example, there is a Stylist script inside the default Hercules installation that you can look at, this may help you create a Stylist of your own: {{git|npc/custom/stylist.txt}}

[[Category:Script Command]]

Mes

2016-09-16T17:57:49Z

Haru: Marked Mes as outdated

{{outdated}}

[[Category:Script_Command]]
==Syntax==
* [[mes]] "<message>";
* [[mes]] "<Line 1>","<Line 2>","<Line 3>";
* [[mes]] "<message>"+<variable> or command +"<message>";

==Description==

The most basic scripting command. 
Displays a window with '''<message>''' in it to the invoking character, if the window already exists, it will just display the given message. 
Notice that mes does not create a ''next'' or ''close'' button, so you have to create one using the [[next]] or [[close]] command, otherwise the player will be stuck in your script. 
Use the + operator to give out multiple messages combined with variables or some commands(for example [[countitem]], [[getitemname]] or [[strcharinfo]])in one mes. 
Use "^<Red><Green><Blue> " in front of the message to give '''<message>''' a color. 
<Red><Green><Blue> stand for three hexadecimal numbers, representing the color components of Red Green and Blue in the wanted colour, like a html-code(see examples).
 Do not forget to set the color to black again, by putting "^000000" after your message, exept you want to color your whole text... 
 
Be careful: Magenta (ff00ff) is considered as transparent in the client, using it in a Dialogue will result in a weird (or funny) effect.

==Examples==
<pre>mes "Hello World";
//Will open up a text box with:</pre>
Hello World

<pre>mes "Hello 1","Hello 2","Hello 3";
// This will Generate 3 lines</pre>
Hello 1 
Hello 2 
Hello 3

<pre>mes "Hello"+strcharinfo(0)+", how are you?";
// Will upon up a textbox printing:</pre>
Hello Charname, how are you?

<pre>mes "^FF0000 Hello World^000000";
//Will open up a text box with</pre>
Hello World

<pre>mes "\'Hello!\'";
// use \as prefix to include Symbols:
// will print:</pre>
'Hello!'

Compiling/Windows

2016-04-25T12:58:43Z

Haru: /* Using Cygwin */

For compiling on Windows, Visual Studio is the preferred method, although using Cygwin is also possible.

=== Using Visual Studio ===
[[Image:Compile-hercules.PNG|thumb|300px|MS Visual Studio 2015: Compile configuration (red) and solution (blue) with it's child projects.]]
Hercules ships with solution and project files for Visual Studio from 2012 onwards.
* Download the latest version of [https://www.visualstudio.com Visual Studio] (at the time of writing, MS Visual Studio 2015 Community Edition) and install it, if you do not have Visual Studio already installed.
* Open '''Hercules-14.sln''' in your Hercules folder if you use Visual Studio 2015, for Visual Studio 2013, you need to open '''Hercules-12.sln''', for Visual Studio 2012, you need to open '''Hercules-11.sln''' instead.
* Select the desired compile configuration (marked red). Use '''Release''' when you compile the server, where players will be playing on. '''Debug''' compiles the server without optimizations and with debugging information.
* Right-click the solution node (marked blue) and select '''Build solution'''. If you have compiled the server before, it is recommended to use '''Rebuild solution''', as it forces the compiling of all components, not just those, which seem to have changed since last compile.
* If the compilation was successful, the resulting executables are in the same folder as the solution named ''login-server.exe'', ''char-server.exe'', ''map-server.exe'' and ''mapcache.exe''.

=== Using Cygwin ===
[http://www.cygwin.com/ Cygwin] is a POSIX compatibility layer for Windows. As such it enables compiling the way it would be done on Linux. Compiling in Cygwin is '''not recommended''' due to lower performance and increased installation complexity.

* Download [http://www.cygwin.com/setup.exe Cygwin] and install it, if not already done so. When installing, select following packages:
** from ''Devel'': ''cmake'', ''gcc'' and ''make''
** from ''Lib'': ''libidn-devel'', ''libpcre-devel'', ''readline'', ''zlib-devel''
* Running Cygwin Terminal will create folder <code>'''home/user'''</code> inside Cygwin installation folder, where ''user'' is the name currently logged on Windows user.
* SQL server needs to be installed in Cygwin so the compiler can access the SQL libraries. Download the .tar.gz archive from the [http://dev.mysql.com/downloads/mysql/?current_os=src MySQL website], such as '''mysql-5.5.20.tar.gz'''.
* Place the archive into <code>'''/home/user'''</code> and execute following inside Cygwin Terminal to unpack it:
cd ~
tar xvzf mysql-5.5.20.tar.gz
* Navigate to directory with unpacked archive:
cd mysql-5.5.20
* To avoid conficts, replace ''dtoa()'' with ''_dtoa()'' in ''strings/dtoa.c'' file:
sed -i 's/dtoa(/_dtoa(/g' ./strings/dtoa.c
* Build MySQL with following commands:
cmake .
make mysqlclient libmysql
make install
* After everything completes, Cygwin is ready for compiling Hercules. Navigate to the Hercules folder in Cygwin. Windows drives are accesible as <code>/cygdrive/x</code> where ''x'' is the letter assigned to the drive by Windows.
* Execute following commands inside Hercules folder to compile it:
./configure --with-mysql=/usr/local/mysql/bin/mysql_config
make sql
* If the compilation was successful, the resulting executables are in the Hercules folder named ''login-server_sql.exe'', ''char-server_sql.exe'' and ''map-server_sql.exe''.
* Server executables can be run inside Cygwin Terminal or directly, but in this case you need to copy required libraries to Hercules folder:
** ''cygwin1.dll'', ''cygz.dll'', ''cyggcc_s-1.dll'', ''cygpcre-0.dll'' from <code>/bin</code>
** ''cygmysqlclient-18.dll'' from <code>/usr/local/mysql/lib</code>

Compiling/Windows

2016-04-25T12:57:34Z

Haru: /* Using Visual Studio */ Updated Visual Studio versions and links

For compiling on Windows, Visual Studio is the preferred method, although using Cygwin is also possible.

=== Using Visual Studio ===
[[Image:Compile-hercules.PNG|thumb|300px|MS Visual Studio 2015: Compile configuration (red) and solution (blue) with it's child projects.]]
Hercules ships with solution and project files for Visual Studio from 2012 onwards.
* Download the latest version of [https://www.visualstudio.com Visual Studio] (at the time of writing, MS Visual Studio 2015 Community Edition) and install it, if you do not have Visual Studio already installed.
* Open '''Hercules-14.sln''' in your Hercules folder if you use Visual Studio 2015, for Visual Studio 2013, you need to open '''Hercules-12.sln''', for Visual Studio 2012, you need to open '''Hercules-11.sln''' instead.
* Select the desired compile configuration (marked red). Use '''Release''' when you compile the server, where players will be playing on. '''Debug''' compiles the server without optimizations and with debugging information.
* Right-click the solution node (marked blue) and select '''Build solution'''. If you have compiled the server before, it is recommended to use '''Rebuild solution''', as it forces the compiling of all components, not just those, which seem to have changed since last compile.
* If the compilation was successful, the resulting executables are in the same folder as the solution named ''login-server.exe'', ''char-server.exe'', ''map-server.exe'' and ''mapcache.exe''.

=== Using Cygwin ===
[http://www.cygwin.com/ Cygwin] is a Linux environment emulation for Windows. As such it enables compiling the way it would be done on Linux. Compiling in Cygwin is '''not recommended''' due to lower performance and increased installation complexity.

* Download [http://www.cygwin.com/setup.exe Cygwin] and install it, if not already done so. When installing, select following packages:
** from ''Devel'': ''cmake'', ''gcc'' and ''make''
** from ''Lib'': ''libidn-devel'', ''libpcre-devel'', ''readline'', ''zlib-devel''
* Running Cygwin Terminal will create folder <code>'''home/user'''</code> inside Cygwin installation folder, where ''user'' is the name currently logged on Windows user.
* SQL server needs to be installed in Cygwin so the compiler can access the SQL libraries. Download the .tar.gz archive from the [http://dev.mysql.com/downloads/mysql/?current_os=src MySQL website], such as '''mysql-5.5.20.tar.gz'''.
* Place the archive into <code>'''/home/user'''</code> and execute following inside Cygwin Terminal to unpack it:
cd ~
tar xvzf mysql-5.5.20.tar.gz
* Navigate to directory with unpacked archive:
cd mysql-5.5.20
* To avoid conficts, replace ''dtoa()'' with ''_dtoa()'' in ''strings/dtoa.c'' file:
sed -i 's/dtoa(/_dtoa(/g' ./strings/dtoa.c
* Build MySQL with following commands:
cmake .
make mysqlclient libmysql
make install
* After everything completes, Cygwin is ready for compiling Hercules. Navigate to the Hercules folder in Cygwin. Windows drives are accesible as <code>/cygdrive/x</code> where ''x'' is the letter assigned to the drive by Windows.
* Execute following commands inside Hercules folder to compile it:
./configure --with-mysql=/usr/local/mysql/bin/mysql_config
make sql
* If the compilation was successful, the resulting executables are in the Hercules folder named ''login-server_sql.exe'', ''char-server_sql.exe'' and ''map-server_sql.exe''.
* Server executables can be run inside Cygwin Terminal or directly, but in this case you need to copy required libraries to Hercules folder:
** ''cygwin1.dll'', ''cygz.dll'', ''cyggcc_s-1.dll'', ''cygpcre-0.dll'' from <code>/bin</code>
** ''cygmysqlclient-18.dll'' from <code>/usr/local/mysql/lib</code>

Compiling

2016-04-25T12:48:34Z

Haru: /* Make */

== Unix ==
=== Using configure & make ===
Configure and make are commands used commonly to configure, build and install Linux applications.
==== Configure ====
{{:Configure}}
==== Make ====
make sql
You should be now noticing that you have 3 new files: '''char-server''', '''map-server''', and '''login-server'''.
Make install is not yet supported.

=== Using cmake & make ===
[http://www.vtk.org/Wiki/CMake Cmake] is a cross-platform configure.

Start creating a new sub directory and move there
mkdir build
cd build

==== Building makefiles ====
Generate the make files by cmake
cmake -G"Unix Makefiles" -DINSTALL_TO_SOURCE=ON ..

<pre>
-- The C compiler identification is GNU
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting system MYSQL
-- Found MYSQL: /usr/lib/libmysqlclient.so (found version "5.1.58")
-- Detecting system MYSQL - done
-- Configuring for system MYSQL
-- Configuring for system MYSQL - done
-- Detecting system PCRE
-- Found PCRE: /usr/lib/i386-linux-gnu/libpcre.so (found version "8.12")
-- Detecting system PCRE - done
-- Configuring for system PCRE
...
-- Creating target login-server_sql
-- Creating target login-server_sql - done
-- Creating target char-server_sql
-- Creating target char-server_sql - done
-- Creating target map-server_sql
-- Enabled PCRE code
-- Creating target map-server_sql - done
-- Creating target mapcache
-- Creating target mapcache - done
-- Disabled dbghelpplug plugin target (requires WIN32 and HAVE_DBGHELP_H)
-- Available targets:
-- common_base
-- common_sql
-- login-server_sql
-- map-server_sql
-- mapcache
-- Configuring done
-- Generating done
-- Build files have been written to: /home/*/Hercules/build
</pre>

==== Compilation ====
Then compile
make install
<pre>
Scanning dependencies of target common_base
[ 1%] Building C object src/common/CMakeFiles/common_base.dir/__/__/3rdparty/mt19937ar/mt19937ar.c.o
[ 1%] Building C object src/common/CMakeFiles/common_base.dir/core.c.o
[ 2%] Building C object src/common/CMakeFiles/common_base.dir/db.c.o
[ 3%] Building C object src/common/CMakeFiles/common_base.dir/des.c.o
...
[ 98%] Building C object src/tool/CMakeFiles/mapcache.dir/__/common/grfio.c.o
[ 99%] Building C object src/tool/CMakeFiles/mapcache.dir/__/common/utils.c.o
[100%] Building C object src/tool/CMakeFiles/mapcache.dir/mapcache.c.o
...
-- Installing: ~/Hercules/./login-server_sql
-- Installing: ~/Hercules/./char-server_sql
-- Installing: ~/Hercules/./map-server_sql
-- Installing: ~/Hercules/./mapcache
</pre>
You'll see nice green output progression then finally login-server_sql, map-server_sql, char-server_sql, in main folder

== Windows ==
{{:Compiling/Windows}}

[[Category:Installation]]

Configure

2016-04-25T12:48:01Z

Haru:

Using '''configure''' script is a method to generate makefiles before compilation in Unix systems.

When installing Hercules, configure script should be run after [[Git Clone]] and before compiling.

== Basic usage ==
<onlyinclude><includeonly><blockquote>''Main article: [[Configure]].''</blockquote></includeonly>
To avoid errors in server-client communication, <code>[[PACKETVER]]</code> must be set to date the client you're going to use has been released at (in YYYYMMDD format), eg <code>20100730</code> for 2010-07-30aRagexeRE. Instead of editing [[mmo.h]] directly, <code>PACKETVER</code> can be set to desired date with configure switch <code>--enable-packetver=YYYYMMDD</code>.

Run following command, replacing ''YYYYMMDD'' with your client release date, eg ''20100730''.
./configure --enable-packetver=YYYYMMDD
Configure script will perform necessary tests and generate makefiles.
</onlyinclude>
=== Sample output ===
<pre>checking whether make sets $(MAKE)... yes
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ANSI C... none needed
checking how to run the C preprocessor... gcc -E
checking whether byte ordering is bigendian... no
checking whether pointers can be stored in ints (old code)... yes
checking whether gcc supports -Wno-unused-parameter... yes
checking whether gcc supports -Wno-pointer-sign... yes
checking whether gcc can actually use -Wno-pointer-sign... yes
checking whether gcc supports -Wno-switch... yes
checking whether gcc supports -fPIC... yes
checking whether gcc needs -fPIC for shared objects... no
checking whether gcc supports -fno-strict-aliasing... yes
checking whether gcc is able to typecast to union... yes
checking for setrlimit... yes
checking for strnlen... yes
checking for inflateEnd in -lz... yes
checking zlib.h usability... yes
checking zlib.h presence... yes
checking for zlib.h... yes
checking for library containing sqrt... -lm
checking for library containing clock_gettime... -lrt
checking whether CLOCK_MONOTONIC is supported and works... yes
checking for mysql_config... /usr/bin/mysql_config
checking for mysql_init in -lmysqlclient... yes
checking mysql.h usability... yes
checking mysql.h presence... yes
checking for mysql.h... yes
checking MySQL library (optional)... yes (5.0.51a)
checking for pcre_study in -lpcre... yes
checking PCRE library (optional)... yes
checking host OS... Linux
checking for MinGW... no
configure: creating ./config.status
config.status: creating Makefile
config.status: creating src/common/Makefile
config.status: creating 3rdparty/mt19937ar/Makefile
config.status: creating src/char/Makefile
config.status: creating src/login/Makefile
config.status: creating src/char_sql/Makefile
config.status: creating src/txt-converter/Makefile
config.status: creating src/map/Makefile
config.status: creating src/plugins/Makefile
config.status: creating src/tool/Makefile</pre>
=== Setting executable bit ===
In order to run configure script it must be executable, ie have the ''execute'' permission set. When checking out a working copy from a git repository repository, executable bit should be set automatically. However, if it fails for some reason, running <code>./configure</code> will bring the following message (or similar):
bash: ./configure: Permission denied
To fix this, set executable permission with:
chmod +x ./configure

== Additional switches ==
To display all available switches use:
./configure --help

=== Debug mode ===
It is possible to compile Hercules in debug mode with <code>--enable-debug</code> switch.
[[Category:Installation]]

NPC

2016-04-25T12:33:19Z

Haru: Corrected forum URL

[[Image:Kafra2.gif|thumb|[[Kafra]] NPC]]
[[NPC]] stands for Non-Player (or playable) Character. An NPC is any person or "living" creature in a game not controlled by a player. For example, any units in any game that would give you a quest, tell you what to do, or just stand there while you speak to them is considered an NPC.

In [[Ragnarok Online]], NPCs are a pretty big part of the game. The [[Hercules]] scripting language is used to create NPCs. You can find many premade NPCs on the [http://herc.ws/board/ Hercules Boards]. Any character you speak to in Ragnarok Online not controlled by a player is an NPC. From warpers, over healers and quest guides, to item sellers. Generally, in Ragnarok Online, a monster is referred to as a [[mob]], and not an NPC, however they are technically considered NPCs as well.

==See also==
* [[Adding a Script|Adding a NPC script]]
* [[Basic Scripting]]

==External Links==
* [http://herc.ws/board/ Hercules Boards]
* [http://img476.imageshack.us/img476/6914/npcs7bh.jpg ID and images of RO Sprites]
* http://kalen.s79.xrea.com/npc/npc.shtml
* http://nn.nachtwolke.com/dev/npclist/

[[Category:Basics]]

Import folder

2016-04-25T12:26:55Z

Haru: /* How it works */ removed references to svn

=Import folder Introduction=
The Import Folder is used to import virtually all of your configuration changes and settings into the core of the Hercules emulator without ever making changes to any .conf files after it is initially configured. This is very helpful when Creating a New Server Build, Compiling , or Updating to the Latest version this will allow retention of all the settings you previously configured without having to deal with possible overwrite conflicts from a git pull or change over to a New Server Build.

=How it works=
So, It works as such; Once you have configured all of the files you wish to configure within the Conf directory of your server side you will take those same settings and copy them to the corresponding import directory files. For Example: Lets say you make the following changes to;

'''conf/battle/client.conf''' ---> Make your desired changes, in this case we are changing hair and dye settings.
// Valid range of dyes and styles on the client.
min_hair_style: 0
max_hair_style: 27 ----> Changing to 40
min_hair_color: 0
max_hair_color: 8 ----> Changing to 200
min_cloth_color: 0
max_cloth_color: 4 ----> Changing to 100

'''conf/battle/client.conf''' ---> We then simply copy only the changed setting lines into ---> conf/import/client_conf.txt

max_hair_style: 40
max_hair_color: 200
max_cloth_color: 100

Since these three settings were the only ones we changed in this example these are the only configuration lines to copy from the .conf file into the corresponding import.txt file. This will now allow the server to directly import these changed settings. This can be done with any of the configuration files. The server reads .confs files within the conf directory first, however any settings configured within the /import/ folder will be read second, thus overwriting default settings. Please note over time settings have changed, so please compare Import.txt Files to any New Server Configuration Settings.

=Commonly Imported Settings=

The most common use of these files is for the following parameters: 
'''/conf/login_athena.conf''' -> /conf/import/login_conf.txt
login_port: 6900
account.engine: auto
account.sql.db_hostname: 127.0.0.1
account.sql.db_port: 3306
account.sql.db_username: ragnarok
account.sql.db_password: ragnarok
account.sql.db_database: ragnarok

'''/conf/char_athena.conf''' -> /conf/import/char_conf.txt
userid: s1
passwd: p1
server_name: Hercules
login_port: 6900
char_ip: 127.0.0.1
char_port: 6121
start_point: new_1-1,53,111

'''/conf/map_athena.conf''' -> /conf/import/map_conf.txt
userid: s1
passwd: p1
char_ip: 127.0.0.1
char_port: 6121
map_ip: 127.0.0.1
map_port: 5121

'''/conf/inter_athena.conf''' -> /conf/import/inter_conf.txt
sql.db_hostname: 127.0.0.1
sql.db_port: 3306
sql.db_username: ragnarok
sql.db_password: ragnarok
sql.db_database: ragnarok
char_server_ip: 127.0.0.1
char_server_port: 3306
char_server_id: ragnarok
char_server_pw: ragnarok
char_server_db: ragnarok
map_server_ip: 127.0.0.1
map_server_port: 3306
map_server_id: ragnarok
map_server_pw: ragnarok
map_server_db: ragnarok
log_db_ip: 127.0.0.1
log_db_port: 3306
log_db_id: ragnarok
log_db_pw: ragnarok
log_db_db: ragnarok
log_login_db: loginlog
use_sql_db: no

=Conclusion=
The Import Folder is a powerful tool and is often overlooked by amateur developers, but it saves a lot of time and effort it is highly recommended to use. The import.txt files can be saved and used in any new build, just ensure you double check the pathways and corresponding configuration settings. The import folder is often incomplete or blank when downloading latest revisions, you will have to add the necessary files or overwrite the blank template files.

[[Category:Configuration]]

Import folder

2016-04-25T12:26:31Z

Haru: /* Import folder Introduction */ removes svn references

=Import folder Introduction=
The Import Folder is used to import virtually all of your configuration changes and settings into the core of the Hercules emulator without ever making changes to any .conf files after it is initially configured. This is very helpful when Creating a New Server Build, Compiling , or Updating to the Latest version this will allow retention of all the settings you previously configured without having to deal with possible overwrite conflicts from a git pull or change over to a New Server Build.

=How it works=
So, It works as such; Once you have configured all of the files you wish to configure within the Conf directory of your server side you will take those same settings and copy them to the corresponding import directory files. For Example: Lets say you make the following changes to;

'''svn/conf/battle/client.conf''' ---> Make your desired changes, in this case we are changing hair and dye settings.
// Valid range of dyes and styles on the client.
min_hair_style: 0
max_hair_style: 27 ----> Changing to 40
min_hair_color: 0
max_hair_color: 8 ----> Changing to 200
min_cloth_color: 0
max_cloth_color: 4 ----> Changing to 100

'''svn/conf/battle/client.conf''' ---> We then simply copy only the changed setting lines into ---> svn/conf/import/client_conf.txt

max_hair_style: 40
max_hair_color: 200
max_cloth_color: 100

Since these three settings were the only ones we changed in this example these are the only configuration lines to copy from the .conf file into the corresponding import.txt file. This will now allow the server to directly import these changed settings. This can be done with any of the configuration files. The server reads .confs files within the conf directory first, however any settings configured within the /import/ folder will be read second, thus overwriting default settings. Please note over time settings have changed, so please compare Import.txt Files to any New Server Configuration Settings.

=Commonly Imported Settings=

The most common use of these files is for the following parameters: 
'''/conf/login_athena.conf''' -> /conf/import/login_conf.txt
login_port: 6900
account.engine: auto
account.sql.db_hostname: 127.0.0.1
account.sql.db_port: 3306
account.sql.db_username: ragnarok
account.sql.db_password: ragnarok
account.sql.db_database: ragnarok

'''/conf/char_athena.conf''' -> /conf/import/char_conf.txt
userid: s1
passwd: p1
server_name: Hercules
login_port: 6900
char_ip: 127.0.0.1
char_port: 6121
start_point: new_1-1,53,111

'''/conf/map_athena.conf''' -> /conf/import/map_conf.txt
userid: s1
passwd: p1
char_ip: 127.0.0.1
char_port: 6121
map_ip: 127.0.0.1
map_port: 5121

'''/conf/inter_athena.conf''' -> /conf/import/inter_conf.txt
sql.db_hostname: 127.0.0.1
sql.db_port: 3306
sql.db_username: ragnarok
sql.db_password: ragnarok
sql.db_database: ragnarok
char_server_ip: 127.0.0.1
char_server_port: 3306
char_server_id: ragnarok
char_server_pw: ragnarok
char_server_db: ragnarok
map_server_ip: 127.0.0.1
map_server_port: 3306
map_server_id: ragnarok
map_server_pw: ragnarok
map_server_db: ragnarok
log_db_ip: 127.0.0.1
log_db_port: 3306
log_db_id: ragnarok
log_db_pw: ragnarok
log_db_db: ragnarok
log_login_db: loginlog
use_sql_db: no

=Conclusion=
The Import Folder is a powerful tool and is often overlooked by amateur developers, but it saves a lot of time and effort it is highly recommended to use. The import.txt files can be saved and used in any new build, just ensure you double check the pathways and corresponding configuration settings. The import folder is often incomplete or blank when downloading latest revisions, you will have to add the necessary files or overwrite the blank template files.

[[Category:Configuration]]

Custom Items

2016-04-25T12:25:38Z

Haru: /* Item Script */ removed references to svn

=Structure=
First, let's take a look at the item_db.conf in the db folder, and its structure:
item_db: (
{
// =================== Mandatory fields ===============================
Id: ID (int)
AegisName: "Aegis_Name" (string, optional if Inherit: true)
Name: "Item Name" (string, optional if Inherit: true)
// =================== Optional fields ================================
Type: Item Type (int, defaults to 3 = etc item)
Buy: Buy Price (int, defaults to Sell * 2)
Sell: Sell Price (int, defaults to Buy / 2)
Weight: Item Weight (int, defaults to 0)
Atk: Attack (int, defaults to 0)
Matk: Magical Attack (int, defaults to 0, ignored in pre-re)
Def: Defense (int, defaults to 0)
Range: Attack Range (int, defaults to 0)
Slots: Slots (int, defaults to 0)
Job: Job mask (int, defaults to all jobs = 0xFFFFFFFF)
Upper: Upper mask (int, defaults to any = 0x3f)
Gender: Gender (int, defaults to both = 2)
Loc: Equip location (int, required value for equipment)
WeaponLv: Weapon Level (int, defaults to 0)
EquipLv: Equip required level (int, defaults to 0)
EquipLv: [min, max] (alternative syntax with min / max level)
Refine: Refineable (boolean, defaults to true)
View: View ID (int, defaults to 0)
BindOnEquip: true/false (boolean, defaults to false)
Script: <"
Script
(it can be multi-line)
">
OnEquipScript: <" OnEquip Script (can also be multi-line) ">
OnUnequipScript: <" OnUnequip Script (can also be multi-line) ">
// =================== Optional fields (item_db2 only) ================
Inherit: true/false (boolean, if true, inherit the values
that weren't specified, from item_db.conf,
else override it and use default values)
},
...
)

* '''ID''': ID of the item.
* '''AegisName''': Server name to reference the item in scripts and lookups, should use no spaces.
* '''Name''': Name in English for displaying as output for @ and script commands.
* '''Type''': Purpose of the item.
0 = Usable : healing
2 = Usable : other
3 = Misc
4 = Weapon
5 = Armor
6 = Card
7 = Pet Egg
8 = Pet Equipment
10 = Arrow/Ammunition
11 = Usable : delayed consumption (items with script "pet" or "itemskill")
18 = Another delayed consume that requires user confirmation before using item.
* '''Buy''': Default [[NPC]] buying price in Zeny. When not specified, becomes double the sell price.
* '''Sell''': Default [[NPC]] selling price in Zeny. When not specified, becomes half the buy price.
* '''Weight''': Item's weight. Each 10 is 1 weight. When not specified, becomes 0.
* '''ATK''': Base weapon attack, in case of a weapon. When not specified, becomes 0.
** In '''RE''' enabled servers this field have a optional delimiter ''':''' to define this item's weaponMATK bonus, for example, '''30:50''' would mean the item gives 30 atk and 50 weaponMATK
* '''Matk''': Weapon's magical attack (only used in renewal mode, ignored in pre-renewal). When not specified, becomes 0.
* '''DEF''': Base defense for armor-type items. When not specified, becomes 0.
* '''Range''': Maximum range in map cells a weapon allows to be the player apart from it's target. When not specified, becomes 0.
* '''Slots''': Amount of card slots in weapon/armor-type items. When not specified, becomes 0.
* '''Job''': Which jobs this item is available for. Values below can be combined to achieve availability for multiple job classes, i. e. <code>0x2|0x4 -> 0x6</code> (Swordman+Mage)
(S.) Novice (2^00): 0x00000001
Swordman (2^01): 0x00000002
Mage (2^02): 0x00000004
Archer (2^03): 0x00000008
Acolyte (2^04): 0x00000010
Merchant (2^05): 0x00000020
Thief (2^06): 0x00000040
Knight (2^07): 0x00000080
Priest (2^08): 0x00000100
Wizard (2^09): 0x00000200
Blacksmith (2^10): 0x00000400
Hunter (2^11): 0x00000800
Assassin (2^12): 0x00001000
''Unused'' (2^13): 0x00002000
Crusader (2^14): 0x00004000
Monk (2^15): 0x00008000
Sage (2^16): 0x00010000
Rogue (2^17): 0x00020000
Alchemist (2^18): 0x00040000
Bard/Dancer (2^19): 0x00080000
''Unused'' (2^20): 0x00100000
Taekwon (2^21): 0x00200000
StarGladiator (2^22): 0x00400000
Soul Linker (2^23): 0x00800000
Gunslinger (2^24): 0x01000000
Ninja (2^25): 0x02000000
Gangsi (2^26): 0x04000000
Death Knight (2^27): 0x08000000
Dark Collector (2^28): 0x10000000
Kagerou/Oboro (2^29): 0x20000000
Rebellion (2^30): 0x40000000
'''Some other commonly used values:'''
All Classes : 0xFFFFFFFF
Every Job Except Novice : 0xFFFFFFFE
* '''Upper''': Specifies whether the item can be used by normal, baby or reborn classes. Values below can be combined, i. e. <code>1|4 -> 5</code> (Normal+Baby Classes)
** Note: Setting <code>2</code> enables the item for Transcendant and 3rd classes. Use <code>8</code> to enable the item for 3rd classes only.
Normal jobs: 0x01 (1)
Upper jobs: 0x02 (2)
Baby jobs: 0x04 (4)
Third jobs: 0x08 (8)
Upper Third jobs: 0x10 (16)
Baby Third jobs: 0x20 (32)

Under pre-re mode third classes are considered upper, making use of
the 8 and above masks is therefore not necessary unless in renewal
mode. When no value is specified, all classes (mask 0x3f) are able to
equip the item.
* '''Gender''': Gender restriction for the item.
0 = Female
1 = Male
2 = No restriction (both)
* '''Loc''': Equipment location of armor and arrow-type items. Values below can be combined, i. e. 136 would indicate both accessory slots (typical value for accessories).
(2^0) 1 = Lower headgear
(2^1) 2 = Right hand
(2^2) 4 = Mantle
(2^3) 8 = Accessory 1
(2^4) 16 = Armor
(2^5) 32 = Left hand
(2^6) 64 = Shoes
(2^7) 128 = Accessory 2
(2^8) 256 = Upper headgear
(2^9) 512 = Middle headgear
(2^10) 1024 = Costume Top Headgear
(2^11) 2048 = Costume Mid Headgear
(2^12) 4096 = Costume Low Headgear
(2^13) 8192 = Costume Garment/Robe
(2^15) 32768 = Arrow (arrow-type items only)
(2^16) 65536 = Shadow Armor
(2^17) 131072 = Shadow Weapon
(2^18) 262144 = Shadow Shield
(2^19) 524288 = Shadow Shoes
(2^20) 1048576 = Shadow Accessory 2
(2^21) 2097152 = Shadow Accessory 1
* '''WeaponLv''': Weapon level of an item (1-4), Becomes 0 when not specified.
* '''EquipLv''': Base level required to be able to equip. It is possible to specify two values, if an item has a maximum level, by using the following syntax:
EquipLv: [minLv, maxLv]

If only one value is specified, maxLv becomes the current server's
MAX_LEVEL. If no values are specified, minLv becomes 0.
* '''Refineable''': Whether the item is available for refining (1) or not (0). If no value is specified, it defaults to true.
* '''View''': For normal items, defines a replacement view-sprite for the item
:(eg: Making apples look like apple juice). The special case are weapons and ammo where this value indicates the weapon-class of the item.
** Weapon-type items:
**# Daggers
**# One-Handed Swords
**# Two-Handed Swords
**# One-Handed Spears
**# Two-Handed Spears
**# One-Handed Axes
**# Two-Handed Axes
**# Maces
**# ''(not used)''
**# Wand/Staff
**# Bows/Crossbows
**# Knuckle Weapons
**# Musical Instruments
**# Whips
**# Books
**# Katars
**# Revolvers
**# Rifles
**# Shotguns
**# Gatling guns
**# Grenade launchers
**# Fuuma shuriken
** Shield-type items:
**# Guard, Novice Guard
**# Buckler
**# Shield, Holy Guard, Evangelist
**# Mirror Shield
** Ammunition-type items:
**# Arrows
**# Throw-able daggers
**# Bullets
**# Shells
**# Grenades
**# Shuriken
**# Kunai
**# Cannonballs
**# Throwable Items (Sling Item)
** Headgear-type items: Please see the View IDs section of this guide.
* '''BindOnEquip''': Whether the item will automatically bind to the character when it is equipped for the first time.
:An item that has this field set, will display a confirmation dialog the first time it is equipped, and, if accepted, the item will become character-bound.
* '''Script''': This is where you put your item bonus. Whether it's an usable item or an equip item, it will take effect according to the item type.
* '''OnEquip_Script''': Script to execute when the item is equipped. Warning, not all item bonuses will work here as expected.
* '''OnUnequip_Script''': Script to execute when the item is unequipped. Warning, not all item bonuses will work here as expected.
* '''Inherit''': This can be used only in item_db2.conf, and if set to true, and the item already exists in item_db.conf,
:all the missing fields will be inherited from there rather than using their default values.
 
In the doc folder look for a text file called "item_bonus", it shows all the scripts items can have and how they work.
 
For more information about this structure read [http://hercules.ws/board/topic/2954-item-db-file-structure-overhaul/ Item DB file structure overhaul]

=Defining Item clientside (Renewal Clients <= 2012-04-10a & Main Clients <= 2012-07-10a) =
After you make your item, put it in your item_db2.txt, so that you will not run into conflicts when updating your repository later. Then go to your data folder and modify the following files, one after another.

==idnum2itemdisplaynametable.txt==
This file holds the item names, as displayed inside the client. Each item added as:
ItemID#ItemName#
ItemID is the number from your ID column inside the item db. If your item name contains spaces, replace those with _ (underscore).

==idnum2itemdesctable.txt==
This file contains the description of your item, when it is right-clicked. The syntax for an item is:
ItemID#
Item Description Line 1
Item Description Line 2
#
You can use any amount of lines for the description. If your description contains a #, make sure it is followed by a space character.
==idnum2itemresnametable.txt==
This file sets the inventory and drop-sprite for an the item. Item is defined as follows:
ItemID#SpriteName#
The SpriteName is the name of the files in collection and item folders inside texture and the ones inside sprite folder. If you want to use the look of an another item, search for it's id and copy the sprite name from there.
==itemslotcounttable.txt==
In this file you set the amount of visible slots for the item. You do not need to add 0 slot items or items, which do not have slots at all (i. e. usable items). Syntax:
ItemID#NumberOfSlots#
NumberOfSlots should be a number from 1-4, larger values might have undesired effects.
==Files for non-identified items==
The following files specify the name, description and look for items, which have not yet been identified. Their syntax follows the same rules as for the files with ''idnum'' prefix. Normally the same text is entered for non-equipment and generic description (which can be copied from official items) is used for equipment of all sorts (weapons, armor, headgears).
* num2itemdesctable.txt
* num2itemdisplaynametable.txt
* num2itemresnametable.txt

=Defining Items clientside (For New Clients)=
If your client date is newer than specified above then you need to specify all the above item information in 1 file

==System/ItemInfo.lub==
Since ItemInfo.lub is compiled, you need to decompile it to lua , add your customs and recompile back to lub file (Some have said that renaming a decompiled file to lub also works)
Syntax:
[<item id>] = {
unidentifiedDisplayName = <item name to show when not magnified>,
unidentifiedResourceName = <file name prefix used for all the images and drop sprite when not magnified>,
unidentifiedDescriptionName = { <comma separated list of strings>,<to get multiple lines>,<in item description> },
identifiedDisplayName = <item name to show when magnified>,
identifiedResourceName = <file name prefix used for all the images and drop sprite when magnified>,
identifiedDescriptionName = { <same format as unidentifiedDescriptionName but for magnified items> },
slotCount = <number of slots>,
ClassNum = <View ID - yes the same one that was there item_db>
},
For Weapons, ClassNum = View ID specified in Weapon_IDs table (inside weapontable.lub file). Look [[Custom_Items#Weapon_Sprite_Solution_.28For_New_Clients.29|below]] for details.

You can also put the different values in DescriptionName in separate lines.

Example: Lets say i want to add a weapon to item id 25000 - a One handed sword named Devastator with 3 slots & the image files & drop sprite files are all named Black_Sword.* . Also i want to display a Sword when not magnified.

[25000] = {
unidentifiedDisplayName = "Sword",
unidentifiedResourceName = "¼Òµå",
unidentifiedDescriptionName = { "Unidentified item, can be identified with [Magnifier]." },
identifiedDisplayName = "Devastator",
identifiedResourceName = "Black_Sword",
identifiedDescriptionName = {
"An Unholy Sword that was created with the sole purpose of destruction",
"Class :^777777 Sword^000000",
"Attack :^777777 325^000000",
"Weight :^777777 80^000000",
"Weapon Level :^777777 4^000000",
"Required Level :^777777 100^000000",
"Applicable Job :^777777 Novice, Swordsman Class, Merchant Class, Thief Class^000000"
},
slotCount = 3,
ClassNum = 2
},

= Allocating Items on Client Side =
Your custom item will have 4 (6 in case its a headgear or garment) files:
1) Drop sprite -> Helmet_drop.spr
2) Drop act file -> Helmet_drop.act
3) Item Inventory image -> Helmet_item.bmp
4) Item Collection image -> Helmet_collection.bmp (the one you see on its description window)
5) Headgear View sprite -> Helmet.spr
6) Headgear View act file -> Helmet.act

Lets say i downloaded a custom item called Helmet which serves as a headgear and the above six files were in them.

==Step 1:==
We place the first four files based on what we specified in id2numresnametable.txt (IdentifiedResourceName in Iteminfo.lub).
For our example lets say i used "Helmet" as the resource name :
i) Copy Helmet_drop.spr to [RO Folder]\data\sprite\¾ÆÀÌÅÛ\Helmet.spr
ii) Copy Helmet_drop.act to [RO Folder]\data\sprite\¾ÆÀÌÅÛ\Helmet.act
iii) Copy Helmet_item.bmp to [RO Folder]\data\texture\À¯ÀúÀÎÅÍÆäÀÌ½º\item\Helmet.bmp
iv) Copy Helmet_collection.bmp to [RO Folder]\data\texture\À¯ÀúÀÎÅÍÆäÀÌ½º\collection\Helmet.bmp
==Step 2 (only for Headgears):==
For displaying headgear on the character there will be two additional files (sprite & act) or 4 if the sprite author intended for a separate set of files for male & female. In my example i have considered the first scenario.

The filename for headgear sprite are now specified in accname.lua file (details of which is available in the [[Custom_Items#View_IDs.2C_Having_A_Custom_Headgear_Without_Xray|View IDs Section]])

lets say i used
[ACCESSORY_IDs.HELMET] = "_Helmet",
then we need to:
i) Copy Helmet.spr to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\¿©\¿©_Helmet.spr (Female)
ii) Copy Helmet.act to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\¿©\¿©_Helmet.act
iii) Copy Helmet.spr to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\³²\³²_Helmet.spr (Male)
iv) Copy Helmet.act to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\³²\³²_Helmet.act

Now it is ready to be used provided you have added entries properly to the lua files.

==Specifications of the files==
1) Drop sprites - ideally have 1 frame & its act file will be just an empty act (only header will be there inside)

2) Equip sprites - typically have 3+ frames to show images for various orientations & its act file will have the info on where to place each frame.

3) Item bmp - 24x24 size 256 bit bmp file.

4) Collection bmp - 75x100 size bmp file (usually 256 bit but there is no restriction)

How to differentiate between sprite files?

Open both sprite files in [http://ratemyserver.net/download_agent.php?type=1&file_num=10 Spr Conview]. The number of frames in the files can be seen at bottom (Sprite: <currentframe>/<total>). If it says Sprite: 1/1 then its a drop sprite and the other is equip sprite.

Sometimes what sprite authors do is they simply copy the original sprite itself to make a drop sprite. In this case you will see both of them as identical when opened in Spr Conview & we don't need to worry about which one is which (since they are the same).

If the process confused you, [http://www.mediafire.com/?8lzt4cbot100w44 here is an example folder], the sprite is done by drkangel. The folder is virus free.

= View IDs, Having A Custom Headgear Without Xray =
Look in your data folder and make sure there is a folder named "lua files", if there is not make it.[http://svn6.assembla.com/svn/ClientSide/Lua_Project/lubs/ Download the most recent lub package] and extract it to your lua files folder in your data folder. [http://svn6.assembla.com/svn/ClientSide/Lua_Project/lua%20files/datainfo/ Download the most recent accname.lua and accessoryid.lua], put it in your datainfo folder that is inside the lua files folder. Now download [http://svn6.assembla.com/svn/ClientSide/Lua_Project/tool/luac5.0.2.exe this lub compiling tool], and put it in the datainfo folder.
Now, Open accessoryid.lua in the datainfo folder with notepad or a text editor of your choice, go all the way down until the names stop. Add your custom gears before the } symbol. You should use a high number just like with your custom item's database ID, or use unused IDs to be sure you won't have to redo them all in the future, or at least for a while. Example:
ACCESSORY_PINKBUNNY_HAIRBAND = 663,
ACCESSORY_GREENBUNNY_HAIRBAND = 664,
ACCESSORY_OLD_ELFEAR = 665,
ACCESSORY_THA_MAERO_MASK = 666,
ACCESSORY_THANATOS_MAI_MASK = 667,
--668 free
ACCESSORY_FISHPIN = 669,
ACCESSORY_CUSTOM_HAT = 900,
}

''You must compile to lub if you leave space between IDs, if you don't plan on compiling to lub, make sure you do not skip any numbers.''

Now open accname.lua, do basically the same thing but just in a different way, and for the sprite. Add your item to the bottom, have it look like the ones above it, except have your items name and the item's sprite name.
[ACCESSORY_IDs.ACCESSORY_PINKBUNNY_HAIRBAND] = "_ÇÎÅ©Åä³¢¸Ó¸®¶ì",
[ACCESSORY_IDs.ACCESSORY_GREENBUNNY_HAIRBAND] = "_±×¸°Åä³¢¸Ó¸®¶ì",
[ACCESSORY_IDs.ACCESSORY_OLD_ELFEAR] = "_°í´ë¿äÁ¤ÀÇ±Í",
[ACCESSORY_IDs.ACCESSORY_THA_MAERO_MASK] = "_Å¸³ªÅä½ºÀÇ½½ÇÄ°¡¸é",
[ACCESSORY_IDs.ACCESSORY_THANATOS_MAI_MASK] = "_Å¸³ªÅä½ºÀÇÁõ¿À°¡¸é",
[ACCESSORY_IDs.ACCESSORY_FISHPIN] = "_¹°°í±âÇÉ",
[ACCESSORY_IDs.ACCESSORY_CUSTOM_HAT] = "_Sprite_Name_Here",
}
Delete the accname.lub and accessoryid.lub. Now that you are done, make sure luac.exe is in your datainfo folder, right click the luac.exe, create a shortcut, right click the shortcut, and click properties, in the target area, add right after the quotes, with the quotes:
-o "accessoryid.lub" "accessoryid.lua"
So that it looks something like this:
"C:\Program Files (x86)\Gravity\RO\data\lua files\datainfo\luac5.0.2.exe" -o "accessoryid.lub" "accessoryid.lua"
Do this also to "accname.lub" except instead of accessoryid in the quotes, do accname. If there is any lua file leftover, you may want to move it somewhere else just for future changes, like My Documents. For future reference, this is also how you turn the other lub files to lua files.

=Modifications=
==Sprite Replacement==
To replace a headgear with your customized headgear, just delete one of the items you want, and replace your customised item ID with that id.

Lets say you have something like this:
15000,Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}
And there's an item you wont need, such as:
2220,Hat,Hat,5,1000,,200,,2,,0,10477567,2,256,,0,1,16,{},{},{}
Well, to replace it, just delete everything in the hat line but its ID, and paste there your custom item, all the line but the ID. Should be like this:
'''2220''',Hat,Hat,5,1000,,200,,2,,0,10477567,2,256,,0,1,16,{},{},{}
15000,'''Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}'''
'''2220,Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}'''
All you need to do now is changing the View ID to the Hat, and change your file names to its name. You can find them on the idnum2resnametable.txt Search for 2220 and the gibberish besides it, w/o the # # is the file name, then rename it to your custom item name.

Remember to add the files to data\sprite\¾ÆÀÌÅÛ (Icon sprite) and both data\sprite\¾Ç¼¼»ç¸®\³² (Male Item Sprite) and data\sprite\¾Ç¼¼»ç¸®\¿© (Female Item Sprite). Remember, these 2 last item names, must have either a ³²_ for male or ¿©_ for female, at the beginning of the name, both .spr and .act. Also, don't forget to change the other files:

idnum2itemdisplaynametable.txt , idnum2itemdesctable.txt , idnum2itemdesctable.txt , num2itemdesctable.txt , num2itemdisplaynametable.txt , num2itemresnametable.txt and itemslotcounttable.txt

Use these files if you want to replace sprites, they will be useful.
* '''actOR:''' with the actor you modify the act file, which is the one who tells the client where does the weapon go and what does it have to do and at a certain moment.
* '''SPR Conview:''' you can use these to view which sprite is which, and also see sequence per sequence.

==Item Restrictions==
Look on your db folder for a file called item_trade.txt and open it

Now, the pattern for a flag is:

Item ID, TradeMask, GM-Level Override

* '''Item ID''': the ID of your item.
* '''TradeMask''': Testrictions the item will have, such as being dropped, stored or traded. These values can be combined to achieve multiple effects.
1:Item can't be dropped
2:Item can't be traded (nor vended)
4:Item can only be traded with wedded partner
8:Item can't be sold to NPCs
16:Item can't be placed in the cart
32:Item can't be placed in the storage
64:Item can't be placed in the guild storage
* '''GM-Level Override''': This is the minimum GM level a player must have to avoid these restrictions.

==Item Script==
{{duplication
|type=section
|what=[[itemskill]], [[sc_start]] and [[skilleffect]]}}
{{disputed
|type=section
|date=September 2010}}
Okay, I'll update this as I go; otherwise, I wont have anything new to show. First with usable items.

Well, there are 3 types of usables:

1.- Healing items, they have in the type field a 0.

2.- Other uses items, such as fly wings and so, which doesn't heal, but does have an instant effect, they have in the type field a 2.

3.- Usable items, which are skills that requires a target selection, therefore they have a delayed use, and in newer versions the item wont be gone until the target is chosen and the cast has finished. Means, you wont lose the item if the skill hasn't been done. They have in the type field an 11.

Now, for an item skill, the pattern for a skill is:
itemskill <skill id>,<skill level>;
Without <> of course.

Now, we go to our db\skill_db.txt and search for the blessing ID, searching for AL_ or blessing, but first, the structure of a skill:
id,range,hit,inf,element,nk,splash,max,list_num,castcancel,cast_defence_rate,inf2,maxcount,skill_type,blow_count,name,description
Now, the AL_BLESSING or Blessing Skill:
34,9,6,16,0,0x1,0,10,1,yes,0,0,0,magic,0, AL_BLESSING,Blessing
We grab the ID and put it on our code:
itemskill 34,<skill lvl>;
Don't mind the actual level of the skill_db.txt for the skill level part. You can actually put the level you want here below 99, so lets pick 4:
itemskill 34,4;
And finally, insert it on the code.
<pre>,{ itemskill 34,4; },{},{}</pre>

There, we have a Lvl 4 Blessing item skill.

Remember, one space before and one after the script, NOT TAB!

And so on with other skills. Just remember these steps and they should be fine. And remember, itemskill is NOT the same as skill. itemskill will make you CAST that skill, while skill will GIVE you the skill. If you give an item, whether delayed use or normal usable two itemskill commands, only the latter will come into effect, as you cannot cast two skills at the same time.

Now, for Potions.

Instead of using itemskill, we will use itemheal:
,{ itemheal 100,0; },{},{}
The green is the HP, the blue is the SP. To add that random heal amount effect, just pick a set amount, let's say 120, then pick 1 or 2 numbers, up to you. Then, add the rand() command, like this:
,{ itemheal rand(120,9,49),0; },{},{}
Explanation: This item will heal about 49~120 hp and 0 SP. To heal SP you change the 0 to a number. Like this:
,{ itemheal rand(120,9,49),50; },{},{}
It will now heal 50 SP.
Now, for skilleffect and sc_start.

Okay, let's see. Here's a example of an item casting a skill and simulating a skill.
,{ itemskill 34,10; skilleffect 29,0; sc_start 12,140000,5; },{},{}
skilleffect will display on your client a skill visual effect. The pattern is:

skilleffect <skill ID>,<number>;

;skill ID
:Self-explanatory.
;number
:Have you seen those skills that shows up numbers upon casting? Such as heal? Well, putting a number there will display it. But only works on skills with numbers floating.

sc_start has the following pattern:

sc_start <status id>,<duration>,<val1>[,<unit id>];

;status id
:Refer to const.txt in your db folder for all effects. Open it with a text editor then search by either clicking edit, then find, or press and hold the ctrl key, and while still holding it press the f key, then release, and search for "SC_ALL -1". Everything below this is an effect. The effects stop at "e_gasp 0" which are emoticons.
;duration
:Is the amount time in milliseconds (1000 msec = 1 sec) that the status will be active.
;val1
:Typically it's the level of the skill, associated with this status.
;unit id
:Allows to start the status on an other unit, than the attached player. For players this is account id. This parameter is optional, and can be omitted.

Now, for the item I said, it will show you the visual effect of Blessing and cast on you a lvl 5 Agi-Up! skill for 140 seconds.

For more item scripts see script_commands.txt in your doc folder, as well as item_bonus.txt in your doc folder.

==Weapon Sprite Solution (Renewal Clients <= 2012-04-10a & Main Clients <= 2012-07-10a)==
For these clients, Weapons are limited to use a range of Item IDs hardcoded in the clientn for each type.
For e.g.

1265,Bloody_Roar,Bloody Roar,4,,10,1000,120,,1,0,4096,7,2,34,4,75,1,16,{ bonus bIgnoreDefRace,RC_DemiHuman; bonus bFlee,-160; bonus bFlee2,-160; bonus bNoRegen,1; bonus bNoRegen,2; },{},{}
1266,Test,Test,4,4000,2000,10,165,,1,0,4096,7,2,34,3,33,1,16,{}

// 1-Handed Axes
1301,Axe,Axe,4,500,,800,38,,1,3,8803555,7,2,2,1,3,1,6,{}

Here the item 1266 is a custom katar and it does show up as a katar (if you have the proper sprite files ofcourse). but if i use some id like say 22000, client wont display it. So what is the range of item ids you can use? Look below:

* One handed Swords = 1100-1149, 13400-13499
* Two handed Swords = 1150-1199, 21000-21999

* Knives, Daggers etc = 1200-1249, 13000-13099
* Katars = 1250-1299 ; Has 35 free IDs

* One handed Axes = 1300-1349; Has 43 free IDs
* Two handed Axes = 1350-1399; Has 32 free IDs

* One handed Spears = 1400-1449; Has 34 free IDs
* Two Handed Spears = 1450-1471, 1474-1499

* Maces = 1500-1549, 16000-16999
* Books = 1550-1599 ; Has only 2 IDs.
* Knuckles = 1800-1899 ; Has 95 free IDs

* One Handed Staves/Rods = 1600-1699; Has 79 free IDs
* Two Handed Staves/Rods = 1472,1473,2000-2099

* Bows = 1700-1749, 18100-18499
* Guitars = 1900-1949 ; Has 32 free IDs
* Whips = 1950-1999 ; Has 130 free IDs

* Handguns = 13100-13149
* Other guns = 13150-13199

* Ninja weapons = 13300-13399

The number of unused Item IDs left known for a range has also been mentioned above. Best practice to follow check in your range in official db before adding custom weapon.

==Weapon Sprite Solution (For New Clients) ==
For new clients the view id system is also applicable to client. To add a custom weapon you need to first edit a file
called weapontable.lub in your data folder
data/luafiles514/lua files/datainfo/weapontable.lub

I will be adding Oriental_Sword which will be a 1-Handed sword. Open weapontable.lub.
First you will see a table called Weapon_IDs. Take note of the first 30 values in this table - these are the only available Weapon types in the client right now.

Anyways go to the last entry which should be for Wizardy Staff = 97. You can use a view id after that like shown below
WEAPONTYPE_Oriental_Sword = 98,

Come down and you see the next table called WeaponNameTable. Here is where you add your sprite name suffix. 
What do i mean by that? Its the last part in your weapon sprite & act file. Before it used to be _<Item ID>.
data/sprite/<job dependent folder>/<job dependent prefix>_<gender><weapon suffix>.spr

OK Back to topic. so I add my entry like shown below.
[Weapon_IDs.WEAPONTYPE_Oriental_Sword] = "_Oriental"

Lastly come down further in weapontable.lub and you see the last table called Expansion_Weapon_IDs. 
Remember the 30 types i told you to take note of ? here we assign one of those to our custom (like a mapping or connection). 
Since mine is a 1-Handed Sword I specify it like below.
[Weapon_IDs.WEAPONTYPE_Oriental_Sword] = Weapon_IDs.WPCLASS_WEAPONTYPE_SWORD

Now for the most important part. For our client to actually pick up all these details we need to provide the view id which we used in Weapon_IDs table as the ClassNum value in ItemInfo.lua. Check the [[Custom_Items#System.2FItemInfo.lub|ItemInfo.lub format]] shown above for details.

With this your weapon sprite will become visible while attacking.
[[Category:Database]]
[[Category:Data]]
[[Category:Customization]]

Custom Items

2016-04-25T12:25:05Z

Haru: /* Defining Item clientside (Renewal Clients <= 2012-04-10a & Main Clients <= 2012-07-10a) */ Removed reference to svn

=Structure=
First, let's take a look at the item_db.conf in the db folder, and its structure:
item_db: (
{
// =================== Mandatory fields ===============================
Id: ID (int)
AegisName: "Aegis_Name" (string, optional if Inherit: true)
Name: "Item Name" (string, optional if Inherit: true)
// =================== Optional fields ================================
Type: Item Type (int, defaults to 3 = etc item)
Buy: Buy Price (int, defaults to Sell * 2)
Sell: Sell Price (int, defaults to Buy / 2)
Weight: Item Weight (int, defaults to 0)
Atk: Attack (int, defaults to 0)
Matk: Magical Attack (int, defaults to 0, ignored in pre-re)
Def: Defense (int, defaults to 0)
Range: Attack Range (int, defaults to 0)
Slots: Slots (int, defaults to 0)
Job: Job mask (int, defaults to all jobs = 0xFFFFFFFF)
Upper: Upper mask (int, defaults to any = 0x3f)
Gender: Gender (int, defaults to both = 2)
Loc: Equip location (int, required value for equipment)
WeaponLv: Weapon Level (int, defaults to 0)
EquipLv: Equip required level (int, defaults to 0)
EquipLv: [min, max] (alternative syntax with min / max level)
Refine: Refineable (boolean, defaults to true)
View: View ID (int, defaults to 0)
BindOnEquip: true/false (boolean, defaults to false)
Script: <"
Script
(it can be multi-line)
">
OnEquipScript: <" OnEquip Script (can also be multi-line) ">
OnUnequipScript: <" OnUnequip Script (can also be multi-line) ">
// =================== Optional fields (item_db2 only) ================
Inherit: true/false (boolean, if true, inherit the values
that weren't specified, from item_db.conf,
else override it and use default values)
},
...
)

* '''ID''': ID of the item.
* '''AegisName''': Server name to reference the item in scripts and lookups, should use no spaces.
* '''Name''': Name in English for displaying as output for @ and script commands.
* '''Type''': Purpose of the item.
0 = Usable : healing
2 = Usable : other
3 = Misc
4 = Weapon
5 = Armor
6 = Card
7 = Pet Egg
8 = Pet Equipment
10 = Arrow/Ammunition
11 = Usable : delayed consumption (items with script "pet" or "itemskill")
18 = Another delayed consume that requires user confirmation before using item.
* '''Buy''': Default [[NPC]] buying price in Zeny. When not specified, becomes double the sell price.
* '''Sell''': Default [[NPC]] selling price in Zeny. When not specified, becomes half the buy price.
* '''Weight''': Item's weight. Each 10 is 1 weight. When not specified, becomes 0.
* '''ATK''': Base weapon attack, in case of a weapon. When not specified, becomes 0.
** In '''RE''' enabled servers this field have a optional delimiter ''':''' to define this item's weaponMATK bonus, for example, '''30:50''' would mean the item gives 30 atk and 50 weaponMATK
* '''Matk''': Weapon's magical attack (only used in renewal mode, ignored in pre-renewal). When not specified, becomes 0.
* '''DEF''': Base defense for armor-type items. When not specified, becomes 0.
* '''Range''': Maximum range in map cells a weapon allows to be the player apart from it's target. When not specified, becomes 0.
* '''Slots''': Amount of card slots in weapon/armor-type items. When not specified, becomes 0.
* '''Job''': Which jobs this item is available for. Values below can be combined to achieve availability for multiple job classes, i. e. <code>0x2|0x4 -> 0x6</code> (Swordman+Mage)
(S.) Novice (2^00): 0x00000001
Swordman (2^01): 0x00000002
Mage (2^02): 0x00000004
Archer (2^03): 0x00000008
Acolyte (2^04): 0x00000010
Merchant (2^05): 0x00000020
Thief (2^06): 0x00000040
Knight (2^07): 0x00000080
Priest (2^08): 0x00000100
Wizard (2^09): 0x00000200
Blacksmith (2^10): 0x00000400
Hunter (2^11): 0x00000800
Assassin (2^12): 0x00001000
''Unused'' (2^13): 0x00002000
Crusader (2^14): 0x00004000
Monk (2^15): 0x00008000
Sage (2^16): 0x00010000
Rogue (2^17): 0x00020000
Alchemist (2^18): 0x00040000
Bard/Dancer (2^19): 0x00080000
''Unused'' (2^20): 0x00100000
Taekwon (2^21): 0x00200000
StarGladiator (2^22): 0x00400000
Soul Linker (2^23): 0x00800000
Gunslinger (2^24): 0x01000000
Ninja (2^25): 0x02000000
Gangsi (2^26): 0x04000000
Death Knight (2^27): 0x08000000
Dark Collector (2^28): 0x10000000
Kagerou/Oboro (2^29): 0x20000000
Rebellion (2^30): 0x40000000
'''Some other commonly used values:'''
All Classes : 0xFFFFFFFF
Every Job Except Novice : 0xFFFFFFFE
* '''Upper''': Specifies whether the item can be used by normal, baby or reborn classes. Values below can be combined, i. e. <code>1|4 -> 5</code> (Normal+Baby Classes)
** Note: Setting <code>2</code> enables the item for Transcendant and 3rd classes. Use <code>8</code> to enable the item for 3rd classes only.
Normal jobs: 0x01 (1)
Upper jobs: 0x02 (2)
Baby jobs: 0x04 (4)
Third jobs: 0x08 (8)
Upper Third jobs: 0x10 (16)
Baby Third jobs: 0x20 (32)

Under pre-re mode third classes are considered upper, making use of
the 8 and above masks is therefore not necessary unless in renewal
mode. When no value is specified, all classes (mask 0x3f) are able to
equip the item.
* '''Gender''': Gender restriction for the item.
0 = Female
1 = Male
2 = No restriction (both)
* '''Loc''': Equipment location of armor and arrow-type items. Values below can be combined, i. e. 136 would indicate both accessory slots (typical value for accessories).
(2^0) 1 = Lower headgear
(2^1) 2 = Right hand
(2^2) 4 = Mantle
(2^3) 8 = Accessory 1
(2^4) 16 = Armor
(2^5) 32 = Left hand
(2^6) 64 = Shoes
(2^7) 128 = Accessory 2
(2^8) 256 = Upper headgear
(2^9) 512 = Middle headgear
(2^10) 1024 = Costume Top Headgear
(2^11) 2048 = Costume Mid Headgear
(2^12) 4096 = Costume Low Headgear
(2^13) 8192 = Costume Garment/Robe
(2^15) 32768 = Arrow (arrow-type items only)
(2^16) 65536 = Shadow Armor
(2^17) 131072 = Shadow Weapon
(2^18) 262144 = Shadow Shield
(2^19) 524288 = Shadow Shoes
(2^20) 1048576 = Shadow Accessory 2
(2^21) 2097152 = Shadow Accessory 1
* '''WeaponLv''': Weapon level of an item (1-4), Becomes 0 when not specified.
* '''EquipLv''': Base level required to be able to equip. It is possible to specify two values, if an item has a maximum level, by using the following syntax:
EquipLv: [minLv, maxLv]

If only one value is specified, maxLv becomes the current server's
MAX_LEVEL. If no values are specified, minLv becomes 0.
* '''Refineable''': Whether the item is available for refining (1) or not (0). If no value is specified, it defaults to true.
* '''View''': For normal items, defines a replacement view-sprite for the item
:(eg: Making apples look like apple juice). The special case are weapons and ammo where this value indicates the weapon-class of the item.
** Weapon-type items:
**# Daggers
**# One-Handed Swords
**# Two-Handed Swords
**# One-Handed Spears
**# Two-Handed Spears
**# One-Handed Axes
**# Two-Handed Axes
**# Maces
**# ''(not used)''
**# Wand/Staff
**# Bows/Crossbows
**# Knuckle Weapons
**# Musical Instruments
**# Whips
**# Books
**# Katars
**# Revolvers
**# Rifles
**# Shotguns
**# Gatling guns
**# Grenade launchers
**# Fuuma shuriken
** Shield-type items:
**# Guard, Novice Guard
**# Buckler
**# Shield, Holy Guard, Evangelist
**# Mirror Shield
** Ammunition-type items:
**# Arrows
**# Throw-able daggers
**# Bullets
**# Shells
**# Grenades
**# Shuriken
**# Kunai
**# Cannonballs
**# Throwable Items (Sling Item)
** Headgear-type items: Please see the View IDs section of this guide.
* '''BindOnEquip''': Whether the item will automatically bind to the character when it is equipped for the first time.
:An item that has this field set, will display a confirmation dialog the first time it is equipped, and, if accepted, the item will become character-bound.
* '''Script''': This is where you put your item bonus. Whether it's an usable item or an equip item, it will take effect according to the item type.
* '''OnEquip_Script''': Script to execute when the item is equipped. Warning, not all item bonuses will work here as expected.
* '''OnUnequip_Script''': Script to execute when the item is unequipped. Warning, not all item bonuses will work here as expected.
* '''Inherit''': This can be used only in item_db2.conf, and if set to true, and the item already exists in item_db.conf,
:all the missing fields will be inherited from there rather than using their default values.
 
In the doc folder look for a text file called "item_bonus", it shows all the scripts items can have and how they work.
 
For more information about this structure read [http://hercules.ws/board/topic/2954-item-db-file-structure-overhaul/ Item DB file structure overhaul]

=Defining Item clientside (Renewal Clients <= 2012-04-10a & Main Clients <= 2012-07-10a) =
After you make your item, put it in your item_db2.txt, so that you will not run into conflicts when updating your repository later. Then go to your data folder and modify the following files, one after another.

==idnum2itemdisplaynametable.txt==
This file holds the item names, as displayed inside the client. Each item added as:
ItemID#ItemName#
ItemID is the number from your ID column inside the item db. If your item name contains spaces, replace those with _ (underscore).

==idnum2itemdesctable.txt==
This file contains the description of your item, when it is right-clicked. The syntax for an item is:
ItemID#
Item Description Line 1
Item Description Line 2
#
You can use any amount of lines for the description. If your description contains a #, make sure it is followed by a space character.
==idnum2itemresnametable.txt==
This file sets the inventory and drop-sprite for an the item. Item is defined as follows:
ItemID#SpriteName#
The SpriteName is the name of the files in collection and item folders inside texture and the ones inside sprite folder. If you want to use the look of an another item, search for it's id and copy the sprite name from there.
==itemslotcounttable.txt==
In this file you set the amount of visible slots for the item. You do not need to add 0 slot items or items, which do not have slots at all (i. e. usable items). Syntax:
ItemID#NumberOfSlots#
NumberOfSlots should be a number from 1-4, larger values might have undesired effects.
==Files for non-identified items==
The following files specify the name, description and look for items, which have not yet been identified. Their syntax follows the same rules as for the files with ''idnum'' prefix. Normally the same text is entered for non-equipment and generic description (which can be copied from official items) is used for equipment of all sorts (weapons, armor, headgears).
* num2itemdesctable.txt
* num2itemdisplaynametable.txt
* num2itemresnametable.txt

=Defining Items clientside (For New Clients)=
If your client date is newer than specified above then you need to specify all the above item information in 1 file

==System/ItemInfo.lub==
Since ItemInfo.lub is compiled, you need to decompile it to lua , add your customs and recompile back to lub file (Some have said that renaming a decompiled file to lub also works)
Syntax:
[<item id>] = {
unidentifiedDisplayName = <item name to show when not magnified>,
unidentifiedResourceName = <file name prefix used for all the images and drop sprite when not magnified>,
unidentifiedDescriptionName = { <comma separated list of strings>,<to get multiple lines>,<in item description> },
identifiedDisplayName = <item name to show when magnified>,
identifiedResourceName = <file name prefix used for all the images and drop sprite when magnified>,
identifiedDescriptionName = { <same format as unidentifiedDescriptionName but for magnified items> },
slotCount = <number of slots>,
ClassNum = <View ID - yes the same one that was there item_db>
},
For Weapons, ClassNum = View ID specified in Weapon_IDs table (inside weapontable.lub file). Look [[Custom_Items#Weapon_Sprite_Solution_.28For_New_Clients.29|below]] for details.

You can also put the different values in DescriptionName in separate lines.

Example: Lets say i want to add a weapon to item id 25000 - a One handed sword named Devastator with 3 slots & the image files & drop sprite files are all named Black_Sword.* . Also i want to display a Sword when not magnified.

[25000] = {
unidentifiedDisplayName = "Sword",
unidentifiedResourceName = "¼Òµå",
unidentifiedDescriptionName = { "Unidentified item, can be identified with [Magnifier]." },
identifiedDisplayName = "Devastator",
identifiedResourceName = "Black_Sword",
identifiedDescriptionName = {
"An Unholy Sword that was created with the sole purpose of destruction",
"Class :^777777 Sword^000000",
"Attack :^777777 325^000000",
"Weight :^777777 80^000000",
"Weapon Level :^777777 4^000000",
"Required Level :^777777 100^000000",
"Applicable Job :^777777 Novice, Swordsman Class, Merchant Class, Thief Class^000000"
},
slotCount = 3,
ClassNum = 2
},

= Allocating Items on Client Side =
Your custom item will have 4 (6 in case its a headgear or garment) files:
1) Drop sprite -> Helmet_drop.spr
2) Drop act file -> Helmet_drop.act
3) Item Inventory image -> Helmet_item.bmp
4) Item Collection image -> Helmet_collection.bmp (the one you see on its description window)
5) Headgear View sprite -> Helmet.spr
6) Headgear View act file -> Helmet.act

Lets say i downloaded a custom item called Helmet which serves as a headgear and the above six files were in them.

==Step 1:==
We place the first four files based on what we specified in id2numresnametable.txt (IdentifiedResourceName in Iteminfo.lub).
For our example lets say i used "Helmet" as the resource name :
i) Copy Helmet_drop.spr to [RO Folder]\data\sprite\¾ÆÀÌÅÛ\Helmet.spr
ii) Copy Helmet_drop.act to [RO Folder]\data\sprite\¾ÆÀÌÅÛ\Helmet.act
iii) Copy Helmet_item.bmp to [RO Folder]\data\texture\À¯ÀúÀÎÅÍÆäÀÌ½º\item\Helmet.bmp
iv) Copy Helmet_collection.bmp to [RO Folder]\data\texture\À¯ÀúÀÎÅÍÆäÀÌ½º\collection\Helmet.bmp
==Step 2 (only for Headgears):==
For displaying headgear on the character there will be two additional files (sprite & act) or 4 if the sprite author intended for a separate set of files for male & female. In my example i have considered the first scenario.

The filename for headgear sprite are now specified in accname.lua file (details of which is available in the [[Custom_Items#View_IDs.2C_Having_A_Custom_Headgear_Without_Xray|View IDs Section]])

lets say i used
[ACCESSORY_IDs.HELMET] = "_Helmet",
then we need to:
i) Copy Helmet.spr to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\¿©\¿©_Helmet.spr (Female)
ii) Copy Helmet.act to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\¿©\¿©_Helmet.act
iii) Copy Helmet.spr to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\³²\³²_Helmet.spr (Male)
iv) Copy Helmet.act to [RO Folder]\data\sprite\¾Ç¼¼»ç¸®\³²\³²_Helmet.act

Now it is ready to be used provided you have added entries properly to the lua files.

==Specifications of the files==
1) Drop sprites - ideally have 1 frame & its act file will be just an empty act (only header will be there inside)

2) Equip sprites - typically have 3+ frames to show images for various orientations & its act file will have the info on where to place each frame.

3) Item bmp - 24x24 size 256 bit bmp file.

4) Collection bmp - 75x100 size bmp file (usually 256 bit but there is no restriction)

How to differentiate between sprite files?

Open both sprite files in [http://ratemyserver.net/download_agent.php?type=1&file_num=10 Spr Conview]. The number of frames in the files can be seen at bottom (Sprite: <currentframe>/<total>). If it says Sprite: 1/1 then its a drop sprite and the other is equip sprite.

Sometimes what sprite authors do is they simply copy the original sprite itself to make a drop sprite. In this case you will see both of them as identical when opened in Spr Conview & we don't need to worry about which one is which (since they are the same).

If the process confused you, [http://www.mediafire.com/?8lzt4cbot100w44 here is an example folder], the sprite is done by drkangel. The folder is virus free.

= View IDs, Having A Custom Headgear Without Xray =
Look in your data folder and make sure there is a folder named "lua files", if there is not make it.[http://svn6.assembla.com/svn/ClientSide/Lua_Project/lubs/ Download the most recent lub package] and extract it to your lua files folder in your data folder. [http://svn6.assembla.com/svn/ClientSide/Lua_Project/lua%20files/datainfo/ Download the most recent accname.lua and accessoryid.lua], put it in your datainfo folder that is inside the lua files folder. Now download [http://svn6.assembla.com/svn/ClientSide/Lua_Project/tool/luac5.0.2.exe this lub compiling tool], and put it in the datainfo folder.
Now, Open accessoryid.lua in the datainfo folder with notepad or a text editor of your choice, go all the way down until the names stop. Add your custom gears before the } symbol. You should use a high number just like with your custom item's database ID, or use unused IDs to be sure you won't have to redo them all in the future, or at least for a while. Example:
ACCESSORY_PINKBUNNY_HAIRBAND = 663,
ACCESSORY_GREENBUNNY_HAIRBAND = 664,
ACCESSORY_OLD_ELFEAR = 665,
ACCESSORY_THA_MAERO_MASK = 666,
ACCESSORY_THANATOS_MAI_MASK = 667,
--668 free
ACCESSORY_FISHPIN = 669,
ACCESSORY_CUSTOM_HAT = 900,
}

''You must compile to lub if you leave space between IDs, if you don't plan on compiling to lub, make sure you do not skip any numbers.''

Now open accname.lua, do basically the same thing but just in a different way, and for the sprite. Add your item to the bottom, have it look like the ones above it, except have your items name and the item's sprite name.
[ACCESSORY_IDs.ACCESSORY_PINKBUNNY_HAIRBAND] = "_ÇÎÅ©Åä³¢¸Ó¸®¶ì",
[ACCESSORY_IDs.ACCESSORY_GREENBUNNY_HAIRBAND] = "_±×¸°Åä³¢¸Ó¸®¶ì",
[ACCESSORY_IDs.ACCESSORY_OLD_ELFEAR] = "_°í´ë¿äÁ¤ÀÇ±Í",
[ACCESSORY_IDs.ACCESSORY_THA_MAERO_MASK] = "_Å¸³ªÅä½ºÀÇ½½ÇÄ°¡¸é",
[ACCESSORY_IDs.ACCESSORY_THANATOS_MAI_MASK] = "_Å¸³ªÅä½ºÀÇÁõ¿À°¡¸é",
[ACCESSORY_IDs.ACCESSORY_FISHPIN] = "_¹°°í±âÇÉ",
[ACCESSORY_IDs.ACCESSORY_CUSTOM_HAT] = "_Sprite_Name_Here",
}
Delete the accname.lub and accessoryid.lub. Now that you are done, make sure luac.exe is in your datainfo folder, right click the luac.exe, create a shortcut, right click the shortcut, and click properties, in the target area, add right after the quotes, with the quotes:
-o "accessoryid.lub" "accessoryid.lua"
So that it looks something like this:
"C:\Program Files (x86)\Gravity\RO\data\lua files\datainfo\luac5.0.2.exe" -o "accessoryid.lub" "accessoryid.lua"
Do this also to "accname.lub" except instead of accessoryid in the quotes, do accname. If there is any lua file leftover, you may want to move it somewhere else just for future changes, like My Documents. For future reference, this is also how you turn the other lub files to lua files.

=Modifications=
==Sprite Replacement==
To replace a headgear with your customized headgear, just delete one of the items you want, and replace your customised item ID with that id.

Lets say you have something like this:
15000,Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}
And there's an item you wont need, such as:
2220,Hat,Hat,5,1000,,200,,2,,0,10477567,2,256,,0,1,16,{},{},{}
Well, to replace it, just delete everything in the hat line but its ID, and paste there your custom item, all the line but the ID. Should be like this:
'''2220''',Hat,Hat,5,1000,,200,,2,,0,10477567,2,256,,0,1,16,{},{},{}
15000,'''Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}'''
'''2220,Angel_Wing,Angel Wing,4,,10,10,0,,1,0,0,3,0,0,0,0,0,{},{},{}'''
All you need to do now is changing the View ID to the Hat, and change your file names to its name. You can find them on the idnum2resnametable.txt Search for 2220 and the gibberish besides it, w/o the # # is the file name, then rename it to your custom item name.

Remember to add the files to data\sprite\¾ÆÀÌÅÛ (Icon sprite) and both data\sprite\¾Ç¼¼»ç¸®\³² (Male Item Sprite) and data\sprite\¾Ç¼¼»ç¸®\¿© (Female Item Sprite). Remember, these 2 last item names, must have either a ³²_ for male or ¿©_ for female, at the beginning of the name, both .spr and .act. Also, don't forget to change the other files:

idnum2itemdisplaynametable.txt , idnum2itemdesctable.txt , idnum2itemdesctable.txt , num2itemdesctable.txt , num2itemdisplaynametable.txt , num2itemresnametable.txt and itemslotcounttable.txt

Use these files if you want to replace sprites, they will be useful.
* '''actOR:''' with the actor you modify the act file, which is the one who tells the client where does the weapon go and what does it have to do and at a certain moment.
* '''SPR Conview:''' you can use these to view which sprite is which, and also see sequence per sequence.

==Item Restrictions==
Look on your db folder for a file called item_trade.txt and open it

Now, the pattern for a flag is:

Item ID, TradeMask, GM-Level Override

* '''Item ID''': the ID of your item.
* '''TradeMask''': Testrictions the item will have, such as being dropped, stored or traded. These values can be combined to achieve multiple effects.
1:Item can't be dropped
2:Item can't be traded (nor vended)
4:Item can only be traded with wedded partner
8:Item can't be sold to NPCs
16:Item can't be placed in the cart
32:Item can't be placed in the storage
64:Item can't be placed in the guild storage
* '''GM-Level Override''': This is the minimum GM level a player must have to avoid these restrictions.

==Item Script==
{{duplication
|type=section
|what=[[itemskill]], [[sc_start]] and [[skilleffect]]}}
{{disputed
|type=section
|date=September 2010}}
Okay, I'll update this as I go; otherwise, I wont have anything new to show. First with usable items.

Well, there are 3 types of usables:

1.- Healing items, they have in the type field a 0.

2.- Other uses items, such as fly wings and so, which doesn't heal, but does have an instant effect, they have in the type field a 2.

3.- Usable items, which are skills that requires a target selection, therefore they have a delayed use, and in newer SVNs the item wont be gone until the target is chosen and the cast has finished. Means, you wont lose the item if the skill hasn't been done. They have in the type field an 11.

Now, for an item skill, the pattern for a skill is:
itemskill <skill id>,<skill level>;
Without <> of course.

Now, we go to our db\skill_db.txt and search for the blessing ID, searching for AL_ or blessing, but first, the structure of a skill:
id,range,hit,inf,element,nk,splash,max,list_num,castcancel,cast_defence_rate,inf2,maxcount,skill_type,blow_count,name,description
Now, the AL_BLESSING or Blessing Skill:
34,9,6,16,0,0x1,0,10,1,yes,0,0,0,magic,0, AL_BLESSING,Blessing
We grab the ID and put it on our code:
itemskill 34,<skill lvl>;
Don't mind the actual level of the skill_db.txt for the skill level part. You can actually put the level you want here below 99, so lets pick 4:
itemskill 34,4;
And finally, insert it on the code.
<pre>,{ itemskill 34,4; },{},{}</pre>

There, we have a Lvl 4 Blessing item skill.

Remember, one space before and one after the script, NOT TAB!

And so on with other skills. Just remember these steps and they should be fine. And remember, itemskill is NOT the same as skill. itemskill will make you CAST that skill, while skill will GIVE you the skill. If you give an item, whether delayed use or normal usable two itemskill commands, only the latter will come into effect, as you cannot cast two skills at the same time.

Now, for Potions.

Instead of using itemskill, we will use itemheal:
,{ itemheal 100,0; },{},{}
The green is the HP, the blue is the SP. To add that random heal amount effect, just pick a set amount, let's say 120, then pick 1 or 2 numbers, up to you. Then, add the rand() command, like this:
,{ itemheal rand(120,9,49),0; },{},{}
Explanation: This item will heal about 49~120 hp and 0 SP. To heal SP you change the 0 to a number. Like this:
,{ itemheal rand(120,9,49),50; },{},{}
It will now heal 50 SP.
Now, for skilleffect and sc_start.

Okay, let's see. Here's a example of an item casting a skill and simulating a skill.
,{ itemskill 34,10; skilleffect 29,0; sc_start 12,140000,5; },{},{}
skilleffect will display on your client a skill visual effect. The pattern is:

skilleffect <skill ID>,<number>;

;skill ID
:Self-explanatory.
;number
:Have you seen those skills that shows up numbers upon casting? Such as heal? Well, putting a number there will display it. But only works on skills with numbers floating.

sc_start has the following pattern:

sc_start <status id>,<duration>,<val1>[,<unit id>];

;status id
:Refer to const.txt in your db folder for all effects. Open it with a text editor then search by either clicking edit, then find, or press and hold the ctrl key, and while still holding it press the f key, then release, and search for "SC_ALL -1". Everything below this is an effect. The effects stop at "e_gasp 0" which are emoticons.
;duration
:Is the amount time in milliseconds (1000 msec = 1 sec) that the status will be active.
;val1
:Typically it's the level of the skill, associated with this status.
;unit id
:Allows to start the status on an other unit, than the attached player. For players this is account id. This parameter is optional, and can be omitted.

Now, for the item I said, it will show you the visual effect of Blessing and cast on you a lvl 5 Agi-Up! skill for 140 seconds.

For more item scripts see script_commands.txt in your doc folder, as well as item_bonus.txt in your doc folder.

==Weapon Sprite Solution (Renewal Clients <= 2012-04-10a & Main Clients <= 2012-07-10a)==
For these clients, Weapons are limited to use a range of Item IDs hardcoded in the clientn for each type.
For e.g.

1265,Bloody_Roar,Bloody Roar,4,,10,1000,120,,1,0,4096,7,2,34,4,75,1,16,{ bonus bIgnoreDefRace,RC_DemiHuman; bonus bFlee,-160; bonus bFlee2,-160; bonus bNoRegen,1; bonus bNoRegen,2; },{},{}
1266,Test,Test,4,4000,2000,10,165,,1,0,4096,7,2,34,3,33,1,16,{}

// 1-Handed Axes
1301,Axe,Axe,4,500,,800,38,,1,3,8803555,7,2,2,1,3,1,6,{}

Here the item 1266 is a custom katar and it does show up as a katar (if you have the proper sprite files ofcourse). but if i use some id like say 22000, client wont display it. So what is the range of item ids you can use? Look below:

* One handed Swords = 1100-1149, 13400-13499
* Two handed Swords = 1150-1199, 21000-21999

* Knives, Daggers etc = 1200-1249, 13000-13099
* Katars = 1250-1299 ; Has 35 free IDs

* One handed Axes = 1300-1349; Has 43 free IDs
* Two handed Axes = 1350-1399; Has 32 free IDs

* One handed Spears = 1400-1449; Has 34 free IDs
* Two Handed Spears = 1450-1471, 1474-1499

* Maces = 1500-1549, 16000-16999
* Books = 1550-1599 ; Has only 2 IDs.
* Knuckles = 1800-1899 ; Has 95 free IDs

* One Handed Staves/Rods = 1600-1699; Has 79 free IDs
* Two Handed Staves/Rods = 1472,1473,2000-2099

* Bows = 1700-1749, 18100-18499
* Guitars = 1900-1949 ; Has 32 free IDs
* Whips = 1950-1999 ; Has 130 free IDs

* Handguns = 13100-13149
* Other guns = 13150-13199

* Ninja weapons = 13300-13399

The number of unused Item IDs left known for a range has also been mentioned above. Best practice to follow check in your range in official db before adding custom weapon.

==Weapon Sprite Solution (For New Clients) ==
For new clients the view id system is also applicable to client. To add a custom weapon you need to first edit a file
called weapontable.lub in your data folder
data/luafiles514/lua files/datainfo/weapontable.lub

I will be adding Oriental_Sword which will be a 1-Handed sword. Open weapontable.lub.
First you will see a table called Weapon_IDs. Take note of the first 30 values in this table - these are the only available Weapon types in the client right now.

Anyways go to the last entry which should be for Wizardy Staff = 97. You can use a view id after that like shown below
WEAPONTYPE_Oriental_Sword = 98,

Come down and you see the next table called WeaponNameTable. Here is where you add your sprite name suffix. 
What do i mean by that? Its the last part in your weapon sprite & act file. Before it used to be _<Item ID>.
data/sprite/<job dependent folder>/<job dependent prefix>_<gender><weapon suffix>.spr

OK Back to topic. so I add my entry like shown below.
[Weapon_IDs.WEAPONTYPE_Oriental_Sword] = "_Oriental"

Lastly come down further in weapontable.lub and you see the last table called Expansion_Weapon_IDs. 
Remember the 30 types i told you to take note of ? here we assign one of those to our custom (like a mapping or connection). 
Since mine is a 1-Handed Sword I specify it like below.
[Weapon_IDs.WEAPONTYPE_Oriental_Sword] = Weapon_IDs.WPCLASS_WEAPONTYPE_SWORD

Now for the most important part. For our client to actually pick up all these details we need to provide the view id which we used in Weapon_IDs table as the ClassNum value in ItemInfo.lua. Check the [[Custom_Items#System.2FItemInfo.lub|ItemInfo.lub format]] shown above for details.

With this your weapon sprite will become visible while attacking.
[[Category:Database]]
[[Category:Data]]
[[Category:Customization]]

Installation

2016-04-25T12:24:12Z

Haru: Marked svn information as outdated

This article is aimed at downloading Hercules and any dependancies required to run it. In this article, you are expected to know basic file and program
management of the OS you are attempting to run Hercules on. (Or use Google to search for the answers)

==System Requirements==
{{EntirePage|System Requirements}}
Hercules runs on variety of 32-bit and 64-bit (limited) operating systems, including Windows, Linux and Unix. Hardware requirements are ones of typical server environment, whether virtual or dedicated.

==Program Requirements==
To run Hercules, the following programs must be installed on the machine that will run Hercules:
===*nix based===
For *nix, most of these programs will come as [[wikipedia:Software_package_%28installation%29|Packages]] with your OS, for example,
the FreeBSD Ports collection, or Debians apt-get or aptitude. Please see your OS's help/support pages to find out how to utilize package installations. As a general rule, the following packages will be required to compile Hercules: 
[http://www.gnu.org/software/wget/ wget], [http://subversion.tigris.org/ subversion], [http://gcc.gnu.org/ GCC], [http://www.gnu.org/software/make/ make] (if running *BSD, gmake is needed instead of make.)
====libmysqlclient15-dev====
libmysqlclient15-dev is the library for MySQL and is '''required''' to compile an SQL version of Hercules. This will most likely need to be installed via packages.

===Windows based===
Depending on how you want to compile, one of two methods can be used. We '''highly recommend''' the use of [http://www.microsoft.com/Express/vc/ Visual C++].
[http://www.cygwin.com/ Cygwin] can also be used. If cygwin is used, you have some configuration to do, please see below: 
<blockquote>Expand the development or devel branch in Cygwin and make sure GCC and Make are checked. These are the only 2 things you need,
the others are up to you whether you want to download them or not. The downloading and installation of packages may take some time
depending on your packages, their size, your network speed, and the remote server's network speed.
This shouldn't take too long if it's just GCC and Make.</blockquote>
You will also need [http://subversion.tigris.org/ subversion]

==Installing software==
===Linux OS's===
A simple make and make install is all that is needed for most of the packages. You can find [[:Category:Installation|instructions]] and readmes in each of the downloads for your distro telling you how to install and compile each package. Once subversion is installed, you can download Hercules's latest source via [[GIT]]. 
<code><pre>
$ git clone git://github.com/HerculesWS/Hercules.git hercules </pre></code>
for trunk

===Windows OS's===
{{outdated|type=section}}
When using SVN in Windows, all your commands are in a right click menu integrated into the Windows Shell. 
[[Image:svnwindows.jpg]] 
Simply create a new folder, right click on it and select 'SVN Checkout...' and a dialog box will appear. 
[[Image:checkout.jpg]] 
Enter your URL (in the example above, simply add /trunk after the URL to checkout Trunk, or /branches/stable for stable) and TSVN will download
a fresh copy of Hercule's SVN to that folder.

==Compiling==
Please see [[Compiling]] for more detailed instructions.

For your OS, you will need to compile binaries if you had downloaded Hercules via the SVN. you can then move on to [[:Category:Configuration]] and then running Hercules.

==See Also==
* [[:Category:Installation|Installation per OS]]
* [[GIT]]
* [[Installing_SQL|Installing SQL for Hercules use]]

[[Category:Basics]]

Git

2016-04-25T11:45:23Z

Haru: /* Using .diff/.patch files */ removed svn references

[[Category:incomplete]]
==Preface==
This article will cover the '''Git''' details related to Hercules. '''Git''' is a version control system that allows multiple users to contribute to the development of Hercules, if permitted. It is also the most efficient method to downloading the source code of Hercules.

==About Git==
As mentioned above '''Git''' is a version control system that allows users to download the latest source code.

===Checkout===
When you '''clone''' a git repository, it is downloaded, along with all history, properties and files, onto your machine so you can make local changes or use it in a production environment.

===Commit===
When you '''commit''' a piece of code, you are saving a set of changes in a form that can be uploaded back to the server. Each commit includes the author's name, what they changed and when they changed it, which can be viewed and referenced later.

===Push===
When you '''push''' your commits, you are sending your commits to the central git server, to make them available to other people.

Only members of the [[Staff|Hercules development team]] can commit code straight to the Hercules Git.

===Pull===
When you '''pull''' commits, you are downloading the latest commits that were pushed to the git repository, and merging them to your working copy. In this operation, many files are changed, but some are added, deleted or moved. When you pull changes, a lot of conflicts can happen, so keep an eye out of those.

===Obtain/Install Git===
Please see the [[:Category:Installation]] appropriate category for installation of Git on your operating system of choice and how to utilize it.

==Hercules Git Details==
You can find the root or index of the Hercules source code at the following link: <code>{{git||full}}</code>. This link can be used if you need to view a single file and don't want to dig up your "copy" of the source code.

===Hercules Developer Branches===
Each developer that contributes to the Hercules Project is welcome to their own branches on the git repository. A lot of times, these separate branches branch are a testing bed for a new feature. You should never assume that any branch that is not trunk or not stable is usable. Often times, it is not.

==Using .diff/.patch files==
{{EntirePage|Diff}}
Often times, developers and contributors will release their work with a .diff or .patch file. these files are designed specifically to be applied to Hercules and 'patched' in.

If the revision numbers are different, or the code is different in anyway, the patch will likely fail with the error message that the revision numbers do not match. The diff file will include some important symbols and numbers to help you apply them manually.
/path/to/file [Revision 233]
@@ +241,4 -241,4 @@
+ This line will be added at the line number or position indicated above.
- This line will be removed at the line number or position indicated above.
So in the file, we're to remove line 241 and replace it with the line that has the '+' next to it.

[[Category:Basics]]

Git

2016-04-25T11:44:15Z

Haru: /* Hercules Git Details */ removed svn references

[[Category:incomplete]]
==Preface==
This article will cover the '''Git''' details related to Hercules. '''Git''' is a version control system that allows multiple users to contribute to the development of Hercules, if permitted. It is also the most efficient method to downloading the source code of Hercules.

==About Git==
As mentioned above '''Git''' is a version control system that allows users to download the latest source code.

===Checkout===
When you '''clone''' a git repository, it is downloaded, along with all history, properties and files, onto your machine so you can make local changes or use it in a production environment.

===Commit===
When you '''commit''' a piece of code, you are saving a set of changes in a form that can be uploaded back to the server. Each commit includes the author's name, what they changed and when they changed it, which can be viewed and referenced later.

===Push===
When you '''push''' your commits, you are sending your commits to the central git server, to make them available to other people.

Only members of the [[Staff|Hercules development team]] can commit code straight to the Hercules Git.

===Pull===
When you '''pull''' commits, you are downloading the latest commits that were pushed to the git repository, and merging them to your working copy. In this operation, many files are changed, but some are added, deleted or moved. When you pull changes, a lot of conflicts can happen, so keep an eye out of those.

===Obtain/Install Git===
Please see the [[:Category:Installation]] appropriate category for installation of Git on your operating system of choice and how to utilize it.

==Hercules Git Details==
You can find the root or index of the Hercules source code at the following link: <code>{{git||full}}</code>. This link can be used if you need to view a single file and don't want to dig up your "copy" of the source code.

===Hercules Developer Branches===
Each developer that contributes to the Hercules Project is welcome to their own branches on the git repository. A lot of times, these separate branches branch are a testing bed for a new feature. You should never assume that any branch that is not trunk or not stable is usable. Often times, it is not.

==Using .diff/.patch files==
{{EntirePage|Diff}}
Often times, developers and contributors will release their work with a .diff or .patch file. these files are designed specifically to be applied to an SVN revision and 'patched' in.

In Windows, you can apply a diff or patch file by placing the diff file into the SVN directory, right clicking the diff or patch file, navigating to the Subversion menu and clicking 'Apply Patch'.

If the revision numbers are different, or the code is different in anyway, the patch will likely fail with the error message that the revision numbers do not match. The diff file will include some important symbols and numbers to help you apply them manually.
/path/to/file [Revision 233]
@@ +241,4 -241,4 @@
+ This line will be added at the line number or position indicated above.
- This line will be removed at the line number or position indicated above.
So in the file, we're to remove line 241 and replace it with the line that has the '+' next to it.

[[Category:Basics]]

Git

2016-04-25T11:42:42Z

Haru: /* About Git */ Removed svn references

[[Category:incomplete]]
==Preface==
This article will cover the '''Git''' details related to Hercules. '''Git''' is a version control system that allows multiple users to contribute to the development of Hercules, if permitted. It is also the most efficient method to downloading the source code of Hercules.

==About Git==
As mentioned above '''Git''' is a version control system that allows users to download the latest source code.

===Checkout===
When you '''clone''' a git repository, it is downloaded, along with all history, properties and files, onto your machine so you can make local changes or use it in a production environment.

===Commit===
When you '''commit''' a piece of code, you are saving a set of changes in a form that can be uploaded back to the server. Each commit includes the author's name, what they changed and when they changed it, which can be viewed and referenced later.

===Push===
When you '''push''' your commits, you are sending your commits to the central git server, to make them available to other people.

Only members of the [[Staff|Hercules development team]] can commit code straight to the Hercules Git.

===Pull===
When you '''pull''' commits, you are downloading the latest commits that were pushed to the git repository, and merging them to your working copy. In this operation, many files are changed, but some are added, deleted or moved. When you pull changes, a lot of conflicts can happen, so keep an eye out of those.

===Obtain/Install Git===
Please see the [[:Category:Installation]] appropriate category for installation of Git on your operating system of choice and how to utilize it.

==Hercules Git Details==
You can find the root or index of the Hercules source code at the following link: <code>{{git||full}}</code>. This link can be used if you need to view a single file and don't want to dig up your "copy" of the source code.

===Hercules Trunk===
'''Hercules Trunk''' is used as the ''testing'' or otherwise development code. It has all of the latest features, but is not guaranteed to be bug or problem free.

You can checkout the trunk branch from the following link:
<code>{{git|trunk/}}</code>

===Hercules Developer Branches===
Each developer that contributes to the Hercules Project is welcome to their own folder on the SVN, where they may make their own branch. A lot of times, this separate branch is a testing bed for a new feature. You should never assume that any branch that is not trunk or not stable is usable. Often times, it is not.

==Using .diff/.patch files==
{{EntirePage|Diff}}
Often times, developers and contributors will release their work with a .diff or .patch file. these files are designed specifically to be applied to an SVN revision and 'patched' in.

In Windows, you can apply a diff or patch file by placing the diff file into the SVN directory, right clicking the diff or patch file, navigating to the Subversion menu and clicking 'Apply Patch'.

If the revision numbers are different, or the code is different in anyway, the patch will likely fail with the error message that the revision numbers do not match. The diff file will include some important symbols and numbers to help you apply them manually.
/path/to/file [Revision 233]
@@ +241,4 -241,4 @@
+ This line will be added at the line number or position indicated above.
- This line will be removed at the line number or position indicated above.
So in the file, we're to remove line 241 and replace it with the line that has the '+' next to it.

[[Category:Basics]]

Hercules

2016-04-25T11:36:19Z

Haru: Updated forum links

{{infobox/software
|developer=[[Staff|Hercules Developers]]
|version=[https://github.com/HerculesWS/Hercules/commit/ GitHub]
|os=Windows, Linux, FreeBSD, Mac OSX
|lang=English
|type=Ragnarok Online Emulator
|license=GNU General Public License 3 (open source)
|web=http://herc.ws/}}
'''Hercules''' is a free and open source implementation of [[wikipedia:AEGIS_(Ragnarok_Online)|Aegis]], a [[wikipedia:Ragnarok Online|Ragnarok Online]] game server, and is written in [[wikipedia:C_(programming_language)|C]]. Written in C the program is very versatile and provides NPCs, warps and modifications. and is currently version controlled via Git. The project is jointly managed by a group of volunteers located around the world as well as a tremendous community providing QA and support. Hercules is a continuation of the original Athena project.

== Repository ==
Hercules is available via [http://herc.ws/board/topic/152-obtaining-hercules/ Git]

== Support ==
You may access our [http://herc.ws/board/ forums] or [[IRC|IRC channel]] for support.

== External Links ==
* [http://herc.ws/board/ Official Hercules Support Board]

[[Category:Hercules]]

Hercules

2016-04-25T11:35:48Z

Haru: /* Support */ Updated forum link

{{infobox/software
|developer=[[Staff|Hercules Developers]]
|version=[https://github.com/HerculesWS/Hercules/commit/ GitHub]
|os=Windows, Linux, FreeBSD, Mac OSX
|lang=English
|type=Ragnarok Online Emulator
|license=GNU General Public License 3 (open source)
|web=http://hercules.ws/}}
'''Hercules''' is a free and open source implementation of [[wikipedia:AEGIS_(Ragnarok_Online)|Aegis]], a [[wikipedia:Ragnarok Online|Ragnarok Online]] game server, and is written in [[wikipedia:C_(programming_language)|C]]. Written in C the program is very versatile and provides NPCs, warps and modifications. and is currently version controlled via Git. The project is jointly managed by a group of volunteers located around the world as well as a tremendous community providing QA and support. Hercules is a continuation of the original Athena project.

== Repository ==
Hercules is available via [http://hercules.ws/board/topic/152-obtaining-hercules/ Git]

== Support ==
You may access our [http://herc.ws/board/ forums] or [[IRC|IRC channel]] for support.

== External Links ==
* [http://hercules.ws/board/ Official Hercules Support Board]

[[Category:Hercules]]

Hercules

2016-04-25T11:35:18Z

Haru: /* Repository */ SVN is deprecated

{{infobox/software
|developer=[[Staff|Hercules Developers]]
|version=[https://github.com/HerculesWS/Hercules/commit/ GitHub]
|os=Windows, Linux, FreeBSD, Mac OSX
|lang=English
|type=Ragnarok Online Emulator
|license=GNU General Public License 3 (open source)
|web=http://hercules.ws/}}
'''Hercules''' is a free and open source implementation of [[wikipedia:AEGIS_(Ragnarok_Online)|Aegis]], a [[wikipedia:Ragnarok Online|Ragnarok Online]] game server, and is written in [[wikipedia:C_(programming_language)|C]]. Written in C the program is very versatile and provides NPCs, warps and modifications. and is currently version controlled via Git. The project is jointly managed by a group of volunteers located around the world as well as a tremendous community providing QA and support. Hercules is a continuation of the original Athena project.

== Repository ==
Hercules is available via [http://hercules.ws/board/topic/152-obtaining-hercules/ Git]

== Support ==
You may access our [http://hercules.ws/board/ forums] or [[IRC|IRC channel]] for support.

== External Links ==
* [http://hercules.ws/board/ Official Hercules Support Board]

[[Category:Hercules]]

System Requirements

2016-03-06T23:21:12Z

Haru: /* Software Requirements */

== Basic Requirements ==

[[Hercules]] works off of the [[wikipedia:Client–server_model|client-server model]]. The player, usually using a [[Hexing|hexed]] kRO [[Renewal|RE]] client, first connects to the [[Login Server]]. When the client enters their login information, it is given the list of available char-servers, which the player chooses from. After the server has been chosen, the client connects to the selected [[Character Server]], which displays the characters on that player's account. After selecting a character, the client is directed to the [[Map Server]], which maintains maps and the character positions on the server and relays this information to the client.

Hercules is designed to run on a machine that is designated as a Server, either Dedicated or VPS. It can run on a workstation, but using that workstation for other tasks (including playing on the same machine that is running the server) will reduce performance.

== Hardware Requirements ==
Hercules requires the following resources from the machine in order to function without problems or the common "Lag":

* 1.5 GHz or faster CPU, either Intel or AMD is acceptable. Some members have reported that they have gotten Hercules to run on other processors.
* 128 MB of RAM, MINIMUM. The map server in an idle state consumes about 76MB of RAM, depending on how many maps and [[NPC|NPCs]] are loaded (41mb when no NPCs are in use).
* A video card powerful enough to run the Operating System of your choice (or no video card at all). Hercules is a console based software, which means that all that is required to run it is a console or command access.
* Fast internet or network connection. This is very hard to predict. A lot of questions arise that ask 'how much bandwidth does Hercules need?'. There is no answer to that. It is all depending on how many characters are connected, from where, and what they do while connected to the server.
* 250MB of Hard Drive space or better, up-to gigabytes depending on how big the database may get.

== Software Requirements ==
Hercules, depending on what you plan to do with it and what platform you run it on, will require, at a minimum, the following:

* GCC compatible compiler
* GNU Make
* zlib
* MySQL server and libraries
* Git
* pcre

== Supported Operating Systems ==
The following operating systems have been tested and are known to work:
=== [[wikipedia:Linux|Linux]] ===
* Debian Based: [http://www.debian.org/ Debian], [http://www.knoppix.net/ Knoppix], [http://www.ubuntu.com/ Ubuntu Server & Desktop]
* RPM Based: [http://www.centos.org/ CentOS], [http://fedoraproject.org/ Fedora Core], [http://www2.mandriva.com/ Mandriva], [http://www.redhat.com/rhel/ Red Hat Linux], [http://www.novell.com/linux/ SUSE Linux]
* Others: [https://www.gentoo.org Gentoo], [http://www.slackware.com/ Slackware]

=== [[wikipedia:Unix|Unix]] ===
* BSD Based: [http://www.freebsd.org/ FreeBSD], [http://www.openbsd.org/ OpenBSD]
=== [[wikipedia:Microsoft_Windows|Windows]] ===
* [[wikipedia:Windows_Server|Server Versions]]: Windows Server 2008, Windows Server 2008 R2, Windows Server 2012
* Home Versions: Windows Vista, Windows 7, Windows 8, Windows 8.1

[[Category:Basics]]

Installing SQL

2015-07-08T13:03:20Z

Haru: Updated SQL tables information

= Introduction =
This article will guide you through the installation and configuration stages of MySQL for your particular Operating System. What is a MySQL database? [[wikipedia:MySQL|MySQL]] is a multi-user access database that stores a number of different kinds of information in scaleable tables. In layman's terms, it puts a bunch of stuff in charts for your server to read. Hercules no longer supports text based save files (for Accounts, Characters, etc.) and requires a MySQL database to create these save files.

== Windows ==
This guide will instruct you on installing MySQL on Windows Vista/7, although it should work relatively the same with Windows XP. This guide also assumes you have already [[Installation_on_Windows|installed your Hercules server]]. 
 
'''<big>Uninstallation Note</big>''' 
Before continuing, it is important to note that if you make an error and decide to start again by uninstalling the MySQL database and software, that you make sure you do a ''thorough'' uninstallation, and then reboot Windows before trying again. A couple tips to make sure your uninstallation is thorough:
* Uninstall Workbench first
* Remove the MySQL database folders in your user folder. This is generally in:
C:\Users\<YOUR_USER_NAME>\AppData\Roaming\MySQL
:Just delete the whole folder.
* Run Administrative Tools -> Services and look to make sure nothing MySQL related is running or set to run (because it shouldn't exist anymore)
* Go to the location on your hard drive you installed MySQL5 and Workbench and ensure everything is deleted.
* Make sure you reboot.
* There is a Oracle made guide [http://dev.mysql.com/doc/refman/5.1/en/windows-installer-uninstalling.html here], but it isn't necessarily thorough.
* If you still have hanging and crashing during the configuration wizard, you may have to create your root account manually. Do an internet search for this, as it varies by system. And continue afterwards at the "MySQL Workbench" section.

=== Download ===
To install MySQL Server you will first need to download the package corresponding to your version of Windows. [http://dev.mysql.com/downloads/mysql/ MySQL Community Server] is available for free and is exactly what is needed. Version 5.5 currently works well with Hercules and is recommended. '''ENSURE''' that you download the appropriate bit version (32 or 64) for your system, if you do not, you will receive errors during the execution wizard. This software installs the server on your computer that stores the data files and tables. Although alone, without prior knowledge of MySQL it is very difficult to operate and configure your servers data. That is why you will need MySQL Workbench. 
 
[http://dev.mysql.com/downloads/workbench/5.2.html MySQL Workbench] is a tool for viewing your MySQL database in a GUI environment. As said, it is not required but very beneficial; in addition, it is required by this guide. To be able to install and run MySQL Workbench 5.2 your System also needs to have the libraries listed below installed. The listed items are provided as links to the corresponding download pages where you can fetch the necessary files.

[http://www.microsoft.com/download/en/details.aspx?id=17113 Microsoft .NET Framework 4 Client Profile] 
[http://www.microsoft.com/download/en/details.aspx?id=5555 Microsoft Visual C++ 2010 Redistributable Package (x86)]

=== Configure Hercules Files ===
Before you begin with your MySQL installation, you need to setup your server conf files to be ready for the database you are about to install. I choose to do this in advance, because it allows you to have the usernames and passwords ready for use so you don't have to go back and set them, and you can just run your server afterwards with everything all ready.
* Open "inter-server.conf", and change sql.db_password, char_server_pw, map_server_pw and log_db_pw to a password of your choice. For this guide we will use the password "Fish". Passwords are case sensitive. This is not a strong password, and you should use a better one, this is just an example. Also change log_db_db to "log". All other fields should be let alone, the default username and port functions fine. ([http://imageshack.us/a/img546/9444/interathena.jpg Image])
* Open "map-server.conf" and "char-server.conf" and locate the server communication passwords:
userid: s1
passwd: p1
Change these to whatever you want, but something secure. For this guide we will use "FishUser" and "FishPassword"
userid: FishUser
passwd: FishPassword
 
Make sure these are the same in both map-server and char-server otherwise you will have errors.
* There are additional SQL configuration features in "login-server.conf" that you should take a look at now, to enable for use (such as IPban features).
* Write all these passwords down or keep the files open for reference and continue to your MySQL installation!

=== Install MySQL ===
First, you will need to install the MySQL server where all the data will be stored. After downloading the [http://dev.mysql.com/downloads/mysql/ MySQL Community Server], run the installer and use the following steps (''for this installation version 5.5.28 was used'').
# Click next and accept the license agreement.
# Click "Typical" for Setup Type; then click "Install" (you may have to allow UAC control from windows).
# Click "Next" when the MySQL Enterprise tool pops up, this is a simple advertisement.
# After installation is finished the completion screen with a "Finish" button will show, make sure you have "Launch the MySQL Instance Configuration Wizard" '''CHECKED'''! The configuration wizard will allow you to setup the server to accept the kind of data you want and by setting it up now you will most likely never have to configure it again.
# Click "Next" at the first screen, and then click "[http://imageshack.us/a/img90/1771/standardconfig.jpg Standard Configuration]" and hit "Next".
# Check both "Install As Windows Service" and "Include Bin Directory in Windows PATH" for the Service Name, name it "''MySQL5''" and ensure "Launch the MySQL Server Automatically is '''CHECKED'''. ([http://imageshack.us/a/img685/3323/serverinstance.jpg Image])
# On the next screen, you will need to select the root password. This password is very important as you will '''never be able to retrieve it''' so make sure you write it down somewhere safe. The "root" access to your MySQL database can pretty much do anything to your data, so make sure you keep this information safe. If you want to enable root access from a remote machine, check the included box. You probably won't need to enable that unless you know what you're doing. Keep the password you selected available for now.
# On the next screen just click "Execute" to run the configuration unless you want to go back and change something.
# Once it is finished, hit "Finish" to close the wizard. It will report if there are any errors (there shouldn't be).

=== MySQL Workbench ===
Next it is time to install the MySQL Workbench application. This application will allow you to edit your database and prepare it for Hercules, as well as perform maintenance in the future.
# Run the MySQL Workbench installer and click "Next" on the first screen.
# Choose your installation directory. The default directory should be fine. Click "Next" to proceed.
# Select "Complete" and click "Next", and then install, granting permissions when prompted.
# Once the wizard is completed, hit "Finish" and the default Workbench screen will come up.
# This is called the Home Screen and should look like [http://imageshack.us/a/img571/3885/workbenchhome.jpg this].
# You need to create a new server instance to host your files for Hercules to access. Select "New Server Instance" under the "Server Administration" section.
# A window will pop up, select "localhost" and click "Next". This installs the instance on the localhost, which is your computer.
# On the next screen, leave everything the default. Where it says "Username" leave that at root, so you have root access. Under that, click "[http://imageshack.us/a/img845/4056/storeinvault.jpg Store in Vault]" and enter the root password from earlier (it's alright to copy/paste the password if you put it in a text file).
# After it has successfully tested the database connection, click "Next"
# On the next screen, leave the configuration settings defaulted. It should point to the existing service (MySQL5 from earlier) and the default path is fine. ([http://imageshack.us/a/img600/1089/defaultwindowsconfig.jpg Image])
# On the next screen hit "Next" and then "Continue" on the popup. Leave the Server Instance with the default name of
mysqld@localhost
You are now ready to install your Hercules databases.

=== Database Installation ===
It is now time to install the pre-installed database files that will allow your Hercules server to connect to your MySQL database and properly store data, such as characters, items, and guilds. Open up MySQL Workbench to the home screen.
# Double click "localhost" on the left under the "SQL Development" section. ([http://imageshack.us/a/img337/8550/localhostdoubleclick.jpg Image])
# On the next screen (after a small loading bubble pops up), you will have access to the specific tables that were mentioned earlier. You will enter this screen in the future when you want to edit accounts and other things directly (not common).
# We need to install a new "Schema", this is like a folder where all the database tables are stored. [http://imageshack.us/a/img194/2897/newschema.jpg Click the yellow cylinder looking thing in the upper left to create a new Schema]. Name it "ragnarok" - '''NOTE!''' Lower case is important here, make sure it is exactly "ragnarok". The server collation should be "Server Default".
# Click "Apply" to create the Schema. A window will pop up with the actual commands that are going to take place; click "Apply" again to finalize your order.
# Now right click 'ragnarok' under "Object Browser" and click "Set as default schema", a line will appear through it telling the browser that any commands you make now will be ordered to that Schema.
# Next, [http://imageshack.us/a/img571/205/opensqlscript.png click the button directly to the left of the one you just did], it says "SQL" with a tiny folder. Navigate to your Hercules/sql-files/ folder, and open the sql script file "main.sql".
# You'll see a bunch of code appear, these are commands that will tell the browser to create plain databases for your Hercules server. Click the yellow lightning bolt in the upper left hand corner to execute it and allow it to finish (ensure you click the first lightning bolt, the one without a cursor symbol or a magnifying glass over it).
# After it finishes, a bunch of executed commands will appear on the bottom of the screen. You can now expand the ragnarok schema to see a bunch of tables. ([http://imageshack.us/a/img72/1450/ragnaroktables.jpg Image])
# Now, do the same thing for a schema called "log", but open and execute logs.sql instead of main.sql. Ensure the tables are there as well.
# Close the existing query tabs by hitting the "X" in the upper right of the tab. With the ragnarok tables still open, scroll down to the "login" table and '''RIGHT click''' it, then select "Edit Table Data".
# Here you'll see existing account information that players can log in with to make characters. If you remember, the first account is the server communication account and it has the default password that you were asked to reset earlier. For our example we chose "FishUser" and "FishPassword". Enter these in the "username" and "password" field. And then create your first GM account by clicking where the word "null" is on the row with a ' * ' and enter "2000000" for the "account_id" field, with a username and password that you like. For this guide we chose a username of "HercGM" and a password of "12345" and a sex of "M". To enable full administrator GM, just set the "group_id" to "99". Zero out everything else. [http://imageshack.us/a/img411/5976/logintables.jpg When you are finished it should look like THIS].
# Hit the "Apply" button in the corner and then again when the code prompt appears. This should modify your tables. After it is done, you may close the SQL Editor by clicking the "X" on the tab at upper left corner. Hitting the "X" in the upper right closes the whole workbench. If you accidentally close it, just open it again.
# On the Workbench Home Screen, click "Manage Security" under Server Administration. Select "mysqld@localhost" and then click "OK".
# The next screen is the security window. You want to add an account that your server can use to access the databases that is NOT the root account, for enhanced security. Click "Add Account" in the lower left of the default screen.
# The login name needs to be "ragnarok", and the password we selected earlier for this guide is "Fish". The system will tell you how strong your password is... Fish is a very weak password. Leave the connectivity limit box defaulted and then hit "Apply" in the lower right. ([http://imageshack.us/a/img59/2025/newsecurityaccount.jpg Image])
# You'll see the account show up in the left above root. Select it and then click the "Administrative Roles" tab.
# Ensure that the "MonitorAdmin", "DBManager", "DBDesigner" and "BackupAdmin" are checked. Some of these will select themselves based on what you click. Then click "Apply". As a note, this step isn't entirely necessary but provides increased security. The simpler step is to just give the user all privileges by clicking the "DBA" option at the top. ([http://imageshack.us/a/img266/5876/useradministrativeroles.png Image])
# Click the "Schema Privileges" tab.
# In this tab, click "ragnarok" and then click the only available button, which is "Add Entry...".
# Leave "Any Host" selected and change Schema to "Selected Schemas". Then select the "ragnarok" schema and hit OK.
# At the bottom, hit "Select 'ALL'" to enable all database privileges for this Schema. This allows your ''ragnarok'' user to have access to all the tables in the schema of the same name. In other words, it allows your server to read/write the tables in the database you made. Make sure you click "Save Changes".
# Do the same for the "log" schema you made. When you are [http://imageshack.us/a/img89/1509/userschemaprivileges.jpg done it should look like this].
 
'''Congratulations!''' You have successful installed the MySQL database and are ready to run your server! See below for further adjustments.

==== Additional Configurations ====
===== Enabling Logging =====
Simply open log-server.conf in your conf folder, and look for:
// Use MySQL Logs? (SQL Version Only)
sql_logs: 0
Change 0 to 1. You can also go through and change logging options. Your logs will be stored within your log schema. To view IPs in loginlog, you must click it, then right click it and choose alter table, then click on the columns tab. For the PK row, check all of the boxes, then apply it. Now you can double click on the loginlog and view the IPs, though after you are done alter the table again and uncheck all the boxes, this helps insure security. This should only be done for IP bans.

===== Increasing Security =====
'''Use MD5 to encrypt your password''' 
** '''WARNING:''' This will turn your passwords gibberish, just numbers and letters, making them unreadable so be sure to note down your password, either in a text file on your C drive, or on a piece of paper. In MySQL Workbench, click edit, then preferences, then click the SQL Queries tab. Uncheck "(Safe Updates) Forbid UPDATE and DELETE statements without a WHERE clause...", then click OK. Make ragnarok your default schema, by right clicking its name and clicking "Set as Default Schema", now click File, then Open SQL script, and open convert_passwords.sql. Then click the execute icon.

== Linux ==
To Install the Mysql Server there is really only a few things that you have to do.

=== Installing MySQL ===
From your terminal, type
sudo yum install mysql-server*
- OR -
sudo apt-get install mysql-server

After your Operating System downloaded and installed MySQL, you will see your terminal window changed and you will be prompted to provide the root password for the MySQL server

=== Setting up your own user ===
Once the server has been installed you will need to call the server from terminal with this command.
mysql -u root
or
mysql -u root -p
then, type in your password.

You are now logged into the MySQL server as root. The best way to use your own SQL server is to have a username of your own control with your own password. The next command will create your own user. The <code>IDENTIFIED BY</code> clause defines the password.
CREATE USER 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
GRANT ALL PRIVILEGES ON 'ragnarok'.* to 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
flush privileges;

If that doesn't work it my be due to a version syntax error, try the following.

<pre>
CREATE USER 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
GRANT ALL PRIVILEGES ON ragnarok.* to 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
</pre>

=== Installing the Tables ===

<pre>
cd /path/to/Hercules/
</pre>

Note: Afterwards issue this command lines, please have your password prepared since every after command lines issued you will be prompted for it.

# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercuser_rodb < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodblog < logs.sql</pre>
# If your Control Panel software or website requires it, you may also import the item, monster and monster skill databases (not necessary for the correct operation of Hercules)
#: (pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db.sql</pre>
#: (renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db_re.sql</pre>
#: (common to renewal and pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db2.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_acc_reg_num_db, global_acc_reg_str_db, ipbanlist, login, loginlog
#map-server: autotrade_data, autotrade_merchants, mapreg, npc_market_data
#char-server: everything else
Note that the sql_updates table is needed by all three servers.

[[Category:Installation]]

Installing SQL

2015-07-08T13:01:30Z

Haru: Removed reference to the now deprecated SQL item and mob databases

= Introduction =
This article will guide you through the installation and configuration stages of MySQL for your particular Operating System. What is a MySQL database? [[wikipedia:MySQL|MySQL]] is a multi-user access database that stores a number of different kinds of information in scaleable tables. In layman's terms, it puts a bunch of stuff in charts for your server to read. Hercules no longer supports text based save files (for Accounts, Characters, etc.) and requires a MySQL database to create these save files.

== Windows ==
This guide will instruct you on installing MySQL on Windows Vista/7, although it should work relatively the same with Windows XP. This guide also assumes you have already [[Installation_on_Windows|installed your Hercules server]]. 
 
'''<big>Uninstallation Note</big>''' 
Before continuing, it is important to note that if you make an error and decide to start again by uninstalling the MySQL database and software, that you make sure you do a ''thorough'' uninstallation, and then reboot Windows before trying again. A couple tips to make sure your uninstallation is thorough:
* Uninstall Workbench first
* Remove the MySQL database folders in your user folder. This is generally in:
C:\Users\<YOUR_USER_NAME>\AppData\Roaming\MySQL
:Just delete the whole folder.
* Run Administrative Tools -> Services and look to make sure nothing MySQL related is running or set to run (because it shouldn't exist anymore)
* Go to the location on your hard drive you installed MySQL5 and Workbench and ensure everything is deleted.
* Make sure you reboot.
* There is a Oracle made guide [http://dev.mysql.com/doc/refman/5.1/en/windows-installer-uninstalling.html here], but it isn't necessarily thorough.
* If you still have hanging and crashing during the configuration wizard, you may have to create your root account manually. Do an internet search for this, as it varies by system. And continue afterwards at the "MySQL Workbench" section.

=== Download ===
To install MySQL Server you will first need to download the package corresponding to your version of Windows. [http://dev.mysql.com/downloads/mysql/ MySQL Community Server] is available for free and is exactly what is needed. Version 5.5 currently works well with Hercules and is recommended. '''ENSURE''' that you download the appropriate bit version (32 or 64) for your system, if you do not, you will receive errors during the execution wizard. This software installs the server on your computer that stores the data files and tables. Although alone, without prior knowledge of MySQL it is very difficult to operate and configure your servers data. That is why you will need MySQL Workbench. 
 
[http://dev.mysql.com/downloads/workbench/5.2.html MySQL Workbench] is a tool for viewing your MySQL database in a GUI environment. As said, it is not required but very beneficial; in addition, it is required by this guide. To be able to install and run MySQL Workbench 5.2 your System also needs to have the libraries listed below installed. The listed items are provided as links to the corresponding download pages where you can fetch the necessary files.

[http://www.microsoft.com/download/en/details.aspx?id=17113 Microsoft .NET Framework 4 Client Profile] 
[http://www.microsoft.com/download/en/details.aspx?id=5555 Microsoft Visual C++ 2010 Redistributable Package (x86)]

=== Configure Hercules Files ===
Before you begin with your MySQL installation, you need to setup your server conf files to be ready for the database you are about to install. I choose to do this in advance, because it allows you to have the usernames and passwords ready for use so you don't have to go back and set them, and you can just run your server afterwards with everything all ready.
* Open "inter-server.conf", and change sql.db_password, char_server_pw, map_server_pw and log_db_pw to a password of your choice. For this guide we will use the password "Fish". Passwords are case sensitive. This is not a strong password, and you should use a better one, this is just an example. Also change log_db_db to "log". All other fields should be let alone, the default username and port functions fine. ([http://imageshack.us/a/img546/9444/interathena.jpg Image])
* Open "map-server.conf" and "char-server.conf" and locate the server communication passwords:
userid: s1
passwd: p1
Change these to whatever you want, but something secure. For this guide we will use "FishUser" and "FishPassword"
userid: FishUser
passwd: FishPassword
 
Make sure these are the same in both map-server and char-server otherwise you will have errors.
* There are additional SQL configuration features in "login-server.conf" that you should take a look at now, to enable for use (such as IPban features).
* Write all these passwords down or keep the files open for reference and continue to your MySQL installation!

=== Install MySQL ===
First, you will need to install the MySQL server where all the data will be stored. After downloading the [http://dev.mysql.com/downloads/mysql/ MySQL Community Server], run the installer and use the following steps (''for this installation version 5.5.28 was used'').
# Click next and accept the license agreement.
# Click "Typical" for Setup Type; then click "Install" (you may have to allow UAC control from windows).
# Click "Next" when the MySQL Enterprise tool pops up, this is a simple advertisement.
# After installation is finished the completion screen with a "Finish" button will show, make sure you have "Launch the MySQL Instance Configuration Wizard" '''CHECKED'''! The configuration wizard will allow you to setup the server to accept the kind of data you want and by setting it up now you will most likely never have to configure it again.
# Click "Next" at the first screen, and then click "[http://imageshack.us/a/img90/1771/standardconfig.jpg Standard Configuration]" and hit "Next".
# Check both "Install As Windows Service" and "Include Bin Directory in Windows PATH" for the Service Name, name it "''MySQL5''" and ensure "Launch the MySQL Server Automatically is '''CHECKED'''. ([http://imageshack.us/a/img685/3323/serverinstance.jpg Image])
# On the next screen, you will need to select the root password. This password is very important as you will '''never be able to retrieve it''' so make sure you write it down somewhere safe. The "root" access to your MySQL database can pretty much do anything to your data, so make sure you keep this information safe. If you want to enable root access from a remote machine, check the included box. You probably won't need to enable that unless you know what you're doing. Keep the password you selected available for now.
# On the next screen just click "Execute" to run the configuration unless you want to go back and change something.
# Once it is finished, hit "Finish" to close the wizard. It will report if there are any errors (there shouldn't be).

=== MySQL Workbench ===
Next it is time to install the MySQL Workbench application. This application will allow you to edit your database and prepare it for Hercules, as well as perform maintenance in the future.
# Run the MySQL Workbench installer and click "Next" on the first screen.
# Choose your installation directory. The default directory should be fine. Click "Next" to proceed.
# Select "Complete" and click "Next", and then install, granting permissions when prompted.
# Once the wizard is completed, hit "Finish" and the default Workbench screen will come up.
# This is called the Home Screen and should look like [http://imageshack.us/a/img571/3885/workbenchhome.jpg this].
# You need to create a new server instance to host your files for Hercules to access. Select "New Server Instance" under the "Server Administration" section.
# A window will pop up, select "localhost" and click "Next". This installs the instance on the localhost, which is your computer.
# On the next screen, leave everything the default. Where it says "Username" leave that at root, so you have root access. Under that, click "[http://imageshack.us/a/img845/4056/storeinvault.jpg Store in Vault]" and enter the root password from earlier (it's alright to copy/paste the password if you put it in a text file).
# After it has successfully tested the database connection, click "Next"
# On the next screen, leave the configuration settings defaulted. It should point to the existing service (MySQL5 from earlier) and the default path is fine. ([http://imageshack.us/a/img600/1089/defaultwindowsconfig.jpg Image])
# On the next screen hit "Next" and then "Continue" on the popup. Leave the Server Instance with the default name of
mysqld@localhost
You are now ready to install your Hercules databases.

=== Database Installation ===
It is now time to install the pre-installed database files that will allow your Hercules server to connect to your MySQL database and properly store data, such as characters, items, and guilds. Open up MySQL Workbench to the home screen.
# Double click "localhost" on the left under the "SQL Development" section. ([http://imageshack.us/a/img337/8550/localhostdoubleclick.jpg Image])
# On the next screen (after a small loading bubble pops up), you will have access to the specific tables that were mentioned earlier. You will enter this screen in the future when you want to edit accounts and other things directly (not common).
# We need to install a new "Schema", this is like a folder where all the database tables are stored. [http://imageshack.us/a/img194/2897/newschema.jpg Click the yellow cylinder looking thing in the upper left to create a new Schema]. Name it "ragnarok" - '''NOTE!''' Lower case is important here, make sure it is exactly "ragnarok". The server collation should be "Server Default".
# Click "Apply" to create the Schema. A window will pop up with the actual commands that are going to take place; click "Apply" again to finalize your order.
# Now right click 'ragnarok' under "Object Browser" and click "Set as default schema", a line will appear through it telling the browser that any commands you make now will be ordered to that Schema.
# Next, [http://imageshack.us/a/img571/205/opensqlscript.png click the button directly to the left of the one you just did], it says "SQL" with a tiny folder. Navigate to your Hercules/sql-files/ folder, and open the sql script file "main.sql".
# You'll see a bunch of code appear, these are commands that will tell the browser to create plain databases for your Hercules server. Click the yellow lightning bolt in the upper left hand corner to execute it and allow it to finish (ensure you click the first lightning bolt, the one without a cursor symbol or a magnifying glass over it).
# After it finishes, a bunch of executed commands will appear on the bottom of the screen. You can now expand the ragnarok schema to see a bunch of tables. ([http://imageshack.us/a/img72/1450/ragnaroktables.jpg Image])
# Now, do the same thing for a schema called "log", but open and execute logs.sql instead of main.sql. Ensure the tables are there as well.
# Close the existing query tabs by hitting the "X" in the upper right of the tab. With the ragnarok tables still open, scroll down to the "login" table and '''RIGHT click''' it, then select "Edit Table Data".
# Here you'll see existing account information that players can log in with to make characters. If you remember, the first account is the server communication account and it has the default password that you were asked to reset earlier. For our example we chose "FishUser" and "FishPassword". Enter these in the "username" and "password" field. And then create your first GM account by clicking where the word "null" is on the row with a ' * ' and enter "2000000" for the "account_id" field, with a username and password that you like. For this guide we chose a username of "HercGM" and a password of "12345" and a sex of "M". To enable full administrator GM, just set the "group_id" to "99". Zero out everything else. [http://imageshack.us/a/img411/5976/logintables.jpg When you are finished it should look like THIS].
# Hit the "Apply" button in the corner and then again when the code prompt appears. This should modify your tables. After it is done, you may close the SQL Editor by clicking the "X" on the tab at upper left corner. Hitting the "X" in the upper right closes the whole workbench. If you accidentally close it, just open it again.
# On the Workbench Home Screen, click "Manage Security" under Server Administration. Select "mysqld@localhost" and then click "OK".
# The next screen is the security window. You want to add an account that your server can use to access the databases that is NOT the root account, for enhanced security. Click "Add Account" in the lower left of the default screen.
# The login name needs to be "ragnarok", and the password we selected earlier for this guide is "Fish". The system will tell you how strong your password is... Fish is a very weak password. Leave the connectivity limit box defaulted and then hit "Apply" in the lower right. ([http://imageshack.us/a/img59/2025/newsecurityaccount.jpg Image])
# You'll see the account show up in the left above root. Select it and then click the "Administrative Roles" tab.
# Ensure that the "MonitorAdmin", "DBManager", "DBDesigner" and "BackupAdmin" are checked. Some of these will select themselves based on what you click. Then click "Apply". As a note, this step isn't entirely necessary but provides increased security. The simpler step is to just give the user all privileges by clicking the "DBA" option at the top. ([http://imageshack.us/a/img266/5876/useradministrativeroles.png Image])
# Click the "Schema Privileges" tab.
# In this tab, click "ragnarok" and then click the only available button, which is "Add Entry...".
# Leave "Any Host" selected and change Schema to "Selected Schemas". Then select the "ragnarok" schema and hit OK.
# At the bottom, hit "Select 'ALL'" to enable all database privileges for this Schema. This allows your ''ragnarok'' user to have access to all the tables in the schema of the same name. In other words, it allows your server to read/write the tables in the database you made. Make sure you click "Save Changes".
# Do the same for the "log" schema you made. When you are [http://imageshack.us/a/img89/1509/userschemaprivileges.jpg done it should look like this].
 
'''Congratulations!''' You have successful installed the MySQL database and are ready to run your server! See below for further adjustments.

==== Additional Configurations ====
===== Enabling Logging =====
Simply open log-server.conf in your conf folder, and look for:
// Use MySQL Logs? (SQL Version Only)
sql_logs: 0
Change 0 to 1. You can also go through and change logging options. Your logs will be stored within your log schema. To view IPs in loginlog, you must click it, then right click it and choose alter table, then click on the columns tab. For the PK row, check all of the boxes, then apply it. Now you can double click on the loginlog and view the IPs, though after you are done alter the table again and uncheck all the boxes, this helps insure security. This should only be done for IP bans.

===== Increasing Security =====
'''Use MD5 to encrypt your password''' 
** '''WARNING:''' This will turn your passwords gibberish, just numbers and letters, making them unreadable so be sure to note down your password, either in a text file on your C drive, or on a piece of paper. In MySQL Workbench, click edit, then preferences, then click the SQL Queries tab. Uncheck "(Safe Updates) Forbid UPDATE and DELETE statements without a WHERE clause...", then click OK. Make ragnarok your default schema, by right clicking its name and clicking "Set as Default Schema", now click File, then Open SQL script, and open convert_passwords.sql. Then click the execute icon.

== Linux ==
To Install the Mysql Server there is really only a few things that you have to do.

=== Installing MySQL ===
From your terminal, type
sudo yum install mysql-server*
- OR -
sudo apt-get install mysql-server

After your Operating System downloaded and installed MySQL, you will see your terminal window changed and you will be prompted to provide the root password for the MySQL server

=== Setting up your own user ===
Once the server has been installed you will need to call the server from terminal with this command.
mysql -u root
or
mysql -u root -p
then, type in your password.

You are now logged into the MySQL server as root. The best way to use your own SQL server is to have a username of your own control with your own password. The next command will create your own user. The <code>IDENTIFIED BY</code> clause defines the password.
CREATE USER 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
GRANT ALL PRIVILEGES ON 'ragnarok'.* to 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
flush privileges;

If that doesn't work it my be due to a version syntax error, try the following.

<pre>
CREATE USER 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
GRANT ALL PRIVILEGES ON ragnarok.* to 'ragnarok'@'%' IDENTIFIED BY 'ragnarok';
</pre>

=== Installing the Tables ===

<pre>
cd /path/to/Hercules/
</pre>

Note: Afterwards issue this command lines, please have your password prepared since every after command lines issued you will be prompted for it.

# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercules1234_rag < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_skill_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_skill_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_log < logs.sql</pre>
# If you are using Renewal you also have to import the following
#: <pre>mysql -u root -prootpassword hercules1234_log < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_log < item_db2_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_log < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_log < mob_skill_db_re.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_reg_value, ipbanlist, login, loginlog
#map-server: mapreg, item_db, item_db2, mob_db, mob_db2
#char-server: everything else + global_reg_value once again
Note that global_reg_value tables are needed by both login-server and char-server (though it may be different tables)

[[Category:Installation]]

Installation (CentOS)

2015-07-08T13:00:39Z

Haru: Updated SQL tabiles information

This guide covers how to install [[Hercules]] on [[wikipedia:CentOS|CentOS]] and other [[wikipedia:List_of_Linux_distributions#RPM-based|versions of Linux]] that use [[wikipedia:Yellowdog_Updater,_Modified|yum]].

== Requirements ==
* [[wikipedia:CentOS|CentOS]] or an [[wikipedia:List_of_Linux_distributions#RPM-based|RPM-based Linux]] that has the '''[[wikipedia:Yellowdog_Updater,_Modified|yum]]''' command
* root access or access to an account that has [[wikipedia:Sudo|sudo privileges]]
* an Internet connection to download install packages

== Prerequisites ==
All of these commands will be typed at the [[wikipedia:Command-line_interface|command-line interface]].
=== Install Prerequisites ===
# Login to your server via [[wikipedia:Secure_Shell|SSH]], or if you are already logged into a [[wikipedia:Graphical_user_interface|GUI]] press Ctrl+Alt+T to open a terminal window.
# Type the following command (this will install GCC, Make, MySQL, MySQL header files, MySQL Server, PCRE header files, Git, and Zlib header files)
#: <pre>yum install gcc make mysql mysql-devel mysql-server pcre-devel git zlib-devel</pre>
# (Optional) type the following command to install some additional packages:
#: <pre>yum -y install dos2unix gdb nano screen unzip wget zip</pre>

=== Create a non-root Linux user ===
By the [[wikipedia:Principle_of_least_privilege|principle of least privilege]], it is recommended you do '''NOT''' run Hercules as root.
# Type the following command to create a non-root Linux account:
#: <pre>useradd --create-home --shell /bin/bash hercules1234</pre>
#: <code>--create-home</code> = create the user's home directory
#: <code>--shell</code> = sets their login shell to [[wikipedia:Bash_(Unix_shell)|Bash]]
#: '''<code>hercules1234</code>''' = the login name of the new Linux account
#: ''<code>1234</code>'' = pick your own random numbers to make the username more unique
# Set a password for the new user (run this command and follow the prompts):
#: <pre>passwd hercules1234</pre>

=== Configure MySQL ===

==== Set a root password ====
The default MySQL Server install creates a MySQL user 'root'@'localhost' with NO password. It is recommended you create a password for the root user.
# Run this command and follow the prompts:
#: Firest Start MySQL:
#: <pre>/etc/init.d/mysqld start </pre>
#: Then configure MySQL by:
#: <pre>mysql_secure_installation</pre>
# Login to your MySQL Server as root:
#: ''When prompted, enter your root MySQL password.''
#: <pre>mysql --user=root -p</pre>
# Now your prompt should look like this (the MySQL command prompt):
#: <pre>mysql> </pre>

==== Create SQL database for Hercules ====
# At the MySQL prompt, type this to [http://dev.mysql.com/doc/refman/5.5/en/create-database.html create a database] (replace <code>hercules1234</code> with the Linux username you created earlier):
#: <pre>mysql> CREATE DATABASE hercules1234_rag;</pre>
# Create a separate database for logs:
#: <pre>mysql> CREATE DATABASE hercules1234_log;</pre>

==== Setup a MySQL user for Hercules ====
# At the MySQL prompt, type something like this to create a new MySQL user:
#: <pre>mysql> CREATE USER 'hercules1234'@'localhost' IDENTIFIED BY 'secretpassword';</pre>
#: <code>hercules1234</code> = the name of the MySQL user (we named it the same as the Linux user to make it easier to identify)
#: <code>localhost</code> = the hostname or IP it will connect from
#: '''<code>secretpassword</code>''' = the password for this MySQL user
# [http://dev.mysql.com/doc/refman/5.5/en/grant.html Grant privileges] to the 'hercules' MySQL user:
#: <pre>mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON `hercules1234\_rag`.* TO 'hercules1234'@'localhost';</pre>
#: <pre>mysql> GRANT SELECT,INSERT ON `hercules1234\_log`.* TO 'hercules1234'@'localhost';</pre> (note the [http://dev.mysql.com/doc/refman/5.5/en/string-literals.html#character-escape-sequences escaped underscore])

== Install [[Hercules]] ==

=== Login as your non-root Linux user ===
The rest of the setup is done as hercules1234 (the Linux user you created in step 2.2)
# Logout from root SSH (or minimize the window).
# Login to your server via SSH as the hercules1234 Linux user.

=== Git Clone ===
{{:Git Clone/Unix}}

=== [http://dev.mysql.com/doc/refman/5.5/en/batch-commands.html Import] MySQL Tables ===
# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercuser_rodb < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodblog < logs.sql</pre>
# If your Control Panel software or website requires it, you may also import the item, monster and monster skill databases (not necessary for the correct operation of Hercules)
#: (pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db.sql</pre>
#: (renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db_re.sql</pre>
#: (common to renewal and pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db2.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_acc_reg_num_db, global_acc_reg_str_db, ipbanlist, login, loginlog
#map-server: autotrade_data, autotrade_merchants, mapreg, npc_market_data
#char-server: everything else
Note that the sql_updates table is needed by all three servers.

=== [[:Category:Configuration|Configure Hercules]]===

=== Compile Source Code ===
cd Hercules
./configure
make sql

===== How to Recompile =====
In the future (after you update or edit any file in /src) to recompile, add ''make clean'' before make sql:
cd Hercules
./configure
'''make clean'''
make sql

== Start your Hercules Server ==
//change access mode of athena-start file so that you can execute it.
//Use (dos2unix athena-start) if yo uare getting ^M errors ie. newline errors
chmod a+x athena-start

//To Start
./athena-start start
//To Stop
./athena-start stop
//To Restart
./athena-start restart

== See Also ==

[[Category:Installation Guides|CentOS]]

Installation (Debian)

2015-07-08T12:59:51Z

Haru: /* Import MySQL Tables */

This guide covers how to install [[Hercules]] on [[wikipedia:Debian|Debian]] and other [[wikipedia:List_of_Linux_distributions#Debian-based|versions of Linux]] that use apt-get.

== Requirements ==
* [[wikipedia:Debian|Debian]] or an [[wikipedia:List_of_Linux_distributions##Debian-based]] that has the apt-get command
* root access or access to an account that has [[wikipedia:Sudo|sudo privileges]]
* an Internet connection to download install packages

== Prerequisites ==
All of these commands will be typed at the [[wikipedia:Command-line_interface|command-line interface]].
=== Install Prerequisites ===
# Login to your server via [[wikipedia:Secure_Shell|SSH]], or if you are already logged into a [[wikipedia:Graphical_user_interface|GUI]] press Ctrl+Alt+T to open a terminal window.
apt-get update
apt-get upgrade
apt-get dist-update // To update to the latest version of Debian
# Type the following command (this will install GCC, Make, MySQL Server, MySQL header files, PCRE header files, git, and Zlib header files)
#: <pre>apt-get install git make gcc mysql-server libmysqlclient-dev zlib1g-dev libpcre3-dev screen</pre>

=== Create a non-root Linux user ===
By the [[wikipedia:Principle_of_least_privilege|principle of least privilege]], it is recommended you do '''NOT''' run Hercules as root.
# Type the following command to create a non-root Linux account:
#: <pre>useradd hercuser</pre>
# Be sure not to forget setting new password for new user
#: <pre>passwd hercuser</pre>

== Install [[Hercules]] ==

=== Login as your non-root Linux user ===
The rest of the setup is done as hercuser (the Linux user you created earlier)
# Logout from root SSH (or minimize the window).
# Login to your server via SSH as the hercuser Linux user.

=== Git Clone ===
<pre>git clone https://github.com/HerculesWS/Hercules.git ~/Hercules</pre>

=== [http://dev.mysql.com/doc/refman/5.5/en/batch-commands.html Import] MySQL Tables ===
# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercuser_rodb < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodblog < logs.sql</pre>
# If your Control Panel software or website requires it, you may also import the item, monster and monster skill databases (not necessary for the correct operation of Hercules)
#: (pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db.sql</pre>
#: (renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db_re.sql</pre>
#: (common to renewal and pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db2.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_acc_reg_num_db, global_acc_reg_str_db, ipbanlist, login, loginlog
#map-server: autotrade_data, autotrade_merchants, mapreg, npc_market_data
#char-server: everything else
Note that the sql_updates table is needed by all three servers.

=== [[:Category:Configuration|Configure Hercules]]===

=== Compile Source Code ===
cd Hercules
./configure
make sql

*If you have added plugins for use with Hercules please use the below syntax instead of the above:
cd Hercules
./configure
make sql plugins

===== How to Recompile =====
In the future (after you update or edit any file in /src) to recompile, add ''make clean'' before make sql:
cd Hercules
./configure
'''make clean'''
make sql plugins

== Start your Hercules Server ==
//change access mode of athena-start file so that you can execute it.
//Use (dos2unix athena-start) if you are getting ^M errors ie. newline errors
chmod a+x athena-start

//To Start
./athena-start start
//To Stop
./athena-start stop
//To Restart
./athena-start restart

== See Also ==

[[Category:Installation Guides|Debian Linux]]

Overview of Errors

2015-07-08T12:56:18Z

Haru: Corrected item database filenames, removed reference to SQL item databases.

This article will, in the end, contain all possible script related errors, what their causes are and what you should do to fix them.

== Introduction ==
{{Incomplete|type=section}}
=== Definition of Error ===
The errors mentioned in this article, are all the possible script related errors that show in the map-server's console. These errors are often accompanied by a tag in front of it. The tag will be [Error] or [Fatal Error]. (Where fatal error will crash your server.) Also, the errors that display a part of a script with *'s in front of it (Parsing Errors), will be covered in this article.
Please do note that you must be in debugging mode, which is if I'm not mistaking, the default mode. This article will not cover the different kinds of script related warnings, because the error-list alone is already massive.

=== How to Find and Fix Your Error ===
Fixing errors in scripts require some handiness. Single errors are easy to do, but sometimes, you get a lot of errors. Do not be afraid then though, because a large list of errors will often be fixed, by fixing the first error. So, when using this guide, search for the topmost error in your server's console first, and try to fix it. If it is fixed, there is a 50% chance that all the other errors will disappear.

Sometimes though, the amount of errors are so huge, that you cannot scroll high enough to find the first error. If this is the case, then there are three ways to make it easier for you:
* Fetch the error stream and save it to a file
* Comment out the newly added NPCs, or only make the newly added NPCs load.
* Divide your NPCs into smaller NPCs.
How to do the first, I am afraid to say, I forgot. The second one is fairly easy though. Removing your new scripts from the conf files, and starting up your server then, will tell you where to look. If the errors are gone, then they are most likely in your new scripts. Otherwise, they are in the default scripts. If they are in your new scripts, then it is wise to first read to that script again, to remove obvious errors. Also, always check the header. If you make a single mistake in the header, the rest of the script will bug out. If that still doesn't help, decrease the error list, then consider to have your server only load the new scripts, one at the time, in the hope that it will show fewer errors.

However, if that still doesn't allow you to find the topmost error, then there is always the third option - breaking down your script in smaller NPCs. What this means, is that you just randomly put inside your script a } followed by a valid header. Then you've split your script in two halves. 50% chance that 50% of the errors will be gone, and that you are closer to finding the solution. If the error list is still too long, simply split it up again, and again, and again, until you can see all the errors of a single NPC in your screen. That way, you can find the first error in that specific NPC, and fix it. This will result into the mapserver only showing the errors in the broken down NPCs before that NPC. I know, it's a long method, but sometimes, it's the only way. But when you have found the original error, then you can use this guide to find a solution for it.

Each error will have it's own section, in which the exact error is listed. These sections will also contain an explanation on what likely caused this error and what possible fixes are. This all is accompanied by one or more examples, to make everything more clear.
To quickly find your specific error, search for a part of the error message, of course, without the Error tag. When searching for it, make sure that you do not include the things that can alter, like NPC name, file name, variable name etc.

If the error you want to search for, almost completely contains custom things, like that NPC name etc, and you still want to look for it, then try replacing all the parts that can change by three dots. For example if you want to search for this error:
Out of range spawn coordinates: prt_fild08 (-50,-50), map size is (250,250)
then try using this to search for:
Out of range spawn coordinates: ... (...,...), map size is (...,...)
If this still doesn't give any results, you can always try the main index list. However, older error lines do not show up in this one. So, if you are also unsuccessful there, then please try the [[#Outdated Errors|Outdated Errors]] section as a last resort. It lists all old error message. If you still cannot find it, then you can always try the Scripting Support forum.

=== Using Older GIT Revisions ===
You are probably not using the latest version of Hercules. Unfortunately, over time, some errors change in text, or even become obsolete (erased). To not put you in a disadvantage, we will keep track of older error reports. At the moment, we have up to Revision 12340 covered for the script.c related errors, and up to 11501 covered for npc.c related errors.

When time comes, we will try to cover even older errors, and change the list if new errors appear, or when they change in syntax. However, if the error that you are looking for, is not in the normal list, nor the Outdated Errors list, then your best chance is asking for support in the Script Support Forum on the forums. Please, do not forget to mention your GIT revision when doing this.

== Overview of Errors ==
There is a total of over 152 errors at the moment. Currently, 152 of them are covered. This is 100.00% of the total for the script.c section and an unknown percentage for the npc.c section.

=== Outdated Errors ===
This list contains all currently known old errors messages that have been changed. They will link you to the current version of the error.

==== Up to Revision 10812 ====
----
* [[Overview_of_Errors#script:guardian:_invalid_data_type_for_argument_.236_.28from_1.29|buildin_guardian: invalid data type for argument #8 (...).]]
* [[Overview_of_Errors#script:input:_not_a_variable script:|buildin_input: given argument is not a variable!]]
* [[Overview_of_Errors#script:set:_not_a_variable|script: buildin_set: not name]]
* [[Overview_of_Errors#script:callsub:_argument_is_not_a_label|script: callsub: not label !]]
* [[Overview_of_Errors#script:getvariableofnpc:_can.27t_find_npc_... script:|getvariableofnpc: can't find npc ...]]
* [[Overview_of_Errors#script:getvariableofnpc:_not_a_variable|script: getvariableofnpc: first argument is not a variable name]]
* [[Overview_of_Errors#script:getvariableofnpc:_invalid_scope_.28not_npc_variable.29|script: getvariableofnpc: invalid scope ... (not npc variable)]]
* [[Overview_of_Errors#script:goto:_not_a_label|script:goto: not label!]]
* [[Overview_of_Errors#script:menu:_argument_.23..._.28from_1.29_is_not_a_label_or_label_not_found.|script:menu: argument #... (from 1) is not a label or label not found (op=...).]]
* [[Overview_of_Errors#script:menu:_argument_.23..._.28from_1.29_is_not_a_string_or_compatible.|script:menu: argument #... (from 1) is not a string or compatible (op=...).]]
* [[Overview_of_Errors#script:op_1:_argument_is_not_a_number_.28op.3D....29|script:op_1: invalid type of data op:... data:...]]
* [[Overview_of_Errors#script:op_1:_unexpected_operator_..._i1.3D...|script:op_1: unexpected operator op:...]]
* [[Overview_of_Errors#script:op_2:_invalid_data_for_operator_...|script:op_2: invalid type of data op:... left:... right:...]]
* [[Overview_of_Errors#script:op_2num:_division_by_zero_detected_op.3D..._i1.3D..._i2.3D...|script:op_2num: division by zero detected op:...]]
* [[Overview_of_Errors#script:op_2num:_unexpected_number_operator_..._i1.3D..._i2.3D...|script:op_2num: unexpected number operator op:...]]
* [[Overview_of_Errors#script:op2_str:_unexpected_string_operator_...|script:op2_str: unexpected string operator op:...]]
* [[Overview_of_Errors#script:op_3:_invalid_data_for_the_ternary_operator_test|script:op_3: invalid type of data op:... data:...]]
* [[Overview_of_Errors#script:warpportal:_npc_is_needed|script:warpportal: npc is needed]]

== In-depth Info on Errors ==
=== Warnings (script.c) ===
Warnings do not necessarily mean, that something is wrong, but can work in an undesired way.

==== Unexpected type for argument ... Expected ... ====
'''Cause''' 
The data type of the value passed into a build-in function's argument differs from the one defined in that function's BUILDIN_DEF definition, typically passing a number where a string is expected and vice versa. A set of [Debug] messages follow this warning, that specify the function's parameters, the function itself and the NPC that hosts the reported script. This warning occurs only during runtime of a script. Note, that the affected script continues to run and auto-conversion rules apply, except the script command itself stops the execution of the script (typically commands that deal with variables and labels).

'''Solution''' 
Verify all values passed to the function and make sure, that all of them have the expected type.

'''Example''' 
[[itemheal]] "200",0;
The first parameter is supposed to be a number (amount of HP to heal). So the correct script would be:
itemheal 200,0;

=== Errors (npc.c) ===
All errors located in npc.c that have the [Error] tag are listed in this section. 
==== bad duplicate name (in ...)! : ... ====
Source Syntax: ShowError("bad duplicate name (in %s)! : %s", file, w2);
 Cause 
The format of your duplicate line is wrong. What is missing, is either which NPC the duplicate command should copy or the use of an incorrect name or incorrect characters. The error is located in the file that is mentioned between the ( and ). The name that the server found, if any there, is displayed after the :.
 Solution 
Make sure that you have put an event label in the duplicate name. The format should be one of the following two:
map,x,y,d<tab>duplicate(EVENT LABEL)<tab>New name<tab>sprite
map,x,y,d<tab>duplicate(EVENT LABEL)<tab>New name<tab>sprite,triggerx,triggery
 Example 
Wrong code:
prontera,200,200,4<tab>script<tab>Original::TestNPC<tab>46,{
mes "Hi";
close;
}

prontera,210,200,4<tab>duplicate()<tab>Copy<tab>46
The last line is missing the event label between the brackets. It should be this:
prontera,210,200,4<tab>duplicate(TestNPC)<tab>Copy<tab>46
 

----

==== bad duplicate name (in ...)! (not exist) : ... ====
Source Syntax: ShowError("bad duplicate name (in %s)! (not exist) : %s\n", file, srcname);
 Cause 
This error is trying to tell you that you are duplicating a non-existing NPC.
 Solution 
Make sure that the NPC you want to duplicate, has the same Event Label as you specified between the round brackets behind duplicate. Either correct the Event Label of the original NPC or the Event Label in the duplicate line. Or, erase the duplicate line. Remember, the format for the original NPC is:
map,x,y,d,<tab>script<tab>Original Name::My_Event_Label<tab>sprite{,triggerx,triggery},{
And for the duplicate:
map,x,y,d,<tab>duplicate(My_Event_Label)<tab>New Name<tab>sprite{,triggerx,triggery}
 Example 
Wrong code:
prontera,200,200,4<tab>script<tab>Original<tab>46,{
mes "Hi";
close;
}

prontera,210,200,4<tab>duplicate(TestNPC)<tab>Copy<tab>46
The first line is missing the event label between the brackets. It should be this:
prontera,210,200,4<tab>script<tab>Original::TestNPC<tab>46
 

----

==== bad monster ID : ... ... (file ...) ====
Source Syntax: ShowError("bad monster ID : %s %s (file %s)\n", w3, w4, current_file);
 Cause 
The monster you are trying to spawn, does not exist. At least, the mapserver could not find it's mob_id in mob_db.txt or mob_db2.txt. (Or possibly not in the homunculus db.)
 Solution 
Either add the monster to the mob_db2.txt file, or change the mob_id number in the spawn line to the correct mob_id number.
 Example 
Wrong code:
monster "prt_fild08",100,100,"Poring",999,5;
Correct code:
monster "prt_fild08",100,100,"Poring",1002,5;

----

==== bad monster line : ... ... ... (file ...) ====
Source Syntax: ShowError("bad monster line : %s %s %s (file %s)\n", w1, w3, w4, current_file);
 Cause 
For a monster line to be correct, it needs to have at least the following:
* Valid mapname
* Valid x
* Valid y
And it also needs to have at least:
* Valid class
* Valid amount
If you only have two or less of the topmost, and/or 1 or less of the bottom two, then this error will occur.
 Solution 
Make sure that your monster line contains at least the needed information. Check if you have a mapname, x, y, mob_id and an amount, and correct it where needed.
 Example 
Wrong code:
monster "prt_fild08","Poring",5;
Correct code:
monster "prt_fild08",0,0,"Poring",1002,5;

----

==== bad script line (in file ...): ... ====
Source Syntax: ShowError("bad script line (in file %s): %s\n", file, w3);
 Cause 
This error occurs when the header of your NPC is incorrect. There are two separate ways for a NPC header to function correctly:
map,x,y,d<tab>script<tab>Name<tab>sprite,{
-<tab>script<tab>Name<tab>-1,{
When the server does not detect a dash (-) at the start of your header, it will check for the other format. If it does not find a mapname, x, y, direction, the word script or a comma after the sprite, then it will give you this error.
 Solution 
Recheck, if you abide the rules of writing a NPC header. Make sure you have all the commas in the right spots, that you have the location setup correctly and that you are using the script identifier word.
 Example 
Wrong code:
prontera,200,200<tab>script<tab>My NPC<tab>48,{
Correct code:
prontera,200,200,4<tab>script<tab>My NPC<tab>48,{

----

==== Bad setcell line : ... ====
Source Syntax: ShowError("Bad setcell line : %s\n",w3);
 Cause 
You did not obey the format for using the setcell command. The format should be:
<map name>%TAB%setcell%TAB%<type>,<x1>,<y1>,<x2>,<y2>
This error occurs when you forgot one of the following five things:
* Forgot to define the type.
* Forgot to define x1
* Forgot to define y1
* Forgot to define x2
* Forgot to define y2
 Solution 
Recheck, if the way you defined your setcell line is correct. There should be a tab, followed by 5 arguments after the setcell keyword.
 Example 
Wrong code:
prontera<tab>setcell<tab>cell_wall,170,50,171
Correct code:
prontera<tab>setcell<tab>cell_wall,170,50,171,100

----

==== bad shop line : ... ====
Source Syntax: ShowError("bad shop line : %s\n", w3);
 Cause 
You did not obey the format of a shop header. Make sure it uses the following format:
map,x,y,d<tab>shop<tab>Name<tab>sprite,{item list + prices}
This error occurs when you are missing the mapname, x, y and/or direction.
 Solution 
Recheck if you are using the shop header in the correct way. Add the missing mapname, x-coordinate, y-coordinate and/or direction.
 Example 
Wrong code:
prontera,100,100<tab>shop<tab>My First Shop<tab>83,501:-1,502:-1,503:-1,504:-1,506:-1
Correct code:
prontera,100,100,4<tab>shop<tab>My First Shop<tab>83,501:-1,502:-1,503:-1,504:-1,506:-1
----

==== bad warp line : ... ====
Source Syntax: ShowError("bad warp line : %s\n", w3);
 Cause 
You didn't use the warp NPC header correctly. Make sure it uses the following format:
from_map,from_x,from_y,d<tab>warp<tab>Name<tab>trigger_x,trigger_y,to_map,to_x,to_y
This error occurs when you are missing one of the parameters given after the name. (Destination map and coordinates and trigger size.)
 Solution 
Recheck if you are using the warp header in the correct way. Add what is missing.
 Example 
Wrong code:
prontera,107,215,0<tab>warp<tab>prt01<tab>prt_in,240,139
Correct code:
prontera,107,215,0<tab>warp<tab>prt01<tab>2,2,prt_in,240,139

----

==== bad warp line (destination map not found): ... ====
Source Syntax: ShowError("bad warp line (destination map not found): %s\n", w3);
 Cause 
Your mapserver failed to find the map where the warp is supposed to go to.
 Solution 
Make sure that the destination you typed in your warp line, really exists and is a map loaded by the server. Of course, also check it for typos.
 Example 
Wrong code:
prontera,107,215,0<tab>warp<tab>prt01<tab>prontera_in,240,139
Correct code:
prontera,107,215,0<tab>warp<tab>prt01<tab>prt_in,240,139

----

==== Could not parse file '...', line '...'. * ... ... ... ... ====
Source Syntax: ShowError("Could not parse file '%s', line '%i'.\n * %s %s %s %s\n",current_file,lines,w1,w2,w3,w4);
 Cause 
This can mean a lot of things. Please make sure that your header always looks like this:
map,x,y,d<tab>script<tab>Name<tab>sprite{,triggerx,triggery},{
The server reads this in in the following manner:
location_info<tab>script<tab>Name{#tag}{::EventLabel}<tab>other_info
If you are missing tabs, or any of these four parts, or a combination, then the mapserver will return this error.
 Solution 
Check your NPC header, and make sure it abides the rules.
 Example 
Wrong code:
prontera,200,200,4<space>My NPC<tab>48,{
Correct code:
prontera,200,200,4<tab>script<tab>My NPC<tab>48,{

----

==== File not found : ... ====
Source Syntax: ShowError ("File not found : %s\n", name);
 Cause 
You have added a NPC to the conf file, but the server cannot find the file you mentioned in there.
 Solution 
Check if the file that the mapserver reports, actually exists. If it does, make sure you typed the entry in the conf file in a case sensitive way. If the file does not exist, comment out or erase the entry in the conf file.

----

==== Invalid map '...' in line ..., file ... ====
Source Syntax: ShowError("Invalid map '%s' in line %d, file %s\n", mapname, lines, current_file);
 Cause 
This means, that the map which you specified in the header of the script, does not exist. Or at least, the server cannot find it.
 Solution 
Recheck if you spelled the name right and if the map does exist on your server (by warping to it).
 Example 
Wrong code:
pront,200,200,4<tab>script<tab>My NPC<tab>48,{
Correct code:
prontera,200,200,4<tab>script<tab>My NPC<tab>48,{

----

==== Missing right curly at file ..., line ... ====
Source Syntax: 
ShowError("Missing right curly at file %s, line %d\n",current_file, *lines); 
ShowError("Missing right curly at file %s, line %d\n", file, *lines); 
ShowError("Missing right curly at file %s, line %d\n",file, *lines);
 Cause 
The script that loaded, has more left curly brackets than right curly brackets.
 Solution 
Count and check the number and locations of the left and right curly brackets. In a single script, they should be the same amount.

----

==== no such shop npc : ... ====
Source Syntax: ShowError("no such shop npc : %d\n",id);
 Cause 
You tried to call a non-existing shop with the callshop command.
 Solution 
Make sure the shop actually exists. Also make sure that it has no sprite (-1) and no location (-) part.

----

==== npc_addeventimer: Event ... does not exists. ====
Source Syntax: ShowError("npc_addeventimer: Event %s does not exists.\n", name);
 Cause 
You tried to use a timer in combination with an Event Label. However, the event label was not found by the mapserver.
 Solution 
Make sure that the event label you are referring to exists.
 Example 
Wrong code:
<header with the npc name Tirza>
...
addtimer 60000, "Tirza::OnTimeChecker";
...
OnTimeCheck:
...
Correct code:
<header with the npc name Tirza>
...
addtimer 60000, "Tirza::OnTimeCheck";
...
OnTimeCheck:
...

----

==== npc_click: npc_id != 0 ====
Source Syntax: ShowError("npc_click: npc_id != 0\n");
 Cause 
This error seems to occur when a player uses more than one NPC at the same time. Unlike common sense, this is possible. It can happen when an event is triggered by the player (through a timer for example), and while that code is being executed, the player clicks/starts another NPC.
 Solution 
This error is hard to prevent to be honest. You will have to check in some way if there is any way for a player to be using a NPC and at the same time having an event triggered at another NPC.

----

==== npc_event: (mob_kill) event not found [...] ====
Source Syntax: ShowError("npc_event: (mob_kill) event not found [%s]\n", mobevent);
 Cause 
You created a monster spawn that has an Event Label attached to it (which will trigger when the monster dies). However, the mapserver could not find this event label in your script.
 Solution 
Verify that the monster should have an OnDeath-type label, that the Event Label exists, and that you did not make a typo in it.

----

==== npc_event: event not found [...] ====
Source Syntax: ShowError("npc_event: event not found [%s]\n", eventname);
 Cause 
Kind of the same as the error above. An event label you want to use, does not exist.
 Solution 
Verify that the Event Label exists, and that you did not make a typo in it.

----

==== npc_parse_script: label name longer than 23 chars! '...' (...) ====
Source Syntax: ShowError("npc_parse_script: label name longer than 23 chars! '%s'\n (%s)", lname, current_file);
 Cause 
You have created a label (normal or event label) which is longer than 23 characters. The mapserver cannot use labels bigger than that size.
 Solution 
Shorten your (event)label until it has 23 or less characters in it.
 Example 
Wrong code:
MyFirstLabelWhichITypedTheDayBeforeYesterday: //44 characters O_O
Correct code:
L_MyFirstLabel01: //16 characters.

----

==== npc_script_event: NULL sd. Event Type ... ====
Source Syntax: ShowError("npc_script_event: NULL sd. Event Type %d\n", type);
 Cause 
Your code triggered an event, which requires a player to be online and attached to the NPC. For some reason, the player isn't there.
 Solution 
If it is a player attached timer that causes this, and the player logged off, then there is nothing much you can do.
In any other case, make sure that your script has an attached player. (Like using addtimer instead of initnpctimer.)

----

==== npc_settimerevent_tick: Attached player not found! ====
Source Syntax: ShowError("npc_settimerevent_tick: Attached player not found!\n");
 Cause 
Your script, or in this specific case, your timer, used to have a player attached to it. The player went missing though.
This is most likely because the player logged off.
 Solution 
There is no real solution to this problem. You can make some additional checks to see if the player is still online at a certain moment, and end the script when the person logged off.

----

==== npc_timerevent: Attached player not found. ====
Source Syntax: ShowError("npc_timerevent: Attached player not found.\n");
 Cause 
This error is of the same type as above.
 Solution 
There is no real solution to this problem. You can make some additional checks to see if the player is still online at a certain moment, and end the script when the person logged off.

----

==== npc_timerevent: NPC not found?? ====
Source Syntax: ShowError("npc_timerevent: NPC not found??\n");
 Cause 
Somehow, some way, between the loading of the NPC and the current timerevent, the NPC went missing.
This is possible in a couple of different ways, but the most likely one is disabling the target NPC or unloading it.
 Solution 
Making a solution for this will be a bit time intensive. You need to make sure that the timerevent cannot be triggered when the NPC is unloaded or disabled.
A way to do this, is to make a global variable with the status of the new NPC, or using getmapxy to find if the NPC is still there.

----

==== npc_timerevent_start: Attached player not found! ====
Source Syntax: ShowError("npc_timerevent_start: Attached player not found!\n");
 Cause 
Your script, or in this specific case, your timer, used to have a player attached to it. The player went missing though.
This is most likely because the player logged off.
 Solution 
There is no real solution to this problem. You can make some additional checks to see if the player is still online at a certain moment, and end the script when the person logged off.

----

==== npc_timerevent_stop: Attached player not found! ====
Source Syntax: ShowError("npc_timerevent_stop: Attached player not found!\n");
 Cause 
Your script, or in this specific case, your timer, used to have a player attached to it. The player went missing though.
This is most likely because the player logged off.
 Solution 
There is no real solution to this problem. You can make some additional checks to see if the player is still online at a certain moment, and end the script when the person logged off.

----

==== npc_touch_areanpc : some bug ====
Source Syntax: ShowError("npc_touch_areanpc : some bug \n");
 Cause 
This bug should be impossible to produce. If you want to know the details, dive into the source code, but the short explanation is this:
* Player triggers OnTouch area.
* Mapserver iterates through all the NPCs on that map, and searches to which NPC this OnTouch area belongs.
* With this, it runs a counter from 0 to number of npcs - 1.
* If it finds one, it jumps out early.
* If it doesn't find one, i is equal to the amount of npcs - 1.
* i remains untouched then.
* When i is equal to the max amount of NPCs on the map (so not npcs - 1, but npcs), it gives this error.
Of course, this is impossible to happen, unless there are no NPCs on the map, but then the OnTouch shouldn't be triggered.
 Solution 
Report this bug to the [[developers]], because it does not have a solution script-wise. Provide them with as much data as possible/

----

==== Out of range spawn coordinates: ... (...,...), map size is (...,...) - ... ... (file ...) ====
Source Syntax: ShowError("Out of range spawn coordinates: %s (%d,%d), map size is (%d,%d) - %s %s (file %s)\n", map[mob.m].name, x, y, map[mob.m].xs-1, map[mob.m].ys-1, w1,w3, current_file);
 Cause 
You tried to spawn a monster outside of the boundaries of the map. This can either be done by negative coordinates, or coordinates bigger than the maximum of the map.
 Solution 
Recheck the actual map size, and make sure the spawn coordinates of your mob does not go beyond that. Also, always keep your spawning coordinates not negative.
 Example 
Wrong code:
monster "prt_fild08",-100,5000,"Poring",1002,5;
Correct code:
monster "prt_fild08",0,0,"Poring",1002,5;

----

==== Probably TAB is missing in file '...', line '...': * ... ... ... ... ====
Source Syntax: ShowError("Probably TAB is missing in file '%s', line '%i':\n * %s %s %s %s\n",current_file,lines,w1,w2,w3,w4);
 Cause 
The mapserver could not detect the type that your script should be. This is most likely happening because you miss a tab before the keyword. Or you are using an invalid keyword. 
The following list is a list of all possible keywords:
* duplicate
* function
* mapflag
* monster
* script
* setcell
* shop
* warp
 Solution 
Make sure you have the tabs in the right place, and that you typed the keyword correctly.

----

==== wrong map name : ... ... (file ...) ====
Source Syntax: ShowError("wrong map name : %s %s (file %s)\n", w1,w3, current_file);
 Cause 
The map where you wanted to spawn your monster on, does not exist.
 Solution 
Make sure that you typed the name of the map correctly, and that it is loaded by the mapserver. (Check this by warping to it.)

----

==== wrong monsters spawn delays : ... ... (file ...) ====
Source Syntax: ShowError("wrong monsters spawn delays : %s %s (file %s)\n", w3, w4, current_file);
 Cause 
The spawn delays you entered for your mob are too big. The maximum allowed number for both is: 268435455 (ms). 
This is equal to: 
* 3 days,
* 2 hours,
* 33 minutes,
* 55 seconds,
* and 455 milliseconds.
 Solution 
Lower the spawn delay times until they are equal to or less than 268435455.

----

==== wrong number of monsters : ... ... (file ...) ====
Source Syntax: ShowError("wrong number of monsters : %s %s (file %s)\n", w3, w4, current_file);
 Cause 
The amount of monsters you tried to spawn is incorrect. It needs to be bigger than 0 and has a limit of 1000.
 Solution 
Change the amount of monsters that you are trying to spawn, to a number equal or lower than 1000 and higher than 0.

----

 

=== Errors (script.c) ===
All errors located in script.c that have the [Error] tag are listed in this section. 
==== ...: ... broken data ! ====
Source Syntax: ShowError("%s: %s broken data !\n",mapreg_txt,buf1);
 Cause 
One of your global variables is corrupted or broken. This can be caused by a hard drive failure, physical damage to the hard-drive or memory and/or saving global variables while the server crashed suddenly. The server detects this by looking if there is any data after the variable name, before a new line is started. The global variable that is broken, is mentioned after the :. Before the : will tell you exactly where your global variables are being stored.
 Solution 
The best solution is to manually fix the broken variable. To do this, make sure that your server is completely offline. Then open the file where the global variables are located. Then search for the specific global variable. When you have found the bugged one, either erase it from the file, or give it a correct value (and if needed, array-index). If it is an important variable, you are advised to look in your most recent backup, and use that value as the new value for the broken variable. When you are done, save the file, exit it, and restart your server to see if the error is fixed.

----

==== buildin_callshop: Shop [...] not found (or NPC is not shop type) ====
Source Syntax: ShowError("buildin_callshop: Shop [%s] not found (or NPC is not shop type)\n", shopname);
 Cause 
You used the callshop command, to call a shop. However, this shop does not exist, or, it does exist, but isn't of the type Shop.
 Solution 
Verify that the shop you want to call is actually a shop, and of course, that it exists. And make sure the shop you are calling obeys the rules of shops that can be called with callshop. (More info regarding this, view the callshop example file: {{git|doc/sample/npc_dynamic_shop.txt}})

----

==== buildin_checkweight: Wrong item ID or amount. ====
Source Syntax: ShowError("buildin_checkweight: Wrong item ID or amount.\n");
 Cause 
You tried to check the weight of an invalid item or a negative amount of items.
 Solution 
Verify that the item id is 500 or higher (and of course, that it exists). Also, make sure that you are using a positive amount, and not 0 or a negative amount. When using variables to dynamically use this command, make sure that they obey these limits as well.
 Example 
Wrong code:
set @success, checkweight(400,-10);
Correct code:
set @success, checkweight(500,10);

----

==== buildin_getcharid: invalid parameter (...). ====
Source Syntax: 
Current: ShowError("buildin_getcharid: invalid parameter (%d).\n", num); 
Until Rev. 11638: ShowError("buildin_getcharid: invalid .\n"); 
Note: The error up until 11638 could not happen since it was inaccessible.
 Cause 
You have passed on an invalid parameter to the getcharid function.
 Solution 
Getcharid() can handle 4 different arguments, being:
0 - character id
1 - party id
2 - guild id
3 - account id
You tried to give it a value smaller than 0 or bigger than 3. Please check which kind of id you tried to request and adjust the number accordingly.
 Example 
Wrong code:
getcharid(-1); // I want the party ID.
getcharid(33); // I want the account ID.
Correct code:
getcharid(1);
getcharid(3);

----

==== buildin_getitem: invalid data type for argument #1 (...). ====
Source Syntax: ShowError("buildin_getitem: invalid data type for argument #1 (%d).", data->type);
 Cause 
While using the getitem command, you somehow managed to provide as the first argument, something different than a string or an integer. This command only accepts item names or item ids as a first argument.
 Solution 
Make sure that you have entered a valid number or string as the first argument of getitem. When using a variable, of course, make sure that they also obey this.
 Example 
Wrong code:
getitem "@item_name$",4;
getitem ^1234, 4;
Correct code:
getitem @item_name$, 4;
getitem 1234, 4;

----

==== buildin_getitem: Nonexistant item ... requested. ====
Source Syntax: 
ShowError("buildin_getitem: Nonexistant item %s requested.\n", name); 
ShowError("buildin_getitem: Nonexistant item %d requested.\n", nameid);
 Cause 
The item that you wanted to give with getitem does not exist.
 Solution 
Make sure that the name or the item id which you provided is an actual item. Of course, when using variables to give the item, make sure that they obey this as well.
 Example 
Wrong code:
getitem 400,5;
getitem "Appel",5;
Correct code:
getitem 500,5;
getitem "Apple",5;

----

==== buildin_getmonsterinfo: Wrong Monster ID: ... ====
Source Syntax: ShowError("buildin_getmonsterinfo: Wrong Monster ID: %i\n", mob_id);
 Cause 
The monster ID of the monster you wanted to get information on, does not exist.
 Solution 
Make sure the mob_id is the mob_id of an existing monster in one of your mob_db files.
 Example 
Wrong code:
getmonsterinfo(800,MOB_NAME);
Correct code:
getmonsterinfo(1002,MOB_NAME);

----

==== buildin_getnpctimer: Attached player not found! ====
Source Syntax: ShowError("buildin_getnpctimer: Attached player not found!\n");
 Cause 
You have attached a player to your NPCTimer. When you tried using getnpctimer on that specific timer, the player was not found anymore. This often means that he is offline.
 Solution 
First ask yourself, if it is really needed to attach a player to your NPCTimer. If this is the case, and you do not want to get this error, then you might want to consider using addtimer (a player timer) instead. If you truely want to use NPCTimers with a player attached, then before using getnpctimer, do a check if the player is still online.

----

==== buildin_rid2name: BL type unknown. ====
Source Syntax: ShowError("buildin_rid2name: BL type unknown.\n");
 Cause 
In some incredible way, you managed to provide the RID of a group that does not exist. This command can be used on the RID of the following groups only:
* Homunculus
* Monster
* NPC
* Pet
* Player
There are some other things which have RIDs, like floor items, skill traps etc. These are not allowed with this function.
 Solution 
The most likely cause for this bug is that you have provided an invalid RID, which accidentally does have a so called BL-status. (BL means BlockList, in which essential data is stored. Too complicated to explain it in here in a few words.) Make sure you are using a valid RID for this function.

----

==== buildin_rid2name: invalid RID ====
Source Syntax: ShowError("buildin_rid2name: invalid RID\n");
 Cause 
You managed to provide an invalid RID. This means, that the RID you gave to the rid2name command, does not exist and does not have a BL attached to it. Most probable is that you provided 0 as the RID, which never exists, or the RID of something that used to be, but isn't anymore. (For example, a player who logged off, or a monster which got killed.)
 Solution 
Recheck if you are providing a correct RID. If this is the case, check if it can be sensitive for certain events, like player logging off or monster being killed. If this is the case, then put some additional checks in place to prevent this bug for happening. In the case of player logging off, do a check with the isloggedin command. In the case of a monster, check if it is still alive, etc. etc.

----

==== buildin_soundeffectall: insufficient arguments for specific area broadcast. ====
Source Syntax: ShowError("buildin_soundeffectall: insufficient arguments for specific area broadcast.\n");
 Cause 
You didn't provide enough arguments for soundeffectall. Soundeffectall can be used in two ways. One way is with a predefined coverage (bc_all, bc_map etc. constants), which all have a numerical value lower than 23, even when added to each other. The other way, is providing a coverage equal to or bigger than 23, which allows you to define a custom area on a custom map, where the sound will be played. 
In this case, you provided a coverage which had a numerical value of 23 or higher, you will have to provide a mapname, and an area by giving x0, y0, x1 and y1. Unfortunately, you failed to do exactly that.
 Solution 
If it was your intend to use a custom area, then make sure you provided all of the 8 arguments. For the custom area, this is the format:
soundeffectall "effect filename",<number>,<coverage>,"mapname",<x0>,<y0>,<x1>,<y2>;
where coverage >= 23.
If you intended to use a predefined area, make sure that the numerical value of coverage is smaller than 23. To check this, open up db/const.txt, and look up the values behind the bc_ entries. Add up the numbers of the bc's that you used, to see if it stays under 23.

----

==== buildin_warp: moving player '...' to "...",...,... failed. ====
Source Syntax: ShowError("buildin_warp: moving player '%s' to \"%s\",%d,%d failed.\n", sd->status.name, str, x, y);
 Cause 
The server wasn't able to warp the specific target to its new location. There are two possible reasons for this to happen.
1 - Invalid map index.
2 - Map not in this map-server, and failed to locate alternate map-server.
 Solution 
Make sure you supplied the correct mapname to the warp function and make sure that the map is loaded and enabled in the mapserver.

----

==== can't read ... ====
Source Syntax: ShowError("can't read %s\n", line);
 Cause 
Your mapserver failed to open up the file located at: "db/const.txt".
 Solution 
This can be caused by a couple of things. Either the file isn't located there anymore (it was renamed, moved or deleted), or the file is already opened by some other application which locked it from reading. Make sure that the file exists and isn't in use by any other application, not even a text editor.

----

==== Failed to save the mapreg data! ====
Source Syntax: ShowError("Failed to save the mapreg data!\n");
 Cause 
This error is not related to bugs in the actual code of a script. It is part of the auto-save routine where the global variables are written to permanent storage (save/mapreg.txt for TXT and SQL, or the mapreg table for SQL if you defined the DMAPREGSQL flag when you compiled your source code). This error does not occur when you compiled your code in such a way that it saves your global variables to the SQL table named mapreg. However, in any other case, at certain intervals, your mapserver auto-saves the global variables to the file in save/mapreg.txt. When it occurs a problem during this, being unable to open or write to the file, then the mapserver will not save the global variables, and will return this error.
 Solution 
A long story short: You will have to verify that the file save/mapreg.txt is not locked from writing. Reasons for the file to be locked, is when it is opened by another application, like a text editor, or when the last time it was used, it wasn't closed properly. So, make sure that it is not locked anymore. (Do not close the mapserver in the meantime, or all your global variables might get lost.)

----

==== file not found: [...] ====
Source Syntax: ShowError("file not found: <nowiki>[%s]</nowiki>\n", cfgName);
 Cause 
This error occurs when your mapserver is unable to find or open conf/script_athena.conf.
 Solution 
Make sure that the file is not locked and does exist. To check if it is locked, check if it is in use by any other program, like a text-editor. If any other application has the file opened, close that application.

----

==== function not found ====
Source Syntax: ShowError("function not found\n");
 Cause 
This usually happens, when you have declared a function name, but did not implement the function.
 Solution 
Add code for every declared function.
 Example 
Wrong code:
function NonExistingFunction;
// ...
NonExistingFunction;

Correct code:
function ExistingFunction;
// ...
ExistingFunction;
// ...
function ExistingFunction {
// code
}

----

==== getnpctimer: Invalid NPC ====
Source Syntax: ShowError("getnpctimer: Invalid NPC\n");
 Cause 
You tried accessing a NPC timer of a NPC that does not exist.
 Solution 
Recheck if the NPC that you want to look up the NPC timer of, actually exists, and that you did not make any typos in the name.

----

==== initnpctimer: invalid argument type #1 (needs be int or string)). ====
Source Syntax: ShowError("initnpctimer: invalid argument type #1 (needs be int or string)).\n");
 Cause 
You tried using initnpctimer, and gave an invalid argument. This command can be used in conjunction with a string (NPC name) or an integer (starting value).
 Solution 
Recheck if you actually needed an argument to use this command, and when this is the case, if it is actually a correct argument.
 Example 
Wrong code:
initnpctimer "@NPC_Name$";
Correct code:
initnpctimer @NPC_Name$;

----

==== NPC event parameter deprecated! Please use 'NPCNAME::OnEVENT' instead of '...'. ====
Source Syntax: ShowError("NPC event parameter deprecated! Please use 'NPCNAME::OnEVENT' instead of '%s'.\n",evt);
 Cause 
In the past, when you wanted to specify a NPC event, you could simply use OnEvent. This has changed a while back though. Now you must use the format NPCNAME::OnEvent. You most likely forgot to either include the NPC name, or the On part of the event label.
 Solution 
Check if you obey the format, and that your event label really starts with On.

----

==== run_func : ...? (...(...)) ====
Source Syntax: ShowError("run_func : %s? (%d(%d))\n",str_buf+str_data[func].str,func,str_data[func].type);
 Cause 
This is an error that occurs deep inside the code, and is therefor probably rare to encounter. It basically means, that the function that the server is trying to run, is actually not a function. A possible scenario where this can occur, is a default start up, and while the server is up, you do an @loadnpc <npc>. However, this new NPC has a variable named exactly like a function, and now overwrites it.
 Solution 
Check in your scripts if the function really is a function, and if no other NPC overwrites the function, by using the same name as a variable name or something likewise.

----

==== run_func: '...' (type ...) is not function and command! ====
Source Syntax:
ShowError("run_func: '"CL_WHITE"%s"CL_RESET"' (type %d) is not function and command!\n", str_buf+str_data[func].str, str_data[func].type);
 Cause 
This is an error that occurs deep inside the code, and is therefor probably rare to encounter. It basically means, that the function that the server is trying to run, is actually not a function. A possible scenario where this can occur, is a default start up, and while the server is up, you do an @loadnpc <npc>. However, this new NPC has a variable named exactly like a function, and now overwrites it.
 Solution 
Check in your scripts if the function really is a function, and if no other NPC overwrites the function, by using the same name as a variable name or something likewise.

----

==== run_script: infinity loop ! ====
Source Syntax: ShowError("run_script: infinity loop !\n");
 Cause 
You managed to create a loop in your script, which is never ending. Because this may result into a lock up of your server, because of high CPU usage, the mapserver gives you this error.
 Solution 
Check if the infinite loop really needs to exist, and if not, make sure that there is an exit possibility.
 Example 
Wrong code:
while(1) {
set @i, @i + 1;
mes @i;
next;
}
Correct code:
while(@i < 100) {
set @i, @i + 1;
mes @i;
next;
}

----

==== script: jump_zero: not label ! ====
Source Syntax: ShowError("script: jump_zero: not label !\n");
 Cause 
The label you provided with the jump_zero command, isn't a label.
 Solution 
Recheck if the label exists, and uses the correct formatting of label names.
 Example 
Wrong code:
jumpzero(Zeny), 1337;
Correct code:
jumpzero(Zeny), L_IsBroke;

----

==== script:callfunc: function not found! [...] ====
Source Syntax: ShowError("script:callfunc: function not found! [%s]\n",str);
 Cause 
You tried to call a function with callfunc, which does not exist.
 Solution 
Recheck if you did not make any typos in the make of the function, and that the function really exists.

----

==== script:callsub: argument is not a label ====
Source Syntax: 
Current: ShowError("script:callsub: argument is not a label\n"); 
Until Rev. 10812: ShowError("script: callsub: not label !\n");
 Cause 
The label you provided for your callsub does not exist.
 Solution 
Recheck if you did not make any typos in the subroutine which you are trying to call. Make sure the label exists.

----

==== script:cleararray: illegal scope ====
Source Syntax: ShowError("script:cleararray: illegal scope\n");
 Cause 
This error indicates that you tried to use cleararray on a variable which isn't an array.
 Solution 
Recheck if the array you want to clear actually is an array, and that you typed the name of the array correctly.

----

==== script:cleararray: not a variable ====
Source Syntax: ShowError("script:cleararray: not a variable\n");
 Cause 
The variable you tried to clear with cleararray, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
cleararray .1st_array[0],0,5;
Correct code:
cleararray .First_array[0],0,5;

----

==== script:conv_num: cannot convert to number, defaulting to 0 ====
Source Syntax: ShowError("script:conv_num: cannot convert to number, defaulting to 0\n");
 Cause 
You tried converting something which isn't a string nor a valid number, to a decimal integer. The mapserver replaced what you tried to convert, to 0. The mapserver is capable of automatically converting strings, octal numbers ("o377") and hex numbers ("0xFF").
 Solution 
Check if all your (unmeant/silent) conversions are alright, and if you did not try to convert for example a binary number ("0b10011101") to a decimal integer.
 Example 
Wrong code:
set @i, 0b10011101; // 0b10011101 equals to 157 as decimal number, 0x9D as hex, or o235 as octonal.
Possible correct codes:
set @i, 0x9D;
set @i, o235;
set @i, 157;

----

==== script:conv_num: overflow detected, capping to ... ====
Source Syntax: ShowError("script:conv_num: overflow detected, capping to %ld\n", num);
 Cause 
This error occurs when you try to convert a number from a different system than decimal, and the result is bigger than what an integer can hold. This maximum is 2,147,483,647. When this happens, to prevent memory corruption or buffer overflow, the mapserver automatically caps the number at this maximum.
 Solution 
Calculate if the number which you try to convert to the decimal system, is less than the maximum allowed. Change when needed, to prevent unexpected results.
 Example 
Wrong code:
set @result, 0xFFFF * 0xFFFF; // 65535 * 65535 = 4294836225.
mes "0xFFFF * 0xFFFF = "+@result; // Displays: "0xFFFF * 0xFFFF = 2147483647"
Correct code:
set @i1, 0xFFFF; // Converts to 65535
set @i2, 0xFFFF; // Converts to 65535
set @temp_low, @i1 * (@i2%1000); // 65535 * (65535%1000) = 65535 * 535 = 35061225 (Fits.)
set @temp_high, @i1 * (@i2/1000); // 65535 * (65535/1000) = 65535 * 65 = 4259775 (Fits.)
set @result_low, @temp_low%1000; // We only need the lower part: 35061225%1000 = 225
set @result_high, @temp_high + (@temp_low/1000); // 4259775 + (35061225/1000) = 4259775 + 35061 = 4294836
mes "0xFFFF * 0xFFFF = "+@result_high+@result_low; // Displays: "0xFFFF * 0xFFFF = 4294836225"
Short Correct code:
set @result_low, (0xFFFF * (0xFFFF%1000))%1000;
set @result_high, (0xFFFF * (0xFFFF/1000)) + ((0xFFFF * (0xFFFF%1000))%1000)/1000;
mes "0xFFFF * 0xFFFF = "+@result_high+@result_low; // Displays: "0xFFFF * 0xFFFF = 4294836225"
Short Compact Correct code:
set @result_low, (0xFFFF * (0xFFFF%1000))%1000;
set @result_high, (0xFFFF * 0xFFFF + (0xFFFF%1000) * (0xFFFF%1000))/1000;
mes "0xFFFF * 0xFFFF = "+@result_high+@result_low; // Displays: "0xFFFF * 0xFFFF = 4294836225"

----

==== script:conv_num: underflow detected, capping to ... ====
Source Syntax: ShowError("script:conv_num: underflow detected, capping to %ld\n", num);
 Cause 
This error is telling you the opposite of the previous error. Due to converting numbers or calculations, your result has become lower than the lowest possible integer which your mapserver can store. As a safety precaution, it has set the value to -2,147,483,648
 Solution 
Calculate if the number which you try to convert to the decimal system, is more than the minimum allowed. Change when needed, to prevent unexpected results.

----

==== script:conv_str: cannot convert to string, defaulting to "" ====
Source Syntax: ShowError("script:conv_str: cannot convert to string, defaulting to \"\"\n");
 Cause 
You tried converting something to a string, but the mapserver was unable to convert this. Therefor, it has used the empty string "" instead.
 Solution 
Make sure you entered something that can be converted to a string. Things need to be converted when for example displaying a number in a mes-dialogue.
 Example 
Wrong code:
mes "You are the "+ 1st +"."; // 1st is not a valid string, nor a valid number.
Correct code:
mes "You are the first.";
mes "You are the "+1+"st.";

----

==== script:copyarray: illegal scope ====
Source Syntax: ShowError("script:copyarray: illegal scope\n");
 Cause 
This error indicates that you tried to use copyarray on a variable which isn't an array.
 Solution 
Recheck if the array you want to copy actually is an array, and that you typed the name of the array correctly. Of course, also check this for the target array.

----

==== script:copyarray: not a variable ====
Source Syntax: ShowError("script:copyarray: not a variable\n");
 Cause 
The variable you tried to copy with copyarray, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
copyarray @2ndarray2[0],@1starray[2],2;
Correct code:
copyarray @secondarray2[0],@firstarray[2],2;

----

==== script:copyarray: type mismatch ====
Source Syntax: ShowError("script:copyarray: type mismatch\n");
 Cause 
You tried copying an integer array to a string array, or the other way around.
 Solution 
Make sure that both either have the $-suffix, or do not have the string suffix.
 Example 
Wrong code:
copyarray @MyArray2$[0],@MyArray1[2],2;
Correct code:
copyarray @MyArray2[0],@MyArray1[2],2;

----

==== script:deletearray: illegal scope ====
Source Syntax: ShowError("script:deletearray: illegal scope\n");
 Cause 
This error indicates that you tried to use deletearray on a variable which isn't an array.
 Solution 
Recheck if the array you want to delete actually is an array, and that you typed the name of the array correctly.

----

==== script:deletearray: not a variable ====
 Cause 
The variable you tried to delete with deletearray, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
deletearray .1st_array[0],5;
Correct code:
deletearray .First_array[0],5;

----

==== script:getarg: index (idx=...) out of range (count=...) and no default value found ====
Source Syntax: ShowError("script:getarg: index (idx=%d) out of range (count=%d) and no default value found\n", idx, count);
 Cause 
You tried to use getarg() on a non-existing parameter. When calling a function or a subroutine, you can give certain parameters to it. These parameters can be requested with getarg(). Getarg can be used in combination with optional parameters though. For this, you will have to specify a default value. Here is how to do that:
set @temp, getarg(0); //Normal getarg. Will give the error if it does not exist.
set @temp, getarg(5,10); // Special getarg. If getarg(5) does not exist, it will use the value 10, and will not give this error.
 Solution 
Check if the parameter you want to obtain with getarg, always exists. (Keep in mind, getarg starts with 0, not with 1.) If it should always exist, check your callfunc and callsub lines and anything related to it. However, if the parameter is optional, then use the second format, where you can provide a default value when the parameter has not been given.
 Example 
Wrong code:
callfunc "F_MyFunction",5,10;
...
F_MyFunction:
set @MF_start, getarg(0);
set @MF_end, getarg(1);
set @MF_increase, getarg(2);
Correct code:
callfunc "F_MyFunction",5,10;
...
F_MyFunction:
set @MF_start, getarg(0);
set @MF_end, getarg(1);
set @MF_increase, getarg(2,1);

----

==== script:getarg: no callfunc or callsub! ====
Source Syntax: ShowError("script:getarg: no callfunc or callsub!\n");
 Cause 
You tried using getarg without having called the function or subroutine. In layman's terms, this means: You used goto F_MyFunction;, instead of callfunc "F_MyFunction"; Or, you used getarg in a piece of normal code, and not in a subroutine or a function.
 Solution 
First check if the getarg command is inside a real function or subroutine. If this isn't the case, remove it or make the piece of code a real function or subroutine. If the getarg is inside a real function or subroutine, and you are still getting the error, then this means that you have jumped to the function or subroutine in a weird way. Check if you used anything like goto <function or subname>; or if the code in advance of the function/sub isn't properly ended. This last thing can happen when you have some code above the sub or function, which doesn't have a close; or end; at the end.

----

==== script:getarraysize: illegal scope ====
Source Syntax: ShowError("script:getarraysize: illegal scope\n");
 Cause 
This error indicates that you tried to use getarraysize on a variable which isn't an array.
 Solution 
Recheck if the array you want to get the size of, actually is an array, and that you typed the name of the array correctly.

----

==== script:getarraysize: not a variable ====
Source Syntax: ShowError("script:getarraysize: not a variable\n");
 Cause 
The variable you tried to obtain the size of with getarraysize, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
set @temp, getarraysize(.1st_array);
Correct code:
set @temp, getarraysize(.First_array);

----

==== script:getelementofarray: illegal scope ====
Source Syntax: ShowError("script:getelementofarray: illegal scope\n");
 Cause 
This error indicates that you tried to use getelementofarray on a variable which isn't an array.
 Solution 
Recheck if the array you want to get an element of, actually is an array, and that you typed the name of the array correctly.

----

==== script:getelementofarray: not a variable ====
Source Syntax: ShowError("script:getelementofarray: not a variable\n");
 Cause 
The variable you tried to get an element of with getelementofarray, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
set @temp, getelementofarray(.1st_array,5);
Correct code:
set @temp, getelementofarray(.First_array,5);

----

==== script:getvariableofnpc: can't find npc ... ====
Source Syntax: 
Current: ShowError("script:getvariableofnpc: can't find npc %s\n", script_getstr(st,3)); 
Until Rev. 10812: ShowError("script: getvariableofnpc: can't find npc %s\n", npcname);
 Cause 
You tried to request the variable of a NPC which doesn't exist.
 Solution 
Check if the NPC you want to get the variable of, indeed exists. Of course, also check if you did not make any typos in the name of the NPC.

----

==== script:getvariableofnpc: invalid scope (not npc variable) ====
Source Syntax: 
Current: ShowError("script:getvariableofnpc: invalid scope (not npc variable)\n"); 
Until Rev. 10812: ShowError("script: getvariableofnpc: invalid scope %s (not npc variable)\n", var_name);
 Cause 
You tried requesting the value of a variable, which isn't a permanent npc variable. (Meaning, only has the prefix '.' and no @.) This command can only be used to access permanent npc variables.
 Solution 
Check if the variable you are trying to request is an actual permanent npc variable. If this is not the cause of the error, then you will have to change the other NPC and make the variable in there a permanent NPC varable. Adjust the variable name of the line getvariableofnpc accordingly of course.

----

==== script:getvariableofnpc: not a variable ====
Source Syntax: 
Current: ShowError("script:getvariableofnpc: not a variable\n"); 
Until Rev. 10812: ShowError("script: getvariableofnpc: first argument is not a variable name\n");
 Cause 
The variable you requested does not obey the rules of variable naming. That, or the slight possibility that it doesn't exist.
 Solution 
Check if you wrote the name correctly and if it obeys the rules of variable naming. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]] 
Also check if you did not make the same mistake in the NPC where you want to get the variable of.
 Example 
Wrong code:
set @temp, getvariableofnpc(.1stVar,"MyFirstNPC");
Correct code:
set @temp, getvariableofnpc(.FirstVar,"MyFirstNPC");

----

==== script:goto: not a label ====
Source Syntax: 
Current: ShowError("script:goto: not a label\n"); 
Until Rev. 10812: ShowError("script:goto: not label!\n");
 Cause 
You tried to jump to a label which doesn't exist, or isn't defined as a label.
 Solution 
Check the name, to see if it is correct. Also check if the label exists. If this both is the case, and you still get the error, then make sure that the name is different from any variable name, function name, subroutine name and command name.

----

==== script:guardian: invalid data type for argument #6 (from 1) ====
Source Syntax: 
Current: ShowError("script:guardian: invalid data type for argument #6 (from 1)\n"); 
Until Rev. 10812: ShowError("buildin_guardian: invalid data type for argument #8 (%d).", data->type);
 Cause 
Your sixth argument for the guardian command isn't of the correct type. You will have to use one of the following formats:
guardian "<map name>",<x>,<y>,"<name to show>",<mob id>;
guardian "<map name>",<x>,<y>,"<name to show>",<mob id>,"<event label>";
guardian "<map name>",<x>,<y>,"<name to show>",<mob id>,<guardian index>;
guardian "<map name>",<x>,<y>,"<name to show>",<mob id>,"<event label>",<guardian index>;
In essence, this means, that your event label and/or guardian index is not respectively a string and/or an integer. (The index needs to be an integer, the event label needs to be a string.)
 Solution 
Check if you are using the correct type for the specific argument you want to use. Make sure that the sixth argument really is a string or an integer.

----

==== script:input: not a variable ====
Source Syntax: 
Current: ShowError("script:input: not a variable\n"); 
Until Rev. 10812: ShowError("script: buildin_input: given argument is not a variable!\n");
 Cause 
You tried to use input on a variable which isn't a variable. This means that you are naming your variable wrong, or that you typed the name of a command, label, function or subroutine.
 Solution 
Verify that you are obeying the rules for variable naming, and that the name you use isn't already taken by any command, label, function or subroutine.

----

==== script:menu: argument #... (from 1) is not a label or label not found. ====
Source Syntax: 
Current: ShowError("script:menu: argument #%d (from 1) is not a label or label not found.\n", i); 
Until Rev. 10812: ShowError("script:menu: argument #%d (from 1) is not a label or label not found (op=%s).\n", i, script_op2name(data->type));
 Cause 
The target label you provided for a specific menu option, is not a correct label name, or does not exist. Please note that in a menu, the dash (-) is a valid replacement for a label.
 Solution 
Verify that the reported label does exist, and is correctly typed, and that it also obeys the rules for label naming.

----

==== script:menu: illegal number of arguments (...). ====
Source Syntax: ShowError("script:menu: illegal number of arguments (%d).\n", (script_lastdata(st) - 1));
 Cause 
The amount of arguments in your menu is not even. This makes it an invalid menu, because every menu option needs to be accompanied by a label where it should go to.
 Solution 
Check if you have put your commas between every menu option and label, and check if every menu option is accompanied by a label.
 Example 
Wrong code:
menu "Option 1",Label_1,"Option 2";
Correct code:
menu "Option 1",Label_1,"Option 2",Label_2;
or
menu "Option 1",Label_1,"Option 2",-;

----

==== script:menu: unexpected data in label argument ====
Source Syntax: ShowError("script:menu: unexpected data in label argument\n");
 Cause 
The target label you provided for a specific menu option, is not a correct label name, or does not exist. Please note that in a menu, the dash (-) is a valid replacement for a label.
 Solution 
Verify that the reported label does exist, and is correctly typed, and that it also obeys the rules for label naming.

----

==== script:op_1: argument is not a number (op=...) ====
Source Syntax: 
Current: ShowError("script:op_1: argument is not a number (op=%s)\n", script_op2name(op)); 
Until Rev. 10812: ShowError("script:op_1: invalid type of data op:%s data:%s\n", script_op2name(op), script_op2name(data->type));
 Cause 
You tried to use an arithmetic operation (mathematical operation) that uses a single value, on something else than an integer.
 Solution 
Make sure that what you provided as argument is indeed an integer.
 Example 
Wrong code:
if(!"Hello") close;
Correct code:
if(!(MyInput$ == "Hello")) close;
or
if(!MyVariable) close;

----

==== script:op_1: unexpected operator ... i1=... ====
Source Syntax: 
Current: ShowError("script:op_1: unexpected operator %s i1=%d\n", script_op2name(op), i1); 
Until Rev. 10812: ShowError("script:op_1: unexpected operator op:%s\n", script_op2name(op));
 Cause 
You tried using a single variable mathematical operator which isn't valid. For the recap, these are the possible arithmetic operators that only use a single variable:
set var, -var; // Make negative. (dash)
set var, !var; // Integer inversion. (exclamation mark)
set var, ~var; // Bitwise inversion. (tilde)
 Solution 
Make sure that you have provided the right sign for this single argument operator.

----

==== script:op_2: invalid data for operator ... ====
Source Syntax: 
Current: ShowError("script:op_2: invalid data for operator %s\n", script_op2name(op)); 
Until Rev. 10812: ShowError("script:op_2: invalid type of data op:%s left:%s right:%s\n", script_op2name(op), script_op2name(left->type), script_op2name(right->type));
 Cause 
You provided either an invalid type of argument (not string and not integer), or you used an operator which isn't ADD, and tried to use it on a string in combination with an integer.
 Solution 
If you are using ADD (+), then make sure that you did provide either strings, integers or both, and not an invalid type of data. In any other case, make sure that you provided two strings or two integers.

----

==== script:op_2num: division by zero detected op=... i1=... i2=... ====
Source Syntax: 
Current: ShowError("script:op_2num: division by zero detected op=%s i1=%d i2=%d\n", script_op2name(op), i1, i2); 
Until Rev. 10812: ShowError("script:op_2num: division by zero detected op:%s\n", script_op2name(op));
 Cause 
You used the operator MOD (%) or DIV (/) where you divided the given number by 0. This is impossible to calculate, since any division by 0 is undefined, even in the real world math.
 Solution 
Change the formula in such a way, that it isn't dividing by zero. When using a variable divide-by-number, make sure that this variable can never be 0.
 Example 
Wrong code:
set @result, my_var%0;
set @result, my_var/0;
Correct code:
set @result, my_var%5;
set @result, my_var/2;

----

==== script:op_2num: unexpected number operator ... i1=... i2=... ====
Source Syntax: 
Current: ShowError("script:op_2num: unexpected number operator %s i1=%d i2=%d\n", script_op2name(op), i1, i2); 
Until Rev. 10812: ShowError("script:op_2num: unexpected number operator op:%s\n", script_op2name(op));
 Cause 
You tried using an operator which isn't supported by the Athena Scripting Engine. The following operators for calculations with 2 integers are allowed:
* a & b // Bitwise AND (C_AND)
* a | b // Bitwise OR (C_OR)
* a ^ b // Bitwise XOR (Exclusive OR or C_XOR)
* a && b // Logical AND (C_LAND)
* a || b // Logical OR (C_LOR)
* a == b // Is equal to (C_EQ)
* a != b // Is unqual to (C_NE)
* a > b // Is greater than (C_GT)
* a >= b // Is greater than or equal to (C_GE)
* a > b // Bitshift right (C_R_SHIFT)
* a < Solution 
Check which operator of the ones above you wanted to use, and make sure you use that one.

----

==== script:op2_str: unexpected string operator ... ====
Source Syntax: 
Current: ShowError("script:op2_str: unexpected string operator %s\n", script_op2name(op)); 
Until Rev. 10812: ShowError("script:op2_str: unexpected string operator op:%s\n", script_op2name(op));
 Cause 
You tried using a string operator on two strings, which doesn't exist. The following Binary String Operators are allowed:
* a$ == b$ // Is equal to (C_EQ)
* a$ != b$ // Is not equal to (C_NE)
* a$ > b$ // Is greater than (C_GT)
* a$ >= b$ // Is greater than or equal to (C_GE)
* a$ < b$ // Is smaller than (C_LT)
* a$ <= b$ // Is smaller than or equal to (C_LE)
* a$ + b$ // Combine strings (C_ADD)
Please note: Binary in Binary String Operators does not mean bitwise, it simply means it uses two arguments.
Also note: Only the ADD operator returns a string. The other operators return an integer.
Third note, the operators with smaller than and bigger than in it, well, that isn't the actual way it works. You will have to dive into a manual on strcmp to read what it does exactly.
 Solution 
Check which operator of the ones above you wanted to use, and make sure you use that one.

----

==== script:op_3: invalid data for the ternary operator test ====
Source Syntax: 
Current: ShowError("script:op_3: invalid data for the ternary operator test\n"); 
Until Rev. 10812: ShowError("script:op_3: invalid type of data op:%s data:%s\n", script_op2name(op), script_op2name(data->type));
 Cause 
There is one single Ternary Operator which you can use in the Athena Scripting Engine. It's the compressed if-else statement. This is the format:
<condition> ? <expression when true> : <expression when false>
The condition is using no operators, Unary operators (1 argument), or any of the comparison Binary operators (2 arguments). Whatever operator you use the arguments provided for that operator, must be both a string or both an integer in the case of binary operators, or a string or an integer in any of the other operator types. When you fail to do this, for example, when comparing a string to an integer, or when you use something else besides a string or an integer, you will get this error.
 Solution 
Make sure that whatever you put in the condition part of the code, is of the valid type integer or string. Also, when using more than one argument, make sure that for each operator, they match up in type.
 Example 
Wrong code:
mes (MyString$ > MyInt) ? "You win" : "You lose";
Correct code:
mes (YourInt > MyInt) ? "You win" : "You lose";

----

==== script:query_sql: not a variable ====
Source Syntax: ShowError("script:query_sql: not a variable\n");
 Cause 
You tried to pass a variable for storing results for your SQL query. The variable isn't a variable though.
 Solution 
Recheck if the variables at the end of your query_sql statement are indeed variables. Check their spelling and if they aren't commands or labels or something likewise.
 Example 
Wrong code:
query_sql("SELECT `name` FROM `char` WHERE `char_id` = '"+.@char_id+"'", .@$result);
Correct code:
query_sql("SELECT `name` FROM `char` WHERE `char_id` = '"+.@char_id+"'", .@result$);

----

==== script:run_script_main: unexpected stack position stack.sp(...) != default(...) ====
Source Syntax: ShowError("script:run_script_main: unexpected stack position stack.sp(%d) != default(%d)\n", stack->sp, stack->defsp);
 Cause 
This error means that your stack got corrupted. This is not something you can do anything about.
 Solution 
First, restart your server, and see if the error happens again. If it does occur again, then you should contact a [[Staff|developer]], because it is likely that someone made an error in the script engine then.

----

==== script:set: no player attached for player variable '...' ====
Source Syntax: ShowError("script:set: no player attached for player variable '%s'\n", name);
 Cause 
Server variables are NPC variables (.) and global variables ($). In your script you used one of the non-server variables, which need a player to be attached to the script. However, there is no player attached to the script.
 Solution 
Recheck if the variable is supposed to be a non-server variable. If it is supposed to be a non-server variable, make sure that there is a player attached to the script.

----

==== script:set: not a variable ====
Source Syntax: 
Current: ShowError("script:set: not a variable\n"); 
Until Rev. 10812: ShowError("script: buildin_set: not name\n");
 Cause 
You tried to use set on something which isn't a variable. That, or you failed to provide any variable, or a variable who's name is already used by a label, function, sub-function or script command.
 Solution 
Recheck if you provided a variable to be set, as well as the variable having the correct naming requirements.
 Example 
Wrong code:
set ,5;
Correct code:
set @temp, 5;

----

==== script:setarray: illegal scope ====
Source Syntax: ShowError("script:setarray: illegal scope\n");
 Cause 
This error indicates that you tried to use setarray on a variable which isn't an array.
 Solution 
Recheck if the array you want to set actually is an array, and that you typed the name of the array correctly.

----

==== script:setarray: not a variable ====
Source Syntax: ShowError("script:setarray: not a variable\n");
 Cause 
The variable you tried to set with setarray, isn't a variable, or it isn't a legal variable name.
 Solution 
Confirm that the variable does exist, and that it obeys the official rules for names of a variable. For reference, check this link: [[Variables#Other_Important_Info Naming Variables]]
 Example 
Wrong code:
setarray .1st_array[1],3,6,5;
Correct code:
setarray .First_array[1],3,6,5;

----

==== script:setd: no player attached for player variable '...' ====
Source Syntax: ShowError("script:setd: no player attached for player variable '%s'\n", buffer);
 Cause 
Server variables are NPC variables (.) and global variables ($). In your script you used one of the non-server variables, which need a player to be attached to the script. However, there is no player attached to the script.
 Solution 
Recheck if the variable is supposed to be a non-server variable. If it is supposed to be a non-server variable, make sure that there is a player attached to the script.

----

==== script:setmobdata: unknown data identifier ... ====
Source Syntax: ShowError("script:setmobdata: unknown data identifier %d\n", type);
 Cause 
You wanted to change a part of a mob's data, however, that part does not exist. You can set up to 27 different parameters when it comes to mob data, of which the first 21 are explained here: [http://djyhnzo.freepgs.com/index.php?c=setmobdata setmobdata]
 Solution 
Make sure that whatever you are trying to set, is something that exists. You should only use this line when you know what you are doing, so if you are unsure on what is wrong, simply erase the line.

----

==== script:setnpcdisplay: expected a string or number ====
Source Syntax: ShowError("script:setnpcdisplay: expected a string or number\n");
 Cause 
You did not provide a correct new name or view id for the NPC.
 Solution 
The format of setnpcdisplay allows you to change the name, the view ID or both of the NPC. If you change the name, provide the name before the view ID, if you are changing that as well. Also, recheck that the new view ID is a number and the new name is a string, if these are being altered.
 Example 
Wrong code:
setnpcdisplay(strnpcinfo(0), 113, "Announcer");
Correct code:
setnpcdisplay(strnpcinfo(0), "Announcer", 113);
----

==== script:unitattack: unsupported source unit type ... ====
Source Syntax: ShowError("script:unitattack: unsupported source unit type %d\n", unit_bl->type);
 Cause 
You can only use the unitattack command on players, monsters or pets. You tried using it on a different type of unit.
 Solution 
Recheck the unit id which you provided, if it is the UID of a player, monster or pet. These three types have a terminal UID, which gets erased when the monster dies, the pet walks away, or when the player logs out. To make sure that your error isn't caused by this as well, put some safeguards in place, like checking if the player is still online.

----

==== script:warpportal: npc is needed ====
Source Syntax: 
Current: ShowError("script:warpportal: npc is needed\n"); 
Until Rev. 10812: ShowError("script:warpportal: npc is needed");
 Cause 
Warpportal is a command that can be used from inside a script to spawn a warp portal. This works different from the script type warp portal, which is permanent. One of the requirements for warpportal is that it needs to be executed from within a normal NPC. In your case, this is exactly what went wrong.
 Solution 
Make sure that your warpportal line is within a normal NPC, and not defined as a stand-alone warpportal, nor that it is inside a function, subroutine, itemscript or monsterscript.

----

==== script_rid2sd: fatal error ! player not attached! ====
Source Syntax: ShowError("script_rid2sd: fatal error ! player not attached!\n");
 Cause 
One of the commands you were using in your script, requires the assistance of a player. A wide variety of commands as well as certain variables, require the player to be attached to the script. This is what went wrong in your script. For example, you tried to access or set a player variable with no player attached to the script, or a command like addtimer which requires the attachment of a player.
 Solution 
In the case of a variable, make sure that either a player is attached, or in the cases that this is impossible, that you are using a NPC or global variable. 
In the case of commands, also make sure that the player is attached. 
If by default, a player should be attached, then the most likely option is that the player logged off. So, make some safeguards against this, by using for example the isloggedin command, to check if the player is still logged in.

----

==== script_save_mapreg: Unable to lock-open file [...] ====
Source Syntax: ShowError("script_save_mapreg: Unable to lock-open file [%s]\n",mapreg_txt);
 Cause 
Your mapserver tried to save the global variables to its file (save/mapreg.txt). Unfortunately, it was unable to do this, because the file is already opened by another program in the lock-mode.
 Solution 
Recheck if no other program (like a text-editor) is using the file, and make sure that when no other program is using it, that the file has been closed properly.

----

==== startnpctimer: invalid argument type #1 (needs be int or string)). ====
Source Syntax: ShowError("startnpctimer: invalid argument type #1 (needs be int or string)).\n");
 Cause 
Startnpctimer has several formats. The different kinds of formats allow you to either attach it to another NPC, or to let it start at a certain value. The value or the NPC name you provided is incorrect, the mapserver does not recognize it as a string or integer.
 Solution 
Recheck if you are giving the correct argument to the command, make sure it is an integer or a string. In the case of using a variable, make sure that the variable contains correct data.

----

==== stopnpctimer: invalid argument type #1 (needs be int or string)). ====
Source Syntax: ShowError("stopnpctimer: invalid argument type #1 (needs be int or string)).\n");
 Cause 
Stopnpctimer has several formats. The different kinds of formats allow you to either attach it to another NPC, or to let it start at a certain value. The value or the NPC name you provided is incorrect, the mapserver does not recognize it as a string or integer.
 Solution 
Recheck if you are giving the correct argument to the command, make sure it is an integer or a string. In the case of using a variable, make sure that the variable contains correct data.

----

==== unget_com can back only 1 data ====
Source Syntax: ShowError("unget_com can back only 1 data\n");
 Cause 
As most code that is inside the scripting engine's main part, this error seems unlikely to be caused by your scripts. What exactly causes it to trigger is unknown to me.
 Solution 
Your best chance is to get support in the Scripting Support Forum, or to contact one of the [[developers]].

----

==== unknown command : ... @ ... ====
Source Syntax: ShowError("unknown command : %d @ %d\n",c,pos);
 Cause 
This error indicates a source problem. It means, that the script engine generated a byte instruction out of some part of your script, which is undefined in the runtime part of the engine.
 Solution 
Report it to core developers, together with your script, to get the source issue fixed.

----

==== wrong item ID : countitem(...) ====
Source Syntax: ShowError("wrong item ID : countitem(%i)\n", nameid);
 Cause 
You provided an invalid item id for countitem. This error is triggered when you provide an item id lower than 500.
 Solution 
Check if you didn't enter a faulty item id, and correct it when needed.
 Example 
Wrong code:
if(countitem(400) < 1) close;
Correct code:
if(countitem(500) < 1) close;

----

==== wrong item ID : countitem2(...) ====
Source Syntax: ShowError("wrong item ID : countitem2(%i)\n", nameid);
 Cause 
You provided an invalid item id for countitem. This error is triggered when you provide an item id lower than 500.
 Solution 
Check if you didn't enter a faulty item id, and correct it when needed.
 Example 
Wrong code:
if(countitem2(400,1,0,0,0,0,0,0) < 1) close;
Correct code:
if(countitem2(500,1,0,0,0,0,0,0) < 1) close;

----

==== wrong item ID : equipitem(...) ====
Source Syntax: ShowError("wrong item ID : equipitem(%i)\n",nameid);
 Cause 
You tried to equip an item with equipitem, which doesn't exist.
 Solution 
Check if you entered the correct item id, and also check if it exists in item_db.conf or item_db2.conf.

----

 

=== Fatal Errors ===
All fatal errors are listed in this section. 
==== npc_addeventtimer: out of memory ! ====
Source Syntax: ShowFatalError("npc_addeventtimer: out of memory !\n");
 Cause 
Your script tried to start another eventtimer. Unfortunately your server's computer has run out of memory, so it cannot create this new timer.
 Solution 
Try freeing up more memory. However, if the problem still occurs, then the real cause might be in faulty scripting. Check the script if it loops a lot with timers located inside the loops. Try to minimize the amount of loops or even better, avoid them when using timer script commands.

----

==== npc_event_export: label name error ! ====
Source Syntax: ShowFatalError("npc_event_export: label name error !\n");
 Cause 
This error occurs when you have a npc event label with an invalid size of the name. NPC event labels always start with On.
The size of the name of the event label is each character after On and before the ':'. When this amount of characters is 0 (in the case of "On:") or bigger than the constant NameLength, which is 23 or 24 (in the case of "OnAbcdefghijklmnopqrstuvwxyz:"), your mapserver will be unable to create the npc event label, and therefor crash.
 Solution 
Rename the event labels that are bugged. Make sure that they actually have a name between the On and ":" part, and that this name does not exceed 23 characters.

----

==== npc_event_export: out of memory ! ====
Source Syntax: ShowFatalError("npc_event_export: out of memory !\n");
 Cause 
This error occurs when the server does not have enough free memory to allocate a new npc event label. (These are the labels that start with On.)
 Solution 
Try to free up more memory, or add new memory to your system. If this does not solve the problem, then you will have to consider to use less npc event labels. This can be accomplished by either erasing NPCs that contain them, or by optimizing your npc event labels.

----

==== npc_timerevent_import: out of memory ! ====
Source Syntax: ShowFatalError("npc_timerevent_import: out of memory !\n");
 Cause 
This error occurs when the server does not have enough free memory left to allocate space for an OnTimer: label.
 Solution 
Free up more memory, or remove OnTimer labels that you do not use.
 

----

 

=== Parsing Errors ===
All parsing errors are listed in this section. 
==== expect ';' or '{' at function syntax ====
Source Syntax: disp_error_message("expect ';' or '{' at function syntax",p);
 Cause 
An in-script function was used or declared in an invalid manner.
 Solution 
You tried to write or use an in-script function. The normal format for this is one of the following two:
function test; // Calls upon in-script function test.
function test { // Declaration of a function including needed code.
// Function code goes here.
}
In your case, the script parser encountered something else than the allowed { or ; after the function's name. Recheck your in-script function, and make sure it either has a ; or a { at the end of the line.

----

==== need '(' ====
Source Syntax: disp_error_message("need '('",p);
 Cause 
In your script, there is a function that you are trying to call. This function requires it's arguments to be between round brackets. Your script is lacking at least the left one ('('), and most likely both.
 Solution 
Search inside your script for the function call displayed by the error. Fix it by making sure there are parentheses around the arguments.
 Example 
Wrong code:
...
set .var, SF_DummyFunction 5, 7;
...
Correct code is:
...
set .var, SF_DummyFunction(5, 7);
...

----

==== not found '{' ====
Source Syntax: disp_error_message("not found '{'",p);
 Cause 
The header of your script or function is missing a '{'. This left curly bracket specifies the start of the body of the script, and must be on the same line as your header.
 Solution 
If you forgot to place a { at all, then place it at the end of the header line. If you placed the opening curly bracket at the next line, then move it until it is at the same line as the header.
 Example 
Wrong code:
prontera,200,200,4<tab>script<tab>Dummy<tab>46,
{
mes "hi";
close;
}
It should be:
prontera,200,200,4<tab>script<tab>Dummy<tab>46,{
mes "hi";
close;
}

----

==== parse_callfunc: callsub has no arguments, please review it's definition ====
Source Syntax: disp_error_message("parse_callfunc: callsub has no arguments, please review it's definition",p);
 Cause 
In the words of one of the devs: "Someone fucked up the script engine."
This means, that if you get this error, which is highly unlikely, that you probably did nothing wrong.
 Solution 
When you encounter this problem though, please report it to the core developers. Tell them what you did that caused it (i.e. show the script, tell them what you did with the script, just loading or using it or whatever, and of course, when the bug happens).

----

==== parse_callfunc: DEBUG last curly is not an argument list ====
Source Syntax: disp_error_message("parse_callfunc: DEBUG last curly is not an argument list",p);
 Cause 
The parsing of function parameter lists is bugged in the script engine. (In essence, you should never get this error.)
 Solution 
There is no known solution to this. What is advised by the Developers themselves is to report this to the devs. When doing this, also provide your script that is causing this error.

----

==== parse_callfunc: expected ')' to close argument list ====
Source Syntax: disp_error_message("parse_callfunc: expected ')' to close argument list",p);
 Cause 
This error occurs when you are calling a function or something likewise, which uses round brackets around the arguments, but you forgot to enter the closing rounding bracket.
 Solution 
Simply go to the specified bugged function call, and count if the amount of left round brackets match the amount of right round brackets. Change them when needed.
 Example 
Wrong usage:
...
set @temp, SF_DummyFunction(5, 7;
...
As you can see, 1 (, but no ). Correct line would be:
set @temp, SF_DummyFunction(5, 7);

----

==== parse_callfunc: not enough arguments, expected ',' ====
Source Syntax: disp_error_message2("parse_callfunc: not enough arguments, expected ','", p, script_config.warn_func_mismatch_paramnum);
 Cause 
When calling upon a predefined function, you need to meet the exact amount of arguments. In this case, you did not have enough arguments.
 Solution 
Make sure the bugged function has the right amount of arguments. Look at it's template, and see if the amount of arguments match.

----

==== parse_curly_close: unexpected string ====
Source Syntax: disp_error_message("parse_curly_close: unexpected string",p);
 Cause 
We are not 100% sure, but this might happen if you place a normal string after you put the closing curly of the NPC. Again, not 100% sure, but the developers say that this is one of those rare cases that shouldn't occur. However, when it does occur, please use the scripting support forum if you cannot figure out how to fix it.
Another possibility as a cause, is that you have too many right curly brackets ('}').
 Solution 
The probable solution is to erase the string or right curly bracket that the mapserver shows you. Or, recount your left and right curly brackets, and make sure they are all in the right spot.

----

==== parse_expr: unexpected char ====
Source Syntax: disp_error_message("parse_expr: unexpected char",p);
 Cause 
This error occurs when the server detects a character in your script that shouldn't be there. This can happen when you have misplaced one of the following characters: ')', ';', ':', '[', ']' or '}'.
 Solution 
Either move or remove the wrong placed character, or fix the text/arguments that are forgotten in front of these characters.
 Example 
Example of what might cause this error:
...
set .@[0], 5;
...
What the line can be:
set .@temp[0], 5;

----

==== parse_line: expect command, missing function name or calling undeclared function ====
Source Syntax: disp_error_message("parse_line: expect command, missing function name or calling undeclared function",p);
 Cause 
This is probably happening when you are trying to call to a function that simply does not exist.
 Solution 
Make sure the function you are trying to reach, actually exists. If it exists, make sure you did not make any typos. And if it didn't exist, create the function, or remove the line.

----

==== parse_line: need ')' ====
Source Syntax: disp_error_message("parse_line: need ')'",p);
 Cause 
This error is most commonly seen when your if, for or while statement lacks a closing round bracket.
 Solution 
Check your for, if or while statement, and make sure the amount of opening round brackets match the amount of closing round brackets. Also, with if and while, make sure that the entire condition that you want to check, is closed in by at least one ( and one ). Extra brackets are not a sin, too few are.
 Example 
Wrong code:
if(i > 10 end;
This should be:
if(i > 10) end;

----

==== parse_line: need ';' ====
Source Syntax: disp_error_message("parse_line: need ';'",p);
 Cause 
One of the most common errors. There are actually two versions of this one. One that only occurs within the first line of a for-statement, the other one being, simply forgetting a ';' at the end of the line.
 Solution 
In case of a for-statement going bad, please make sure it upholds this format: for(<initiation>;<condition>;<iteration>).
In case of anything else, then the error is 99 out of 100 times, not on the line the script parser tells you. It is often a forgotten ; in the line above. Make sure this is the case, and add it there.
 Example 
Wrong code:
set @temp, 5
close;
Correct code should be:
set @temp, 5;
close;

----

==== parse_simpleexpr: unexpected character ====
Source Syntax: disp_error_message("parse_simpleexpr: unexpected character",p);
 Cause 
The script engine was expecting a word (the name of a variable, label, function or something like that) and found something else.
 Solution 
Make sure that you have typed the right word, and did not use invalid characters.
 Example 
Probably example of wrong code:
mes "2 + 2 equals "+ ( + 2) +".";
mes "I know math!";
Correct code:
mes "2 + 2 equals "+ (2 + 2) +".";
mes "I know math!";

----

==== parse_simpleexpr: unexpected eof @ string ====
Source Syntax: disp_error_message("parse_simpleexpr: unexpected eof @ string",p);
 Cause 
Your string is not properly closed. In fact, there is nothing behind the string. This can be caused when you are editing your file, and save your progress while you were typing a string, and then ran this script.
 Solution 
Close the string like it should be closed (with a "), or remove the line all together if it shouldn't be there. Also close up the script all together, because eof means End of File. So even if you just fix this bug, your NPC is still bugged.
 Example 
Wrong code:
...
mes "Bye
<file ends>
Right code:
...
mes "Bye";
close;
}

----

==== parse_simpleexpr: unexpected expr end ====
Source Syntax: disp_error_message("parse_simpleexpr: unexpected expr end",p);
 Cause 
This can happen in a variety of cases. They call come down to not closing a string, command or condition correct.
 Solution 
Make sure that your string or command is properly closed. If this does not apply, make sure that your condition is set up correctly.
 Example 
Wrong code:
set @total, 5 + ;
Correct code:
set @total, 5;
or
set @total, 5 + 1;

----

==== parse_simpleexpr: unexpected newline @ string ====
Source Syntax: disp_error_message("parse_simpleexpr: unexpected newline @ string",p);
 Cause 
You either forgot to close your string, or pressed return, and typed the rest on a new line. Unfortunately, a string needs to be closed on the same line.
 Solution 
Properly close the string, or divide it in multiple parts using: "string part 1" + "string part 2" etc.
 Example 
Wrong code:
mes "Hello there.
My name is Nienke.";
Corrected code:
mes "Hello there. My name is Nienke.";
or
mes "Hello there." +
"My name is Nienke.";

----

==== parse_simpleexpr: unmatch ')' ====
Source Syntax: disp_error_message("parse_simpleexpr: unmatch ')'",p);
 Cause 
The amount of opening round brackets does not match the amount of closing round brackets. Again, this can happen in a wide variety of cases.
 Solution 
Count the amount of brackets that you have. Make sure each opening bracket has a closing bracket.
 Example 
Wrong code:
set @total, 5 * (6 + (5 * 5);
Correct code:
set @total, 5 * (6 + (5 * 5));
or
set @total, 5 * (6 + 5 * 5);

----

==== parse_simpleexpr: unmatch ']' ====
Source Syntax: disp_error_message("parse_simpleexpr: unmatch ']'",p);
 Cause 
This error occurs when you forgot to close off the element part of an array.
 Solution 
To fix this, you need to ask yourself first: Did I want an array at this point? If not, remove the opening square bracket. If you did, make sure the amount of opening square brackets match the amount of closing square brackets.
 Example 
Wrong code:
set @temp[0, 5;
Correct code:
set @temp[0], 5;

----

==== parse_subexpr: need ':' ====
Source Syntax: disp_error_message("parse_subexpr: need ':'", p-1);
 Cause 
This errors occurs, when you use a compact if statement, and forgot the : to separate the true and false statements. A compact if statement looks like this:
<condition> ? <expression when true> : <expression when false>
 Solution 
Confirm you wanted to use the compact if statement. If this is the case, find where you forgot to add the ':'. If it isn't the case, make sure that the question mark triggering this statement is not there, or erase the entire line.
 Example 
Wrong code:
mes "You are part of team " + ( (a == 1) ? "Blue""Red" );
Correct code:
mes "You are part of team " + ( (a == 1) ? "Blue" : "Red" );

----

==== parse_syntax: 'case' label not integer ====
Source Syntax: disp_error_message("parse_syntax: 'case' label not integer",p);
 Cause 
The format for a case label is: "case #:", where # must be an integer value. If this is not the case, the mapserver will throw this error at you. The Athena Scripting Language does '''NOT''' support "case <string>:" and possibly not even "case <character>:".
 Solution 
Change whatever you had between the case and ':' to a real integer value instead.
 Example 
Wrong code:
switch(@a$) {
case "Hi":
Correct code:
switch(@a) {
case 1:

----

==== parse_syntax: dup 'case' ====
Source Syntax: disp_error_message("parse_syntax: dup 'case'",p);
 Cause 
Inside the same switch, one 'case label' exists more than one time. This error is like the normal duplicate label error. Two of the same named labels exists in the same piece of code, in this case, the switch.
 Solution 
Remove the duplicated case label, and when needed, merge their both codes.
 Example 
Wrong code:
case 1:
set @a, 5;
break;
case 1:
set @b, 5;
break;
Correct code:
case 1:
set @a, 5;
set @b, 5;
break;

----

==== parse_syntax: dup 'default' ====
Source Syntax: disp_error_message("parse_syntax: dup 'default'",p);
 Cause 
Same cause as the error right above this one. There is a duplicated label named default within the same switch.
 Solution 
Remove the second default label, and when needed, merge the code.
 Example 
Wrong code:
default:
set @a, 5;
break;
default:
set @b, 5;
break;
Correct code:
default:
set @a, 5;
set @b, 5;
break;

----

==== parse_syntax: expect ':' ====
Source Syntax: disp_error_message("parse_syntax: expect ':'",p);
 Cause 
The case label, inside the switch command, is missing the ':'. This is exactly the same as with normal variables.
 Solution 
Simply add the colon after the case label. Or, when the case label is not needed, simply remove it.
 Example 
Wrong code:
case 1
set @a, 5;
break;
Correct code:
case 1:
set @a, 5;
break;

----

==== parse_syntax: expect space ' ' ====
Source Syntax: disp_error_message("parse_syntax: expect space ' '",p);
 Cause 
Another case label error. The format for a case label is: "case #:", where # is an integer value. The format dictates that there needs to be a space between the word "case" and the integer value. This space is missing in your script.
 Solution 
Add the space between "case" and the number.
 Example 
Wrong code:
case1:
set @a, 5;
break;
Correct code:
case 1:
set @a, 5;
break;

----

==== parse_syntax: need '(' ====
Source Syntax: disp_error_message("parse_syntax: need '('",p);
 Cause 
Your for-line is not following the default format. The format is: for(<initiation>;<condition>;<iteration);. You are missing the '('.
 Solution 
Remove the for-statement all together, if it is not supposed to be there, or add the missing left round bracket.
 Example 
Wrong code:
for set @a,5; @a < 10; set @a, @a + 1) {
Correct code:
for(set @a,5; @a < 10; set @a, @a + 1) {

----

==== parse_syntax: need ':' ====
Source Syntax: disp_error_message("parse_syntax: need ':'",p);
 Cause 
Missing the ':' behind the switch label named "default".
 Solution 
Add the missing colon directly after default. (Or remove the default label all together.)
 Example 
Wrong code:
default
break;
Correct code:
default:
break;

----

==== parse_syntax: need ';' ====
Source Syntax: disp_error_message("parse_syntax: need ';'",p);
 Cause 
One of the most common errors. There are actually two versions of this one. One that only occurs within the first line of a for-statement, the other one being, simply forgetting a ';' at the end of the line.
 Solution 
In case of a for-statement going bad, please make sure it upholds this format: for(<initiation>;<condition>;<iteration>).
In case of anything else, then the error is 99 out of 100 times, not on the line the script parser tells you. It is often a forgotten ; in the line above. Make sure this is the case, and add it there.
 Example 
Wrong code:
set @temp, 5
close;
Correct code should be:
set @temp, 5;
close;

----

==== parse_syntax: need 'while' ====
Source Syntax: disp_error_message("parse_syntax: need 'while'",p);
 Cause 
Your Do-command is missing the while-command after the closing '}'. Format for this command is: do { <statements> } while (<condition);
 Solution 
Add the missing while-command and when needed, the condition.
 Example 
Wrong code:
do {
set @a, @a + 1;
}
Correct code:
do {
set @a, @a + 1;
} while (@a < 100);

----

==== parse_syntax: unexpected 'continue' ====
Source Syntax: disp_error_message("parse_syntax: unexpected 'continue'",p);
 Cause 
Continue can be only used within looping commands, like for, do .. while and while. It simply means, ignore the rest, start a new round. Your continue-command however, is placed outside one of these looping commands.
 Solution 
Move continue; to inside the looping command you wanted it to use for. If this is not what you wanted, then erase the line.
 Example 
Wrong code:
for(set @i, 0; @i < 10; set @i, @i + 1) {
if(@My_Numbers[@i] != $Winning_Numbers[@i]) {
set @i, @i + 1;
set Points, Points - 1;
}
set Points, Points + 1;
}
continue;
Correct code:
for(set @i, 0; @i < 10; set @i, @i + 1) {
if(@My_Numbers[@i] != $Winning_Numbers[@i]) continue;
set Points, Points + 1;
}

----

==== parse_syntax: unexpected 'default' ====
Source Syntax: disp_error_message("parse_syntax: unexpected 'default'",p);
 Cause 
This happens when you place the "default:" label outside of a switch.
 Solution 
Erase the default label or move it inside the switch you wanted to use it for.
 Example 
The example in the error right above this one can be applied for this one as well.

----

==== parse_syntax: unexpected 'break' ====
Source Syntax: disp_error_message("parse_syntax: unexpected 'break'",p);
 Cause 
The break; command is only supposed to be used in looping functions or functions that use curly brackets (like if or switch). It will make you jump outside of the statement. In this case, this break; is not located in such a function.
 Solution 
Remove the break; or replace it by an end; if you want to end the script.
 Example 
Wrong code:
-<tab>script<tab>Dummy<tab>-1,{
OnInit:
set $Blah, 14;
break;
....
Correct code:
-<tab>script<tab>Dummy<tab>-1,{
OnInit:
set $Blah, 14;
end;
....

----

==== parse_syntax: unexpected 'case' ====
Source Syntax: disp_error_message("parse_syntax: unexpected 'case' ",p);
 Cause 
This happens when you place the "case #:" label outside of a switch.
 Solution 
Erase the case label or move it inside the switch you wanted to use it for.
 Example 
The example in the third error above this one can be applied for this one as well.

----

==== parse_syntax:function: function name is missing or invalid ====
Source Syntax: disp_error_message("parse_syntax:function: function name is missing or invalid", p);
 Cause 
The name you are using in the function line is not valid, or is there not at all.
 Solution 
Use a correct name for the function. The same rules abide as for labels and variable names.
 Example 
Wrong code:
function 1stFunction;
function;
Correct code for both:
function SF_Function01;

----

==== script:add_word: invalid word. A word consists of underscores and/or alphanumeric characters, and valid variable prefixes/postfixes. ====
Source Syntax: disp_error_message("script:add_word: invalid word. A word consists of underscores and/or alphanumeric characters, and valid variable prefixes/postfixes.", p);
 Cause 
This happens when a word does not meet the standard format. Like the error says: A word consists of underscores and/or alphanumeric characters, and valid variable prefixes/postfixes.
 Solution 
Change the name to meet the requirements.

----

==== set_label: dup label ====
Source Syntax: disp_error_message("set_label: dup label ",script_pos);
 Cause 
This label already exists. It is not allowed to have the same label more than once, within the same NPC, itemscript, monsterscript, function or sub.
 Solution 
Remove or rename one of the two labels to fix this. Also change the code depending on the label that is going to be changed or removed.
 Example 
Wrong code:
...
goto Hello;
...
Hello:
mes "Hello";
close;
Hello:
mes "Hi";
close;
Correct code:
...
goto Hello;
...
Hello:
mes "Hello";
close;

----

==== set_label: invalid label name ====
Source Syntax: disp_error_message("set_label: invalid label name",script_pos);
 Cause 
You are trying to use the name of a reserved variable or constant as a label name. This is not allowed.
 Solution 
Change the label name into something else.
 Example 
Wrong code:
goto BaseLevel;
...
BaseLevel:
Correct code:
goto L_BaseLevel;
...
L_BaseLevel:

----

==== unexpected end of script ====
Source Syntax: disp_error_message("unexpected end of script",p);
 Cause 
The script parser encountered an unexpected end of the script without having a matching amount of paired curly brackets and without encountering the end tag.
 Solution 
Recheck your script and make sure that you have the closing curly bracket at the end of your script. Also count your curly brackets. Make sure that there is a matching } for each { that you have.

----

=== Obsolete Errors ===
This section will cover all errors that used to exist in the past, but are not represented anymore in today's revision. (So, there is not even a replacement, they were completely erased.)
==== Up to Revision 11859 ====
----
===== getequipid: sd == NULL =====
Source Syntax: ShowError("getequipid: sd == NULL\n");
 Cause 
You tried to use getequipid, without having a player attached to the script.
 Solution 
Make sure that the command is only used when a player is attached to the script. If needed, when using timed events for example, check whether the player is still online or not.

----
===== script:get_val error, cannot access player variable '...', defaulting to "" =====
Source Syntax: ShowError("script:get_val: cannot access player variable '%s', defaulting to \"\"\n", name); 
 Cause 
You tried accessing a player type variable (Temporal or permanent player variable, account variable or global account variable) without having a player attached to the script. Because this variable was of the type String, the mapserver converted it to an empty string "".
 Solution 
Make sure that you actually have a player attached to your script when trying to access player-type variables.

----

===== script:get_val error, cannot access player variable '...', defaulting to 0 =====
Source Syntax: ShowError("script:get_val: cannot access player variable '%s', defaulting to 0\n", name); 
 Cause 
You tried accessing a player type variable (Temporal or permanent player variable, account variable or global account variable) without having a player attached to the script. Because this variable was of the type Integer, the mapserver converted it to 0.
 Solution 
Make sure that you actually have a player attached to your script when trying to access player-type variables.

----

==== Up to Revision 11778 ====
----
===== buildin_fakenpcname: Invalid look value ... =====
Source Syntax: ShowError("buildin_fakenpcname: Invalid look value %d\n",look);
 Cause 
With the fakenpcname command, you can not only change the name into a new name. You can also adjust the look. This is what you attempted to do, but failed, because you provided an invalid look value.
 Solution 
Change the look value (third argument) in such a way that it fits in the boundaries. The minimum value is -32768 and the maximum value is 32767.
 Example 
Wrong code:
fakenpcname "My NPC","Your NPC",600000;
Correct code:
fakenpcname "My NPC","Your NPC",32767;

----

==== Up to Revision 11501 ====
----
===== script:skip_space: end of file while parsing block comment. expected */ =====
Source Syntax: disp_error_message("script:skip_space: end of file while parsing block comment. expected "CL_BOLD"*/"CL_NORM, p);
 Cause 
A comment block was opened but never closed. The server encountered the end of the file before finding the closing tag for the comment block. A comment block starts with /* and everything after it, including on new lines, will be regarded as comments, until it encounters */.
 Solution 
Add the */ at the end of your comment block, to fix this error.
 Example 
Wrong code:
/* Tralalalala
lalalalala
Oops, end of the file.
Correct code:
/* Tralalalala
lalalalala
Oops, end of the file. */

----

==== Up to Revision 10842 ====
----
===== get_val error, cannot access player variable '...' =====
Source Syntax: ShowError("get_val error, cannot access player variable '%s'\n", name);
 Cause 
You tried accessing a player type variable (Temporal or permanent player variable, account variable or global account variable) without having a player attached to the script.
 Solution 
Make sure that you actually have a player attached to your script when trying to access player-type variables.

----

===== script:menu: argument #... (from 1) is not a string or compatible. =====
Source Syntax: 
Until Rev. 10842: ShowError("script:menu: argument #%d (from 1) is not a string or compatible.\n", (i - 1)); 
Until Rev. 10812: ShowError("script:menu: argument #%d (from 1) is not a string or compatible (op=%s).\n", (i - 1), script_op2name(data->type));
 Cause 
This error should occur when the given argument is not a string nor an integer. (Will be fixed in revision ...)
 Solution 
Check if what you provided as a menu option is a real string or an integer. Correct it if needed.

----

==== Up to Revision 10812 ====
----
===== script: getelementofarray (operator[]): param1 not name ! =====
Source Syntax: ShowError("script: getelementofarray (operator[]): param1 not name !\n");
 Cause 
The variable name which you provided (the first argument of getelementofarray) is not a valid variable name.
 Solution 
Make sure that the variable name is using the correct syntax. For a full set of rules on variable naming, check the [[Variables|appropriate article]].
 Example 
Wrong code:
set @result, getelementofarray(1starray,3);
Correct code:
set @result, getelementofarray(firstarray,3);

----

[[Category:Debugging]]
[[Category:Scripting]]

Installation (Debian)

2015-07-08T12:54:08Z

Haru: Updated SQL tables information

This guide covers how to install [[Hercules]] on [[wikipedia:Debian|Debian]] and other [[wikipedia:List_of_Linux_distributions#Debian-based|versions of Linux]] that use apt-get.

== Requirements ==
* [[wikipedia:Debian|Debian]] or an [[wikipedia:List_of_Linux_distributions##Debian-based]] that has the apt-get command
* root access or access to an account that has [[wikipedia:Sudo|sudo privileges]]
* an Internet connection to download install packages

== Prerequisites ==
All of these commands will be typed at the [[wikipedia:Command-line_interface|command-line interface]].
=== Install Prerequisites ===
# Login to your server via [[wikipedia:Secure_Shell|SSH]], or if you are already logged into a [[wikipedia:Graphical_user_interface|GUI]] press Ctrl+Alt+T to open a terminal window.
apt-get update
apt-get upgrade
apt-get dist-update // To update to the latest version of Debian
# Type the following command (this will install GCC, Make, MySQL Server, MySQL header files, PCRE header files, git, and Zlib header files)
#: <pre>apt-get install git make gcc mysql-server libmysqlclient-dev zlib1g-dev libpcre3-dev screen</pre>

=== Create a non-root Linux user ===
By the [[wikipedia:Principle_of_least_privilege|principle of least privilege]], it is recommended you do '''NOT''' run Hercules as root.
# Type the following command to create a non-root Linux account:
#: <pre>useradd hercuser</pre>
# Be sure not to forget setting new password for new user
#: <pre>passwd hercuser</pre>

== Install [[Hercules]] ==

=== Login as your non-root Linux user ===
The rest of the setup is done as hercuser (the Linux user you created earlier)
# Logout from root SSH (or minimize the window).
# Login to your server via SSH as the hercuser Linux user.

=== Git Clone ===
<pre>git clone https://github.com/HerculesWS/Hercules.git ~/Hercules</pre>

=== [http://dev.mysql.com/doc/refman/5.5/en/batch-commands.html Import] MySQL Tables ===
# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercuser_rodb < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodblog < logs.sql</pre>
# If your Control Panel software or website requires it, you may also import the item, monster and monster skill databases (not necessary for the correct operation of Hercules)
(pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db.sql</pre>
(renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db_re.sql</pre>
(common to renewal and pre-renewal)
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db2.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_acc_reg_num_db, global_acc_reg_str_db, ipbanlist, login, loginlog
#map-server: autotrade_data, autotrade_merchants, mapreg, npc_market_data
#char-server: everything else
Note that the sql_updates table is needed by all three servers.

=== [[:Category:Configuration|Configure Hercules]]===

=== Compile Source Code ===
cd Hercules
./configure
make sql

*If you have added plugins for use with Hercules please use the below syntax instead of the above:
cd Hercules
./configure
make sql plugins

===== How to Recompile =====
In the future (after you update or edit any file in /src) to recompile, add ''make clean'' before make sql:
cd Hercules
./configure
'''make clean'''
make sql plugins

== Start your Hercules Server ==
//change access mode of athena-start file so that you can execute it.
//Use (dos2unix athena-start) if you are getting ^M errors ie. newline errors
chmod a+x athena-start

//To Start
./athena-start start
//To Stop
./athena-start stop
//To Restart
./athena-start restart

== See Also ==

[[Category:Installation Guides|Debian Linux]]

System Requirements

2015-06-29T23:29:04Z

Haru: /* Linux */

== Basic Requirements ==

[[Hercules]] works off of the [[wikipedia:Client–server_model|client-server model]]. The player, usually using a [[Hexing|hexed]] kRO [[Renewal|RE]] client, first connects to the [[Login Server]]. When the client enters their login information, it is given the list of available char-servers, which the player chooses from. After the server has been chosen, the client connects to the selected [[Character Server]], which displays the characters on that player's account. After selecting a character, the client is directed to the [[Map Server]], which maintains maps and the character positions on the server and relays this information to the client.

Hercules is designed to run on a machine that is designated as a Server, either Dedicated or VPS. It can run on a workstation, but using that workstation for other tasks (including playing on the same machine that is running the server) will reduce performance.

== Hardware Requirements ==
Hercules requires the following resources from the machine in order to function without problems or the common "Lag":

* 1.5 GHz or faster CPU, either Intel or AMD is acceptable. Some members have reported that they have gotten Hercules to run on other processors.
* 128 MB of RAM, MINIMUM. The map server in an idle state consumes about 76MB of RAM, depending on how many maps and [[NPC|NPCs]] are loaded (41mb when no NPCs are in use).
* A video card powerful enough to run the Operating System of your choice (or no video card at all). Hercules is a console based software, which means that all that is required to run it is a console or command access.
* Fast internet or network connection. This is very hard to predict. A lot of questions arise that ask 'how much bandwidth does Hercules need?'. There is no answer to that. It is all depending on how many characters are connected, from where, and what they do while connected to the server.
* 250MB of Hard Drive space or better, up-to gigabytes depending on how big the database may get.

== Software Requirements ==
Hercules, depending on what you plan to do with it and what platform you run it on, will require, at a minimum, the following:

* GCC compatible compiler
* GNU Make
* zlib
* MySQL server and libraries
* Git
* pcre (optional)

== Supported Operating Systems ==
The following operating systems have been tested and are known to work:
=== [[wikipedia:Linux|Linux]] ===
* Debian Based: [http://www.debian.org/ Debian], [http://www.knoppix.net/ Knoppix], [http://www.ubuntu.com/ Ubuntu Server & Desktop]
* RPM Based: [http://www.centos.org/ CentOS], [http://fedoraproject.org/ Fedora Core], [http://www2.mandriva.com/ Mandriva], [http://www.redhat.com/rhel/ Red Hat Linux], [http://www.novell.com/linux/ SUSE Linux]
* Others: [https://www.gentoo.org Gentoo], [http://www.slackware.com/ Slackware]

=== [[wikipedia:Unix|Unix]] ===
* BSD Based: [http://www.freebsd.org/ FreeBSD], [http://www.openbsd.org/ OpenBSD]
=== [[wikipedia:Microsoft_Windows|Windows]] ===
* [[wikipedia:Windows_Server|Server Versions]]: Windows Server 2008, Windows Server 2008 R2, Windows Server 2012
* Home Versions: Windows Vista, Windows 7, Windows 8, Windows 8.1

[[Category:Basics]]

System Requirements

2015-06-29T23:28:48Z

Haru: /* Supported Operating Systems */

== Basic Requirements ==

[[Hercules]] works off of the [[wikipedia:Client–server_model|client-server model]]. The player, usually using a [[Hexing|hexed]] kRO [[Renewal|RE]] client, first connects to the [[Login Server]]. When the client enters their login information, it is given the list of available char-servers, which the player chooses from. After the server has been chosen, the client connects to the selected [[Character Server]], which displays the characters on that player's account. After selecting a character, the client is directed to the [[Map Server]], which maintains maps and the character positions on the server and relays this information to the client.

Hercules is designed to run on a machine that is designated as a Server, either Dedicated or VPS. It can run on a workstation, but using that workstation for other tasks (including playing on the same machine that is running the server) will reduce performance.

== Hardware Requirements ==
Hercules requires the following resources from the machine in order to function without problems or the common "Lag":

* 1.5 GHz or faster CPU, either Intel or AMD is acceptable. Some members have reported that they have gotten Hercules to run on other processors.
* 128 MB of RAM, MINIMUM. The map server in an idle state consumes about 76MB of RAM, depending on how many maps and [[NPC|NPCs]] are loaded (41mb when no NPCs are in use).
* A video card powerful enough to run the Operating System of your choice (or no video card at all). Hercules is a console based software, which means that all that is required to run it is a console or command access.
* Fast internet or network connection. This is very hard to predict. A lot of questions arise that ask 'how much bandwidth does Hercules need?'. There is no answer to that. It is all depending on how many characters are connected, from where, and what they do while connected to the server.
* 250MB of Hard Drive space or better, up-to gigabytes depending on how big the database may get.

== Software Requirements ==
Hercules, depending on what you plan to do with it and what platform you run it on, will require, at a minimum, the following:

* GCC compatible compiler
* GNU Make
* zlib
* MySQL server and libraries
* Git
* pcre (optional)

== Supported Operating Systems ==
The following operating systems have been tested and are known to work:
=== [[wikipedia:Linux|Linux]] ===
* Debian Based: [http://www.debian.org/ Debian], [http://www.knoppix.net/ Knoppix], [http://www.ubuntu.com/ Ubuntu Server & Desktop]
* RPM Based: [http://www.centos.org/ CentOS], [http://fedoraproject.org/ Fedora Core], [http://www2.mandriva.com/ Mandriva], [http://www.redhat.com/rhel/ Red Hat Linux], [http://www.novell.com/linux/ SUSE Linux]
* Others: [https://www.gentoo.org] Gentoo], [http://www.slackware.com/ Slackware]

=== [[wikipedia:Unix|Unix]] ===
* BSD Based: [http://www.freebsd.org/ FreeBSD], [http://www.openbsd.org/ OpenBSD]
=== [[wikipedia:Microsoft_Windows|Windows]] ===
* [[wikipedia:Windows_Server|Server Versions]]: Windows Server 2008, Windows Server 2008 R2, Windows Server 2012
* Home Versions: Windows Vista, Windows 7, Windows 8, Windows 8.1

[[Category:Basics]]

System Requirements

2015-06-29T23:26:17Z

Haru: /* Software Requirements */

== Basic Requirements ==

[[Hercules]] works off of the [[wikipedia:Client–server_model|client-server model]]. The player, usually using a [[Hexing|hexed]] kRO [[Renewal|RE]] client, first connects to the [[Login Server]]. When the client enters their login information, it is given the list of available char-servers, which the player chooses from. After the server has been chosen, the client connects to the selected [[Character Server]], which displays the characters on that player's account. After selecting a character, the client is directed to the [[Map Server]], which maintains maps and the character positions on the server and relays this information to the client.

Hercules is designed to run on a machine that is designated as a Server, either Dedicated or VPS. It can run on a workstation, but using that workstation for other tasks (including playing on the same machine that is running the server) will reduce performance.

== Hardware Requirements ==
Hercules requires the following resources from the machine in order to function without problems or the common "Lag":

* 1.5 GHz or faster CPU, either Intel or AMD is acceptable. Some members have reported that they have gotten Hercules to run on other processors.
* 128 MB of RAM, MINIMUM. The map server in an idle state consumes about 76MB of RAM, depending on how many maps and [[NPC|NPCs]] are loaded (41mb when no NPCs are in use).
* A video card powerful enough to run the Operating System of your choice (or no video card at all). Hercules is a console based software, which means that all that is required to run it is a console or command access.
* Fast internet or network connection. This is very hard to predict. A lot of questions arise that ask 'how much bandwidth does Hercules need?'. There is no answer to that. It is all depending on how many characters are connected, from where, and what they do while connected to the server.
* 250MB of Hard Drive space or better, up-to gigabytes depending on how big the database may get.

== Software Requirements ==
Hercules, depending on what you plan to do with it and what platform you run it on, will require, at a minimum, the following:

* GCC compatible compiler
* GNU Make
* zlib
* MySQL server and libraries
* Git
* pcre (optional)

== Supported Operating Systems ==
The following operating systems have been tested and are known to work:
=== [[wikipedia:Linux|Linux]] ===
* Debian Based: [http://www.debian.org/ Debian], [http://www.knoppix.net/ Knoppix], [http://www.ubuntu.com/ Ubuntu Server & Desktop]
* RPM Based: [http://www.centos.org/ CentOS], [http://fedoraproject.org/ Fedora Core], [http://www2.mandriva.com/ Mandriva], [http://www.redhat.com/rhel/ Red Hat Linux], [http://www.novell.com/linux/ SUSE Linux]
* Slackware Based: [http://www.slackware.com/ Slackware]
=== [[wikipedia:Unix|Unix]] ===
* BSD Based: [http://www.freebsd.org/ FreeBSD], [http://www.openbsd.org/ OpenBSD]
=== [[wikipedia:Microsoft_Windows|Windows]] ===
* [[wikipedia:Windows_Server|Server Versions]]: Windows Server 2000, Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012
* Home Versions: Windows 98, Windows ME, Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows 8.1

64-bit operating systems of all those listed will take some time and effort to get working.

[[Category:Basics]]

System Requirements

2015-06-29T23:25:21Z

Haru: /* Hardware Requirements */

== Basic Requirements ==

[[Hercules]] works off of the [[wikipedia:Client–server_model|client-server model]]. The player, usually using a [[Hexing|hexed]] kRO [[Renewal|RE]] client, first connects to the [[Login Server]]. When the client enters their login information, it is given the list of available char-servers, which the player chooses from. After the server has been chosen, the client connects to the selected [[Character Server]], which displays the characters on that player's account. After selecting a character, the client is directed to the [[Map Server]], which maintains maps and the character positions on the server and relays this information to the client.

Hercules is designed to run on a machine that is designated as a Server, either Dedicated or VPS. It can run on a workstation, but using that workstation for other tasks (including playing on the same machine that is running the server) will reduce performance.

== Hardware Requirements ==
Hercules requires the following resources from the machine in order to function without problems or the common "Lag":

* 1.5 GHz or faster CPU, either Intel or AMD is acceptable. Some members have reported that they have gotten Hercules to run on other processors.
* 128 MB of RAM, MINIMUM. The map server in an idle state consumes about 76MB of RAM, depending on how many maps and [[NPC|NPCs]] are loaded (41mb when no NPCs are in use).
* A video card powerful enough to run the Operating System of your choice (or no video card at all). Hercules is a console based software, which means that all that is required to run it is a console or command access.
* Fast internet or network connection. This is very hard to predict. A lot of questions arise that ask 'how much bandwidth does Hercules need?'. There is no answer to that. It is all depending on how many characters are connected, from where, and what they do while connected to the server.
* 250MB of Hard Drive space or better, up-to gigabytes depending on how big the database may get.

== Software Requirements ==
Hercules, depending on what you plan to do with it and what platform you run it on, will require, at a minimum, the following:

* GCC compatible compiler
* zlib
* MySQL server and libraries
* Git (if using self-compiled packages)

== Supported Operating Systems ==
The following operating systems have been tested and are known to work:
=== [[wikipedia:Linux|Linux]] ===
* Debian Based: [http://www.debian.org/ Debian], [http://www.knoppix.net/ Knoppix], [http://www.ubuntu.com/ Ubuntu Server & Desktop]
* RPM Based: [http://www.centos.org/ CentOS], [http://fedoraproject.org/ Fedora Core], [http://www2.mandriva.com/ Mandriva], [http://www.redhat.com/rhel/ Red Hat Linux], [http://www.novell.com/linux/ SUSE Linux]
* Slackware Based: [http://www.slackware.com/ Slackware]
=== [[wikipedia:Unix|Unix]] ===
* BSD Based: [http://www.freebsd.org/ FreeBSD], [http://www.openbsd.org/ OpenBSD]
=== [[wikipedia:Microsoft_Windows|Windows]] ===
* [[wikipedia:Windows_Server|Server Versions]]: Windows Server 2000, Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012
* Home Versions: Windows 98, Windows ME, Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows 8.1

64-bit operating systems of all those listed will take some time and effort to get working.

[[Category:Basics]]

GDB

2015-02-25T18:14:46Z

Haru: /* Using gdb with Hercules */ Additional info about debug builds

GDB stands for GNU Debugger. It is a program for *nix related systems that allows you to view stacktrace and coredumps of your servers if it crashes.

= Getting GDB =
Typically GDB comes installed on most *nix distro's. It comes installed on FreeBSD 7.1-RELEASE or newer if the ports collection is installed. Typically, it will be located in /usr/bin/gdb, but if it is not, you can either compile it from source or install it using your package manager for your distribution.

== Debian Based (apt-get, aptitude or synaptic) ==
On Debian based systems, you can use apt-get or aptitude, or the synaptic package manager to install gdb. If you prefer the terminal, you can issue ONE of the following to install gdb:

[sudo] aptitude install gdb
[sudo] apt-get install gdb

If you have access to gdm and the synaptic package manager, you can simply search for 'gdb' and mark for complete installation.

== YUM based (Redhat/CentOS) ==
On YUM based systems, you can simply issue the following to install gdb via RPM packages:

yum install gdb

== *BSD based ==
Typically GDM will come with an install of FreeBSD, but if it's not, it is best to make it from source, skip ahead.

== Compiling from source ==
Use your favourite download manager (wget, etc) to get the .tar.gz of the latest stable version of gdb from gdb's website. (http://www.gnu.org/software/gdb/)

Extract the .tar.gz using the following command:

tar -zxf gdb-x.xx.tar.gz

You need a GCC compatible compiler, so if you don't have one, get one now. there is a 99% chance that your distribution comes with a gcc compiler.

./configure && make && make install

Should install it for use. If you're on a *BSD based system, you may have to issue the following command to be able to use it.

% rehash

= Using gdb with Hercules =

Go to Your Hercules Folder and type the following command

ulimit -u unlimited

Restart the server then,
Find out which program(map/char/login server) crashed and its core file (should be named the same as the server file with an additional ".core" extension).. then on the console, type:

gdb xxx-server xxx-server.core

'''[xxx = map/char/login (The one which is crashing)]'''

You should get some limited output of the problem, or if the servers do not have a trace, you will get the following error:

No stack.

If it says Dump file was not found, then type the following command(The file is saved with other name)

gdb xxx-server core

'''[xxx = map/char/login (The one which is crashing)]'''

If a valid dump was found, you should get a prompt

gdb>

At that prompt, type:

gdb> bt full

And that will give you a full output of the problem area and a line number in which you should look for the crash. This just told you where the crash is located and what line you should look at to fix it. If you feel that is an Hercules development problem, feel free to submit a bug with that full report and one of the core developers can look into it.

'''Note:''' in order to obtain detailed information from gdb, Hercules needs to be compiled with special flags. Normal builds are optimized for performance and don't include debug information. To build in debug mode, it is necessary to pass --enable-debug=gdb and --disable-lto to the configure script as follows:

./configure --enable-debug=gdb --disable-lto
make clean
make sql

= See Also =
* [http://www.gnu.org/software/gdb/download/ Download page for GDB]
[[Category:Debugging]]

Installation (CentOS)

2014-11-10T04:33:48Z

Haru: Removed some references to 'trunk', since the default directory name is now 'Hercules'. Removed note about --disable-64bit, since it is currently auto-detected.

This guide covers how to install [[Hercules]] on [[wikipedia:CentOS|CentOS]] and other [[wikipedia:List_of_Linux_distributions#RPM-based|versions of Linux]] that use [[wikipedia:Yellowdog_Updater,_Modified|yum]].

== Requirements ==
* [[wikipedia:CentOS|CentOS]] or an [[wikipedia:List_of_Linux_distributions#RPM-based|RPM-based Linux]] that has the '''[[wikipedia:Yellowdog_Updater,_Modified|yum]]''' command
* root access or access to an account that has [[wikipedia:Sudo|sudo privileges]]
* an Internet connection to download install packages

== Prerequisites ==
All of these commands will be typed at the [[wikipedia:Command-line_interface|command-line interface]].
=== Install Prerequisites ===
# Login to your server via [[wikipedia:Secure_Shell|SSH]], or if you are already logged into a [[wikipedia:Graphical_user_interface|GUI]] press Ctrl+Alt+T to open a terminal window.
# Type the following command (this will install GCC, Make, MySQL, MySQL header files, MySQL Server, PCRE header files, Git, and Zlib header files)
#: <pre>yum install gcc make mysql mysql-devel mysql-server pcre-devel git zlib-devel</pre>
# (Optional) type the following command to install some additional packages:
#: <pre>yum -y install dos2unix gdb nano screen unzip wget zip</pre>

=== Create a non-root Linux user ===
By the [[wikipedia:Principle_of_least_privilege|principle of least privilege]], it is recommended you do '''NOT''' run Hercules as root.
# Type the following command to create a non-root Linux account:
#: <pre>useradd --create-home --shell /bin/bash hercules1234</pre>
#: <code>--create-home</code> = create the user's home directory
#: <code>--shell</code> = sets their login shell to [[wikipedia:Bash_(Unix_shell)|Bash]]
#: '''<code>hercules1234</code>''' = the login name of the new Linux account
#: ''<code>1234</code>'' = pick your own random numbers to make the username more unique
# Set a password for the new user (run this command and follow the prompts):
#: <pre>passwd hercules1234</pre>

=== Configure MySQL ===

==== Set a root password ====
The default MySQL Server install creates a MySQL user 'root'@'localhost' with NO password. It is recommended you create a password for the root user.
# Run this command and follow the prompts:
#: Firest Start MySQL:
#: <pre>/etc/init.d/mysqld start </pre>
#: Then configure MySQL by:
#: <pre>mysql_secure_installation</pre>
# Login to your MySQL Server as root:
#: ''When prompted, enter your root MySQL password.''
#: <pre>mysql --user=root -p</pre>
# Now your prompt should look like this (the MySQL command prompt):
#: <pre>mysql> </pre>

==== Create SQL database for Hercules ====
# At the MySQL prompt, type this to [http://dev.mysql.com/doc/refman/5.5/en/create-database.html create a database] (replace <code>hercules1234</code> with the Linux username you created earlier):
#: <pre>mysql> CREATE DATABASE hercules1234_rag;</pre>
# Create a separate database for logs:
#: <pre>mysql> CREATE DATABASE hercules1234_log;</pre>

==== Setup a MySQL user for Hercules ====
# At the MySQL prompt, type something like this to create a new MySQL user:
#: <pre>mysql> CREATE USER 'hercules1234'@'localhost' IDENTIFIED BY 'secretpassword';</pre>
#: <code>hercules1234</code> = the name of the MySQL user (we named it the same as the Linux user to make it easier to identify)
#: <code>localhost</code> = the hostname or IP it will connect from
#: '''<code>secretpassword</code>''' = the password for this MySQL user
# [http://dev.mysql.com/doc/refman/5.5/en/grant.html Grant privileges] to the 'hercules' MySQL user:
#: <pre>mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON `hercules1234\_rag`.* TO 'hercules1234'@'localhost';</pre>
#: <pre>mysql> GRANT SELECT,INSERT ON `hercules1234\_log`.* TO 'hercules1234'@'localhost';</pre> (note the [http://dev.mysql.com/doc/refman/5.5/en/string-literals.html#character-escape-sequences escaped underscore])

== Install [[Hercules]] ==

=== Login as your non-root Linux user ===
The rest of the setup is done as hercules1234 (the Linux user you created in step 2.2)
# Logout from root SSH (or minimize the window).
# Login to your server via SSH as the hercules1234 Linux user.

=== Git Clone ===
{{:Git Clone/Unix}}

=== [http://dev.mysql.com/doc/refman/5.5/en/batch-commands.html Import] MySQL Tables ===
# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercules1234_rag < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_skill_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_skill_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_log < logs.sql</pre>
# If you are using Renewal you also have to import the following
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < item_db2_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercules1234_rag < mob_skill_db_re.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_reg_value, ipbanlist, login, loginlog
#map-server: mapreg, item_db, item_db2, mob_db, mob_db2,mob_skill_db
#char-server: everything else + global_reg_value once again
Note that global_reg_value tables are needed by both login-server and char-server (though it may be different tables)

=== [[:Category:Configuration|Configure Hercules]]===

=== Compile Source Code ===
cd Hercules
./configure
make sql

===== How to Recompile =====
In the future (after you update or edit any file in /src) to recompile, add ''make clean'' before make sql:
cd Hercules
./configure
'''make clean'''
make sql

== Start your Hercules Server ==
//change access mode of athena-start file so that you can execute it.
//Use (dos2unix athena-start) if yo uare getting ^M errors ie. newline errors
chmod a+x athena-start

//To Start
./athena-start start
//To Stop
./athena-start stop
//To Restart
./athena-start restart

== See Also ==

[[Category:Installation Guides|CentOS]]

Installation (Debian)

2014-11-10T04:30:39Z

Haru: Removed some references to 'trunk', since the default directory name is now 'Hercules'. Removed note about --disable-64bit, since it is currently auto-detected.

This guide covers how to install [[Hercules]] on [[wikipedia:Debian|Debian]] and other [[wikipedia:List_of_Linux_distributions#Debian-based|versions of Linux]] that use apt-get.

== Requirements ==
* [[wikipedia:Debian|Debian]] or an [[wikipedia:List_of_Linux_distributions##Debian-based]] that has the apt-get command
* root access or access to an account that has [[wikipedia:Sudo|sudo privileges]]
* an Internet connection to download install packages

== Prerequisites ==
All of these commands will be typed at the [[wikipedia:Command-line_interface|command-line interface]].
=== Install Prerequisites ===
# Login to your server via [[wikipedia:Secure_Shell|SSH]], or if you are already logged into a [[wikipedia:Graphical_user_interface|GUI]] press Ctrl+Alt+T to open a terminal window.
apt-get update
apt-get upgrade
apt-get dist-update // To update to the latest version of Debian
# Type the following command (this will install GCC, Make, MySQL Server, MySQL header files, PCRE header files, git, and Zlib header files)
#: <pre>apt-get install git make gcc mysql-server libmysqlclient-dev zlib1g-dev libpcre3-dev screen</pre>

=== Create a non-root Linux user ===
By the [[wikipedia:Principle_of_least_privilege|principle of least privilege]], it is recommended you do '''NOT''' run Hercules as root.
# Type the following command to create a non-root Linux account:
#: <pre>useradd hercuser</pre>
# Be sure not to forget setting new password for new user
#: <pre>passwd hercuser</pre>

== Install [[Hercules]] ==

=== Login as your non-root Linux user ===
The rest of the setup is done as hercuser (the Linux user you created earlier)
# Logout from root SSH (or minimize the window).
# Login to your server via SSH as the hercuser Linux user.

=== Git Clone ===
<pre>git clone https://github.com/HerculesWS/Hercules.git ~/Hercules</pre>

=== [http://dev.mysql.com/doc/refman/5.5/en/batch-commands.html Import] MySQL Tables ===
# Change directory to the '''sql-files''' folder.
#: <pre>cd sql-files/</pre>
# Execute these commands:
#: ''When prompted, enter your MySQL root password.''
#: <pre>mysql -u root -prootpassword hercuser_rodb < main.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db2.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodblog < logs.sql</pre>
# If you are using Renewal you also have to import the following
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < item_db2_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_db_re.sql</pre>
#: <pre>mysql -u root -prootpassword hercuser_rodb < mob_skill_db_re.sql</pre>

NOTE: if you want to use different SQL DBs for login/char/map servers this is the list of databases each server use:
#login-server: global_reg_value, ipbanlist, login, loginlog
#map-server: mapreg, item_db, item_db2, mob_db, mob_db2,mob_skill_db
#char-server: everything else + global_reg_value once again
Note that global_reg_value tables are needed by both login-server and char-server (though it may be different tables)

=== [[:Category:Configuration|Configure Hercules]]===

=== Compile Source Code ===
cd Hercules
./configure
make sql

*If you have added plugins for use with Hercules please use the below syntax instead of the above:
cd Hercules
./configure
make sql plugins

===== How to Recompile =====
In the future (after you update or edit any file in /src) to recompile, add ''make clean'' before make sql:
cd Hercules
./configure
'''make clean'''
make sql plugins

== Start your Hercules Server ==
//change access mode of athena-start file so that you can execute it.
//Use (dos2unix athena-start) if you are getting ^M errors ie. newline errors
chmod a+x athena-start

//To Start
./athena-start start
//To Stop
./athena-start stop
//To Restart
./athena-start restart

== See Also ==

[[Category:Installation Guides|Debian Linux]]