Basic scripting¶

Warning

This page may contain outdated information, incompatible with the current version of Hercules and its coding standards.

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 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,4scriptTest NPC1_M_MERCHANT,{

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

functionscriptFunction Name{

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,4shopFruit Store1_M_MERCHANT,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 "";

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

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:
OnInit:
OnAgitStart:
OnAgitEnd:
OnTouch:
OnPCLoginEvent:
OnPCLogoutEvent:
OnPCBaseLvUpEvent:
OnPCJobLvUpEvent:
OnPCDieEvent:
OnPCKillEvent:
OnNPCKillEvent:
OnPCLoadMapEvent:

Menus, Close, and Next¶

*menu "",{,"",,...};
*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¶

*if(condition) {