diff options
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 3206 |
1 files changed, 1873 insertions, 1333 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 0441d385a..d2a3d80eb 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -1,4 +1,4 @@ -//===== Hercules Documentation =============================== +//===== Hercules Documentation =============================== //= Hercules Script Commands //===== By: ================================================== //= Hercules Dev Team @@ -67,8 +67,7 @@ expression, like a bunch of functions or operators returning a value, in (round brackets) instead of most numbers. Round brackets will not always be required, but they're often a good idea. -Wherever you refer to a map name, it's always 'mapname' or 'mapname.gat' -(Please, don't use .gat suffix anymore. It's useless.) +Wherever you refer to a map, use 'mapname' instead of 'mapname.gat'. Script loading structure @@ -145,8 +144,8 @@ for a better explanation, see 'setmapflag'. <map name>,<x>,<y>,<xs>,<ys>%TAB%monster%TAB%<monster name>%TAB%<mob id>,<amount>,<delay1>,<delay2>,<event>{,<mob size>,<mob ai>} -Map name is the name of the map the monsters will spawn on. x,y are the -coordinates where the mob should spawn. If xs and ys are non-zero, they +Map name is the name of the map the monsters will spawn on. X,Y are the +coordinates where the mob should spawn. If X's and Y's are non-zero, they specify the 'radius' of a spawn-rectangle area centered at x,y. Putting zeros instead of these coordinates will spawn the monsters randomly. Note this is only the initial spawn zone, as mobs random-walk, they are free to @@ -183,8 +182,8 @@ There are two optional fields for monster size and AI. Size can be 0 (medium), 1 (small), or 2 (big). AI can be 0 (default), 1 (attack/friendly), 2 (sphere), 3 (flora), or 4 (zanzou). -Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able -to be detected on the map with the SC_CASH_BOSS_ALARM status (used by Convex Mirror, item ID# 12214). +Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able to be +detected on the map with the SC_CASH_BOSS_ALARM status (used by Convex Mirror, item ID# 12214). ** NPC names @@ -208,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. @@ -244,9 +243,11 @@ and to make it look southeast it's facing 5.) Sprite id is the sprite number used to display this particular NPC. For a full list of sprite id numbers see http://kalen.s79.xrea.com/npc/npce.shtml You may also use a monster's ID number instead to display a monster sprite -for this NPC. It is possible to use a job sprite as well, but you must -first define it as a monster sprite in 'mob_avail.txt', a full description -on how to do this is not in the scope of this manual. +for this NPC, in npcs that have view ids of mobs it's encouraged to use +OnTouch events with a 2,2 range and with an 'end' after the header to avoid +bugs (for more info on why see npc_click@map/npc.c). It is possible to use a job +sprite as well, but you must first define it as a monster sprite in 'mob_avail.txt', +a full description on how to do this is not in the scope of this manual. A '-1' sprite id will make the NPC invisible (and unclickable). A '111' sprite id will make an NPC which does not have a sprite, but is still clickable, which is useful if you want to make a clickable object of @@ -293,14 +294,37 @@ create differing prices for items in different shops. You can alternatively use "cashshop" in place of "shop" to use the Cash Shop interface, allowing you to buy items with special points (Currently -stored as account vars in global_reg #CASHPOINTS and #KAFRAPOINTS). This +stored as account vars in #CASHPOINTS and #KAFRAPOINTS). This type of shop will not allow you to sell items at it, you may only purchase items here. The layout used to define sale items still count, and "<price>" refers to how many points will be spent purchasing the them. +** Define a trader NPC +<map name>,<x>,<y>,<facing>%TAB%trader%TAB%<NPC Name>%TAB%<sprite id>,{<code>} +-%TAB%trader%TAB%<NPC Name>%TAB%-1,{<code>} + +All the standards that are valid to script objects are also valid for trader objects +(see ** Define an NPC object for more information). +This will define a trader NPC, which can cause a shop, cashshop or market window +to come up when clicked or called by other means. Unlike shop/cashshop NPCs this +type will run a code and can change the items that are being sold over time without +other NPC objects. +The types that a trader object can have are the following: +- NST_ZENY (0) Normal Zeny Shop (shop) +- NST_CASH (1) Normal Cash Shop (cashshop) +- 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) +Unless otherwise specified via *tradertype an trader object will be defined as +NST_ZENY. + +Note: NST_MARKET is only available with PACKETVER 20131223 or newer. +See '12 - NPC Trader-Related Commands' and /doc/sample/npc_trader_sample.txt for +more information regarding how to use this NPC type. + ** 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> @@ -405,7 +429,9 @@ are otherwise identical. Writing a number like '0x<hex digits>' will make it recognized as a hexadecimal value. Notice that 0x10 is equal to 16. Also notice that if you try to 'mes 0x10' it will print '16'. -This is not used much, but it pays to know about it. +Number values can't exceed the limits of an integer variable: Any number +greater than INT_MAX (2147483647) or smaller than INT_MIN (-2147483648) will +be capped to those values and will cause a warning to be reported. Variables --------- @@ -413,7 +439,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 @@ -434,14 +463,13 @@ temporary - They cease to exist when the server resets. Prefix: scope and extent nothing - A permanent variable attached to the character, the default - variable type. They are stored with all the account data in the - `global_reg_value` table using type 3. + variable type. "@" - A temporary variable attached to the character. They disappear when the character logs out. "$" - A global permanent variable. They are stored in database table `mapreg`. "$@" - A global temporary variable. - Thhey are important for scripts which are called with no RID + They are important for scripts which are called with no RID attached, that is, not triggered by a specific character object. "." - A NPC variable. They exist in the NPC and disappear when the server restarts or @@ -450,19 +478,17 @@ nothing - A permanent variable attached to the character, the default .variables which are accessible from inside the function, however 'getvariableofnpc' does NOT work on function objects. ".@" - A scope variable. - They are unique to the instance and scope. Each instance has - its own scope that ends when the script ends. Calling a - function with 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). + They are unique to the character, script and scope. Each script + execution has its own scope that ends when the script ends. + Calling a function with callsub/callfunc starts a new scope, + returning from the function ends it. When a scope ends, its + 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. + each instance. "#" - A permanent local account variable. - They are stored in the 'global_reg_value' table using type 2. "##" - A permanent global account variable stored by the login server. - They are stored in the 'global_reg_value' table, using type 1. The only difference you will note from normal # variables is when you have multiple char-servers connected to the same login-server. The # variables are unique to each char-server, @@ -486,6 +512,8 @@ $@name$ - temporary global string variable .name$ - NPC string variable .@name - scope integer variable .@name$ - scope string variable + 'name - instance integer variable + 'name$ - instance string variable #name - permanent local account integer variable #name$ - permanent local account string variable ##name - permanent global account integer variable @@ -518,7 +546,9 @@ JobExp - Amount of job experience points. NextBaseExp - Amount of base experience points needed to reach next level. NextJobExp - Amount of job experience points needed to reach next level. Weight - Amount of weight the character currently carries. + Display as in Weight/10. MaxWeight - Maximum weight the character can carry. + Display as in MaxWeight/10. Sex - 0 if female, 1 if male. Class - Character's job. Upper - 0 if the character is normal class, 1 if advanced, 2 if baby. @@ -551,29 +581,53 @@ Variables can be accessed and assigned values directly without the use of the built-in 'set' function. This means that variables can be accessed and modified much like other programming languages. - @x = 100; - @x = @y = 100; + .@x = 100; + .@x = .@y = 100; Support for modifying variable values using 'set' is still supported (and required to exist for this method to work) so previous scripts will -continue working. +continue working. Its usage, though, is deprecated, and it should never be +used in new scripts unless there are special reasons to do so. When assigning values, all operator methods are supported which exist in the below 'Operators' section. For instance: - @x += 100; - @x -= 100; - @x *= 2; - @x /= 2; - @x %= 5; - @x >>= 2; - @x <<= 2; + .@x += 100; + .@x -= 100; + .@x *= 2; + .@x /= 2; + .@x %= 5; + .@x >>= 2; + .@x <<= 2; Will all work. For more information on available operators, see the 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 @@ -583,8 +637,10 @@ Note: Strings ------- -To include symbol '"' in a string you should use prefix '\"'. +Strings are enclosed in "double quotes". To include the literal double +quote symbol (") in a string you need to escape it with a blackslash: + .@string$ = "This string contains some \"double quote\" symbols"; Arrays ------ @@ -595,75 +651,61 @@ array with an 'array index', a number of a variable in that array: <variable name>[<array index>] +All variable types can be used as arrays. + Variables stored in this way, inside an array, are also called 'array elements'. Arrays are specifically useful for storing a set of similar -data (like several item IDs for example) and then looping through it. You +data (like several item IDs for example) and then looping through it. You can address any array variable as if it was a normal variable: - set @arrayofnumbers[0],1; + .@arrayofnumbers[0] = 1; -You can also do sneaky things like using a variable (or an expression, or -even a value from an another array) to get at an array value: +You can use a variable (or an expression, or even a value from an another +array) as array index: - set @x,100; - set @arrayofnumbers[@x],10; + .@x = 100; + .@arrayofnumbers[.@x] = 10; -This will make @arrayofnumbers[100] equal to 10. +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). +Index numbering always starts with 0 and arrays can hold over 2 billion +variables. As such, the (guaranteed) allowed values for indices are in the +range 0 ~ 2147483647. -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 -not going to be pretty. :) +If the array index is omitted, it defaults to zero. Writing +.@arrayofnumbers is perfectly equivalent to writing .@arrayofnumbers[0]. Arrays can naturally store strings: -@menulines$[0] is the 0th element of the @menulines$ array of strings. +.@menulines$[0] is the 0th element of the .@menulines$ array of strings. Notice the '$', normally denoting a string variable, before the square brackets that denotes an array index. -Resume of the allowed variable and array scopes ------- -- --- ------- -------- --- ----- ------ - -+==========+======+=======+ -|VarType | Norm | Array | -+==========+======+=======+ -|$Str$ | OK! | OK! | -+----------+------+-------+ -|$@Str$ | OK! | OK! | -+----------+------+-------+ -|@Str$ | OK! | OK! | -+----------+------+-------+ -|#Str$ | OK! | FAIL! | -+----------+------+-------+ -|Str$ | OK! | FAIL! | -+----------+------+-------+ -|$Int | OK! | OK! | -+----------+------+-------+ -|$@Int | OK! | OK! | -+----------+------+-------+ -|@Int | OK! | OK! | -+----------+------+-------+ -|#Int | OK! | FAIL! | -+----------+------+-------+ -|Int | OK! | FAIL! | -+----------+------+-------+ -|.Str$ | OK! | OK! | -+----------+------+-------+ -|.Int | OK! | OK! | -+----------+------+-------+ -|.@Str$ | OK! | OK! | -+----------+------+-------+ -|.@Int | OK! | OK! | -+----------+------+-------+ - Variable References ------------------- //##TODO - +Hard-coded constants +-------------------- +Most of the constants defined by the scripting engine can be found in +'db/const.txt' and have the same value independently of settings that +are core related, but there are constants that can be used to retrieve +core information that's set when the server is compiled. + +PACKETVER - Server packet version +MAX_LEVEL - Maximum level +MAX_STORAGE - Maximum storage items +MAX_GUILD_STORAGE - Maximum guild storage items +MAX_CART - Maximum cart items +MAX_INVENTORY - Maximum inventory items +MAX_ZENY - Maximum Zeny +MAX_BG_MEMBERS - Maximum BattleGround members +MAX_CHAT_USERS - Maximum Chat users + +Send targets and status options are also hard-coded and can be found +in src/map/script.c::script_hardcoded_constants or in functions that +currently use them. Operators --------- @@ -698,16 +740,22 @@ other, but you can not compare numbers to strings. > - True if the first value greater than the second value. < - True if the first value is less than the second value. != - True if the first value IS NOT equal to the second one. + ~= - True if the second value (as regular expression) matches the first + value. Both values must be strings. See the script function pcre_match + for more details and advanced features. + ~! - True if the second value (as regular expression) DOES NOT match the + first value. Both values must be strings. See script function pcre_match + for more details and advanced features. Examples: 1==1 is True. 1<2 is True while 1>2 is False. - @x>2 is True if @x is equal to 3. But it isn't true if @x is 2. + .@x>2 is True if .@x is equal to 3. But it isn't true if .@x is 2. -Only '==' and '!=' have been tested for comparing strings. Since there's -no way to code a seriously complex data structure in this language, trying -to sort strings by alphabet would be pointless anyway. +Only '==', '!=', '~=' and '~!' have been tested for comparing strings. Since +there's no way to code a seriously complex data structure in this language, +trying to sort strings by alphabet would be pointless anyway. Comparisons can be stacked in the same condition: @@ -728,10 +776,10 @@ Logical bitwise operators work only on numbers, and they are the following: In the other hand, Right shift moves the binary 1(s) of a number n positions to the right, which is the same as dividing by 2, n times. Example: - set b,2; - set a, b << 3; + b = 2; + a = b << 3; mes a; - set a, a >> 2; + a = a >> 2; mes a; The first mes command would display 16, which is the same as: 2 x (2 x 2 x 2) = 16. @@ -766,12 +814,12 @@ Logical bitwise operators work only on numbers, and they are the following: arguments, so in the example 1010 & 0010, only the 2^1 bit is active (1) in both. Resulting in the bit 0010, which is 2. - Basic example of creating and using a bit-mask: - set @options,2|4|16; // (note: this is the same as 2+4+16, or 22) - if (@options & 1) mes "Option 1 is activated"; - if (@options & 2) mes "Option 2 is activated"; - if (@options & 4) mes "Option 3 is activated"; - if (@options & 8) mes "Option 4 is activated"; - if (@options & 16) mes "Options 5 is activated"; + .@options = 2|4|16; // (note: this is the same as 2+4+16, or 22) + if (.@options & 1) mes "Option 1 is activated"; + if (.@options & 2) mes "Option 2 is activated"; + if (.@options & 4) mes "Option 3 is activated"; + if (.@options & 8) mes "Option 4 is activated"; + if (.@options & 16) mes "Option 5 is activated"; This would return the messages about option 2, 3 and 5 being shown (since we've set the 2,4 and 16 bit to 1). ^ - Xor. @@ -780,24 +828,22 @@ Logical bitwise operators work only on numbers, and they are the following: hand, it sets to 1 if they have different values in the said binary position. This is another way of setting and unsetting bits in bit-masks. - + Example: - First let's set the quests that are currently in progress: - set inProgress,1|8|16; // quest 1,8 and 16 are in progress + inProgress = 1|8|16; // quest 1,8 and 16 are in progress - After playing for a bit, the player starts another quest: if( inProgress&2 == 0 ){ - // this will set the bit for quest 2 (inProgress has that bit - // set to 0) - set inProgress,inProgress^2; + // this will set the bit for quest 2 (inProgress has that bit set to 0) + inProgress = inProgress^2; mes "Quest 2: find a newbie and be helpful to him for an hour."; close; } - After spending some time reading info on Xor's, the player finally completes quest 1: - if( inProgress&1 && isComplete ){ - // this will unset the bit for quest 1 (inProgress has that - // bit set to 1) - set inProgress,inProgress^1; + if( inProgress&1 && isComplete ) { + // this will unset the bit for quest 1 (inProgress has that bit set to 1) + inProgress = inProgress^1; mes "Quest 1 complete!! You unlocked the secrets of the Xor dynasty, use them wisely."; close; } @@ -810,7 +856,7 @@ operator, and are the following: it will become negative and vice versa. Example: - set .@myvar,10; + .@myvar = 10; mes "Negative 10 is "+(-.@myvar); ! - Logical Not. @@ -818,8 +864,7 @@ operator, and are the following: and false will become true. Example: - if(!callfunc("F_dosomething")) - { + if(!callfunc("F_dosomething")) { mes "Doing something failed."; close; } @@ -831,8 +876,8 @@ operator, and are the following: Example: - Ensure, that quest 2 is disabled, while keeping all other active, if they are. - set inProgress,inProgress&(~2); - // same as set inProgress,inProgress&0xfffffffd + inProgress = inProgress&(~2); + // same as set inProgress,inProgress&0xfffffffd Ternary operators take three expressions (numbers, strings or boolean), and are the following: @@ -850,6 +895,76 @@ 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 | + | ~= Regexp match | + | ~! Regexp non-match | +--------------------------------------------------------------------------- +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 ------ @@ -886,7 +1001,8 @@ OnInit will execute every time the scripts loading is complete, including when they are reloaded with @reloadscript command. OnInterIfInit will execute when the map server connects to a char server, OnInterIfInitOnce will only execute once and will not execute if the map server reconnects -to the char server later. +to the char server later. Note that all those events will be executed upon +scripts reloading. OnAgitStart: OnAgitEnd: @@ -957,6 +1073,21 @@ Only the special labels which are not associated with any script command are listed here. There are other kinds of labels which may be triggered in a similar manner, but they are described with their associated commands. +OnCountFunds: + +This special label is triggered when a player opens a trader NPC object that +is NST_CUSTOM. It is used to define different currency types to the trader via +*setcurrency. Should be used along with OnPayFunds, see /doc/sample/npc_trader_sample.txt +for more information. + +OnPayFunds: + +This special label is triggered when a purchase is made on a trader NPC object +that is NST_CUSTOM. Receives @price, total cost and @points, secondary input +field for cash windows. It is used to remove items that are set as currency. +Should be used along with OnCountFunds, see /doc/sample/npc_trader_sample.txt +for more information. + On<label name>: These special labels are used with Mob scripts mostly, and script commands @@ -1005,27 +1136,39 @@ 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. + ------------------------- -From here on, we will have the commands sorted as follow: +From here on, we will have the commands sorted as followed: -1.- Basic commands. -2.- Information-retrieving commands. -3.- Checking commands. -4.- Player-related commands. -5.- Mob / NPC -related commands. -6.- Other commands. -7.- Instance commands. -8.- Quest Log commands. -9.- Battleground commands. -10.- Mercenary commands. -11.- Queue commands. +1 - Basic Commands +2 - Information-Retrieving Commands + -- 2.1 - Item-Related Commands + -- 2.2 - Guild-Related Commands +3 - Checking Commands + -- 3.1 - Checking Item-Related Commands +4 - Player-Related Commands + -- 4.1 - Player Item-Related Commands + -- 4.2 - Guild-Related Commands + -- 4.3 - Marriage-Related Commands +5 - Mob / NPC Related commands + -- 5.1 - Time-Related Commands + -- 5.2 - Guild-Related Commands +6 - Other Commands +7 - Instance-Related Commands +8 - Quest Log Commands +9 - Battleground Commands +10 - Mercenary Commands +11 - Queue Commands +12 - NPC Trader Commands -===================== -|1.- Basic commands.| -===================== +--------------------------------------- +//===================================== +1 - Basic Commands +//===================================== --------------------------------------- *mes "<string>"{,"<string>"..."<string>"}; @@ -1064,6 +1207,19 @@ command, use the script command in the following format: This will display 3 different lines while only consuming a single line in the relevant script file. +If you're using a client from 2011-10-10aRagexe.exe onwards, you can also +use automatic navigation and open URLs in browser by using some HTML-like +labels. For example: + + mes "go to <NAVI>[Hat Maker]<INFO>izlude,131,148,</INFO></NAVI> to make hats"; + +Will make the [Hat Maker] text clickable in the client and start a navigation +to that point. + + mes "You can <URL>Google<INFO>http://www.google.com/</INFO></URL> anything"; + +Clicking Google will open the browser and point to Google website. + --------------------------------------- *next; @@ -1126,28 +1282,25 @@ Don't expect things to run smoothly if you don't make your scripts 'end'. This command will stop the execution for this particular script. It is required for any script not using 'mes'. - if (BaseLevel<=10) goto L_Lvl10; - if (BaseLevel<=20) goto L_Lvl20; - if (BaseLevel<=30) goto L_Lvl30; - if (BaseLevel<=40) goto L_Lvl40; - if (BaseLevel<=50) goto L_Lvl50; - if (BaseLevel<=60) goto L_Lvl60; - if (BaseLevel<=70) goto L_Lvl70; - L_Lvl10: + if (BaseLevel <= 10) { npctalk "Look at that you are still a n00b"; end; - L_Lvl20: + } + if (BaseLevel <= 20) { npctalk "Look at that you are getting better, but still a n00b"; end; - L_Lvl30: + } + if (BaseLevel <= 30) { npctalk "Look at that you are getting there, you are almost 2nd profession now right???"; end; - L_Lvl40: + } + if (BaseLevel <= 40) { npctalk "Look at that you are almost 2nd profession"; end; + } -Without the use if 'end' it would travel through the labels until the end -of the script. If you were lvl 10 or less, you would see all the speech +Without the use of 'end' it would travel through the ifs until the end +of the script. If you were lvl 10 or less, you would see all the speech lines, the use of 'end' stops this, and ends the script. --------------------------------------- @@ -1160,19 +1313,9 @@ in. This isn't the only way to set a variable directly: you can set them much like any other programming language as stated before (refer to the 'Assigning variables' section). -This is the most basic script command and is used a lot whenever you try -to do anything more advanced than just printing text into a message box. - - set @x,100; - -will make @x equal 100. - - set @x,1+5/8+9; - -will compute 1+5/8+9 (which is, surprisingly, 10 - remember, all numbers -are integer in this language) and make @x equal to it. - -Returns the variable reference. +This command is deprecated and it shouldn't be used in new scripts, except +some special cases (mostly, set getvariableofnpc). Use direct value +assignment instead. --------------------------------------- @@ -1204,8 +1347,8 @@ This can also be used to set an array dynamically: Examples: - set getd("$varRefence"), 1; - set @i, getd("$" + "pikachu"); + mes "The value of $varReference is: " + getd("$varRefence"); + set .@i, getd("$" + "pikachu"); --------------------------------------- @@ -1222,10 +1365,10 @@ Examples: //This will set the .v variable to the value of the TargetNPC's .var //variable. - set .v,getvariableofnpc(.var,"TargetNPC"); + .v = getvariableofnpc(.var,"TargetNPC"); //This will set the .var variable of TargetNPC to 1. - set getvariableofnpc(.var,"TargetNPC"),1; + set getvariableofnpc(.var,"TargetNPC"), 1; Note: even though function objects can have .variables, getvariableofnpc will not work on them. @@ -1256,6 +1399,10 @@ 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. +This command is deprecated and it should not be used in new scripts, as it +is likely to be removed at a later time. Please consider using select() or +prompt() instead. + Options can be grouped together, separated by the character ':'. menu "A:B",L_Wrong,"C",L_Right; @@ -1304,47 +1451,46 @@ 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. + setarray .@possiblemenuitems$[0],<list of potential menu items>; + .@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 ) - { + // .@i is our loop counter. + for (.@i = 0; .@i < getarraysize(.@possiblemenuitems$); ++.@i) { // That 'condition' is whatever condition that determines whether - // a menu item number @i actually goes into the menu or not. + // 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. + // available. - set @menulist$[@j],@possiblemenuitems$[@i]; + 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; + set .@menureference[.@j],.@i; // Since we've just added a menu item into the list, we - // increment the menu lines counter. + // increment the menu lines counter. - set @j,@j+1; + ++.@j; } // We go on to the next possible menu item. } -This will create you an array @menulist$ which contains the text of all +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 +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>],-; + 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 @@ -1360,19 +1506,19 @@ 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]]+"!"; + 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 +.@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 +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' +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, @@ -1385,7 +1531,7 @@ 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>]); + .@dummy = select(.@menulist$[0],.@menulist$[1],...,.@menulist$[<X>]); For the purposes of the technique described above these two statements are perfectly equivalent. @@ -1395,13 +1541,13 @@ perfectly equivalent. *select("<option>"{,"<option>",...}) *prompt("<option>"{,"<option>",...}) -This function is a handy replacement for 'menu' for some specific cases -where you don't want a complex label structure - like, for example, asking -simple yes-no questions. It will return the number of menu option picked, -starting with 1. Like 'menu', it will also set the variable @menu to +This function is a handy replacement for 'menu' that doesn't use a complex +label structure. It will return the number of menu option picked, +starting with 1. Like 'menu', it will also set the variable @menu to contain the option the user picked. - if (select("Yes:No")==1) mes "You said yes, I know."; + if (select("Yes:No") == 1) + mes "You said yes, I know."; And like 'menu', the selected option is consistent with grouped options and empty options. @@ -1422,16 +1568,13 @@ many uses, one example would be a guessing game, also making use of the mes "Try and guess the number I am thinking of."; mes "The number will be between 1 and 10."; next; - set @number, rand(1,10); - input @guess; - if(@guess==@number) - { + .@number = rand(1,10); + input .@guess; + if (.@guess == .@number) { mes "[Woman]"; mes "Well done that was the number I was thinking of"; close; - } - else - { + } else { mes "[Woman]"; mes "Sorry, that wasn't the number I was thinking of."; close; @@ -1444,15 +1587,12 @@ allowed. mes "[Woman]"; mes "Please say HELLO"; next; - input @var$; - if(@var$=="HELLO") - { + input .@var$; + if (.@var$ == "HELLO") { mes "[Woman]"; mes "Well done you typed it correctly"; close; - } - else - { + } else { mes "[Woman]"; mes "Sorry you got it wrong"; close; @@ -1488,8 +1628,9 @@ back to the place that called it. close; } function%TAB%script%TAB%funcNPC%TAB%{ - set @win, rand(2); - if(@win==0) return; + .@win = rand(2); + if (.@win == 0) + return; mes "Sorry you lost"; end; } @@ -1506,8 +1647,8 @@ make the script generally cleaner: mes "[Man]" mes "Gimme a number!"; next; - input @number; - if (callfunc("OddFunc",@number)) mes "It's Odd!"; + input .@number; + if (callfunc("OddFunc",.@number)) mes "It's Odd!"; close; } function%TAB%script%TAB%OddFunc%TAB%{ @@ -1554,10 +1695,10 @@ label is not callable in this manner from another script. Example 1: callsub for checking (if checks pass, return to script) callsub S_CheckFull, "guild_vs2",50; switch( rand(4) ) { - case 0: warp "guild_vs2",9,50; end; - case 1: warp "guild_vs2",49,90; end; - case 2: warp "guild_vs2",90,50; end; - case 3: warp "guild_vs2",49,9; end; + case 0: warp "guild_vs2",9,50; end; + case 1: warp "guild_vs2",49,90; end; + case 2: warp "guild_vs2",90,50; end; + case 3: warp "guild_vs2",49,9; end; } ... @@ -1573,11 +1714,11 @@ Example 2: callsub used repeatedly, with different arguments // notice how the Zeny check/delete is reused, instead of copy-pasting for // every warp. switch(select("Abyss Lake:Amatsu Dungeon:Anthell:Ayothaya Dungeon:Beacon Island, Pharos") { - case 1: callsub S_DunWarp,"hu_fild05",192,207; - case 2: callsub S_DunWarp,"ama_in02",119,181; - case 3: callsub S_DunWarp,"moc_fild20",164,145; - case 4: callsub S_DunWarp,"ayo_fild02",279,150; - case 5: callsub S_DunWarp,"cmd_fild07",132,125; + case 1: callsub S_DunWarp,"hu_fild05",192,207; + case 2: callsub S_DunWarp,"ama_in02",119,181; + case 3: callsub S_DunWarp,"moc_fild20",164,145; + case 4: callsub S_DunWarp,"ayo_fild02",279,150; + case 5: callsub S_DunWarp,"cmd_fild07",132,125; // etc } @@ -1588,7 +1729,7 @@ S_DunWarp: // getarg(1) = x // getarg(2) = y if (Zeny >= 100) { - set Zeny, Zeny-100; + Zeny -= 100; warp getarg(0),getarg(1),getarg(2); } else { mes "Dungeon warp costs 100 Zeny."; @@ -1625,8 +1766,8 @@ number 0. If no such argument was given, a zero is returned. ... function%TAB%script%TAB%funcNPC%TAB%{ - set @win, rand(getarg(0)); - if(@win==0) return; + .@win = rand(getarg(0)); + if(.@win==0) return; mes "Sorry you lost"; "woman1" NPC object calls the funcNPC. The argument it gives in this call @@ -1660,7 +1801,7 @@ Example: callfunc "funcNPC",5,4,3; ... function%TAB%script%TAB%funcNPC%TAB%{ - set .@count, getargcount(); // 3 + .@count = getargcount(); // 3 ... } @@ -1677,7 +1818,7 @@ Using this command outside of functions or scripts referenced by callsub will result in error and termination of the script. callfunc "<your function>";// when nothing is returned - set <variable>,callfunc("<your function>"); + <variable> = callfunc("<your function>"); // when a value is being returned --------------------------------------- @@ -1722,7 +1863,7 @@ prontera,154,189,4 script Item Seller 767,{ mes "Would you like to buy a phracon for 50z?"; next; if(select("Yes","No, thanks") == 1) { - set Zeny, Zeny-50; + Zeny -= 50; getitem 1010,1; mes "Thank you!"; } @@ -1765,8 +1906,8 @@ Example: } - script test -1,{ - set .@try, is_function("try"); // 1 - set .@not, is_function("not"); // 0 + .@try = is_function("try"); // 1 + .@not = is_function("not"); // 0 } --------------------------------------- @@ -1793,106 +1934,71 @@ above. Anything that is returned by a function can be used in a condition check without bothering to store it in a specific variable: - if (strcharinfo(0)=="Daniel Jackson") mes "It is true, you are Daniel!"; + if (strcharinfo(0)=="Daniel Jackson") mes "It is true, you are Daniel!"; More examples of using the 'if' command in the real world: Example 1: - set @var1,1; - input @var2; - if(@var1==@var2) goto L_Same; - mes "Sorry that is wrong"; - close; - L_Same: - close; + .@var1 = 1; + input .@var2; + if (.@var1 == .@var2) + close; + mes "Sorry that is wrong"; + close; Example 2: - - set @var1,1; - input @var2; - if(@var1!=@var2) mes "Sorry that is wrong"; - close; + + .@var1 = 1; + input .@var2; + if (.@var1 != .@var2) + mes "Sorry that is wrong"; + close; (Notice examples 1 and 2 have the same effect.) Example 3: - set @var1,@var1+1; - mes "[Forgetfull Man]"; - if (@var==1) mes "This is the first time you have talked to me"; - if (@var==2) mes "This is the second time you have talked to me"; - if (@var==3) mes "This is the third time you have talked to me"; - if (@var==4) mes "This is the forth time you have talked to me, but I think I am getting amnesia, I have forgotten about you"; - if (@var==4) set @var,0; - close; + ++.@var1; + mes "[Forgetfull Man]"; + if (.@var == 1) mes "This is the first time you have talked to me"; + if (.@var == 2) mes "This is the second time you have talked to me"; + if (.@var == 3) mes "This is the third time you have talked to me"; + if (.@var == 4) mes "This is the forth time you have talked to me, but I think I am getting amnesia, I have forgotten about you"; + if (.@var == 4) .@var = 0; + close; Example 4: - mes "[Quest Person]"; - if(countitem(512)>=1) goto L_GiveApple; - // The number 512 was found from item_db, it is the item number - // for the Apple. - mes "Can you please bring me an apple?"; - close; - L_GiveApple: - mes "Oh an apple, I didn't want it, I just wanted to see one"; - close; - -Example 5: - - mes "[Person Checker]"; - if($name$!=null) goto L_Check; - mes "Please tell me someones name"; - next; - input $name$; - set $name2$,strcharinfo(0); - mes "[Person Checker]"; - mes "Thank you"; - L_Check: - if($name$==strcharinfo(0) ) goto L_SameName; - mes "[Person Checker]"; - mes "You are not the person that " +$name2$+ " mentioned"; - L_End: - set $name$,null; - set $name2$,null; - close; - L_SameName: - mes "[Person Checker]"; - mes "You are the person that " +$name2$+ " just mentioned"; - mes "nice to meet you"; - goto L_End; + mes "[Quest Person]"; + // The (AegisName) constant Apple comes from item_db, it is the item number 512. + if (countitem(Apple) >= 1) { + mes "Oh an apple, I didn't want it, I just wanted to see one"; + close; + } + mes "Can you please bring me an apple?"; + close; -See 'strcharinfo' for explanation of what this function does. +Example 5: Using complex conditions. + + mes "[Multi Checker]"; + if ((queststarted == 1) && (countitem(Apple) >= 5)) { + // Executed only if the quest has been started AND You have 5 apples + mes "[Multi Checker]"; + mes "Well done you have started the quest of got me 5 apples"; + mes "Thank you"; + queststarted = 0; + delitem Apple, 5; + close; + } + mes "Please get me 5 apples"; + queststarted = 1; + close; -Example 6: Using complex conditions. - - mes "[Multi Checker]"; - if( (@queststarted==1) && (countitem(512)>=5) ) goto L_MultiCheck; - // Only if the quest has been started AND You have 5 apples will it goto "L_MultiCheck" - mes "Please get me 5 apples"; - set @queststarted,1; - close; - L_MultiCheck: - mes "[Multi Checker]"; - mes "Well done you have started the quest of got me 5 apples"; - mes "Thank you"; - set @queststarted,0; - delitem 512,5; - close; - -With the Advanced scripting engine, we got nested if's. That is: - -if (<condition>) - dothis; -else - dothat; - If the condition doesn't meet, it'll do the action following the else. We can also group several actions depending on a condition, this way: -if (<condition) -{ +if (<condition) { dothis1; dothis2; dothis3; @@ -1903,6 +2009,30 @@ if (<condition) dothat4; } +Example 6: + + mes "[Person Checker]"; + if ($name$ == "") { + mes "Please tell me someone's name"; + next; + input $name$; + $name2$ = strcharinfo(0); + mes "[Person Checker]"; + mes "Thank you"; + close; + } + if ($name$ == strcharinfo(0)) { + mes "You are the person that " +$name2$+ " just mentioned"; + mes "nice to meet you"; + } else { + mes "You are not the person that " +$name2$+ " mentioned"; + } + $name$ = ""; + $name2$ = ""; + close; + +See 'strcharinfo' for explanation of what this function does. + Remember that if you plan to do several actions upon the condition being false, and you forget to use the curly braces (the { } ), the second action will be executed regardless the output of the condition, unless of @@ -1915,8 +2045,7 @@ about limits as to how many nested if you can have, there is no spoon ;). ... if (<condition 1>) dothis; -else if (<condition 2>) -{ +else if (<condition 2>) { dotheother; do that; end; @@ -1930,8 +2059,9 @@ else if (<condition 2>) This command works like an 'if'+'goto' combination in one go. (See 'if'). If the condition is false (equal to zero) this command will immediately -jump to the specified label like in 'goto'. While 'if' is more generally -useful, for some cases this could be an optimization. +jump to the specified label like in 'goto'. + +This command should not be used in scripts directly. The main reason for this command is that other control statements, like 'switch', 'for' or 'while', are disassembled into simple expressions @@ -1964,10 +2094,10 @@ Example 2: multiple statements } Example 3: counter-controlled loop - set .@i, 1; + .@i = 1; while (.@i <= 5) { mes "This line will print 5 times."; - set .@i, .@i +1; + ++.@i; } Example 4: sentinel-controlled loop @@ -1994,12 +2124,12 @@ usually involves incrementing a variable). Then the condition is reevaluated and the cycle continues. Example 1: - for( set .@i, 1; .@i <= 5; set .@i, .@i +1 ) + for (.@i = 0; .@i < 5; ++.@i) mes "This line will print 5 times."; Example 2: mes "This will print the numbers 1 - 5."; - for( set .@i, 1; .@i <= 5; set .@i, .@i +1 ) + for (.@i = 1; .@i <= 5; ++.@i) mes .@i; --------------------------------------- @@ -2015,15 +2145,14 @@ statement following the 'do...while' loop expression. Example 1: sentinel-controlled loop mes "This menu will keep appearing until you pick Cancel"; do { - set .@menu, select("One:Two:Three:Cancel"); - } while (.@menu != 4); + .@choice = select("One:Two:Three:Cancel"); + } while (.@choice != 4); Example 2: counter-controlled loop mes "This will countdown from 10 to 1."; - set .@i, 10; + .@i = 10; do { - mes .@i; - set .@i, .@i - 1; + mes .@i--; } while (.@i > 0); --------------------------------------- @@ -2032,22 +2161,28 @@ Example 2: counter-controlled loop Toggling this to enabled (1) allows the script instance to bypass the infinite loop protection, allowing your script to loop as much as it may -need. Disabling (0) will warn you if an infinite loop is detected. +need. Disabling (0) may warn you if an infinite loop is detected if your +script is looping too many times. + +Please note, once again, that this isn't a solution to all problems, and by +disabling this protection your Hercules server may become laggy or +unresponsive if the script it is used in is performing lenghty loop +operations. Example: freeloop(1); // enable script to loop freely //Be aware with what you do here. - for ( set .@i,0; .@i<.@bigloop; set .@i, .@i+1 ) { + for (.@i = 0; .@i < .@bigloop; ++.@i) { dothis; // will sleep the script for 1ms when detect an infinity loop to // let Hercules do what it need to do (socket, timer, process, - // etc.) + // etc.) } freeloop(0); // disable - for ( set .@i,0; .@i<.@bigloop; set .@i, .@i+1 ) { + for (.@i = 0; .@i < .@bigloop; ++.@i) { dothis; // throw an infinity loop error } @@ -2059,19 +2194,19 @@ Example: This command will allow you to quickly fill up an array in one go. Check the Kafra scripts in the distribution to see this used a lot. - setarray @array[0], 100, 200, 300, 400, 500, 600; + setarray .@array[0], 100, 200, 300, 400, 500, 600; -First value is the index of the first element of the array to alter. For -example: +The index of the first element of the array to alter can be omitted if +zero. For example: + + setarray .@array, 200, 200, 200; + setarray .@array[1], 300, 150; - setarray @array[0],200,200,200; - setarray @array[1],300,150; - will produce: - @array[0]=200 - @array[1]=300 - @array[2]=150 + .@array[0] = 200 + .@array[1] = 300 + .@array[2] = 150 --------------------------------------- @@ -2080,13 +2215,15 @@ will produce: This command will change many array values at the same time to the same value. - setarray @array[0], 100, 200, 300, 400, 500, 600; - // This will make all 6 values 0 - cleararray @array[0],0,6; - // This will make array element 0 change to 245 - cleararray @array[0],245,1; - // This will make elements 1 and 2 change to 345 - cleararray @array[1],345,2; + setarray .@array, 100, 200, 300, 400, 500, 600; + // This will make all 6 values 0 + cleararray .@array[0], 0, 6; + // This will make array element 0 change to 245 + cleararray .@array[0], 245, 1; + // This is equivalent to the above + cleararray .@array, 245, 1; + // This will make elements 1 and 2 change to 345 + cleararray .@array[1], 345, 2; See 'setarray'. @@ -2097,28 +2234,28 @@ See 'setarray'. This command lets you quickly shuffle a lot of data between arrays, which is in some cases invaluable. - setarray @array[0], 100, 200, 300, 400, 500, 600; - // So we have made @array[] - copyarray @array2[0],@array[2],2; - - // Now, @array2[0] will be equal to @array[2] (300) and - // @array2[1] will be equal to @array[3]. + setarray .@array, 100, 200, 300, 400, 500, 600; + // So we have made .@array[] + copyarray .@array2[0],.@array[2],2; + + // Now, .@array2[0] will be equal to .@array[2] (300) and + // .@array2[1] will be equal to .@array[3]. So using the examples above: - @array[0] = 100 - @array[1] = 200 - @array[2] = 300 - @array[3] = 400 - @array[4] = 500 - @array[5] = 600 + .@array[0] = 100 + .@array[1] = 200 + .@array[2] = 300 + .@array[3] = 400 + .@array[4] = 500 + .@array[5] = 600 New Array: - @array2[0] = 300 - @array2[1] = 400 - @array2[2] = 0 - @array2[3] = 0 + .@array2[0] = 300 + .@array2[1] = 400 + .@array2[2] = 0 + .@array2[3] = 0 -Notice that @array[4] and @array[5] won't be copied to the second array, +Notice that .@array[4] and .@array[5] won't be copied to the second array, and it will return a 0. --------------------------------------- @@ -2128,35 +2265,54 @@ and it will return a 0. This command will delete a specified number of array elements totally from an array, shifting all the elements beyond this towards the beginning. - // This will delete array element 0, and move all the other array - // elements up one place. - deletearray @array[0],1 + // This will delete array element 0, and move all the other array + // elements up one place. + deletearray .@array[0],1 + + // This would delete array elements numbered 1, 2 and 3, leave element 0 + // in its place, and move the other elements ups, so there are no gaps. + deletearray .@array[1],3 + +If the amount of items to delete is not specified, all elements of the +array starting from the specified one to the end, are deleted. If no +starting element is specified either, the the entire array will be +deleted. -// This would delete array elements numbered 1, 2 and 3, leave element 0 -// in its place, and move the other elements ups, so there are no gaps. + // This would delete all elements of the array starting from 2, leaving + // element 0 and 1 + deletearray .@array[2]; - deletearray @array[1],3 + // This would delete all elements of the array + deletearray .@array; --------------------------------------- +//===================================== +1 - End of Basic-Related Commands +//===================================== +--------------------------------------- + -====================================== -|2.- Information-retrieving commands.| -====================================== +--------------------------------------- +//===================================== +2 - Information-retrieving Related Commands +//===================================== --------------------------------------- *strcharinfo(<type>) This function will return either the name, party name or guild name for the invoking character. Whatever it returns is determined by type. - - 0 - Character's name. - 1 - The name of the party they're in if any. - 2 - The name of the guild they're in if any. - 3 - The name of the map the character is in. +(0) PC_NAME - Character's name. +(1) PC_PARTY - The name of the party they're in if any. +(2) PC_GUILD - The name of the guild they're in if any. +(3) PC_MAP - The name of the map the character is in. If a character is not a member of any party or guild, an empty string will be returned when requesting that information. +Note: Numbers can also be used in <type>, but their usage is disncouraged as +using only numbers reduces script readability + --------------------------------------- *strnpcinfo(<type>) @@ -2174,21 +2330,28 @@ Whatever it returns is determined by type. *getarraysize(<array name>) -This function returns the number of values that are contained inside the -specified array. Notice that zeros and empty strings at the end of this -array are not counted towards this number. +This function returns highest index of the array that is filled. +Notice that zeros and empty strings at the end of this array are not +counted towards this number. For example: - setarray @array[0], 100, 200, 300, 400, 500, 600; - set @arraysize,getarraysize(@array); + setarray .@array, 100, 200, 300, 400, 500, 600; + .@arraysize = getarraysize(.@array); -This will make @arraysize == 6. But if you try this: +This will make .@arraysize == 6. But if you try this: - setarray @array[0], 100, 200, 300, 400, 500, 600, 0; - set @arraysize,getarraysize(@array); - -@arraysize will still equal 6, even though you've set 7 values. + setarray .@array, 100, 200, 300, 400, 500, 600, 0; + .@arraysize = getarraysize(.@array); + +.@arraysize will still equal 6, even though you've set 7 values. + +If you do this: + + .@array[1000] = 1; + .@arraysize = getarraysize(.@array); + +.@arraysize will be 1000, even though only one element has been set. --------------------------------------- @@ -2197,15 +2360,15 @@ This will make @arraysize == 6. But if you try this: This command retrieves the value of the element of given array at given index. This is equivalent to using: - <array name>[<index>] + <array name>[<index>] 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 or accessing another npc's arrays: - getelementofarray(getarg(0),<index>) - getelementofarray(getvariableofnpc(.var, "testNPC"),<index>) + getelementofarray(getarg(0),<index>) + getelementofarray(getvariableofnpc(.var, "testNPC"),<index>) --------------------------------------- @@ -2226,20 +2389,25 @@ All of these also behave as variables, but don't expect to be able to just Example 1: - // Returns how many status points you haven't spent yet. - mes "Unused status points: "+readparam(9); + // Returns how many status points you haven't spent yet. + mes "Unused status points: "+readparam(9); Using this particular information as a function call is not required. Typing this will return the same result: - mes "Unused status points: "+StatusPoint; + mes "Unused status points: "+StatusPoint; Example 2: You can also use this command to get stat values. - if (readparam(bVit) > 77) - mes "Only people with over 77 Vit are reading this!"; + if (readparam(bVit) > 77) + mes "Only people with over 77 Vit are reading this!"; + +Example 3: + + // Display your current weight + mes "Your current weight is "+( Weight/10 )+"/"+( MaxWeight/10 ); --------------------------------------- @@ -2278,7 +2446,7 @@ Retrieves IDs of the currently invoked NPC. If a unique npc name is given, IDs of that NPC are retrieved instead. Type specifies what ID to retrieve and can be one of the following: - 0 - Unit ID (GID) + 0 - Unit ID (GID) If an invalid type is given or the NPC does not exist, 0 is returned. @@ -2291,7 +2459,7 @@ If an invalid type is given or the NPC does not exist, 0 is returned. These functions return the character ID of the attached player's child, mother, mother, or father, respectively. It returns 0 if no ID is found. - if (getmotherid()) mes "Your mother's ID is: "+getmotherid(); + if (getmotherid()) mes "Your mother's ID is: "+getmotherid(); --------------------------------------- @@ -2308,8 +2476,8 @@ This function returns the character ID of the invoking character's marriage partner, if any. If the invoking character is not married, it will return 0, which is a quick way to see if they are married: - if (!getpartnerid()) mes "I'm not going to be your girlfriend!"; - if (getpartnerid()) mes "You're married already!"; + if (!getpartnerid()) mes "I'm not going to be your girlfriend!"; + if (getpartnerid()) mes "You're married already!"; --------------------------------------- @@ -2320,9 +2488,9 @@ number. If there is no such party ID, "null" will be returned. Lets say the ID of a party was saved as a global variable: - // This would return the name of the party from the ID stored in a - // variable - mes "You're in the '"+getpartyname($@var)+"' party, I know!"; + // This would return the name of the party from the ID stored in a + // variable + mes "You're in the '"+getpartyname($@var)+"' party, I know!"; --------------------------------------- @@ -2371,14 +2539,14 @@ Example 1: list party member names // It's a good idea to copy the global temporary $@partymember***** // variables to your own scope variables because if you have pauses in - // this script (sleep, sleep2, next, close2, input, menu, select, or - // prompt), another player could click this NPC, trigger - // 'getpartymember', and overwrite the $@partymember***** variables. - set .@count, $@partymembercount; + // this script (sleep, sleep2, next, close2, input, menu, select, or + // prompt), another player could click this NPC, trigger + // 'getpartymember', and overwrite the $@partymember***** variables. + .@count = $@partymembercount; copyarray .@name$[0], $@partymembername$[0], $@partymembercount; // list the party member names - for (set .@i,0; .@i < .@count; set .@i, .@i+1) { + for (.@i = 0; .@i < .@count; ++.@i) { mes (.@i +1) + ". ^0000FF" + .@name$[.@i] + "^000000"; } close; @@ -2386,28 +2554,28 @@ Example 1: list party member names Example 2: check party count (with a 'next' pause), before warping to event - set .register_num, 5; // How many party members are required? + .register_num = 5; // How many party members are required? // get the charID and accountID of character's party members getpartymember getcharid(1), 1; getpartymember getcharid(1), 2; - if ( $@partymembercount != .register_num ) { + if ($@partymembercount != .register_num) { mes "Please form a party of "+ .register_num +" to continue"; close; } // loop through both and use 'isloggedin' to count online party members - for ( set .@i, 0; .@i < $@partymembercount; set .@i, .@i +1 ) - if ( isloggedin( $@partymemberaid[.@i], $@partymembercid[.@i] ) ) - set .@count_online, .@count_online +1 ; + for (.@i = 0; .@i < $@partymembercount; ++.@i) + if (isloggedin($@partymemberaid[.@i], $@partymembercid[.@i])) + .@count_online++; // We search accountID & charID because a single party can have - // multiple characters from the same account. Without searching - // through the charID, if a player has 2 characters from the same - // account inside the party but only 1 char online, it would count - // their online char twice. + // multiple characters from the same account. Without searching + // through the charID, if a player has 2 characters from the same + // account inside the party but only 1 char online, it would count + // their online char twice. - if ( .@count_online != .register_num ) { + if (.@count_online != .register_num) { mes "All your party members must be online to continue"; close; } @@ -2415,22 +2583,22 @@ Example 2: check party count (with a 'next' pause), before warping to event // copy the array to prevent players cheating the system copyarray .@partymembercid, $@partymembercid, .register_num; - mes "Are you ready ?"; + mes "Are you ready?"; next; // careful here select "Yes"; // When a script hits a next, menu, sleep or input that pauses the - // script, players can invite or /leave and make changes in their - // party. To prevent this, we call getpartymember again and compare - // with the original values. + // script, players can invite or /leave and make changes in their + // party. To prevent this, we call getpartymember again and compare + // with the original values. getpartymember getcharid(1), 1; - if ( $@partymembercount != .register_num ) { + if ($@partymembercount != .register_num) { mes "You've made changes to your party !"; close; } - for ( set .@i, 0; .@i < $@partymembercount; set .@i, .@i +1 ) { - if ( .@partymembercid[.@i] != $@partymembercid[.@i] ) { + for (.@i = 0; .@i < $@partymembercount; ++.@i) { + if (.@partymembercid[.@i] != $@partymembercid[.@i]) { mes "You've made changes to your party !"; close; } @@ -2495,11 +2663,27 @@ Examples: // Outputs IP address of character "Silver". mes "Silver's IP: " + getcharip("Silver"); - + +--------------------------------------- + +*sit({"<character name>"}) +*stand({"<character name>"}) + +This function will force a character to sit/stand if it is standing/sitting. +If no player is specified, the attached player will be used. + +--------------------------------------- + +*issit({"<character name>"}) + +This function will return a number depending on the character's sitting state. +If the character is sitting, it will return 1, otherwise (standing) it will return 0. +In case no player is specified, the function will return the state of the attached player. + --------------------------------------- -\\ -2,2 Item-related commands -\\ +//===================================== +2.1 - Item-Related Commands +//===================================== --------------------------------------- *getequipid(<equipment slot>) @@ -2521,6 +2705,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 @@ -2529,37 +2720,34 @@ for either slot. Can be used to check if you have something equipped, or if you haven't got something equipped: - if(getequipid(EQI_HEAD_TOP)==2234) goto L_WearingTiara; - mes "Come back when you have a Tiara on"; - close; - L_WearingTiara: - mes "What a lovely Tiara you have on"; - close; + if(getequipid(EQI_HEAD_TOP) == Tiara) { + mes "What a lovely Tiara you have on"; + close; + } + mes "Come back when you have a Tiara on"; + close; You can also use it to make sure people don't pass a point before removing an item totally from them. Let's say you don't want people to wear Legion Plate armor, but also don't want them to equip if after the check, you would do this: - if ((getequipid(EQI_ARMOR) == 2341) || (getequipid(EQI_ARMOR) == 2342) goto L_EquipedLegionPlate; - // the || is used as an or argument, there is 2341 and 2342 cause - // there are two different legion plate armors, one with a slot one - // without. - if ((countitem(2341) > 0) || (countitem(2432) > 0) goto L_InventoryLegionPlate; - mes "I will lets you pass"; - close2; - warp "place",50,50; - end; - L_EquipedLegionPlate: - mes "You are wearing some Legion Plate Armor, please drop that in your stash before continuing"; - close; - L_InventoryLegionPlate: - mes "You have some Legion Plate Armor in your inventory, please drop that in your stash before continuing"; - close; + if (getequipid(EQI_ARMOR) == Full_Plate_Armor || getequipid(EQI_ARMOR) == Full_Plate_Armor_) { + mes "You are wearing some Legion Plate Armor, please drop that in your stash before continuing"; + close; + } + if (countitem(Full_Plate_Armor) > 0 || countitem(Full_Plate_Armor_) > 0) { + mes "You have some Legion Plate Armor in your inventory, please drop that in your stash before continuing"; + close; + } + mes "I will lets you pass"; + close2; + warp "place",50,50; + end; --------------------------------------- -*getequipname(<equpment slot>) +*getequipname(<equipment slot>) Returns the jname of the item equipped in the specified equipment slot on the invoking character, or an empty string if nothing is equipped in that @@ -2568,10 +2756,10 @@ Does the same thing as getitemname(getequipid()). Useful for an NPC to state what your are wearing, or maybe saving as a string variable. See 'getequipid' for a full list of valid equipment slots. - if( getequipname(EQI_HEAD_TOP) != "" ) - mes "So you are wearing a "+getequipname(EQI_HEAD_TOP)+" on your head"; + if( getequipname(EQI_HEAD_TOP) != "" ) + mes "So you are wearing a "+getequipname(EQI_HEAD_TOP)+" on your head"; else - mes "You are not wearing any head gear"; + mes "You are not wearing a head gear"; --------------------------------------- @@ -2591,12 +2779,11 @@ may have several broken items, 1 given as an argument will return the first one found, 2 will return the second one, etc. Will return 0 if no such item is found. - // Let's see if they have anything broken: - if (getbrokenid(1)==0) goto Skip; - // They do, so let's print the name of the first broken item: - mes "Oh, I see you have a broken "+getitemname(getbrokenid(1))+" here!"; - Skip: - mes "You don't have anything broken, quit bothering me."; + // Let's see if they have anything broken: + if (getbrokenid(1)==0) + mes "You don't have anything broken, quit bothering me."; + else // They do, so let's print the name of the first broken item: + mes "Oh, I see you have a broken "+getitemname(getbrokenid(1))+" here!"; --------------------------------------- @@ -2606,14 +2793,14 @@ This functions will return 1 if there is an equipment placed on the specified equipment slot and 0 otherwise. For a list of equipment slots see 'getequipid'. Function originally used by the refining NPCs: - if (getequipisequiped(EQI_HEAD_TOP)) goto L_equipped; - mes "[Refiner]"; - mes "Do you want me to refine your dumb head?"; - close; - L_equipped: - mes "[Refiner]"; - mes "That's a fine hat you are wearing there..."; - close; + if (getequipisequiped(EQI_HEAD_TOP)) { + mes "[Refiner]"; + mes "That's a fine hat you are wearing there..."; + close; + } + mes "[Refiner]"; + mes "Do you want me to refine your dumb head?"; + close; --------------------------------------- @@ -2623,14 +2810,14 @@ Will return 1 if the item equipped on the invoking character in the specified equipment slot is refinable, and 0 if it isn't. For a list of equipment slots see 'getequipid'. - if (getequipisenableref(EQI_HEAD_TOP)) goto L_Refine; - mes "[Refiner]"; - mes "I can't refine this hat!..."; - close; - L_Refine: - mes "[Refiner]"; - mes "Ok I can refine this"; - close; + if (getequipisenableref(EQI_HEAD_TOP)) { + mes "[Refiner]"; + mes "Ok I can refine this"; + close; + } + mes "[Refiner]"; + mes "I can't refine this hat!..."; + close; --------------------------------------- @@ -2642,11 +2829,11 @@ equipment slot. For a list of equipment slots see 'getequipid'. Can be used to check if you have reached a maximum refine value, default for this is +10: - if(getequiprefinerycnt(EQI_HEAD_TOP) < 10) goto L_Refine_HeadGear; - mes "Sorry, it's not possible to refine hats better than +10"; - close; - L_Refine_HeadGear: - mes "I will now upgrade your "+getequipname(EQI_HEAD_TOP); + if(getequiprefinerycnt(EQI_HEAD_TOP) < 10) + mes "I will now upgrade your "+getequipname(EQI_HEAD_TOP); + else + mes "Sorry, it's not possible to refine hats better than +10"; + close; --------------------------------------- @@ -2666,28 +2853,28 @@ according to the database, 0 will be returned. Examples: // Right hand can only contain a weapon. - switch (getequipweaponlv(EQI_HAND_R)) { - case 1: mes "You are holding a lvl 1 weapon."; break; - case 2: mes "You are holding a lvl 2 weapon."; break; - case 3: mes "You are holding a lvl 3 weapon."; break; - case 4: mes "You are holding a lvl 4 weapon."; break; - case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break; - default: mes "Seems you don't have a weapon on."; break; - } + switch (getequipweaponlv(EQI_HAND_R)) { + case 1: mes "You are holding a lvl 1 weapon."; break; + case 2: mes "You are holding a lvl 2 weapon."; break; + case 3: mes "You are holding a lvl 3 weapon."; break; + case 4: mes "You are holding a lvl 4 weapon."; break; + case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break; + default: mes "Seems you don't have a weapon on."; break; + } // Left hand can hold either a weapon or shield. - if (getequipid(EQI_HAND_R) == 0) { - mes "Seems you have nothing equipped here."; - close; - } - switch (getequipweaponlv(EQI_HAND_L)) { - case 0: mes "You are holding a shield, so it doesn't have a level."; break; - case 1: mes "You are holding a lvl 1 weapon."; break; - case 2: mes "You are holding a lvl 2 weapon."; break; - case 3: mes "You are holding a lvl 3 weapon."; break; - case 4: mes "You are holding a lvl 4 weapon."; break; - case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break; - } + if (getequipid(EQI_HAND_R) == 0) { + mes "Seems you have nothing equipped here."; + close; + } + switch (getequipweaponlv(EQI_HAND_L)) { + case 0: mes "You are holding a shield, so it doesn't have a level."; break; + case 1: mes "You are holding a lvl 1 weapon."; break; + case 2: mes "You are holding a lvl 2 weapon."; break; + case 3: mes "You are holding a lvl 3 weapon."; break; + case 4: mes "You are holding a lvl 4 weapon."; break; + case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break; + } --------------------------------------- @@ -2704,8 +2891,9 @@ the random change of a refine succeeding or failing and then going through with it (which is what the official NPC refinery scripts use it for). // This will find a random number from 0 - 99 and if that is equal to or -// more than the value recovered by this command it will go to L_Fail - if (getequippercentrefinery(EQI_HAND_L)<=rand(100)) goto L_Fail; +// more than the value recovered by this command it will show a message + if (getequippercentrefinery(EQI_HAND_L) <= rand(100)) + mes "Aww"; --------------------------------------- @@ -2752,6 +2940,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 @@ -2774,7 +2963,7 @@ This function will return the number of cards inserted into the weapon currently equipped on the invoking character. While this function was meant for item scripts, it will work outside them: - if (cardscnt()==4) mes "So you've stuck four cards into that weapon, think you're cool now?"; + if (cardscnt()==4) mes "So you've stuck four cards into that weapon, think you're cool now?"; --------------------------------------- @@ -2783,7 +2972,7 @@ While this function was meant for item scripts, it will work outside them: This function will return the refine count of the equipment from which the function is called. This function is intended for use in item scripts. - if (getrefine()==10) mes "Wow. That's a murder weapon."; + if (getrefine()==10) mes "Wow. That's a murder weapon."; --------------------------------------- @@ -2816,8 +3005,8 @@ if there is no such item. Example: -//@slots now has the amount of slots of the item with ID 1205. - set @slots, getItemSlots(1205); +//.@slots now has the amount of slots of the item with ID 1205. + .@slots = getitemslots(1205); --------------------------------------- @@ -2850,9 +3039,9 @@ produced). It's useful for when you want to check whether an item contains cards or if it's signed. --------------------------------------- -// -2,1.- End of item-related commands. -// +//===================================== +2.1 - End of Item-Related Commands +//===================================== --------------------------------------- *getmapxy("<variable for map name>",<variable for x>,<variable for y>,<type>{,"<search string>"}) @@ -2864,14 +3053,14 @@ parameters given were not variables or the search was not successful. Type is the type of object to search for: - 0 - Character object - 1 - NPC object - 2 - Pet object - 3 - Monster object - 4 - Homunculus object - 5 - Mercenary object - 6 - Elemental object - + 0 - Character object + 1 - NPC object + 2 - Pet object + 3 - Monster object + 4 - Homunculus object + 5 - Mercenary object + 6 - Elemental object + While 3 is meant to look for a monster object, no searching will be done if you specify type 3, and the function will always return -1. @@ -2885,22 +3074,22 @@ string, it will NOT locate a pet by name. What a mess. Example, a working and tested one now: - prontera,164,301,3%TAB%script%TAB%Meh%TAB%730,{ - mes "My name is Meh. I'm here so that Nyah can find me."; - close; - } + prontera,164,301,3%TAB%script%TAB%Meh%TAB%730,{ + mes "My name is Meh. I'm here so that Nyah can find me."; + close; + } + + prontera,164,299,3%TAB%script%TAB%Nyah%TAB%730,{ + mes "My name is Nyah."; + mes "I will now search for Meh all across the world!"; + if (getmapxy(.@mapname$,.@mapx,.@mapy,1,"Meh")!=0) { + mes "I can't seem to find Meh anywhere!"; + close; + } + mes "And I found him on map "+.@mapname$+" at X:"+.@mapx+" Y:"+.@mapy+" !"; + close; + } - prontera,164,299,3%TAB%script%TAB%Nyah%TAB%730,{ - mes "My name is Nyah."; - mes "I will now search for Meh all across the world!"; - if (getmapxy(@mapname$,@mapx,@mapy,1,"Meh")!=0) goto Notfound; - mes "And I found him on map "+@mapname$+" at X:"+@mapx+" Y:"+@mapy+" !"; - close; - Notfound: - mes "I can't seem to find Meh anywhere!"; - close; - } - Notice that NPC objects disabled with 'disablenpc' will still be located. --------------------------------------- @@ -2915,8 +3104,8 @@ account has no GM level. This allows you to make NPC's only accessible for certain GM levels, or behave specially when talked to by GMs. - if (getgmlevel()) mes "What is your command, your godhood?"; - if (getgmlevel()) goto Wherever; + if (getgmlevel()) mes "What is your command, your godhood?"; + if (getgmlevel() < 99) end; --------------------------------------- @@ -2959,7 +3148,7 @@ This function returns specified information about the current system time. It will only return numbers. - if (gettime(4)==6) mes "It's a Saturday. I don't work on Saturdays."; + if (gettime(4)==6) mes "It's a Saturday. I don't work on Saturdays."; --------------------------------------- @@ -2976,8 +3165,8 @@ Max length is the maximum length of a time string to generate. The example given in Hercules sample scripts works like this: - mes gettimestr("%Y-%m/%d %H:%M:%S",21); - + mes gettimestr("%Y-%m/%d %H:%M:%S",21); + This will print a full date and time like 'YYYY-MM/DD HH:MM:SS'. --------------------------------------- @@ -2989,10 +3178,10 @@ What it returns is specified by Type. Type can be one of the following values, which control what is returned: - 0 - Count of all characters on the map of the invoking character. - 1 - Count of all characters in the entire server. - 8 - Count of all characters on the map of the NPC the script is - running in. + 0 - Count of all characters on the map of the invoking character. + 1 - Count of all characters in the entire server. + 8 - Count of all characters on the map of the NPC the script is + running in. --------------------------------------- @@ -3027,21 +3216,22 @@ window (see 'mes') paging it by 10 names as if with the 'next' command. You need to put a 'close' after that yourself. --------------------------------------- -\\ -2,2.- Guild-related commands -\\ +//===================================== +2.2 - Guild-Related Commands +//===================================== --------------------------------------- + *getguildname(<guild id>) This function returns a guild's name given an ID number. If there is no such guild, "null" will be returned; - // Would print whatever guild 10007 name is. - mes "The guild "+GetGuildName(10007)+" are all nice people."; + // Would print whatever guild 10007 name is. + mes "The guild "+getguildname(10007)+" are all nice people."; - // This will do the same as above: - set @var,10007; - mes "We have some friends in "+GetGuildName(@var)+", you know."; + // This will do the same as above: + .@var = 10007; + mes "We have some friends in "+getguildname(.@var)+", you know."; This is used all over the WoE controlling scripts. You could also use it for a guild-based event. @@ -3054,25 +3244,24 @@ This function return the name of the master of the guild which has the specified ID number. If there is no such guild, "null" will be returned. // Would return the guild master of guild 10007, whatever that might be. - mes getguildmaster(10007)+" runs "+getguildname(10007); + mes getguildmaster(10007)+" runs "+getguildname(10007); Can be used to check if the character is the guild master of the specified guild. Maybe you want to make a room only guild masters can enter: - set @GID,getcharid(2); - if(@GID==0) goto L_NoGuild; - if(strcharinfo(0)==getguildmaster(@GID)) goto L_GuildMaster; - mes "Sorry you don't own the guild you are in"; - close; - L_NoGuild: - mes "Sorry you are not in a guild"; - close; - L_GuildMaster: - mes "Welcome guild master of "+GetGuildName(@GID); - close; - + .@GID = getcharid(2); + if (.@GID == 0) { + mes "Sorry you are not in a guild"; + close; + } + if (strcharinfo(0) == getguildmaster(.@GID)) { + mes "Welcome guild master of "+GetGuildName(.@GID); + close; + } + mes "Sorry you don't own the guild you are in"; + close; --------------------------------------- @@ -3161,12 +3350,12 @@ Returns the amount of characters from the specified guild on the given map. Example: -mes "You have "+getMapGuildUsers("prontera",getcharid(2))+" guild members in Prontera."; +mes "You have "+getmapguildusers("prontera",getcharid(2))+" guild members in Prontera."; --------------------------------------- -// -2,2.- End of guild-related commands -// +//===================================== +2.2 - End of Guild-Related Commands +//===================================== --------------------------------------- *getskilllv(<skill id>) @@ -3182,25 +3371,26 @@ enough. Example 1: - if (getskilllv(152)) goto L_HasSkillThrowStone; - mes "You don't have Throw Stone"; - close; - L_HasSkillThrowStone: - mes "You have got the skill Throw Stone"; - close; + if (getskilllv(TF_THROWSTONE)) { + // TF_THROWSTONE is defined in skill_db.txt and its value is 152 + mes "You have got the skill Throw Stone"; + close; + } + mes "You don't have Throw Stone"; + close; Example 2: - if (getskilllv(28) >= 5) goto L_HasSkillHeallvl5orMore; - if (getskilllv(28) == 10) goto L_HasSkillHealMaxed; - mes "You heal skill is below lvl 5"; - close; - L_HasSkillHeallvl6orMore: - mes "Your heal lvl is 5 or more"; - close; - L_HasSkillHealMaxed: - mes "Your heal lvl has been maxed"; - close; + if (getskilllv(AL_HEAL) == 10) { + mes "Your heal lvl has been maxed"; + close; + } + if (getskilllv(AL_HEAL) >= 5) { + mes "Your heal lvl is 5 or more"; + close; + } + mes "You heal skill is below lvl 5"; + close; --------------------------------------- @@ -3251,7 +3441,7 @@ PET_HUNGRY PET_INTIMATE Example: - set @i, petstat(PET_CLASS); + .@i = petstat(PET_CLASS); --------------------------------------- @@ -3291,6 +3481,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 @@ -3325,15 +3548,15 @@ Example: if (getmobdrops(.@mob_id)) { // 'getmobdrops' returns 1 on success // immediately copy global temporary variables into scope - // variables, since we don't know when 'getmobdrops' will get - // called again for another mob, overwriting your global temporary - // variables. - set .@count, $@MobDrop_count; + // variables, since we don't know when 'getmobdrops' will get + // called again for another mob, overwriting your global temporary + // variables. + .@count = $@MobDrop_count; copyarray .@item[0],$@MobDrop_item[0],.@count; copyarray .@rate[0],$@MobDrop_rate[0],.@count; mes getmonsterinfo(.@mob_id,MOB_NAME) + " - " + .@count + " drops found:"; - for( set .@i,0; .@i < .@count; set .@i,.@i +1 ) { + for (.@i = 0; .@i < .@count; ++.@i) { mes .@item[.@i] + " (" + getitemname(.@item[.@i]) + ") " + .@rate[.@i]/100 + ((.@rate[.@i]%100 < 10) ? ".0":".") + .@rate[.@i]%100 + "%"; } } else { @@ -3353,13 +3576,13 @@ of skill points not used). Example: -//This will set the temp character variable @skillPoints to the amount of +//This will set the temp character variable @skill_points to the amount of //skill points, and then tell the player the value. - set @skillPoints, skillPointCount(); - mes "You have "+@skillPoints+" skill points in total!"; + @skill_points = skillpointcount(); + mes "You have "+@skill_points+" skill points in total!"; //Self-explanatory... :P - if (skillPointCount() > 20) + if (skillpointcount() > 20) mes "Wow, you have more then 20 Skill Points in total!"; This command does not count skills which are set as flag 3 (permamently @@ -3373,17 +3596,18 @@ invoking character, in percent, modified by the their current defense against said status. The 'base rate' is the base chance of the status effect being inflicted, in percent. - if (rand(100) > getscrate(Eff_Blind, 50)) goto BlindHimNow; - + if (rand(100) > getscrate(Eff_Blind, 50)) { + // do something + } + You can see the full list of available effect types you can possibly inflict in 'db/const.txt' under 'Eff_'. --------------------------------------- - -======================== -|3.- Checking commands.| -======================== -------------------------- +//===================================== +3 - Checking-Related Commands +//===================================== +--------------------------------------- *playerattached() @@ -3469,25 +3693,25 @@ set and 0 if the option is not set. Option numbers valid for the first (option) version of this command are: -0x1 - Sight in effect. -0x2 - Hide in effect. -0x4 - Cloaking in effect. -0x8 - Cart number 1 present. -0x10 - Falcon present. -0x20 - Peco Peco present. -0x40 - GM Perfect Hide in effect. -0x80 - Cart number 2 present. -0x100 - Cart number 3 present. -0x200 - Cart number 4 present. -0x400 - Cart number 5 present. -0x800 - Orc head present. -0x1000 - The character is wearing a wedding sprite. -0x2000 - Ruwach is in effect. -0x4000 - Chasewalk in effect. -0x8000 - Flying or Xmas suit. -0x10000 - Sighttrasher. -0x100000 - Warg present. -0x200000 - The character is riding a warg. +0x000001 - Sight in effect. +0x000002 - Hide in effect. +0x000004 - Cloaking in effect. +0x000008 - Cart number 1 present. +0x000010 - Falcon present. +0x000020 - Peco Peco present. +0x000040 - GM Perfect Hide in effect. +0x000080 - Cart number 2 present. +0x000100 - Cart number 3 present. +0x000200 - Cart number 4 present. +0x000400 - Cart number 5 present. +0x000800 - Orc head present. +0x001000 - The character is wearing a wedding sprite. +0x002000 - Ruwach is in effect. +0x004000 - Chasewalk in effect. +0x008000 - Flying or Xmas suit. +0x010000 - Sighttrasher. +0x100000 - Warg present. +0x200000 - The character is riding a warg. Option numbers valid for the second version (opt1) of this command are: @@ -3499,10 +3723,10 @@ Option numbers valid for the second version (opt1) of this command are: Option numbers valid for the third version (opt2) of this command are: -0x1 - Poisoned. -0x2 - Cursed. -0x4 - Silenced. -0x8 - Signum Crucis (plays a howl-like sound effect, but otherwise no +0x01 - Poisoned. +0x02 - Cursed. +0x04 - Silenced. +0x08 - Signum Crucis (plays a howl-like sound effect, but otherwise no visible effects are displayed) 0x10 - Blinded. 0x80 - Deadly poisoned. @@ -3551,7 +3775,7 @@ Note: the character needs to have the skill HT_FALCON to gain a falcon. The accompanying function will return 1 if the invoking character has a falcon and 0 if they don't. - if (checkfalcon()) mes "But you already have a falcon!"; + if (checkfalcon()) mes "But you already have a falcon!"; --------------------------------------- @@ -3568,7 +3792,7 @@ Note: the character needs to have the skill KN_RIDING to gain a mount. The accompanying function will return 1 if the invoking character is riding a bird and 0 if they aren't. - if (checkriding()) mes "PLEASE leave your bird outside! No riding birds on the floor here!"; + if (checkriding()) mes "PLEASE leave your bird outside! No riding birds on the floor here!"; --------------------------------------- @@ -3586,7 +3810,7 @@ If the character can mount a dragon, the <color> options are: 5 - Red Dragon Note: the character must be a Rune Knight and have the skill - RK_DRAGONTRAINING to gain a mount. + RK_DRAGONTRAINING to gain a mount. The accompanying function will return 1 if the invoking character is riding a dragon and 0 if they aren't. @@ -3611,7 +3835,7 @@ The 'setmounting' function toggles cash mount for the invoking character. It will return 1 if successful, 0 otherwise. Note: Character must not be mounting a non-cash mount (eg. dragon, peco, - wug, etc.) + wug, etc.) The accompanying function will return 1 if the invoking character has a cash mount and 0 if they don't. @@ -3640,7 +3864,7 @@ Return values for 'checkvending' are Examples: //This will check if Aaron is vending, and if so, put a message in - //front of the attached player saying Aaron is vending. + //front of the attached player saying Aaron is vending. if (checkvending("Aaron")) mes "Aaron is currently vending!"; @@ -3674,9 +3898,9 @@ night mode or day mode. 'isnight' returns 1 if it's night and 0 if it isn't, 'isday' the other way around. They can be used interchangeably, pick the one you like more: - // These two are equivalent: - if (isday()) mes "I only prowl in the night."; - if (isnight()!=1) mes "I only prowl in the night."; + // These two are equivalent: + if (isday()) mes "I only prowl in the night."; + if (isnight()!=1) mes "I only prowl in the night."; --------------------------------------- @@ -3695,10 +3919,11 @@ by the type parameter. 6 - RENEWAL_ASPD (renewal ASPD) --------------------------------------- -\\ -3,1.- Item-related commands -\\ +//===================================== +3.1 - Checking Item-Related Commands +//===================================== --------------------------------------- + *isequipped(<id>{,<id>{,<id>{,<id>}}}) This function will return 1 if the invoking character has all of the item @@ -3708,11 +3933,11 @@ Theoretically there is no limit to the number of items that may be tested for at the same time. If even one of the items given is not equipped, 0 will be returned. - // (Poring,Santa Poring,Poporing,Marin) - if (isequipped(4001,4005,4033,4196)) mes "Wow! You're wearing a full complement of possible poring cards!"; - // (Poring) - if (isequipped(4001)) mes "A poring card is useful, don't you think?"; - + // (Poring,Santa Poring,Poporing,Marin) + if (isequipped(4001,4005,4033,4196)) mes "Wow! You're wearing a full complement of possible poring cards!"; + // (Poring) + if (isequipped(4001)) mes "A poring card is useful, don't you think?"; + The function was meant for item scripts to support the cards released by Gravity in February 2005, but it will work just fine in normal NPC scripts. @@ -3724,7 +3949,7 @@ This function is similar to 'isequipped', but instead of 1 or 0, it will return the number of cards in the list given that were found on the invoking character. - if (isequippedcnt(4001,4005,4033,4196) == 4) mes "Finally got all four poring cards?"; + if (isequippedcnt(4001,4005,4033,4196) == 4) mes "Finally got all four poring cards?"; --------------------------------------- @@ -3746,15 +3971,16 @@ equipment slot, which makes this script command kinda pointless. For a list of equipment slots see 'getequipid'. --------------------------------------- -// -3,1.- End of item-related commands -// +//===================================== +3.0 & 3.1 - End of Checking/Item-Related Commands +//===================================== --------------------------------------- -============================== -|4.- Player-related commands.| -============================== -------------------------- +--------------------------------------- +//===================================== +4 - Player-Related Commands +//===================================== +--------------------------------------- *attachrid(<account ID>) *detachrid; @@ -3801,13 +4027,13 @@ chat window. This command will take the invoking character to the specified map, and if wanted, specified coordinates too, but these can be random. - warp "place",50,55; + warp "place",50,55; This would take them to X 50 Y 55 on the map called "place". If your X and Y coordinates land on an unwalkable map square, it will send the warped character to a random place. Same will happen if they are both zero: - warp "place",0,0; + warp "place",0,0; Notice that while warping people to coordinates 0,0 will normally get them into a random place, it's not certain to always be so. Darned if I know @@ -3829,19 +4055,19 @@ defined by the x1/y1-x2/y2 square, will be warped. Nobody outside the area will be affected, including the activating character, if they are outside the area. - areawarp "place",10,10,120,120,"place2",150,150; + areawarp "place",10,10,120,120,"place2",150,150; Everyone that is in the area between X 10 Y 10 and X 120 Y 120, in a square shape, on the map called "place", will be affected, and warped to "place2" X 150 Y 150. - areawarp "place",10,10,120,120,"place2",0,0; + areawarp "place",10,10,120,120,"place2",0,0; By using ,0,0; as the destination coordinates it will take all the characters in the affected area to a random set of co-ordinates on the "place2" map. - areawarp "place",10,10,120,120,"place2",150,150,200,200; + areawarp "place",10,10,120,120,"place2",150,150,200,200; By using the optional x4 and y4 parameters, the destination coordinates will be a random place within the defined x3/y3-x4/y4 square. @@ -3860,59 +4086,59 @@ you can get with getcharid(1). You can also request another party id given a member's name with getcharid(1,<player_name>). You can use the following "map names" for special warping behavior: -Random: All party members are randomly warped in their current map - (as if they all used a fly wing). -SavePointAll: All party members are warped to their respective save point. -SavePoint: All party members are warped to the save point of the - currently attached player (will fail if there's no player - attached). -Leader: All party members are warped to the leader's position. The - leader must be online and in the current map-server for this - to work. +Random: All party members are randomly warped in their current map + (as if they all used a fly wing). +SavePointAll: All party members are warped to their respective save point. +SavePoint: All party members are warped to the save point of the + currently attached player (will fail if there's no player + attached). +Leader: All party members are warped to the leader's position. The + leader must be online and in the current map-server for this + to work. If you specify a from_mapname, warpparty will only affect those on that map. Example: -mes "[Party Warper]"; -mes "Here you go!"; -close2; -set @id,getcharid(1); -warpparty "prontera",150,100,@id; -close; - + mes "[Party Warper]"; + mes "Here you go!"; + close2; + .@id = getcharid(1); + warpparty "prontera",150,100,.@id; + close; + --------------------------------------- - + *warpchar "<mapname>",<x>,<y>,<char_id>; - + Warps another player to specified map and coordinate given the char id, which you can get with getcharid(0,<player_name>). Obviously this is useless if you want to warp the same player that is executing this script, unless it's some kind of "chosen" script. - + Example: - + warpchar "prontera",150,100,150001; - + --------------------------------------- - + *warpguild "<mapname>",<x>,<y>,<guild_id>; - + Warps a guild to specified map and coordinate given the guild id, which you can get with getcharid(2). You can also request another guild id given the member's name with getcharid(2,<player_name>). - + You can use the following "map names" for special warping behavior: -Random: All guild members are randomly warped in their current map - (as if they all used a fly wing) -SavePointAll: All guild members are warped to their respective save point. -SavePoint: All guild members are warped to the save point of the - currently attached player (will fail if there's no player - attached). +Random: All guild members are randomly warped in their current map + (as if they all used a fly wing) +SavePointAll: All guild members are warped to their respective save point. +SavePoint: All guild members are warped to the save point of the + currently attached player (will fail if there's no player + attached). Example: - + warpguild "prontera",x,y,Guild_ID; --------------------------------------- @@ -3936,7 +4162,7 @@ are equivalent. Map name, X coordinate and Y coordinate should be perfectly obvious. This ignores any and all map flags, and can make a character respawn where no teleportation is otherwise possible. - savepoint "place",350,75; + savepoint "place",350,75; --------------------------------------- @@ -3945,9 +4171,9 @@ character respawn where no teleportation is otherwise possible. This command will heal a set amount of HP and/or SP on the invoking character. - heal 30000,0; // This will heal 30,000 HP - heal 0,30000; // This will heal 30,000 SP - heal 300,300; // This will heal 300 HP and 300 SP + heal 30000,0; // This will heal 30,000 HP + heal 0,30000; // This will heal 30,000 SP + heal 300,300; // This will heal 300 HP and 300 SP This command just alters the hit points and spell points of the invoking character and produces no other output whatsoever. @@ -3956,17 +4182,26 @@ character and produces no other output whatsoever. *itemheal <hp>,<sp>; -This command heals given absolute amounts of HP and/or SP on the invoking +This command heals given relative amounts of HP and/or SP on the invoking character. Unlike heal, this command is intended for use in item scripts. -It applies potion-related bonuses, such as alchemist ranking, cards and -status changes. When used inside an NPC script, certain bonuses are -omitted. +It applies potion-related bonuses, such as alchemist ranking, cards, +status changes. +It also applies a sp/vit-related bonus that is calculated by: + heal = heal*[(100+STATUS*2)/100] +So if a player has 99 vit and the script is 'itemheal 5,0': + heal(hp) = 5*[(100+99*2)/100] + heal(hp) = 14,9 + heal(hp) = 14 + heal(sp) = 0 + +When used inside an NPC script, potion-related bonuses are omitted. There is also a nice example on using this with the 'rand' function, to give you a random amount of healing. - // This will heal anything thing from 100 to 150 HP and no SP - itemheal rand(100,150),0; + // If the player has 50 vit and no bonuses this will heal + // anything from 200 to 300 HP and 5 SP + itemheal rand(100,150),5; --------------------------------------- @@ -3975,9 +4210,9 @@ give you a random amount of healing. This command will heal the invoking character. It heals the character, but not by a set value - it adds percent of their maximum HP/SP. - percentheal 100,0; // This will heal 100% HP - percentheal 0,100; // This will heal 100% SP - percentheal 50,50; // This will heal 50% HP and 50% SP + percentheal 100,0; // This will heal 100% HP + percentheal 0,100; // This will heal 100% SP + percentheal 50,50; // This will heal 50% HP and 50% SP So the amount that this will heal will depend on the total amount of HP or SP you have maximum. Like 'heal', this will not call up any animations or @@ -3996,17 +4231,17 @@ currently connected to the server. This command will change the job class of the invoking character. - jobchange 1; // This would change your player into a Swordman - jobchange 4002; // This would change your player into a Swordman High + jobchange 1; // This would change your player into a Swordman + jobchange 4002; // This would change your player into a Swordman High This command does work with numbers, but you can also use job names. The full list of job names and the numbers they correspond to can be found in 'db/const.txt'. - // This would change your player into a Swordman - jobchange Job_Swordman; - // This would change your player into a Swordman High - jobchange Job_Swordman_High; + // This would change your player into a Swordman + jobchange Job_Swordman; + // This would change your player into a Swordman High + jobchange Job_Swordman_High; 'upper flag' can alternatively be used to specify the type of job one changes to. For example, jobchange Job_Swordman,1; will change the @@ -4042,12 +4277,12 @@ constants which make it easy to convert among classes. The command will return -1 if you pass it a job number which doesn't have an eA job-number equivalent. - set @eac, eaclass(); - if ((@eac&EAJ_BASEMASK) == EAJ_SWORDMAN) + .@eac = eaclass(); + if ((.@eac&EAJ_BASEMASK) == EAJ_SWORDMAN) mes "Your base job is Swordman."; - if (@eac&EAJL_UPPER) + if (.@eac&EAJL_UPPER) mes "You are a rebirth job."; - if ((@eac&EAJ_UPPERMASK) == EAJ_SWORDMAN) + if ((.@eac&EAJ_UPPERMASK) == EAJ_SWORDMAN) mes "You must be a Swordman, Baby Swordman or High Swordman."; For more information on the eA Job System, see the docs/ea_job_system.txt @@ -4064,16 +4299,16 @@ male will be used by default). The command will return -1 if there is no valid class to represent the specified job (for example, if you try to get the baby version of a Taekwon class). - set @eac, eaclass(); + .@eac = eaclass(); //Check if class is already rebirth - if (@eac&EAJL_UPPER) { + if (.@eac&EAJL_UPPER) { mes "You look strong."; close; } - set @eac, roclass(@eac|EAJL_UPPER); + .@eac = roclass(.@eac|EAJL_UPPER); //Check if class has a rebirth version - if (@eac != -1) { - mes "Bet you can't wait to become a "+jobname(@eac)+"!"; + if (.@eac != -1) { + mes "Bet you can't wait to become a "+jobname(.@eac)+"!"; close; } @@ -4086,7 +4321,21 @@ of a specified job class. Nothing but appearance will change. Examples: -2338,Wedding_Dress,Wedding Dress,5,43000,,500,,0,,0,119529470,7,0,16,,0,1,0,{ bonus bMdef,15; changebase 22; } + /* This example is an item script in the item db */ + { + Id: 2338 + AegisName: "Wedding_Dress" + Name: "Wedding Dress" + Type: 5 + Buy: 43000 + Weight: 500 + Job: 0xFFFFFFFE + Loc: 16 + Script: <" + bonus bMdef,15; + changebase Job_Wedding; + "> + }, changebase Job_Novice; // Changes player to Novice sprite. @@ -4134,25 +4383,22 @@ they will also have their skills reset upon 'changesex'. *getexp <base xp>,<job xp>; This command will give the invoking character a specified number of base -and job experience points. Can be used as a quest reward. Negative values +and job experience points. Should be used as a quest reward. Negative values won't work. +Is subject to EXP bonuses and to the `quest_exp_rate` config option. - getexp 10000,5000; + getexp 10000,5000; -You can also use the "set" command with the constants defined in -'db/const.txt': +You can also assign directly to the parameters defined in 'db/const.txt': - // These 2 combined has the same effect as the above command - set BaseExp,BaseExp+10000; - set JobExp,JobExp+5000; + BaseExp += 10000; + JobExp += 5000; You can also reduce the amount of experience points: - set BaseExp,BaseExp-10000; + BaseExp -= 10000; -Note that 'getexp' is now subject to the 'quest_exp_rate' config option, -which adjusts the gained value. If you want to bypass this, use the 'set' -method. +When setting the parameters directly no bonuses or config options are applied. --------------------------------------- @@ -4166,29 +4412,29 @@ 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. + // 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; + setlook VAR_HEADPALETTE, 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; + // 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 VAR_BODYPALETTE,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 + +0 - Base sprite +1 - VAR_HEAD - Hairstyle +2 - VAR_WEAPON - Weapon +3 - VAR_HEAD_TOP - Head top +4 - VAR_HEAD_MID - Head mid +5 - VAR_HEAD_BOTTOM - Head bottom +6 - VAR_HEADPALETTE - Hair color +7 - VAR_BODYPALETTE - Clothes color +8 - VAR_SHIELD - Shield +9 - VAR_SHOES - 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 @@ -4224,9 +4470,9 @@ The knock-back is not restricted by items or map flags, only obstacles are taken into account. If there is not enough space to perform the push (e.g. due to a wall), the character is pushed only up to the obstacle. - // pushes the character 5 cells in 3 o'clock direction from it's - // current position. - pushpc DIR_EAST, 5; + // pushes the character 5 cells in 3 o'clock direction from it's + // current position. + pushpc DIR_EAST, 5; --------------------------------------- @@ -4236,13 +4482,13 @@ This command will return the SVN revision number or Git SHA-1 hash the server is currently running on (depends on whether you used a SVN or Git client for getting Hercules). - if ( get_version() >= 15000 ) - mes "Welcome Hercules!"; + if ( get_version() >= 15000 ) + mes "Welcome to Hercules!"; --------------------------------------- -\\ -4,1.- Item-related commands -\\ +//===================================== +4.1 - Player Item-Related Commands +//===================================== --------------------------------------- *getitem <item id>,<amount>{,<account ID>}; @@ -4256,8 +4502,8 @@ character inventory instead. In the first and most commonly used version of this command, items are referred to by their database ID number found in 'db/(pre-)re/item_db.txt'. - getitem 502,10 // The person will receive 10 apples - getitem 617,1 // The person will receive 1 Old Violet Box + getitem 502,10 // The person will receive 10 apples + getitem 617,1 // The person will receive 1 Old Violet Box Giving an item ID of -1 will give a specified number of random items from the list of those that fall out of Old Blue Box. Unlike in all other @@ -4303,12 +4549,12 @@ but is a lot more flexible. Those parameters that are different from 'getitem' are: -identify - Whether you want the item to be identified (1) or not (0). -refine - For how many pluses will it be refined. It will not let you - refine an item higher than the max refine. -attribute - Whether the item is broken (1) or not (0). -card1,2,3,4 - If you want a card compound to it, place the card ID number - into the specific card slot. +identify - Whether you want the item to be identified (1) or not (0). +refine - For how many pluses will it be refined. It will not let you + refine an item higher than the max refine. +attribute - Whether the item is broken (1) or not (0). +card1,2,3,4 - If you want a card compound to it, place the card ID number + into the specific card slot. Card1-card4 values are also used to store name information for named items, as well as the elemental property of weapons and armor. You can @@ -4323,70 +4569,115 @@ If you still want to try creating a named item with this command because 'getnameditem' won't do it for you cause it's too limited, you can do it like this. Careful, minor magic ahead. - // First, let's get an ID of a character who's name will be on the - // item. Only an existing character's name may be there. - // Let's assume our character is 'Adam' and find his ID. - - set @charid,getcharid(0,"Adam"); + // First, let's get an ID of a character who's name will be on the + // item. Only an existing character's name may be there. + // Let's assume our character is 'Adam' and find his ID. - // Now we split the character ID number into two portions with a - // binary shift operation. If you don't understand what this does, - // just copy it. - - set @card3, @charid & 65535; - set @card4, @charid >> 16; + .@charid = getcharid(0,"Adam"); - // If you're inscribing non-equipment, @card1 must be 254. - // Arrows are also not equipment. :) - set @card1,254; - - // For named equipment, card2 means the Star Crumbs and elemental - // crystals used to make this equipment. For everything else, it's 0. - - set @card2,0; - - // Now, let's give the character who invoked the script some - // Adam's Apples: - - getitem2 512,1,1,0,0,@card1,@card2,@card3,@card4; + // Now we split the character ID number into two portions with a + // binary shift operation. If you don't understand what this does, + // just copy it. + + .@card3 = .@charid & 65535; + .@card4 = .@charid >> 16; + + // If you're inscribing non-equipment, .@card1 must be 254. + // Arrows are also not equipment. :) + .@card1 = 254; + + // For named equipment, card2 means the Star Crumbs and elemental + // crystals used to make this equipment. For everything else, it's 0. + + .@card2 = 0; + + // Now, let's give the character who invoked the script some + // Adam's Apples: + + getitem2 512,1,1,0,0,.@card1,.@card2,.@card3,.@card4; This wasn't tested with all possible items, so I can't give any promises, experiment first before relying on it. To create equipment, continue this example it like this: - // We've already have card3 and card4 loaded with correct - // values so we'll just set up card1 and card2 with data - // for an Ice Stiletto. + // We've already have card3 and card4 loaded with correct + // values so we'll just set up card1 and card2 with data + // for an Ice Stiletto. - // If you're inscribing equipment, @card1 must be 255. - set @card1,255; - - // That's the number of star crumbs in a weapon. - set @sc,2; - - // That's the number of elemental property of the weapon. - set @ele,1; + // If you're inscribing equipment, .@card1 must be 255. + .@card1 = 255; - // And that's the wacky formula that makes them into - // a single number. - set @card2,@ele+((@sc*5)<<8); + // That's the number of star crumbs in a weapon. + .@sc = 2; - // That will make us an Adam's +2 VVS Ice Stiletto: - - getitem2 1216,1,1,2,0,@card1,@card2,@card3,@card4; + // That's the number of elemental property of the weapon. + .@ele = 1; + + // And that's the wacky formula that makes them into + // a single number. + .@card2 = .@ele+((.@sc*5)<<8); + + // That will make us an Adam's +2 VVS Ice Stiletto: + + getitem2 1216,1,1,2,0,.@card1,.@card2,.@card3,.@card4; Experiment with the number of star crumbs - I'm not certain just how much will work most and what it depends on. The valid element numbers are: 1 - Ice, 2 - Earth 3 - Fire 4 - Wind. - + You can, apparently, even create duplicates of the same pet egg with this command, creating a pet which is the same, but simultaneously exists in 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 (.@i = 0; .@i < getarraysize(@bound_items); ++.@i) + mes getitemname(@bound_items[.@i]); + close; + +--------------------------------------- *getnameditem <item id>,<character name|character ID>; *getnameditem "<item name>",<character name|character ID>; @@ -4434,11 +4725,11 @@ Note: 'delitem' in an NPC script can still remove rental items. This command will create an item lying around on a specified map in the specified location. - itemid - Found in 'db/(pre-)re/item_db.txt' - amount - Amount you want produced - map name - The map name - X - The X coordinate - Y - The Y coordinate. + itemid - Found in 'db/(pre-)re/item_db.txt' + amount - Amount you want produced + map name - The map name + X - The X coordinate + Y - The Y coordinate. This item will still disappear just like any other dropped item. Like 'getitem', it also accepts an 'english name' field from the database and @@ -4463,12 +4754,12 @@ matches the given one. It returns the number of items found. For performance reasons, the results array is limited to 10 items. mes "What item are you looking for?"; - input @name$; - set @qty, searchitem(@matches[0],@name$); - mes "I found "+@qty+" items:"; - for (set @i, 0; @i < @qty; set @i, @i+1) + input .@name$; + .@qty = searchitem(.@matches[0],.@name$); + mes "I found "+.@qty+" items:"; + for (.@i = 0; .@i < .@qty; ++.@i) //Display name (eg: "Apple[0]") - mes getitemname(@matches[@i])+"["+getitemslots(@matches[@i])+"]"; + mes getitemname(.@matches[.@i])+"["+getitemslots(.@matches[.@i])+"]"; --------------------------------------- @@ -4479,8 +4770,8 @@ This command will remove a specified amount of items from the invoking or target character. Like all the item commands, it uses the item ID found inside 'db/(pre-)re/item_db.txt'. - delitem 502,10; // The person will lose 10 apples - delitem 617,1; // The person will lose 1 Old Violet Box + delitem 502,10; // The person will lose 10 apples + delitem 617,1; // The person will lose 1 Old Violet Box It is always a good idea to check if the player actually has the items before you delete them. If you try to delete more items that the player @@ -4507,9 +4798,9 @@ Check 'getitem2' to understand its expanded parameters. This function will return the number of items for the specified item ID that the invoking character has in the inventory. - mes "[Item Checker]"; - mes "Hmmm, it seems you have "+countitem(502)+" apples"; - close; + mes "[Item Checker]"; + mes "Hmmm, it seems you have "+countitem(502)+" apples"; + close; Like 'getitem', this function will also accept an 'english name' from the database as an argument. @@ -4517,10 +4808,10 @@ database as an argument. If you want to state the number at the end of a sentence, you can do it by adding up strings: - mes "[Item Checker]"; - mes "Hmmm, the total number of apples you are holding is "+countitem("APPLE"); - close; - + mes "[Item Checker]"; + mes "Hmmm, the total number of apples you are holding is "+countitem("APPLE"); + close; + --------------------------------------- *countitem2(<item id>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>) @@ -4535,29 +4826,46 @@ Check 'getitem2' to understand the arguments of the function. --------------------------------------- -*groupranditem <group id>; +*groupranditem <item_id/constant>; -Returns the item_id of a random item picked from the group specified. The -different groups and their group number are specified in -'db/(pre-)re/item_group_db.txt'. +Returns the item_id of a random item picked from the item container specified. There +are different item containers and they are specified in 'db/(pre-)re/item_group.conf'. -When used in conjunction with other functions, you can get a random item. -For example, for a random pet lure: +Example: + getitem groupranditem 603,1; + getitem groupranditem Old_Blue_Box,1; + +--------------------------------------- -getitem groupranditem(15),1; +*getrandgroupitem <item_id/constant>,<quantity>; + +Similar to the above example, this command allows players to obtain the specified +quantity of a random item from the container. The different containers +are specified in 'db/(pre-)re/item_group.conf'. + +Example: + getrandgroupitem Old_Blue_Box,1; + getrandgroupitem 603,1; --------------------------------------- -*getrandgroupitem <group id>,<quantity>; +*packageitem -Similar to the above example, this command allows players to obtain the -specified quantity of a random item from the group "<group id>". The -different groups and their group number are specified in -db/(pre-)re/item_group_db.txt +This command has only 1 param which is optional. If the package item_id is not provided, it +will try to use the item id from the item it is being used from (if called from an item script). +It runs a item package and grants the items accordingly to the attached player. -For example, obtaining three of the same random item from Old Blue Box: +Example: -getrandgroupitem(1,3); +/* This example is an item script from the item db */ + { + Id: 12477 + AegisName: "Gift_Bundle" + Name: "Gift Bundle" + Type: 2 + Buy: 0 + Script: <" packageitem(); "> + }, --------------------------------------- @@ -4595,8 +4903,9 @@ skill requirements. --------------------------------------- -itemeffect <item id>; -itemeffect "<item name>"; +*itemeffect <item id>; +*itemeffect "<item name>"; +*consumeitem is an alias of itemeffect (added for compatibility) This command will run the item script of the specified item on the invoking character. The character does not need to posess the item, and @@ -4716,21 +5025,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>; @@ -4740,25 +5045,17 @@ of the invoking character. The item will be destroyed. This will also display a 'refine failure' effect on the character and put appropriate messages into their chat window. -The official scripts seems to use the 'failedrefitem' command as a -function instead: 'failedrefitem(<number>)' but it returns nothing on the -stack. This is since jAthena, so probably nobody knows for sure why is it -so. - --------------------------------------- -*downrefitem <equipment slot>; +*downrefitem <equipment slot>{,<downgrade_count>}; -This command will downgrade an item by - 1 in the specified equipment slot -of the invoking character. So the item will not be destroyed unlike in the +This command will downgrade an item by - 1 (unless optional <downgrade_count> is provided) +in the specified equipment slot of the invoking character. +So the item will not be destroyed unlike in the failedrefitem script command. This will also display a 'refine failure' effect on the character and put appropriate messages into their chat window. -The official scripts seems to use the 'downrefitem' command as a function -instead: 'downrefitem(<number>)' but it returns nothing on the stack. -This is since jAthena, so probably nobody knows for sure why is it so. - --------------------------------------- *unequip <equipment slot>; @@ -4781,7 +5078,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 @@ -4826,8 +5123,8 @@ happens when a result item is double-clicked and can be one of the following: 0 = Shows the store's position on the mini-map and highlights the shop - sign with yellow color, when the store is on same map as the - invoking player. + sign with yellow color, when the store is on same map as the + invoking player. 1 = Directly opens the shop, regardless of distance. Example: @@ -4836,9 +5133,19 @@ Example: searchstores 10,1; --------------------------------------- -// -4,1.- End of item-related commands -// + +*delequip <equipment slot>; + +This command will destroy whatever is currently equipped in the invoking +character's specified equipment slot. For a full list of possible equipment +slots see 'getequipid'. + +This command will return 1 if an item was deleted and 0 otherwise. + +--------------------------------------- +//===================================== +4.1 - End of Player Item-Related Commands +//===================================== --------------------------------------- *openstorage; @@ -4851,10 +5158,10 @@ The storage window opens regardless of whether there are open NPC dialogs or not, but it is preferred to close the dialog before displaying the storage window, to avoid any disruption when both windows overlap. - mes "I will now open your stash for you"; - close2; - openstorage; - end; + mes "I will now open your stash for you"; + close2; + openstorage; + end; --------------------------------------- @@ -4863,10 +5170,10 @@ storage window, to avoid any disruption when both windows overlap. This will open a character's Mail window on the client connected to the invoking character. - mes "Close this window to open your mail inbox."; - close2; - openmail; - end; + mes "Close this window to open your mail inbox."; + close2; + openmail; + end; --------------------------------------- @@ -4875,15 +5182,15 @@ invoking character. This will open the Auction window on the client connected to the invoking character. - mes "Close this window to open the Auction window."; - close2; - openauction; - end; + mes "Close this window to open the Auction window."; + close2; + openauction; + end; --------------------------------------- -\\ -4,2.- Guild-related commands -\\ +//===================================== +4.2 - Guild-Related Commands +//===================================== --------------------------------------- *guildopenstorage() @@ -4926,15 +5233,16 @@ This command will bump up the specified guild skill by the specified number of levels. This refers to the invoking character and will only work if the invoking character is a member of a guild AND it's guild master, otherwise no failure message will be given and no error will occur, but -nothing will happen - same about the guild skill trying to exceed the -possible maximum. The full list of guild skills is available in +nothing will happen. The full list of guild skills is available in 'db/(pre-)re/skill_db.txt', these are all the GD_ skills at the end. +If a level higher than the maximum is given as parameter the skill will be +leveled to the maximum and not above. // This would give your character's guild one level of Approval // (GD_APPROVAL ID 10000). Notice that if you try to add two levels of // Approval, or add Approval when the guild already has it, it will only // have one level of Approval afterwards. - guildskill 10000,1; + guildskill 10000,1; You might want to make a quest for getting a certain guild skill, make it hard enough that all the guild needs to help or something. Doing this for @@ -4943,9 +5251,9 @@ a good idea for a fun quest. (Wasting a level point on that is really annoying :D) --------------------------------------- -// -4,2 End of guild-related commands. -// +//===================================== +4.2 - End of Guild-Related Commands +//===================================== --------------------------------------- *resetlvl <action type>; @@ -5001,16 +5309,16 @@ Used in reset NPC's (duh!). These command bestow a status effect on the invoking character. This command is used a lot in the item scripts. - // This would poison them for 10 min - sc_start SC_Poison,600000,0; + // This would poison them for 10 min + sc_start SC_Poison,600000,0; Effect type is a number of effect, 'db/const.txt' lists the common (mostly negative) status effect types as constants, starting with 'SC_'. You can also use this to give someone an effect of a player-cast spell: - // This will bless someone as if with Bless 10: - sc_start 10,240000,10; - + // This will bless someone as if with Bless 10: + sc_start 10,240000,10; + Extra argument's meaning differs depending on the effect type, for most effects caused by a player skill the extra argument means the level of the skill that would have been used to create that effect, for others it might @@ -5031,7 +5339,7 @@ status change in question. For example, elemental armor defense takes the following four values: - val1 is the first element, val2 is the resistance to the element val1. - val3 is the second element, val4 is the resistance to said element. -eg: sc_start4 SC_DefEle,60000,Ele_Fire,20,Ele_Water,-15; +eg: sc_start4 SC_ARMOR_RESIST,300000,20,20,20,20; 'sc_end' will remove a specified status effect. If SC_All is used (-1), it will do a complete removal of all statuses (although permanent ones will @@ -5040,6 +5348,10 @@ re-apply). You can see the full list of status effects caused by skills in 'src/map/status.h' - they are currently not fully documented, but most of that should be rather obvious. +Note: to use SC_NOCHAT you should alter Manner + Manner = -5; // Will mute a user for 5 minutes + Manner = 0; // Will unmute a user + Manner = 5; // Will unmute a user and prevent the next use of 'Manner' --------------------------------------- @@ -5073,16 +5385,16 @@ command will not actually use the skill: it is intended for scripts which simulate skill usage by the NPC, such as buffs, by setting appropriate status and displaying the skill's effect. - mes "Be blessed!"; - // Heal of 2000 HP - heal 2000,0; - skilleffect 28,2000; - // Blessing Level 10 - sc_start 10,240000,10; - skilleffect 34,0; - // Increase AGI Level 5 - sc_start 12,140000,5; - skilleffect 29,0; + mes "Be blessed!"; + // Heal of 2000 HP + heal 2000,0; + skilleffect 28,2000; + // Blessing Level 10 + sc_start 10,240000,10; + skilleffect 34,0; + // Increase AGI Level 5 + sc_start 12,140000,5; + skilleffect 29,0; This will heal the character with 2000 HP, buff it with Blessing Lv 10 and Increase AGI Lv 5, and display appropriate effects. @@ -5137,8 +5449,9 @@ will retain the default behavior of the command. *statusup <stat>; This command will bump a specified stat of the invoking character up by -one permanently. Stats are to be given as number, but you can use these -constants to replace them: +one permanently using status points to do so, if there aren't enough to perform +the change nothing will happen. +Stats are to be given as number, but you can use these constants to replace them: bStr - Strength bVit - Vitality @@ -5152,10 +5465,11 @@ bLuk - Luck *statusup2 <stat>,<amount>; This command will bump a specified stat of the invoking character up by -the specified amount permanently. Amount can be negative. See 'statusup'. +the specified amount permanently without using status points. +Amount can be negative. See 'statusup'. // This will decrease a character's Vit forever. - statusup bVit,-1; + statusup bVit,-1; --------------------------------------- @@ -5262,10 +5576,6 @@ Flag 3 is the same as flag 0 in that it saves to the database. However, these skills are ignored when any action is taken that adjusts the skill tree (reset/job change). -Flag 4 is the same as flag 1 in that it saves to the database. However, -these skills are ignored when any action is taken that adjusts the skill -tree (reset/job change). - --------------------------------------- *nude; @@ -5290,9 +5600,9 @@ next; undisguise; // Return to normal character sprite. --------------------------------------- -\\ -4,3 Marriage-related commands -\\ +//===================================== +4.3 - Marriage-Related Commands +//===================================== --------------------------------------- *marriage("<spouse name>"); @@ -5331,9 +5641,9 @@ This function will also destroy both wedding rings and send a message to both players, telling them they are now divorced. --------------------------------------- -// -4,3.- End of marriage-related commands -// +//===================================== +4.3 - End of Marriage-Related Commands +//===================================== --------------------------------------- *pcfollow <id>,<target id>; @@ -5347,10 +5657,10 @@ Examples: // This will make Aaron follow Bullah, when both of these characters are // online. - PCFollow getCharID(3,"Aaron"),getCharID(3,"Bullah"); + pcfollow getcharid(3,"Aaron"),getcharid(3,"Bullah"); // Makes Aaron stop following whoever he is following. - PCStopFollow getCharID(3,"Aaron"); + pcstopfollow getcharid(3,"Aaron"); --------------------------------------- @@ -5369,15 +5679,21 @@ Examples: // Enables the current char to move again. pcblockmove getcharid(3),0; ---------------------------------------- -================================== -|5.- Mob / NPC -related commands.| -================================== +--------------------------------------- +//===================================== +4 - End of Player-Related Commands +//===================================== --------------------------------------- -*monster "<map name>",<x>,<y>,"<name to show>",<mob id>,<amount>{,"<event label>",<size>,<ai>}; -*areamonster "<map name>",<x1>,<y1>,<x2>,<y2>,"<name to show>",<mob id>,<amount>{,"<event label>",<size>,<ai>}; +--------------------------------------- +//===================================== +5 - Mob / NPC Related Commands +//===================================== +--------------------------------------- + +*monster "<map name>",<x>,<y>,"<name to show>",<mob id>,<amount>{,"<event label>"{,<size>{,<ai>}}}; +*areamonster "<map name>",<x1>,<y1>,<x2>,<y2>,"<name to show>",<mob id>,<amount>{,"<event label>"{,<size>{,<ai>}}}; This command will spawn a monster on the specified coordinates on the specified map. If the script is invoked by a character, a special map @@ -5412,7 +5728,7 @@ the RID of the killing character. 3 = flora (Alchemist skill) 4 = zanzou (Kagerou/Oboro skill) - monster "place",60,100,"Poring",1002,1,"NPCNAME::OnLabel"; + monster "place",60,100,"Poring",1002,1,"NPCNAME::OnLabel"; The coordinates of 0,0 will spawn the monster on a random place on the map. Both 'monster' and 'areamonster' return the GID of the monster @@ -5420,19 +5736,19 @@ spawned if there was ONLY ONE monster to be spawned. This is useful for controlling each of the spawned mobs with the unit* commands shown below. For example: - // We'll make a poring which will automatically attack invoking player: - set .@mobGID, monster "Prontera",150,150,"Poring",1002,1; - unitattack .@mobGID, getcharid(3); // Attacker GID, attacked GID + // We'll make a poring which will automatically attack invoking player: + .@mobGID = monster "Prontera",150,150,"Poring",PORING,1; // PORING is defined in the mob db and its value is 1002 + unitattack .@mobGID, getcharid(3); // Attacker GID, attacked GID The way you can get the GID of more than only one monster is looping through all the summons to get their individual GIDs and do whatever you want with them. For example: - // We want to summon .mobnumber porings which will give us a kiss - for (set .@i, 0; .@i < .mobnumber; set .@i, .@i + 1){ - set .@mobGID, monster "map",.x,.y,"Kisser Poring",1002,1; - unitemote .@mobGID, e_kis; - } + // We want to summon .mobnumber porings which will give us a kiss + for (.@i = 0; .@i < .mobnumber; ++.@i) { + .@mobGID = monster "map",.x,.y,"Kisser Poring",PORING,1; + unitemote .@mobGID, e_kis; + } Refer to the unit* commands below. @@ -5442,29 +5758,28 @@ by x1/y1-x2/y2. Simple monster killing script: - <NPC object definition. Let's assume you called him NPCNAME.> - mes "[Summon Man]"; - mes "Want to start the kill?"; - next; - menu "Yes",L_Yes,"No",-; - mes "[Summon Man]"; - mes "Come back later"; - close; - L_Yes: - monster "prontera",0,0,"Quest Poring",1002,10,"NPCNAME::OnPoringKilled"; - // By using 0,0 it will spawn them in a random place. - mes "[Summon Man]"; - mes "Now go and kill all the Poring I summoned"; - // He summoned ten. - close; - OnPoringKilled: - set $PoringKilled,$PoringKilled+1; - if ($PoringKilled==10) goto L_AllDead; - end; - L_AllDead: - announce "Summon Man: Well done all the poring are dead",3; - set $PoringKilled,0; - end; + <NPC object definition. Let's assume you called him NPCNAME.> + mes "[Summon Man]"; + mes "Want to start the kill?"; + next; + if (select("Yes:No") != 1) { + mes "[Summon Man]"; + mes "Come back later"; + close; + } + monster "prontera",0,0,"Quest Poring",PORING,10,"NPCNAME::OnPoringKilled"; + // By using 0,0 it will spawn them in a random place. + mes "[Summon Man]"; + mes "Now go and kill all the Poring I summoned"; + // He summoned ten. + close; + OnPoringKilled: + ++$poring_killed; + if ($poring_killed == 10) { + announce "Summon Man: Well done all the poring are dead",bc_self; + $poring_killed = 0; + } + end; For more examples see just about any official 2-1 or 2-2 job quest script. @@ -5549,9 +5864,11 @@ commands can have non-empty event label. If you pass this function an empty string for the event label, it will return the total count of monster without event label, including permanently spawning monsters. + With the dynamic mobs system enabled, where mobs are not kept in memory for maps with no actual people playing on them, this will return a 0 for any such map. + If the event label is given as "all", all monsters will be counted, regardless of having any event label attached. @@ -5620,20 +5937,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. @@ -5650,26 +5993,12 @@ 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>; +*unitwalk <GID>,<target_GID>; This is one command, but can be used in two ways. If only the first argument is given, the unit whose GID is given will start walking towards -the map with the given mapid (we believe these are the map-indexes found -in db/map_index.txt). +the target whose GID is given. When 2 arguments are passed, the given unit will walk to the given x,y coordinates on the map where the unit currently is. @@ -5679,9 +6008,8 @@ Examples: //Will move/walk the poring we made to the coordinates 150,150 unitwalk .GID,150,150; -//Will move the poring towards alberta (if my assumed map-indexes are -//correct). - unitwalk .GID,3; +//NPC will move towards the attached player. + unitwalk .GID,getcharid(3);//a player's GID is their account ID --------------------------------------- @@ -5747,17 +6075,17 @@ The script of the NPC object invoked in this manner will run as if it's been invoked by the RID that was active in the script that issued a 'doevent'. As such, the command will not work if an RID is not attached. - place,100,100,1%TAB%script%TAB%NPC%TAB%53,{ - mes "This is what you will see when you click me"; - close; - OnLabel: - mes "This is what you will see if the doevent is activated"; - close; - } + place,100,100,1%TAB%script%TAB%NPC%TAB%53,{ + mes "This is what you will see when you click me"; + close; + OnLabel: + mes "This is what you will see if the doevent is activated"; + close; + } - .... + .... - doevent "NPC::OnLabel"; + doevent "NPC::OnLabel"; --------------------------------------- @@ -5779,25 +6107,25 @@ This command can be used to make other NPCs act, as if they were responding to the invoking NPC's actions, such as using an emotion or talking. - place,100,100,1%TAB%script%TAB%NPC%TAB%53,{ - mes "Hey NPC2 copy what I do"; - close2; - set .@emote, rand(1,30); - donpcevent "NPC2::OnEmote"; - OnEmote: - emotion .@emote; - end; - } + place,100,100,1%TAB%script%TAB%NPC%TAB%53,{ + mes "Hey NPC2 copy what I do"; + close2; + @emote = rand(1,30); + donpcevent "NPC2::OnEmote"; + OnEmote: + emotion @emote; + end; + } - place,102,100,1%TAB%script%TAB%NPC2%TAB%53,{ - mes "Hey NPC copy what I do"; - close2; - set .@emote, rand(1,30); - donpcevent "NPC::OnEmote"; - OnEmote: - emotion .@emote; - end; - } + place,102,100,1%TAB%script%TAB%NPC2%TAB%53,{ + mes "Hey NPC copy what I do"; + close2; + @emote = rand(1,30); + donpcevent "NPC::OnEmote"; + OnEmote: + emotion @emote; + end; + } Whichever of the both NPCs is talked to, both will show a random emotion at the same time. @@ -5821,9 +6149,9 @@ object running it was a player talking - that is, above their head and in the chat window. The display name of the NPC will get appended in front of the message to complete the effect. - // This will make everyone in the area see the NPC greet the character - // who just invoked it. - npctalk "Hello "+strcharinfo(0)+", how are you?"; + // This will make everyone in the area see the NPC greet the character + // who just invoked it. + npctalk "Hello "+strcharinfo(0)+", how are you?"; --------------------------------------- @@ -5837,13 +6165,14 @@ Returns 0 is successful, 1 if the NPC does not exist. Size is 0 = normal 1 = small 2 = big. --------------------------------------- -\\ -5,1.- Time-related commands -\\ +//===================================== +5.1 - Time-Related Commands +//===================================== --------------------------------------- + *addtimer <ticks>,"NPC::OnLabel"; *deltimer "NPC::OnLabel"; -*addtimercount <ticks>,"NPC::OnLabel"; +*addtimercount "NPC::OnLabel",<ticks>; These commands will create, destroy, and delay a countdown timer - 'addtimer' to create, 'deltimer' to destroy and 'addtimercount' to delay @@ -5875,16 +6204,16 @@ On5secs: --------------------------------------- -*initnpctimer{ "<NPC name>" {, <Attach Flag>} } | - { "<NPC name>" | <Attach Flag> }; -*stopnpctimer{ "<NPC name>" {, <Detach Flag>} } | - { "<NPC name>" | <Detach Flag> }; -*startnpctimer{ "<NPC name>" {, <Attach Flag>} } | - { "<NPC name>" | <Attach Flag> }; -*setnpctimer <tick>{,"<NPC name>"}; -*getnpctimer(<type of information>{,"<NPC name>"}) -*attachnpctimer {"<character name>"}; -*detachnpctimer {"<NPC name>"}; +*initnpctimer { "<NPC name>" {, <Attach Flag>} } | + { "<NPC name>" | <Attach Flag> }; +*stopnpctimer { "<NPC name>" {, <Detach Flag>} } | + { "<NPC name>" | <Detach Flag> }; +*startnpctimer { "<NPC name>" {, <Attach Flag>} } | + { "<NPC name>" | <Attach Flag> }; +*setnpctimer <tick>{,"<NPC name>"}; +*getnpctimer (<type of information>{,"<NPC name>"}) +*attachnpctimer {"<character name>"}; +*detachnpctimer {"<NPC name>"}; This set of commands and functions will create and manage an NPC-based timer. The NPC name may be omitted, in which case the calling NPC is used @@ -5930,80 +6259,80 @@ The 'setnpctimer' command will explicitly set the timer to a given tick. 0 - Will return the current tick count of the timer. 1 - Will return 1 if there are remaining "OnTimer<ticks>:" labels in the - specified NPC waiting for execution. + specified NPC waiting for execution. 2 - Will return the number of times the timer has triggered and will - trigger an "OnTimer<tick>:" label in the specified NPC. + trigger an "OnTimer<tick>:" label in the specified NPC. Example 1: - <NPC Header> { - // We need to use attachnpctimer because the mes command below - // needs RID attach - attachnpctimer; - initnpctimer; - npctalk "I cant talk right now, give me 10 seconds"; - end; - OnTimer5000: - npctalk "Ok 5 seconds more"; - end; - OnTimer6000: - npctalk "4"; - end; - OnTimer7000: - npctalk "3"; - end; - OnTimer8000: - npctalk "2"; - end; - OnTimer9000: - npctalk "1"; - end; - OnTimer10000: - stopnpctimer; - mes "[Man]"; - mes "Ok we can talk now"; - detachnpctimer; - // and remember attachnpctimer and detachnpctimer can only be used - // while the NPC timer is not running! - } + <NPC Header> { + // We need to use attachnpctimer because the mes command below + // needs RID attach + attachnpctimer; + initnpctimer; + npctalk "I cant talk right now, give me 10 seconds"; + end; + OnTimer5000: + npctalk "Ok 5 seconds more"; + end; + OnTimer6000: + npctalk "4"; + end; + OnTimer7000: + npctalk "3"; + end; + OnTimer8000: + npctalk "2"; + end; + OnTimer9000: + npctalk "1"; + end; + OnTimer10000: + stopnpctimer; + mes "[Man]"; + mes "Ok we can talk now"; + detachnpctimer; + // and remember attachnpctimer and detachnpctimer can only be used + // while the NPC timer is not running! + } Example 2: - OnTimer15000: - npctalk "Another 15 seconds have passed."; + OnTimer15000: + npctalk "Another 15 seconds have passed."; - // You have to use 'initnpctimer' instead of 'setnpctimer 0'. - // This is equal to 'setnpctimer 0' + 'startnpctimer'. - // Alternatively, you can also insert another 'OnTimer15001' label - // so that the timer won't stop. - initnpctimer; - end; - - // This OnInit label will run when the script is loaded, so that the - // timer is initialized immediately as the server starts. It is - // dropped back to 0 every time the NPC says something, so it will - // cycle continuously. - OnInit: - initnpctimer; - end; + // You have to use 'initnpctimer' instead of 'setnpctimer 0'. + // This is equal to 'setnpctimer 0' + 'startnpctimer'. + // Alternatively, you can also insert another 'OnTimer15001' label + // so that the timer won't stop. + initnpctimer; + end; + + // This OnInit label will run when the script is loaded, so that the + // timer is initialized immediately as the server starts. It is + // dropped back to 0 every time the NPC says something, so it will + // cycle continuously. + OnInit: + initnpctimer; + end; Example 3: - mes "[Man]"; - mes "I have been waiting "+(getnpctimer(0)/1000)+" seconds for you."; - // We divide the timer returned by 1000 to convert milliseconds to - // seconds. - close; + mes "[Man]"; + mes "I have been waiting "+(getnpctimer(0)/1000)+" seconds for you."; + // We divide the timer returned by 1000 to convert milliseconds to + // seconds. + close; Example 4: - mes "[Man]"; - mes "Ok, I will let you have 30 more seconds..."; - close2; - setnpctimer (getnpctimer(0)-30000); - // Notice the 'close2'. If there were a 'next' there the timer would - // be changed only after the player pressed the 'next' button. - end; + mes "[Man]"; + mes "Ok, I will let you have 30 more seconds..."; + close2; + setnpctimer (getnpctimer(0)-30000); + // Notice the 'close2'. If there were a 'next' there the timer would + // be changed only after the player pressed the 'next' button. + end; --------------------------------------- @@ -6021,11 +6350,11 @@ will not keep the rid, while sleep2 does. Examples: // This will pause the script for 10 seconds and ditch the RID - // (so no player is attached anymore) - sleep 10000; - // Pauses the script for 5 seconds, and continue with the RID attached. + // (so no player is attached anymore) + sleep 10000; + // Pauses the script for 5 seconds, and continue with the RID attached. sleep2 5000; - //Cancels any running sleep timers on the NPC 'NPC'. + //Cancels any running sleep timers on the NPC 'NPC'. awake "NPC"; --------------------------------------- @@ -6040,16 +6369,17 @@ color format is in RGB (0xRRGGBB). The color is currently ignored by the client and appears always green. --------------------------------------- -// -5,1.- End of time-related commands -// +//===================================== +5.1 - End of Time-related commands +//===================================== +--------------------------------------- *announce "<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}}; This command will broadcast a message to all or most players, similar to @kami/@kamib GM commands. - announce "This will be shown to everyone at all in yellow.",0; + announce "This will be shown to everyone at all in yellow.",0; The region the broadcast is heard in (target), source of the broadcast and the color the message will come up as is determined by the flags. @@ -6058,25 +6388,25 @@ The flag values are coded as constants in db/const.txt to make them easier to use. Target flags: -- bc_all: Broadcast message is sent server-wide (default). -- bc_map: Message is sent to everyone in the same map as the source of - the broadcast (see below). -- bc_area: Message is sent to players in the vicinity of the source. -- bc_self: Message is sent only to current player. -You cannot use more than one target flag. +- bc_all: Broadcast message is sent server-wide (default). +- bc_map: Message is sent to everyone in the same map as the source of + the broadcast (see below). +- bc_area: Message is sent to players in the vicinity of the source. +- bc_self: Message is sent only to current player. +You cannot use more than one target flag. Source flags: -- bc_pc: Broadcast source is the attached player (default). -- bc_npc: Broadcast source is the NPC, not the player attached to the - script (useful when a player is not attached or the message - should be sent to those nearby the NPC). +- bc_pc: Broadcast source is the attached player (default). +- bc_npc: Broadcast source is the NPC, not the player attached to the + script (useful when a player is not attached or the message + should be sent to those nearby the NPC). You cannot use more than one source flag. Special flags: -- bc_yellow: Broadcast will be displayed in yellow color (default). -- bc_blue: Broadcast will be displayed in blue color. -- bc_woe: Indicates that this broadcast is 'WoE Information' that can - be disabled client-side. +- bc_yellow:Broadcast will be displayed in yellow color (default). +- bc_blue: Broadcast will be displayed in blue color. +- bc_woe: Indicates that this broadcast is 'WoE Information' that can + be disabled client-side. Due to the way client handles broadcasts, it is impossible to set both bc_blue and bc_woe. @@ -6089,7 +6419,7 @@ The color parameter is a single number which can be in hexadecimal notation. For example: - announce "This will be shown to everyone at all in green.",bc_all,0x00FF00; + announce "This will be shown to everyone at all in green.",bc_all,0x00FF00; Will display a global announce in green. The color format is in RGB (0xRRGGBB). @@ -6102,12 +6432,12 @@ Default font size is 12. Using this for private messages to players is probably not that good an idea, but it can be used instead in NPCs to "preview" an announce. - // This will be a private message to the player using the NPC that - // made the announcement - announce "This is my message just for you",bc_blue|bc_self; + // This will be a private message to the player using the NPC that + // made the announcement + announce "This is my message just for you",bc_blue|bc_self; - // This will be shown on everyones screen that is in sight of the NPC. - announce "This is my message just for you people here",bc_npc|bc_area; + // This will be shown on everyones screen that is in sight of the NPC. + announce "This is my message just for you people here",bc_npc|bc_area; --------------------------------------- @@ -6127,7 +6457,7 @@ residing in the specified x1/y1-x2/y2 rectangle on the map given. The flags and optional parameters are the same as in 'announce', but target and source flags are ignored. - areaannounce "prt_church",0,0,350,350,"God's in his heaven, all right with the world",0; + areaannounce "prt_church",0,0,350,350,"God's in his heaven, all right with the world",0; --------------------------------------- @@ -6241,7 +6571,7 @@ amount. // The NPC will just show a box above its head that says "Hello World", // clicking it will do nothing, since the limit is zero. - waitingroom "Hello World",0; + waitingroom "Hello World",0; // The NPC will have a box above its head, with "Disco - Waiting Room" // written on it, and will have 8 waiting slots. Clicking this will enter @@ -6249,7 +6579,7 @@ amount. // accumulate. Once this happens, it will cause the NPC "Bouncer" run the // label "OnStart". - waitingroom "Disco - Waiting Room",8,"Bouncer::OnStart",7; + waitingroom "Disco - Waiting Room",8,"Bouncer::OnStart",7; // The NPC will have a box above its head, with "Party - Waiting Room" // written on it, and will have 8 waiting slots. Clicking this will allow @@ -6257,7 +6587,7 @@ amount. // the player will be able to wait until 7 players accumulate. Once this // happens, it will cause the NPC "Bouncer" run the label "OnStart". - waitingroom "Party - Waiting Room",8,"Bouncer::OnStart",7,5000,50,99; + waitingroom "Party - Waiting Room",8,"Bouncer::OnStart",7,5000,50,99; Creating a waiting room does not stop the execution of the script and it will continue to the next line. @@ -6395,14 +6725,11 @@ may be a number or a string depending on the mapflag in question. --------------------------------------- -*removemapflag "<map name>",<flag>{,<zone>}; +*removemapflag "<map name>",<flag>; This command removes a mapflag from a specified map. See 'setmapflag' for a list of mapflags. -The zone optional parameter is used to remove the zone from restricted -mapflags. - --------------------------------------- *getmapflag("<map name>",<flag>) @@ -6423,11 +6750,11 @@ used in Lupus' variable rates script. Examples: // Will set the base experience rate to 20x (2000%) - setBattleFlag "base_exp_rate",2000; + setbattleflag "base_exp_rate",2000; // Will return the value of the base experience rate (when used after the // above example, it would print 2000). - mes getBattleFlag("base_exp_rate"); + mes getbattleflag("base_exp_rate"); --------------------------------------- @@ -6465,9 +6792,9 @@ Example: mapwarp "prontera","alberta",150,150,1,63; --------------------------------------- -\\ -5,2.- Guild-related Commands -\\ +//===================================== +5.2 - Guild-Related Commands +//===================================== --------------------------------------- *maprespawnguildid "<map name>",<guild id>,<flag>; @@ -6534,7 +6861,7 @@ which returns a guild id: // This will change the emblem on the flag to that of the guild that owns // "guildcastle" - flagemblem GetCastleData("guildcastle",1); + flagemblem getcastledata("guildcastle",1); --------------------------------------- @@ -6565,9 +6892,9 @@ Type indicates what information to return: 2 - current hp --------------------------------------- -// -5,2.- End of guild-related commands -// +//===================================== +5.2 - End of Guild-Related Commands +//===================================== --------------------------------------- *npcspeed <speed value>; @@ -6601,9 +6928,9 @@ by defining a job-sprite based sprite id in 'db/mob_avail.txt' with this. *movenpc "<NPC name>",<x>,<y>{,<dir>}; -This command looks like the NPCWalkToxy function,but is a little different. +This command looks like the npcwalktoxy function,but is a little different. -While NPCWalkToXY just makes the NPC 'walk' to the coordinates given +While npcwalktoxy just makes the NPC 'walk' to the coordinates given (which sometimes gives problems if the path isn't a straight line without objects), this command just moves the NPC. It basically warps out and in on the current and given spot. Direction can be used to change the NPC's @@ -6613,23 +6940,23 @@ Example: // This will move Bugga from to the coordinates 100,20 (if those // coordinates are legit). - moveNPC "Bugga",100,20; - ---------------------------------------- + movenpc "Bugga",100,20; -===================== -|6.- Other commands.| -===================== +--------------------------------------- +//===================================== +6 - Other Commands +//===================================== --------------------------------------- *debugmes "<message>"; 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!"; - +// + // 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>"; @@ -6681,23 +7008,23 @@ Point number is the number of the point - you can have several. If more than one point is drawn at the same coordinates, they will cycle, which can be used to create flashing marks. - // This command will show a mark at coordinates X 30 Y 40, is mark - // number 1, and will be red. - - viewpoint 1,30,40,1,0xFF0000; + // This command will show a mark at coordinates X 30 Y 40, is mark + // number 1, and will be red. + + viewpoint 1,30,40,1,0xFF0000; This will create three points: - viewpoint 1,30,40,1,0xFF0000; - viewpoint 1,35,45,2,0xFF0000; - viewpoint 1,40,50,3,0xFF0000; + viewpoint 1,30,40,1,0xFF0000; + viewpoint 1,35,45,2,0xFF0000; + viewpoint 1,40,50,3,0xFF0000; And this is how you remove them: - viewpoint 2,30,40,1,0xFF0000; - viewpoint 2,35,45,2,0xFF0000; - viewpoint 2,40,50,3,0xFF0000; - + viewpoint 2,30,40,1,0xFF0000; + viewpoint 2,35,45,2,0xFF0000; + viewpoint 2,40,50,3,0xFF0000; + The client determines what it does with the points entirely, the server keeps no memory of where the points are set whatsoever. @@ -6709,11 +7036,11 @@ This command will display a picture, usually an NPC illustration, also called cutin, for the currently attached client. The position parameter determines the placement of the illustration and takes following values: - 0 - bottom left corner - 1 - bottom middle - 2 - bottom right corner - 3 - middle of screen in a movable window with an empty title bar - 4 - middle of screen without the window header, but still movable + 0 - bottom left corner + 1 - bottom middle + 2 - bottom right corner + 3 - middle of screen in a movable window with an empty title bar + 4 - middle of screen without the window header, but still movable The picture is read from data\texture\???????\illust, from both the GRF archive and data folder, and is required to be a bitmap. The file @@ -6729,15 +7056,15 @@ one will cause the old one to disappear. To delete the currently displayed illustration without displaying a new one, an empty file name and position 255 must be used. - // Displays the Comodo Kafra illustration in lower right corner. - cutin "kafra_07",2; + // Displays the Comodo Kafra illustration in lower right corner. + cutin "kafra_07",2; - // Typical way to end a script, which displayed an illustration during a - // dialog with a player. - mes "See you."; - close2; - cutin "",255; - end; + // Typical way to end a script, which displayed an illustration during a + // dialog with a player. + mes "See you."; + close2; + cutin "",255; + end; --------------------------------------- @@ -6811,11 +7138,11 @@ 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'). +character only ('playbgm') or multiple characters ('playbgmall'). BGM filename is the filename in /BGM/ folder. It has to be in .mp3 extension, but it's not required to specify the extension in the script. @@ -6842,10 +7169,10 @@ This command will run the given command line exactly as if it was typed in from the keyboard by the player connected to the invoking character, and that character belonged to an account which had GM level 99. - // This will ask the invoker for a character name and then use the - // '@nuke' GM command on them, killing them mercilessly. - input @player$; - atcommand "@nuke "+@player$; + // This will ask the invoker for a character name and then use the + // '@nuke' GM command on them, killing them mercilessly. + input .@player$; + atcommand "@nuke "+.@player$; This command has a lot of good uses, I am sure you can have some fun with this one. @@ -6860,9 +7187,9 @@ GM level 99. The commands can also run without an attached rid. - // This would do the same as above, but now - // it doesn't need a player attached by default. - charcommand "#option 0 0 0 Roy"; + // This would do the same as above, but now + // it doesn't need a player attached by default. + charcommand "#option 0 0 0 Roy"; --------------------------------------- @@ -6924,7 +7251,7 @@ This is the replacement of the older commands, these use the same values for GID as the other unit* commands (See 'GID'). Skill ID is the ID of the skill, skill level is the level of the skill. -For the position, the x and y are given in the unitSkillUsePos. +For the position, the x and y are given in the unitskillusepos. --------------------------------------- @@ -6940,9 +7267,9 @@ value, and "NPC level" is the temporary level of the NPC (used in some skills). Neither value can be greater than the max level defined in config, and will not work properly if the NPC has a mob sprite. - // Casts Level 10 Heal on the attached player, calculated with - // all stats 99 and base level 60. - npcskill "AL_HEAL",10,99,60; + // Casts Level 10 Heal on the attached player, calculated with + // all stats 99 and base level 60. + npcskill "AL_HEAL",10,99,60; --------------------------------------- @@ -6975,15 +7302,54 @@ script is used. --------------------------------------- +*pcre_match("<string>","<regex>"); + +This command is only available if the server is compiled with regular +expressions library enabled. + +The string <string> will be searched for a match to the regular expression +<regex>, and the number of matches will be returned. + +An alternative way to invoke this command is to use the operators '~=' or '~!'. +The operator '~=' is exactly the same as pcre_match, while the operator '~!' +will return 1 if no matches were found, or 0 if at least a match was found. + + if (pcre_match("string", "regex")) mes "There was a match."; + if ("string" ~= "regex") mes "There was a match."; + if ("string" ~! "regex") mes "There were no matches."; + +You can find more usage examples in the test script npc/custom/test.txt. + +Using regular expressions is high wizardry. But with this high wizardry +comes unparalleled power of text manipulation. For an explanation of what +a regular expression pattern is, see a few web pages: + +http://www.regular-expressions.info/ +http://www.weitz.de/regex-coach/ + +Additionally, the following temporary variables will be filled (unless the +command is invoked as '~!'): + +- $@regexmatchcount: The number of matches detected, including any + parenthesized capture-groups. +- $@regexmatch$[0]: The part of <string> That matched the full <regex> pattern. +- $@regexmatch$[1 .. $@regexmatchcount]: The parts of <string> that matched + each of the parenthesized capture-groups in <pattern>. + +A capture group is a part of a regex enclosed in (parentheses) in order to +store in a variable the part of the expression that was matched by that part of +the regex. For more details, see the links above, as this is not intended to be +a regex tutorial. + +--------------------------------------- + *defpattern <set number>,"<regular expression pattern>","<event label>"; *activatepset <set number>; *deactivatepset <set number>; *deletepset <set number>; This set of commands is only available if the server is compiled with -regular expressions library enabled. Default compilation and most binary -distributions aren't, which is probably bad, since these, while complex to -use, are quite fascinating. +regular expressions library enabled. They will make the NPC object listen for text spoken publicly by players and match it against regular expression patterns, then trigger labels @@ -7007,13 +7373,6 @@ pattern set number in this case will deactivate all pattern sets defined. 'deletepset' will delete a pattern set from memory, so you can create a new pattern set in its place. -Using regular expressions is high wizardry. But with this high wizardry -comes unparalleled power of text manipulation. For an explanation of what -a regular expression pattern is, see a few web pages: - -http://www.regular-expressions.info/ -http://www.weitz.de/regex-coach/ - For an example of this in use, see doc/sample/npc_test_pcre.txt With this you could, for example, automatically punish players for asking @@ -7027,7 +7386,7 @@ instead if they want it so much. Returns the result of the calculation. Example: -set @i, pow(2,3); // @i will be 8 + .@i = pow(2,3); // .@i will be 8 --------------------------------------- @@ -7036,7 +7395,7 @@ set @i, pow(2,3); // @i will be 8 Returns square-root of number. Example: -set @i, sqrt(25); // @i will be 5 + .@i = sqrt(25); // .@i will be 5 --------------------------------------- @@ -7045,7 +7404,7 @@ set @i, sqrt(25); // @i will be 5 Returns distance between 2 points. Example: -set @i, distance(100,200,101,202); + .@i = distance(100,200,101,202); --------------------------------------- @@ -7070,13 +7429,13 @@ Note that 'query_sql' runs on the main database while 'query_logsql' runs on the log database. Example: -set @nb, query_sql("select name,fame from `char` ORDER BY fame DESC LIMIT 5", @name$, @fame); -mes "Hall Of Fame: TOP5"; -mes "1."+@name$[0]+"("+@fame[0]+")"; // Will return a person with the biggest fame value. -mes "2."+@name$[1]+"("+@fame[1]+")"; -mes "3."+@name$[2]+"("+@fame[2]+")"; -mes "4."+@name$[3]+"("+@fame[3]+")"; -mes "5."+@name$[4]+"("+@fame[4]+")"; + .@nb = query_sql("select name,fame from `char` ORDER BY fame DESC LIMIT 5", .@name$, .@fame); + mes "Hall Of Fame: TOP5"; + mes "1."+.@name$[0]+"("+.@fame[0]+")"; // Will return a person with the biggest fame value. + mes "2."+.@name$[1]+"("+.@fame[1]+")"; + mes "3."+.@name$[2]+"("+.@fame[2]+")"; + mes "4."+.@name$[3]+"("+.@fame[3]+")"; + mes "5."+.@name$[4]+"("+.@fame[4]+")"; --------------------------------------- @@ -7086,8 +7445,8 @@ Converts the value to a string and escapes special characters so that it's safe to use in query_sql(). Returns the escaped form of the given value. Example: - set .@str$, "John's Laptop"; - set .@esc_str$, escape_sql(.@name$); // Escaped string: John\'s Laptop + .@str$ = "John's Laptop"; + .@esc_str$ = escape_sql(.@name$); // Escaped string: John\'s Laptop --------------------------------------- @@ -7107,7 +7466,7 @@ Valid types are: Example: -setiteminfo 7049,6,9990; // Stone now weighs 999.0 +setiteminfo Stone, 6, 9990; // Stone now weighs 999.0 --------------------------------------- @@ -7124,25 +7483,36 @@ Type can optionally be used indicates which script to set (default is 0): Example: -setitemscript 2637,"{ if(isequipped(2236)==0)end; if(getskilllv(26)){skill 40,1;}else{skill 26,1+isequipped(2636);} }"; -setitemscript 2637,""; +setitemscript Silver_Ring_, "{ if(isequipped(2236)==0)end; if(getskilllv(26)){skill 40,1;}else{skill 26,1+isequipped(2636);} }"; +setitemscript Silver_Ring_, ""; --------------------------------------- -*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) --------------------------------------- @@ -7183,47 +7553,47 @@ The first letter is position 0. Returns char at specified index. If index is out of range, returns an 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 is 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: - + insertchar("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>) @@ -7231,9 +7601,9 @@ Example: 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!!" --------------------------------------- @@ -7246,21 +7616,21 @@ uppercase for 'charisupper' or lowercase for 'charislower'. Otherwise, 0. Characters not of the alphabelt will return 0. Example: - + charisupper("Hercules", 0); //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>) @@ -7272,7 +7642,7 @@ as a delimiter, the string will be placed in the array in its original form, without any changes. Example: - + explode(.@my_array$, "Explode:Test:1965:red:PIE", ":"); //.@my_array$ contents will be... //.@my_array$[0]: "Explode" @@ -7288,14 +7658,14 @@ Example: 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[,...]]]) +*sprintf(<format>{,param{,param{,...}}}) C style sprintf. The resulting string is returned same as in PHP. All C format specifiers are supported except %n. For more info check sprintf @@ -7303,16 +7673,16 @@ function at www.cplusplus.com Number of params is only limited by Hercules' script engine. Example: - .@format$ = 'The %s contains %d monkeys'; + .@format$ = "The %s contains %d monkeys"; dispbottom(sprintf(.@format$, "zoo", 5)); - //prints "The zoo contains 5 monkeys" + //prints "The zoo contains 5 monkeys" + + dispbottom(sprintf(.@format$, "barrel", 82)); + //prints "The barrel contains 82 monkeys" - dispbottom(sprintf(.@format$, "barrel", 82)); - //prints "The barrel contains 82 monkeys" - --------------------------------------- -*sscanf(<string>,<format>[,param[,param[,...]]]) +*sscanf(<string>,<format>{,param{,param{,...}}}) C style sscanf. All C format specifiers are supported. More info: sscanf @ www.cplusplus.com. The number of params is only @@ -7321,7 +7691,7 @@ limited by Hercules' script engine. 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>}) @@ -7335,7 +7705,7 @@ 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>}}) @@ -7348,8 +7718,8 @@ 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" + --------------------------------------- *countstr(<input>, <search>{, <usecase>}) @@ -7369,16 +7739,16 @@ This command sets the current RO client interface font to one of the fonts stored in data\*.eot by using an ID of the font. When the ID of the currently used font is used, default interface font is used again. - 0 - Default - 1 - RixLoveangel - 2 - RixSquirrel - 3 - NHCgogo - 4 - RixDiary - 5 - RixMiniHeart - 6 - RixFreshman - 7 - RixKid - 8 - RixMagic - 9 - RixJJangu + 0 - Default + 1 - RixLoveangel + 2 - RixSquirrel + 3 - NHCgogo + 4 - RixDiary + 5 - RixMiniHeart + 6 - RixFreshman + 7 - RixKid + 8 - RixMagic + 9 - RixJJangu --------------------------------------- @@ -7388,12 +7758,12 @@ Displays given numeric 'value' in large digital clock font on top of the screen. The optional parameter 'type' specifies visual aspects of the "clock" and can be one of the following values: - 0 - Displays the value for 5 seconds (default). - 1 - Incremental counter (1 tick/second). - 2 - Decremental counter (1 tick/second). Does not stop at zero, but - overflows. - 3 - Decremental counter (1 tick/second). Two digits only, stops at - zero. + 0 - Displays the value for 5 seconds (default). + 1 - Incremental counter (1 tick/second). + 2 - Decremental counter (1 tick/second). Does not stop at zero, but + overflows. + 3 - Decremental counter (1 tick/second). Two digits only, stops at + zero. For type 1 and 2 the start value is set by using negative number of the one intended to set (ex. -10 starts the counter at 10 seconds). Except for @@ -7401,11 +7771,11 @@ type 3 the value is interpreted as seconds and formatted as time in days, hours, minutes and seconds. Note, that the official script command does not have the optional parameter. - // displays 23:59:59 for 5 seconds - showdigit 86399; + // displays 23:59:59 for 5 seconds + showdigit 86399; - // counter that starts at 60 and runs for 60 seconds - showdigit 60,3; + // counter that starts at 60 and runs for 60 seconds + showdigit 60,3; --------------------------------------- @@ -7504,8 +7874,8 @@ inventory. The kind of pet is specified by pet ID numbers listed in 'db/pet_db.txt'. The egg is created exactly as if the character just successfully caught a pet in the normal way. - // This will make you a poring: - makepet 1002; + // This will make you a poring: + makepet 1002; Notice that you absolutely have to create pet eggs with this command. If you try to give a pet egg with 'getitem', pet data will not be created by @@ -7618,10 +7988,9 @@ Directions are the same as NPC sprite facing directions: 0=north, This will open a book item at the specified page. --------------------------------------- - -======================== -|7.- Instance commands.| -======================== +//===================================== +7 - Instance-Related Commands +//===================================== --------------------------------------- *instance_create("<instance name>",<owner id>{,<optional owner_type>}); @@ -7633,23 +8002,19 @@ ID this command returns. Example: // Store the Party ID of the invoking character. - set .@party_id, getcharid(1); + .@party_id = getcharid(1); // Attempt to create an instance using that party ID. - set .@id, instance_create("Endless Tower", .@party_id); + .@id = instance_create("Endless Tower", .@party_id); if (.@id == -1) { // Invalid type - not used anymore ... - } - else if (.@id == -2) { // Invalid Party ID + } else if (.@id == -2) { // Invalid Party ID ... - } - else if (.@id == -3) { // No free instances (MAX_INSTANCE exceeded) + } else if (.@id == -3) { // No free instances (MAX_INSTANCE exceeded) ... - } - else if (.@id == -4) { // Already exists + } else if (.@id == -4) { // Already exists ... - } - else (.@id < 0) { // Unspecified error while queuing instance. + } else (.@id < 0) { // Unspecified error while queuing instance. ... } @@ -7730,6 +8095,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. @@ -7782,16 +8155,91 @@ 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. + + +--------------------------------------- +//===================================== +7 - End of Instance-Related Commands +//===================================== +--------------------------------------- + + +--------------------------------------- +//===================================== +8 - Quest Log-Related 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; +} -========================= -|8.- Quest Log commands.| -========================= --------------------------------------- *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>; @@ -7821,51 +8269,60 @@ If no additional argument supplied, return the state of the quest: 0 = Quest has been given, but the state is "inactive" 1 = Quest has been given, and the state is "active" 2 = Quest completed - + If parameter "PLAYTIME" is supplied: -1 = Quest not started (not in quest log) 0 = the time limit has not yet been reached 1 = the time limit has not been reached but the quest is marked as - complete + complete 2 = the time limit has been reached - + If parameter "HUNTING" is supplied: - -1 = Quest not started (not in quest log) - 0 = you haven't killed all of the target monsters and the time limit - has not been reached. - 1 = you haven't killed all of the target monsters but the time limit - has been reached. - 2 = you've killed all of the target monsters + -1 = Quest not started (not in quest log) + 0 = you haven't killed all of the target monsters and the time limit + has not been reached. + 1 = you haven't killed all of the target monsters but the time limit + has been reached. + 2 = you've killed all of the target monsters --------------------------------------- -*showevent <state>, <color>; +*showevent <icon>{,<mark color>} -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. +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. -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. +Available Icons: -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. +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) ----------------------------------------- +Mark Color: +0 - No Mark +1 - Yellow Mark +2 - Green Mark +3 - Purple Mark -============================ -|9.- Battleground commands.| -============================ +--------------------------------------- +//===================================== +8 - End of Quest Log-Related Commands +//===================================== +--------------------------------------- + + +--------------------------------------- +//===================================== +9 - Battlegrounds-Related Commands +//===================================== --------------------------------------- *waitingroom2bg_single(<battle group>,"<mapname>",<x>,<y>,"<npc name>"); @@ -7893,9 +8350,9 @@ If the option parameter is left out, the waiting room of the current NPC is used. Example: - // Battle Group will be referred to as $@KvM01BG_id1, and when they - // die, respawn at bat_c01,52,129. - set $@KvM01BG_id1, waitingroom2bg("bat_c01",52,129,"KvM01_BG::OnGuillaumeQuit","KvM01_BG::OnGuillaumeDie"); + // Battle Group will be referred to as $@KvM01BG_id1, and when they + // die, respawn at bat_c01,52,129. + $@KvM01BG_id1 = waitingroom2bg("bat_c01",52,129,"KvM01_BG::OnGuillaumeQuit","KvM01_BG::OnGuillaumeDie"); end; ---------------------------------------- @@ -7907,7 +8364,7 @@ map. The <Battle Group ID> can be retrieved using getcharid(4). Example: bg_team_setxy getcharid(4),56,212; - mapannounce "bat_a01", "Group [1] has taken the work shop, and will now respawn there.",bc_map,"0xFFCE00"; + mapannounce "bat_a01", "Group [1] has taken the work shop, and will now respawn there.",bc_map,0xFFCE00; end; ---------------------------------------- @@ -7935,12 +8392,12 @@ Battle group is considered friendly. Example: // It can be used in two different ways. - bg_monster $@TierraBG1_id2,"bat_a01",167,50,"Food Depot",1910,"Feed Depot#1::OnMyMobDead"; + bg_monster $@TierraBG1_id2,"bat_a01",167,50,"Food Depot",OBJ_B,"Feed Depot#1::OnMyMobDead"; end; // Alternatively, you can set an ID for the monster using "set". // This becomes useful when used with the command below. - set $@Guardian_3, bg_monster($@TierraBG1_id2,"bat_a01",268,204,"Guardian",1949,"NPCNAME::OnMyMobDead"); + $@Guardian_3 = bg_monster($@TierraBG1_id2,"bat_a01",268,204,"Guardian",B_S_GUARDIAN,"NPCNAME::OnMyMobDead"); end; ---------------------------------------- @@ -7955,14 +8412,14 @@ Example: end; OnEnable: - mapannounce "A guardian has been summoned for Battle Group 2!",bc_map,"0xFFCE00"; - set $@Guardian, bg_monster($@BG_2,"bat_a01",268,204,"Guardian",1949,"NPCNAME::OnMyMobDead"); + mapannounce "A guardian has been summoned for Battle Group 2!",bc_map,0xFFCE00; + set $@Guardian, bg_monster($@BG_2,"bat_a01",268,204,"Guardian",B_S_GUARDIAN,"NPCNAME::OnMyMobDead"); initnpctimer; end; OnTimer1000: stopnpctimer; - mapannounce "Erm, sorry about that! This monster was meant for Battle Group 1.",bc_map,"0xFFCE00"; + mapannounce "Erm, sorry about that! This monster was meant for Battle Group 1.",bc_map,0xFFCE00; bg_monster_set_team $@Guardian, $@BG_1; end; @@ -7996,7 +8453,7 @@ Example: Retrieves data related to given battle group. Type can be one of the following: - 0 - Amount of players currently belonging to the group. + 0 - Amount of players currently belonging to the group. ---------------------------------------- @@ -8013,11 +8470,17 @@ This command will force the update of the displayed scoreboard. It is only usable when the map is defined as a Type 2 Battleground: mapflag%TAB%<mapname>%TAB%battleground%TAB%2 ----------------------------------------- +--------------------------------------- +//===================================== +9 - End of Battlegrounds-Related Commands +//===================================== +--------------------------------------- + -========================== -|10.- Mercenary commands.| -========================== +--------------------------------------- +//===================================== +10 - Mercenary Commands +//===================================== --------------------------------------- *mercenary_create <class>,<contract time>; @@ -8047,9 +8510,9 @@ currently attached character. Sets or gets the mercenary calls value for given guild for currently attached character. Guild can be one or the following constants: - ARCH_MERC_GUILD - SPEAR_MERC_GUILD - SWORD_MERC_GUILD + ARCH_MERC_GUILD + SPEAR_MERC_GUILD + SWORD_MERC_GUILD ---------------------------------------- @@ -8059,9 +8522,9 @@ attached character. Guild can be one or the following constants: Sets or gets the mercenary faith value for given guild for currently attached character. Guild can be one or the following constants: - ARCH_MERC_GUILD - SPEAR_MERC_GUILD - SWORD_MERC_GUILD + ARCH_MERC_GUILD + SPEAR_MERC_GUILD + SWORD_MERC_GUILD --------------------------------------- @@ -8072,23 +8535,29 @@ If char id is given, the information of that character is retrieved instead. Type specifies what information to retrieve and can be one of the following: - 0 - Database ID - 1 - Class - 2 - Name - 3 - Faith value for this mercenary's guild, if any - 4 - Calls value for this mercenary's guild, if any - 5 - Kill count - 6 - Remaining life time in msec - 7 - Level + 0 - Database ID + 1 - Class + 2 - Name + 3 - Faith value for this mercenary's guild, if any + 4 - Calls value for this mercenary's guild, if any + 5 - Kill count + 6 - Remaining life time in msec + 7 - Level If the character does not have a mercenary, the command returns "" for name and 0 for all other types. ----------------------------------------- +--------------------------------------- +//===================================== +10 - End of Mercenary-Related Commands +//===================================== +--------------------------------------- -====================== -|11.- Queue Commands.| -====================== + +--------------------------------------- +//===================================== +11 - Queue-Related Commands +//===================================== --------------------------------------- *queue(); @@ -8124,7 +8593,7 @@ Modifies <queue_id>'s <optionType>. When <option val> is not present <queue_id>'s <optionType> with the new <option val> value. Currently 3 options are available: -HQO_OnDeath (0), HQO_OnLogout (1), HQO_OnMapChange (2) +HQO_OnDeath (1), HQO_OnLogout (2), HQO_OnMapChange (3) Note: The constant names are not final. @@ -8161,7 +8630,7 @@ obtains the next member in the iterator's queue, returns the next member's id or 0 when it doesnt exist. Example: - for( set .@elem,qiget(.@queue_iterator_id); qicheck(.@queue_iterator_id); set .@elem,qiget(.@queue_iterator_id) ) { + for (.@elem = qiget(.@queue_iterator_id); qicheck(.@queue_iterator_id); .@elem = qiget(.@queue_iterator_id)) { //Do something } @@ -8173,3 +8642,74 @@ Deletes a queue iterator from memory and returns 1 when it fails, otherwise 0 is returned. --------------------------------------- +//===================================== +11 - End of Queue-Related Commands +//===================================== +--------------------------------------- + +--------------------------------------- +//===================================== +12 - NPC Trader-Related 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). + +--------------------------------------- |