diff options
| author | Andrei Karas <akaras@inbox.ru> | 2014-10-05 11:34:32 +0300 |
|---|---|---|
| committer | Andrei Karas <akaras@inbox.ru> | 2017-06-27 19:32:37 +0300 |
| commit | 9e70581952d89efdabbc94a42f0d015452241f48 (patch) | |
| tree | b8d13f2674d3bbdeb70857ca4d8d90fe220c72e3 /doc/script_commands.txt | |
| parent | 6049fbf77ebdcf61027bc799790edbe7657aadee (diff) | |
| download | hercules-9e70581952d89efdabbc94a42f0d015452241f48.tar.gz hercules-9e70581952d89efdabbc94a42f0d015452241f48.tar.bz2 hercules-9e70581952d89efdabbc94a42f0d015452241f48.tar.xz hercules-9e70581952d89efdabbc94a42f0d015452241f48.zip | |
Remove conf dir.
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 9804 |
1 files changed, 0 insertions, 9804 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt deleted file mode 100644 index bf403bfec..000000000 --- a/doc/script_commands.txt +++ /dev/null @@ -1,9804 +0,0 @@ -//===== Hercules Documentation =============================== -//= Hercules Script Commands -//===== By: ================================================== -//= Hercules Dev Team -//===== Description: ========================================= -//= A reference manual for the Hercules scripting language. -//= Commands are sorted depending on their functionality. -//============================================================ - -This document is a reference manual for all the scripting commands and -functions available in current Hercules GIT. It is not a simple tutorial. -When people tell you to "Read The F***ing Manual", they mean this. - -The information was mostly acquired through looking up how things actually -work in the source code of the server, which was written by many people -over time, and lots of them don't speak English and never left any notes - -or are otherwise not available for comments. As such, anything written in -here might not be correct, it is only correct to the best of our -knowledge, which is limited. - -This is not a place to teach you basic programming. This document will not -teach you basic programming by itself. It's more of a reference for those -who have at least a vague idea of what they want to do and want to know -what tools they have available to do it. We've tried to keep it as simple -as feasible, but if you don't understand it, getting a clear book on -programming in general will help better than yelling around the forum for -help. - -A little learning never caused anyone's head to explode. - -Structure ---------- - -The commands and functions are listed in no particular order: - -*Name of the command and how to call it. - -Descriptive text - - Small example if possible. Will usually be incomplete, it's there just - to give you an idea of how it works in practice. - -To find a specific command, use Ctrl+F, (or whatever keys call up a search -function in whatever you're reading this with) put an * followed by the -command name, and it should find the command description for you. - -If you find anything omitted, please tell us. :) - -Syntax ------- - -Throughout this document, wherever a command wants an argument, it is -given in <angle brackets>. This doesn't mean you should type the angle -brackets. :) If an argument of a command is optional, it is given in -{curly brackets}. You've doubtlessly seen this convention somewhere, if -you didn't, get used to it, that's how big boys do it. If a command can -optionally take an unspecified number of arguments, you'll see a list like -this: - -command(<argument>{, <argument>...<argument>}) - -This still means they will want to be separated by commas. - -Where a command wants a string, it will be given in "quotes", if it's a -number, it will be given without them. Normally, you can put an -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, use 'mapname' instead of 'mapname.gat'. - - -Script loading structure ------------------------- - -Scripts are loaded by the map server as referenced in the -'npc/(pre-)re/scripts_main.conf' configuration file. - -The file contains a list of scripts to be loaded (or other configuration files -to be parsed, through the @include directive), in the following format: - -npc_global_list: ( - "npc/path/to/the/script/to/load.txt", - "npc/other/file.txt", -@include "npc/other_configuration_file.conf" -) - -Any script will only get loaded once even if specified twice, to prevent -possible errors. - -It's possible to specify scripts to exclude from loading, by inserting them -(using the same syntax) in the list available in npc/scripts_removed.conf: - -npc_removed_list: ( - "npc/path/to/the/file/to/skip.txt", -) - -Script file format ------------------- - -Whenever '//' is encountered in a line upon reading, everything beyond -this on that line is considered to be a comment and is ignored. This works -wherever you place it. - -// This line will be ignored when processing the script. - -Block comments can also be used, where you can place /* and */ between any -text you wish Hercules to ignore. - -Example: -/* This text, - * no matter which new line you start - * is ignored, until the following - * symbol is encountered: */ - -The asterisks (*) in front of each line is a personal preference, and is -not required. - -Upon loading all the files, the server will execute all the top-level -commands in them. No variables exist yet at this point, no commands can be -called other than those given in this section. These commands set up the -basic server script structure - create NPC objects, spawn monster objects, -set map flags, etc. No code is actually executed at this point except -them. The top-level commands the scripting are pretty confusing, since -they aren't structured like you would expect commands, command name first, -but rather, normally start with a map name. - -What's more confusing about the top-level commands is that most of them -use a tab symbol to divide their arguments. - -To prevent problems and confusion, the tab symbols are written as '%TAB%' -or '<TAB>' throughout this document, even though this makes the text a bit -less readable. Using an invisible symbol to denote arguments is one of the -bad things about this language, but we're stuck with it for now. :) - -Here is a list of valid top-level commands: - -** Set a map flag: - -<map name>%TAB%mapflag%TAB%<flag> - -This will, upon loading, set a specified map flag on a map you like. These -are normally in files inside 'npc/mapflag' and are loaded first, so by the -time the server's up, all the maps have the flags they should have. Map -flags determine the behavior of the map regarding various common problems, -for a better explanation, see 'setmapflag'. - -** Create a permanent monster spawn: - -<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 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 -move away from their specified spawn region. - -Monster name is the name the monsters will have on screen, and has no -relation whatsoever to their names anywhere else. It's the mob id that -counts, which identifies monster record in 'mob_db.txt' database of -monsters. If the mob name is given as "--ja--", the 'japanese name' field -from the monster database is used, (which, in Hercules, actually contains -an English name) if it's "--en--", it's the 'english name' from the -monster database (which contains an uppercase name used to summon the -monster with a GM command). - -Amount is the amount of monsters that will be spawned when this command is -executed, it is affected by spawn rates in 'conf/map/battle.conf'. - -Delay1 and delay2 control monster respawn delays - the first one is the -fixed base respawn time, and the second is random variance on top of the -base time. Both values are given in milliseconds (1000 = 1 second). Note -that the server also enforces a minimum respawn delay of 5 seconds. - -You can specify a custom level to use for the mob different from the one -of the database by adjoining the level after the name with a comma. eg: -"Poring,50" for a name will spawn a monster with name Poring and level 50. - -Event is a script event to be executed when the mob is killed. The event -must be in the form "NPCName::OnEventName" to execute, and the event name -label should start with "On". As with all events, if the NPC is an -on-touch NPC, the player who triggers the script must be within 'trigger' -range for the event to work. - -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). - -** NPC names - -/!\ WARNING: this applies to warps, NPCs, duplicates and shops /!\ - -NPC names are kinda special and are formatted this way: - -<Display name>{::<Unique name>} - -All NPCs need to have a unique name that is used for identification -purposes. When you have to identify a NPC by it's name, you should use -<Unique name>. If <Unique name> is not provided, use <Display name> -instead. - -The client has a special feature when displaying names: if the display -name contains a '#' character, it hides that part of the name. -Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter' - -<Display name> must be at most 24 characters in length. -<Unique name> must be at most 24 characters in length. - -** Define a warp point - -<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. - -SpanX and SpanY will make the warp sensitive to a character who didn't -step directly on it, but walked into a zone which is centered on the warp -from coordinates and is SpanX in each direction across the X axis and -SpanY in each direction across the Y axis. - -Warp NPC objects also have a name, because you can use it to refer to them -later with 'enablenpc'/'disablenpc'. - -Facing of a warp object is irrelevant, it is not used in the code and all -current scripts have a zero in there. - -** Define an NPC object. - -<map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite>,{<code>} -<map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite>,<triggerX>,<triggerY>,{<code>} - -This will place an NPC object on a specified map at the specified -location, and is a top-level command you will use the most in your custom -scripting. The NPCs are triggered by clicking on them, and/or by walking -in their trigger area, if defined. See that below. - -Facing is a direction the NPC sprite will face in. Not all NPC sprites -have different images depending on the direction you look from, so for -some facing will be meaningless. Facings are counted counterclockwise in -increments of 45 degrees, where 0 means facing towards the top of the map. -(So to turn the sprite towards the bottom of the map, you use facing 4, -and to make it look southeast it's facing 5.) - -Sprite is the sprite identifier used to display this particular NPC. For a -full list of sprite numbers see http://kalen.s79.xrea.com/npc/npce.shtml as -well as db/constants.conf. -You may also use a monster's ID constant instead to display a monster sprite -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 'FAKE_NPC' sprite will make the NPC invisible (and unclickable). -A 'HIDDEN_NPC' sprite 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 -the 3D terrain. - -TriggerX and triggerY, if given, will define an area, centered on NPC and -spanning triggerX cells in every direction across X and triggerY in every -direction across Y. Walking into that area will trigger the NPC. If no -'OnTouch:' special label is present in the NPC code, the execution will -start from the beginning of the script, otherwise, it will start from the -'OnTouch:' label. Monsters can also trigger the NPC, though the label -'OnTouchNPC:' is used in this case. If player left area npc will called -if present label 'OnUnTouch'. - -The code part is the script code that will execute whenever the NPC is -triggered. It may contain commands and function calls, descriptions of -which compose most of this document. It has to be in curly brackets, -unlike elsewhere where we use curly brackets, these do NOT signify an -optional parameter. - -** Define a 'floating' NPC object. - --%TAB%script%TAB%<NPC Name>%TAB%FAKE_NPC,{<code>} - -This will define an NPC object not triggerable by normal means. This would -normally mean it's pointless since it can't do anything, but there are -exceptions, mostly related to running scripts at specified time, which is -what these floating NPC objects are for. More on that below. - -** Define a shop/cashshop NPC. - --%TAB%shop%TAB%<NPC Name>%TAB%<sprite>,<itemid>:<price>{,<itemid>:<price>...} -<map name>,<x>,<y>,<facing>%TAB%shop%TAB%<NPC Name>%TAB%<sprite>,<itemid>:<price>{,<itemid>:<price>...} - -This will define a shop NPC, which, when triggered (which can only be done -by clicking) will cause a shop window to come up. No code whatsoever runs -in shop NPCs and you can't change the prices otherwise than by editing the -script itself (no variables even exist at this point of scripting, so -don't even bother trying to use them). - -The item id is the number of item in the 'item_db.txt' database. If Price -is set to -1, the 'buy price' given in the item database will be used. -Otherwise, the price you gave will be used for this item, which is how you -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 #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>,{<code>} --%TAB%trader%TAB%<NPC Name>%TAB%FAKE_NPC,{<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> -shop/cashshop/npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite> -shop/cashshop/npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite> -npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite>,<triggerX>,<triggerY> -npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite>,<triggerX>,<triggerY> - -This will duplicate an warp/shop/cashshop/NPC referred to by 'label'. -Warp duplicates inherit the target location. -Shop/cashshop duplicates inherit the item list. -NPC duplicates inherit the script code. -The rest (name, location, facing, sprite, span/trigger area) is -obtained from the definition of the duplicate (not inherited). - -** Define a function object - -function%TAB%script%TAB%<function name>%TAB%{<code>} - -This will define a function object, callable with the 'callfunc' command -(see below). This object will load on every map server separately, so you -can get at it from anywhere. It's not possible to call the code in this -object by anything other than the 'callfunc' script command. - -The code part is the script code that will execute whenever the function -is called with 'callfunc'. It has to be in curly brackets, unlike -elsewhere where we use curly brackets, these do NOT signify an optional -parameter. - -Once an object is defined which has a 'code' field to it's definition, it -contains script commands which can actually be triggered and executed. - -~ RID? GID? ~ - -What a RID is and why do you need to know ------------------------------------------ - -Most scripting commands and functions will want to request data about a -character, store variables referenced to that character, send stuff to the -client connected to that specific character. Whenever a script is invoked -by a character, it is passed a so-called RID - this is the account ID -number of a character that caused the code to execute by clicking on it, -walking into it's OnTouch zone, or otherwise. - -If you are only writing common NPCs, you don't need to bother with it. -However, if you use functions, if you use timers, if you use clock-based -script activation, you need to be aware of all cases when a script -execution can be triggered without a RID attached. This will make a lot of -commands and functions unusable, since they want data from a specific -character, want to send stuff to a specific client, want to store -variables specific to that character, and they would not know what -character to work on if there's no RID. - -Unless you use 'attachrid' to explicitly attach a character to the script -first (see player-related commands). - -Whenever we say 'invoking character', we mean 'the character who's RID is -attached to the running script. The script function playerattached() can -be used to check which is the currently attached player to the script (it -will return 0 if the there is no player attached or the attached player no -longer is logged on to the map-server). - -But what about GID? ---- ---- ----- ---- - -GID stands for the Game ID of something, this can either be the GID of a -mob obtained through the monster() script command (if only summoned one), -the GID of a NPC obtained through the getnpcid() script command or the -account ID of a character (same as its RID). Another way would be to right -click on a mob, NPC or char as GM sprited char to view its GID. - -Item and pet scripts --------------------- - -Each item in the item database has three special fields - Script, -OnEquip_Script and OnUnequip_Script. The first is script code run every -time a character equips the item, with the RID of the equipping character. -Every time they unequip an item, all temporary bonuses given by the script -commands are cleared, and all the scripts are executed once again to -rebuild them. This also happens in several other situations (like upon -login) but the full list is currently unknown. - -OnEquip_Script is a piece of script code run whenever the item is used by -a character by double-clicking on it. OnUnequip_Script runs whenever the -equipment is unequipped by a character. - -Not all script commands work properly in the item scripts. Where commands -and functions are known to be meant specifically for use in item scripts, -they are described as such. - -Every pet in the pet database has a PetScript field, which determines pet -behavior. It is invoked wherever a pet of the specified type is spawned -(hatched from an egg, or loaded from the char server when a character who -had that pet following them connects). This may occur in some other -situations as well. Don't expect anything other than commands definitely -marked as usable in pet scripts to work in there reliably. - -Numbers -------- - -Beside the common decimal numbers, which are nothing special whatsoever -(though do not expect to use fractions, since ALL numbers are integer in -this language), the script engine also handles hexadecimal numbers, which -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'. - -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 ---------- - -The meat of every programming language is variables - places where you -store data. - -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 -name - an identifier consisting of '_' and alphanumeric characters -postfix - determines the type of the variable: integer or string - -Scope can be: -global - global to all servers -local - local to the server -account - attached to the account of the character identified by RID -character - attached to the character identified by RID -npc - attached to the NPC -scope - attached to the scope of the instance - -Extent can be: -permanent - They still exist when the server resets. -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. -"@" - 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. - 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 - the NPC is reloaded. Can be accessed from inside the NPC or by - calling 'getvariableofnpc'. Function objects can also have - .variables which are accessible from inside the function, - however 'getvariableofnpc' does NOT work on function objects. -".@" - A scope variable. - 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 instance. -"#" - A permanent local account variable. -"##" - A permanent global account variable stored by the login server. - 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, - while the ## variables are shared by all these char-servers. - -Postfix: integer or string -nothing - integer variable, can store positive and negative numbers, but - only whole numbers (so don't expect to do any fractional math). -'$' - string variable, can store text. - -Examples: - name - permanent character integer variable - name$ - permanent character string variable - @name - temporary character integer variable - @name$ - temporary character string variable - $name - permanent global integer variable - $name$ - permanent global string variable -$@name - temporary global integer variable -$@name$ - temporary global string variable - .name - NPC integer 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 -##name$ - permanent global account string variable - -If a variable was never set, it is considered to equal zero for integer -variables or an empty string ("", nothing between the quotes) for string -variables. Once you set it to that, the variable is as good as forgotten -forever, and no trace remains of it even if it was stored with character -or account data. The maximum length of variable name including prefix and -suffix is 32. - -Some variables are special, that is, they are already defined for you by -the scripting engine. You can see the full list somewhere in -'db/constants.conf', which is a file you should read, since it also -allows you to replace lots of numbered arguments for many commands with -easier to read text. The special variables most commonly used are all -permanent character-based variables: - -Zeny - Amount of Zeny in the inventory. -BankVault - Amount of Zeny in the bank. -Hp - Current amount of hit points. -MaxHp - Maximum amount of hit points. -Sp - Current spell points. -MaxSp - Maximum amount of spell points. -StatusPoint - Amount of status points remaining. -SkillPoint - Amount of skill points remaining. -BaseLevel - Character's base level. -JobLevel - Character's job level. -BaseExp - Amount of base experience points. -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 - Character's gender (SEX_MALE or SEX_FEMALE). -Class - Character's job. -Upper - 0 if the character is normal class, 1 if advanced, 2 if baby. -BaseClass - The character's 1-1 'normal' job, regardless of Upper value. - For example, this will return Job_Acolyte for Acolyte, - Priest/Monk, High Priest/Champion, and Arch Bishop/Sura. - If the character has not reached a 1-1 class, it will return - Job_Novice. -BaseJob - The character's 'normal' job, regardless of Upper value. - For example, this will return Job_Acolyte for Acolyte, - Baby Acolyte, and High Acolyte. -Karma - The character's karma. Karma system is not fully functional, - but this doesn't mean this doesn't work at all. Not tested. -Manner - The character's manner rating. Becomes negative if the - player utters words forbidden through the use of - 'manner.txt' client-side file. - -While these behave as variables, do not always expect to just set them - -it is not certain whether this will work for all of them. Whenever there -is a command or a function to set something, it's usually preferable to -use that instead. The notable exception is Zeny, which you can and often -will address directly - setting it will make the character own this number -of Zeny. If you try to set Zeny to a negative number, the script will be -terminated with an error. - -Assigning variables ---------- --------- - -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; - -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. 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; - -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 - !! variables. In order to copy arrays between variables the use of - !! 'copyarray' function is still required. - -Strings -------- - -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 ------- - -Arrays (in Hercules at least) are essentially a set of variables going -under the same name. You can tell between the specific variables of an -array with an 'array index', a number of a variable in that array: - -<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 -can address any array variable as if it was a normal variable: - - .@arrayofnumbers[0] = 1; - -You can use a variable (or an expression, or even a value from an another -array) as array index: - - .@x = 100; - .@arrayofnumbers[.@x] = 10; - -This will make .@arrayofnumbers[100] equal to 10. - -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. - -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. -Notice the '$', normally denoting a string variable, before the square -brackets that denotes an array index. - -Variable References -------------------- - -//##TODO - -Hard-coded constants --------------------- -Most of the constants defined by the scripting engine can be found in -'db/constants.conf' 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 in the inventory -MAX_BANK_ZENY - Maximum Zeny in the bank -MAX_BG_MEMBERS - Maximum BattleGround members -MAX_CHAT_USERS - Maximum Chat users -MAX_REFINE - Maximum Refine level - -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 ---------- - -Operators are things you can do to variables and numbers. They are either -the common mathematical operations or conditional operators: - -+ - will add two numbers. If you try to add two strings, the result will - be a string glued together at the +. You can add a number to a string, - and the result will be a string. No other math operators work with - strings. -- - will subtract two numbers. -* - will multiply two numbers. -** - will raise the first number to the power of the second number. -/ - will divide two numbers. Note that this is an integer division, i.e. - 7/2 is not equal 3.5, it's equal 3. -% - will give you the remainder of the division. 7%2 is equal to 1. - -There are also conditional operators. This has to do with the conditional -command 'if' and they are meant to return either 1 if the condition is -satisfied and 0 if it isn't. That's what they call 'boolean' variables. 0 -means 'False'. Anything except the zero is 'True'. Odd as it is, -1 and -5 -and anything below zero will also be True.) - -You can compare numbers to each other and you compare strings to each -other, but you can not compare numbers to strings. - - == - Is true if both sides are equal. For strings, it means they contain - the same value. - >= - True if the first value is equal to, or greater than, the second - value. - <= - True if the first value is equal to, or less than, the second value. - > - 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. - -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: - - && - Is True if and only if BOTH sides are true. - ('1==1 && 2==2' is true. '2==1 && 1==1' is false.) - || - Is True if either side of this expression is True. - - 1==1 && 2==2 is True. - 1==1 && 2==1 is False. - 1==1 || 2==1 is True. - -Logical bitwise operators work only on numbers, and they are the following: - - << - Left shift. - >> - Right shift. - Left shift moves the binary 1(s) of a number n positions to the left, - which is the same as multiplying by 2, n times. - 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: - b = 2; - a = b << 3; - mes(a); - 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. - The second mes() command would display 4, which is the same as: - 16 / 2 = 8; 8 / 2 = 4. - & - And. - | - Or. - The bitwise operator AND (&) is used to test two values against each - other, and results in setting bits which are active in both arguments. - This can be used for a few things, but in Hercules this operator is - usually used to create bit-masks in scripts. - - The bitwise operator OR (|) sets to 1 a binary position if the binary - position of one of the numbers is 1. This way a variable can hold - several values we can check, known as bit-mask. A variable currently - can hold up to 32 bit-masks (from position 0 to position 1). This is a - cheap(skate) and easy way to avoid using arrays to store several - checks that a player can have. - - A bit-mask basically is (ab)using the variables bits to set various - options in one variable. With the current limit in variables it is - possible to store 32 different options in one variable (by using the - bits on position 0 to 31). - - Example(s): - - Basic example of the & operator, bit example: - 10 & 2 = 2 - Why? : - 10 = 2^1 + 2^3 (2 + 8), so in bits, it would be 1010 - 2 = 2^1 (2), so in bits (same size) it would be 0010 - The & (AND) operator sets bits which are active (1) in both - 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: - .@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 print the messages about option 2, 3 and 5 (since we've set - the 2,4 and 16 bit to 1). - ^ - Xor. - The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if - both numbers have the same value in the said position. On the other - 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: - 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) - 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) - inProgress = inProgress^1; - mes("Quest 1 complete!! You unlocked the secrets of the Xor dynasty, use them wisely."); - close(); - } - -Unary operators with only with a single number, which follows the -operator, and are the following: - - - - Negation. - The sign of the number will be reversed. If the number was positive, - it will become negative and vice versa. - - Example: - .@myvar = 10; - mes("Negative 10 is "+(-.@myvar)); - - ! - Logical Not. - Reverses the boolean result of an expression. True will become false - and false will become true. - - Example: - if (!callfunc("F_dosomething")) { - mes("Doing something failed."); - close(); - } - - ~ - Bitwise Not. - Reverses each bit in a number, also known as one's complement. Cleared - bits are set, and set bits are cleared. - - Example: - - Ensure, that quest 2 is disabled, while keeping all other active, if - they are. - inProgress = inProgress&(~2); - // same as set inProgress, inProgress&0xfffffffd - -Ternary operators take three expressions (numbers, strings or boolean), -and are the following: - - ?: - Conditional operator - Very useful e.g. to replace - - if (Sex == SEX_MALE) - mes("You're Male."); - else - mes("You're Female."); - - clauses with simple - - mes("Welcome, " + (Sex == SEX_MALE ? "Mr." : "Mrs.") + " " + strcharinfo(PC_NAME)); - - or to replace any other simple if-else clauses. It might be worth - 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 | ** Exponentiation | Left to right ---------------------------------------------------------------------------- -4 | * Multiplication | Left to right - | / Division | - | % Modulo (remainder) | ---------------------------------------------------------------------------- -5 | + Addition | Left to right - | - Subtraction | ---------------------------------------------------------------------------- -6 | << Bitwise left shift | Left to right - | >> Bitwise right shift | ---------------------------------------------------------------------------- -7 | < Less than | Left to right - | <= Less than or equal to | - | > Greater than | - | >= Greater than or equal to | ---------------------------------------------------------------------------- -8 | == Equal to | Left to right - | != Not equal to | - | ~= Regexp match | - | ~! Regexp non-match | ---------------------------------------------------------------------------- -9 | & Bitwise AND | Left to right ---------------------------------------------------------------------------- -10 | ^ Bitwise XOR (exclusive or) | Left to right ---------------------------------------------------------------------------- -11 | | Bitwise OR (inclusive or) | Left to right ---------------------------------------------------------------------------- -12 | && Logical AND | Left to right ---------------------------------------------------------------------------- -13 | || Logical OR | Left to right ---------------------------------------------------------------------------- -14 | ?: Ternary conditional | Right to left ---------------------------------------------------------------------------- -15 | = Direct assignment | Right to left -(lowest) | += Assignment by sum | - | -= Assignment by difference | - | *= Assignment by product | - | **= Assignment by power | - | /= 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 ------- - -Within executable script code, some lines can be labels: - -<label name>: - -Labels are points of reference in your script, which can be used to route -execution with 'goto' and 'menu' commands, invoked with 'doevent', 'donpcevent' -and 'callsub' commands and are otherwise essential. A label's name may not be -longer than 23 characters. (24th is the ':'.) It may only contain alphanumeric -characters and underscore. In addition to labels you name yourself, there are -also some special labels which the script engine will start execution from if -a special event happens: - -OnClock<hour><minute>: -OnMinute<minute>: -OnHour<hour>: -On<weekday><hour><minute>: -OnDay<month><day>: - -This will execute when the server clock hits the specified date or time. -Hours and minutes are given in military time. ('0105' will mean 01:05 AM). -Weekdays are Sun, Mon, Tue, Wed, Thu, Fri, Sat. Months are 01 to 12, days are -01 to 31. Remember the zero. :) - -OnInit: -OnInterIfInit: -OnInterIfInitOnce: - -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. Note that all those events will be executed upon -scripts reloading. - -OnAgitStart: -OnAgitEnd: -OnAgitInit: -OnAgitStart2: -OnAgitEnd2: -OnAgitInit2: - -OnAgitStart will run whenever the server shifts into WoE mode, whether it -is done with @agitstart GM command or with 'AgitStart' script command. -OnAgitEnd will do likewise for the end of WoE. - -OnAgitInit will run when data for all castles and all guilds that hold a -castle is received by map-server from the char-server after initial -connect. - -No RID will be attached while any of the above mentioned labels are -triggered, so no character or account-based variables will be accessible, -until you attach a RID with 'attachrid' (see below). - -The above also applies to, the last three labels, the only difference is -that these labels are used exclusively for WoE SE, and are called -independently. - -OnInstanceInit: - -This label will be executed when an instance is created and initialized through -the 'instance_init' command. It will run again if @reloadscript is used while -an instance is in progress. - -OnTouch: - -This label will be executed if a trigger area is defined for the NPC -object it's in. If it isn't present, the execution will start from the -beginning of the NPC code. The RID of the triggering character object will -be attached. - -OnTouch_: - -Similar to OnTouch, but will only run one instance. Another character is -chosen once the triggering character leaves the area. - -OnUnTouch: - -This label will be executed if plater leave trigger area is defined for the NPC -object it's in. If it isn't present, nothing will happend. -The RID of the triggering character object will be attached. - -OnPCLoginEvent: -OnPCLogoutEvent: -OnPCBaseLvUpEvent: -OnPCJobLvUpEvent: - -It's pretty obvious when these four special labels will be invoked. - -OnPCDieEvent: - -This special label triggers when a player dies. The variable 'killerrid' -is set to the ID of the killer. - -OnPCKillEvent: - -This special label triggers when a player kills another player. The -variable 'killedrid' is set to the ID of the player killed. - -OnNPCKillEvent: - -This special label triggers when a player kills a monster. The variable -'killedrid' is set to the Class of the monster killed. - -OnPCLoadMapEvent: - -This special label will trigger once a player steps in a map marked with -the 'loadevent' mapflag and attach its RID. The fact that this label -requires a mapflag for it to work is because, otherwise, it'd be -server-wide and trigger every time a player would change maps. Imagine the -server load with 1,000 players (oh the pain...) - -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 -that requires you to point/link a command to a mob or another NPC, giving -a label name to start from. The label name can be any of your liking, but -must be started with "On". - -Example: - -monster("prontera", 123, 42, "Poringz0rd", 2341, 23, "Master::OnThisMobDeath"); - -amatsu,13,152,4 script Master 767,{ - mes("Hi there"); - close(); - -OnThisMobDeath: - announce("Hey, "+strcharinfo(PC_NAME)+" just killed a Poringz0rd!", bc_blue|bc_all); - end; -} - -Each time you kill one, that announce will appear in blue to everyone. - -"Global" labels - -There's a catch with labels and doevent(). If you call a label (using -doevent()) and called label is in NPC that has trigger area, that label must -end with "Global" to work globally (i.e. if RID is outside of the trigger area, -which usually happens since otherwise there would be no point calling the label -with doevent(), because OnTouch would do the job). For further reference look -for npc_event in npc.c. - -Scripting commands and functions --------------------------------- - -The commands and functions are listed here in no particular order. There's -a difference between commands and functions - commands leave no 'return -value' which might be used in a conditional statement, as a command -argument, or stored in a variable. - -All instructions must end with a ';'. Actually, you may expect to have multiple -instructions on one line if you properly terminate them with a ';', but it's -consider ill practice, since it impairs legibility of the script. - -Please note that command and function names are case sensitive. - -------------------------- - - -From here on, we will have the commands sorted as followed: - -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 -//===================================== ---------------------------------------- - -*mes("<string>") - -This command will displays a box on the screen for the invoking character, -if no such box is displayed already, and will print the string specified -into that box. There is normally no 'close' or 'next' button on this box, -unless you create one with 'close' or 'next', and while it's open the -player can't do much else, so it's important to create a button later. If -the string is empty, it will show up as an empty line. - - mes("Text that will appear in the box"); - -Inside the string you may put color codes, which will alter the color of -the text printed after them. The color codes are all '^<R><G><B>' and -contain three hexadecimal numbers representing colors as if they were -HTML colors - ^FF0000 is bright red, ^00FF00 is bright green, ^0000FF is -bright blue, ^000000 is black. ^FF00FF is a pure magenta, but it's also -a color that is considered transparent whenever the client is drawing -windows on screen, so printing text in that color will have kind of a -weird effect. You may also use C_ constants accompany with "F_MesColor" -function for the color effect, see the full list of the available ones -in 'db/constants.conf' under 'C_'. Once you've set a text's color to something, -you have to set it back to black unless you want all the rest of the text be in -that color: - - mes("This is ^FF0000 red ^000000 and this is ^00FF00 green, ^000000 so."); - mes(callfunc("F_MesColor", C_BLUE) +"This message is now in BLUE"); - -Notice that the text coloring is handled purely by the client. If you use -non-English characters, the color codes might get screwed if they stick to -letters with no intervening space. Separating them with spaces from the -letters on either side solves the problem. - -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"); - -This will allow you to visit 'Google' with the in-game browser using default dimensions. - - mes("You can <URL>Bing!<INFO>http://www.bing.com/,800,600</INFO></URL> anything"); - -Clicking 'Bing!' will open the in-game browser using the specified dimensions. (800x600) - ---------------------------------------- - -*mesf("<format>"{, <param>{, <param>{, ...}}}) - -This command will display a box on the screen for the invoking character, -if no such box is displayed already, and will print the string specified -into that box, after applying the same format-string replacements as sprintf(). - -Example: - - mesf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class)); - // is equivalent to: - mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); - -This command is a combination of mes() and sprintf(). See their documentation -for more details. - ---------------------------------------- - -*next() - -This command will display a 'next' button in the message window for the -invoking character. Clicking on it will cause the window to clear and -display a new one. Used to segment NPC-talking, next() is often used in -combination with mes() and close(). - -If no window is currently on screen, one will be created, but once the -invoking character clicks on it, a warning is thrown on the server console -and the script will terminate. - - mes("[Woman]"); - mes("This would appear on the page"); - next(); - mes("[Woman]"); // This is needed since it is a new page and the top will now be blank - mes("This would appear on the 2nd page"); - ---------------------------------------- - -*close() - -This command will create a 'close' button in the message window for the -invoking character. If no window is currently on screen, the script -command 'end;' must be used. This is one of the ways to end a speech from -an NPC. Once the button is clicked, the NPC script execution will end, and -the message box will disappear. - - mes("[Woman]"); - mes("I am finished talking to you, click the close button."); - close(); - mes("This command will not run at all, since the script has ended."); - ---------------------------------------- - -*close2() - -This command will create a 'close' button in the message window for the -invoking character. WARNING: If no window is currently on screen, the -script execution will halt indefinitely! See 'close'. There is one -important difference, though - even though the message box will have -closed, the script execution will not stop, and commands after 'close2' -will still run, meaning an 'end' has to be used to stop the script, unless -you make it stop in some other manner. - - mes("[Woman]"); - mes("I will warp you now."); - close2(); - warp("place", 50, 50); - end; - -Don't expect things to run smoothly if you don't make your scripts 'end'. - ---------------------------------------- - -*end - -This instruction will stop the execution for this particular script. -Note that this is to be considered a special instruction (not a regular -command or function), and as such doesn't require parentheses. - - if (BaseLevel <= 10) { - npctalk("Look at that you are still a n00b"); - end; - } - if (BaseLevel <= 20) { - npctalk("Look at that you are getting better, but still a n00b"); - end; - } - if (BaseLevel <= 30) { - npctalk("Look at that you are getting there, you are almost 2nd profession now right???"); - end; - } - if (BaseLevel <= 40) { - npctalk("Look at that you are almost 2nd profession"); - end; - } - -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. - ---------------------------------------- - -*set(<variable>, <expression>) - -This command will set a variable to the value that the expression results -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 command is deprecated and it shouldn't be used in new scripts, except -some special cases (mostly, set(getvariableofnpc(), <value>)). Use direct value -assignment instead. - ---------------------------------------- - -*setd("<variable name>", <value>) - -Works almost identically as set(), except the variable name is -identified as a string and can thus be constructed dynamically. - -This command is equivalent to: - set(getd("variable name"), <value>); - -Examples: - - setd(".@var$", "Poporing"); - mes(.@var$); // Displays "Poporing". - - setd(".@" + .@var$ + "123$", "Poporing is cool"); - mes(.@Poporing123$); // Displays "Poporing is cool". - ---------------------------------------- - -*getd("<variable name>") - -Returns a reference to a variable, the name can be constructed dynamically. -Refer to setd() for usage. - -This can also be used to set an array dynamically: - setarray(getd(".array[0]"), 1, 2, 3, 4, 5); - -Examples: - - mes("The value of $varReference is: " + getd("$varRefence")); - set(.@i, getd("$" + "pikachu")); - ---------------------------------------- - -*getvariableofnpc(<variable>, "<npc name>") - -Returns a reference to a NPC variable (. prefix) from the target NPC. -This can only be used to get . variables. - -Examples: - -//This will return the value of .var, note that this can't be used, since -//the value isn't caught. - getvariableofnpc(.var, "TargetNPC"); - -//This will set the .@v variable to the value of the TargetNPC's .var -//variable. - .@v = getvariableofnpc(.var, "TargetNPC"); - -//This will set the .var variable of TargetNPC to 1. - set(getvariableofnpc(.var, "TargetNPC"), 1); - -Note: even though function objects can have .variables, -getvariableofnpc() should not be used on them. - ---------------------------------------- - -*getvariableofpc(<variable>, <account id>{, <default value>}) - -Returns a reference to a PC variable from the target player. -If <default value> is passed, it will return this value if the player is -not found. - -Examples: - -//This will return the value of @var, note that this can't be used, since -//the value isn't caught. - getvariableofpc(@var, getcharid(CHAR_ID_ACCOUNT, "player")); - -//This will set the .@v variable to the value of the player's @var -//variable. - .@v = getvariableofpc(@var, getcharid(CHAR_ID_ACCOUNT, "player")); - -//This will set the @var variable of the player to 1. - set(getvariableofpc(@var, getcharid(CHAR_ID_ACCOUNT, "player")), 1); - ---------------------------------------- - -*goto(<label>) - -This command will make the script jump to a label, usually used in -conjunction with other instructions, such as "if", but often used on its own. - - ... - goto(Label); - mes("This will not be seen"); -Label: - mes("This will be seen"); - -Gotos are considered to be harmful and should be avoided whenever possible. - ---------------------------------------- - -*menu("<option_text>", <target_label>{, "<option_text>", <target_label>, ...}) - -This command will create a selectable menu for the invoking character. -Only one menu can be on screen at the same time. - -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); - -It also sets a special temporary character variable @menu, which contains -the number of option the player picked. Numbering of options starts at 1. -This number is consistent with empty options and grouped options. - - menu("A::B", L_Wrong, "", L_Impossible, "C", L_Right); - L_Wrong: - // If they click "A" or "B" they will end up here - // @menu == 1 if "A" - // @menu == 2 will never happen because the option is empty - // @menu == 3 if "B" - L_Impossible: - // Empty options are not displayed and therefore can't be selected - // this label will never be reached from the menu command - L_Right: - // If they click "C" they will end up here - // @menu == 5 - -If a label is '-', the script execution will continue right after the menu -command if that option is selected, this can be used to save you time, and -optimize big scripts. - - menu("A::B:", -, "C", L_Right); - // If they click "A" or "B" they will end up here - // @menu == 1 if "A" - // @menu == 3 if "B" - L_Right: - // If they click "C" they will end up here - // @menu == 5 - -Both these examples will perform the exact same task. - -If you give an empty string as a menu item, the item will not display. -This can effectively be used to script dynamic menus by using empty string -for entries that should be unavailable at that time. - -You can do it by using arrays, but watch carefully - this trick isn't high -wizardry, but minor magic at least. You can't expect to easily duplicate -it until you understand how it works. - -Create a temporary array of strings to contain your menu items, and -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>); - .@j = 0; // That's the menu lines counter. - - // We loop through the list of possible menu items. - // .@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. - - if (<condition>) { - // We record the option into the list of options actually - // available. - .@menulist$[.@j] = .@possiblemenuitems$[.@i]; - - // We just copied the string, we do need it's number for later - // though, so we record it as well. - .@menureference[.@j] = .@i; - - // Since we've just added a menu item into the list, we - // increment the menu lines counter. - ++.@j; - } - - // We go on to the next possible menu item. - } - -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 -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>], -); - -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 -will show up past the end. But this menu() call doesn't jump anywhere, it -just continues execution right after the menu() command. (And it's a good -thing it doesn't, cause you can only explicitly define labels to jump to, -and how do you know which ones to define if you don't know beforehand -which options will end up where in your menu?) -But how do you figure out which option the user picked? Enter the @menu. - -@menu contains the number of option that the user selected from the list, -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]]+"!"); - -@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 -menu items that we've saved just for this purpose. - -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)' -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, -or make a randomly shuffled menu. - -Kafra code bundled with the standard distribution uses a similar -array-based menu technique for teleport lists, but it's much simpler and -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: - - .@dummy = select(.@menulist$[0], .@menulist$[1], ..., .@menulist$[<X>]); - -For the purposes of the technique described above these two statements are -perfectly equivalent. - ---------------------------------------- - -*select("<option>"{, "<option>", ...}) -*prompt("<option>"{, "<option>", ...}) - -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."); - -And like 'menu', the selected option is consistent with grouped options -and empty options. - -'prompt' works almost the same as select, except that when a character -clicks the Cancel button, this function will return 255 instead. - ---------------------------------------- - -*input(<variable>{, <min>{, <max>}}) - -This command will make an input box pop up on the client connected to the -invoking character, to allow entering of a number or a string. This has -many uses, one example would be a guessing game, also making use of the -'rand' function: - - mes("[Woman]"); - mes("Try and guess the number I am thinking of."); - mes("The number will be between 1 and 10."); - next(); - .@number = rand(1, 10); - input(.@guess); - if (.@guess == .@number) { - mes("[Woman]"); - mes("Well done that was the number I was thinking of"); - close(); - } else { - mes("[Woman]"); - mes("Sorry, that wasn't the number I was thinking of."); - close(); - } - -If you give the input() command a string variable to put the input in, it -will allow the player to enter text. Otherwise, only numbers will be -allowed. - - mes("[Woman]"); - mes("Please say HELLO"); - next(); - input(.@var$); - if (.@var$ == "HELLO") { - mes("[Woman]"); - mes("Well done you typed it correctly"); - close(); - } else { - mes("[Woman]"); - mes("Sorry you got it wrong"); - close(); - } - -Normally you may not input a negative number with this command. -This is done to prevent exploits in badly written scripts, which would let -people, for example, put negative amounts of Zeny into a bank script and -receive free Zeny as a result. - -The command has two optional arguments and a return value. -The default value of 'min' and 'max' can be set with 'input_min_value' and -'input_max_value' in conf/map/script.conf. -For numeric inputs the value is capped to the range [min, max]. Returns 1 -if the value was higher than 'max', -1 if lower than 'min' and 0 otherwise. -For string inputs it returns 1 if the string was longer than 'max', -1 is -shorter than 'min' and 0 otherwise. - ---------------------------------------- - -*callfunc("<function>"{, <argument>, ...<argument>}) - -This command lets you call up a function NPC. A function NPC can be called -from any script on any map server. Using the 'return' instruction it -will come back to the place that called it. - - place,50,50,6%TAB%script%TAB%Woman%TAB%115,{ - mes("[Woman]"); - mes("Lets see if you win"); - callfunc("funcNPC"); - mes("Well done you have won"); - close(); - } - function%TAB%script%TAB%funcNPC%TAB%{ - .@win = rand(2); - if (.@win == 0) - return; - mes("Sorry you lost"); - end; - } - -You can pass arguments to your function - values telling it what exactly -to do - which will be available there with getarg() (see 'getarg'). -Notice that returning is not mandatory, you can end execution right there. - -If you want to return a real value from inside your function NPC, you -may do so: - - place,50,50,6%TAB%script%TAB%Man%TAB%115,{ - mes("[Man]"); - mes("Gimme a number!"); - next(); - input(.@number); - if (callfunc("OddFunc", .@number)) - mes("It's Odd!"); - close(); - } - function%TAB%script%TAB%OddFunc%TAB%{ - if (getarg(0)%2==0) - return 0;// it's even - return 1;// it's odd - } - -Alternately, user-defined functions may be called directly without the use -of the callfunc() script command. - - function<TAB>script<TAB>SayHello<TAB>{ - mes("Hello " + getarg(0)); - return 0; - } - - place,50,50,6<TAB>script<TAB>Man<TAB>115,{ - mes("[Man]"); - SayHello(strcharinfo(PC_NAME)); - close(); - } - -Note: - - !! A user-defined function must be declared /before/ a script attempts to - !! call it. That is to say, any functions should be placed above scripts - !! or NPCs (or loaded in a separate file first) before attempting to call - !! them directly. - ---------------------------------------- - -*callsub(<label>{, <argument>, ...<argument>}) - -This command will go to a specified label within the current script (do -NOT use quotes around it) coming in as if it were a 'callfunc' call, and -pass it arguments given, if any, which can be recovered there with -'getarg'. When done there, you should use the 'return' command to go back -to the point from where this label was called. This is used when there is -a specific thing the script will do over and over, this lets you use the -same bit of code as many times as you like, to save space and time, -without creating extra NPC objects which are needed with 'callfunc'. A -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; - } - end; - -S_CheckFull: - if (getmapusers(getarg(0)) >= getarg(1)) { - mes("I'm sorry, this arena is full. Please try again later."); - close(); - } - return; - -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); - break; - case 2: - callsub(S_DunWarp, "ama_in02", 119, 181); - break; - case 3: - callsub(S_DunWarp, "moc_fild20", 164, 145); - break; - case 4: - callsub(S_DunWarp, "ayo_fild02", 279, 150); - break; - case 5: - callsub(S_DunWarp, "cmd_fild07", 132, 125); - break; - // etc - } - -// ... - -S_DunWarp: -// getarg(0) = "mapname" -// getarg(1) = x -// getarg(2) = y - if (Zeny >= 100) { - Zeny -= 100; - warp(getarg(0), getarg(1), getarg(2)); - } else { - mes("Dungeon warp costs 100 Zeny."); - } - close(); - ---------------------------------------- - -*getarg(<index>{, <default_value>}) - -This function is used when you use the 'callsub' or 'callfunc' commands. -In the call you can specify variables that will make that call different -from another one. This function will return an argument the function or -subroutine was called with, and is the normal way to get them. -This is another thing that can let you use the same code more than once. - -Argument numbering starts with 0, i.e. the first argument you gave is -number 0. If no such argument was given, a zero is returned. - - place,50,50,6%TAB%script%TAB%Woman1%TAB%115,{ - mes("[Woman]"); - mes("Lets see if you win"); - callfunc("funcNPC", 2); - mes("Well done you have won"); - // ... - } - - place,52,50,6%TAB%script%TAB%Woman2%TAB%115,{ - mes("[Woman]"); - mes("Lets see if you win"); - callfunc("funcNPC", 5); - mes("Well done you have won"); - // ... - } - - function%TAB%script%TAB%funcNPC%TAB%{ - .@win = rand(getarg(0)); - if (.@win == 0) - return; - mes("Sorry you lost"); - close(); - } - -"woman1" NPC object calls the funcNPC. The argument it gives in this call -is stated as 2, so when the random number is generated by the 'rand' -function, it can only be 0 or 1. Whereas "woman2" gives 5 as the argument -number 0 when calling the function, so the random number could be 0, 1, 2, -3 or 4, this makes "woman2" less likely to say the player won. - -You can pass multiple arguments in a function call: - - callfunc("funcNPC", 5, 4, 3); - -getarg(0) would be 5, getarg(1) would be 4 and getarg(2) would be 3. - -Getarg also has an optional argument: -If the target argument exists, it is returned. -Otherwise, if <default_value> is present it is returned instead, if not -the script terminates immediately. - -In previous example getarg(2, -1) would be 3 and getarg(3, -1) would be -1. - ---------------------------------------- - -*getargcount() - -This function is used when you use the 'callsub' or 'callfunc' commands. -In the call you can specify arguments. This function will return the -number of arguments provided. - -Example: - callfunc("funcNPC", 5, 4, 3); - // ... - function%TAB%script%TAB%funcNPC%TAB%{ - .@count = getargcount(); // 3 - //... - } - ---------------------------------------- - -*return {<value>} - -This instruction causes the script execution to leave previously called -function with callfunc() or script with callsub() and return to the -location, where the call originated from. Optionally a return value can -be supplied. - -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 - <variable> = callfunc("<your function>"); // when a value is being returned - ---------------------------------------- - -*function <function name>; -*<function name>{(<argument>, ...<argument>)}; -*function <function name> { -<code> -} - -This works like callfunc(), and is used for cleaner and faster scripting. -The function must be defined and used within a script, and works like a -label with arguments. -Note that the name may only contain alphanumeric characters and underscore. - -Usage: - - 1. Declare the function. - function <function name>; - 2. Call the function anywhere within the script. - It can also return a value when used with parentheses. - <function name>; - 3. Define the function within the script. - <function name> {<code>} - -Example: - -prontera,154,189,4 script Item Seller 767,{ - /* Function declaration */ - function SF_Selling; - - if (Zeny > 50) { - mes("Welcome!"); - /* Function call */ - SF_Selling(); - } else { - mes("You need 50z, sorry!"); - } - close(); - - /* Function definition */ - function SF_Selling { - mes("Would you like to buy a phracon for 50z?"); - next(); - if (select("Yes", "No, thanks") == 1) { - Zeny -= 50; - getitem(Phracon, 1); - mes("Thank you!"); - } - return; - } -} - -Example with parameters and return value: - -prontera,150,150,0 script TestNPC 123,{ - /* Function declaration */ - function MyAdd; - - mes("Enter two numbers."); - next(); - input(.@a); - input(.@b); - /* Function call */ - mes(.@a+" + "+.@b+" = "+MyAdd(.@a, .@b)); - close(); - - /* Function definition */ - function MyAdd { - return(getarg(0)+getarg(1)); - } -} - - ---------------------------------------- - -*is_function("<function name>") - -This command checks whether a function exists. -It returns 1 if function is found, or 0 if it isn't. - -Example: - - function script try { - dothat(); - } - - - script test FAKE_NPC,{ - .@try = is_function("try"); // 1 - .@not = is_function("notafunction"); // 0 - } - ---------------------------------------- - -*if (<condition>) <statement or block> - -This is the basic conditional command. - -The condition can be any expression. All expressions resulting in a -non-zero value will be considered True, including negative values. All -expressions resulting in a zero are false. - -If the expression results in True, the statement will be executed. If it -isn't true, nothing happens and we move on to the next line of the script. - - if (true) - mes("This will always print."); - if (0) - mes("And this will never print."); - if (5) - mes("This will also always print."); - if (-1) - mes("Funny as it is, this will also print just fine."); - -For more information on conditional operators see the operators section -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(PC_NAME) == "Daniel Jackson") - mes("It is true, you are Daniel!"); - -More examples of using the 'if' command in the real world: - -Example 1: - - .@var1 = 1; - input(.@var2); - if (.@var1 == .@var2) - close(); - mes("Sorry that is wrong"); - close(); - -Example 2: - - .@var1 = 1; - input(.@var2); - if (.@var1 != .@var2) - mes("Sorry that is wrong"); - close(); - -(Notice examples 1 and 2 have the same effect.) - -Example 3: - - ++@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]"); - // 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(); - -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(); - -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>) { - dothis1(); - dothis2(); -} else { - dothat1(); - dothat2(); - dothat3(); -} - -Example 6: - - mes("[Person Checker]"); - if ($name$ == "") { - mes("Please tell me someone's name"); - next(); - input($name$); - $name2$ = strcharinfo(PC_NAME); - mes("[Person Checker]"); - mes("Thank you"); - close(); - } - if ($name$ == strcharinfo(PC_NAME)) { - 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 -course, you stop the execution of the script if the condition is true -(that is, in the first grouping using a return, and end or a close()). - -Also, you can have multiple conditions nested or chained, and don't worry -about limits as to how many nested if you can have, there is no spoon ;). - -... -if (<condition 1>) { - dothis(); -} else if (<condition 2>) { - dotheother(); - do_that(); - end; -} else { - do_this(); -} -... - ---------------------------------------- - -*while (<condition>) <statement or block> - -This is probably the simplest and most frequently used loop structure. The -'while' statement can be interpreted as "while <condition> is true, -perform <statement>". It is a pretest loop, meaning the conditional -expression is tested before any of the statements in the body of the loop -are performed. If the condition evaluates to false, the statement(s) in -the body of the loop is/are never executed. If the condition evaluates to -true, the statement(s) are executed, then control transfers back to the -conditional expression, which is reevaluated and the cycle continues. - -Multiple statements can be grouped with { }, curly braces, just like with -the 'if' statement. - -Example 1: - while (switch(select("Yes", "No") == 2)) - mes("You picked no."); - -Example 2: multiple statements - while (switch(select("Yes", "No") == 2 )) { - mes("Why did you pick no?"); - mes("You should pick yes instead!"); - } - -Example 3: counter-controlled loop - .@i = 1; - while (.@i <= 5) { - mes("This line will print 5 times."); - ++.@i; - } - -Example 4: sentinel-controlled loop - mes("Input 0 to stop"); - input(.@num); - while (.@num != 0) { - mes("You entered " + .@num); - input(.@num); - } - close(); - ---------------------------------------- - -*for (<variable initialization>; <condition>; <variable update>) <statement or block> - -Another pretest looping structure is the 'for' statement. It is considered -a specialized form of the 'while' statement, and is usually associated -with counter-controlled loops. Here are the steps of the 'for' statement: -the initialize statement is executed first and only once. The condition -test is performed. When the condition evaluates to false, the rest of the -for statement is skipped. When the condition evaluates to true, the body -of the loop is executed, then the update statement is executed (this -usually involves incrementing a variable). Then the condition is -reevaluated and the cycle continues. - -Example 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 (.@i = 1; .@i <= 5; ++.@i) - mes(.@i); - ---------------------------------------- - -*do { <statements>; } while (<condition>) - -The 'do...while' is the only post-test loop structure available in this -script language. With a post-test, the statements are executed once before -the condition is tested. When the condition is true, the statement(s) are -repeated. When the condition is false, control is transferred to the -statement following the 'do...while' loop expression. - -Example 1: sentinel-controlled loop - mes("This menu will keep appearing until you pick Cancel"); - do { - .@choice = select("One:Two:Three:Cancel"); - } while (.@choice != 4); - -Example 2: counter-controlled loop - mes("This will countdown from 10 to 1."); - .@i = 10; - do { - mes(.@i--); - } while (.@i > 0); - ---------------------------------------- - -*freeloop(<toggle>) - -Toggling this to enabled (true) allows the script instance to bypass the -infinite loop protection, allowing your script to loop as much as it may -need. Disabling (false) 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(true); // enable script to loop freely - - //Be aware with what you do here. - 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.) - } - - freeloop(false); // disable - - for (.@i = 0; .@i < .@bigloop; ++.@i) { - dothis(); - // throw an infinity loop error - } - ---------------------------------------- - -*setarray(<array name>[<first value>], <value>{, <value>...<value>}) - -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); - -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); - -will produce: - - .@array[0] = 200 - .@array[1] = 300 - .@array[2] = 150 - ---------------------------------------- - -*cleararray(<array name>[<first value to alter>], <value>, <number of values to set>) - -This command will change many array values at the same time to the same -value. - - 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'. - ---------------------------------------- - -*copyarray(<destination array>[<first value>], <source array>[<first value>], <amount of data to copy>) - -This command lets you quickly shuffle a lot of data between arrays, which -is in some cases invaluable. - - 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 - -New Array: - .@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, -and it will return a 0. - ---------------------------------------- - -*deletearray(<array name>[<first value>], <how much to delete>) - -This command will delete a specified number of array elements totally from -an array, shifting all the elements beyond this towards the beginning. - - // 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 all elements of the array starting from 2, leaving - // element 0 and 1 - deletearray(.@array[2]); - - // This would delete all elements of the array - deletearray(.@array); - ---------------------------------------- -//===================================== -1 - End of Basic-Related Commands -//===================================== ---------------------------------------- - - ---------------------------------------- -//===================================== -2 - Information-retrieving Related Commands -//===================================== ---------------------------------------- - -*strcharinfo(<type>{, <default value>{, <GID>}}) - -This function will return either the name, party name or guild name for -the invoking character. Whatever it returns is determined by type. -(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 <GID> is passed, it will return the value of the specified player instead -the attached player. If the player is not found, it will return -<default value>, if any, or else return an empty string. - -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>{, <default value>{, <GID>}}) - -This function will return the various parts of the name of the calling NPC. -Whatever it returns is determined by type. - -(0) NPC_NAME - The NPC's display name (visible#hidden) -(1) NPC_NAME_VISIBLE - The visible part of the NPC's display name -(2) NPC_NAME_HIDDEN - The hidden part of the NPC's display name -(3) NPC_NAME_UNIQUE - The NPC's unique name (::name) -(4) NPC_MAP - The name of the map the NPC is in. - -If <GID> is passed, it will return the value of the specified NPC instead of -the attached NPC. If the NPC is not found, it will return <default value>, -if any, or else return an empty string. - ---------------------------------------- - -*charid2rid(<char id>) - -This function returns the RID of the character with the given character ID. - -If the character is offline or doesn't exist, 0 is returned. - ---------------------------------------- - -*getarraysize(<array name>) - -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, 100, 200, 300, 400, 500, 600); - .@arraysize = getarraysize(.@array); - -This will make .@arraysize == 6. But if you try this: - - 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. - ---------------------------------------- - -*getarrayindex(<array name>) - -This command returns the index of the passed array. This is useful when -used in combination with getarg() - -Example: - - getarrayindex(.@foo[42]) // 42 - ---------------------------------------- - -*getelementofarray(<array name>, <index>) - -This command retrieves the value of the element of given array at given -index. This is equivalent to using: - - <array name>[<index>] - -Also useful when passing arrays to functions or accessing another npc's -arrays: - getelementofarray(getarg(0), <index>) - getelementofarray(getvariableofnpc(.var, "testNPC"), <index>) - ---------------------------------------- - -*readparam(<parameter number>{, "<player name>"}) - -This function will return the basic stats of an invoking character, -referred to by the parameter number. Instead of a number, you can use a -parameter name if it is defined in 'db/constants.conf'. - -Example parameters: - -StatusPoint, BaseLevel, SkillPoint, Class, Upper, Zeny, Sex, Weight, -MaxWeight, JobLevel, BaseExp, JobExp, NextBaseExp, NextJobExp, Hp, MaxHp, -Sp, MaxSp, BaseJob, Karma, Manner, bVit, bDex, bAgi, bStr, bInt, bLuk - -All of these also behave as variables, but don't expect to be able to just -'set' them - some will not work for various internal reasons. - -Example 1: - - // 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); - -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!"); - -Example 3: - - // Display your current weight - mes("Your current weight is "+ (Weight/10) + "/" + (MaxWeight/10)); - ---------------------------------------- - -*getcharid(<type>{, "<character name>"}) - -This function will return a unique ID number of the invoking character, -or, if a character name is specified, of that player. - -Type is the kind of associated ID number required: - -(0) CHAR_ID_CHAR - Character ID number. -(1) CHAR_ID_PARTY - Party ID number. -(2) CHAR_ID_GUILD - Guild ID number. -(3) CHAR_ID_ACCOUNT - Account ID number. -(4) CHAR_ID_BG - Battle ground ID - -For most purposes other than printing it, a number is better to have than -a name (people do horrifying things to their character names). - -If the character is not in a party or not in a guild, the function will -return 0 if guild or party number is requested. If a name is specified and -the character is not found, 0 is returned. - -If getcharid(CHAR_ID_CHAR) returns a zero, the script got called not by a character -and doesn't have an attached RID. Note that this will cause the map server -to print "player not attached!" error messages, so it is preferred to use -playerattached() to check for the character attached to the script. - - if (getcharid(CHAR_ID_GUILD) == 0) - mes("Only members of a guild are allowed here!"); - ---------------------------------------- - -*getnpcid(<type>{, "<npc name>"}) - -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) - -If an invalid type is given or the NPC does not exist, 0 is returned. - ---------------------------------------- - -*getchildid() -*getmotherid() -*getfatherid() - -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() != 0) - mes("Your mother's ID is: "+getmotherid()); - ---------------------------------------- - -*ispartneron() - -This function returns true if the invoking character's marriage partner -is currently online and false if they are not or if the character has no -partner. - ---------------------------------------- - -*getpartnerid() - -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() == 0) - mes("I'm not going to be your girlfriend!"); - else - mes("You're married already!"); - ---------------------------------------- - -*getpartyname(<party id>) - -This function will return the name of a party that has the specified ID -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!"); - ---------------------------------------- - -*getpartymember(<party id>{, <type>}) - -This command will find all members of a specified party and returns their -names (or character id or account id depending on the value of "type") -into an array of temporary global variables. There's actually quite a few -commands like this which will fill a special variable with data upon -execution and not do anything else. - -Upon executing this, - -$@partymembername$[] is a global temporary string array which contains all - the names of these party members. - (only set when type is 0 or not specified) - -$@partymembercid[] is a global temporary number array which contains the - character id of these party members. - (only set when type is 1) - -$@partymemberaid[] is a global temporary number array which contains the - account id of these party members. - (only set when type is 2) - -$@partymembercount is the number of party members that were found. - -The party members will (apparently) be found regardless of whether they -are online or offline. Note that the names come in no particular order. - -Be sure to use $@partymembercount to go through this array, and not -'getarraysize', because it is not cleared between runs of 'getpartymember'. -If someone with 7 party members invokes this script, the array would have -7 elements. But if another person calls up the NPC, and he has a party of -5, the server will not clear the array for you, overwriting the values -instead. So in addition to returning the 5 member names, the 6th and 7th -elements from the last call remain, and you will get 5+2 members, of which -the last 2 don't belong to the new guy's party. $@partymembercount will -always contain the correct number, (5) unlike 'getarraysize()' which will -return 7 in this case. - -Example 1: list party member names - - // get the party member names - getpartymember(getcharid(CHAR_ID_PARTY), 0); - - // 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. - .@count = $@partymembercount; - copyarray(.@name$[0], $@partymembername$[0], $@partymembercount); - - // list the party member names - for (.@i = 0; .@i < .@count; ++.@i) { - mes((.@i +1) + ". ^0000FF" + .@name$[.@i] + "^000000"); - } - close(); - - -Example 2: check party count (with a next() pause), before warping to event - - .register_num = 5; // How many party members are required? - - // get the charID and accountID of character's party members - getpartymember(getcharid(CHAR_ID_PARTY), 1); - getpartymember(getcharid(CHAR_ID_PARTY), 2); - - 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 (.@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. - - if (.@count_online != .register_num) { - mes("All your party members must be online to continue"); - close(); - } - - // copy the array to prevent players cheating the system - copyarray(.@partymembercid, $@partymembercid, .register_num); - - 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. - - getpartymember(getcharid(CHAR_ID_PARTY), 1); - if ($@partymembercount != .register_num) { - mes("You've made changes to your party !"); - close(); - } - for (.@i = 0; .@i < $@partymembercount; ++.@i) { - if (.@partymembercid[.@i] != $@partymembercid[.@i]) { - mes("You've made changes to your party !"); - close(); - } - } - - // Finally, it's safe to start the event! - warpparty("event_map", 0, 0, getcharid(CHAR_ID_PARTY), true); - ---------------------------------------- - -*getpartyleader(<party id>{, <type>}) - -This function returns some information about the given party-id's leader. -When type is omitted, the default information retrieved is the leader's -name. Possible types are: - - 1: Leader account id - 2: Leader character id - 3: Leader's class - 4: Leader's current map name - 5: Leader's current level as stored on the party structure (may not be - current level if leader leveled up recently). - -If retrieval fails (leader not found or party does not exist), this -function returns "null" instead of the character name, and -1 for the -other types. - ---------------------------------------- - -*getlook(<type>) - -This function will return the number for the current character look value -specified by type. See 'setlook' for valid look types. - -This can be used to make a certain script behave differently for -characters dressed in black. :) - ---------------------------------------- - -*getsavepoint(<information type>) - -This function will return information about the invoking character's save -point. You can use it to let a character swap between several recorded -save points. Available information types are: - - 0 - Map name (a string) - 1 - X coordinate - 2 - Y coordinate - ---------------------------------------- - -*getcharip({"<character name>"|<account id>|<char id>}) - -This function will return the IP address of the invoking character, or, if -a player is specified, of that character. A blank string is returned if no -player is attached. - -Examples: - -// Outputs IP address of attached player. - mes("Your IP: " + getcharip()); - -// 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 true, otherwise (standing) it will return false. -In case no player is specified, the function will return the state of the attached player. - ---------------------------------------- -//===================================== -2.1 - Item-Related Commands -//===================================== ---------------------------------------- - -*getequipid(<equipment slot>) - -This function returns the item ID of the item equipped in the equipment -slot specified on the invoking character. If nothing is equipped there, it -returns -1. Valid equipment slots are: - -EQI_HEAD_TOP (1) - Upper head gear -EQI_ARMOR (2) - Armor (Where you keep your Jackets and Robes) -EQI_HAND_L (3) - What is in your Left hand. -EQI_HAND_R (4) - What is in your Right hand. -EQI_GARMENT (5) - The garment slot (Mufflers, Hoods, Manteaus) -EQI_SHOES (6) - What foot gear the player has on. -EQI_ACC_L (7) - Accessory 1. -EQI_ACC_R (8) - Accessory 2. -EQI_HEAD_MID (9) - Middle Headgear (masks and glasses) -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 -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) == 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) == 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(<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 -position. -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 (getequipid(EQI_HEAD_TOP) != 0) - mes("So you are wearing a "+getequipname(EQI_HEAD_TOP)+" on your head"); - else - mes("You are not wearing a head gear"); - ---------------------------------------- - -*getitemname(<item id>) - -Given the database ID number of an item, this function will return the -text stored in the 'japanese name' field (which, in Hercules, stores an -English name the players would normally see on screen). -Return "null" if no such item exist. - ---------------------------------------- - -*getbrokenid(<number>) - -This function will search the invoking character's inventory for any -broken items, and will return their item ID numbers. Since the character -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) - 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!"); - ---------------------------------------- - -*getbrokencount() - -This function will return the total amount of broken equipment on the -invoking character. - ---------------------------------------- - -*getequipisequiped(<equipment slot>) - -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)) { - 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(); - ---------------------------------------- - -*getequipisenableref(<equipment slot>) - -Will return true if the item equipped on the invoking character in the -specified equipment slot is refinable, and false if it isn't. For a list -of equipment slots see getequipid(). - - if (getequipisenableref(EQI_HEAD_TOP)) { - mes("[Refiner]"); - mes("Ok I can refine this"); - close(); - } - mes("[Refiner]"); - mes("I can't refine this hat!..."); - close(); - ---------------------------------------- - -*getequiprefinerycnt(<equipment slot>) - -Returns the current number of pluses for the item in the specified -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) - mes("I will now upgrade your "+getequipname(EQI_HEAD_TOP)); - else - mes("Sorry, it's not possible to refine hats better than +10"); - ---------------------------------------- - -*getequipweaponlv(<equipment slot>) - -This function returns the weapon level for the weapon equipped in the -specified equipment slot on the invoking character. For a list of -equipment slots see 'getequipid'. - -Only EQI_HAND_L and EQI_HAND_R normally make sense, since only weapons -have a weapon level. You can, however, probably, use this field for other -equippable custom items as a flag or something. - -If no item is equipped in this slot, or if it doesn't have a weapon level -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; - } - -// 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; - } - ---------------------------------------- - -*getequippercentrefinery(<equipment slot>{, <type>}) - -This function calculates and returns the percent value chance to -successfully refine the item found in the specified equipment slot of the -invoking character by +1. Refine rates are defined in the db/<re/pre-re>/refine_db.conf -files. For a list of equipment slots see getequipid(). - -These values can be displayed for the player to see, or used to calculate -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). - -Refine Chance Type Constants - -REFINE_CHANCE_TYPE_NORMAL: 0 (Normal Ores) -REFINE_CHANCE_TYPE_ENRICHED: 1 (Enriched Ores) -REFINE_CHANCE_TYPE_E_NORMAL: 2 (Event Normal Ores) -REFINE_CHANCE_TYPE_E_ENRICHED: 3 (Event Enriched Ores) - -Refine rate information - -Normal Ores: http://ro.gnjoy.com/news/probability/View.asp?category=4&seq=1941553&curpage=1 -Enriched Ores: http://ro.gnjoy.com/news/probability/View.asp?category=4&seq=1941565&curpage=1 -Event Normal Ores: http://ro.gnjoy.com/news/probability/View.asp?category=4&seq=1941558&curpage=1 -Event Enriched Ores: http://ro.gnjoy.com/news/probability/View.asp?category=4&seq=1941567&curpage=1 - -// 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 show a message - if (getequippercentrefinery(EQI_HAND_L, REFINE_CHANCE_TYPE_NORMAL) <= rand(100)) - mes("Aww"); - ---------------------------------------- - -*getareadropitem("<map name>", <x1>, <y1>, <x2>, <y2>, <item>) - -This function will count all the items with the specified ID number lying -on the ground on the specified map within the x1/y1-x2/y2 square on it and -return that number. - -This is the only function around where a parameter may be either a string -or a number! If it's a number, it means that only the items with that item -ID number will be counted. If it is a string, it is assumed to mean the -'english name' field from the item database. If you give it an empty -string, or something that isn't found from the item database, it will -count items number 512 (Apple). - ---------------------------------------- - -*getequipcardcnt(<equipment slot>) - -This function will return the number of cards that have been compounded -onto a specific equipped item for the invoking character. See 'getequipid' -for a list of possible equipment slots. - ---------------------------------------- - -*getinventorylist() - -This command sets a bunch of arrays with a complete list of whatever the -invoking character has in its inventory, including all the data needed to -recreate these items perfectly if they are destroyed. Here's what you get: - -@inventorylist_id[] - array of item ids. -@inventorylist_amount[] - their corresponding item amounts. -@inventorylist_equip[] - will return the slot the item is equipped on, if at all. -@inventorylist_refine[] - for how much it is refined. -@inventorylist_identify[] - whether it is identified. -@inventorylist_attribute[] - whether it is broken. -@inventorylist_card1[] - These four arrays contain card data for the -@inventorylist_card2[] items. These data slots are also used to store -@inventorylist_card3[] names inscribed on the items, so you can -@inventorylist_card4[] explicitly check if the character owns an item - made by a specific craftsman. -@inventorylist_expire[] - expire time (Unix time stamp). 0 means never - expires. -@inventorylist_bound - whether it is an account bounded item or not. -@inventorylist_count - the number of items in these lists. - -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 -only way to correctly handle an NPC trader for carded and named items who -could resell them - since NPC objects cannot own items, so they have to -store item data in variables and recreate the items. - -Notice that the variables this command generates are all temporary, -attached to the character, and integer. - -Be sure to use @inventorylist_count to go through these arrays, and not -getarraysize(), because the arrays are not automatically cleared between -runs of getinventorylist(). - ---------------------------------------- - -*getcartinventorylist() - -This command sets a bunch of arrays with a complete list of whatever the -invoking character has in its cart_inventory, including all the data needed to -recreate these items perfectly if they are destroyed. Here's what you get: - -@cartinventorylist_id[] - array of item ids. -@cartinventorylist_amount[] - their corresponding item amounts. -@cartinventorylist_refine[] - for how much it is refined. -@cartinventorylist_identify[] - whether it is identified. -@cartinventorylist_attribute[] - whether it is broken. -@cartinventorylist_card1[] - These four arrays contain card data for the -@cartinventorylist_card2[] items. These data slots are also used to store -@cartinventorylist_card3[] names inscribed on the items, so you can -@cartinventorylist_card4[] explicitly check if the character owns an item - made by a specific craftsman. -@cartinventorylist_expire[] - expire time (Unix time stamp). 0 means never - expires. -@cartinventorylist_bound - whether it is an account bound item or not. -@cartinventorylist_count - the number of items in these lists. - -This could be handy to save/restore a character's cart_inventory, since no -other command returns such a complete set of data, and could also be the -only way to correctly handle an NPC trader for carded and named items who -could resell them - since NPC objects cannot own items, so they have to -store item data in variables and recreate the items. - -Notice that the variables this command generates are all temporary, -attached to the character, and integer. - -Be sure to use @cartinventorylist_count to go through these arrays, and not -getarraysize(), because the arrays are not automatically cleared between -runs of getcartinventorylist(). - ---------------------------------------- - -*cardscnt() - -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?"); - ---------------------------------------- - -*getrefine() - -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."); - ---------------------------------------- - -*getitemslots(<item ID>) - -This function will look up the item with the specified ID number in the -database and return the number of slots this kind of items has - 0 if they -are not slotted. It will also be 0 for all non-equippable items, -naturally, unless someone messed up the item database. It will return -1 -if there is no such item. - -Example: - -//.@slots now has the amount of slots of the item with ID 1205. - .@slots = getitemslots(1205); - ---------------------------------------- - -*getiteminfo(<item ID>, <type>) - -This function will look up the item with the specified ID number in the -database and return the info set by TYPE argument. -It will return -1 if there is no such item. - -Valid types are: - 0 - Buy Price; 1 - Sell Price; 2 - Item Type; - 3 - maxchance (Max drop chance of this item e.g. 1 = 0.01% , etc.. - if = 0, then monsters don't drop it at all (rare or a quest item) - if = 10000, then this item is sold in NPC shops only - 4 - sex; 5 - equip; 6 - weight; 7 - atk; 8 - def; 9 - range; - 10 - slot; 11 - look; 12 - elv; 13 - wlv; 14 - view id - - If RENEWAL is defined, 15 - matk - -Check sample in doc/sample/getiteminfo.txt - ---------------------------------------- - -*getequipisenableopt(<equipment slot>) - -This function checks if the equipped item allows the use of bonus options. - -Returns 1 if allowed, 0 if not. - ---------------------------------------- - -*getequippedoptioninfo(<info_type>); - -This function is to be used with the scripts of contents listed in -db/item_options.conf only. - -Returns the value of the current equipment being parsed. -If the equip was not found or the type is invalid, -1 is returned. - ---------------------------------------- - -*getequipoptioninfo(<equip_index>,<slot>,<type>); - -Gets the option information of an equipment. - -<equipment_index> For a list of equipment indexes see getequipid(). -<option_slot> can range from 1 to MAX_ITEM_OPTIONS -<type> can be IT_OPT_INDEX (the ID of the option bonus, @see "Id" or "Name" in db/item_options.conf) - or IT_OPT_VALUE (the value of the bonus script of the equipment, @see "Script" in db_item_options.conf). - -returns the value of the slot if exists or -1 for invalid slot, type or slots. - ---------------------------------------- - -*setequipoption(<equip_index>,<slot>,<opt_index>,<value>); - -Set an equipment's option index or value for the specified option slot. - -<equipment_index> For a list of equipment indexes see getequipid(). -<option_slot> can range from 1 to MAX_ITEM_OPTIONS -<type> can be IT_OPT_INDEX (the ID of the option bonus, @see "Id" or "Name" in db/item_options.conf) -<value> The value of the type to be set. - -returns 0 if value couldn't be set, 1 on success. - ---------------------------------------- - -*getequipcardid(<equipment slot>, <card slot>) - -Returns value for equipped item slot in the indicated slot (0, 1, 2, or 3). - -This function returns CARD ID, 255, 254, -255 (for card 0, if the item is -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 -//===================================== ---------------------------------------- - -*getmapxy("<variable for map name>", <variable for x>, <variable for y>, <type>{, "<search parameter>"}) - -This function will locate a character object, NPC object or pet's -coordinates and place their coordinates into the variables specified when -calling it. It will return 0 if the search was successful, and -1 if the -parameters given were not variables or the search was not successful. - -Type is the type of object to search for: - - UNITTYPE_PC - Character object - UNITTYPE_NPC - NPC object - UNITTYPE_PET - Pet object - UNITTYPE_MOB - Monster object - UNITTYPE_HOM - Homunculus object - UNITTYPE_MER - Mercenary object - UNITTYPE_ELEM - Elemental object - -To look for a monster object, monster GID is required. The function will -always return -1 when search using string. - -The search parameter is optional. If it is not specified, the location of the -invoking character will always be returned for UNITTYPE_PC, the location of the -NPC running this function for UNITTYPE_NPC. If a search parameter is specified, -for UNITTYPE_PC and UNITTYPE_NPC, the character or NPC with the specified name -or GID will be located. - -If type is UNITTYPE_PET, UNITTYPE_HOM, UNITTYPE_MER or UNITTYPE_ELEM the search -will locate the owner's pet/homun/mercenary/elementals if the search parameter -is not provided. It will NOT locate these object by name, but can be done if GID -is provided. - -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,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, UNITTYPE_NPC, "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(); - } - -Notice that NPC objects disabled with disablenpc() will still be located. - ---------------------------------------- - -*getunits(<type>, <variable>, <limit>, "<map>"{, <x1>, <y1>, <x2>, <y2>}) - -This function searches a whole map or area for units and adds their GID to -the provided <variable> array. It filters units by <type> and stops searching -after <limit> units have been found. Set <limit> to false (0) if you wish to -disable the limit altogether. - -Type is the type of unit to search for: - - BL_PC - Character object - BL_MOB - Monster object - BL_PET - Pet object - BL_HOM - Homunculus object - BL_MER - Mercenary object - BL_IEM - Item object (item drops) - BL_SKILL - Skill object (skill fx & sfx) - BL_NPC - NPC object - BL_CHAT - Chat object - BL_ELEM - Elemental object - BL_CHAR - Shorthand for (BL_PC|BL_MOB|BL_HOM|BL_MER|BL_ELEM) - BL_ALL - Any kind of object - -** Do NOT use UNITTYPE_ constants here, they have different values. - -Example: - - .@count = getunits((BL_PC | BL_NPC), .@units, false, "prontera"); - -The above example would search the map "prontera" for all PC and NPC units and -add them to the .@units array, while setting .@count to the amount of units -added to the array (useful in for() loops). - ---------------------------------------- - -*getgmlevel() - -This function will return the (GM) level of player group the account to -which the invoking character belongs. If this is somehow executed from a -console command, 99 will be returned, and 0 will be returned if the -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() > 0) - mes("What is your command, your godhood?"); - if (getgmlevel() < 99) - end; - ---------------------------------------- - -*setgroupid(<new group id>{, "<character name>"|<account id>}) - -This function will temporary adjust the id of player group the account to which the -player specified if the new group id is available. -Return true if successful, otherwise it will return false. - ---------------------------------------- - -*getgroupid() - -This function will return the id of player group the account to which the -invoking player belongs. - ---------------------------------------- - -*gettimetick(<type>) - -Valid types are : - 0 - server's tick (milleseconds), unsigned int, loops every ~50 days - 1 - time since the start of the current day in seconds - 2 - UNIX epoch time (number of seconds elapsed since 1st of January 1970) - ---------------------------------------- - -*gettime(<type>) - -This function returns specified information about the current system time. - -Valid types: - 1 - GETTIME_SECOND - Seconds (of a minute) - 2 - GETTIME_MINUTE - Minutes (of an hour) - 3 - GETTIME_HOUR - Hour (of a day) - 4 - GETTIME_WEEKDAY - Week day (0 for Sunday, 6 is Saturday) - - Additional: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY - 5 - GETTIME_DAYOFMONTH - Day of the month. - 6 - GETTIME_MONTH - Number of the month. - - Additional: JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER - 7 - GETTIME_YEAR - Year - 8 - GETTIME_DAYOFYEAR - Day of the year. - -It will only return numbers based on types. -Example : - if (gettime(GETTIME_WEEKDAY) == SATURDAY) { - mes("It's a Saturday. I don't work on Saturdays."); - } else if (gettime(GETTIME_MONTH) == JANUARY) { - mes("It's January. I don't work on January."); - } else if (gettime(GETTIME_MONTH) == OCTOBER && gettime(GETTIME_DAYOFMONTH) == 31) { - mes("It's Halloween."); - } - ---------------------------------------- - -*gettimestr(<format string>, <max length>) - -This function will return a string containing time data as specified by -the format string. - -This uses the C function 'strfmtime', which obeys special format -characters. For a full description see, for example, the description of -'strfmtime' at http://www.delorie.com/gnu/docs/glibc/libc_437.html -All the format characters given in there should properly work. -Max length is the maximum length of a time string to generate. - -The example given in Hercules sample scripts works like this: - - mes(gettimestr("%Y-%m/%d %H:%M:%S", 21)); - -This will print a full date and time like 'YYYY-MM/DD HH:MM:SS'. - ---------------------------------------- - -*getusers(<type>) - -This function will return a number of users on a map or the whole server. -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. - ---------------------------------------- - -*getmapusers("<map name>") - -This function will return the number of users currently located on the -specified map. - -Currently being used in the PVP scripts to check if a PVP room is full of -not, if the number returned it equal to the maximum allowed it will not -let you enter. - -Return -1 if the map name is invalid. - ---------------------------------------- - -*getareausers({"<map name>", }{<x1>, <y1>, <x2>, <y2>}) -*getareausers({"<map name>", }{<radius>}) - -This function will return the count of connected characters which are -located within the specified area. Area can be x1/y1-x2/y2 square, -or radius from npc position. If map name missing, used attached player map. - -This is useful for maps that are split into many buildings, such as all -the "*_in" maps, due to all the shops and houses. - -Examples: - // return players in area npc area on current map. - .@num = getareausers(); - // return players in square (1, 1) - (10, 10) - .@num = "players: " + getareausers(1, 1, 10, 10); - ---------------------------------------- - -*getusersname(); - -This command will give the invoking character a list of names of the -connected characters (including themselves) into an NPC script message -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 -//===================================== ---------------------------------------- - -*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."); - - // 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. - ---------------------------------------- - -*getguildmaster(<guild id>) - -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)); - -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: - - .@GID = getcharid(CHAR_ID_GUILD); - if (.@GID == 0) { - mes("Sorry you are not in a guild"); - close(); - } - if (strcharinfo(PC_NAME) == getguildmaster(.@GID)) { - mes("Welcome guild master of "+getguildname(.@GID)); - close(); - } - mes("Sorry you don't own the guild you are in"); - close(); - ---------------------------------------- - -*getguildmasterid(<guild id>) - -This function will return the character ID number of the guild master of -the guild specified by the ID. 0 if the character is not a guild master of -any guild. - ---------------------------------------- - -*getcastlename("<map name>") - -This function returns the name of the castle when given the map name for -that castle. The data is read from 'db/castle_db.txt'. - ---------------------------------------- - -*getcastledata("<map name>", <type of data>) -*setcastledata("<map name>", <type of data>, <value>); - -This function returns the castle ownership information for the castle -referred to by its map name. Castle information is stored in -`guild_castle` SQL table. - -Types of data correspond to `guild_castle` table columns: - - 1 - `guild_id` - Guild ID. - 2 - `economy` - Castle Economy score. - 3 - `defense` - Castle Defense score. - 4 - `triggerE` - Number of times the economy was invested in today. - 5 - `triggerD` - Number of times the defense was invested in today. - 6 - `nextTime` - unused - 7 - `payTime` - unused - 8 - `createTime` - unused - 9 - `visibleC` - Is 1 if a Kafra was hired for this castle, 0 otherwise. -10 - `visibleG0` - Is 1 if the 1st guardian is present (Soldier Guardian) -11 - `visibleG1` - Is 1 if the 2nd guardian is present (Soldier Guardian) -12 - `visibleG2` - Is 1 if the 3rd guardian is present (Soldier Guardian) -13 - `visibleG3` - Is 1 if the 4th guardian is present (Archer Guardian) -14 - `visibleG4` - Is 1 if the 5th guardian is present (Archer Guardian) -15 - `visibleG5` - Is 1 if the 6th guardian is present (Knight Guardian) -16 - `visibleG6` - Is 1 if the 7th guardian is present (Knight Guardian) -17 - `visibleG7` - Is 1 if the 8th guardian is present (Knight Guardian) - -All types of data have their meaning determined by War of Emperium -scripts, with exception of: - - `guild_id` that is always the ID of the guild that owns the castle, - - `defense` that is used in Guardians & Emperium HP calculations, - - `visibleG` that is always considered to hold guardian presence bits. - -The setcastledata() command will behave identically, but instead of -returning values for the specified types of accessible data, it will alter -them and cause them to be sent to the char-server for storage. - -Changing Guild ID or Castle Defense will trigger additional actions, like -recalculating guardians' HP. - ---------------------------------------- - -*getgdskilllv(<guild id>, <skill id>) -*getgdskilllv(<guild id>, "<skill name>") - -This function returns the level of the skill <skill id> of the guild -<guild id>. -If the guild does not have that skill, 0 is returned. -If the guild does not exist, -1 is returned. -Refer to 'db/(pre-)re/skill_db.txt' for the full list of skills. -GD_* are guild skills - ---------------------------------------- - -*requestguildinfo(<guild id>{, "<event label>"}); - -This command requests the guild data from the char server and merrily -continues with the execution. Whenever the guild information becomes -available (which happens instantly if the guild information is already in -memory, or later, if it isn't and the map server has to wait for the char -server to reply) it will run the specified event as in a 'doevent' call. - ---------------------------------------- - -*getmapguildusers(<mapname>, <guild id>) - -Returns the amount of characters from the specified guild on the given map. - -Example: - - mes("You have "+getmapguildusers("prontera", getcharid(CHAR_ID_GUILD))+" guild members in Prontera."); - ---------------------------------------- - -*getguildmember(<guild id>{, <type>}); - -This command will find all members of a specified guild and returns their names -(or character id or account id depending on the value of "type") into an array -of temporary global variables. - -Upon executing this, - -$@guildmembername$[] is a global temporary string array which contains all the - names of these guild members. - (only set when type is 0 or not specified) - -$@guildmembercid[] is a global temporary number array which contains the - character id of these guild members. - (only set when type is 1) - -$@guildmemberaid[] is a global temporary number array which contains the - account id of these guild members. - (only set when type is 2) - -$@guildmembercount is the number of guild members that were found. - -The guild members will be found regardless of whether they are online or offline. -Note that the names come in no particular order. - -Be sure to use $@guildmembercount to go through this array, and not -getarraysize(), because it is not cleared between runs of getguildmember(). - -For usage examples, see getpartymember(). - ---------------------------------------- -//===================================== -2.2 - End of Guild-Related Commands -//===================================== ---------------------------------------- - -*getskilllv(<skill id>) -*getskilllv("<skill name>") - -This function returns the level of the specified skill that the invoking -character has. If they don't have the skill, 0 will be returned. The full -list of character skills is available in 'db/(pre-)re/skill_db.txt'. - -There are two main uses for this function, it can check whether the -character has a skill or not, and it can tell you if the level is high -enough. - -Example 1: - - 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(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(); - ---------------------------------------- - -*getskilllist(); - -This command sets a bunch of arrays with a complete list of skills the -invoking character has. Here's what you get: - -@skilllist_id[] - skill ids. -@skilllist_lv[] - skill levels. -@skilllist_flag[] - see 'skill' for the meaning of skill flags. -@skilllist_count - number of skills in the above arrays. - -While getskilllv() is probably more useful for most situations, this is the -easiest way to store all the skills and make the character something else -for a while. Advanced job for a day? :) This could also be useful to see -how many skills a character has. - ---------------------------------------- - -*getpetinfo(<type>) - -This function will return pet information for the pet the invoking -character currently has active. Valid types are: - - 0 - Unique pet ID number as stored by the char server and distinguishing - it from all other pets the characters actually have. This value is - currently useless, at most you can use it to tell pets apart reliably. - 1 - Pet class number as per 'db/pet_db.txt' - will tell you what kind of - a pet it is. - 2 - Pet name. Will return "null" if there's no pet. - 3 - Pet friendly level (intimacy score). 1000 is full loyalty. - 4 - Pet hungry level. 100 is completely full. - 5 - Pet rename flag. 0 means this pet has not been named yet. - -If the invoking player doesn't own a pet, this command will return -"null" for type 2, and return 0 for other types. - ---------------------------------------- - -*petstat(<flag>) - -Returns current pet status, all are integers except name. -Returns 0 or "" if the player doesn't have pets. - -Flags usable: -PET_CLASS -PET_NAME -PET_LEVEL -PET_HUNGRY -PET_INTIMATE - -Example: - .@i = petstat(PET_CLASS); - ---------------------------------------- - -*getmonsterinfo(<mob ID>, <type>) - -This function will look up the monster with the specified ID number in the -mob database and return the info set by TYPE argument. -It will return -1 if there is no such monster (or the type value is -invalid), or "null" if you requested the monster's name. - -Valid types are listed in constants.conf: - MOB_NAME 0 - MOB_LV 1 - MOB_MAXHP 2 - MOB_BASEEXP 3 - MOB_JOBEXP 4 - MOB_ATK1 5 - MOB_ATK2 6 - MOB_DEF 7 - MOB_MDEF 8 - MOB_STR 9 - MOB_AGI 10 - MOB_VIT 11 - MOB_INT 12 - MOB_DEX 13 - MOB_LUK 14 - MOB_RANGE 15 - MOB_RANGE2 16 - MOB_RANGE3 17 - MOB_SIZE 18 - MOB_RACE 19 - MOB_ELEMENT 20 - MOB_MODE 21 - MOB_MVPEXP 22 - -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(PORING, Poring_Doll, 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 true in case of success (the item was removed), and -false otherwise (the monster didn't have the specified item in its drop -list). - -Example: - // Remove Jellopy (909) from the Poring's (1002) drops - delmonsterdrop(PORING, Jellopy); - ---------------------------------------- - -*getmobdrops(<mob id>) - -This command will find all drops of the specified mob and return the item -IDs and drop percentages into arrays of temporary global variables. -getmobdrops() returns true if successful and false if the mob ID doesn't -exist. - -Upon executing this, - -$@MobDrop_item[] is a global temporary number array which contains the - item IDs of the monster's drops. - -$@MobDrop_rate[] is a global temporary number array which contains the - drop percentages of each item. (1 = .01%) - -$@MobDrop_count is the number of item drops found. - -Be sure to use $@MobDrop_count to go through the arrays, and not -'getarraysize', because the temporary global arrays are not cleared -between runs of 'getmobdrops'. If a mob with 7 item drops is looked up, -the arrays would have 7 elements. But if another mob is looked up and it -only has 5 item drops, the server will not clear the arrays for you, -overwriting the values instead. So in addition to returning the 5 item -drops, the 6th and 7th elements from the last call remain, and you will -get 5+2 item drops, of which the last 2 don't belong to the new mob. -$@MobDrop_count will always contain the correct number (5), unlike -getarraysize() which would return 7 in this case. - -Example: - - // get a Mob ID from the user - input(.@mob_id); - - if (getmobdrops(.@mob_id)) { // getmobdrops() returns true 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. - .@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 (.@i = 0; .@i < .@count; ++.@i) { - mes(.@item[.@i] + " (" + getitemname(.@item[.@i]) + ") " + .@rate[.@i]/100 + ((.@rate[.@i]%100 < 10) ? ".0":".") + .@rate[.@i]%100 + "%"); - } - } else { - mes("Unknown monster ID."); - } - close(); - ---------------------------------------- - -*skillpointcount() - -Returns the total amount of skill points a character possesses -(SkillPoint + skill points used in skills) This command can be used to -check the currently attached characters total amount of skill points. -This means the skill points used in skill are counted, and added to -SkillPoints (number of skill points not used). - -Example: - -//This will set the temp character variable @skill_points to the amount of -//skill points, and then tell the player the value. - @skill_points = skillpointcount(); - mes("You have "+@skill_points+" skill points in total!"); - -//Self-explanatory... :P - 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 -granted) (e.g. ALL_BUYING_STORE/ALL_INCCARRY). ---------------------------------------- - -*getscrate(<effect type>, <base rate>{, <GID>}) - -This function will return the chance of a status effect affecting the -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)) { - // do something - } - -You can see the full list of available effect types you can possibly -inflict in 'db/constants.conf' under 'Eff_'. - ---------------------------------------- -//===================================== -3 - Checking-Related Commands -//===================================== ---------------------------------------- - -*playerattached() - -Returns the ID of the player currently attached to the script. It will -return 0 if no one is attached, or if the attached player no longer exists -on the map server. It is wise to check for the attached player in script -functions that deal with timers as there's no guarantee the player will -still be logged on when the timer triggers. Note that the ID of a player -is actually their account ID. - ---------------------------------------- - -*isloggedin(<account id>{, <char id>}) - -This function returns true if the specified account is logged in and -false if they aren't. You can also pass the char_id to check for both -account and char id. - ---------------------------------------- - -*checkweight(<item id>, <amount>{, <item id>, <amount>, <item id>, <amount>, ...}) -*checkweight("<item name>", <amount>{, "<item name>", <amount>, "<item name>", <amount>, ...}) -*checkweight2(<id_array>, <amount_array>) - -These functions will compute and return true if the total weight of the -specified number of specific items does not exceed the invoking -character's carrying capacity, and false otherwise. It is important to -see if a player can carry the items you expect to give them, failing to -do that may open your script up to abuse or create some very unfair -errors. - -The second function will check an array of items and amounts, and also -returns true on success and false on failure. - -The functions, in addition to checking to see if the player is capable of -holding a set amount of items, also ensure the player has room in their -inventory for the item(s) they will be receiving. - -Like getitem(), this function will also accept an 'english name' from -the database as an argument. - -Example 1: - - if (checkweight(Apple, 10)) { - getitem(Apple, 10); - } else { - mes("Sorry, you cannot hold this amount of apples!"); - } - -Example 2: - - setarray(.@item[0], 512, 513, 514); - setarray(.@amount[0], 10, 5, 5); - if (!checkweight(.@item, .@amount)) { - mes("Sorry, you cannot hold this amount of fruit!"); - } - ---------------------------------------- - -*basicskillcheck() - -This function will return the state of the configuration option -'basic_skill_check' in 'conf/map/battle.conf'. Returns true if the -option is enabled and false if it isn't. If the 'basic_skill_check' -option is enabled, which it is by default, characters must have a -certain number of basic skill levels to sit, request a trade, use -emotions, etc. Making your script behave differently depending on -whether the characters must actually have the skill to do all these -things might in some cases be required. - ---------------------------------------- - -*checkoption(<option number>{, <account id>}) -*checkoption1(<option number>{, <account id>}) -*checkoption2(<option number>{, <account id>}) -*setoption(<option number>{, <flag>{, <account id>}}); - -The setoption() series of functions check for a so-called option that is -set on the invoking character. 'Options' are used to store status -conditions and a lot of other non-permanent character data of the yes-no -kind. For most common cases, it is better to use checkcart(), -checkfalcon(), checkmount() and other similar functions, but there are -some options which you cannot get at this way. If <account id> is given, -this player will be used instead of the invoking character. - -Option numbers valid for the first (option) version of this command are: - -0x000000 Option_Nothing - No options -0x000001 Option_Sight - Sight in effect. -0x000002 Option_Hide - Hide in effect. -0x000004 Option_Cloak - Cloaking in effect. -0x000008 - Cart number 1 present. -0x000010 Option_Falcon - Falcon present. -0x000020 Option_Riding - Peco Peco present. -0x000040 Option_Invisible - 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 Option_Orcish - Orc head present. -0x001000 Option_Wedding - The character is wearing a wedding sprite. -0x002000 - Ruwach is in effect. -0x004000 Option_Chasewalk - Chasewalk in effect. -0x008000 Option_Flying - Flying or Xmas suit. -0x010000 - Sighttrasher. -0x100000 Option_Wug - Warg present. -0x200000 Option_Wugrider - The character is riding a warg. - -Option numbers valid for the second version (opt1) of this command are: - -1 - Petrified. -2 - Frozen. -3 - Stunned. -4 - Sleeping. -6 - Petrifying (the state where you can still walk) - -Option numbers valid for the third version (opt2) of this command are: - -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. - -Option numbers (except for opt1) are bit-masks - you can add them up to -check for several states, but the functions will return true if at least -one of them is in effect. - -setoption() will set options on the invoking character. There are no -second and third versions of this command, so you can only change the -values in the first list (cloak, cart, ruwach, etc). If flag is 1 (default -when omitted), the option will be added to what the character currently -has; if 0, the option is removed. - -This is definitely not a complete list of available option flag numbers. -Ask a core developer (or read the source: src/map/status.h) for the full -list. - ---------------------------------------- - -*setcart({<type>}) -*checkcart() - -If <type> is 0 this command will remove the cart from the character. -Otherwise it gives the invoking character a cart. The cart given will be -cart number <type> and will work regardless of whether the character is a -merchant class or not. -Note: the character needs to have the skill MC_PUSHCART to gain a cart. - -The accompanying function will return true if the invoking character has a -cart (any kind of cart) and false if they don't. - - if (checkcart()) - mes("But you already have a cart!"); - ---------------------------------------- - -*setfalcon({<flag>}) -*checkfalcon() - -If <flag> is 0 this command will remove the falcon from the character. -Otherwise it gives the invoking character a falcon. The falcon will be -there regardless of whether the character is a hunter or not. It will -(probably) not have any useful effects for non-hunters though. -Note: the character needs to have the skill HT_FALCON to gain a falcon. - -The accompanying function will return true if the invoking character has a -falcon and false if they don't. - - if (checkfalcon()) - mes("But you already have a falcon!"); - ---------------------------------------- - -*setmount({<flag>}) -*checkmount() - -If <flag> is MOUNT_NONE this command will remove the mount from the -character. - -Otherwise it gives the invoking character the desired combat mount, where -allowed by their class and skills. - -If no flag is specified, the mount is automatically chosen according to the -character's class and skills. - -The following flag values are accepted: - - MOUNT_NONE: - - Dismount - MOUNT_PECO: - - PecoPeco (Knight series class) - - GrandPeco (Crusader series class) - - Gryphon (Royal Guard) - MOUNT_WUG: - - Warg (Ranger) - MOUNT_MADO: - - Mado Gear (Mechanic) - MOUNT_DRAGON: - MOUNT_DRAGON_GREEN: - MOUNT_DRAGON_BROWN: - MOUNT_DRAGON_GRAY: - MOUNT_DRAGON_BLUE: - MOUNT_DRAGON_RED: - - Dragon (Rune Knight) - if MOUNT_DRAGON is specified, a the default (green) dragon will be used. - -Unlike 'setfalcon' and 'setcart' this will not work at all if they aren't of a -class which can ride a mount. - -The accompanying function will return MOUNT_NONE if the invoking -character is not on a mount, and a non-zero value (according to the -above constants) if they are. -Note: in case of dragons, the returned value will always be MOUNT_DRAGON, -regardless of color. - - if (checkmount()) - mes("Leave your mount outside! No riding mounts on the floor here!"); - - if (checkmount() == MOUNT_DRAGON) - mes("Wow, your dragon is cool! Can I pet it?"); - ---------------------------------------- - -*setcashmount() -*hascashmount() - -The 'setcashmount' function toggles cash mount for the invoking character. -It will return true if successful, false otherwise. - -Note: Character must not be mounting a non-cash mount (eg. dragon, peco, - wug, etc.) - -The accompanying function will return true if the invoking character has a -cash mount and false if they don't. - ---------------------------------------- - -*checkwug() - -This function will return true if the invoking character has a warg and false if -they don't. - ---------------------------------------- - -*checkvending({"<Player Name>"}) -*checkchatting({"<Player Name>"}) - -Checks if the player is vending or in a chatroom. -Name is optional, and defaults to the attached player if omitted. - -Return values for 'checkvending' are - 0 = not vending - 1 = normal vending - 2 = vending using @autotrade - -checkchatting() returns true if they are in a chat room, false if they are not. - -Examples: - //This will check if Aaron is vending, and if so, put a message in - //front of the attached player saying Aaron is vending. - if (checkvending("Aaron")) - mes("Aaron is currently vending!"); - - //This will check if the attached player in a chat room or not. - if (checkchatting()) - mes("You are currently in a chat room!"); - ---------------------------------------- - -*checkidle({"<Player Name>"}) - -Returns the time, in seconds, that the specified player has been idle. -Name is optional, and defaults to the attached player if omitted. - ---------------------------------------- - -*agitcheck() -*agitcheck2() - -These function will let you check whether the server is currently in WoE -mode (or WoE SE mode if the second function is called) and will return true -if War of Emperium is on and false if it isn't. - ---------------------------------------- - -*isnight() - -This functions will return true or false depending on whether the server is in -night mode or day mode: - - if (!isnight()) - mes("I only prowl in the night."); - ---------------------------------------- -//===================================== -3.1 - Checking Item-Related Commands -//===================================== ---------------------------------------- - -*isequipped(<item id>{, <item id>{, <item id>{, <item id>}}}) - -This function will return true if the invoking character has all of the item -IDs given equipped (if card IDs are passed, then it checks if the cards -are inserted into slots in the equipment they are currently wearing). -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, false will be returned. - - // (Poring, Santa Poring, Poporing, Marin) - if (isequipped(Poring_Card, Poring__Card, Poporing_Card, Marin_Card)) - mes("Wow! You're wearing a full complement of possible poring cards!"); - // (Poring) - if (isequipped(Poring_Card)) - mes("A poring card is useful, don't you think?"); - // (Earring) - if (isequipped(Earring_)) - mes("You got a pair of nice Earring."); - -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. - ---------------------------------------- - -*isequippedcnt(<item id>{, <item id>{, <item id>{, <item id>}}}) - -This function is similar to isequipped(), but instead of true or false, it will -return the number of equipped items/cards in the list given that were found on the -invoking character. - - if (isequippedcnt(Poring_Card, Poring__Card, Poporing_Card, Marin_Card) == 4) - mes("Finally got all four poring cards?"); - if (isequippedcnt(Helm_Of_Sun_, Earring_) == 2) - mes("You equipped both Helm of Sun and Earring."); - ---------------------------------------- - -*checkequipedcard(<card id>) - -This function will return true if the card specified by it's item ID number -is inserted into any equipment they have in their inventory, currently -equipped or not. - ---------------------------------------- - -*getequipisidentify(<equipment slot>) - -This function will return true if an item in the specified equipment slot is -identified and false if it isn't. Since you can't even equip unidentified -equipment, there's a question of whether it can actually end up there, and -it will normally return true all the time if there is an item in this -equipment slot, which makes this script command kinda pointless. -For a list of equipment slots see getequipid(). - ---------------------------------------- -//===================================== -3.0 & 3.1 - End of Checking/Item-Related Commands -//===================================== ---------------------------------------- - ---------------------------------------- -//===================================== -4 - Player-Related Commands -//===================================== ---------------------------------------- - -*attachrid(<account ID>) -*detachrid() - -These commands allow the manipulation of the script's currently attached -player. While attachrid() allows attaching of a different player by using -its account id for the parameter rid, detachrid() makes the following -commands run as if the script was never invoked by a player. - -In case, that the player cannot be attached, such as, when the player went -offline in the mean time, attachrid() returns false, otherwise true. - ---------------------------------------- - -*rid2name(<rid>) - -Converts rid to name. Note: The player/monster/NPC must be online/enabled. -Good for PCKillEvent where you can convert 'killedrid' to the name of the -player. - -Note: rid2name() may not produce correct character names since RID means - account id. - It will return the current online character of the account only. - ---------------------------------------- - -*message(<account ID>, "<message>") -*message("<character name>", "<message>") - -That command will send a message to the chat window of the character -specified by account ID or name. The text will also appear above the head -of that character. It will not be seen by anyone else. - ---------------------------------------- - -*dispbottom("<message>"{, <color>}) - -This command will send the given message into the invoking character's -chat window. The color format is in RGB (0xRRGGBB), and default to green -if <color> field is left out. - ---------------------------------------- - -*showscript("<message>"{, <GID>}) - -Makes the attached player or GID, display a message similiar to a chat, -this will be seen by everyone near the invoking character but will not -be displayed in the chat window. - ---------------------------------------- - -*warp("<map name>", <x>, <y>{, <flag>}) - -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); - -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); - -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 -where this is actually coded, it might be that this happens because square -0,0 is unwalkable on all official maps. Beware if you're using custom maps. - -There are also three special 'map names' you can use: - -"Random" will warp the player randomly on the current map. -"Save" and "SavePoint" will warp the player back to their save point. - -If flag parameter is set to 0, after player warped will be not stopped -currend running npc script. Running script after warp can be issue for -Gravity client if warp to other maps. - ---------------------------------------- - -*areawarp("<from map name>", <x1>, <y1>, <x2>, <y2>, "<to map name>", <x3>, <y3>{, <x4>, <y4>}) - -This command is similar to 'warp', however, it will not refer to the -invoking character, but instead, all characters within a specified area, -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); - -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); - -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); - -By using the optional x4 and y4 parameters, the destination coordinates -will be a random place within the defined x3/y3-x4/y4 square. - -Like warp(), areawarp() will also explicitly warp characters randomly into -the current map if you give the 'to map name' as "Random". - -See also warp(). - ---------------------------------------- - -*warpparty("<to_mapname>", <x>, <y>, <party_id>, "<from_mapname>", <include_leader>) - -Warps a party to specified map and coordinate given the party ID, which -you can get with getcharid(CHAR_ID_PARTY). You can also request another party id given -a member's name with getcharid(CHAR_ID_PARTY, <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. - -If you specify a from_mapname, warpparty() will only affect those on -that map. - -You can exclude Party leader from warping, by keeping include_leader option as false. - -Example: - - mes("[Party Warper]"); - mes("Here you go!"); - close2(); - .@id = getcharid(CHAR_ID_PARTY); - warpparty("prontera", 150, 100, .@id, true); - 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(CHAR_ID_CHAR, <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>, {"<from_mapname>"}) - -Warps a guild to specified map and coordinate given the guild id, which -you can get with getcharid(CHAR_ID_GUILD). You can also request another guild id given -the member's name with getcharid(CHAR_ID_GUILD, <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). - -If you specify a from_mapname, warpguild() will only affect those on that map. - -Example: - - warpguild("prontera", x, y, Guild_ID); - warpguild("prontera", x, y, Guild_ID, "payon"); // warp member from Payon map only. - ---------------------------------------- - -*warppartner("<map name>", <x>, <y>) - -This function will find the invoking character's marriage partner, if any, -and warp them to the map and coordinates given. Go kidnap that spouse. :) -It will return true upon success and false if the partner is not online, -the character is not married, or if there's no invoking character (no -RID). -0,0 will, as usual, normally translate to random coordinates. - ---------------------------------------- - -*savepoint("<map name>", <x>, <y>) - -This command saves where the invoking character will return to upon -'return to save point', if dead or in some other cases. The two versions -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); - ---------------------------------------- - -*heal(<hp>, <sp>) - -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 - -This command just alters the hit points and spell points of the invoking -character and produces no other output whatsoever. - ---------------------------------------- - -*itemheal(<hp>, <sp>) - -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, -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. - - // 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); - ---------------------------------------- - -*percentheal(<hp>, <sp>) - -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 - -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 -effects. - ---------------------------------------- - -*recovery() -*recovery(<account id>) -*recovery("<map name>"{, <x1>, <y1>, <x2>, <y2>}) - -In its first form, this command will revive and restore full HP and SP to all -characters currently connected to the server. In its second form, it will only -affect the target player. In its third form it will affect a whole map or area. - ---------------------------------------- - -*jobchange(<job number>{, <upper flag>}) - -This command will change the job class of the invoking character. - - jobchange(Job_Swordman); // This would change your player into a Swordman - jobchange(Job_Swordman_High); // 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/constants.conf'. - -'upper flag' can alternatively be used to specify the type of job one -changes to. For example, jobchange(Job_Swordman, 1); will change the -character to a high swordsman. The upper values are: --1 (or when omitted): preserves the current job type. -0: Normal/standard classes -1: High/Advanced classes -2: Baby classes - -This command will also set a permanent character-based variable -'jobchange_level' which will contain the job level at the time right -before changing jobs, which can be checked for later in scripts. - ---------------------------------------- - -*jobname(<job number>) - -This command retrieves the name of the given job using the names defined -in messages.conf. - - mes("[Kid]"); - mes("I never thought I'd met a "+jobname(Class)+" here of all places."); - close(); - ---------------------------------------- - -*eaclass({<job number>}) - -This commands returns the "eA job-number" corresponding to the given -class, and uses the invoking player's class if none is given. The eA -job-number is also a class number system, but it's one that comes with -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. - - .@eac = eaclass(); - if ((.@eac&EAJ_BASEMASK) == EAJ_SWORDMAN) - mes("Your base job is Swordman."); - if (.@eac&EAJL_UPPER) - mes("You are a rebirth job."); - 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 -file. - ---------------------------------------- -*roclass(<job number> {, <gender>}) - -Does the opposite of eaclass(). That is, given an eA job-number, it returns -the corresponding RO class number. A gender is required because both Bard -and Dancers share the same eA job-number (EAJ_BARDDANCER), and uses the -invoking player's gender if none is given (if no player is attached, -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). - - .@eac = eaclass(); - //Check if class is already rebirth - if (.@eac&EAJL_UPPER) { - mes("You look strong."); - close(); - } - .@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)+"!"); - close(); - } - ---------------------------------------- - -*changebase(<job ID number>) - -This command will change the appearance of the invoking character to that -of a specified job class. Nothing but appearance will change. - -Examples: - - /* 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. - -changebase(Class); // Changes player back to default sprite. - ---------------------------------------- - -*classchange(<view id>, <type> {, <char id>}) - -This command is very ancient, it's origins are clouded in mystery. -It will send a 'display id change' packet to player with given char ID -or to everyone in the immediate area of the NPC object if char ID is 0 or -not passed, which will make the NPC look like a different sprite, an NPC -sprite ID, or a monster ID. This effect is not stored anywhere and will -not persist. -Note that you can't send a Job sprite ID - -type is not used and should always be 0. - ---------------------------------------- - -*changesex() - -This command will change the gender for the attached character's account. -If it was male, it will become female, if it was female, it will become -male. The change will be written to the character server, the player will -receive the message: "Need disconnection to perform change-sex request..." -and the player will be immediately kicked to the login screen. When they -log back in, they will be the opposite sex. - -If there are any Dancer/Gypsy or Bard/Clown characters on the account, -they will also have their skills reset upon 'changesex'. - ---------------------------------------- - -*changecharsex() - -This command is exactly same as changesex(), with an exception that, -character sex will be changed instead of account sex. -Requires client 2014-10-22 or greater. - ---------------------------------------- - -*getexp(<base xp>, <job xp>) - -This command will give the invoking character a specified number of base -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); - -You can also assign directly to the parameters defined in -'db/constants.conf': - - BaseExp += 10000; - JobExp += 5000; - -You can also reduce the amount of experience points: - - BaseExp -= 10000; - -When setting the parameters directly no bonuses or config options are applied. - ---------------------------------------- - -*setlook(<look type>, <look value>) -*changelook(<look type>, <look value>) - -'setlook' will alter the look data for the invoking character. It is used -mainly for changing the palette used on hair and clothes: you specify -which look type you want to change, then the palette you want to use. Make -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. - - setlook(LOOK_HAIR_COLOR, 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(LOOK_CLOTHES_COLOR, 1); - -Here are the possible look types: - - 0 - LOOK_BASE Base sprite - 1 - LOOK_HAIR Hairstyle - 2 - LOOK_WEAPON Weapon - 3 - LOOK_HEAD_BOTTOM Head bottom - 4 - LOOK_HEAD_TOP Head top - 5 - LOOK_HEAD_MID Head mid - 6 - LOOK_HAIR_COLOR Hair color - 7 - LOOK_CLOTHES_COLOR Clothes color - 8 - LOOK_SHIELD Shield - 9 - LOOK_SHOES Shoes - 10 - LOOK_BODY Body(N/A) - 11 - LOOK_FLOOR FLOOR(N/A) - 12 - LOOK_ROBE Robe - 13 - LOOK_BODY2 Body style - -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 -is kept, but normally doesn't do a thing. - -Only the look data for hairstyle, hair color and clothes color are saved -to the char server's database and will persist. The rest freely change as -the character puts on and removes equipment, changes maps, logs in and out -and otherwise you should not expect to set them. In fact, messing with -them is generally hazardous, do it at your own risk, it is not tested -what will this actually do - it won't cause database corruption and -probably won't cause a server crash, but it's easy to crash the client -with just about anything unusual. - -However, it might be an easy way to quickly check for empty view IDs for -sprites, which is essential for making custom headgear. - -Since a lot of people have different palettes for hair and clothes, it's -impossible to tell you what all the color numbers are. If you want a -serious example, there is a Stylist script inside the default Hercules -installation that you can look at: 'npc/custom/stylist.txt' - ---------------------------------------- - -*pushpc(<direction>, <cells>) - -This command will push the currently attached player to given direction by -given amount of square cells. Direction is the same as used when declaring -NPCs, and can be specified by using one of the DIR_* constants -(db/constants.conf). - -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); - ---------------------------------------- - -*montransform(<monster id>, <duration>{, <sc_type>{, <val1>{, <val2>{, <val3>{, <val4>}}}}}) -*montransform("<monster name>", <duration>{, <sc_type>{, <val1>{, <val2>{, <val3>{, <val4>}}}}}) - -This command can transform your character into monster and you can still -use all your skills like a normal character. -Can only be removed when your killed or if you die or if duration is over. - -for sc_type, val1, val2, val3, val4, see sc_start(), sc_start2(), sc_start4() commands. - ---------------------------------------- -//===================================== -4.1 - Player Item-Related Commands -//===================================== ---------------------------------------- - -*getitem(<item id>, <amount>{, <account ID>}) -*getitem("<item name>", <amount>{, <account ID>}) - -This command will give a specific amount of specified items to the target -character. If the character is not online, nothing will happen. -If <account ID> is not specified, items will be created in the invoking -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(Apple, 10); // The person will receive 10 apples - getitem(Old_Violet_Box, 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 -cases, these will be unidentified, if they turn out to be equipment. This -is exactly what's written in the Old Blue Box's item script. - -Other negative IDs also correspond to other random item generating item -tables: - -Giving an item ID of -2 will produce the effects of Old Violet Box. -Giving an item ID of -3 will produce the effects of Old Card Album. -Giving an item ID of -4 will produce the effects of Gift Box. -Giving an item ID of -5 will produce the effects of Worn Out Scroll, -which, in current Git, drops only Jellopies anyway. - -This transaction is logged if the log script generated transactions option -is enabled. - -You may also create an item by it's name in the 'english name' field in -the item database: - - getitem("Red_Potion", 10); // Not recommended, use Red_Potion instead of "Red_Potion" - -Which will do what you'd expect. If it can't find that name in the -database, apples will be created anyway. - -This is used in pretty much all NPC scripts that have to do with items and -quite a few item scripts. For more examples check just about any official -script. - ---------------------------------------- - -*getitem2(<item id>, <amount>, <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>{, <account ID>}) -*getitem2("<item name>", <amount>, <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>{, <account ID>}) - -This command will give an amount of specified items to the invoking -character. If an optional account ID is specified, and the target -character is currently online, items will be created in their inventory -instead. If they are not online, nothing will happen. It works essentially -the same as 'getitem' (it even works for negative ID numbers the same way) -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. - -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 -create a named item in this manner, however, if you just need a named -piece of standard equipment, it is much easier to the 'getnameditem' -function instead. - -You will need to keep these values if you want to destroy and then -perfectly recreate a named item, for this see getinventorylist(). - -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. - - .@charid = getcharid(CHAR_ID_CHAR, "Adam"); - - // 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(Apple, 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. - - // If you're inscribing equipment, .@card1 must be 255. - .@card1 = 255; - - // That's the number of star crumbs in a weapon. - .@sc = 2; - - // 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(Stiletto, 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()+" bound items."); - next(); - mes("The list of bounded items include:"); - for (.@i = 0; .@i < getarraysize(@bound_items); ++.@i) - mes(getitemname(@bound_items[.@i])); - close(); - ---------------------------------------- - -*checkbound(<item_id>{, <bound_type>{, <refine>{, <attribute>{, <card_1>{, <card_2>{, <card_3>{, <card_4>}}}}}}}) - -This command allows you to check whether or not the attached player has the specified bound item in their inventory. -If a bound type is not specified or a bound type of 0 is used, it will search the player's inventory for a bound item -of any type, so long as the other parameters match. In all cases, this command will return the bound type of the -item found, or 0 if the specified item was not found. - -Valid bound types are: - 0 - All Bound types. - 1 - Account Bound - 2 - Guild Bound - 3 - Party Bound - 4 - Character Bound - -Optional Parameters: - bound_type - checks to see if the item has the specified bound type. - refine - checks to see if the item is refined to the given number. - attribute - whether the item is broken (1) or not (0). - card 1,2,3,4 - checks to see if the specified cards are compounded on the item as well. - -Example: - // This will check if you have a bound (any type) 1205 (Cutter). - if (checkbound(Cutter)) { - mes("You have a bound Cutter"); - } else { - mes("You do not have a bound Cutter"); - } - close(); - - // This will also check if you have a bound (any type) 1205 (Cutter). - if (checkbound(Cutter, 0)) { - mes("You have a bound Cutter"); - } else { - mes("You do not have a bound Cutter"); - } - close(); - - // This will check if the player doesn't have a bound 1205 (Cutter). - if (!checkbound(Cutter)) { - mes("You do not have a bound Cutter"); - } else { - mes("You do have a bound Cutter"); - } - close(); - - // This will check if the item found, has a bound type of 2 (guild_bound) - if (checkbound(Cutter) == 2) { - mes("You have a guild_bound Cutter"); - } else { - mes("You do not have a guild_bound Cutter."); - } - close(); - - // This will check if you have a 'guild_bound' +7 1205 (Cutter). - if (checkbound(Cutter, 2, 7)) { - mes("You have a +7 guild_bound Cutter."); - } else { - mes("You don't have the required item."); - } - close(); ---------------------------------------- - -*getnameditem(<item id>, <character name|character ID>) -*getnameditem("<item name>", <character name|character ID>) - -Create an item signed with the given character's name. - -The command returns true when the item is created successfully, or false -if it fails. Failure occurs when: -- There is no player attached. -- Item name or ID is not valid. -- The given character ID/name is offline. - -Example: - -//This will give the currently attached player a Aaron's Apple (if Aaron -//is online). - getnameditem(Apple, "Aaron"); - -//Self-explanatory (I hope). - if (getnameditem(Apple, "Aaron")) { - mes("You now have a Aaron's Apple!"); - } - ---------------------------------------- - -*rentitem(<item id>, <time>) -*rentitem("<item name>", <time>) - -Creates a rental item in the attached character's inventory. The item will -expire in <time> seconds and be automatically deleted. When receiving a -rental item, the character will receive a message in their chat window. -The character will also receive warning messages in their chat window -before the item disappears. - -This command can not be used to rent stackable items. Rental items cannot -be dropped, traded, sold to NPCs, or placed in guild storage (i.e. trade -mask 75). -Note: delitem() in an NPC script can still remove rental items. - ---------------------------------------- - -*makeitem(<item id>, <amount>, "<map name>", <X>, <Y>) -*makeitem("<item name>", <amount>, "<map name>", <X>, <Y>) - -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. - -This item will still disappear just like any other dropped item. Like -getitem(), it also accepts an 'english name' field from the database and -creates apples if the name isn't found. -If the map name is given as "this", the map the invoking character is on -will be used. - ---------------------------------------- - -*makeitem2(<item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,{"<map name>",<X>,<Y>,<range>}) -*makeitem2("<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,{"<map name>",<X>,<Y>,<range>}) - -This script command work like 'makeitem', but it has additional parameters -to expand the usage of the scritp command. - -Parameter List: - itemid - ID / Name of an item - amount - Amount you want produced (Value: 1~MAX_AMOUNT) - - if item type is Armor/Wepaon/PetEgg/PetArmor, amount will be limit to 1 - identify - Item to be identified (1) or not (0) - refine - Refine count of item. (Value: 0 ~ MAX_REFINE) - attribute - Item is broken (1) or not (0) - card1,2,3,4 - Card IDs that compound on each slot - -Optional Parameter List: - map name - Map name (Default to attached player map) - X,Y - The coordinate of item will be dropped - If value = 0, it's drop random across the map - If value = -1, its drop around player - range - Range of item drop around player. (Value: 1 ~ battle_config.area_size, Default: 3) - Default value will be used if no player are attached to the script. - ---------------------------------------- - -*cleanarea("<map name>",<x1>,<y1>,<x2>,<y2>) -*cleanmap("<map name>") - -These commands will clear all items lying on the ground on the specified -map, either within the x1/y1-x2/y2 rectangle or across the entire map. - ---------------------------------------- - -*searchitem(<array name>, "<item name>") - -This command will fill the given array with the ID of items whose name -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$); - .@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])+"]"); - ---------------------------------------- - -*delitem(<item id>, <amount>{, <account ID>}) -*delitem("<item name>", <amount>{, <account ID>}) - -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(Apple, 10); // The person will lose 10 apples - delitem(Old_Violet_Box, 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 -has, the player will lose the ones he/she has and the script will be -terminated with an error. - -Like getitem() this command will also accept an 'english name' field from -the database. If the name is not found, nothing will be deleted. - ---------------------------------------- - -*delitem2(<item id>, <amount>, <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>{, <account ID>}) -*delitem2("<item name>", <amount>, <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>{, <account ID>}) - -This command will remove a specified amount of items from the invoking or -target character. -Check getitem2() to understand its expanded parameters. - ---------------------------------------- - -*countitem(<item id>) -*countitem("<item name>") - -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(Apple)+" apples"); - close; - -Like getitem(), this function will also accept an 'english name' from the -database as an argument. - ---------------------------------------- - -*countitem2(<item id>, <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>) -*countitem2("<item name>", <identify>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>) - -Expanded version of countitem() function, used for created/carded/forged -items. - -This function will return the number of items for the specified item ID -and other parameters that the invoking character has in the inventory. -Check getitem2() to understand the arguments of the function. - ---------------------------------------- - -*groupranditem(<item_id/constant>) - -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'. - -Example: - getitem(groupranditem(Old_Blue_Box), 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); - ---------------------------------------- - -*packageitem({item_id}) - -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. - -Example: - -/* This example is an item script from the item db */ - { - Id: 12477 - AegisName: "Gift_Bundle" - Name: "Gift Bundle" - Type: 2 - Buy: 0 - Script: <" packageitem(); "> - }, - ---------------------------------------- - -*enable_items() -*disable_items() - -These commands enable/disable changing of equipments while an NPC is -running. When disable_items() is run, equipments cannot be changed -during scripts until enable_items() is called or the script has -terminated. To avoid possible exploits, when disable_items() is invoked, -it will only disable changing equips while running that script in -particular. Note that if a different script also calls disable_items(), -it will override the last call (so you may want to call this command at -the start of your script without assuming the effect is still in -effect). -If 'item_enabled_npc' option is set to true in 'conf/map/battle/items.conf' all -NPC are allowing changing of equipment by default except for those have been -set with 'disable_items'. - ---------------------------------------- - -*itemskill(<skill id>, <skill level>, {flag}) -*itemskill("<skill name>", <skill level>, {flag}) - -This command meant for item scripts to replicate single-use skills in -usable items. It will not work properly if there is a visible dialog -window or menu. -If the skill is self or auto-targeting, it will be used immediately. -Otherwise, a target cursor is shown. -Flag is a optional param and, when present, the command will not check for -skill requirements. - -// When Anodyne is used, it will cast Endure, Level 1, as if the actual skill -// has been used from skill tree. - itemskill(SM_ENDURE, 1); - ---------------------------------------- - -*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 -the item will not be deleted. While this command is intended for usable -items, it will run for any item type. - ---------------------------------------- - -*produce(<item level>) - -This command will open a crafting window on the client connected to the -invoking character. The 'item level' is a number which determines what -kind of a crafting window will pop-up. - -You can see the full list of such item levels in 'db/produce_db.txt' which -determines what can actually be produced. The window will not be empty -only if the invoking character can actually produce the items of that type -and has the appropriate raw materials in their inventory. - -The success rate to produce the item is the same as the success rate of -the skill associated with the item level. If there is no skill id, the -success rate will be 50%. - -Valid item levels are: - - 1 - Level 1 Weapons - 2 - Level 2 Weapons - 3 - Level 3 Weapons - 21 - Blacksmith's Stones and Metals - 22 - Alchemist's Potions, Holy Water, Assassin Cross's Deadly Poison - 23 - Elemental Converters - ---------------------------------------- - -*cooking(<dish level>) - -This command will open a produce window on the client connected to the -invoking character. The 'dish level' is the number which determines what -kind of dish level you can produce. You can see the full list of dishes -that can be produced in 'db/produce_db.txt'. - -The window will be shown empty if the invoking character does not have -enough of the required incredients to cook a dish. - -Valid dish levels are: - -11 - Level 1 Dish -12 - Level 2 Dish -13 - Level 3 Dish -14 - Level 4 Dish -15 - Level 5 Dish -16 - Level 6 Dish -17 - Level 7 Dish -18 - Level 8 Dish -19 - Level 9 Dish -20 - Level 10 Dish - -Although it's required to set a dish level, it doesn't matter if you set -it to 1 and you want to cook a level 10 dish, as long as you got the -required ingredients to cook the dish the command works. - ---------------------------------------- - -*makerune(<% success bonus>) - -This command will open a rune crafting window on the client connected to -the invoking character. Since this command is officially used in rune -ores, a bonus success rate must be specified (which adds to the base -formula). - -You can see the full list of runes that can be produced in -'db/produce_db.txt'. The window will not be empty only if the invoking -character can actually produce a rune and has the appropriate raw -materials in their inventory. - ---------------------------------------- - -*successremovecards(<equipment slot>) - -This command will remove all cards from the item found in the specified -equipment slot of the invoking character, create new card items and give -them to the character. If any cards were removed in this manner, it will -also show a success effect. - ---------------------------------------- - -*failedremovecards(<equipment slot>, <type>) - -This command will remove all cards from the item found in the specified -equipment slot of the invoking character. 'type' determines what happens -to the item and the cards: - - 0 - will destroy both the item and the cards. - 1 - will keep the item, but destroy the cards. - 2 - will keep the cards, but destroy the item. - -Whatever the type is, it will also show a failure effect on screen. - ---------------------------------------- - -*repair(<broken item number>) - -This command repairs a broken piece of equipment, using the same list of -broken items as available through 'getbrokenid'. - -The official scripts seem to use the repair command as a function instead: -'repair(<number>)' but it returns nothing on the stack. Probably only -Valaris, who made it, can answer why is it so. - ---------------------------------------- - -*repairall() - -This command repairs all broken equipment in the attached player's -inventory. A repair effect will be shown if any items are repaired, else -the command will end silently. - ---------------------------------------- - -*successrefitem(<equipment slot>{, <upgrade_count>}) - -This command will refine an item in the specified equipment slot of the -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. - ---------------------------------------- - -*failedrefitem(<equipment slot>) - -This command will fail to refine an item in the specified equipment slot -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. - ---------------------------------------- - -*downrefitem(<equipment slot>{, <downgrade_count>}) - -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. - ---------------------------------------- - -*unequip(<equipment slot>) - -This command will unequip whatever is currently equipped in the invoking -character's specified equipment slot. For a full list of possible -equipment slots see 'getequipid'. - -If an item occupies several equipment slots, it will get unequipped from -all of them. - ---------------------------------------- - -*clearitem() - -This command will destroy all items the invoking character has in their -inventory (including equipped items). It will not affect anything else, -like storage or cart. - ---------------------------------------- - -*equip(<item id>) -*equip2(<item id>, <refine>, <attribute>, <card1>, <card2>, <card3>, <card4>) -*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 -item in his/her inventory, while the autoequip function will equip the -given item ID when this is looted. The option parameter of the autoequip -is 1 or 0, 1 to turn it on, and 0 to turn it off. - -Examples: - -//This will equip a 1104 (falchion) on the character if this is in the -//inventory. - equip(Falchion); - -//This will equip a +10 1104 (falchion) on the character if this is in the -//inventory. - equip2(Falchion, 10, 0, 0, 0, 0, 0); - -//The invoked character will now automatically equip a falchion when it's -//looted. - autoequip(Falchion, 1); - -//The invoked character will no longer automatically equip a falchion. - autoequip(Falchion, 0); - ---------------------------------------- - -*buyingstore(<slots>) - -Invokes buying store preparation window like the skill 'Open Buying -Store', without the item requirement. Amount of slots is limited by the -server to a maximum of 5 slots by default. - -Example: - - // Gives the player opportunity to buy 4 different kinds of items. - buyingstore(4); - ---------------------------------------- - -*searchstores(<uses>, <effect>); - -Invokes the store search window, which allows to search for both vending -and buying stores. Parameter uses indicates, how many searches can be -started, before the window has to be reopened. Effect value affects what -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. - 1 = Directly opens the shop, regardless of distance. - -Example: - - // Item Universal_Catalog_Gold (10 uses, effect: open shop) - searchstores(10, 1); - ---------------------------------------- - -*mergeitem(); - -mergeitem() opens the item merge window, -The Item merge window shows all stackable item(same ItemID) with different -serial, that can be merged into one stack. -Check sample: npc/other/item_merge.txt - ---------------------------------------- - -*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(). - -It is always a good idea to check if the player actually has the item you want -before you use this command. If you try to delete in a position that the player -has no gear, script will be terminated with an error. - ---------------------------------------- -//===================================== -4.1 - End of Player Item-Related Commands -//===================================== ---------------------------------------- - -*openstorage() - -This will open character's Kafra storage window on the client connected to -the invoking character. It can be used from any kind of NPC or item -script, not just limited to Kafra Staff. - -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; - ---------------------------------------- - -*openmail() - -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; - ---------------------------------------- - -*openauction() - -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; - ---------------------------------------- -//===================================== -4.2 - Guild-Related Commands -//===================================== ---------------------------------------- - -*guildopenstorage() - -This function works the same as openstorage() but will open a guild -storage window instead for the guild storage of the guild the invoking -character belongs to. This is a function because it returns a value - 0 if -the guild storage was opened successfully and 1 if it wasn't. (Notice, -it's a ZERO upon success.) -Since guild storage is only accessible to one character at one time, it -may fail if another character is accessing the guild storage at the same -time. - -This will also fail and return 2 if the attached character does not belong -to any guild. - ---------------------------------------- - -*guildchangegm(<guild id>, <new master's name>) - -This function will change the Guild Master of a guild. The ID is the -guild's id, and the new guild master's name must be passed. - -Returns true on success, false otherwise. - ---------------------------------------- - -*guildgetexp(<amount>) - -This will give the specified amount of guild experience points to the -guild the invoking character belongs to. It will silently fail if they do -not belong to any guild. - ---------------------------------------- - -*guildskill(<skill id>, <level>) -*guildskill("<skill name>", <level>) - -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. 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(GD_APPROVAL, 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 -the Glory of the Guild skill, which allows your guild to use an emblem, is -a good idea for a fun quest. (Wasting a level point on that is really -annoying :D) - ---------------------------------------- -//===================================== -4.2 - End of Guild-Related Commands -//===================================== ---------------------------------------- - -*resetlvl(<action type>) - -This is a character reset command, meant mostly for rebirth script -supporting Advanced jobs, which will reset the invoking character's stats -and level depending on the action type given. Valid action types are: - - 1 - Base level 1, Job level 1, 0 skill points, 0 base exp, 0 job exp, - wipes the status effects (only the ones settable by 'setoption'), - sets all stats to 1. If the new job is 'Novice High', give 100 status - points, give First Aid and Play Dead skills. - 2 - Base level 1, Job level 1, 0 skill points, 0 base exp, 0 job exp. - Skills and attribute values are not altered. - 3 - Base level 1, base exp 0. Nothing else is changed. - 4 - Job level 1, job exp 0. Nothing else is changed. - -In all cases everything the character has on will be unequipped. - ---------------------------------------- - -*resetstatus() - -This is a character reset command, which will reset the stats on the -invoking character and give back all the stat points used to raise them -previously. Nothing will happen to any other numbers about the character. - -Used in reset NPC's (duh!). - ---------------------------------------- - -*resetskill() - -This command takes off all the skill points on the invoking character, so -they only have Basic Skill blanked out (lvl 0) left, and returns the -points for them to spend again. Nothing else will change but the skills. -Quest skills will also reset if 'quest_skill_reset' option is set to true in -'conf/map/battle.conf'. If the 'quest_skill_learn' option is set in there, the -points in the quest skills will also count towards the total. - -Used in reset NPC's (duh!). - ---------------------------------------- - -*sc_start(<effect type>, <ticks>, <value 1>{, <rate>, <flag>{, <GID>}}) -*sc_start2(<effect type>, <ticks>, <value 1>, <value 2>{, <rate>, <flag>{, <GID>}}) -*sc_start4(<effect type>, <ticks>, <value 1>, <value 2>, <value 3>, <value 4>{, <rate>, <flag>{, <GID>}}) -*sc_end(<effect type>{, <GID>}) - -These commands will bestow a status effect on a character. - -The <effect type> determines which status is invoked. This can be either a number -or constant, with the common statuses (mostly negative) found in -'db/constants.conf' with the 'SC_' prefix. A full list is located in -'src/map/status.h', though they are not currently documented. - -The duration of the status is given in <ticks>, or milleseconds. - -Certain status changes take an additional parameter <value 1>, which typically -modifies player stats by the given number or percentage. This differs for each -status, and is sometimes zero. - -Optional value <rate> is the chance that the status will be invoked (10000 = 1%). -This is used primarily in item scripts. When used in an NPC script, a flag MUST -be defined for the rate to work. - -Optional value <flag> is how the status change start will be handled (a bitmask). - SCFLAG_NONE = 0x00: No special behavior. - SCFLAG_NOAVOID = 0x01: Status change cannot be avoided. - SCFLAG_FIXEDTICK = 0x02: Tick cannot be reduced by stats (default). - SCFLAG_LOADED = 0x04: sc_data was loaded, no value will be altered. - SCFLAG_FIXEDRATE = 0x08: Rate cannot be reduced. - SCFLAG_NOICON = 0x10: Status icon (SI) won't be shown. - -If a <GID> is given, the status change will be invoked on the specified character -instead of the one attached to the script. This can only be defined after setting -a rate and flag. - -sc_start2() and sc_start4() allow extra parameters to be passed, and are used only -for effects that require them. The meaning of the extra values vary depending on the -effect type. - -sc_end() will remove a specified status effect. If SC_ALL (-1) is given, it will -perform a complete removal of all statuses (although permanent ones will re-apply). - -Examples: - // This will poison the invoking character for 10 minutes at 50% chance. - sc_start(SC_POISON, 600000, 0, 5000); - - // This will bestow the effect of Level 10 Blessing. - sc_start(SC_BLESSING, 240000, 10); - - // This will end the Freezing status for the invoking character. - sc_end(SC_FREEZE); - -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' - ---------------------------------------- - -*getstatus(<effect type>{, <type>}) - -Retrieve information about a specific status effect when called. Depending -on <type> specified the function will return different information. - -Possible <type> values: - - 0 or undefined: whether the status is active - - 1: the val1 of the status - - 2: the val2 of the status - - 3: the val3 of the status - - 4: the val4 of the status - - 5: the amount of time in milliseconds that the status has remaining - -If <type> is not defined or is set to 0, then the script function will -either return 1 if the status is active, or 0 if the status is not active. -If the status is not active when any of the <type> fields are provided, -this script function will always return 0. - ---------------------------------------- - -*skilleffect(<skill id>, <number>) -*skilleffect("<skill name>", <number>) - -This command displays visual and aural effects of given skill on currently -attached character. The number parameter is for skill whose visual effect -involves displaying of a number (healing or damaging). Note that this -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(AL_HEAL, 2000); - // Blessing Level 10 - sc_start(SC_BLESSING, 240000, 10); - skilleffect(AL_BLESSING, 0); - // Increase AGI Level 5 - sc_start(SC_INC_AGI, 140000, 5); - skilleffect(AL_INCAGI, 0); - -This will heal the character with 2000 HP, buff it with Blessing Lv 10 and -Increase AGI Lv 5, and display appropriate effects. - ---------------------------------------- - -*npcskilleffect(<skill id>, <number>, <x>, <y>) -*npcskilleffect("<skill name>", <number>, <x>, <y>) - -This command behaves identically to skilleffect(), however, the effect -will not be centered on the invoking character's sprite, nor on the NPC -sprite, if any, but will be centered at map coordinates given on the same -map as the invoking character. - ---------------------------------------- - -*specialeffect(<effect number>{, <send_target>{, <unit id>{, <account id>}}}) -*specialeffect(<effect number>{, <send_target>{, "<NPC Name>"{, <account id>}}}) - -This command will display special effect with the given number, centered -on the specified NPCs coordinates, if any. For a full list of special -effect numbers known see 'doc/effect_list.txt'. Some effect numbers are -known not to work in some client releases. (Notably, rain is absent from -any client executables released after April 2005.) - -<NPC name> parameter will display <effect number> on another NPC. If the -NPC specified does not exist, the command will do nothing. When specifying -an NPC, <send_target> must be specified when specifying an <NPC Name>, -specifying AREA will retain the default behavior of the command. - -<unit id> behaves like <NPC Name> except it can display the effect on -any kind of unit, not just NPC, by specifying its GID. - -When <send_target> is SELF you can specify which player to send the effect -to by passing <account id>. - -Example usage: - - // To make a NPC do an effect and show it to everyone: - specialeffect(EF_HIT1, AREA, "John Doe#1"); - - // To make a player do an effect and show it to everyone: - specialeffect(EF_HIT1, AREA, getcharid(CHAR_ID_ACCOUNT, "player")); - - // To make a NPC do an effect and show it only to the attached player: - specialeffect(EF_HIT1, SELF, "John Doe#1"); - - // To make a NPC do an effect and show it only to another player: - specialeffect(EF_HIT1, SELF, "John Doe#1", getcharid(CHAR_ID_ACCOUNT, "player")); - ---------------------------------------- - -*specialeffect2(<effect number>{, <send_target>{, "<Player Name>"}}) - - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - @ /!\ This command is deprecated @ - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - -This command behaves identically to the specialeffect(), but the effect -will be centered on the invoking character's sprite. - -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 use specialeffect instead, -ie: specialeffect(<effect number>, <send_target>, playerattached()) - ---------------------------------------- - -*statusup(<stat>) - -This command will bump a specified stat of the invoking character up by -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 -bInt - Intelligence -bAgi - Agility -bDex - Dexterity -bLuk - Luck - ---------------------------------------- - -*statusup2(<stat>, <amount>) - -This command will bump a specified stat of the invoking character up by -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); - ---------------------------------------- - -*bonus(<bonus type>, <val1>) -*bonus2(<bonus type>, <val1>, <val2>) -*bonus3(<bonus type>, <val1>, <val2>, <val3>) -*bonus4(<bonus type>, <val1>, <val2>, <val3>, <val4>) -*bonus5(<bonus type>, <val1>, <val2>, <val3>, <val4>, <val5>) - -These commands are meant to be used in item scripts. They will probably -work outside item scripts, but the bonus will not persist for long. They, -as expected, refer only to an invoking character. - -You can find the full list of possible bonuses and which command to use -for each kind in 'doc/item_bonus.txt'. - ---------------------------------------- - -*autobonus(<bonus script>, <rate>, <duration>{, <flag>, {<other script>}}) -*autobonus2(<bonus script>, <rate>, <duration>{, <flag>, {<other script>}}) -*autobonus3(<bonus script>, <rate>, <duration>, <skill id>, {<other script>}) -*autobonus3(<bonus script>, <rate>, <duration>, "<skill name>", {<other script>}) - -These commands are meant to be used in item scripts. They will probably -work outside item scripts, but the bonus will not persist for long. They, -as expected, refer only to an invoking character. - -What these commands do is 'attach' a script to the player which will get -executed on attack (or when attacked in the case of autobonus2()). - -Rate is the trigger rate of the script (1000 = 100%). - -Duration is the time that the bonus will last for since the script has -triggered. - -Skill ID/skill name the skill which will be used as trigger to start the -bonus (for autobonus3()). - -The optional argument 'flag' is used to classify the type of attack where -the script can trigger (it shares the same flags as the bAutoSpell bonus -script): - -Range criteria: - BF_SHORT: Trigger on melee attack - BF_LONG: Trigger on ranged attack - Default: BF_SHORT+BF_LONG -Attack type criteria: - BF_WEAPON: Trigger on weapon skills - BF_MAGIC: Trigger on magic skills - BF_MISC: Trigger on misc skills - Default: BF_WEAPON -Skill criteria: - BF_NORMAL: Trigger on normal attacks - BF_SKILL: Trigger on skills - default: If the attack type is BF_WEAPON (only) BF_NORMAL is used, - otherwise BF_SKILL+BF_NORMAL is used. - -The difference between the optional argument 'other script' and the 'bonus -script' is that, the former one triggers only when attacking (or attacked) -and the latter one runs on status calculation as well, which makes sure, -within the duration, the "bonus" that get lost on status calculation is -restored. So, 'bonus script' is technically supposed to accept "bonus" -command only. And we usually use 'other script' to show visual effects. - -In all cases, when the script triggers, the attached player will be the -one who holds the bonus. There is currently no way of knowing within this -script who was the other character (the attacker in autobonus2(), or the -target in autobonus() and autobonus3()). - -//Grants a 1% chance of starting the state "all stats +10" for 10 seconds -//when using weapon or misc attacks (both melee and ranged skills) and -//shows a special effect when the bonus is active. - autobonus("{ bonus(bAllStats, 10); }", 10, 10000, BF_WEAPON|BF_MISC, "{ specialeffect(EF_FIRESPLASHHIT, AREA, playerattached()); }"); - ---------------------------------------- - -*skill(<skill id>, <level>{, <flag>}) -*skill("<skill name>", <level>{, <flag>}) -*addtoskill(<skill id>, <level>{, <flag>}) -*addtoskill("<skill name>", <level>{, <flag>}) - -These commands will give the invoking character a specified skill. This is -also used for item scripts. - -Level is obvious. Skill id is the ID number of the skill in question as -per 'db/(pre-)re/skill_db.txt'. It is not known for certain whether this -can be used to give a character a monster's skill, but you're welcome to -try with the numbers given in 'db/(pre-)re/mob_skill_db.txt'. - -Flag is 0 if the skill is given permanently (will get written with the -character data) or 1 if it is temporary (will be lost eventually, this is -meant for card item scripts usage.). The flag parameter is optional, and -defaults to 1 in 'skill' and to 2 in 'addtoskill'. - -Flag 2 means that the level parameter is to be interpreted as a stackable -additional bonus to the skill level. If the character did not have that -skill previously, they will now at 0+the level given. - -// This will permanently give the character Stone Throw -// (TF_THROWSTONE, 152), at level 1. - skill(TF_THROWSTONE, 1, 0); - -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). - ---------------------------------------- - -*nude() - -This command will unequip anything equipped on the invoking character. - -It is not required to do this when changing jobs since jobchange() will -unequip everything not equippable by the new job class anyway. - ---------------------------------------- - -*disguise(<Monster ID>) -*undisguise() - -This command disguises the current player with a monster sprite. -The disguise lasts until undisguise() is issued or the player logs out. - -Example: - -disguise(PORING); // Disguise character as a Poring. -next(); -undisguise(); // Return to normal character sprite. - ---------------------------------------- -//===================================== -4.3 - Marriage-Related Commands -//===================================== ---------------------------------------- - -*marriage("<spouse name>") - -This function will marry two characters, the invoking character and the -one referred to by name given, together, setting them up as each other's -marriage partner. No second function call has to be issued (in current Git -at least) to make sure the marriage works both ways. The function returns -true upon success, or false if the marriage could not be completed, either -because the other character wasn't found or because one of the two -characters is already married. - -This will do nothing else for the marriage except setting up the spouse ID -for both of these characters. No rings will be given and no effects will -be shown. - ---------------------------------------- - -*wedding() - -This command will call up wedding effects - the music and confetti - -centered on the invoking character. Example can be found in the wedding -script. - ---------------------------------------- - -*divorce() - -This function will "un-marry" the invoking character from whoever they -were married to. Both will no longer be each other's marriage partner, -(at least in current Git, which prevents the cases of multi-spouse -problems). It will return true upon success or false if the character -was not married at all. - -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 -//===================================== ---------------------------------------- - -*pcfollow(<id>, <target id>) -*pcstopfollow(<id>) - -Makes a character follow or stop following someone. This command does the -same as the @follow command. The main difference is that @follow can use -character names, and this commands needs the Account ID for the target. - -Examples: - -// This will make Aaron follow Bullah, when both of these characters are -// online. - pcfollow(getcharid(CHAR_ID_ACCOUNT, "Aaron"), getcharid(CHAR_ID_ACCOUNT, "Bullah")); - -// Makes Aaron stop following whoever he is following. - pcstopfollow(getcharid(CHAR_ID_ACCOUNT, "Aaron")); - ---------------------------------------- - -*pcblockmove(<id>, <option>) - -Prevents the given ID from moving when the optionis true , and false -enables the ID to move again. The ID can either be the GID of a -monster/NPC or account ID of a character, and will run for the attached -player if zero is supplied. - -Examples: - -// Prevents the current char from moving away. - pcblockmove(getcharid(CHAR_ID_ACCOUNT), true); - -// Enables the current char to move again. - pcblockmove(getcharid(CHAR_ID_ACCOUNT), false); - - ---------------------------------------- -//===================================== -4 - End of Player-Related Commands -//===================================== ---------------------------------------- - ---------------------------------------- -//===================================== -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 -name, "this", will be recognized to mean the name of the map the invoking -character is located at. This command works fine in the item scripts. - -The same command arguments mean the same things as described above in the -beginning of this document when talking about permanent monster spawns. -Monsters spawned in this manner will not respawn upon being killed. - -Unlike the permanent monster spawns, if the mob id is -1, a random monster -will be picked from the entire database according to the rules configured -in the server for dead branches. This will work for all other kinds of -non-permanent monster spawns. - -The only very special thing about this command is an event label, which is -an optional parameter. This label is written like -'<NPC object name>::<label name>' and upon the monster being killed, it -will execute the script inside of the specified NPC object starting from -the label given. The RID of the player attached at this execution will be -the RID of the killing character. - -<size> can be: - Size_Medium = medium (default) - Size_Small = small - Size_Large = big - -<ai> can be: - 0 = none (default) - 1 = attack/friendly - 2 = sphere (Alchemist skill) - 3 = flora (Alchemist skill) - 4 = zanzou (Kagerou/Oboro skill) - - monster("place", 60, 100, "Poring", PORING, 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 -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: - .@mobGID = monster("prontera", 150, 150, "Poring", PORING, 1); // PORING is defined in the mob db and its value is 1002 - unitattack(.@mobGID, getcharid(CHAR_ID_ACCOUNT)); // 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 (.@i = 0; .@i < .mobnumber; ++.@i) { - .@mobGID = monster("map", .x, .y, "Kisser Poring", PORING, 1); - unitemote(.@mobGID, e_kis); - } - -Refer to the unit* commands below. - -The areamonster() command works much like the monster() command and is not -significantly different, but spawns the monsters within a square defined -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(); - 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. - ---------------------------------------- - -*areamobuseskill("<map name>", <x>, <y>, <range>, <mob id>, <skill id>, <skill level>, <cast time>, <cancelable>, <emotion>, <target type>) -*areamobuseskill("<map name>", <x>, <y>, <range>, <mob id>, "<skill name>", <skill level>, <cast time>, <cancelable>, <emotion>, <target type>) - -This command will make all monsters of the specified mob ID in the -specified area use the specified skill. Map name, x, and y define the -center of the area, which extending <range> cells in each direction (ex: a -range of 3 would create a 7x7 square). The skill can be specified by skill -ID or name. <cast time> is in milliseconds (1000 = 1 second), and the rest -should be self-explanatory. - -<target type> can be: - 0 = self - 1 = the mob's current target - 2 = the mob's master - 3 = random target - -Example: - - // spawn 1 Shining Plant in the 5x5 area centered on (155,188) - areamonster("prontera", 153, 186, 157, 190, "Shining Plant", SHINING_PLANT, 1); - // make the plant cast level 10 Cold Bolt on a random target - areamobuseskill("prontera", 155, 188, 2, SHINING_PLANT, MG_COLDBOLT, 10, 3000, 1, e_gg, 3) - ---------------------------------------- - -*killmonster("<map name>", "<event label>"{, <type>}) - -This command will kill all monsters that were spawned with monster() or -areamonster() and have a specified event label attached to them. Commonly -used to get rid of remaining quest monsters once the quest is complete. - -If the label is given as "All", all monsters which have their respawn -times set to -1 (like all the monsters summoned with 'monster' or -'areamonster' script command, and all monsters summoned with GM commands, -but no other ones - that is, all non-permanent monsters) on the specified -map will be killed regardless of the event label value. - -killmonster() supports an optional argument type. Using 1 for type will make -the command fire "OnMyMobDead" events from any monsters that do die as a -result of this command. - ---------------------------------------- - -*killmonsterall("<map name>"{, <type>}) - -This command will kill all monsters on a specified map name, regardless of -how they were spawned or what they are without triggering any event label -attached to them, unless you specify 1 for type parameter. In this case, -mob death labels will be allowed totrigger when there is no player. Any -other number for this parameter won't be recognized. - ---------------------------------------- - -*strmobinfo(<type>, <monster id>) - -This function will return information about a monster record in the -database, as per 'db/(pre-)re/mob_db.txt'. Type is the kind of information -returned. Valid types are: - - 1 - 'english name' field in the database, a string. - 2 - 'japanese name' field in the database, a string. - All other returned values are numbers: - 3 - Level. - 4 - Maximum HP. - 5 - Maximum SP. - 6 - Experience reward. - 7 - Job experience reward. - ---------------------------------------- - -*mobcount("<map name>", "<event label>") - -This function will count all the monsters on the specified map that have a -given event label and return the number or 0 if it can't find any. -Naturally, only monsters spawned with 'monster' and 'areamonster' script -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. - -If the map name is given as "this", the map the invoking character is on -will be used. If the map is not found, or the invoker is not a character -while the map is "this", it will return -1. - ---------------------------------------- - -*clone("<map name>", <x>, <y>, "<event>", <char id>{, <master_id>{, <mode>{, <flag>, <duration>}}}) - -This command creates a monster which is a copy of another player. The -first four arguments serve the same purpose as in the monster script -command, The <char id> is the character id of the player to clone (player -must be online). -If <master id> is given, the clone will be a 'slave/minion' of it. -Master_id must be a character id of another online player. - -The mode can be specified to determine the behavior of the clone, its -values are the same as the ones used for the mode field in the mob_db. The -default mode is aggressive, assists, can move, can attack. - -Flag can be either zero or one currently. If zero, the clone is a normal -monster that'll target players, if one, it is considered a summoned -monster, and as such, it'll target other monsters. Defaults to zero. - -The duration specifies how long the clone will live before it is -auto-removed. Specified in seconds, defaults to no limit (zero). - -Returned value is the monster ID of the spawned clone. If command fails, -returned value is zero. - ---------------------------------------- - -*summon("Monster name", <monster id>{, <Time Out>{, "event label"}}) - -This command will summon a monster. (see also monster()) Unlike monsters -spawned with other commands, this one will set up the monster to fight to -protect the invoking character. Monster name and mob id obey the same -rules as the one given at the beginning of this document for permanent -monster spawns with the exceptions mentioned when describing 'monster' -command. - -The effect for the skill 'Call Homunculus' will be displayed centered on -the invoking character. - -Timeout is the time in milliseconds the summon lives, and is set default -to 60000 (1 minute). Note that also the value 0 will set the timer to -default, and it is not possible to create a spawn that lasts forever. -If an event label is given, upon the monster being killed, the event label -will run as if by donpcevent(). - -// Will summon a poring to fight for the character. - summon("--ja--", PORING); - ---------------------------------------- - -*homevolution() - -This command will try to evolve the current player's homunculus. -If it doesn't work, the /swt emotion is shown. - -To evolve a homunculus, the invoking player must have a homunculus, the -homunculus must not be the last evolution and the homunculus must have -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 - -If the attached player doesn't own a homunculus, this command will return -"null" for type 2, and return 0 for other types. - ---------------------------------------- - -*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 (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. - -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 true upon success and false for all failures. - ---------------------------------------- - -*checkhomcall() - -This function checks if the attached player's Homunculus is active, -and will return the following values: - -1: The player has no Homunculus. - 0: The player's Homunculus is active. - 1: The player's Homunculus is vaporized. - 2: The player's Homunculus is in morph state. - ---------------------------------------- - -*getunittype(<GID>) - -Returns the type of object from the given Game ID. Returns -1 if the given GID -does not exist. The return values are :- - - UNITTYPE_PC 0 - UNITTYPE_NPC 1 - UNITTYPE_PET 2 - UNITTYPE_MOB 3 - UNITTYPE_HOM 4 - UNITTYPE_MER 5 - UNITTYPE_ELEM 6 - ---------------------------------------- - -*unitwalk(<GID>, <x>, <y>) -*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 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. - -Examples: - -//Will move/walk the poring we made to the coordinates 150,150 - unitwalk(.GID, 150, 150); - -//NPC will move towards the attached player. - unitwalk(.GID, getcharid(CHAR_ID_ACCOUNT));//a player's GID is their account ID - ---------------------------------------- - -*unitkill(<GID>) -*unitwarp(<GID>, <Mapname>, <x>, <y>) -*unitattack(<GID>, <Target ID>) -*unitstop(<GID>) -*unittalk(<GID>, <Text>) -*unitemote(<GID>, <Emote>) - -Okay, these commands should be fairly self explaining. -For the emotions, you can look in db/constants.conf for prefixes with e_ -PS: unitwarp() supports a <GID> of zero, which causes the executor of the -script to be affected. This can be used with OnTouchNPC to warp -monsters: - -OnTouchNPC: - unitwarp(0, "this", -1, -1); - ---------------------------------------- - -*disablenpc("<NPC object name>") -*enablenpc("<NPC object name>") - -These two commands will disable and enable, respectively, an NPC object -specified by name. The disabled NPC will disappear from sight and will no -longer be triggerable in the normal way. It is not clear whether it will -still be accessible through donpcevent() and other triggering commands, -but it probably will be. You can disable even warp NPCs if you know their -object names, which is an easy way to make a map only accessible through -walking half the time. Then you 'enablenpc' them back. - -You can also use these commands to create the illusion of an NPC switching -between several locations, which is often better than actually moving the -NPC - create one NPC object with a visible and a hidden part to their -name, make a few copies, and then disable all except one. - ---------------------------------------- - -*hideonnpc("<NPC object name>") -*hideoffnpc("<NPC object name>") - -These commands will make the NPC object specified display as hidden or -visible, even though not actually disabled per se. Hidden as in thief Hide -skill, but unfortunately, not detectable by Ruwach or Sight. - -As they are now, these commands are pointless, it is suggested to use -'disablenpc'/'enablenpc', because these two commands actually unload the -NPC sprite location and other accompanying data from memory when it is not -used. However, you can use these for some quest ideas (such as cloaking -NPCs talking while hidden then revealing... you can wonder around =P). - ---------------------------------------- - -*doevent("<NPC object name>::<event label>") - -This command will start a new execution thread in a specified NPC object -at the specified label. The execution of the script running this command -will not stop, and the event called by the doevent() command will not run -until the invoking script has terminated. No parameters may be passed with -a doevent() call. - -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(); - } - - // ... - - doevent("NPC::OnLabel"); - ---------------------------------------- - -*donpcevent("<NPC object name>::<event label>") - -This command invokes the event label code within an another NPC or NPCs. -It starts a separate instance of execution, and the invoking NPC will -resume execution its immediately. - -If the supplied event label has the form "NpcName::OnLabel", then only -given NPC's event label will be invoked (much like goto() into another -NPC). If the form is "::OnLabel" (NPC name omitted), the event code of all -NPCs with given label will be invoked, one after another. In both cases -the invoked script will run without an attached RID, whether or not the -invoking script was attached to a player. The event label name is required -to start with "On". - -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(); - @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(); - @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. - -Command returns true or false on success and failure. -A debug message also shows on the console when no events are triggered. - ---------------------------------------- - -*npctalk("<message>"{, "<npc name>"}) - -This command will display a message to the surrounding area as if the NPC -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(PC_NAME)+", how are you?"); - npctalk("Hello "+strcharinfo(PC_NAME)+", how are you?", "Another_NPC_Name"); - ---------------------------------------- - -*setnpcdisplay("<npc name>", "<display name>", <class id>, <size>) -*setnpcdisplay("<npc name>", "<display name>", <class id>) -*setnpcdisplay("<npc name>", "<display name>") -*setnpcdisplay("<npc name>", <class id>) - -Changes the display name and/or display class of the target NPC. -Returns 0 is successful, 1 if the NPC does not exist. -Size is 0 = normal 1 = small 2 = big. - ---------------------------------------- -//===================================== -5.1 - Time-Related Commands -//===================================== ---------------------------------------- - -*addtimer(<ticks>, "NPC::OnLabel"{, <account id>}) - -This command will create a countdown timer. -The event label given is the identifier of that timer. -The timer runs on the character object that is attached to the script, -and can have multiple instances. If <acccount id> is passed, this player -will be used instead. When the label is run, it is run as if the player -that the timer runs on has clicked the NPC. - -When this timer runs out, a new execution thread will start in the -specified NPC object at the specified label. - -The ticks are given in 1/1000ths of a second. - -One more thing. These timers are stored as part of player data. If the -player logs out, all of these get immediately deleted, without executing -the script. If this behavior is undesirable, use some other timer -mechanism (like sleep()). - -Example: -<NPC Header> { - dispbottom("Starting a 5 second timer..."); - addtimer(5000, strnpcinfo(NPC_NAME_UNIQUE)+"::On5secs"); - end; -On5secs: - dispbottom("5 seconds have passed!"); - end; -} - ---------------------------------------- - -*deltimer("NPC::OnLabel"{, <account id>}) - -Deletes timers created by addtimer() that matches the given event -label. Refer to addtimer() for additional information. - ---------------------------------------- - -*addtimercount("NPC::OnLabel", <ticks>{, <account id>}) - -Delays a timer that was created with addtimer() by <ticks> ticks -if it matches the given event label. Refer to addtimer() for additional -information. - ---------------------------------------- - -*gettimer(<type>{, <account id>{, "<event>"}}) - -Returns informations on timers that were created by addtimer(). - -valid <type> for gettimer() are: - -(0) TIMER_COUNT - Will return the total number of timers for the specified or - attached player. Can be filtered by <event>. -(1) TIMER_TICK_NEXT - Will return the number of ticks until the next timer runs - for the specified or attached player. Can be filtered by <event>. -(2) TIMER_TICK_LAST - Will return the number of ticks until the last timer runs - for the specified or attached player. Can be filtered by <event>. - ---------------------------------------- - -*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 -as target. - -Contrary to addtimer()/deltimer() commands which let you have many different -timers referencing different labels in the same NPC, each with their own -countdown, initnpctimer() can only have one per NPC object. But it can -trigger many labels and let you know how many were triggered already and -how many still remain. - -This timer is counting up from 0 in ticks of 1/1000ths of a second each. -Upon creating this timer, the execution will not stop, but will happily -continue onward. The timer will then invoke new execution threads at -labels "OnTimer<time>:" in the NPC object it is attached to. - -To create the timer, use the initnpctimer(), which will start it running. -stopnpctimer() will pause the timer, without clearing the current tick, -while startnpctimer() will let the paused timer continue. - -By default timers do not have a RID attached, which lets them continue -even if the player that started them logs off. To attach a RID to a timer, -you can either use the optional "attach flag" when using -initnpctimer()/startnpctimer(), or do it manually by using attachnpctimer(). -Likewise, the optional flag of stopnpctimer() lets you detach any RID after -stopping the timer, and by using detachnpctimer() you can detach a RID at -any time. - -Normally there is only a single timer per NPC, but as an exception, as -long as you attach a player to the timer, you can have multiple timers -running at once, because these will get stored on the players instead of -the NPC. -NOTE: You need to attach the RID before the timer _before_ you start it to -get a player-attached timer. Otherwise it'll stay a NPC timer (no effect). - -If the player that is attached to the npctimer logs out, the -"OnTimerQuit:" event label of that NPC will be triggered, so you can do -the appropriate cleanup (the player is still attached when this event is -triggered). - -The setnpctimer() command will explicitly set the timer to a given tick. -getnpctimer() provides timer information. Its parameter defines what type: - - 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. - 2 - Will return the number of times the timer has triggered and will - 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! - } - -Example 2: - - 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; - -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(); - -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; - ---------------------------------------- - -*sleep(<milliseconds>) -*sleep2(<milliseconds>) -*awake("<NPC name>") - -These commands are used to control the pause of a NPC. -sleep() and sleep2() will pause the script for the given amount of -milliseconds. -awake() is used to cancel a sleep(). When awake() is called on a NPC it will run -as if the sleep timer ran out, and thus making the script continue. sleep() -and sleep2() basically do the same, but the main difference is that sleep() -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. - sleep2(5000); - //Cancels any running sleep timers on the NPC 'NPC'. - awake("NPC"); - ---------------------------------------- - -*progressbar("<color>", <seconds>) - -This command works almost like sleep2(), but displays a progress bar above -the head of the currently attached character (like cast bar). Once the -given amount of seconds passes, the script resumes. If the character moves -while the progress bar progresses, it is aborted and the script ends. The -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 -//===================================== ---------------------------------------- - -*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.", bc_all); - -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. - -The flag values are coded as constants in db/constants.conf 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. - -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). -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. -Due to the way client handles broadcasts, it is impossible to set both -bc_blue and bc_woe. - -The optional parameters allow usage of broadcasts in custom colors, -font-weights, sizes etc. If any of the optional parameters is used, -special flag is ignored. Optional parameters may not work well (or at all) -depending on a game client used. - -The color parameter is a single number which can be in hexadecimal -notation. C_ constant can also be used for color effects, see the full list -of the available ones in 'db/constants.conf' under 'C_'. - -For example: - announce("This announcement will be shown to everyone in green.", bc_all, 0x00FF00); -Will display a global announce in green. The color format is in RGB -(0xRRGGBB). - -Another example: - announce("This announcement will shown to everyone in purple.", bc_all, C_PURPLE); - -In official scripts only two font-weights (types) are used: - - normal (FW_NORMAL = 400, default), - - bold (FW_BOLD = 700). - -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 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); - ---------------------------------------- - -*mapannounce("<map name>", "<text>", <flag>{, <fontColor>{, <fontType>{, <fontSize>{, <fontAlign>{, <fontY>}}}}}}) - -This command will work like announce() but will only broadcast to -characters currently residing on the specified map. The flag and optional -parameters parameters are the same as in announce(), but target and source -flags are ignored. - ---------------------------------------- - -*areaannounce("<map name>", <x1>, <y1>, <x2>, <y2>, "<text>", <flag>{, <fontColor>{, <fontType>{, <fontSize>{, <fontAlign>{, <fontY>}}}}}}) - -This command works like 'announce' but will only broadcast to characters -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); - ---------------------------------------- - -*callshop("<name>", <option>) - -These are a series of commands used to create dynamic shops. -The callshop() function calls an invisible shop (FAKE_NPC) as if the player -clicked on it. - -For the options on callShop: - 0 = The normal window (buy, sell and cancel) - 1 = The buy window - 2 = The sell window - -Example: - -//Will call the shop named DaShop and opens the buy menu. -callshop("DaShop", 1); - - -The shop which is called by callshop() (as long as an npcshop* command is -executed from that NPC (see note 1)) will trigger the labels OnBuyItem and -OnSellitem. These labels can take over handling for relatively the buying -of items from the shop and selling the items to a shop. Via these labels -you can customize the way an item is bought or sold by a player. - -In the OnBuyItem, two arrays are filled (@bought_nameid and -@bought_quantity) with information about the name id (item id) sold -and the amount sold of it. Same goes for the OnSellItem label, only the -variables are named different (@sold_nameid, @sold_quantity, @sold_refine, -@sold_attribute, @sold_identify, @sold_card1, @sold_card2, @sold_card3, -@sold_card4). An example on a shop comes with Hercules, and can be found -in the doc/sample/npc_dynamic_shop.txt file. - -This example shows how to use the labels and their set variables to create -a dynamic shop. - -Note 1: These labels will only be triggered if a npcshop* command is -executed, this is because these commands set a special data on the shop -NPC, named master_nd in the source. -The OnSellItem and OnBuyItem are triggered in the NPC whose master_nd is -given in the shop. - ---------------------------------------- - -*npcshopitem("<name>", <item id>, <price>{, <item id>, <price>{, <item id>, <price>{, ...}}}) - -This command lets you override the contents of an existing NPC shop or -cashshop. The current sell list will be wiped, and only the items -specified with the price specified will be for sale. - -The function returns true if shop was updated successfully, or false if not found. - -Note that you cannot use -1 to specify default selling price! - ---------------------------------------- - -*npcshopadditem("<name>", <item id>, <price>{, <item id>, <price>{, <item id>, <price>{, ...}}}) - -This command will add more items at the end of the selling list for the -specified NPC shop or cashshop. If you specify an item already for sell, -that item will appear twice on the sell list. - -The function returns true if shop was updated successfully, or false if not found. - -Note that you cannot use -1 to specify default selling price! - ---------------------------------------- - -*npcshopdelitem("<name>", <item id>{, <item id>{, <item id>{, ...}}}) - -This command will remove items from the specified NPC shop or cashshop. -If the item to remove exists more than once on the shop, all instances -will be removed. - -Note that the function returns true even if no items were removed. The return -value is only to confirm that the shop was indeed found. - ---------------------------------------- - -*npcshopattach("<name>"{, <flag>}) - -This command will attach the current script to the given NPC shop. -When a script is attached to a shop, the events "OnBuyItem" and -"OnSellItem" of your script will be executed whenever a player buys/sells -from the shop. Additionally, the arrays @bought_nameid[], -@bought_quantity[] or @sold_nameid[] and @sold_quantity[] will be filled -up with the items and quantities bought/sold. - -The optional parameter specifies whether to attach (true) or detach (false) -from the shop (the default is to attach). Note that detaching will detach -any NPC attached to the shop, even if it's from another script, while -attaching will override any other script that may be already attached. - -The function returns false if the shop was not found, true otherwise. - ---------------------------------------- - -*waitingroom("<chatroom name>", <limit>{, <event label>, <trigger>, <required zeny>, <min lvl>, <max lvl>}) - -This command will create a chat room, owned by the NPC object running this -script and displayed above the NPC sprite. -The maximum length of a chat room name is 60 letters. - -The limit is the maximum number of people allowed to enter the chat room. -The attached NPC is included in this count. If the optional event and -trigger parameters are given, the event label -("<NPC object name>::<label name>") will be invoked as if with a donpcevent() -upon the number of people in the chat room reaching the given triggering -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); - -// 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 -// the chat room, where 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("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 -// a player who has 5000 zeny and lvl 50~99 to enter the chat room, where -// 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); - -Creating a waiting room does not stop the execution of the script and it -will continue to the next line. - -For more examples see the 2-1 and 2-2 job quest scripts which make -extensive use of waiting rooms. - ---------------------------------------- - -*delwaitingroom({"<NPC object name"}) - -This command will delete a waiting room. If no parameter is given, it will -delete a waiting room attached to the NPC object running this command, if -it is, it will delete a waiting room owned by another NPC object. This is -the only way to get rid of a waiting room, nothing else will cause it to -disappear. - -It's not clear what happens to a waiting room if the NPC is disabled with -disablenpc(), by the way. - ---------------------------------------- - -*enablewaitingroomevent({"<NPC object name>"}) -*disablewaitingroomevent({"<NPC object name>"}) - -This will enable and disable triggering the waiting room event (see -waitingroom()) respectively. Optionally giving an NPC object name will do -that for a specified NPC object. The chat room will not disappear when -triggering is disabled and enabled in this manner and players will not be -kicked out of it. Enabling a chat room event will also cause it to -immediately check whether the number of users in it exceeded the trigger -amount and trigger the event accordingly. - -Normally, whenever a waiting room was created to make sure that only one -character is, for example, trying to pass a job quest trial, and no other -characters are present in the room to mess up the script. - ---------------------------------------- - -*getwaitingroomstate(<information type>{, "<NPC object name>"}) - -This function will return information about the waiting room state for the -attached waiting room or for a waiting room attached to the specified NPC -if any. - -The valid information types are: - - 0 - Number of users currently in the waiting room - $@chatmembers[] - list of user account_id - 1 - Maximum number of users allowed. - 2 - Will return 1 if the waiting room has a trigger set. - 0 otherwise. - 3 - Will return 1 if the waiting room is currently disabled. - 0 otherwise. - 4 - The Title of the waiting room (string) - 5 - Password of the waiting room, if any. Pointless, since there is no - way to set a password on a waiting room right now. - 16 - Event name of the waiting room (string) - 32 - Whether or not the waiting room is full. - 33 - Whether the amount of users in the waiting room is higher than the - trigger number. - 34 - Minimum Base Level to enter waiting room. - 35 - Maximum Base Level to enter waiting room. - 36 - Minimum Zeny to enter waiting room. - ---------------------------------------- - -*warpwaitingpc("<map name>", <x>, <y>{, <number of people>}) - -This command will warp the amount of characters equal to the trigger -number of the waiting room chat attached to the NPC object running this -command to the specified map and coordinates, kicking them out of the -chat. Those waiting the longest will get warped first. It can also do a -random warp on the same map ("Random" instead of map name) and warp to the -save point ("SavePoint"). - -The list of characters to warp is taken from the list of the chat room -members. Those not in the chat room will not be considered even if they -are talking to the NPC in question. If the number of people is given, -exactly this much people will be warped. - -This command can also keep track of who just got warped. It does this by -setting special variables: - -$@warpwaitingpc[] is an array containing the account_id numbers of the - characters who were just warped. -$@warpwaitingpcnum contains the number of the character it just warped. - -See also 'getpartymember' for advice on what to do with those variables. - -The obvious way of using this effectively would be to set up a waiting -room for two characters to be warped onto a random PVP map for a -one-on-one duel, for example. - ---------------------------------------- - -*kickwaitingroomall({"<NPC object name>"}) - -This command kicks everybody out of a specified waiting room chat. - ---------------------------------------- - -*setmapflagnosave("<map name>", "<alternate map name>", <x>, <y>) - -This command sets the 'nosave' flag for the specified map and also gives -an alternate respawn-upon-relogin point. - -It does not make a map impossible to make a save point on as you would -normally think, savepoint() will still work. It will, however, make the -specified map kick the reconnecting players off to the alternate map given -to the coordinates specified. - ---------------------------------------- - -*setmapflag("<map name>", <flag>{, <val>}) - -This command marks a specified map with a map flag given. Map flags alter -the behavior of the map, you can see the list of the available ones in -'db/constants.conf' under 'mf_'. - -The map flags alter the behavior of the map regarding teleporting -(mf_nomemo, mf_noteleport, mf_nowarp), storing location when -disconnected (mf_nosave), dead branch usage (mf_nobranch), penalties -upon death (mf_nopenalty, mf_nozenypenalty), PVP behavior (mf_pvp, -mf_pvp_noparty, mf_pvp_noguild), WoE behavior (mf_gvg, mf_gvg_noparty), -ability to use skills or open up trade deals (mf_notrade, mf_novending, -mf_noskill, mf_noicewall), current weather effects (mf_snow, mf_fog, -mf_sakura, mf_leaves, mf_clouds, mf_clouds2, mf_fireworks), whether -night will be in effect on this map (mf_nightenabled) and so on. - -The val optional parameter is as the mapflags variable when one exists, it -may be a number or a string depending on the mapflag in question. - ---------------------------------------- - -*removemapflag("<map name>", <flag>) - -This command removes a mapflag from a specified map. -See setmapflag() for examples of mapflags. - ---------------------------------------- - -*getmapflag("<map name>", <flag>) - -This command checks the status of a given mapflag and returns the -mapflag's state. -false means OFF, and true means ON. See setmapflag() for examples of mapflags. - ---------------------------------------- - -*setbattleflag("<battle flag>", <value>) -*getbattleflag("<battle flag>") - -Sets or gets the value of the given battle flag. -Battle flags are the flags found in the conf/map/battle/*.conf files and is -also used in Lupus' variable rates script. - -Examples: - -// Will set the base experience rate to 20x (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")); - ---------------------------------------- - -*warpportal(<x>, <y>, "<mapname>", <x>, <y>) - -Creates a warp Portal as if a acolyte class character did it. -The first x and y is the place of the warp portal on the map where the NPC -is on the mapname and second x and y is the target area of the warp portal. - -Examples: - -// Will create a warp portal on the NPC's map at 150,150 -// leading to prontera, coords 150,180. - warpportal(150, 150, "prontera", 150, 180); - ---------------------------------------- - -*mapwarp("<from map>", "<to map>", <x>, <y>{, <type>, <ID>}) - -This command will collect all characters located on the From map and warp -them wholesale to the same point on the To map, or randomly distribute -them there if the coordinates are zero. "Random" is understood as a -special To map name and will mean randomly shuffling everyone on the same -map. - -Optionally, a type and ID can be specified. Available types are: - - 0 - Everyone - 1 - Guild - 2 - Party - -Example: - -// Will warp all members of guild with ID 63 on map prontera to alberta. - mapwarp("prontera", "alberta", 150, 150, 1, 63); - ---------------------------------------- -//===================================== -5.2 - Guild-Related Commands -//===================================== ---------------------------------------- - -*maprespawnguildid("<map name>", <guild id>, <flag>) - -This command goes through the specified map and for each player and -monster found there does stuff. - -Flag is a bit-mask (add up numbers to get effects you want) - 1 - warp all guild members to their save points. - 2 - warp all non-guild members to their save points. - 4 - remove all monsters which are not guardian or Emperium. - -Flag 7 will, therefore, mean 'wipe all mobs but guardians and the Emperium -and kick all characters out', which is what the official scripts do upon -castle surrender. Upon start of WoE, the scripts do 2 (warp out all people -not in the guild that owns the castle). - -Characters not belonging to any guild will be warped out regardless of the -flag setting. - -For examples, check the WoE scripts in the distribution. - ---------------------------------------- - -*agitstart() -*agitend() -*agitstart2() -*agitend2() - -These four commands will start/end War of Emperium or War of Emperium SE. - -This is a bit more complex than it sounds, since the commands themselves -won't actually do anything interesting, except causing all 'OnAgitStart:' -and 'OnAgitEnd:', or 'OnAgitStart2:' and 'OnAgitEnd2:' in the case of -latter two commands, events to run everywhere, respectively. They are used -as simple triggers to run a lot of complex scripts all across the server, -and they, in turn, are triggered by clock with an 'OnClock<time>:' -time-triggering label. - ---------------------------------------- - -*gvgon("<map name>") -*gvgoff("<map name>") - -These commands will turn GVG mode for the specified maps on and off, -setting up appropriate map flags. In GVG mode, maps behave as if during -the time of WoE, even though WoE itself may or may not actually be in -effect. - ---------------------------------------- - -*flagemblem(<guild id>) - -This command only works when run by the NPC objects which have sprite id -GUILD_FLAG (722), which is a 3D guild flag sprite. If it isn't, the data -will change, but nothing will be seen by anyone. If it is invoked in -that manner, the emblem of the specified guild will appear on the flag, -though, if any players are watching it at this moment, they will not see -the emblem change until they move out of sight of the flag and return. - -This is commonly used in official guildwar scripts with a function call -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)); - ---------------------------------------- - -*guardian("<map name>", <x>, <y>, "<name to show>", <mob id>{, "<event label>"{, <guardian index>}}) - -This command is roughly equivalent to monster(), but is meant to be used -with castle guardian monsters and will only work with them. It will set -the guardian characteristics up according to the castle's investment -values and otherwise set the things up that only castle guardians need. - -Returns the id of the mob or 0 if an error occurred. -When 'guardian index' isn't supplied it produces a temporary guardian. -Temporary guardians are not saved with the castle and can't be accessed by -guardianinfo. - ---------------------------------------- - -*guardianinfo("<map name>", <guardian number>, <type>) - -This function will return various info about the specified guardian, or -1 -if it fails for some reason. It is primarily used in the castle manager -NPC. - -Map name and guardian number (value between 0 and 7) define the target. -Type indicates what information to return: - 0 - visibility (whether the guardian is installed or not) - 1 - max. hp - 2 - current hp - ---------------------------------------- -//===================================== -5.2 - End of Guild-Related Commands -//===================================== ---------------------------------------- - -*npcspeed(<speed value>) -*npcwalkto(<x>, <y>) -*npcstop() - -These commands will make the NPC object in question move around the map. -As they currently are, they are a bit buggy and are not useful for much -more than making an NPC move randomly around the map. - -npcspeed() will set the NPCs walking speed to a specified value. As in the -@speed GM command, 200 is the slowest possible speed while 0 is the -fastest possible (instant motion). 100 is the default character walking -speed. -npcwalkto() will start the NPC sprite moving towards the specified -coordinates on the same map as it is currently on. The script proceeds -immediately after the NPC begins moving. -npcstop() will stop the motion. - -While in transit, the NPC will be clickable, but invoking it will cause it -to stop moving, which will make it's coordinates different from what the -client computed based on the speed and motion coordinates. The effect is -rather unnerving. - -Only a few NPC sprites have walking animations, and those that do, do not -get the animation invoked when moving the NPC, due to the problem in the -NPC walking code, which looks a bit silly. You might have better success -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. - -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 -facing direction. - -Example: - -// This will move Bugga from to the coordinates 100,20 (if those -// coordinates are legit). - movenpc("Bugga", 100, 20); - ---------------------------------------- - -*navigateto("<map>"{,<x>,<y>,<flag>,<hide_window>,<monster_id>,<char_id>}); - -Generates a navigation for attached or specified character. Requires client -2011-10-10aRagEXE or newer. - -The flag specifies how the client will calculate the specific route. - -Valid flags are: - NAV_NONE - No services - NAV_AIRSHIP_ONLY - Airship only - NAV_SCROLL_ONLY - Scroll only - NAV_AIRSHIP_AND_SCROLL - Airship and Scroll - NAV_KAFRA_ONLY - Kafra only - NAV_KAFRA_AND_AIRSHIP - Kafra and Airship - NAV_KAFRA_AND_SCROLL - Kafra and Scroll - NAV_ALL - All services - -When flag is not specified, the default value is NAV_KAFRA_AND_AIRSHIP. - -The hide_window specifies whether to display (0) or hide (1) the navigation window. -By default the window is hidden. - -You can specify the monster_id in combination with a mapname to make the -navigation system tell you, that you have reached the desired mob. - -Note: -The client requires custom monster spawns be in the navigation file -for using the embedded client Navigation feature to work properly. In this -instance sending the player to the map where the monster spawns is a simpler -solution rather than sending the map and the monster_id. - ---------------------------------------- -//===================================== -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(PC_NAME)+" has clicked me!"); - - debugmes("\033[38D\033[K ==Message== \n"); // enable colour code. ---------------------------------------- - -*logmes("<message>") - -This command will write the message given to the map server NPC log file, -as specified in 'conf/map/logs.conf'. If SQL logging is enabled, the message -will go to the 'npclog' table. - -If logs are not enabled for NPCs, nothing will happen. - ---------------------------------------- - -*globalmes("<message>"{, "<NPC name>"}) - -This command will send a message to the chat window of all currently -connected characters. - -If NPC name is specified, the message will be sent as if the sender would -be the NPC with the said name. - ---------------------------------------- - -*channelmes("<#channel>", "<message>") - -This command will send a message to the specified chat channel. - -The sent message will not include any character's names. - -For special channels, such as #map and #ally, the attached RID's map or guild -will be used. - -If the channel doesn't exist (or, in the case of a character-specific channel, -no RID is attached), false will be returned. In case of success, true is -returned. - ---------------------------------------- - -*addchannelhandler("<#channel>", "<NPC::OnEvent>") - -This command will trigger the specified event every time a player -talks in the specified channel, with said player as attached rid. -It assigns the message to @channelmes$ - -OnChannelMessage: - channelmes("#chan", "Echo: " + @channelmes$); - end; - -OnInit: - addchannelhandler("#chan", "NPC::OnChannelMessage"); - ---------------------------------------- - -*removechannelhandler("<#channel>", "<NPC::OnEvent>") - -Removes a channel handler added by addchannelhandler() - ---------------------------------------- -*rand(<number>{, <number>}) - -This function returns a number ... -(if you specify one) ... randomly positioned between 0 and the number you - specify -1. -(if you specify two) ... randomly positioned between the two numbers you - specify. - -rand(10) would result in 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9 -rand(0, 9) would result in 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9 -rand(2, 5) would result in 2, 3, 4 or 5 - ---------------------------------------- - -*viewpoint(<action>, <x>, <y>, <point number>, <color>) - -This command will mark places on the mini map in the client connected to -the invoking character. It uses the normal X and Y coordinates from the -main map. The colors of the marks are defined using a hexadecimal number, -same as the ones used to color text in mes() output, but are written as -hexadecimal numbers in C. (They look like 0x<six numbers>.) - -Action is what you want to do with a point, 1 will set it, while 2 will -clear it. 0 will also set it, but automatically removes the point after 15 -seconds. -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 will create three points: - - 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); - -The client determines what it does with the points entirely, the server -keeps no memory of where the points are set whatsoever. - ---------------------------------------- - -*cutin("<filename>", <position>) - -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 - -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 -extension .bmp can be omitted. Magenta color (#ff00ff) is considered -transparent. There is no limit placed on the size of the illustrations -by the client, although loading of large pictures (about 700x700 and -larger) causes the client to freeze shortly (lag). Typically the size is -about 320x480. New illustrations can be added by just putting the new file -into the location above. - -The client is able to display only one cutin at the same time and each new -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); - - // Typical way to end a script, which displayed an illustration during a - // dialog with a player. - mes("See you."); - close2(); - cutin("", 255); - end; - ---------------------------------------- - -*pet(<pet id>) - -This command is used in all the item scripts for taming items. Running -this command will make the pet catching cursor appear on the client -connected to the invoking character, usable on the monsters with the -specified pet ID number. It will still work outside an item script. - -A full list of pet IDs can be found inside 'db/pet_db.txt' - ---------------------------------------- - -*emotion(<emotion number>{, <target>{, "<target name>"}}) - -This command makes an object display an emotion sprite above their own as -if they were doing that emotion. For a full list of emotion numbers, see -'db/constants.conf' under 'e_'. The not so obvious ones are 'e_what' (a -question mark) and 'e_gasp' (the exclamation mark). - -The optional target parameter specifies who will get the emotion on top of -their head. If false (default if omitted), the NPC in current use will show -the emotion, if true, the player that is running the script will display it. - -Target name parameter allows to display emotion on top of other NPC/PC -without event labels. If specified name is not found, command does nothing. - ---------------------------------------- - -*misceffect(<effect number>) - - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - @ /!\ This command is deprecated @ - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - -This command, if run from an NPC object that has a sprite, will call up a -specified effect number, centered on the NPC sprite. If the running code -does not have an object ID (a 'floating' NPC) or is not running from an -NPC object at all (an item script) the effect will be centered on the -character who's RID got attached to the script, if any. For usable item -scripts, this command will create an effect centered on the player using -the item. - -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 use specialeffect instead, -ie: specialeffect(<effect number>, <send target>, <unit id>) - ---------------------------------------- - -*soundeffect("<effect filename>", <type>) -*soundeffectall("<effect filename>", <type>{, "<map name>"}{, <x0>, <y0>, <x1>, <y1>}) - -These two commands will play a sound effect to either the invoking -character only (soundeffect()) or multiple characters (soundeffectall()). -If the running code does not have an object ID (a 'floating' NPC) or is -not running from an NPC object at all (an item script) the sound will be -centered on the character who's RID got attached to the script, if any. -If it does, it will be centered on that object. (an NPC sprite) - -Effect filename is the filename in a GRF. It must have the .wav extension. - -It's not quite certain what the 'type' actually does, it is sent to the -client directly. It probably determines which directory to play the effect -from. It's certain that giving 0 for the number will play sound files from -'\data\wav\', but where the other numbers will read from is unclear. - -The sound files themselves must be in the PCM format, and file names -should also have a maximum length of 23 characters including the .wav -extension: - -soundeffect("1234567890123456789.wav", 0); // will play the soundeffect -soundeffect("12345678901234567890.wav", 0); // throws gravity error - -You can add your own effects this way, naturally. - ---------------------------------------- - -*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()). - -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. - -If coordinates are omitted, BGM will be broadcasted on the entire map. If -the map name is also omitted the BGM will be played for the entire server. - -You can add your own BGMs this way, naturally. - ---------------------------------------- - -*pvpon("<map name>") -*pvpoff("<map name>") - -These commands will turn PVP mode for the specified maps on and off. -Beside setting the flags referred to in setmapflag(), pvpon() will also -create a PVP timer and ranking as will @pvpon GM command do. - ---------------------------------------- - -*atcommand("<command>") - -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$); - -Use of this command is not recommended unless you know what you're -doing, since not all atcommands are intended to be used by the script -engine. - ---------------------------------------- - -*charcommand("<command>") - -This command will run the given command line exactly as if it was typed in -from the keyboard from a character that belonged to an account which had -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"); - -Use of this command is not recommended unless you know what you're -doing, since not all atcommands are intended to be used by the script -engine. - ---------------------------------------- - -*bindatcmd("command", "<NPC object name>::<event label>"{, <group level>, <group level char>, <log>}) - -This command will bind a NPC event label to an atcommand. Upon execution -of the atcommand, the user will invoke the NPC event label. Each atcommand -is only allowed one binding. If you rebind, it will override the original -binding. If group level is provided, only users of that group level or -above will be able to access the command, if not provided, everyone will -be able to access the command. -"group level char" is the minimum group level required for the label to be -used on others like a char command would, e.g. "#command "target" params", -when not provided, "group level char" defaults to 99. -"log" whether to log the usages of this command with the atcommand log -(true = log, false = no log), default is to not log. - -The following variables are set upon execution: - .@atcmd_command$ = The name of the @command used. - .@atcmd_parameters$[] = Array containing the given parameters, - starting from an index of 0. - .@atcmd_numparameters = The number of parameters defined. - -Parameters are split on spaces. Multiple spaces aren't grouped together, and -will create multiple (empty) arguments. -Any leading spaces before the first parameter will be omitted. - -Usage example: - -When a user types the command "@test", an angel effect will be shown. - -- script atcmd_example FAKE_NPC,{ -OnInit: - bindatcmd("test", strnpcinfo(NPC_NAME_UNIQUE)+"::OnAtcommand"); - end; -OnAtcommand: - specialeffect(EF_ANGEL2, AREA, playerattached()); - end; -} - -Parameter splitting example: - @mycommand - .@atcmd_numparameters -> 0 - .@atcmd_parameters$ -> { } - @mycommand<space><space> - .@atcmd_numparameters -> 0 - .@atcmd_parameters$ -> { } - @mycommand<space>foo - .@atcmd_numparameters -> 1 - .@atcmd_parameters$ -> { "foo" } - @mycommand<space><space>foo - .@atcmd_numparameters -> 1 - .@atcmd_parameters$ -> { "foo" } - @mycommand<space>foo<space>bar - .@atcmd_numparameters -> 2 - .@atcmd_parameters$ -> { "foo", "bar" } - @mycommand<space>foo<space><space>bar - .@atcmd_numparameters -> 3 - .@atcmd_parameters$ -> { "foo", "", "bar" } - @mycommand<space>foo<space> - .@atcmd_numparameters -> 2 - .@atcmd_parameters$ -> { "foo", "" } - @mycommand<space>foo<space><space> - .@atcmd_numparameters -> 3 - .@atcmd_parameters$ -> { "foo", "", "" } - -The called event label needs to take care of joining arguments together, in -case it expects spaces. For example: - -- script atcmd_example FAKE_NPC,{ -OnInit: - bindatcmd("test", strnpcinfo(NPC_NAME_UNIQUE)+"::OnAtcommand"); - end; -OnAtcommand: - // This command expects a character name (that may contain spaces) as - // the only parameter. - .@name$ = ""; - for (.@i = 0; .@i < .@atcmd_numparameters; ++.@i) { - .@name$ += (.@i > 0 ? " " : "") + .@atcmd_parameters$[.@i]; - } - dispbottom("The specified name is: '" + .@name$ + "'"); - end; -} - ---------------------------------------- - -*add_group_command("<command>", <group id>, <use on self>, <use on other>) - -Allows to explicitly change the command permissions for a specific group. - -This command bypasses group inheritance, which means groups inheriting from -the specified <group id> will NOT inherit the specified permission. You should -use add_group_command() for every group you want to give permission to. - -Example: - bindatcmd("foobar", "NPC::OnUseCommand", 99, 99, 0); // define the command - add_group_command("foobar", 2, true, false); // allow group 2 to use @foobar - add_group_command("foobar", 5, true, true); // allow group 5 to use @foobar and #foobar - ---------------------------------------- - -*unbindatcmd("command") - -This command will unbind a NPC event label from an atcommand. - ---------------------------------------- - -*useatcmd("command") - -This command will execute an atcommand binding on the attached RID from a -script. The three .@atcmd_***** variables will NOT be set when invoking -scripts-atcommands this way. - ---------------------------------------- - -*can_use_command("<command>"{, <account id>}) - -Checks if the attached or specified player can use the specified -atcommand and returns true or false accordingly. Works for both -built-in atcommands and custom atcommands. - ---------------------------------------- - -*has_permission(<permission>{, <account id>}) -*has_permission("<permission>"{, <account id>}) - -Check if the attached or specified player has the specified permission -and returns true or false accordingly. See doc/permissions.txt for -details about permissions. - -Valid <permission> are: - - PERM_TRADE - PERM_PARTY - PERM_ALL_SKILL - PERM_USE_ALL_EQUIPMENT - PERM_SKILL_UNCONDITIONAL - PERM_JOIN_ALL_CHAT - PERM_NO_CHAT_KICK - PERM_HIDE_SESSION - PERM_WHO_DISPLAY_AID - PERM_RECEIVE_HACK_INFO - PERM_WARP_ANYWHERE - PERM_VIEW_HPMETER - PERM_VIEW_EQUIPMENT - PERM_USE_CHECK - PERM_USE_CHANGEMAPTYPE - PERM_USE_ALL_COMMANDS - PERM_RECEIVE_REQUESTS - PERM_SHOW_BOSS - PERM_DISABLE_PVM - PERM_DISABLE_PVP - PERM_DISABLE_CMD_DEAD - PERM_HCHSYS_ADMIN - PERM_TRADE_BOUND - PERM_DISABLE_PICK_UP - PERM_DISABLE_STORE - PERM_DISABLE_EXP - PERM_DISABLE_SKILL_USAGE - -Example: - - if (has_permission(PERM_WARP_ANYWHERE)) { - //do something - } - -It is also possible to pass a string for plugin permissions: - - if (has_permission("show_version")) { - //do something - } - -** Passing a string is slower than passing a constant because - the engine has to loop through the array to find the permission. - In most cases you should use the PERM_ constants. - ---------------------------------------- - -*unitskilluseid(<GID>, <skill id>, <skill lvl>{, <target id>}) -*unitskilluseid(<GID>, "<skill name>", <skill lvl>{, <target id>}) -*unitskillusepos(<GID>, <skill id>, <skill lvl>, <x>, <y>) -*unitskillusepos(<GID>, "<skill name>", <skill lvl>, <x>, <y>) - -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. - ---------------------------------------- - -*npcskill(<skill id>, <skill lvl>, <stat point>, <NPC level>) -*npcskill("<skill name>", <skill lvl>, <stat point>, <NPC level>) - -This command causes the attached NPC object to cast a skill on the -attached player. The skill will have no cast time or cooldown. The player -must be within the default skill range or the command will fail silently. - -The "stat point" parameter temporarily sets all NPC stats to the given -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); - ---------------------------------------- - -*setnpcdistance(<distance>) - -This command can reduce distance from where npc can be clicked. -Usefull to use from OnInit event. - - // Set distance to one tile on server load - OnInit: - setnpcdistance(1); - ---------------------------------------- - -*getnpcdir({<name>}) - -Return current npc direction for parameter "name" or for attached npc -if it missing. If name missing and not attached npc, return -1. - -Example: - .@dir = getnpcdir(); - ---------------------------------------- - -*setnpcdir({<name>, }<direction>) - -Set npc direction. If npc name missing, will be used attached npc. - -Example: - setnpcdir(DIR_WEST); - ---------------------------------------- - -*getnpcclass({<name>}) - -Return npc class/sprite id for npc with given name or for attached npc. -If name missing and no attached npc, return -1. - -Example: - .@class = getnpcclass(); - ---------------------------------------- - -*day(); -*night(); - -These two commands will switch the entire server between day and night -mode respectively. If your server is set to cycle between day and night by -configuration, it will eventually return to that cycle. - -Example: - -- script DayNight FAKE_NPC,{ -OnClock0600: - day(); - end; -OnInit: - // setting correct mode upon server start-up - if (gettime(GETTIME_HOUR) >= 6 && gettime(GETTIME_HOUR) < 18) - end; -OnClock1800: - night(); - end; -} - -This script allows to emulate the day/night cycle as the server does, but -also allows triggering additional effects upon change, like announces, -gifts, etc. -The day/night cycle set by configuration should be disabled when this -script is used. - ---------------------------------------- - -*pcre_match("<string>", "<regex>") - -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 true if no matches were found, or false 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>) - -They will make the NPC object listen for text spoken publicly by players -and match it against regular expression patterns, then trigger labels -associated with these regular expression patterns. - -Patterns are organized into sets, which are referred to by a set number. -You can have multiple sets patterns, and multiple patterns may be active -at once. Numbers for pattern sets start at 1. - -defpattern() will associate a given regular expression pattern with an -event label. This event will be triggered whenever something a player says -is matched by this regular expression pattern, if the pattern is currently -active. - -activatepset() will make the pattern set specified active. An active -pattern will enable triggering labels defined with defpattern(), which -will not happen by default. -deactivatepset() will deactivate a specified pattern set. Giving -1 as a -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. - -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 -for Zeny in public places, or alternatively, automatically give them Zeny -instead if they want it so much. - ---------------------------------------- - -*pow(<number>, <power>) - - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - @ /!\ This command is deprecated @ - @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ - -Returns the result of the calculation. - -Example: - .@i = pow(2, 3); // .@i will be 8 - -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 use the exponentiation operator, -ie: (2 ** 3) instead of pow(2, 3) - ---------------------------------------- - -*log10(<number>) - -Returns log base 10 of the number. - -Note: The value is truncated to integer. - -Example: - .@i = log10(100); // .@i will be 2 - ---------------------------------------- - -*sqrt(<number>) - -Returns square-root of number. - -Note: The value is truncated to integer. - -Example: - .@i = sqrt(25); // .@i will be 5 - ---------------------------------------- - -*distance(<x0>, <y0>, <x1>, <y1>) - -Returns distance between 2 points. - -Note: When Hercules is configured to use circular areas, the Euclidean distance -is returned, otherwise the Chebyshev distance. The value is truncated to -integer. - -Example: - .@i = distance(100, 200, 101, 202); - ---------------------------------------- - -*min(<number>{, <number>...<number>}) -*max(<number>{, <number>...<number>}) - -Returns the smallest (or biggest) from the set of given numbers. - -Example: - .@minimum = min(1, -6, -2, 8, 2); // .@minimum will be equal to -6 - .@maximum = max(0, 5, 10, 4); // .@maximum will be equal to 10 - .@level = min(BaseLevel, 70); // .@level will be the character's base level, capped to 70 - ---------------------------------------- - -*md5("<string>") - -Returns the md5 checksum of a number or string. - -Example: - mes md5(12345); - mes md5("12345"); // Will both display 827ccb0eea8a706c4c34a16891f84e7b - mes md5("qwerty");// Will display d8578edf8458ce06fbc5bb76a58c5ca4 - ---------------------------------------- - -*swap(<variable>, <variable>) - -Swap the value of 2 variables. Both sides must be same integer or string type. - -Example: - .@var1 = 111; - .@var2 = 222; - swap(.@var1, .@var2); - mes("var1 = "+ .@var1); // return 222 - mes("var2 = "+ .@var2); // return 111 - ---------------------------------------- - -*query_sql("your MySQL query"{, <array variable>{, <array variable>{, ...}}}) -*query_logsql("your MySQL query"{, <array variable>{, <array variable>{, ...}}}) - -Executes an SQL query. A 'select' query can fill array variables with up -to 128 rows of values, and will return the number of rows (the array size). - -Note that query_sql() runs on the main database while query_logsql() runs -on the log database. - -Example: - .@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]+")"); - ---------------------------------------- - -*escape_sql(<value>) - -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: - .@str$ = "John's Laptop"; - .@esc_str$ = escape_sql(.@name$); // Escaped string: John\'s Laptop - ---------------------------------------- - -*setiteminfo(<item id>, <type>, <value>) - -This function will set some value of an item. -Returns the new value on success, or -1 on fail (item_id not found or -invalid type). - -Valid types are: - 0 - Buy Price; 1 - Sell Price; 2 - Item Type; - 3 - maxchance (Max drop chance of this item e.g. 1 = 0.01% , etc.. - if = 0, then monsters don't drop it at all (rare or a quest item) - if = 10000, then this item is sold in NPC shops only - 4 - sex; 5 - equip; 6 - weight; 7 - atk; 8 - def; 9 - range; - 10 - slot; 11 - look; 12 - elv; 13 - wlv; 14 - view id - -Example: - -setiteminfo Stone, 6, 9990; // Stone now weighs 999.0 - ---------------------------------------- - -*setitemscript(<item id>, <"{ new item script }">{, <type>}) - -Set a new script bonus to the Item. Very useful for game events. -You can remove an item's itemscript by leaving the itemscript argument -empty. Returns 1 on success, or 0 on fail (item_id not found or new item -script is invalid). -Type can optionally be used indicates which script to set (default is 0): - 0 - Script - 1 - OnEquip_Script - 2 - OnUnequip_Script - -Example: - -setitemscript(Silver_Ring_, "{ if (isequipped(Santa's_Hat) == 0) end; if (getskilllv(AL_TELEPORT)) { skill(MC_IDENTIFY, 1); } else { skill(AL_TELEPORT, 1+isequipped(Santa's_Hat)); } }"); -setitemscript(Silver_Ring_, ""); - ---------------------------------------- - -*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). strtol() lets -the user specify a base (valid range is between 2 and 36 inclusive, -or the special value0, which means auto-detection). - -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: - -.@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) - ---------------------------------------- - -*compare("<string>", "<substring>") - -This command returns true when the substring is in the main string or -false otherwise. This command is not case sensitive. - -Examples: - -//dothis(); will be executed ('Bloody Murderer' contains 'Blood'). - if (compare("Bloody Murderer", "Blood")) - dothis(); -//dothat(); will not be executed ('Blood butterfly' does not contain 'Bloody'). - if (compare("Blood Butterfly", "Bloody")) - dothat(); - ---------------------------------------- - -*strcmp("<string>", "<string>") - -This command compares two strings and is similar to strcmp in C. - -Return Values: - >0 : String 1 > String 2 - 0 : Strings are equal - <0 : String 1 < String 2 - -Examples: - .@a = strcmp("abcdef", "ABCDEF"); - if (.@a > 0){ - mes(".@a is greater than 0."); //Output is this. - } else { - mes(".@a is less or equal to 0"); - } - ---------------------------------------- - -*getstrlen("<string>") - -This function will return the length of the string given as an argument. -It is useful to check if anything input by the player exceeds name length -limits and other length limits and asking them to try to input something -else. - ---------------------------------------- - -*isstr(<argument>) - -This command checks if the given <argument> is a string (1), -an integer (0) or something else (2). - -Example: - - isstr(69); // outputs 0 - isstr("69"); // outputs 1 - ---------------------------------------- - -*charisalpha("<string>", <position>) - -This function will return true if the character number Position in the given -string is a letter, false if it isn't a letter but a digit or a space. -The first letter is position 0. - ---------------------------------------- - -*charat(<string>, <index>) - -Returns char at specified index. If index is out of range, returns an -empty string. - -Example: - - charat("This is a string", 10); //returns "s" - ---------------------------------------- - -*chr(<int>) - -Returns a char from its ASCII value. - -Example: - - chr(99); //returns "c" - ---------------------------------------- - -*ord(<chr>) - -Returns the ASCII value of char <chr>. - -Example: - - ord("c"); //returns 99 - ---------------------------------------- - -*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>) -*strtolower(<string>) - -Returns the specified string in it's uppercase/lowercase form. -All non-alpha characters will be preserved. - -Example: - - strtoupper("The duck is blue!!"); //returns "THE DUCK IS BLUE!!" - ---------------------------------------- - -*charisupper(<string>, <index>) -*charislower(<string>, <index>) - -Returns true if character at specified index of specified string is -uppercase for charisupper() or lowercase for charislower(). Otherwise, false. -Characters not of the alphabelt will return false. - -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>) - -Breaks a string up into substrings based on the specified delimiter. -Substrings will be stored within the specified string array. Only the 1st -char of the delimiter parameter will be used. If an empty string is passed -as a delimiter, the string will be placed in the array in its original -form, without any changes. Return the number of elements written to -<dest_array>. - -Example: - - .@num_elements = explode(.@my_array$, "Explode:Test:1965:red:PIE", ":"); - //.@my_array$ contents will be... - //.@my_array$[0]: "Explode" - //.@my_array$[1]: "Test" - //.@my_array$[2]: "1965" - //.@my_array$[3]: "red" - //.@my_array$[4]: "PIE" - //.@num_elements: 5 - ---------------------------------------- - -*implode(<string_array>{, <glue>}) - -Combines all substrings within the specified string array into a single -string. If the glue parameter is specified, it will be inserted inbetween -each substring. - -Example: - setarray(.@my_array$[0], "This", "is", "a", "test"); - implode(.@my_array$, " "); //returns "This is a test" - ---------------------------------------- - -*sprintf(<format>{, param{, param{, ...}}}) - -C style sprintf. The resulting string is returned. - -The format string can contain placeholders (format specifiers) using the -following structure: - - %[parameter][flags][width]type - -The following format specifier types are supported: - -%%: Prints a literal '%' (special case, doesn't support parameter, flag, width) -%d, %i: Formats the specified value as a decimal signed number -%u: Formats the specified value as a decimal unsigned number -%x: Formats the specified value as a hexadecimal (lowercase) unsigned number -%X: Formats the specified value as a hexadecimal (uppercase) unsigned number -%o: Formats the specified value as an octal unsigned number -%s: Formats the specified value as a string -%c: Formats the specified value as a character (only uses the first character - of strings) - -The following format specifier types are not supported: - -%n (not implemented due to safety concerns) -%f, %F, %e, %E, %g, %G (the script engine doesn't use floating point values) -%p (the script engine doesn't use pointers) -%a, %A (not supported, use 0x%x and 0x%X respectively instead) - -An ordinal parameter can be specified in the form 'x$' (where x is a number), -to reorder the output (this may be useful in translated strings, where the -sentence order may be different from the original order). Example: - - // Name, level, job name - mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); - -When translating the sentence to other languages (for example Italian), -swapping some arguments may be appropriate, and it may be desirable to keep the -actual arguments in the same order (i.e. when translating through the HULD): - - // Job name is printed before the level, although they're specified in the opposite order. - // Name, job name, level - mes(sprintf("Ciao, io sono %1$s, un %3$s di livello %2$d", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); - -The supported format specifier flags are: - -- (minus): Left-align the output of this format specifier. (the default is to - right-align the output). -+ (plus): Prepends a plus for positive signed-numeric types. positive = '+', - negative = '-'. -(space): Prepends a space for positive signed-numeric types. positive = ' ', - negative = '-'. This flag is ignored if the '+' flag exists. -0 (zero): When a field width option is specified, prepends zeros for numeric - types. (the default prepends spaces). -A field width can be specified. - - mes(sprintf("The temperature is %+d degrees Celsius", .@temperature)); // Keeps the '+' sign in front of positive values - .@map_name$ = sprintf("quiz_%02d", .@i); // Keeps the leading 0 in "quiz_00", etc - -A field width may be specified, to ensure that 'at least' that many characters -are printed. If a star ('*') is specified as width, then the width is read as -argument to the sprintf() function. This also supports positional arguments. - - sprintf("%04d", 10) // Returns "0010" - sprintf("%0*d", 5, 10) // Returns "00010" - sprintf("%5d", 10) // Returns " 10" - sprintf("%-5d", 10) // Returns "10 " - sprintf("%10s", "Hello") // Returns " Hello"; - sprintf("%-10s", "Hello") // Returns "Hello "; - -Precision ('.X') and length ('hh', 'h', 'l', 'll', 'L', 'z', 'j', 't') -specifiers are not implemented (not necessary for the script engine purposes) - -Example: - .@format$ = "The %s contains %d monkeys"; - dispbottom(sprintf(.@format$, "zoo", 5)); - //prints "The zoo contains 5 monkeys" - - dispbottom(sprintf(.@format$, "barrel", 82)); - //prints "The barrel contains 82 monkeys" - ---------------------------------------- - -*sscanf(<string>, <format>{, param{, param{, ...}}}) - -C style sscanf. All C format specifiers are supported. -More info: sscanf @ www.cplusplus.com. The number of params is only -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>}) - -PHP style strpos. Finds a substring (needle) within a string (haystack). -The offset parameter indicates the index of the string to start searching. -Returns index of substring on successful search, else -1. -Comparison is case sensitive. - -Example: - strpos("foobar", "bar", 0); //returns 3 - strpos("foobarfoo", "foo", 0); //returns 0 - strpos("foobarfoo", "foo", 1); //returns 6 - ---------------------------------------- - -*replacestr(<input>, <search>, <replace>{, <usecase>{, <count>}}) - -Replaces all instances of a search string in the input with the specified -replacement string. By default is case sensitive unless <usecase> is set -to false. If specified it will only replace as many instances as specified -in the count parameter. - -Example: - replacestr("testing tester", "test", "dash"); //returns "dashing dasher" - replacestr("Donkey", "don", "mon", false); //returns "monkey" - replacestr("test test test test test", "test", "yay", false, 3); //returns "yay yay yay test test" - ---------------------------------------- - -*countstr(<input>, <search>{, <usecase>}) - -Counts all instances of a search string in the input. By default is case -sensitive unless <usecase> is set to false. - -Example: - countstr("test test test Test", "test"); //returns 3 - countstr("cake Cake", "Cake", false); //returns 2 - ---------------------------------------- - -*setfont(<font>) - -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 - ---------------------------------------- - -*showdigit(<value>{, <type>}) - -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. - -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 -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); - - // counter that starts at 60 and runs for 60 seconds - showdigit(60, 3); - ---------------------------------------- - -* The Pet AI commands - -These commands will only work if the invoking character has a pet, and are -meant to be executed from pet scripts. They will modify the pet AI -decision-making for the current pet of the invoking character, and will -NOT have any independent effect by themselves, which is why only one of -them each may be in effect at any time for a specific pet. A pet may -have petloot(), petskillbonus(), petskillattack() and petskillsupport() at the -same time. - -*petskillbonus(<bonus type>, <value>, <duration>, <delay>) - -This command will make the pet give a bonus to the owner's stat (bonus -type - bInt, bVit, bDex, bAgi, bLuk, bStr, bSpeedRate - for a full list, see the -values starting with 'b' in 'db/constants.conf'). - -*petrecovery(<status type>, <delay>) - -This command will make the pet cure a specified status condition. The -curing actions will occur once every <delay> seconds. For a full list of -status conditions that can be cured, see the list of 'SC_' status -condition constants in 'db/constants.conf' - -*petloot(<max items>) - -This command will turn on pet looting, with a maximum number of items to -loot specified. Pet will store items and return them when the maximum is -reached or when pet performance is activated. - -*petskillsupport(<skill id>, <skill level>, <delay>, <percent hp>, <percent sp>) -*petskillsupport("<skill name>", <skill level>, <delay>, <percent hp>, <percent sp>) - -This will make the pet use a specified support skill on the owner whenever -the HP and SP are below the given percent values, with a specified delay -time between activations. The skill numbers are as per -'db/(pre-)re/skill_db.txt'. -It's not quite certain who's stats will be used for the skills cast, the -character's or the pets. Probably, Skotlex can answer that question. - -*petskillattack(<skill id>, <damage>, <number of attacks>, <rate>, <bonusrate>) -*petskillattack("<skill name>", <damage>, <number of attacks>, <rate>, <bonusrate>) - -This command will make the pet cast an attack skill on the enemy the pet's -owner is currently fighting. Skill IDs and levels are as per petskillsupport(). -If <number of attacks> is specified different than 0, it will make the pet cast -the skill with a fixed amount of damage inflicted and the specified number of -attacks. A value of zero uses the skill's defaults. - -All commands with delays and durations will only make the behavior active -for the specified duration of seconds, with a delay of the specified -number of seconds between activations. Rates are a chance of the effect -occurring and are given in percent. 'bonusrate' is added to the normal -rate if the pet intimacy is at the maximum possible. - -The behavior modified with the above mentioned commands will only be -exhibited if the pet is loyal and appropriate configuration options are -set in 'conf/map/battle.conf'. - -Pet scripts in the database normally run whenever a pet of that type -hatches from the egg. Other commands usable in item scripts (see bonus()) -will also happily run from pet scripts. Apparently, the pet-specific -commands will also work in NPC scripts and modify the behavior of the -current pet up until the pet is hatched again. (Which will also occur when -the character is logged in again with the pet still out of the egg.) It is -not certain for how long the effect of such command running from an NPC -script will eventually persist, but apparently, it is possible to usefully -employ them in usable item scripts to create pet buffing items. - -Nobody tried this before, so you're essentially on your own here. - ---------------------------------------- - -*bpet() - -This command opens up a pet hatching window on the client connected to the -invoking character. It is used in item script for the pet incubators and -will let the player hatch an owned egg. If the character has no eggs, it -will just open up an empty incubator window. -This is still usable outside item scripts. - ---------------------------------------- - -*makepet(<pet id>) - -This command will create a pet egg and put it in the invoking character's -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(PORING); - -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 -the char server and the egg will disappear when anyone tries to hatch it. - ---------------------------------------- - -*homshuffle() - -This will recalculate the homunculus stats according to its level, of the -current invoking character. - ---------------------------------------- - -*setcell("<map name>", <x1>, <y1>, <x2>, <y2>, <type>, <flag>) - -Each map cell has several 'flags' that specify the properties of that cell. -These include terrain properties (walkability, shootability, presence of -water), skills (basilica, land protector, ...) and other (NPC nearby, no -vending, ...). -Each of these can be 'on' or 'off'. Together they define a cell's behavior. - -This command lets you alter these flags for all map cells in the specified -(x1,y1)-(x2,y2) rectangle. -'type' defines which flag to modify. Possible options include cell_walkable, -cell_shootable, cell_basilica. For a full list, see constants.conf. -'flag' can be false (clear flat) or true (set flag). - -Example: - - setcell("arena", 0, 0, 300, 300, cell_basilica, true); - setcell("arena", 140, 140, 160, 160, cell_basilica, false); - setcell("arena", 135, 135, 165, 165, cell_walkable, false); - setcell("arena", 140, 140, 160, 160, cell_walkable, true); - -This will add a makeshift ring into the center of the map. The ring will -be surrounded by a 5-cell wide 'gap' to prevent interference from outside, -and the rest of the map will be marked as 'basilica', preventing observers -from casting any offensive skills or fighting among themselves. Note that -the wall will not be shown nor known client-side, which may cause movement -problems. - -Another example: - -OnBarricadeDeploy: - setcell("schg_cas05", 114, 51, 125, 51, cell_walkable, false); - end; -OnBarricadeBreak: - setcell("schg_cas05", 114, 51, 125, 51, cell_walkable, true); - end; - -This could be a part of the WoE:SE script, where attackers are not allowed -to proceed until all barricades are destroyed. This script would place and -remove a nonwalkable row of cells after the barricade mobs. - ---------------------------------------- - -*checkcell("<map name>", <x>, <y>, <type>) - -This command will return true or false, depending on whether the specified cell -has the 'type' flag set or not. There are various types to check, all -mimicking the server's cell_chk enumeration. The types can be found in -db/constants.conf. - -The meaning of the individual types can be confusing, so here's an -overview: - - cell_chkwall/water/cliff - these check directly for the 'terrain component' of the specified cell - - cell_chkpass/reach/nopass/noreach - passable = not wall & not cliff, reachable = passable - wrt. no-stacking mod - - cell_chknpc/basilica/landprotector/novending/nochat - these check for specific dynamic flags (name indicates what they do) - -Example: - - mes("Pick a destination map."); - input(.@map$); - mes("Alright, now give me the coordinates."); - input(.@x); - input(.@y); - if (!checkcell(.@map$, .@x, .@y, cell_chkpass)) { - mes("Can't warp you there, sorry!"); - close(); - } else { - mes("Ok, get ready..."); - close2(); - warp(.@map$, .@x, .@y); - end; - } - ---------------------------------------- - -*setwall("<map name>", <x>, <y>, <size>, <dir>, <shootable>, "<name>") -*delwall("<name>") - -Creates an invisible wall, an array of setcell() starting from x,y and -doing a line of the given size in the given direction. The difference with -setcell is this one update client part too to avoid the glitch problem. -Directions are the same as NPC sprite facing directions: (DIR_ constants). - ---------------------------------------- - -*readbook(<book id>, <page>) - -This will open a book item at the specified page. - ---------------------------------------- -//===================================== -7 - Instance-Related Commands -//===================================== ---------------------------------------- - -*instance_create("<instance name>", <owner id>{, <optional owner_type>}) - -Create an instance using the name "<instance name>" for the <owner_id> of -owner_type (when not provided, defaults to IOT_PARTY). Most instance_* -commands are used in conjunction with this command and depend on the -ID this command returns. - -Example: - // Store the Party ID of the invoking character. - .@party_id = getcharid(CHAR_ID_PARTY); - - // Attempt to create an instance using that 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 == -3) { // No free instances (MAX_INSTANCE exceeded) - // ... - } else if (.@id == -4) { // Already exists - // ... - } else (.@id < 0) { // Unspecified error while queuing instance. - // ... - } - ---------------------------------------- - -*instance_destroy({<instance id>}) - -Destroys instance with the ID <instance id>. If no ID is specified, the -instance the script is attached to is used. If in the end no instance_id, -is found the command halts the script execution. - ---------------------------------------- - -*instance_attachmap("<map name>", <instance id>{, <use base name>{, "<new map name>"}}) - -Attaches the map "<map name>" to the instance specified with -<instance id>. The optional parameter specifies, whether a map requires -emulation for instancing (true) or not (false = default). if use base name is specified, -and "<new map name>" too the server will instance the map under the "<new map name>", -name. - -Returns the resulting map name on success or an empty string on failure. - -Example: - instance_attachmap("prontera", .@instance_id, true, "via"); -^ the above creates a instance (or clone) of prontera, on a map called "via" - ---------------------------------------- - -*instance_detachmap("<map name>"{, <instance id>}) - -Detach the map "<map name>" to the instance with the <instance id>. If no -ID is specified, the instance the script is attached to is used. If in the -end no instance_id is found the command halts the script execution. - ---------------------------------------- - -*instance_init(<instance id>) - -Initializes the instance given by <instance id>. This copies all NPCs from -the source maps to the instanced maps. - ---------------------------------------- - -*instance_announce(<instance id>, "<text>", <flag>{, <fontColor>{, <fontType>{, <fontSize>{, <fontAlign>{, <fontY>}}}}}) - -Works like announce, but has the <instance id> parameter. If instance id -is -1, the instance the script is attached to is used. If in the -end no instance_id is found the command halts the script execution. - ---------------------------------------- - -*instance_attach(<instance id>) - -Attaches the current script to the instance given by <instance id>. - ---------------------------------------- - -*instance_npcname("<npc name>"{, <instance id>}) - -Retrieves the unique name given to a copy of an NPC given by "<npc name>" -in an instance specified <instance id>. If no ID is specified, the -instance the script is attached to is used. If in the end no instance_id, -is found the command halts the script execution. - ---------------------------------------- - -*has_instance("<map name>"{, <instance id>}) - -Checks whether or not the given map belongs to specified instance. If no -ID is specified, the instance the script is attached to is used. If the -script is not attached to an instance, it'll try to check whether the, -player attached to the script possesses an instance with a map matching -"<map name>". If in the end no instance_id is found the command halts the, -script execution. - -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. - ---------------------------------------- - -*instance_warpall("<map name>", <x>, <y>{, <instance id>}) - -Warps all players in the instance <instance id> to <map name> at given -coordinates. If no ID is specified, the instance the script is attached to -is used. If in the end no instance_id is found the command halts the, -script execution. - ---------------------------------------- - -*instance_set_timeout(<alive timeout>, <idle timeout>{, <instance id>}) - -Sets the timeout values for an instance given by <instance id>. If no ID -is specified, the instance the script is attached to is used. If in the end, -no instance_id is found the command halts the script execution. - -Parameter <alive timeout> specifies the total amount of time the instance -will exist. Parameter <idle timeout> specifies how long players have, when -they are outside of the instance, until it is destroyed. - -Both timeout values are in seconds. - ---------------------------------------- - -*instance_check_party(<party id>{, <amount>{, <min>{, <max>}}}) - -This function checks if a party meets certain requirements, returning true if -all conditions are met and false otherwise. It will only check online -characters. - -amount - number of online party members (default is 1). -min - minimum level of all characters in the party (default is 1). -max - maximum level of all characters in the party (default is max - level in conf). - -Example: - -if (instance_check_party(getcharid(CHAR_ID_PARTY), 2, 2, 149)) { - mes("Your party meets the Memorial Dungeon requirements."); - mes("All online members are between levels 1-150 and at least two are online."); - close(); -} else { - mes("Sorry, your party does not meet the requirements."); - close(); -} - ---------------------------------------- - -*instance_check_guild(<guild_id>{, <amount>{, <min>{, <max>}}}) - -This function checks if a guild meets certain requirements, returning true if -all conditions are met and false otherwise. it will only check online characters. - -amount - number of online guild members (default is 1). -min - minimum level of all characters in the guild (default is 1). -max - maximum level of all characters in the guild (default is max level in conf). - -Example: - if (instance_check_guild(getcharid(CHAR_ID_GUILD), 2, 1, 150)) { - mes("Your guild meets the Memorial Dungeon requirements."); - mes("All online members are between levels 1-150 and at least two are online."); - close(); - } else { - mes("Sorry, your guild does not meet the requirements."); - close(); - } - ---------------------------------------- -*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 questprogress() and showevent(). Use this only -in an OnInit label. For the Quest ID, specify the quest ID that you want -checked if it has been started yet. - -For Icon, use one of the following: - -No Icon : QTYPE_NONE -! Quest Icon : QTYPE_QUEST -? Quest Icon : QTYPE_QUEST2 -! Job Icon : QTYPE_JOB -? Job Icon : QTYPE_JOB2 -! Event Icon : QTYPE_EVENT -? Event Icon : QTYPE_EVENT2 -Warg : QTYPE_WARG -Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410) - -Map Mark Color, when used, creates a mark in the user's mini map on the position of the NPC, -the available color values are: - -0 - No Marker -1 - Yellow Marker -2 - Green Marker -3 - Purple Marker - -When a user shows up on a map, each NPC is checked for questinfo that has been set. -If questinfo is present, it will check if the quest has been started, if it has not, the bubble will appear. - -Optionally, you can also specify a Job Class if the quest bubble should only appear for a certain class. - -Example - izlude,100,100,4 script Test 844,{ - mes("[Test]"); - mes("Hello World."); - close(); - - OnInit: - questinfo(1001, QTYPE_QUEST, 0, Job_Novice); - end; - } - ---------------------------------------- - -*setquest(<ID>) - -Place quest of <ID> in the users quest log, the state of which is "active". - -If questinfo() is set, and the same ID is specified here, the icon will be cleared when the quest is set. - ---------------------------------------- - -*completequest(<ID>{, <ID2>}) - -Change the state for the given quest <ID> to "complete" and remove from -the users quest log. - -If a second quest id of greater value is specified, all quests between the two -will be completed. - ---------------------------------------- - -*erasequest(<ID>{, <ID2>}) - -Remove the quest of the given <ID> from the user's quest log. - -If a second quest id of greater value is specified, all quests between the two -will be erased. - ---------------------------------------- - -*changequest(<ID>, <ID2>) - -Remove quest of the given <ID> from the user's quest log. -Add quest of the <ID2> to the the quest log, and the state is "active". - ---------------------------------------- - -*questprogress(<ID>{, PLAYTIME|HUNTING}) - -If no additional argument supplied, return the state of the quest: - 0 = Quest not started (not in quest log) - 1 = Quest has been given - 2 = Quest completed - -If parameter PLAYTIME is supplied: - 0 = Quest not started (not in quest log) - 1 = The time limit has not yet been reached - 2 = The time limit has been reached - -If parameter HUNTING is supplied: - 0 = Quest not started (not in quest log) - 1 = Player hasn't killed all of the target monsters - 2 = Player has killed all of the target monsters - ---------------------------------------- - -*questactive(<ID>) - -Check whether the given quest is in its active state. - -Returns true if the quest is active, false otherwise (quest not started, -inactive or completed) - ---------------------------------------- - -*showevent(<icon>{, <mark color>}) - -Show an emotion on top of a NPC, and optionally, -a colored mark in the mini-map like viewpoint(). -This is used to indicate that a NPC has a quest or an event to -a certain player. - -Available Icons: - -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 - ---------------------------------------- -//===================================== -8 - End of Quest Log-Related Commands -//===================================== ---------------------------------------- - - ---------------------------------------- -//===================================== -9 - Battlegrounds-Related Commands -//===================================== ---------------------------------------- - -*waitingroom2bg_single(<battle group>, "<mapname>", <x>, <y>, "<npc name>") - -Adds the first waiting player from the chat room of given NPC to an -existing battleground group and warps it to specified coordinates on given -map. - ---------------------------------------- - -*waitingroom2bg("<mapname>", <x>, <y>, "<On Quit Event>", "<On Death Event>"{, "<npc name>"}) - -<Mapname> and X Y coordinates refer to where the "respawn" base is, where -the player group will respawn when they die. -<On Quit Event> refers to an NPC label that attaches to the character and -is run when they relog. -<On Death Event> refers to an NPC label that attaches to the character and -is run when they die. Can be "" for empty. - -Unlike the prior command, the latter will attach a GROUP in a waiting room -to the battleground, and sets the array $@arenamembers[0] where 0 holds -the IDs of the first group, and 1 holds the IDs of the second. - -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. - $@KvM01BG_id1 = waitingroom2bg("bat_c01", 52, 129, "KvM01_BG::OnGuillaumeQuit", "KvM01_BG::OnGuillaumeDie"); - end; - ----------------------------------------- - -*bg_team_setxy(<Battle Group ID>, <x>, <y>) - -Update the respawn point of the given battle group to x, y on the same -map. The <Battle Group ID> can be retrieved using getcharid(CHAR_ID_BG). - -Example: - bg_team_setxy(getcharid(CHAR_ID_BG), 56, 212); - mapannounce("bat_a01", "Group [1] has taken the work shop, and will now respawn there.", bc_map, 0xFFCE00); - end; - ----------------------------------------- - -*bg_warp(<Battle Group>, "<Mapname>", <x>, <y>) - -Similar to warp command. -Place all members of <Battle Group> at <mapname> at x y. - -Example: - //place the battle group one for Tierra Gorge at starting position. - bg_warp($@TierraBG1_id1, "bat_a01", 352, 342); - end; - ----------------------------------------- - -*bg_monster(<Battle Group>, "<map name>", <x>, <y>, "<name to show>", <mob id>, "<event label>") - -Similar to monster() script command. -Spawn a monster with allegiance to the given battle group. -Does not allow for the summoning of multiple monsters. -Monsters are similar to that in War of Emperium, in that the specified -Battle group is considered friendly. - -Example: - // It can be used in two different ways. - 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. - $@Guardian_3 = bg_monster($@TierraBG1_id2, "bat_a01", 268, 204, "Guardian", B_S_GUARDIAN, "NPCNAME::OnMyMobDead"); - end; - ----------------------------------------- - -*bg_monster_set_team(<GID>, <Battle Group>) - -This command will change the allegiance if a monster in a battle ground. -GID can be set when spawning the monster via the bg_monster() command. - -Example: - -OnEnable: - mapannounce("bat_b01", "A guardian has been summoned for Battle Group 2!", bc_map, 0xFFCE00); - $@Guardian = bg_monster($@BG_2, "bat_a01", 268, 204, "Guardian", B_S_GUARDIAN, "NPCNAME::OnMyMobDead"); - initnpctimer(); - end; - -OnTimer1000: - stopnpctimer(); - mapannounce("bat_b01", "Erm, sorry about that! This monster was meant for Battle Group 1.", bc_map, 0xFFCE00); - bg_monster_set_team($@Guardian, $@BG_1); - end; - ----------------------------------------- - -*bg_leave() - -Removes attached player from their Battle Group. - ----------------------------------------- - -*bg_destroy(<Batte Group>) - -As the name says, destroys the battle group created for that battle ground. - ----------------------------------------- - -*areapercentheal("<mapname>", <x1>, <y1>, <x2>, <y2>, <hp>, <sp>) - -Not exactly limited to battleground use, this will restore HP/SP in a -defined area at a percentage. - -Example: - areapercentheal("bat_a01", 52, 208, 61, 217, 100, 100); - end; - ----------------------------------------- - -*bg_get_data(<Battle Group>, <type>) - -Retrieves data related to given battle group. Type can be one of the -following: - - 0 - Amount of players currently belonging to the group. - ----------------------------------------- - -*bg_getareausers(<battle group>, "<map_name>", <x0>, <y0>, <x1>, <y1>) - -Retrieves amount of players belonging to given battle group on given map -within an specified rectangular area. - ----------------------------------------- - -*bg_updatescore("<map_name>", <Guillaume Score>, <Croix Score>) - -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%<map_name>%TAB%battleground%TAB%2 - ----------------------------------------- - -*bg_create_team("<map_name>", <Respawn X>, <Respawn Y>) - -This command will create a new BG Team. -When player dies, they will be respawned map_name,X,Y as mentioned. - -Command will return -1 if BG Creation is failed, -else it will return the BG ID(Also known as TeamID). - ----------------------------------------- - -*bg_join_team(<Team_ID>{, <account_id>}) - -This command will make the attached player join to Team with ID as mentioned. -If account_id is provided, command will look for that player, instead of the attached player. - -Command will return -1 if Player is not found, 0 if join is failed, 1 upon successful. - ----------------------------------------- - -*bg_match_over("<Arena Name>"{, <Cancelled>}) - -This command will end the battleground Arena -(Arena Name as referred to, in conf/battlegrounds.conf) -If Cancelled is not provided, it will set the join delay, as mentioned in conf/battlegrounds.conf -else, it will just destroy the Teams and queue's. - -Command will return 0 when successful, else it will return 1. - ---------------------------------------- -//===================================== -9 - End of Battlegrounds-Related Commands -//===================================== ---------------------------------------- - - ---------------------------------------- -//===================================== -10 - Mercenary Commands -//===================================== ---------------------------------------- - -*mercenary_create(<class>, <contract time>) - -This command summons a mercenary of given class, for given amount of time -in milliseconds. Typically used in item scripts of mercenary scrolls. - ----------------------------------------- - -*mercenary_heal(<hp>, <sp>) - -This command works like heal(), but affects the mercenary of the currently -attached character. - ----------------------------------------- - -*mercenary_sc_start(<type>, <tick>, <val1>) - -This command works like sc_start(), but affects the mercenary of the -currently attached character. - ----------------------------------------- - -*mercenary_get_calls(<guild>) -*mercenary_set_calls(<guild>, <value>) - -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 - ----------------------------------------- - -*mercenary_get_faith(<guild>) -*mercenary_set_faith(<guild>, <value>) - -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 - ---------------------------------------- - -*getmercinfo(<type>{, <char id>}) - -Retrieves information about mercenary of the currently attached character. -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 - -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-Related Commands -//===================================== ---------------------------------------- - -*queue() - -Creates a new queue instance and returns the created queue id. - ---------------------------------------- - -*queuesize(<queue_id>) - -Returns the amount of entries in the queue instance of <queue_id>. - ---------------------------------------- - -*queueadd(<queue_id>, <var_id>) - -Adds <var_id> to queue of <queue_id>. - -Returns false if <var_id> couldn't be added (was already present in the queue), -true otherwise. - ---------------------------------------- - -*queueremove(<queue_id>, <var_id>) - -Removes <var_id> from queue of <queue_id>. - -Returns false if <var_id> couldn't be removed (wasn't present in the queue), -true otherwise. - ---------------------------------------- - -*queueopt(<queue_id>, <optionType>, {Optional <option val>}) - -Modifies <queue_id>'s <optionType>. When <option val> is not present -<optionType> is removed from <queue_id>. When present it modifies -<queue_id>'s <optionType> with the new <option val> value. - -Returns true on success, false on failure. - -Currently 3 options are available: -- QUEUEOPT_DEATH (1) -- QUEUEOPT_LOGOUT (2) -- QUEUEOPT_MAPCHANGE (3) - -When the QUEUEOPT_MAPCHANGE event is triggered, it sets a temp char var -@Queue_Destination_Map$ with the destination map name. - -Example: - queueopt(.@queue_id, QUEUEOPT_DEATH, "MyNPC::OnQueueMemberDeathEvent"); - ---------------------------------------- - -*queuedel(<queue_id>) - -Deletes the queue <queue_id>. - -Returns false if the queue wasn't found, true otherwise. - ---------------------------------------- - -*queueiterator(<queue_id>) - -Creates a new queue iterator instance. -A queue iterator is not a reference to a queue's actual members, it copies -the queues members when initialized, this way you can loop through them -even if you remove them from the queue. - ---------------------------------------- - -*qicheck(<queue_iterator_id>) - -Checks whether the current member in the iterator's queue exists. - -Returns true when it does, false otherwise. - ---------------------------------------- - -*qiget(<queue_iterator_id>) - -obtains the next member in the iterator's queue, returns the next member's -id or 0 when it doesnt exist. - -Example: - for (.@elem = qiget(.@queue_iterator_id); qicheck(.@queue_iterator_id); .@elem = qiget(.@queue_iterator_id)) { - //Do something - } - ---------------------------------------- - -*qiclear(<queue_iterator_id>) - -Deletes a queue iterator from memory. - -Returns false when it fails, otherwise true 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). - ---------------------------------------- - -*setunitdata(<GUID>, <DataType>, <Val1> {,<Val2>,<Val3>}) - -Sets or alters the data in real-time for game objects of the following types - -NPCs, Pets, Monsters, Homunuculus', Mercenaries, Elementals. - -Applicable Data Types (available as constants) - - Data Types Description (parameter type) - UDT_SIZE: Unit Size (int) - UDT_LEVEL: Level (int) - UDT_HP: Current HP (int) - UDT_MAXHP: Max HP (int) - UDT_SP: SP (int) - UDT_MAXSP: MAX SP (int) - UDT_MASTERAID: Master Account ID (for Summons) (int) - UDT_MASTERCID: Master Char ID (for Summons) (int) - UDT_MAPIDXY: Warp a Unit to a map. (Val1 = (string) MapName, Val2 = (int) x, Val3 = (int) y) - UDT_WALKTOXY: Make a unit walk to certain co-ordinates. (Val1 = (int) x, Val2 = (int) y) - UDT_SPEED: Unit Speed. (int) - UDT_MODE: Mode (Mobs only) (int) - UDT_AI: Unit AI Type (see constants.conf for Unit AI Types) - UDT_SCOPTION: Status Options. (see constants.conf for Unit Option Types) - UDT_SEX: Gender of the unit. (see constants.conf for Genders) - UDT_CLASS: Class of the unit. (Monster ID) (int) - UDT_HAIRSTYLE: Hair Style ID. (int) - UDT_HAIRCOLOR: Hair Color ID. (int) - UDT_HEADBOTTOM: Headgear Bottom Sprite ID. (int) - UDT_HEADMIDDLE: Headgear Middle Sprite ID. (int) - UDT_HEADTOP: Headgear Top Sprite ID. (int) - UDT_CLOTHCOLOR: Cloth Color ID. (int) - UDT_SHIELD: Shield Sprite ID. (int) - UDT_WEAPON: Weapon Sprite ID. (int) - UDT_LOOKDIR: Face direction. (int) - UDT_CANMOVETICK: Stop a unit from move for n seconds. (int) - UDT_STR: Unit STR. (int) - UDT_AGI: Unit AGI. (int) - UDT_VIT: Unit VIT. (int) - UDT_INT: Unit INT. (int) - UDT_DEX: Unit DEX. (int) - UDT_LUK: Unit LUK. (int) - UDT_ATKRANGE: Attack range of a unit. (int) - UDT_ATKMIN: Min Atk of a unit. (int) - UDT_ATKMAX: Max Atk of a unit. (int) - UDT_MATKMIN: Min MATK of a unit. (int) - UDT_MATKMAX: Max MATK of a unit. (int) - UDT_DEF: DEF. (int) - UDT_MDEF: MDEF. (int) - UDT_HIT: HIT. (int) - UDT_FLEE: FLEE. (int) - UDT_PDODGE: Perfect Dodge. (int) - UDT_CRIT: Critical Rate. (int) - UDT_RACE: Race. (Eg. string constants RC_DemiHuman or Integer 7). - UDT_ELETYPE: Element. (Eg. string constants Ele_Neutral or Integer 0). - UDT_ELELEVEL: Element Level (int). - UDT_AMOTION: AMotion Rate (int). - UDT_ADELAY: ADelay Rate (int). - UDT_DMOTION: DMotion Rate (int). - UDT_HUNGER: Hunger Rate (int) - for summons. - UDT_INTIMACY: Intimacy Rate (int) - for summons. - UDT_LIFETIME: LifeTime (int) - for summons. - UDT_MERC_KILLCOUNT: Kill count for mercenaries (int). - UDT_STATADD: Status Points (int) - for NPCs. - -returns 0 if value could not be set, 1 if successful. - ---------------------------------------- - -*getunitdata (<GUID>,<DataType>{,<Variable>}) - -Retrieves real-time data of a game object. For data with multiple return values, -an array variable may be passed to store the data in. - -Applicable Data types (available as constants) - - Data Types Description (return type) - UDT_SIZE: Unit Size (int) - UDT_LEVEL: Level (int) - UDT_HP: Current HP (int) - UDT_MAXHP: Max HP (int) - UDT_SP: SP (int) - UDT_MAXSP: MAX SP (int) - UDT_MASTERAID: Master Account ID (for Summons) (int) - UDT_MASTERCID: Master Char ID (for Summons) (int) - UDT_MAPIDXY: Warp a Unit to a map. (Val1 = (string) MapName, Val2 = (int) x, Val3 = (int) y) - UDT_SPEED: Unit Speed. (int) - UDT_MODE: Mode (Mobs only) (int) - UDT_AI: Unit AI Type (see constants.conf for Unit AI Types) - UDT_SCOPTION: Status Options. (see constants.conf for Unit Option Types) - UDT_SEX: Gender of the unit. (see constants.conf for Genders) - UDT_CLASS: Class of the unit. (Monster ID) (int) - UDT_HAIRSTYLE: Hair Style ID. (int) - UDT_HAIRCOLOR: Hair Color ID. (int) - UDT_HEADBOTTOM: Headgear Bottom Sprite ID. (int) - UDT_HEADMIDDLE: Headgear Middle Sprite ID. (int) - UDT_HEADTOP: Headgear Top Sprite ID. (int) - UDT_CLOTHCOLOR: Cloth Color ID. (int) - UDT_SHIELD: Shield Sprite ID. (int) - UDT_WEAPON: Weapon Sprite ID. (int) - UDT_LOOKDIR: Face direction. (int) - UDT_CANMOVETICK: Stop a unit from move for n seconds. (int) - UDT_STR: Unit STR. (int) - UDT_AGI: Unit AGI. (int) - UDT_VIT: Unit VIT. (int) - UDT_INT: Unit INT. (int) - UDT_DEX: Unit DEX. (int) - UDT_LUK: Unit LUK. (int) - UDT_ATKRANGE: Attack range of a unit. (int) - UDT_ATKMIN: Min Atk of a unit. (int) - UDT_ATKMAX: Max Atk of a unit. (int) - UDT_MATKMIN: Min MATK of a unit. (int) - UDT_MATKMAX: Max MATK of a unit. (int) - UDT_DEF: DEF. (int) - UDT_MDEF: MDEF. (int) - UDT_HIT: HIT. (int) - UDT_FLEE: FLEE. (int) - UDT_PDODGE: Perfect Dodge. (int) - UDT_CRIT: Critical Rate. (int) - UDT_RACE: Race. (Eg. string constants RC_DemiHuman or Integer 7). - UDT_ELETYPE: Element. (Eg. string constants Ele_Neutral or Integer 0). - UDT_ELELEVEL: Element Level (int). - UDT_AMOTION: AMotion Rate (int). - UDT_ADELAY: ADelay Rate (int). - UDT_DMOTION: DMotion Rate (int). - UDT_HUNGER: Hunger Rate (int) - for summons. - UDT_INTIMACY: Intimacy Rate (int) - for summons. - UDT_LIFETIME: LifeTime (int) - for summons. - UDT_MERC_KILLCOUNT: Kill count for mercenaries (int). - -returns 0 if value could not be retrieved. - ---------------------------------------- - -*getunitname(<GID>) - -Retrieve the name of a unit. - -returns "Unknown" if the value could not be retrieved. - ---------------------------------------- - -*setunitname(<GID>, <Name>) - -Changes the name of a unit. - -Supported Types - [ MOB | HOM | PET ]. - -returns 1 on success, 0 on failure. |