diff options
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 485 |
1 files changed, 418 insertions, 67 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index c0fc8ce40..a4d079d5d 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -207,7 +207,7 @@ Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter' ** Define a warp point -<from map name>,<fromX>,<fromY>,<facing>%TAB%warp%TAB%<warp name>%TAB%<spanx>,<spany>,<to map name>,<toX>,<toY> +<from map name>,<fromX>,<fromY>{,<facing>}%TAB%warp%TAB%<warp name>%TAB%<spanx>,<spany>,<to map name>,<toX>,<toY> This will define a warp NPC that will warp a player between maps, and while most arguments of that are obvious, some deserve special mention. @@ -299,7 +299,7 @@ items here. The layout used to define sale items still count, and ** Define an warp/shop/cashshop/NPC duplicate. -warp: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany> +warp: <map name>,<x>,<y>{,<facing>}%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany> shop/cashshop/npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id> shop/cashshop/npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id> npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY> @@ -414,7 +414,10 @@ Variables The meat of every programming language is variables - places where you store data. -In Hercules scripting language, variable names are not case sensitive. +In Hercules scripting language, variable names are case sensitive. Even though +at the current time the script engine accepts them even with the incorrect +case, it is not advised to rely on this behavior, as it may change at any +time. Variables are divided into and uniquely identified by the combination of: prefix - determines the scope and extent (or lifetime) of the variable @@ -575,6 +578,29 @@ Operators section described below. All operators listed there may be placed in-front of the '=' sign when modifying variables to perform the action as required. +Increment and decrement operators are also provided, for your convenience. +Pre-increment and pre-decrement operators: + + ++@x; // same as @x = @x + 1 + --@x; // same as @x = @x - 1 + +Post-increment and post-decrement operators: + + @x++; // similar to @x = @x + 1 + @x--; // similar to @x = @x - 1 + +The difference between pre- and post- increment/decrement operators is that, +when used in an expression, the pre- ones will be executed before evaluating +the expression, while the post- ones will be executed after. For example: + + @x = 1; + @y = ++@x; // After this line is executed, both @y and @x will be 2 + @x = 1; + @y = @x++; // After this line is executed, @y will be 1, @x will be 2 + +Note: The pre-increment/pre-decrement operators are, by design, faster (or at +least not slower) than their respective post- equivalent. + Note: !! Currently the scripting engine does not support directly copying array @@ -611,8 +637,8 @@ even a value from an another array) to get at an array value: This will make @arrayofnumbers[100] equal to 10. -Notice that index numbering always starts with 0. Arrays cannot hold more -than 128 variables (so the last one can't have a number higher than 127). +Notice that index numbering always starts with 0. Arrays can hold over +2 billion variables. And array indexes probably can't be negative. Nobody tested what happens when you try to get a negatively numbered variable from an array, but it's @@ -851,6 +877,74 @@ and are the following: mentioning that ?: has low priority and has to be enclosed with parenthesis in most (if not all) cases. +Operator Precedence and Associativity + +Operator precedence and associativity work more or less like they do in +mathematics. The rules can be summarized with the following table: + +Precedence | Description | Associativity +--------------------------------------------------------------------------- +1 (highest) | [] Array subscripting | None +--------------------------------------------------------------------------- +2 | ++ Increment | None + | -- Decrement | +--------------------------------------------------------------------------- +2 | - Unary minus | Right to left + | ! Logical NOT | + | ~ Bitwise NOT (One's Complement) | +--------------------------------------------------------------------------- +3 | * Multiplication | Left to right + | / Division | + | % Modulo (remainder) | +--------------------------------------------------------------------------- +4 | + Addition | Left to right + | - Subtraction | +--------------------------------------------------------------------------- +5 | << Bitwise left shift | Left to right + | >> Bitwise right shift | +--------------------------------------------------------------------------- +6 | < Less than | Left to right + | <= Less than or equal to | + | > Greater than | + | >= Greater than or equal to | +--------------------------------------------------------------------------- +7 | == Equal to | Left to right + | != Not equal to | +--------------------------------------------------------------------------- +8 | & Bitwise AND | Left to right +--------------------------------------------------------------------------- +9 | ^ Bitwise XOR (exclusive or) | Left to right +--------------------------------------------------------------------------- +10 | | Bitwise OR (inclusive or) | Left to right +--------------------------------------------------------------------------- +11 | && Logical AND | Left to right +--------------------------------------------------------------------------- +12 | || Logical OR | Left to right +--------------------------------------------------------------------------- +13 | ?: Ternary conditional | Right to left +--------------------------------------------------------------------------- +14 | = Direct assignment | Right to left +(lowest) | += Assignment by sum | + | -= Assignment by difference | + | *= Assignment by product | + | /= Assignment by quotient | + | %= Assignment by remainder | + | <<= Assignment by bitwise left shift | + | >>= Assignment by bitwise right shift | + | &= Assignment by bitwise AND | + | ^= Assignment by bitwise XOR | + | |= Assignment by bitwise OR | + +Operator precedence means some operators are evaluated before others. For +example, in 2 + 4 * 5 , the multiplication has higher precedence so 4 * 5 is +evaluated first yielding 2 + 20 == 22 and not 6 * 5 == 30 . + +Operator associativity defines what happens if a sequence of the same +operators is used one after another: whether the evaluator will evaluate the +left operations first or the right. For example, in 8 - 4 - 2 , subtraction is +left associative so the expression is evaluated left to right. 8 - 4 is +evaluated first making the expression 4 - 2 == 2 and not 8 - 2 == 6 . + Labels ------ @@ -1006,6 +1100,10 @@ multiple commands on one line if you properly terminate them with a ';', but it's better if you don't, since it is not certain just whether the scripting engine will behave nicely if you do. +Please note that command and function names are case sensitive. Even though at +the current time the script engine accepts them with the incorrect case, it is +not advised to rely on this behavior, as it may change at any time. + ------------------------- @@ -1022,6 +1120,7 @@ From here on, we will have the commands sorted as follow: 9.- Battleground commands. 10.- Mercenary commands. 11.- Queue commands. +12.- NPC Trader commands ===================== @@ -2550,6 +2649,13 @@ EQI_HEAD_LOW (10) - Lower Headgear (beards, some masks) EQI_COSTUME_HEAD_LOW (11) - Lower Costume Headgear EQI_COSTUME_HEAD_MID (12) - Middle Costume Headgear EQI_COSTUME_HEAD_TOP (13) - Upper Costume Headgear +EQI_COSTUME_GARMENT (14) - Costume Garment +EQI_SHADOW_ARMOR (15) - Shadow Armor +EQI_SHADOW_WEAPON (16) - Shadow Weapon +EQI_SHADOW_SHIELD (17) - Shadow Shield +EQI_SHADOW_SHOES (18) - Shadow Shoes +EQI_SHADOW_ACC_R (19) - Shadow Accessory 2 +EQI_SHADOW_ACC_L (20) - Shadow Accessory 1 Notice that a few items occupy several equipment slots, and if the character is wearing such an item, 'getequipid' will return it's ID number @@ -2781,6 +2887,7 @@ recreate these items perfectly if they are destroyed. Here's what you get: @inventorylist_expire[] - expire time (Unix time stamp). 0 means never expires. @inventorylist_count - the number of items in these lists. +@inventorylist_bound - whether it is an account bounded item or not. This could be handy to save/restore a character's inventory, since no other command returns such a complete set of data, and could also be the @@ -3320,6 +3427,39 @@ Check sample in doc/sample/getmonsterinfo.txt --------------------------------------- +*addmonsterdrop(<mob id or name>, <item id>, <rate>) + +This command will temporarily add a drop to an existing monster. If the +monster already drops the specified item, its drop rate will be updated to the +given value. + +Both the monster and the item must be valid. Acceptable values for the drop +rate are in the range [1:10000]. + +Return value will be 1 in case of success (the item was added or its drop rate +was updated), and 0 otherwise (there were no free item drop slots). + +Example: + // Add Poring Doll (741) to the Poring's (1002) drops, with 1% (100) rate + addmonsterdrop(1002, 741, 100); + +--------------------------------------- + +*delmonsterdrop(<mob id or name>, <item id>) + +This command will temporarily remove a drop from an existing monster. + +Both the monster and the item must be valid. + +Return value will be 1 in case of success (the item was removed), and 0 +otherwise (the monster didn't have the specified item in its drop list). + +Example: + // Remove Jellopy (909) from the Poring's (1002) drops + delmonsterdrop(1002, 909); + +--------------------------------------- + *getmobdrops(<mob id>) This command will find all drops of the specified mob and return the item @@ -4416,6 +4556,51 @@ two eggs, and may hatch from either, although, I'm not sure what kind of a mess will this really cause. --------------------------------------- +*getitembound <item id>,<amount>,<bound type>{,<account ID>}; +*getitembound "<item name>",<amount>,<bound type>{,<account ID>}; + +This command behaves identically to 'getitem', but the items created will be +bound to the target character as specified by the bound type. All items created +in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in +some cases cannot be traded or stored. + +Valid bound types are: + 1 - Account Bound + 2 - Guild Bound + 3 - Party Bound + 4 - Character Bound + +--------------------------------------- + +*getitembound2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>; +*getitembound2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>; + +This command behaves identically to 'getitem2', but the items created will be +bound to the target character as specified by the bound type. All items created +in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in +some cases cannot be traded or stored. + +For a list of bound types see 'getitembound'. + +--------------------------------------- + +*countbound({<bound type>}) + +This function will return the number of bounded items in the character's +inventory, and sets an array @bound_items[] containing all item IDs of the +counted items. If a bound type is specified, only those items will be counted. + +For a list of bound types see 'getitembound'. + +Example: + mes "You currently have "+countbound()+" bounded items."; + next; + mes "The list of bounded items include:"; + for(set .@i,0; .@i<getarraysize(@bound_items); set .@i,.@i+1) + mes getitemname(@bound_items[.@i]); + close; + +--------------------------------------- *getnameditem <item id>,<character name|character ID>; *getnameditem "<item name>",<character name|character ID>; @@ -4754,21 +4939,17 @@ the command will end silently. --------------------------------------- -*successrefitem <equipment slot>; +*successrefitem <equipment slot>{,<upgrade_count>}; This command will refine an item in the specified equipment slot of the -invoking character by +1. For a list of equipment slots see 'getequipid'. -This command will not only add the +1, but also display a 'refine success' +invoking character by +1 (unless <upgrade_count> is specified). +For a list of equipment slots see 'getequipid'. +This command will also display a 'refine success' effect on the character and put appropriate messages into their chat window. It will also give the character fame points if a weapon reached +10 this way, even though these will only take effect for blacksmith who will later forge a weapon. -The official scripts seems to use the 'successrefitem' command as a -function instead: 'successrefitem(<number>)' but it returns nothing on the -stack. This is since jAthena, so probably nobody knows for sure why is it -so. - --------------------------------------- *failedrefitem <equipment slot>; @@ -4816,7 +4997,7 @@ like storage or cart. --------------------------------------- *equip <item id>; -*autoEquip <item id>,<option>; +*autoequip <item id>,<option>; These commands are to equip a equipment on the attached character. The equip function will equip the item ID given when the player has this @@ -5655,20 +5836,46 @@ above 91000 intimacy with its owner. --------------------------------------- +*gethominfo(<type>) + +This function works as a direct counterpart of 'getpetinfo': + 0 - Homunculus unique ID + 1 - Homunculus Class + 2 - Name + 3 - Friendly level (intimacy score). 100000 is full loyalty. + 4 - Hungry level. 100 is completely full. + 5 - Rename flag. 0 means this homunculus has not been named yet. + 6 - Homunculus level + +--------------------------------------- + +*morphembryo; + +This command will try to put the invoking player's Homunculus in an +uncallable state, required for mutation into a Homunculus S. The player +will also receive a Strange Embryo (ID 6415) in their inventory if +successful, which is deleted upon mutation. + +The command will fail if the invoking player does not have an evolved +Homunculus at level 99 or above. The /swt emotion is shown upon failure. + +Returns 1 upon success and 0 for all failures. + +--------------------------------------- + *hommutate {<ID>}; -This command will try to mutate the invoking player's Homunculus into a -Homunculus S. The Strange Embryo (ID 6415) is deleted upon success. +This command will try to mutate the invoking player's Homunculus into +a Homunculus S. The Strange Embryo (ID 6415) is deleted upon success. -The command will fail if the invoking player does not have an evolved -Homunculus at level 99 or above, if it is not in the embryo state (from -the 'morphembryo' command), or if the invoking player does not possess a -Strange Embryo. The /swt emotion is shown upon failure. +The command will fail if the invoking player does not have an evolved +Homunculus at level 99 or above, if it is not in the embryo state +(from the 'morphembryo' command), or if the invoking player does not +possess a Strange Embryo. The /swt emotion is shown upon failure. -If the optional parameter <ID> is set, the invoking player's Homunculus -will change into the specified Homunculus ID. Otherwise, a random -Homunculus S will be chosen. See 'db/homunculus_db.txt' for a full list of -IDs. +If the optional parameter <ID> is set, the invoking player's Homunculus +will change into the specified Homunculus ID. Otherwise, a random Homunculus S +will be chosen. See 'db/homunculus_db.txt' for a full list of IDs. Returns 1 upon success and 0 for all failures. @@ -5685,19 +5892,6 @@ and will return the following values: --------------------------------------- -*gethominfo(<type>) - -This function works as a direct counterpart of 'getpetinfo': - 0 - Homunculus unique ID - 1 - Homunculus Class - 2 - Name - 3 - Friendly level (intimacy score). 100000 is full loyalty. - 4 - Hungry level. 100 is completely full. - 5 - Rename flag. 0 means this homunculus has not been named yet. - 6 - Homunculus level - ---------------------------------------- - *unitwalk <GID>,<x>,<y>; *unitwalk <GID>,<mapid>; @@ -6658,10 +6852,11 @@ Example: This command will send the message to the server console (map-server window). It will not be displayed anywhere else. - +// // Displays "NAME has clicked me!" in the map-server window. debugmes strcharinfo(0)+" has clicked me!"; - + + // debugmes "\033[38D\033[K ==Message== \n"; // enable colour code. --------------------------------------- *logmes "<message>"; @@ -6843,8 +7038,8 @@ You can add your own effects this way, naturally. --------------------------------------- -*playBGM "<BGM filename>"; -*playBGMall "<BGM filename>"{,"<map name>"{,<x0>,<y0>,<x1>,<y1>}}; +*playbgm "<BGM filename>"; +*playbgmall "<BGM filename>"{,"<map name>"{,<x0>,<y0>,<x1>,<y1>}}; These two commands will play a Background Music to either the invoking character only ('playBGM') or multiple characters ('playBGMall'). @@ -7161,20 +7356,31 @@ setitemscript 2637,""; --------------------------------------- -*atoi ("<string>") -*axtoi ("<string>") +*atoi("<string>") +*axtoi("<string>") +*strtol("string", base) These commands are used to convert strings to numbers. 'atoi' will interpret given string as a decimal number (base 10), while 'axtoi' -interprets strings as hexadecimal numbers (base 16). +interprets strings as hexadecimal numbers (base 16). 'strtol' lets +the user specify a base (valid range is between 2 and 36 inclusive, +or the special value0, which means auto-detection). -Hexadecimal number set: {0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F} +The atoi and strtol functions conform to the C functions with the same +names, and axtoi is the same as strtol, with a base of 16. Results are +clamped to signed 32 bit int range (INT_MIN ~ INT_MAX) Example: -set @var, atoi("11"); // Sets @var to 11 -set @var, axtoi("FF"); // Sets @var to 255 -mes axtoi("11"); // Displays 17 (1 = 1, 10 = 16) +.@var = atoi("11"); // Sets .@var to 11 +.@var = axtoi("FF"); // Sets .@var to 255 +mes axtoi("11"); // Displays 17 (1 = 1, 10 = 16) +.@var = strtol("11", 10); // Sets .@var to 11 (11 base 10) +.@var = strtol("11", 16); // Sets .@var to 17 (11 base 16) +.@var = strtol("11", 0); // Sets .@var to 11 (11 base 10, auto-detected) +.@var = strtol("0x11", 0); // Sets .@var to 17 (11 base 16, auto-detected because of the "0x" prefix) +.@var = strtol("011", 0); // Sets .@var to 9 (11 base 8, auto-detected because of the "0" prefix) +.@var = strtol("11", 2); // Sets .@var to 3 (binary 11) --------------------------------------- @@ -7380,7 +7586,7 @@ 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" + replacestr("test test test test test", "test", "yay", 0, 3); //returns "yay yay yay test test" --------------------------------------- @@ -7762,6 +7968,14 @@ Returns name of the instanced map on success, otherwise an empty string. --------------------------------------- +*has_instance2("<map name>"); + +Same as has_instance, with exception it returns the instance id of the map, +as long as the user is assigned to a instance containing that map. +It will return -1 upon failure, valid instance ids are >= 0. + +--------------------------------------- + *instance_id(); Retrieves the instance id of the script it is being run on. @@ -7814,16 +8028,82 @@ if (instance_check_party(getcharid(1),2,2,149)) { } --------------------------------------- +*instance_set_respawn(<map_name>,<x>,<y>{,<instance_id>}); + +Updates the 'reload spawn' position of a instance, +that is where players in the instance are sent to upon @reloadscript, +uses the npc instance (if any) when instance_id is not provided, +handy to update a instance's progress so that when/if @reloadscript happens +the damage to the players progress is reduced. +It is most effective when used with instance variables (which are @reloadscript persistent) + +If a player warps into a instance before this command has been used, +it will use the player's warp destination as the initial respawn point, +it can of course be modified by using this script command at any point. + +--------------------------------------- +*instance_mapname("<map name>"{,<instance id>}) + +Returns the unique name of the instanced map. If no instance ID is specified, +the instance the script is attached to is used. If the script is not attached to +an instance, the instance of the currently attached player's party is used. If +that fails, the command returns an empty string instead. ========================= |8.- Quest Log commands.| ========================= --------------------------------------- +*questinfo <Quest ID>, <Icon> {, <Map Mark Color>{, <Job Class>}}; + +This is esentially a combination of checkquest and showevent. Use this only +in an OnInit label. For the Quest ID, specify the quest ID that you want +checked if it has been started yet. + +For Icon, use one of the following: + +No Icon : QTYPE_NONE +! Quest Icon : QTYPE_QUEST +? Quest Icon : QTYPE_QUEST2 +! Job Icon : QTYPE_JOB +? Job Icon : QTYPE_JOB2 +! Event Icon : QTYPE_EVENT +? Event Icon : QTYPE_EVENT2 +Warg : QTYPE_WARG +Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410) + +Map Mark Color, when used, creates a mark in the user's mini map on the position of the NPC, +the available color values are: + +0 - No Marker +1 - Yellow Marker +2 - Green Marker +3 - Purple Marker + +When a user shows up on a map, each NPC is checked for questinfo that has been set. +If questinfo is present, it will check if the quest has been started, if it has not, the bubble will appear. + +Optionally, you can also specify a Job Class if the quest bubble should only appear for a certain class. + +Example +izlude,100,100,4 script Test 844,{ + mes "[Test]"; + mes "Hello World."; + close; + + OnInit: + questinfo 1001, QTYPE_QUEST, 0, Job_Novice; + end; +} + +--------------------------------------- + *setquest <ID>; Place quest of <ID> in the users quest log, the state of which is "active". +If *questinfo is set, and the same ID is specified here, the icon will be cleared when the quest is set. + --------------------------------------- *completequest <ID>; @@ -7871,27 +8151,30 @@ If parameter "HUNTING" is supplied: --------------------------------------- -*showevent <state>, <color>; +*showevent <icon>{,<mark color>} + +Show an emotion on top of a NPC, and optionally, +a colored mark in the mini-map like "viewpoint". +This is used to indicate that a NPC has a quest or an event to +a certain player. -Show a colored mark in the mini-map like "viewpoint" and an emotion on top -of a NPC. This is used to indicate that a NPC has a quest or an event to -certain player/s. +Available Icons: -state can be: - 0 = disable ( Used to disable and remove the mark and the emotion from - the NPC. ) - 1 = exclamation emotion ( Used to show an important quest event to - certain player. ) - 2 = interrogation emotion ( Used to show an non-important quest event - to certain player. ) -Other value may cause client crashes. +Remove Icon : QTYPE_NONE +! Quest Icon : QTYPE_QUEST +? Quest Icon : QTYPE_QUEST2 +! Job Icon : QTYPE_JOB +? Job Icon : QTYPE_JOB2 +! Event Icon : QTYPE_EVENT +? Event Icon : QTYPE_EVENT2 +Warg : QTYPE_WARG +Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410) -color can be: - 0 = yellow "Quest" - 1 = orange "Job" - 2 = green "Event" - 3 = an MVP flag -Other values show a transparent mark in the mini-map. +Mark Color: +0 - No Mark +1 - Yellow Mark +2 - Green Mark +3 - Purple Mark ---------------------------------------- @@ -8205,3 +8488,71 @@ Deletes a queue iterator from memory and returns 1 when it fails, otherwise 0 is returned. --------------------------------------- + +====================== +|12.- NPC Trader Commands.| +====================== +--------------------------------------- +Commands that control NPC Trader Shops +See /doc/sample/npc_trader_sample.txt + +--------------------------------------- + +*openshop({NPC_Name}); + +opens the trader shop from the currently-attached npc unless, +when the optional NPC_Name param is used. + +--------------------------------------- + +*sellitem <Item_ID>{,<price>{,<qty>}}; + +adds (or modifies) <Item_ID> data to the shop, +when <price> is not provided (or when it is -1) itemdb default is used. +qty is only necessary for NST_MARKET trader types. + +when <Item_ID> is already in the shop, +the previous data (price/qty), is overwritten with the new. + +--------------------------------------- + +*stopselling <Item_ID>; + +attempts to remove <Item_ID> from the current shop list. + +--------------------------------------- + +*setcurrency <Val1>{,<Val2>}; + +updates the currently attached player shop funds, +to be used within a "OnCountFunds" event of a NST_CUSTOM trader type. + +<Val1> is the value used in the *Cash* Points field +<Val2> is the value used in the Kafra Points field + +--------------------------------------- + +*tradertype(<Type>); + +Modifies the npc trader type, item list is cleared upon modifiying the value. +By default, all npcs staart with tradertype(NST_ZENY); + +- NST_ZENY (0) Normal Zeny Shop +- NST_CASH (1) Normal Cash Shop +- NST_MARKET (2) Normal NPC Market Shop (where items have limited availability and need to be refurbished) +- NST_CUSTOM (3) Custom Shop (any currency, item/var/etca, check sample) + +--------------------------------------- + +*purchaseok(); + +Signs that the transaction (on a NST_CUSTOM trader) has been successful, +to be used within a "OnPayFunds" event of a NST_CUSTOM trader. + +--------------------------------------- + +*shopcount(<Item_ID>); + +Returns the amount of still-available <Item_ID> in the shop (on a NST_MARKET trader). + +--------------------------------------- |