diff options
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 318 |
1 files changed, 240 insertions, 78 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index b8eaa8ebc..bcf269535 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -1,7 +1,7 @@ //===== Athena Doc ======================================== -//= eAthena Script Commands +//= rAthena Script Commands //===== Description ======================================= -//= A reference manual for the eAthena scripting language. +//= A reference manual for the rAthena scripting language. //= Commands are sorted depending on their functionality. //===== Version =========================================== //= 3.45.20110709 @@ -183,13 +183,10 @@ //= Added 'getmercinfo' command. [Ai4rei] //= 3.46.20110810 //= Added information on OnTouchNPC and 'unitwarp' special case [Skotlex] -//= 3.47.20111025 -//= Documented successruneuse and setdragon. [L0ne_W0lf] -//= Ammended documentation for Produce. //========================================================= This document is a reference manual for all the scripting commands and functions -available in current eAthena SVN. It is not a simple tutorial. When people tell +available in current rAthena SVN. It is not a simple tutorial. When people tell you to "Read The F***ing Manual", they mean this. The information was mostly acquired through looking up how things actually work @@ -275,6 +272,19 @@ Whenever '//' is encountered in a line upon reading, everything beyond this on that line is considered to be a comment and is ignored. This works wherever you place it. +// This line will be ignored when processing the script. + +Block comments can also be used, where you can place /* and */ between any text you +wish rAthena to ignore. + +Example: +/* This text, + * no matter which new line you start + * is ignored, until the following + * symbol is encountered: */ + +The asterisks (*) in front of each line is a personal preference, and is not required. + Upon loading all the files, the server will execute all the top-level commands in them. No variables exist yet at this point, no commands can be called other than those given in this section. These commands set up the basic server script @@ -318,7 +328,7 @@ Monster name is the name the monsters will have on screen, and has no relation whatsoever to their names anywhere else. It's the mob id that counts, which identifies monster record in 'mob_db.txt' database of monsters. If the mob name is given as "--ja--", the 'japanese name' field from the monster database is -used, (which, in eAthena, actually contains an english name) if it's "--en--", +used, (which, in rAthena, actually contains an english name) if it's "--en--", it's the 'english name' from the monster database (which contains an uppercase name used to summon the monster with a GM command). @@ -334,13 +344,10 @@ below). Amount is the amount of monsters that will be spawned when this command is executed, it is affected by spawn rates in 'battle_athena.conf'. -Delay1 and delay2 are the monster respawn delays - the first one counts the time -since a monster defined in this spawn was last respawned and the second one -counts the time since the monster of this spawn was last killed. Whichever turns -out to be higher will be used. If the resulting number is smaller than a random -value between 5 and 10 seconds, this value will be used instead. (Which is -normally the case if both delay values are zero.) The times are given in -1/1000ths of a second. +Delay1 and delay2 control monster respawn delays - the first one is the fixed +base respawn time, and the second is random variance on top of the base time. +Both values are given in miliseconds (1000 = 1 second). +Note that the server also enforces a minimum respawn delay of 5 seconds. You can specify a custom level to use for the mob different from the one of the database by adjoining the level after the name with a comma. eg: @@ -508,7 +515,7 @@ What a RID is and why do you need to know Most scripting commands and functions will want to request data about a character, store variables referenced to that character, send stuff to the client connected to that specific character. Whenever a script is invoked by a -character, it is passed a so-called RID - this is the character ID number of a +character, it is passed a so-called RID - this is the account ID number of a character that caused the code to execute by clicking on it, walking into it's OnTouch zone, or otherwise. @@ -582,7 +589,7 @@ Variables The meat of every programming language is variables - places where you store data. -In the eAthena scripting language, variable names are not case sensitive. +In the rAthena scripting language, variable names are not case sensitive. Variables are divided into and uniquely identified by the combination of: prefix - determines the scope and extent (or lifetime) of the variable @@ -628,6 +635,9 @@ nothing - A permanent variable attached to the character, the default variable callsub/callfunc starts a new scope, returning from the function ends it. When a scope ends, it's variables are converted to values ('return .@var;' returns a value, not a reference). +"'" - An instance variable + These are used with the instancing system, and are unique to each + party's instance. "#" - A permanent local account variable. They are stored with all the account data in "save\accreg.txt" in TXT versions and in the SQL versions in the 'global_reg_value' @@ -719,7 +729,7 @@ To include symbol '"' in a string you should use prefix '\"' Arrays ------ -Arrays (in eAthena at least) are essentially a set of variables going under the +Arrays (in rAthena at least) are essentially a set of variables going under the same name. You can tell between the specific variables of an array with an 'array index', a number of a variable in that array: @@ -866,7 +876,7 @@ Logical bitwise operators work only on numbers, and they are the following: | - Or. The bitwise operator AND (&) is used to test two values against each other, and results in setting bits which are active in both arguments. This can - be used for a few things, but in eAthena this operator is usually used to + be used for a few things, but in rAthena this operator is usually used to create bit-masks in scripts. The bitwise operator OR (|)sets to 1 a binary position if the binary position @@ -2132,7 +2142,7 @@ Notice that @array[4] and @array[5] won't be copied to the second array, and it --------------------------------------- -*deletearray <array name>[<first value>],<how much to delete> +*deletearray <array name>[<first value>],<how much to delete>; This command will delete a specified number of array elements totally from an array, shifting all the elements beyond this towards the beginning. @@ -2211,8 +2221,9 @@ This is equivalent to using: The reason for this is, that this short form is internally converted into a call to getelementofarray, when the script is loaded. -Also useful when passing arrays to functions. -getelementofarray(getarg(0),<index>) will work, but getarg(0)[<index>] will not. +Also useful when passing arrays to functions or accessing another npc's arrays: + getelementofarray(getarg(0),<index>) + getelementofarray(getvariableofnpc(.var, "testNPC"),<index>) --------------------------------------- @@ -2500,7 +2511,7 @@ See 'getequipid' for a full list of valid equipment slots. *getitemname(<item id>) Given the database ID number of an item, this function will return the text -stored in the 'japanese name' field (which, in eAthena, stores an english name +stored in the 'japanese name' field (which, in rAthena, stores an english name the players would normally see on screen.) --------------------------------------- @@ -2772,17 +2783,6 @@ when you want to check item cards or if it's signed. Useful for such quests as Hat[0] +4 -> Player's Hat[0] +4 --------------------------------------- - -*successruneuse(<item id>) - -Returns 0 (failed) or 1 (success) when using Rune Knight Runestone items. - - if(successuserune(12725)){ itemskill RK_REFRESH,1; } else { dispbottom "You have failed to use the runestone."; } - -This function not only determines if the rune stone was used successfully -but will also handle the backfire effects imposed upon the player. - ---------------------------------------- // 2,1.- End of item-related commands. // @@ -2894,7 +2894,7 @@ http://www.delorie.com/gnu/docs/glibc/libc_437.html All the format characters given in there should properly work. Max length is the maximum length of a time string to generate. -The example given in eAthena sample scripts works like this: +The example given in rAthena sample scripts works like this: mes gettimestr("%Y-%m/%d %H:%M:%S",21); @@ -3265,14 +3265,6 @@ character while the map is "this", it will return -1. --------------------------------------- -*getstrlen("<string>") - -This function will return the length of the string given as an argument. It is -useful to check if anything input by the player exceeds name length limits and -other length limits and asking them to try to input something else. - ---------------------------------------- - *skillpointcount() Returns the total amount of skill points a character possesses (SkillPoint+SP's used in skills) @@ -3494,30 +3486,6 @@ bird and 0 if they don't. --------------------------------------- -*setdragon {<flag>{,<color>}}; - -If <flag> is 0 this command will remove the mount from the character. -Otherwise it give the invoking character a Dragon Mount if they are a Rune -Knight - -If both <flag> and <color> are supplied, and flag is 1, <color> will change -color of the dragon mount used. <color> is 0 by default. Values higher than 4, -or lower than 0, will default to red or green respectively. - -Valid values for <color> are: - DRAGON_GREEN (0), - DRAGON_BLACK (1), - DRAGON_WHITE (2), - DRAGON_BLUE (3), - DRAGON_RED (4) - -This command is limited to only Rune Knights. - -Note: the character needs to have the skill KN_RIDING to gain a mount -This may be a bug in AEGIS, as RK_DRAGONTRAINING should limit this. - ---------------------------------------- - *checkvending ({"<player name>"}) *checkchatting ({"<Player Name>"}) @@ -3527,7 +3495,7 @@ When no name is given, the attached player is used for checking. Returns true or false (1 or 0) when the player is chatting/vending or not. Example(s): -if (checkVending("Aaron")) mes "Aaron is currently vending!"; +if (checkVending("Aaron")) mes "Aaron is currently vending!"; //This will check if Aaron is vending, and if so, put a message in front //of the attached player saying Aaron is vending. @@ -4035,7 +4003,7 @@ 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 eAthena installation that +example, there is a Stylist script inside the default rAthena installation that you can look at, this may help you create a Stylist of your own: 'custom\dye.txt' @@ -4379,7 +4347,7 @@ target cursor is shown. --------------------------------------- -*produce <item level>{,<itemid>}; +*produce <item level>; This command will open a crafting window on the client connected to the invoking character. The 'item level' is a number which determines what kind of a crafting @@ -4397,10 +4365,6 @@ Valid item levels are: 22 - Alchemist's Potions, Holy Water, Assassin Cross's Deadly Poison 23 - Elemental Converters -Supplying <itemid> currently (and for probably will only) ever be used by -the Rune Knight runestones, to create other runestones and affect the -success rate. Using items lower than 12734 or higher 12738 will have no effect. - --------------------------------------- *cooking <dish level>; @@ -5719,8 +5683,9 @@ is bought or sold by a player. In the OnBuyItem, two arrays are set (@bought_nameid and @bought_quantity), which hold information about the name id (item id) sold and the amount sold of it. Same goes for the OnSellItem label, only the variables are named different -(@sold_nameid and @sold_quantity). An example on a shop comes with eAthena, and -can be found in the doc/sample/npc_dynamic_shop.txt file. +(@sold_nameid, @sold_quantity, @sold_refine, @sold_attribute, @sold_identify, +@sold_card1, @sold_card2, @sold_card3, @sold_card4). An example on a shop comes +with rAthena, and can be found in the doc/sample/npc_dynamic_shop.txt file. This example shows how to use the labels and their set variables to create a dynamic shop. @@ -5854,7 +5819,7 @@ characters are present in the room to mess up the script. The 'enablearena'/'disablearena' commands are just aliases with no parameter. These are supposedly left here for compatibility with official server scripts, -but no eathena script uses these at the moment. +but no rAthena script uses these at the moment. --------------------------------------- @@ -6065,7 +6030,7 @@ returns a guild id: --------------------------------------- -*guardian("<map name>",<x>,<y>,"<name to show>",<mob id>,<amount>{,"<event label>"}{,<guardian index>}) +*guardian "<map name>",<x>,<y>,"<name to show>",<mob id>{,"<event label>"{,<guardian index>}}; This command is roughly equivalent to 'monster', but is meant to be used with castle guardian monsters and will only work with them. It will set the guardian @@ -6079,7 +6044,7 @@ Temporary guardians are not saved with the castle and can't be accessed by guard --------------------------------------- -*guardianinfo("<map name>", <guardian number>, <type>) +*guardianinfo("<map name>", <guardian number>, <type>); This function will return various info about the specified guardian, or -1 if it fails for some reason. It is primarily used in the castle manager NPC. @@ -6610,6 +6575,14 @@ Example(s): --------------------------------------- +*getstrlen("<string>") + +This function will return the length of the string given as an argument. It is +useful to check if anything input by the player exceeds name length limits and +other length limits and asking them to try to input something else. + +--------------------------------------- + *charisalpha("<string>",<position>) This function will return 1 if the character number Position in the given string @@ -6618,6 +6591,193 @@ The first letter is position 0. --------------------------------------- +*charat(<string>,<index>) + + Returns char at specified index. If index is out of range, + returns empty string. + + Example: + + charat("This is a string", 10); //returns "s" + +--------------------------------------- + +*setchar(<string>,<char>,<index>) + + Returns the original string with the char at the specified + index set to the specified char. If index out of range, the + original string will be returned. + Only the 1st char in the <char> parameter will be used. + + Example: + + setchar("Cat", "B", 0); //returns "Bat" + +--------------------------------------- + +*insertchar(<string>,<char>,<index>) + + Returns the original string with the specified char inserted + at the specified index. If index is out of range, the char + will be inserted on the end of the string that it is closest. + Only the 1st char in the <char> parameter will be used. + + Example: + + setchar("laughter", "s", 0); //returns "slaughter" + +--------------------------------------- + +*delchar(<string>,<index>) + + Returns the original string with the char at the specified index + removed. If index is out of range, original string will be returned. + + Example: + + delchar("Diet", 3); //returns "Die" + +--------------------------------------- + +*strtoupper(<string>) +*strtolower(<string>) + + Returns the specified string in it's uppercase/lowercase form. + All non-alpha characters will be preserved + + Example: + + strtoupper("The duck is blue!!"); //returns "THE DUCK IS BLUE!!" + +--------------------------------------- + +*charisupper(<string>,<index>) +*charislower(<string>,<index>) + + Returns 1 if character at specified index of specified string is + uppercase/lowercase. Otherwise, 0. Characters not of the alphabelt + will return 0. + + Example: + + charisupper("eAthena", 1); //returns 1 + +--------------------------------------- + +*substr(<string>,<start_index>,<end_index>) + + Returns the sub-string of the specified string inclusively between + the set indexes. + If indexes are out of range, or the start index is after the end + index, an empty string will be returned. + + Example: + + substr("foobar", 3, 5); //returns "bar" + +--------------------------------------- + +*explode(<dest_array>,<string>,<delimiter>) + + Breaks a string up into substrings based on the specified delimiter. + Substrings will be stored within the specified string array. + Only the 1st char of the delimiter parameter will be used. + If an empty string is passed as a delimiter, the string will be placed + in the array in it's original form. + + Example: + + explode(.@my_array$, "Explode:Test:1965:red:PIE", ":"); + //.@my_array$ contents will be... + //.@my_array$[0]: "Explode" + //.@my_array$[1]: "Test" + //.@my_array$[2]: "1965" + //.@my_array$[3]: "red" + //.@my_array$[4]: "PIE" + + +--------------------------------------- + +*implode(<string_array>{,<glue>}) + + Combines all substrings within the specified string array into a single string. + If the glue parameter is specified, it will be inserted inbetween each substring. + + Example: + setarray .@my_array$[0], "This", "is", "a", "test"; + implode(.@my_array$, " "); //returns "This is a test" + +--------------------------------------- + +*sprintf(<format>[,param[,param[,...]]]) [Mirei] + + C style sprintf. The resulting string is returned same as in PHP. All C format + specifiers are supported except %n. More info: sprintf @ www.cplusplus.com. + The number of params is only limited by eA's script engine. + + See thread: http://www.eathena.ws/board/index.php?showtopic=190410 + + Example: + .@format$ = 'The %s contains %d monkeys'; + dispbottom(sprintf(.@format$, "zoo", 5)); //prints "The zoo contains 5 monkeys" + dispbottom(sprintf(.@format$, "barrel", 82)); //prints "The barrel contains 82 monkeys" + +--------------------------------------- + +*sscanf(<string>,<format>[,param[,param[,...]]]) [Mirei] + + C style sscanf. All C format specifiers are supported. + More info: sscanf @ www.cplusplus.com. The number of params is only limited + by eA's script engine. + + See thread: http://www.eathena.ws/board/index.php?showtopic=191157 + + Example: + sscanf("This is a test: 42 foobar", "This is a test: %d %s", .@num, .@str$); + dispbottom(.@num + " " + .@str$); //prints "42 foobar" + +--------------------------------------- + +*strpos(<haystack>,<needle>{,<offset>}) + + PHP style strpos. Finds a substring (needle) within a string (haystack). + The offset parameter indicates the index of the string to start searching. + Returns index of substring on successful search, else -1. + Comparison is case sensitive. + + Example: + strpos("foobar", "bar", 0); //returns 3 + strpos("foobarfoo", "foo", 0); //returns 0 + strpos("foobarfoo", "foo", 1); //returns 6 + +--------------------------------------- + +*replacestr(<input>, <search>, <replace>{, <usecase>{, <count>}}) + + Replaces all instances of a search string in the input with the specified + replacement string. By default is case sensitive unless <usecase> is set + to 0. If specified it will only replace as many instances as specified + in the count parameter. + + Example: + replacestr("testing tester", "test", "dash"); //returns "dashing dasher" + replacestr("Donkey", "don", "mon", 0); //returns "monkey" + replacestr("test test test test test", "yay", 0, 3); //returns "yay yay yay test test" + +--------------------------------------- + +*countstr(<input>, <search>{, <usecase>}) + + Counts all instances of a search string in the input. By default is case + sensitive unless <usecase> is set to 0. + + Example: + countstr("test test test Test", "test"); //returns 3 + countstr("cake Cake", "Cake", 0); //returns 2 + + +--------------------------------------- + *setfont <font> This command sets the current RO client interface font to one of the @@ -6969,6 +7129,8 @@ Parameter <alive timeout> specifies the total amount of time the instance will exist. Parameter <idle timeout> specifies how long players have, when they are outside of the instance, until it is destroyed. +Both timeout values are in seconds. + --------------------------------------- ========================= |