This is an attempt to standardize the eAthena scripting. Any suggestions are welcome to be posted on the discussion page before editing.

Conventions

Typographical style

Typographical conventions vary depending on situation. The following are recommendations for an international English on the eAthena client (which does not support Unicode at this writing).

Punctuation

• Use only one space ( ) after the punctuation ending a sentence.
• Use three dots (...) for an ellipsis, which marks something cut off.
• Use two dashes (--) for wider dashes, which are used in several constructions, among them denoting ranges and offsetting parts of a text.
  • Please add spaces around the dashes when they are used parenthetically.

// Punctuation example
	mes "[Luca the Hunter]";
	mes "\"Luckily I had a camera with me! Here's a picture of it...\"";
	mes "A liquid -- smelling strangely of fermented apples -- is applied.";

Quotes

• Use \" for direct speech.
  • For the double quotation mark not to interfere with the scripting code, a backslash needs to be prepended it.
• Contractions and quotes within the direct speech use the single quote '.

// Quote example
	mes "\"Ah, Agostine! The 'legendary tailor'!\"";
	mes "\"Aw, you don't have enough gold on you!\"";

Formatting text

• Item and monster names, please use the names in the way shown by the client (e.g., Black Scorpion, Bottle of Sand) outside direct speech in the dialogues.
• Emphasis may be formatted with capital letters, use it sparingly.
• Actions may be put inside asterisks, use it sparingly.

// Formatting example
	mes "\"I was fighting scorpions for experience and I bumped into a RED one.\"";
	mes "\"I fought, of course! It hit me here *points at a bruise at his shoulder*.\"";

Coding conventions

Comments

• Each file should begin with a comment block describing the scope and use of the file.
  • Put a template here?

Indentation

• All indentations are made with tabs, one for each indentation level.
• Labels use no indentations at all.
• Menus have all their options on their own lines, and indented one level.
• If clauses...

// Indentation example
L_label:
	mes "What do you want to do?";
	next;
	menu
		"Spend money", -,
		"Script a fun quest", L_good_choice;
	close;

Various

• Script files should end with a newline (a empty line).

Code blocks

• Code blocks should be separated from each other in a dinstinct way; the best way of doing it is to insert a blank line between code blocks.
• Do not add blank lines within individual blocks.
• The opening brackets should be at the end of the parent line, not in a new line; the closing ones should be on a line of their own.

• In creating an NPC, remember to follow the rules stated in the NPC development section.

Example

An example is given by a quest to get a key for a chest:

// A treasure chest. You need three keys to open it. new_5-1.gat,93,37,0 script Treasure 111,{ mes "Would you try to open it?"; next; menu "Yup", L_Sure, "Nope", close; L_Sure: if (countitem(537) < 3) goto L_WrongKey; delitem 537, 3; getitem 536, 1; mes "You opened it and found a short sword!"; close; L_WrongKey: mes "It seems that this is not the right key..."; close; }

The above script starts with describing the NPC (the chest, NPC sprite 111) and its location. Then follows what happens on activation. A message is shown, then an option dialog is displayed. Then, when the player has less than 3 keys (item id 537), he is told not to have the right key. If he does, the player looses three keys and receives a short sword (item id 536). This quest in particular is questionable as the explanation given to the player doesn't match the implemented behavior (possibly to make the quest more challenging), but I've put it here because it is short and shows one basic way to use the scripting system.

For more examples of the current system, check out the current scripts in use by the server. Beware though, this could affect your enjoyment of the game as it does spoil some of the mystery. Here's a link to SVN so you can view them in your browser:

http://themanaworld.svn.sourceforge.net/viewvc/themanaworld/server-data/trunk/npc/

Note that anything said by an NPC should be put in double quotes ("). You can do that like this: "\"Hello!\" she said."

Map objects

Key
<TAB>	a tab
text	static text, do not change
text	obligatory value, change this
text	optional value, may be skipped

These sections describe how to define map objects.

Warps

Warps are what move players between maps. They can also be used to move players around a single map, if needed. Warps are defined like this:

map1,startX,startY<TAB>warp<TAB>name<TAB>width,height,map2,endX,endY

Where

• map1 is the map which the player will warp from
• startX is the x-coordinate of the tile the player will warp from
• startY is the y-coordinate of the tile the player will warp from
• name is the name of the warp, unused but must be defined
• width is the width of the warp
• height is the height of the warp
• map2 is the map which the player will warp to
• endX is the x-coordinate of the tile the player will end up on
• endY is the y-coordinate of the tile the player will end up on

Width and height are described in detail in Warp Details.

// Warp example (npc/new_10-1-xmas/passages.txt)

new_10-1.gat,69,19	warp	tovillage	4,1,new_11-1.gat,69,127

Monsters

Monsters are defined like this:

map,x,y,width,height<TAB>monster<TAB>name<TAB>mobID,count,spawn1,spawn2,event

Where

• map is the map the monsters should appear on
• x is the x-coordinate of the spawn tile
• y is the y-coordinate of the spawn tile
• width is the tile width of the spawn area
• height is the tile height of the spawn area
• name is the name of the mob, unused but must be defined
• mobID is the mob identifier of the desired monster (in the monster database [1])
• count is the number to spawn
• spawn1 is the minimum delay between successive spawns (per individual)
• spawn2 is the minimum delay between death and respawn (per individual)
• event is the script event to fire upon death

A detailed description of position and area can be found in Mob Details.

// Monster example (npc/new_9-1-woodland/monsters.txt)

new_9-1.gat,0,0,0,0	monster	EvilMushroom	1013,25,0,0,0
new_9-1.gat,0,0,0,0	monster	SleepFlower	1014,40,0,0,0
new_9-1.gat,0,0,0,0	monster	Alzarin	1032,1,2700000,1800000,0

NPCs

NPCs are defined like

map,x,y,direction<TAB>script<TAB>name<TAB>npcID,area1,area2,{

script

}

Where

• map is the map the NPC is located in
• x is the x-coordinate of the NPC
• y is the y-coordinate of the NPC
• direction is the direction the NPC faces, unused but must be defined
• name is the name of the NPC, to hide (the latter part of) a name to the client begin (that part of) the name with a hash (#)
• npcID is the NPC identifier (in the NPC database [2])
• area1 and area2 describe the map area which activates the NPC, optional
• script is the NPC script, see the below

The name of the NPC can be hidden to the player, part of the name or the whole. Begin the name with a hash (#) to hide the whole name, or add it before the part which should be truncated (it will be truncated to the end).

// NPC example with activation area (npc/new_37-1-woodland-mine/miners.txt)

new_37-1.gat,78,59,0	script	Miner	109,1,1,{
	mes "[Miner]";
	mes "\"I'm sorry, but this area is closed off.\"";
}

Shops

Shops are defined like

map,x,y,direction<TAB>shop<TAB>name<TAB>npcID,inventory

Where

• map is the map the shop is located in
• x is the x-coordinate of the shop
• y is the y-coordinate of the shop
• direction is the direction the shop faces, unused but must be defined
• name is the name of the shop, to hide (the latter part of) a name to the client begin (that part of) the name with a hash (#)
• npcID is the NPC identifier for the shop
• inventory is a comma separated inventory list of items to sale

The inventory is defined like

itemID:price[,itemID:price]*

Where [...]* means that part can be repeated as necessary, and

• itemID is the item identifier (in the item database [3])
• price is the price the item is sold for

You add an item:price pair for any item that should be sold by the shop.

// Shop example (npc/new_23-1-dimonds-cove/dimonds.txt)

new_23-1.gat,24,27,0	shop	Bartender	107,539:175,567:500,568:500