· 8 years ago · Jan 29, 2018, 04:00 PM
1//===== rAthena Documentation================================
2//= rAthena Script Commands
3//===== By:==================================================
4//= rAthena Dev Team
5//===== Last Updated:========================================
6//= 20171011
7//===== Description:=========================================
8//= A reference manual for the rAthena scripting language.
9//= Commands are sorted depending on their functionality.
10//===========================================================
11
12This document is a reference manual for all the scripting commands and functions
13available in rAthena. It is not a simple tutorial. When people tell you to
14"Read The F***ing Manual", they mean this.
15
16This is not a place to teach you basic programming. This document will not teach
17you basic programming by itself. It's more of a reference for those who have at
18least a vague idea of what they want to do and want to know what tools they have
19available to do it. We've tried to keep it as simple as possible, but if you
20don't understand it, getting a clear book on programming in general will help
21better than yelling around the forum for help.
22
23A little learning never caused anyone's head to explode.
24
25Structure
26---------
27
28The script commands are listed in no particular order, but are grouped by
29relative function.
30
31*Name of the command and parameters (if any).
32
33Descriptive text
34
35 Small example if possible. Will usually be incomplete, it's there just to
36 give you an idea of how it works in practice.
37
38To find a specific command, use Ctrl+F, (or whatever keys call up a search
39function in whatever you're reading this with) put an asterisk (*) followed by the command
40name, and it should find the command description for you.
41
42If you find anything missing, please let us know!
43
44Syntax
45------
46
47Throughout this document, wherever a command wants an argument, it is given in
48<angle brackets>. This doesn't mean you should type the angle brackets. If an
49argument of a command is optional, it is given in {curly brackets}. You've
50doubtlessly seen this convention somewhere. If a command can optionally take
51an unspecified number of arguments, you'll see a list like this:
52
53command <argument>{,<argument>...<argument>}
54
55This still means they will want to be separated by commas.
56
57Where a command wants a string, it will be given in "quotes", if it's a number,
58it will be given without them. Normally, you can put an expression, like a bunch
59of functions or operators returning a value, in (round brackets) instead of most
60numbers. Round brackets will not always be required, but they're often a good
61idea.
62
63Wherever you refer to a map name, it's always 'map name' (.gat suffix is deprecated).
64
65
66Script loading structure
67------------------------
68
69Scripts are loaded by the map server as referenced in the 'conf/map_athena.conf'
70configuration file, but in the default configuration, it doesn't load any script
71files itself. Instead, it loads the file 'npc/(pre-)re/scripts_main.conf' which itself
72contains references to other files. The actual scripts are loaded from txt
73files, which are linked up like this:
74
75npc: <path to a filename>
76
77Any line like this, invoked, ultimately, by 'map_athena.conf' will load up the
78script contained in this file, which will make the script available. No file
79will get loaded twice to prevent possible errors.
80
81Another configuration file option of relevance is:
82
83delnpc: <path to a filename>
84
85This will unload a specified script filename from memory, which, while
86seemingly useless, may sometimes be required.
87
88Whenever '//' is encountered in a line upon reading, everything beyond this on
89that line is considered to be a comment and is ignored. This works wherever you
90place it.
91
92// This line will be ignored when processing the script.
93
94Block comments can also be used, where you can place /* and */ between any text you
95wish rAthena to ignore.
96
97Example:
98/* This text,
99 * no matter which new line you start
100 * is ignored, until the following
101 * symbol is encountered: */
102
103The asterisks (*) in front of each line is a personal preference and is not required.
104
105Upon loading all the files, the server will execute all the top-level commands
106in them. No variables exist yet at this point, no commands can be called other
107than those given in this section. These commands set up the basic structure - create
108NPC objects, spawn monster objects, set map flags, etc. No code is actually
109executed at this point. The top-level commands are pretty confusing, since
110they aren't structured like you would expect (command name first), but rather,
111normally start with a map name.
112
113What's more confusing about the top-level commands is that most of them use a
114tab symbol to divide their arguments.
115
116To prevent problems and confusion, the tab symbols are written as '%TAB%'
117throughout this document, even though this makes the text a bit less readable.
118Using an invisible symbol to denote arguments is one of the bad things about
119this language.
120
121Here is a list of valid top-level commands:
122
123** Set a map flag:
124
125<map name>%TAB%mapflag%TAB%<flag>
126
127This will, upon loading, set a specified map flag on a map you like. These are
128normally in files inside 'npc/mapflag' and are loaded first, so by the time the
129server's up, all the maps have the flags they should have. Map flags determine
130the behavior of the map in various situations. For more details, see 'setmapflag'
131and 'doc/mapflags.txt'.
132
133** Create a permanent monster spawn:
134
135<map name>,<x>,<y>{,<xs>{,<ys>}}%TAB%monster%TAB%<monster name>{,<monster level>}%TAB%<mob id>,<amount>{,<delay1>{,<delay2>{,<event>{,<mob size>{,<mob ai>}}}}}
136
137Map name is the name of the map the monsters will spawn on. x,y are the
138coordinates where the mob should spawn. If xs and ys are non-zero, they
139specify the 'radius' of a spawn-rectangle area centered at x,y.
140Putting zeros instead of these coordinates will spawn the monsters randomly.
141Note this is only the initial spawn zone, as mobs random-walk, they are free
142to move away from their specified spawn region.
143
144Monster name is the name the monsters will have on screen, and has no relation
145whatsoever to their names anywhere else. It's the mob id that counts, which
146identifies monster record in 'mob_db.txt' database of monsters. If the mob name
147is given as "--ja--", the 'japanese name' field from the monster database is
148used, (which, in rAthena, actually contains an English name) if it's "--en--",
149it's the 'english name' from the monster database (which contains an uppercase
150name used to summon the monster with a GM command).
151
152You can specify a custom level to use for the mob different from the one of
153the database by adjoining the level after the name with a comma. eg:
154"Poring,50" for a name will spawn a monster with name Poring and level 50.
155
156Amount is the amount of monsters that will be spawned when this command is
157executed, it is affected by spawn rates in 'battle_athena.conf'.
158
159Delay1 and delay2 control monster respawn delays - the first one is the fixed
160base respawn time, and the second is random variance on top of the base time.
161Both values are given in milliseconds (1000 = 1 second).
162Note that the server also enforces a minimum respawn delay of 5 seconds.
163
164Event is a script event to be executed when the mob is killed. The event must
165be in the form "NPCName::OnEventName" to execute, and the event name label
166should start with "On". As with all events, if the NPC is an on-touch NPC, the
167player who triggers the script must be within 'trigger' range for the event to
168work.
169
170There are two optional fields for monster size and AI.
171
172<mob size> can be:
173 Size_Small (0)
174 Size_Medium (1)
175 Size_Large (2)
176
177<mob ai> can be:
178 AI_NONE (0) (default)
179 AI_ATTACK (1) (attack/friendly)
180 AI_SPHERE (2) (Alchemist skill)
181 AI_FLORA (3) (Alchemist skill)
182 AI_ZANZOU (4) (Kagerou/Oboro skill)
183 AI_LEGION (5) (Sera skill)
184 AI_FAW (6) (Mechanic skill)
185
186Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able
187to be detected on the map with the SC_BOSSMAPINFO status (used by Convex Mirror).
188
189** NPC names
190
191/!\ WARNING: this applies to warps, NPCs, duplicates and shops /!\
192
193NPC names are kinda special and are formatted this way:
194
195<Display name>{::<Unique name>}
196
197All NPCs need to have a unique name that is used for identification purposes.
198When you have to identify a NPC by its name, you should use <Unique name>.
199If <Unique name> is not provided, use <Display name> instead.
200
201The client has a special feature when displaying names:
202if the display name contains a '#' character, it hides that part of the name.
203ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter'
204
205<Display name> must be at most 24 characters in length.
206<Unique name> must be at most 24 characters in length.
207
208** Define a warp point
209
210<from mapname>,<fromX>,<fromY>,<facing>%TAB%warp%TAB%<warp name>%TAB%<spanx>,<spany>,<to mapname>,<toX>,<toY>
211<from mapname>,<fromX>,<fromY>,<facing>%TAB%warp2%TAB%<warp name>%TAB%<spanx>,<spany>,<to mapname>,<toX>,<toY>
212
213This will define a warp NPC that will warp a player between maps, and while most
214arguments of that are obvious, some deserve special mention.
215
216SpanX and SpanY will make the warp sensitive to a character who didn't step
217directly on it, but walked into a zone which is centered on the warp from
218coordinates and is SpanX in each direction across the X axis and SpanY in each
219direction across the Y axis.
220
221Warp NPC objects also have a name, because you can use it to refer to them later
222with 'enablenpc'/'disablenpc'
223
224Facing of a warp object is irrelevant, it is not used in the code and all
225current scripts have a zero in there.
226
227Unlike 'warp', 'warp2' will also be triggered by hidden player.
228
229** Define an NPC object.
230
231<map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite id>,{<code>}
232<map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>,{<code>}
233
234This will place an NPC object on a specified map at the specified location, and
235is a top-level command you will use the most in your custom scripting. The NPCs
236are triggered by clicking on them, and/or by walking in their trigger area, if
237defined, see that below.
238
239Facing is a direction the NPC sprite will face in. Not all NPC sprites have
240different images depending on the direction you look from, so for some facing
241will be meaningless. Facings are counted counterclockwise in increments of 45
242degrees, where 0 means facing towards the top of the map. (So to turn the sprite
243towards the bottom of the map, you use facing 4, and to make it look southeast
244it's facing 5.)
245
246Sprite ID is the sprite number or constant used to display this particular NPC.
247You may also use a monster's ID instead to display a monster sprite for this NPC.
248It is possible to use a job sprite as well, but you must first define it as a
249monster sprite in 'mob_avail.txt', a full description on how to do this is not
250in the scope of this manual.
251A '-1' Sprite ID will make the NPC invisible (and unclickable).
252A '111' Sprite ID will make an NPC which does not have a sprite, but is still
253clickable, which is useful if you want to make a clickable object of the 3D
254terrain.
255
256TriggerX and triggerY, if given, will define an area, centered on NPC and
257spanning triggerX cells in every direction across X and triggerY in every
258direction across Y. Walking into that area will trigger the NPC. If no
259'OnTouch:' special label is present in the NPC code, the execution will start
260from the beginning of the script, otherwise, it will start from the 'OnTouch:'
261label. Monsters can also trigger the NPC, though the label 'OnTouchNPC:' is
262used in this case.
263
264The code part is the script code that will execute whenever the NPC is
265triggered. It may contain commands and function calls, descriptions of which
266compose most of this document. It has to be in curly brackets, unlike elsewhere
267where we use curly brackets, these do NOT signify an optional parameter.
268
269** Define a 'floating' NPC object.
270
271-%TAB%script%TAB%<NPC Name>%TAB%-1,{<code>}
272
273This will define an NPC object not triggerable by normal means. This would
274normally mean it's pointless since it can't do anything, but there are
275exceptions, mostly related to running scripts at specified time, which is what
276these floating NPC objects are for. More on that below.
277
278** Define a shop/cashshop/itemshop/pointshop NPC.
279
280-%TAB%shop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}
281<map name>,<x>,<y>,<facing>%TAB%shop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}
282
283-%TAB%cashshop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}
284<map name>,<x>,<y>,<facing>%TAB%cashshop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}
285
286-%TAB%itemshop%TAB%<NPC Name>%TAB%<sprite id>,<costitemid>{:<discount>},<itemid>:<price>{,<itemid>:<price>...}
287<map name>,<x>,<y>,<facing>%TAB%itemshop%TAB%<NPC Name>%TAB%<sprite id>,<costitemid>{:<discount>},<itemid>:<price>{,<itemid>:<price>...}
288
289-%TAB%pointshop%TAB%<NPC Name>%TAB%<sprite id>,<costvariable>{:<discount>},<itemid>:<price>{,<itemid>:<price>...}
290<map name>,<x>,<y>,<facing>%TAB%pointshop%TAB%<NPC Name>%TAB%<sprite id>,<costvariable>{:<discount>},<itemid>:<price>{,<itemid>:<price>...}
291
292<map name>,<x>,<y>,<facing>%TAB%marketshop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>:<quantity>{,<itemid>:<price>:<quantity>...}
293
294This will define a shop NPC, which, when triggered (which can only be done by
295clicking) will cause a shop window to come up. No code whatsoever runs in shop
296NPCs and you can't change the prices otherwise than by editing the script
297itself.
298
299The Item ID is the number of item in the 'item_db.txt' database. If Price is set
300to -1, the 'buy price' given in the item database will be used. Otherwise, the
301price you gave will be used for this item, which is how you create differing
302prices for items in different shops.
303
304There are other types of shops available:
305cashshop - use "cashshop" in place of "shop" to use the Cash Shop interface, allowing
306you to buy items with special points that are stored as account variables
307called #CASHPOINTS and #KAFRAPOINTS. This type of shop will not allow you to sell
308items at it, only make purchases. The layout used to define sale items still count, and
309"<price>" refers to how many points will be spent purchasing the them.
310
311"itemshop" and "pointshop" use the Shop interface, allowing you to buy items with a specific
312item or special points from a variable. 'pointshop' only supports permanent character variables,
313temporary character variables, permanent local account variables or permanent global account
314variables. These variables must be of integer type, not string. 'discount' flag is an
315optional value which makes the price at that shop become affected by discount skill.
316
317** Define an warp/shop/cashshop/itemshop/pointshop/NPC duplicate.
318
319warp/warp2: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany>
320shop/cashshop/itemshop/pointshop/npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>
321shop/cashshop/itemshop/pointshop/npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>
322npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>
323npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>
324
325This will duplicate an warp/shop/cashshop/itemshop/pointshop/NPC referred to by 'label'.
326Warp duplicates inherit the target location.
327Shop/cashshop/itemshop/pointshop duplicates inherit the item list.
328NPC duplicates inherit the script code.
329The rest (name, location, facing, sprite ID, span/trigger area)
330is obtained from the definition of the duplicate (not inherited).
331
332** Define a function object
333
334function%TAB%script%TAB%<function name>%TAB%{<code>}
335
336This will define a function object, callable with the 'callfunc' command (see
337below). This object will load on every map server separately, so you can get at
338it from anywhere. It's not possible to call the code in this object by
339anything other than the 'callfunc' script command.
340
341The code part is the script code that will execute whenever the function is
342called with 'callfunc'. It has to be in curly brackets, unlike elsewhere where
343we use curly brackets, these do NOT signify an optional parameter.
344
345Once an object is defined which has a 'code' field to its definition, it
346contains script commands which can actually be triggered and executed.
347
348~ RID? GID? ~
349
350What a RID is and why do you need to know
351-----------------------------------------
352
353Most scripting commands and functions will want to request data about a
354character, store variables referenced to that character, send stuff to the
355client connected to that specific character. Whenever a script is invoked by a
356character, it is passed a so-called RID - this is the account ID number of a
357character that caused the code to execute by clicking on it, walking into its
358OnTouch zone, or otherwise.
359
360If you are only writing common NPCs, you don't need to bother with it. However,
361if you use functions, if you use timers, if you use clock-based script
362activation, you need to be aware of all cases when a script execution can be
363triggered without a RID attached. This will make a lot of commands and functions
364unusable, since they want data from a specific character, want to send stuff to
365a specific client, want to store variables specific to that character, and they
366would not know what character to work on if there's no RID.
367
368Unless you use 'attachrid' to explicitly attach a character to the script first.
369
370Whenever we say 'invoking character', we mean 'the character who's RID is
371attached to the running script. The script function "playerattached" can be
372used to check which is the currently attached player to the script (it will
373return 0 if the there is no player attached or the attached player no longer
374is logged on to the map-server).
375
376But what about GID?
377-------------------
378
379GID stands for the Game ID of something, this can either be the GID obtained
380through mobspawn (mob control commands) or the account ID of a character.
381Another way would be to right click on a mob, NPC or char as GM sprited char
382to view the GID.
383
384See also 'getpetinfo', 'getmercinfo', 'gethominfo', and 'geteleminfo'.
385
386This is mostly used for the new version of skill and the mob control commands
387implemented.
388
389Item and pet scripts
390--------------------
391
392Each item in the item database has three special fields - Script , OnEquip_Script
393and OnUnequip_Script. The first is script code run every time a character equips the item,
394with the RID of the equipping character. Every time they unequip an item, all
395temporary bonuses given by the script commands are cleared, and all the scripts
396are executed once again to rebuild them. This also happens in several other
397situations (like upon login) but the full list is currently unknown.
398
399OnEquip_Script is a piece of script code run whenever the item is used by a character
400by double-clicking on it. OnUnequip_Script runs whenever the
401equipment is unequip by a character
402
403Not all script commands work properly in the item scripts. Where commands and
404functions are known to be meant specifically for use in item scripts, they are
405described as such.
406
407Every pet in the pet database has a PetScript field, which determines pet
408behavior. It is invoked wherever a pet of the specified type is spawned.
409(hatched from an egg, or loaded from the char server when a character who had
410that pet following them connects) This may occur in some other situations as
411well. Don't expect anything other than commands definitely marked as usable in
412pet scripts to work in there reliably.
413
414Numbers
415-------
416
417Beside the common decimal numbers, which are nothing special whatsoever (though
418do not expect to use fractions, since ALL numbers are integer in this language),
419the script engine also handles hexadecimal numbers, which are otherwise
420identical. Writing a number like '0x<hex digits>' will make it recognized as a
421hexadecimal value. Notice that 0x10 is equal to 16. Also notice that if you try
422to 'mes 0x10' it will print '16'.
423
424Number values can't exceed the limits of an integer variable: Any number
425greater than INT_MAX (2147483647) or smaller than INT_MIN (-2147483648) will
426be capped to those values and will cause a warning to be reported.
427
428Variables
429---------
430
431The meat of every programming language is variables - places where you store
432data.
433
434In the rAthena scripting language, variable names are not case sensitive.
435
436Variables are divided into and uniquely identified by the combination of:
437prefix - determines the scope and extent (or lifetime) of the variable
438name - an identifier consisting of '_' and alphanumeric characters
439postfix - determines the type of the variable: integer or string
440
441Scope can be:
442global - global to all servers
443local - local to the server
444account - attached to the account of the character identified by RID
445character - attached to the character identified by RID
446npc - attached to the NPC
447scope - attached to the scope of the instance
448
449Extent can be:
450permanent - They still exist when the server resets.
451temporary - They cease to exist when the server resets.
452
453Prefix: scope and extent
454nothing - A permanent variable attached to the character, the default variable
455 type. They are stored by char-server in the `char_reg_num` and
456 `char_reg_str`.
457"@" - A temporary variable attached to the character.
458 SVN versions before 2094 revision and RC5 version will also treat
459 'l' as a temporary variable prefix, so beware of having variable
460 names starting with 'l' if you want full backward compatibility.
461"$" - A global permanent variable.
462 They are stored by map-server in database table `mapreg`.
463"$@" - A global temporary variable.
464 This is important for scripts which are called with no RID
465 attached, that is, not triggered by a specific character object.
466"." - A NPC variable.
467 They exist in the NPC and disappear when the server restarts or the
468 NPC is reloaded. Can be accessed from inside the NPC or by calling
469 'getvariableofnpc'. Function objects can also have .variables which
470 are accessible from inside the function, however 'getvariableofnpc'
471 does NOT work on function objects.
472".@" - A scope variable.
473 They are unique to the instance and scope. Each instance has its
474 own scope that ends when the script ends. Calling a function with
475 callsub/callfunc starts a new scope, returning from the function
476 ends it. When a scope ends, its variables are converted to values
477 ('return .@var;' returns a value, not a reference).
478"'" - An instance variable.
479 These are used with the instancing system and are unique to each
480 instance type.
481"#" - A permanent local account variable.
482 They are stored by char-server in the `acc_reg_num` table and
483 `acc_reg_str`.
484"##" - A permanent global account variable stored by the login server.
485 They are stored in the `global_acc_reg_num` table and
486 `global_acc_reg_str`.
487 The only difference you will note from normal # variables is when
488 you have multiple char-servers connected to the same login server.
489 The # variables are unique to each char-server, while the ## variables
490 are shared by all these char-servers.
491
492Postfix: integer or string
493nothing - integer variable, can store positive and negative numbers, but only
494 whole numbers (so don't expect to do any fractional math)
495'$' - string variable, can store text
496
497Examples:
498 name - permanent character integer variable
499 name$ - permanent character string variable
500 @name - temporary character integer variable
501 @name$ - temporary character string variable
502 $name - permanent global integer variable
503 $name$ - permanent global string variable
504$@name - temporary global integer variable
505$@name$ - temporary global string variable
506 .name - NPC integer variable
507 .name$ - NPC string variable
508.@name - scope integer variable
509.@name$ - scope string variable
510 'name - instance integer variable
511 'name$ - instance string variable
512 #name - permanent local account integer variable
513 #name$ - permanent local account string variable
514##name - permanent global account integer variable
515##name$ - permanent global account string variable
516
517If a variable was never set, it is considered to equal zero for integer
518variables or an empty string ("", nothing between the quotes) for string
519variables. Once you set it to that, the variable is as good as forgotten
520forever, and no trace remains of it even if it was stored with character or
521account data.
522
523Some variables are special, that is, they are already defined for you by the
524scripting engine. You can see the full list in 'src/map/script_constants.h', which
525is a file you should read, since it also allows you to replace lots of numbered
526arguments for many commands with easier to read text. The special variables most
527commonly used are all permanent character-based variables:
528
529Zeny - Amount of Zeny.
530Hp - Current amount of hit points.
531MaxHp - Maximum amount of hit points.
532Sp - Current spell points.
533MaxSp - Maximum amount of spell points.
534StatusPoint - Amount of status points remaining.
535SkillPoint - Amount of skill points remaining.
536BaseLevel - Character's base level.
537JobLevel - Character's job level.
538BaseExp - Amount of base experience points.
539JobExp - Amount of job experience points.
540NextBaseExp - Amount of base experience points needed to reach the next level.
541NextJobExp - Amount of job experience points needed to reach the next level.
542Weight - Amount of weight the character currently carries.
543MaxWeight - Maximum weight the character can carry.
544Sex - 0 if female, 1 if male.
545Class - Character's job.
546Upper - 0 if the character is a normal class, 1 if advanced, 2 if baby.
547BaseClass - The character's 1-1 'normal' job, regardless of Upper value.
548 For example, this will return Job_Acolyte for Acolyte, Priest/Monk,
549 High Priest/Champion, and Arch Bishop/Sura. If the character has not
550 reached a 1-1 class, it will return Job_Novice.
551BaseJob - The character's 'normal' job, regardless of Upper value.
552 For example, this will return Job_Acolyte for Acolyte,
553 Baby Acolyte, and High Acolyte.
554Karma - The character's karma. Karma system is not fully functional, but
555 this doesn't mean this doesn't work at all. Not tested.
556Manner - The character's manner rating. Becomes negative if the player
557 utters words forbidden through the use of 'manner.txt' client-side
558 file.
559
560While these behave as variables, do not always expect to just set them - it is
561not certain whether this will work for all of them. Whenever there is a command
562or a function to set something, it's usually preferable to use that instead. The
563notable exception is Zeny, which you can and often will address directly -
564setting it will make the character own this number of Zeny.
565If you try to set Zeny to a negative number, the script will be terminated with an error.
566
567Some source-end constants can also be accessed in scripts. This list is located in
568'src/map/script_constants.h', which contains constants such as server defines and status options:
569
570 PACKETVER, MAX_LEVEL, MAX_STORAGE, MAX_INVENTORY, MAX_CART, MAX_ZENY, MAX_PARTY,
571 MAX_GUILD, MAX_GUILDLEVEL, MAX_GUILD_STORAGE, MAX_BG_MEMBERS, MAX_CHAT_USERS,
572 VIP_SCRIPT, MIN_STORAGE
573
574 Option_Nothing, Option_Sight, Option_Hide, Option_Cloak, Option_Falcon, Option_Riding,
575 Option_Invisible, Option_Orcish, Option_Wedding, Option_Chasewalk, Option_Flying,
576 Option_Xmas, Option_Transform, Option_Summer, Option_Dragon1, Option_Wug,
577 Option_Wugrider, Option_Madogear, Option_Dragon2, Option_Dragon3, Option_Dragon4,
578 Option_Dragon5, Option_Hanbok, Option_Oktoberfest, Option_Dragon, Option_Costume
579
580Assigning variables
581--------- ---------
582
583Variables can be accessed and modified much like in other programming languages.
584
585 @x = 100;
586 @x = @y = 100;
587
588Support for modifying variable values using 'set' is still supported (and required
589to exist for this new method to work) so previous scripts will continue to work.
590
591When assigning values, all operator methods are supported which exist in the below
592'Operators' section. For instance:
593
594 @x += 100;
595 @x -= 100;
596 @x *= 2;
597 @x /= 2;
598 @x %= 5;
599 @x >>= 2;
600 @x <<= 2;
601
602Will all work. For more information on available operators, see the Operators section
603described below. All operators listed there may be placed in-front of the '=' sign
604when modifying variables to perform the action as required.
605
606Note:
607
608 !! Currently the scripting engine does not support directly copying array variables.
609 !! In order to copy arrays between variables the use of 'copyarray' function is still
610 !! required.
611
612Strings
613-------
614
615To include symbol '"' in a string you should use prefix '\"'
616
617
618Arrays
619------
620
621Arrays (in rAthena at least) are essentially a set of variables going under the
622same name. You can tell between the specific variables of an array with an
623'array index', a number of a variable in that array:
624
625<variable name>[<array index>]
626
627All variable types can be used as arrays.
628
629Variables stored in this way, inside an array, are also called 'array elements'.
630Arrays are specifically useful for storing a set of similar data (like several
631item IDs for example) and then looping through it. You can address any array
632variable as if it was a normal variable:
633
634 set @arrayofnumbers[0],1;
635
636You can also do things like using a variable (or an expression, or even a
637value from another array) to get at an array value:
638
639 set @x,100;
640 set @arrayofnumbers[@x],10;
641
642This will make @arrayofnumbers[100] equal to 10.
643
644Index numbering always starts with 0 and arrays can hold over 2 billion
645variables. As such, the (guaranteed) allowed values for indices are in the
646range 0 ~ 2147483647.
647
648And array indexes probably can't be negative. Nobody tested what happens when
649you try to get a negatively numbered variable from an array, but it's not going
650to be pretty.
651
652Arrays can naturally store strings:
653
654@menulines$[0] is the 0th element of the @menulines$ array of strings. Notice
655the '$', normally denoting a string variable, before the square brackets that
656denotes an array index.
657
658Variable References
659-------------------
660
661//##TODO
662
663
664
665Operators
666---------
667
668Operators are things you can do to variables and numbers. They are either the
669common mathematical operations or conditional operators
670
671+ - will add two numbers. If you try to add two strings, the result will be a
672 string glued together at the +. You can add a number to a string, and the
673 result will be a string. No other math operators work with strings.
674- - will subtract two numbers.
675* - will multiply two numbers.
676/ - will divide two numbers. Note that this is an integer division, i.e.
677 7/2 is not equal 3.5, it's equal 3.
678% - will give you the remainder of the division. 7%2 is equal to 1.
679
680There are also conditional operators. This has to do with the conditional
681command 'if' and they are meant to return either 1 if the condition is satisfied
682and 0 if it isn't. (That's what they call 'boolean' variables. 0 means 'False'.
683Anything except the zero is 'True' Odd as it is, -1 and -5 and anything below
684zero will also be True.)
685
686You can compare numbers to each other and you compare strings to each other, but
687you can not compare numbers to strings.
688
689 == - Is true if both sides are equal. For strings, it means they are the same.
690 >= - True if the first value is equal to, or greater than, the second value.
691 <= - True if the first value is equal to, or less than, the second value
692 > - True if the first value greater than the second value
693 < - True if the first value is less than the second value
694 != - True if the first value IS NOT equal to the second one
695
696Examples:
697
698 1 == 1 is True.
699 1<2 is True while 1>2 is False.
700 @x>2 is True if @x is equal to 3. But it isn't true if @x is 2.
701
702Only ' == ' and '!=' have been tested for comparing strings. Since there's no way
703to code a seriously complex data structure in this language, trying to sort
704strings by alphabet would be pointless anyway.
705
706Comparisons can be stacked in the same condition:
707
708 && - Is True if and only if BOTH sides are true.
709 ('1 == 1 && 2 == 2' is true. '2 == 1 && 1 == 1' is false.)
710 || - Is True if either side of this expression is True.
711
712 1 == 1 && 2 == 2 is True.
713 1 == 1 && 2 == 1 is False.
714 1 == 1 || 2 == 1 is True.
715
716Logical bitwise operators work only on numbers, and they are the following:
717
718 << - Left shift.
719 >> - Right shift.
720 Left shift moves the binary 1(s) of a number n positions to the left,
721 which is the same as multiplying by 2, n times.
722 In the other hand, Right shift moves the binary 1(s) of a number n positions
723 to the right, which is the same as dividing by 2, n times.
724 Example:
725 set b,2;
726 set a, b << 3;
727 mes a;
728 set a, a >> 2;
729 mes a;
730 The first mes command would display 16, which is the same as 2 x (2 x 2 x 2) = 16.
731 The second mes command would display 4, which is the same as 16 / 2 = 8. 8 / 2 = 4.
732 & - And.
733 | - Or.
734 The bitwise operator AND (&) is used to test two values against each other,
735 and results in setting bits which are active in both arguments. This can
736 be used for a few things, but in rAthena this operator is usually used to
737 create bit-masks in scripts.
738
739 The bitwise operator OR (|)sets to 1 a binary position if the binary position
740 of one of the numbers is 1. This way a variable can hold several values we can check,
741 known as bit-mask. A variable currently can hold up to 32 bit-masks (from position 0
742 to position 1). This is a cheap(skate) and easy way to avoid using arrays to store several checks
743 that a player can have.
744
745 A bit-mask basically is (ab)using the variables bits to set various options in
746 one variable. With the current limit if variables it is possible to store 32
747 different options in one variable (by using the bits on position 0 to 31).
748
749 Example(s):
750 - Basic example of the & operator, bit example:
751 10 & 2 = 2
752 Why? :
753 10 = 2^1 + 2^3 (2 + 8), so in bits, it would be 1010
754 2 = 2^1 (2), so in bits (same size) it would be 0010
755 The & (AND) operator sets bits which are active (1) in both arguments, so in the
756 example 1010 & 0010, only the 2^1 bit is active (1) in both. Resulting in the bit
757 0010, which is 2.
758 - Basic example of creating and using a bit-mask:
759 set @options,2|4|16; //(note: this is the same as 2+4+16, or 22)
760 if (@options & 1) mes "Option 1 is activated";
761 if (@options & 2) mes "Option 2 is activated";
762 if (@options & 4) mes "Option 3 is activated";
763 if (@options & 8) mes "Option 4 is activated";
764 if (@options & 16) mes "Options 5 is activated";
765 This would return the messages about option 2, 3 and 5 being shown (since we've set
766 the 2,4 and 16 bit to 1).
767 ^ - Xor.
768 The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if both
769 numbers have the same value in the said position. On the other hand, it
770 sets to 1 if they have different values in the said binary position.
771 This is another way of setting and unsetting bits in bit-masks.
772
773 Example:
774 - First let's set the quests that are currently in progress:
775 set inProgress,1|8|16; // quest 1,8 and 16 are in progress
776 - After playing for a bit, the player starts another quest:
777 if (inProgress&2 == 0) {
778 // this will set the bit for quest 2 (inProgress has that bit set to 0)
779 set inProgress,inProgress^2;
780 mes "Quest 2: find a newbie and be helpful to him for an hour.";
781 close;
782 }
783 - After spending some time reading info on Xor's, the player finally completes quest 1:
784 if (inProgress&1 && isComplete) {
785 // this will unset the bit for quest 1 (inProgress has that bit set to 1)
786 set inProgress,inProgress^1;
787 mes "Quest 1 complete!! You unlocked the secrets of the Xor dynasty, use them wisely.";
788 close;
789 }
790
791Unary operators with only with a single number, which follows the operator, and
792are following:
793
794 - - Negation.
795 The sign of the number will be reversed. If the number was positive, it will
796 become negative and vice versa.
797
798 Example:
799 set .@myvar,10;
800 mes "Negative 10 is " + (-.@myvar);
801
802 ! - Logical Not.
803 Reverses the boolean result of an expression. True will become false and
804 false will become true.
805
806 Example:
807 if (!callfunc("F_dosomething"))
808 {
809 mes "Doing something failed.";
810 close;
811 }
812
813 ~ - Bitwise Not.
814 Reverses each bit in a number, also known as one's complement. Cleared bits
815 are set, and set bits are cleared.
816
817 Example:
818 - Ensure, that quest 2 is disabled, while keeping all other active, if they are.
819 set inProgress,inProgress&(~2); // same as set inProgress,inProgress&0xfffffffd
820
821Ternary operators take three expressions (numbers, strings or boolean), and are
822following:
823
824 ?: - Conditional operator
825 Very useful e.g. to replace
826
827 if (Sex) mes "..."; else mes "...";
828
829 clauses with simple
830
831 mes "Welcome, " + (Sex?"Mr.":"Mrs.") + " " + strcharinfo(0);
832
833 or to replace any other simple if-else clauses. It might be worth
834 mentioning that ?: has low priority and has to be enclosed with
835 parenthesis in most (if not all) cases.
836
837Labels
838------
839
840Within executable script code, some lines can be labels:
841
842<label name>:
843
844Labels are points of reference in your script, which can be used to route
845execution with 'goto', 'menu' and 'jump_zero' commands, invoked with 'doevent'
846and 'donpcevent' commands and are otherwise essential. A label's name may not be
847longer than 22 characters. (23rd is the ':'.) There is some confusion in the
848source about whether it's 22, 23 or 24 all over the place, so keeping labels
849under 22 characters could be wise. It may only contain alphanumeric characters
850and underscore. In addition to labels you name yourself, there are also some
851special labels which the script engine will start execution from if a special
852event happens:
853
854OnClock<hour><minute>:
855OnMinute<minute>:
856OnHour<hour>:
857On<weekday><hour><minute>:
858OnDay<month><day>:
859
860This will execute when the server clock hits the specified date or time. Hours
861and minutes are given in military time. ('0105' will mean 01:05 AM). Weekdays
862are Sun,Mon,Tue,Wed,Thu,Fri,Sat. Months are 01 to 12, days are 01 to 31.
863Remember the zero.
864
865OnInit:
866OnInterIfInit:
867OnInterIfInitOnce:
868
869OnInit will execute every time the scripts loading is complete, including when
870they are reloaded with @reloadscript command. OnInterIfInit will execute when
871the map server connects to a char server, OnInterIfInitOnce will only execute
872once and will not execute if the map server reconnects to the char server later.
873
874OnAgitStart:
875OnAgitEnd:
876OnAgitInit:
877OnAgitStart2:
878OnAgitEnd2:
879OnAgitInit2:
880OnAgitStart3:
881OnAgitEnd3:
882OnAgitInit3:
883
884OnAgitStart will run whenever the server shifts into WoE mode, whether it is
885done with @agitstart GM command or with 'AgitStart' script command. OnAgitEnd
886will do likewise for the end of WoE.
887
888OnAgitInit will run when data for all castles and all guilds that hold a castle
889is received by map-server from the char-server after initial connect.
890
891No RID will be attached while any of the above mentioned labels are triggered, so
892no character or account-based variables will be accessible, until you attach a
893RID with 'attachrid' (see below).
894
895The above also applies to, the last three labels, the only difference is that
896these labels are used exclusively for WoE SE, and are called independently.
897
898OnInstanceInit:
899
900This label will be executed when an instance is created and initialized through
901the 'instance_create' command. It will run again if @reloadscript is used while
902an instance is in progress.
903
904OnInstanceDestroy:
905
906This label will be executed when an instance is destroyed by a timeout, exceeding
907the keepalive time or through the 'instance_destroy' command. It will be called
908exactly before the instance will be destroyed and all other NPCs of the instance
909will still be available at this point of time.
910
911OnTouch:
912
913This label will be executed if a trigger area is defined for the NPC object it's
914in. If it isn't present, the execution will start from the beginning of the NPC
915code. The RID of the triggering character object will be attached.
916
917OnTouch_:
918
919Similar to OnTouch, but will only run one instance. Another character is
920chosen once the triggering character leaves the area.
921
922OnTouchNPC:
923
924Similar to OnTouch, but will only trigger for monsters. For this case, by using
925'getattachedrid' will returns GID (ID that returned when use 'monster').
926
927OnPCLoginEvent:
928OnPCLogoutEvent:
929OnPCBaseLvUpEvent:
930OnPCJobLvUpEvent:
931
932It's pretty obvious when these four special labels will be invoked.
933
934OnPCDieEvent:
935
936This special label triggers when a player dies. The variable 'killerrid' is
937set to the ID of the killer.
938
939OnPCKillEvent:
940
941This special label triggers when a player kills another player. The variable
942'killedrid' is set to the ID of the player killed.
943
944OnNPCKillEvent:
945
946This special label triggers when a player kills a monster without label. The variable
947'killedrid' is set to the Class (mob ID) of the monster killed.
948
949OnPCLoadMapEvent:
950
951This special label triggers when a player steps in a map marked with the
952'loadevent' mapflag and attaches its RID. The fact that this label requires a
953mapflag for it to work is because, otherwise, it'd be server-wide and trigger
954every time a player would change maps. Imagine the server load with 1,000 players
955(oh the pain...)
956
957OnPCStatCalcEvent:
958
959This special label triggers when a player's stats are recalculated, such as when
960changing stats, equipment, or maps, as well as when logging in, leveling up, and
961mounting a job mount. This can be used to grant additional item bonuses to certain
962player groups, for instance.
963
964OnWhisperGlobal:
965
966This special label triggers when a player whispers the NPC, and will run with the
967player's RID attached. It can accept up to ten parameters, which will be stored
968into separate temporary character string variables @whispervar0$ to @whispervar9$.
969See 'doc/whisper_sys.txt' for further documentation.
970
971Only the special labels which are not associated with any script command are
972listed here. There are other kinds of labels which may be triggered in a similar
973manner, but they are described with their associated commands.
974
975On<label name>:
976
977These special labels are used with Mob scripts mostly, and script commands
978that requires you to point/link a command to a mob or another NPC, giving a label
979name to start from. The label name can be any of your liking, but must be
980started with "On".
981
982Example:
983
984monster "prontera",123,42,"Poringz0rd",2341,23,"Master::OnThisMobDeath";
985
986amatsu,13,152,4 script Master 767,{
987 mes "Hi there";
988 close;
989
990OnThisMobDeath:
991 announce "Hey, " + strcharinfo(0) + " just killed a Poringz0rd!",bc_blue|bc_all;
992 end;
993}
994
995Each time you kill one, that announce will appear in blue to everyone.
996
997"Global" labels
998
999There's a catch with labels and doevent. If you call a label (using doevent)
1000and called label is in NPC that has trigger area, that label must end with
1001"Global" to work globally (i.e. if RID is outside of the trigger area, which
1002usually happens since otherwise there would be no point calling the label with
1003doevent, because OnTouch would do the job). For further reference look for
1004npc_event in npc.c.
1005
1006Scripting commands and functions
1007--------------------------------
1008
1009The commands and functions are listed here in no particular order. There's a
1010difference between commands and functions - commands leave no 'return value'
1011which might be used in a conditional statement, as a command argument, or stored
1012in a variable. Calling commands as if they were functions will sometimes work,
1013but is not advised, as this can lead to some hard to track errors. Calling
1014functions as if they were commands will mess up the stack, so 'return' command
1015will not return correctly after this happens in a particular script.
1016
1017All commands must end with a ';'.
1018
1019-------------------------
1020
1021
1022From here on, we will have the commands sorted as follow:
1023
10241.- Basic commands.
10252.- Information-retrieving commands.
10263.- Checking commands.
10274.- Player-related commands.
10285.- Mob / NPC -related commands.
10296.- Other commands.
10307.- Instance commands.
10318.- Quest Log commands.
10329.- Battleground commands.
103310.- Pet commands.
103410.1.- The Pet AI commands.
103511.- Homunculus commands.
103612.- Mercenary commands.
103713.- Party commands.
103814.- Channel commands.
103915.- Achievement commands.
1040
1041=====================
1042|1.- Basic commands.|
1043=====================
1044---------------------------------------
1045
1046*mes "<string>"{,"<string>"{,...}};
1047
1048This command will display a box on the screen for the invoking character, if no
1049such box is displayed already, and will print the string specified into that
1050box. There is normally no 'close' or 'next' button on this box, unless you
1051create one with 'close' or 'next', and while it's open the player can't do much
1052else, so it's important to create a button later. If the string is empty, it
1053will show up as an empty line.
1054
1055 mes "Text that will appear in the box";
1056
1057Colors
1058------
1059Inside the string you may put color codes, which will alter the color of the
1060text printed after them. The color codes are all '^<R><G><B>' and contain three
1061hexadecimal numbers representing colors as if they were HTML colors - ^FF0000 is
1062bright red, ^00FF00 is bright green, ^0000FF is bright blue, ^000000 is black.
1063^FF00FF is a pure magenta, but it's also a color that is considered transparent
1064whenever the client is drawing windows on screen, so printing text in that color
1065will have kind of a weird effect. Once you've set a text's color to something,
1066you have to set it back to black unless you want all the rest of the text be in
1067that color:
1068
1069 mes "This is ^FF0000 red ^000000 and this is ^00FF00 green, ^000000 so.";
1070
1071Notice that the text coloring is handled purely by the client. If you use non-
1072English characters, the color codes might get screwed if they stick to letters
1073with no intervening space. Separating them with spaces from the letters on
1074either side solves the problem.
1075
1076Multiple Lines
1077--------------
1078To display multiple lines of message while only using a single 'mes' command,
1079use the script command in the following format:
1080
1081 mes "Line 1", "Line 2", "Line 3";
1082
1083This will display 3 different lines while only consuming a single line in
1084the relevant script file.
1085
1086Navigation
1087----------
1088For clients dated 2011-10-10aRagexe onwards, you can generate navigation links
1089using HTML-like labels:
1090
1091 <NAVI>Display Name<INFO>mapname,x,y,0,000,flag</INFO></NAVI>
1092
1093The "flag" parameter can be:
1094 0: Do not open Navigation Window (default).
1095 1: Open Navigation Window.
1096
1097The example below will make the [Tool Shop] text clickable and begin navigation
1098to alberta (98,154) when clicked.
1099
1100 mes "Have you checked out the <NAVI>[Tool Shop]<INFO>alberta,98,154,0,000,0</INFO></NAVI>?";
1101
1102See also 'navigateto', which can be used for certain NPC events.
1103
1104Items
1105-----
1106You can refer to items by using HTML-like links to certain items:
1107
1108 <ITEMLINK>Display Name<INFO>Item ID</INFO></ITEMLINK>
1109
1110Where <Display Name> is the name that will be displayed for your link and
1111<Item ID> being the ID of the item you want to link to when clicked.
1112
1113In 2015 the tag name was changed to <ITEM> resulting in the following syntax:
1114
1115 <ITEM>Display Name<INFO>Item ID</INFO></ITEM>
1116
1117The following sample will open a preview window for Red Potion:
1118
1119 mes "Did you ever consume a <ITEMLINK>Red Potion<INFO>501</INFO></ITEMLINK>?";
1120 // Or in 2015:
1121 mes "Did you ever consume a <ITEM>Red Potion<INFO>501</INFO></ITEM>?";
1122
1123NOTE: Be aware that item links are rendered incorrectly in 2015+ clients at the moment.
1124
1125URLs
1126----
1127Similarly, you can create links to websites that launch in a new window:
1128
1129 <URL>Display Name<INFO>http://www.example.com/</INFO></URL>";
1130
1131---------------------------------------
1132
1133*next;
1134
1135This command will display a 'next' button in the message window for the
1136invoking character. Clicking on it will cause the window to clear and display
1137a new one. Used to segment NPC-talking, next is often used in combination with
1138'mes' and 'close'.
1139
1140If no window is currently on screen, one will be created, but once the invoking
1141character clicks on it, a warning is thrown on the server console and the script
1142will terminate.
1143
1144 mes "[Woman]";
1145 mes "This would appear on the page";
1146 next;
1147 // This is needed since it is a new page and the top will now be blank
1148 mes "[Woman]";
1149 mes "This would appear on the 2nd page";
1150
1151---------------------------------------
1152
1153*close;
1154
1155This command will create a 'close' button in the message window for the invoking
1156character. If no window is currently on screen, the script execution will end. This is one
1157of the ways to end a speech from an NPC. Once the button is clicked, the NPC
1158script execution will end, and the message box will disappear.
1159
1160 mes "[Woman]";
1161 mes "I am finished talking to you. Click the close button.";
1162 close;
1163 mes "This command will not run at all, since the script has ended.";
1164
1165---------------------------------------
1166
1167*close2;
1168
1169This command will create a 'close' button in the message window for the invoking
1170character. WARNING: If no window is currently on screen, the script execution will halt
1171indefinitely! See 'close'. There is one important difference, though - even though
1172the message box will have closed, the script execution will not stop, and commands after
1173'close2' will still run, meaning an 'end' has to be used to stop the script, unless you
1174make it stop in some other manner.
1175
1176 mes "[Woman]";
1177 mes "I will warp you now.";
1178 close2;
1179 warp "place",50,50;
1180 end;
1181
1182Don't expect things to run smoothly if you don't make your scripts 'end'.
1183
1184---------------------------------------
1185
1186*end;
1187
1188This command will stop the execution for this particular script. The two
1189versions are perfectly equivalent. It is the normal way to end a script which
1190does not use 'mes'.
1191
1192 if (BaseLevel <= 10)
1193 npctalk "Look at that you are still a n00b";
1194 else if (BaseLevel <= 20)
1195 npctalk "Look at that you are getting better, but still a n00b";
1196 else if (BaseLevel <= 30)
1197 npctalk "Look at that you are getting there, you are almost 2nd profession now right???";
1198 else if (BaseLevel <= 40)
1199 npctalk "Look at that you are almost 2nd profession";
1200 end;
1201
1202Without the use of 'end' it would travel through the labels until the end of the
1203script. If you were lvl 10 or less, you would see all the speech lines, the use
1204of 'end' stops this, and ends the script.
1205
1206---------------------------------------
1207
1208*set <variable>,<expression>{,<char_id>};
1209*set(<variable>,<expression>{,<char id>})
1210
1211This command will set a variable to the value that the expression results in.
1212Variables may either be set through this command or directly, much like any
1213other programming language (refer to the "Assigning variables" section).
1214
1215This is the most basic script command and is used a lot whenever you try to do
1216anything more advanced than just printing text into a message box.
1217
1218 set @x,100;
1219
1220will make @x equal 100.
1221
1222 set @x,1+5/8+9;
1223
1224will compute 1+5/8+9 (which is, surprisingly, 10 - remember, all numbers are
1225integer in this language) and make @x equal it.
1226
1227Returns the variable reference (since trunk r12870).
1228
1229---------------------------------------
1230
1231*setd "<variable name>",<value>{,<char_id>};
1232
1233Works almost identically as set, except the variable name is identified as a string
1234and can thus be constructed dynamically.
1235
1236This command is equivalent to:
1237 set getd("variable name"),<value>;
1238
1239Examples:
1240
1241 setd ".@var$", "Poporing";
1242 mes .@var$; // Displays "Poporing".
1243
1244 setd ".@" + .@var$ + "123$", "Poporing is cool";
1245 mes .@Poporing123$; // Displays "Poporing is cool".
1246
1247NOTE:
1248 'char_id' only works for non-server variables.
1249 Player with Character ID 'char_id' must be online.
1250
1251---------------------------------------
1252
1253*getd("<variable name>")
1254
1255Returns a reference to a variable, the name can be constructed dynamically.
1256Refer to 'setd' for usage.
1257
1258This can also be used to set an array dynamically:
1259 setarray getd(".array[0]"), 1, 2, 3, 4, 5;
1260
1261Examples:
1262
1263 set getd("$varRefence"), 1;
1264 set @i, getd("$" + "pikachu");
1265
1266---------------------------------------
1267
1268*getvariableofnpc(<variable>,"<npc name>")
1269
1270Returns a reference to a NPC variable (. prefix) from the target NPC.
1271This can only be used to get . variables.
1272
1273Examples:
1274
1275//This will return the value of .var, note that this can't be used, since the value isn't caught.
1276 getvariableofnpc(.var,"TargetNPC");
1277
1278//This will set the .v variable to the value of the TargetNPC's .var variable.
1279 set .v, getvariableofnpc(.var,"TargetNPC");
1280
1281//This will set the .var variable of TargetNPC to 1.
1282 set getvariableofnpc(.var,"TargetNPC"), 1;
1283
1284Note: even though function objects can have .variables,
1285getvariableofnpc will not work on them.
1286
1287---------------------------------------
1288
1289*getvar <variable>,<char_id>;
1290
1291Get variable value from the specified player. Only player/account variables
1292are allowed to be used (temporary character variable "@", permanent
1293character "", permanent local account "#", and permanent global account "##").
1294
1295---------------------------------------
1296
1297*goto <label>;
1298
1299This command will make the script jump to a label, usually used in conjunction
1300with other command, such as "if", but often used on its own.
1301
1302 ...
1303 goto Label;
1304
1305 mes "This will not be seen";
1306 end;
1307Label:
1308 mes "This will be seen";
1309 end;
1310
1311This command should be avoided and only used if there is no other option.
1312
1313---------------------------------------
1314
1315*menu "<option_text>",<target_label>{,"<option_text>",<target_label>,...};
1316
1317This command will create a selectable menu for the invoking character. Only one
1318menu can be on screen at the same time.
1319
1320Depending on what the player picks from the menu, the script execution will
1321continue from the corresponding label. (it's string-label pairs, not label-
1322string)
1323
1324Options can be grouped together, separated by the character ':'.
1325
1326 menu "A:B",L_Wrong,"C",L_Right;
1327
1328It also sets a special temporary character variable @menu, which contains the
1329number of option the player picked. (Numbering of options starts at 1.)
1330This number is consistent with empty options and grouped options.
1331
1332 menu "A::B",L_Wrong,"",L_Impossible,"C",L_Right;
1333
1334 L_Wrong:
1335 // If they click "A" or "B" they will end up here
1336 // @menu == 1 if "A"
1337 // @menu == 2 will never happen because the option is empty
1338 // @menu == 3 if "B"
1339 L_Impossible:
1340 // Empty options are not displayed and therefore can't be selected
1341 // this label will never be reached from the menu command
1342 L_Right:
1343 // If they click "C" they will end up here
1344 // @menu == 5
1345
1346If a label is '-', the script execution will continue right after the menu
1347command if that option is selected, this can be used to save you time, and
1348optimize big scripts.
1349
1350 menu "A::B:",-,"C",L_Right;
1351 // If they click "A" or "B" they will end up here
1352 // @menu == 1 if "A"
1353 // @menu == 3 if "B"
1354 L_Right:
1355 // If they click "C" they will end up here
1356 // @menu == 5
1357
1358Both these examples will perform the exact same task.
1359
1360If you give an empty string as a menu item, the item will not display. This
1361can effectively be used to script dynamic menus by using empty string for
1362entries that should be unavailable at that time.
1363
1364You can do it by using arrays, but watch carefully - this trick isn't high
1365wizardry, but minor magic at least. You can't expect to easily duplicate it
1366until you understand how it works.
1367
1368Create a temporary array of strings to contain your menu items, and populate it
1369with the strings that should go into the menu at this execution, making sure not
1370to leave any gaps. Normally, you do it with a loop and an extra counter, like
1371this:
1372
1373 setarray @possiblemenuitems$[0],<list of potential menu items>;
1374 @j = 0; // That's the menu lines counter.
1375
1376 // We loop through the list of possible menu items.
1377 // @i is our loop counter.
1378 for( @i = 0; @i < getarraysize(@possiblemenuitems$); @i++ )
1379 {
1380 // That 'condition' is whatever condition that determines whether
1381 // a menu item number @i actually goes into the menu or not.
1382
1383 if (<condition>)
1384 {
1385 // We record the option into the list of options actually available.
1386
1387 @menulist$[@j] = @possiblemenuitems$[@i];
1388
1389 // We just copied the string, we do need its number for later
1390 // though, so we record it as well.
1391
1392 @menureference[@j] = @i;
1393
1394 // Since we've just added a menu item into the list, we increment
1395 // the menu lines counter.
1396
1397 @j++;
1398 }
1399
1400 // We go on to the next possible menu item.
1401 }
1402
1403This will create you an array @menulist$ which contains the text of all items
1404that should actually go into the menu based on your condition, and an array
1405@menureference, which contains their numbers in the list of possible menu items.
1406(Remember, arrays start with 0.) There's less of them than the possible menu
1407items you've defined, but the menu command can handle the empty lines - only if
1408they are last in the list, and if it's made this way, they are. Now comes a
1409dirty trick:
1410
1411 // X is whatever the most menu items you expect to handle.
1412 menu @menulist$[0],-,@menulist$[1],-,....@menulist$[<X>],-;
1413
1414This calls up a menu of all your items. Since you didn't copy some of the
1415possible menu items into the list, its end is empty and so no menu items will
1416show up past the end. But this menu call doesn't jump anywhere, it just
1417continues execution right after the menu command. (And it's a good thing it
1418doesn't, cause you can only explicitly define labels to jump to, and how do you
1419know which ones to define if you don't know beforehand which options will end up
1420where in your menu?)
1421But how do you figure out which option the user picked? Enter the @menu.
1422
1423@menu contains the number of option that the user selected from the list,
1424starting with 1 for the first option. You know now which option the user picked
1425and which number in your real list of possible menu items it translated to:
1426
1427 mes "You selected " + @possiblemenuitems$[@menureference[@menu-1]] + "!";
1428
1429@menu is the number of option the user picked.
1430@menu-1 is the array index for the list of actually used menu items that we
1431made.
1432@menureference[@menu-1] is the number of the item in the array of possible menu
1433items that we've saved just for this purpose.
1434
1435And @possiblemenuitems$[@menureference[@menu-1]] is the string that we used to
1436display the menu line the user picked. (Yes, it's a handful, but it works.)
1437
1438You can set up a bunch of 'if (@menureference[@menu-1] == X) goto Y' statements to
1439route your execution based on the line selected and still generate a different
1440menu every time, which is handy when you want to, for example, make users select
1441items in any specific order before proceeding, or make a randomly shuffled menu.
1442
1443Kafra code bundled with the standard distribution uses a similar array-based
1444menu technique for teleport lists, but it's much simpler and doesn't use @menu,
1445probably since that wasn't documented anywhere.
1446
1447See also 'select', which is probably better in this particular case. Instead of
1448menu, you could use 'select' like this:
1449
1450 @dummy = select(@menulist$[0],@menulist$[1],....@menulist$[<X>]);
1451
1452For the purposes of the technique described above these two statements are
1453perfectly equivalent.
1454
1455---------------------------------------
1456
1457*select("<option>"{,"<option>",...})
1458*prompt("<option>"{,"<option>",...})
1459
1460This function is a handy replacement for 'menu' for some specific cases where
1461you don't want a complex label structure - like, for example, asking simple yes-
1462no questions. It will return the number of menu option picked, starting with 1.
1463Like 'menu', it will also set the variable @menu to contain the option the user
1464picked.
1465
1466 if (select("Yes:No" ) == 1)
1467 mes "You said yes, I know.";
1468
1469And like 'menu', the selected option is consistent with grouped options
1470and empty options.
1471
1472'prompt' works almost the same as select, except that when a character clicks
1473the Cancel button, this function will return 255 instead.
1474
1475---------------------------------------
1476
1477*input(<variable>{,<min>{,<max>}})
1478
1479This command will make an input box pop up on the client connected to the
1480invoking character, to allow entering of a number or a string. This has many
1481uses, one example would be a guessing game, also making use of the 'rand'
1482function:
1483
1484 mes "[Woman]";
1485 mes "Try and guess the number I am thinking of.";
1486 mes "The number will be between 1 and 10.";
1487 next;
1488 .@number = rand(1,10);
1489 input .@guess;
1490 if (.@guess == .@number) {
1491 mes "[Woman]";
1492 mes "Well done, that was the number I was thinking of!";
1493 close;
1494 } else {
1495 mes "[Woman]";
1496 mes "Sorry, that wasn't the number I was thinking of.";
1497 close;
1498 }
1499
1500If you give the input command a string variable to put the input in, it will
1501allow the player to enter text. Otherwise, only numbers will be allowed.
1502
1503 mes "[Woman]";
1504 mes "Please say HELLO";
1505 next;
1506 input .@var$;
1507 if (.@var$ == "HELLO") {
1508 mes "[Woman]";
1509 mes "Well done, you typed it correctly.";
1510 close;
1511 } else {
1512 mes "[Woman]";
1513 mes "Sorry, you got it wrong.";
1514 close;
1515 }
1516
1517Normally you may not input a negative number with this command.
1518This is done to prevent exploits in badly written scripts, which would
1519let people, for example, put negative amounts of Zeny into a bank script and
1520receive free Zeny as a result.
1521
1522Since trunk r12192 the command has two optional arguments and a return value.
1523The default value of 'min' and 'max' can be set with 'input_min_value' and
1524'input_max_value' in script_athena.conf.
1525For numeric inputs the value is capped to the range [min,max]. Returns 1 if
1526the value was higher than 'max', -1 if lower than 'min' and 0 otherwise.
1527For string inputs it returns 1 if the string was longer than 'max', -1 is
1528shorter than 'min' and 0 otherwise.
1529
1530---------------------------------------
1531
1532*callfunc "<function>"{,<argument>,...<argument>};
1533*callfunc("<function>"{,<argument>,...<argument>})
1534
1535This command lets you call up a function NPC. A function NPC can be called from
1536any script on any map server. Using the 'return' command it will come back to
1537the place that called it.
1538
1539 place,50,50,6%TAB%script%TAB%Woman%TAB%115,{
1540 mes "[Woman]"
1541 mes "Let's see if you win...";
1542 callfunc "funcNPC";
1543 mes "Well done, you have won!";
1544 close;
1545 }
1546 function%TAB%script%TAB%funcNPC%TAB%{
1547 .@win = rand(2);
1548 if (.@win == 0)
1549 return;
1550 mes "Sorry, you lost.";
1551 close;
1552 }
1553
1554You can pass arguments to your function - values telling it what exactly to do -
1555which will be available there with getarg() (see 'getarg')
1556Notice that returning is not mandatory, you can end execution right there.
1557
1558If you want to return a real value from inside your function NPC, it is better
1559to write it in the function form, which will also work and will make the script
1560generally cleaner:
1561
1562 place,50,50,6%TAB%script%TAB%Man%TAB%115,{
1563 mes "[Man]"
1564 mes "Gimme a number!";
1565 next;
1566 input @number;
1567 if (callfunc("OddFunc",@number)) mes "It's Odd!";
1568 close;
1569 }
1570 function%TAB%script%TAB%OddFunc%TAB%{
1571 if (getarg(0)%2 == 0)
1572 return 0;// it's even
1573 return 1;// it's odd
1574 }
1575
1576Alternately, as of rAthena revision 15979 and 15981, user-defined functions
1577may be called directly without the use of the 'callfunc' script command.
1578
1579 function<tab>script<tab>SayHello<tab>{
1580 mes "Hello " + getarg(0);
1581 return 0;
1582 }
1583
1584 place,50,50,6<tab>script<tab>Man<tab>115,{
1585 mes "[Man]";
1586 SayHello strcharinfo(0);
1587 close;
1588 }
1589
1590Note:
1591
1592 !! A user-defined function must be declared /before/ a script attempts to
1593 !! call it. That is to say, any functions should be placed above scripts or NPCs
1594 !! (or loaded in a separate file first) before attempting to call them directly.
1595
1596---------------------------------------
1597
1598*callsub <label>{,<argument>,...<argument>};
1599*callsub(<label>{,<argument>,...<argument>})
1600
1601This command will go to a specified label within the current script (do NOT use
1602quotes around it) coming in as if it were a 'callfunc' call, and pass it
1603arguments given, if any, which can be recovered there with 'getarg'. When done
1604there, you should use the 'return' command to go back to the point from where
1605this label was called. This is used when there is a specific thing the script
1606will do over and over, this lets you use the same bit of code as many times as
1607you like, to save space and time, without creating extra NPC objects which are
1608needed with 'callfunc'. A label is not callable in this manner from another
1609script.
1610
1611Example 1: callsub for checking (if checks pass, return to script)
1612 callsub S_CheckFull, "guild_vs2",50;
1613 switch( rand(4) ) {
1614 case 0: warp "guild_vs2",9,50; end;
1615 case 1: warp "guild_vs2",49,90; end;
1616 case 2: warp "guild_vs2",90,50; end;
1617 case 3: warp "guild_vs2",49,9; end;
1618 }
1619
1620...
1621
1622S_CheckFull:
1623 if (getmapusers(getarg(0)) >= getarg(1)) {
1624 mes "I'm sorry, this arena is full. Please try again later.";
1625 close;
1626 }
1627 return;
1628
1629Example 2: callsub used repeatedly, with different arguments
1630// notice how the Zeny check/delete is reused, instead of copy-pasting for every warp
1631 switch(select("Abyss Lake:Amatsu Dungeon:Anthell:Ayothaya Dungeon:Beacon Island, Pharos") {
1632 case 1: callsub S_DunWarp,"hu_fild05",192,207;
1633 case 2: callsub S_DunWarp,"ama_in02",119,181;
1634 case 3: callsub S_DunWarp,"moc_fild20",164,145;
1635 case 4: callsub S_DunWarp,"ayo_fild02",279,150;
1636 case 5: callsub S_DunWarp,"cmd_fild07",132,125;
1637 // etc
1638 }
1639
1640...
1641
1642S_DunWarp:
1643// getarg(0) = "map name"
1644// getarg(1) = x
1645// getarg(2) = y
1646 if (Zeny >= 100) {
1647 Zeny -= 100;
1648 warp getarg(0),getarg(1),getarg(2);
1649 } else {
1650 mes "Dungeon warp costs 100 Zeny.";
1651 }
1652 close;
1653
1654---------------------------------------
1655
1656*getarg(<index>{,<default_value>})
1657
1658This function is used when you use the 'callsub' or 'callfunc' commands. In the
1659call you can specify variables that will make that call different from another
1660one. This function will return an argument the function or subroutine was
1661called with, and is the normal way to get them.
1662This is another thing that can let you use the same code more than once.
1663
1664Argument numbering starts with 0, i.e. the first argument you gave is number 0.
1665If no such argument was given, a zero is returned.
1666
1667 place,50,50,6%TAB%script%TAB%Woman1%TAB%115,{
1668 mes "[Woman]";
1669 mes "Let's see if you win...";
1670 callfunc "funcNPC",2;
1671 mes "Well done, you have won!";
1672 close;
1673 }
1674
1675 place,52,50,6%TAB%script%TAB%Woman2%TAB%115,{
1676 mes "[Woman]";
1677 mes "Let's see if you win...";
1678 callfunc "funcNPC",5;
1679 mes "Well done, you have won!";
1680 close;
1681 }
1682
1683 function%TAB%script%TAB%funcNPC%TAB%{
1684 .@win = rand(getarg(0));
1685 if (.@win == 0) return;
1686 mes "Sorry, you lost.";
1687 close;
1688 |
1689
1690"woman1" NPC object calls the funcNPC. The argument it gives in this call is
1691stated as 2, so when the random number is generated by the 'rand' function, it
1692can only be 0 or 1. Whereas "woman2" gives 5 as the argument number 0 when
1693calling the function, so the random number could be 0, 1, 2, 3 or 4, this makes
1694"woman2" less likely to say the player won.
1695
1696You can pass multiple arguments in a function call:
1697
1698 callfunc "funcNPC",5,4,3;
1699
1700getarg(0) would be 5, getarg(1) would be 4 and getarg(2) would be 3.
1701
1702'getarg' has an optional argument since trunk r10773 and stable r10958.
1703If the target argument exists, it is returned.
1704Otherwise, if <default_value> is present it is returned instead,
1705if not the script terminates immediately.
1706
1707In the previous example getarg(2,-1) would be 3 and getarg(3,-1) would be -1.
1708
1709---------------------------------------
1710
1711*getargcount()
1712
1713This function is used when you use the 'callsub' or 'callfunc' commands. In the
1714call you can specify arguments. This function will return the number of arguments
1715provided.
1716
1717Example:
1718 callfunc "funcNPC",5,4,3;
1719 ...
1720 function%TAB%script%TAB%funcNPC%TAB%{
1721 .@count = getargcount(); // 3
1722 ...
1723 }
1724
1725---------------------------------------
1726
1727*return {<value>};
1728
1729This command causes the script execution to leave previously called function
1730with callfunc or script with callsub and return to the location, where the call
1731originated from. Optionally a return value can be supplied, when the call was
1732done using the function form.
1733
1734Using this command outside of functions or scripts referenced by callsub will
1735result in error and termination of the script.
1736
1737 callfunc "<your function>";// when nothing is returned
1738 set <variable>,callfunc("<your function>");// when a value is being returned
1739
1740---------------------------------------
1741
1742*function <function name>;
1743*<function name>{(<argument>,...<argument>)};
1744*function <function name> {
1745<code>
1746}
1747
1748This works like callfunc, and is used for cleaner and faster scripting. The function
1749must be defined and used within a script, and works like a label with arguments.
1750Note that the name may only contain alphanumeric characters and underscore.
1751
1752Usage:
1753
1754 1. Declare the function.
1755 function <function name>;
1756 2. Call the function anywhere within the script.
1757 It can also return a value when used with parentheses.
1758 <function name>;
1759 3. Define the function within the script.
1760 <function name> {<code>}
1761
1762Example:
1763
1764prontera,154,189,4 script Item Seller 767,{
1765 /* Function declaration */
1766 function SF_Selling;
1767
1768 if (Zeny > 50) {
1769 mes "Welcome!";
1770 /* Function call */
1771 SF_Selling;
1772 }
1773 else mes "You need 50z, sorry!";
1774 close;
1775
1776 /* Function definition */
1777 function SF_Selling {
1778 mes "Would you like to buy a phracon for 50z?";
1779 next;
1780 if (select("Yes","No, thanks") == 1) {
1781 Zeny -= Zeny;
1782 getitem 1010,1;
1783 mes "Thank you!";
1784 }
1785 return;
1786 }
1787}
1788
1789Example with parameters and return value:
1790
1791prontera,150,150,0 script TestNPC 123,{
1792 /* Function declaration */
1793 function MyAdd;
1794
1795 mes "Enter two numbers.";
1796 next;
1797 input .@a;
1798 input .@b;
1799 /* Function call */
1800 mes .@a + " + " + .@b + " = " + MyAdd(.@a,.@b);
1801 close;
1802
1803 /* Function definition */
1804 function MyAdd {
1805 return getarg(0)+getarg(1);
1806 }
1807}
1808
1809
1810---------------------------------------
1811
1812*is_function("<function name>")
1813
1814This command checks whether a function exists.
1815It returns 1 if function is found, or 0 if it isn't.
1816
1817Example:
1818
1819 function script try {
1820 dothat;
1821 }
1822
1823 - script test -1,{
1824 .@try = is_function("try"); // 1
1825 .@not = is_function("not"); // 0
1826 }
1827
1828---------------------------------------
1829
1830*if (<condition>) <statement>;
1831
1832This is the basic conditional statement command, and just about the only one
1833available in this scripting language.
1834
1835The condition can be any expression. All expressions resulting in a non-zero
1836value will be considered True, including negative values. All expressions
1837resulting in a zero are false.
1838
1839If the expression results in True, the statement will be executed. If it isn't
1840true, nothing happens and we move on to the next line of the script.
1841
1842 if (1) mes "This will always print.";
1843 if (0) mes "And this will never print.";
1844 if (5) mes "This will also always print.";
1845 if (-1) mes "Funny as it is, this will also print just fine.";
1846
1847For more information on conditional operators see the operators section above.
1848Anything that is returned by a function can be used in a condition check without
1849bothering to store it in a specific variable:
1850
1851 if (strcharinfo(0) == "Daniel Jackson") mes "It is true, you are Daniel!";
1852
1853More examples of using the 'if' command in the real world:
1854
1855Example 1:
1856
1857 .@answer = 1;
1858 input .@input;
1859 if (.@input == .@answer)
1860 close;
1861 mes "Sorry, your answer is incorrect.";
1862 close;
1863
1864Example 2:
1865
1866 .@answer = 1;
1867 input .@input;
1868 if (.@input != .@answer)
1869 mes "Sorry, your answer is incorrect.";
1870 close;
1871
1872Notice that examples 1 and 2 have the same effect.
1873
1874Example 3:
1875
1876 @count++;
1877 mes "[Forgetful Man]";
1878 if (@count == 1) mes "This is the first time you have talked to me.";
1879 if (@count == 2) mes "This is the second time you have talked to me.";
1880 if (@count == 3) mes "This is the third time you have talked to me.";
1881 if (@count == 4) {
1882 mes "This is the fourth time you have talked to me.";
1883 mes "I think I am getting amnesia, I have forgotten about you...";
1884 @count = 0;
1885 }
1886 close;
1887
1888Example 4:
1889
1890 mes "[Quest Person]";
1891 if (countitem(512) < 1) { // 512 is the item ID for Apple, found in item_db
1892 mes "Can you please bring me an apple?";
1893 close;
1894 }
1895 mes "Oh, you brought an Apple!";
1896 mes "I didn't want it, I just wanted to see one.";
1897 close;
1898
1899Example 5:
1900
1901 mes "[Person Checker]";
1902 if ($@name$ == "") { // global variable not yet set
1903 mes "Please tell me someones name";
1904 next;
1905 input $@name$;
1906 $@name2$ = strcharinfo(0);
1907 mes "[Person Checker]";
1908 mes "Thank you.";
1909 close;
1910 }
1911 if ($@name$ == strcharinfo(0)) { // player name matches $@name$
1912 mes "You are the person that " + $@name2$ + " just mentioned.";
1913 mes "Nice to meet you!";
1914
1915 // reset the global variables
1916 $@name$ = "";
1917 $@name2$ = "";
1918
1919 close;
1920 }
1921 mes "You are not the person that " + $name2$ + " mentioned.";
1922 close;
1923
1924See 'strcharinfo' for an explanation of what this function does.
1925
1926Example 6: Using complex conditions.
1927
1928 mes "[Multiple Checks]";
1929 if (@queststarted == 1 && countitem(512) >= 5) {
1930 mes "Well done, you have started the quest and brought me 5 Apples.";
1931 @queststarted = 0;
1932 delitem 512,5;
1933 close;
1934 }
1935 mes "Please bring me 5 apples.";
1936 @queststarted = 1;
1937 close;
1938
1939The script engine also supports nested 'if' statements:
1940
1941 if (<condition>)
1942 dothis;
1943 else
1944 dothat;
1945
1946If the condition isn't met, it'll do the action following the 'else'.
1947We can also group several actions depending on a condition:
1948
1949 if (<condition>) {
1950 dothis1;
1951 dothis2;
1952 } else {
1953 dothat1;
1954 dothat2;
1955 dothat3;
1956 }
1957
1958Remember that if you plan to do several actions upon the condition being false, and
1959you forget to use the curly braces (the { } ), the second action will be executed regardless
1960the output of the condition, unless of course, you stop the execution of the script if the
1961condition is true (that is, in the first grouping using a return; , and end; or a close; )
1962
1963Also, you can have multiple conditions nested or chained.
1964
1965 if (<condition 1>)
1966 dothis;
1967 else if (<condition 2>) {
1968 dothat;
1969 end;
1970 } else
1971 dothis;
1972
1973---------------------------------------
1974
1975*jump_zero (<condition>),<label>;
1976
1977This command works kinda like an 'if'+'goto' combination in one go. (See 'if').
1978If the condition is false (equal to zero) this command will immediately jump to
1979the specified label like in 'goto'. While 'if' is more generally useful, for
1980some cases this could be an optimization.
1981
1982The main reason for this command is that other control statements, like
1983'switch', 'for' or 'while', are disassembled into simple expressions together
1984with this command when a script is parsed.
1985
1986---------------------------------------
1987
1988*switch (expression);
1989
1990The switch statement is similar to a series of if statements on the same expression.
1991In many occasions, you may want to compare the same variable (or expression)
1992with many different values, and execute a different piece of code depending
1993on which value it equals to. This is exactly what the switch statement is for.
1994
1995It is important to understand how the switch statement is executed in order
1996to avoid mistakes. The switch statement executes line by line (actually, statement by statement).
1997In the beginning, no code is executed. Only when a case statement is found
1998with a value that matches the value of the switch expression the case statement(s)
1999will to executed. The parser continues to execute the statements until the end
2000of the switch block, or the first time it sees a break statement. If you don't
2001write a break statement at the end of a case's statement list, the parser will
2002go on executing the statements of the following case (fall-through).
2003
2004Example 1:
2005
2006 switch(select("Yes:No")) {
2007 case 1:
2008 mes "You said yes!";
2009 break;
2010 case 2:
2011 mes "Aww, why?";
2012 break;
2013 }
2014 close;
2015
2016The example above would work like a menu and would go to the first case if
2017the user selects option, otherwise, would go to the second one.
2018
2019Example 2:
2020
2021 switch(getgroupid()) {
2022 case 1:
2023 mes "Wow, you're super!";
2024 break;
2025 case 2:
2026 mes "A helping hand!";
2027 break;
2028 case 3:
2029 mes "10001010010011";
2030 break;
2031 case 4:
2032 mes "Yes, milord?";
2033 break;
2034 default:
2035 mes "Hello there!";
2036 break;
2037 }
2038
2039The example above would print a message depending on the player's groupid.
2040If there is no statement declared for the corresponding groupid, the script
2041would use the 'default' statement that applies to rest of possible values,
2042similar to 'else' in the if-else statement.
2043
2044---------------------------------------
2045
2046*while (<condition>) <statement>;
2047
2048This is probably the simplest and most frequently used loop structure. The 'while'
2049statement can be interpreted as "while <condition> is true, perform <statement>".
2050It is a pretest loop, meaning the conditional expression is tested before any of the
2051statements in the body of the loop are performed. If the condition evaluates to
2052false, the statement(s) in the body of the loop is/are never executed. If the
2053condition evaluates to true, the statement(s) are executed, then control transfers
2054back to the conditional expression, which is reevaluated and the cycle continues.
2055
2056Multiple statements can be grouped with { }, curly braces, just like with the 'if' statement.
2057
2058Example 1:
2059 while (switch(select("Yes:No") == 2 ))
2060 mes "You picked no.";
2061 close;
2062
2063Example 2: multiple statements
2064 while (switch(select("Yes:No") == 2 )) {
2065 mes "Why did you pick no?";
2066 mes "You should pick yes instead!";
2067 }
2068 close;
2069
2070Example 3: counter-controlled loop
2071 .@i = 1;
2072 while (.@i <= 5) {
2073 mes "This line will print 5 times.";
2074 .@i += 1;
2075 }
2076 close;
2077
2078Example 4: sentinel-controlled loop
2079 mes "Input 0 to stop";
2080 input .@num;
2081 while (.@num != 0) {
2082 mes "You entered " + .@num;
2083 input .@num;
2084 }
2085 close;
2086
2087---------------------------------------
2088
2089*for (<variable initialization>; <condition>; <variable update>) <statement>;
2090
2091Another pretest looping structure is the 'for' statement. It is considered a
2092specialized form of the 'while' statement, and is usually associated with counter-
2093controlled loops. Here are the steps of the 'for' statement: the initialize
2094statement is executed first and only once. The condition test is performed.
2095When the condition evaluates to false, the rest of the for statement is skipped.
2096When the condition evaluates to true, the body of the loop is executed, then the
2097update statement is executed (this usually involves incrementing a variable).
2098Then the condition is reevaluated and the cycle continues.
2099
2100Example 1:
2101 for( .@i = 1; .@i <= 5; .@i++ )
2102 mes "This line will print 5 times.";
2103
2104Example 2:
2105 mes "This will print the numbers 1 - 5.";
2106 for( .@i = 1; .@i <= 5; .@i++ )
2107 mes "Number: " + .@i;
2108
2109---------------------------------------
2110
2111*do { <statement>; } while (<condition>);
2112
2113The 'do...while' is the only post-test loop structure available in this script
2114language. With a post-test, the statements are executed once before the condition
2115is tested. When the condition is true, the statement(s) are repeated. When the
2116condition is false, control is transferred to the statement following the
2117'do...while' loop expression.
2118
2119Example 1: sentinel-controlled loop
2120 mes "This menu will keep appearing until you pick Cancel";
2121 do {
2122 .@menu = select("One:Two:Three:Cancel");
2123 } while (.@menu != 4);
2124
2125Example 2: counter-controlled loop
2126 mes "This will countdown from 10 to 1.";
2127 .@i = 10;
2128 do {
2129 mes .@i;
2130 .@i -= 1;
2131 } while (.@i > 0);
2132
2133---------------------------------------
2134
2135*freeloop({<toggle>})
2136
2137Toggling this to enabled (1) allows the script instance to bypass the infinite loop
2138protection, allowing your script to loop as much as it may need. Disabling (0) will
2139warn you if an infinite loop is detected.
2140
2141The command will return the state of freeloop for the attached script, even if no
2142argument is provided.
2143
2144Example:
2145 freeloop(1); // enable script to loop freely
2146
2147 // be careful with what you do here
2148 for ( .@i = 0; .@i < .@bigloop; .@i++ ) {
2149 dothis;
2150 // will sleep the script for 1ms when detect an infinity loop to
2151 // let rAthena do what it needs to do (socket, timer, process, etc.)
2152 }
2153
2154 freeloop(0); // disable freeloop
2155
2156 for ( .@i = 0; .@i < .@bigloop; .@i++ ) {
2157 dothis;
2158 // throw an infinity loop error
2159 }
2160
2161---------------------------------------
2162
2163*setarray <array name>[<first value>],<value>{,<value>...<value>};
2164
2165This command will allow you to quickly fill up an array in one go. Check the
2166Kafra scripts in the distribution to see this used a lot.
2167
2168 setarray @array[0], 100, 200, 300, 400, 500, 600;
2169
2170First value is the index of the first element of the array to alter. For
2171example:
2172
2173 setarray @array[0],200,200,200;
2174 setarray @array[1],300,150;
2175
2176will produce:
2177
2178 @array[0]=200
2179 @array[1]=300
2180 @array[2]=150
2181
2182---------------------------------------
2183
2184*cleararray <array name>[<first value to alter>],<value>,<number of values to set>;
2185
2186This command will change many array values at the same time to the same value.
2187
2188 setarray @array[0], 100, 200, 300, 400, 500, 600;
2189 // This will make all 6 values 0
2190 cleararray @array[0],0,6;
2191 // This will make array element 0 change to 245
2192 cleararray @array[0],245,1;
2193 // This will make elements 1 and 2 change to 345
2194 cleararray @array[1],345,2;
2195
2196See 'setarray'.
2197
2198---------------------------------------
2199
2200*copyarray <destination array>[<first value>],<source array>[<first value>],<amount of data to copy>;
2201
2202This command lets you quickly shuffle a lot of data between arrays, which is in
2203some cases invaluable.
2204
2205 setarray @array[0], 100, 200, 300, 400, 500, 600;
2206 // So we have made @array[]
2207 copyarray @array2[0],@array[2],2;
2208
2209 // Now, @array2[0] will be equal to @array[2] (300) and
2210 // @array2[1] will be equal to @array[3].
2211
2212So using the examples above:
2213 @array[0] = 100
2214 @array[1] = 200
2215 @array[2] = 300
2216 @array[3] = 400
2217 @array[4] = 500
2218 @array[5] = 600
2219
2220New Array:
2221 @array2[0] = 300
2222 @array2[1] = 400
2223 @array2[2] = 0
2224 @array2[3] = 0
2225
2226Notice that @array[4] and @array[5] won't be copied to the second array, and it will return a
22270.
2228
2229---------------------------------------
2230
2231*deletearray <array name>[<first value>],<how much to delete>;
2232
2233This command will delete a specified number of array elements totally from an
2234array, shifting all the elements beyond this towards the beginning.
2235
2236 // This will delete array element 0, and move all the other array elements
2237 // up one place.
2238 deletearray @array[0],1
2239
2240// This would delete array elements numbered 1, 2 and 3, leave element 0 in its
2241// place, and move the other elements ups, so there are no gaps.
2242
2243 deletearray @array[1],3
2244
2245---------------------------------------
2246
2247======================================
2248|2.- Information-retrieving commands.|
2249======================================
2250---------------------------------------
2251
2252*strcharinfo(<type>{,<char_id>})
2253
2254This function will return either the name, party name or guild name for the
2255invoking character. Whatever it returns is determined by type.
2256
2257 0 - Character's name.
2258 1 - The name of the party they're in if any.
2259 2 - The name of the guild they're in if any.
2260 3 - The name of the map the character is in.
2261
2262If a character is not a member of any party or guild, an empty string will be
2263returned when requesting that information.
2264
2265---------------------------------------
2266
2267*strnpcinfo(<type>)
2268
2269This function will return the various parts of the name of the calling NPC.
2270Whatever it returns is determined by type.
2271
2272 0 - The NPC's display name (visible#hidden)
2273 1 - The visible part of the NPC's display name
2274 2 - The hidden part of the NPC's display name
2275 3 - The NPC's unique name (::name)
2276 4 - The name of the map the NPC is in.
2277
2278---------------------------------------
2279
2280*getarraysize(<array name>)
2281
2282This function returns highest index of the array that is filled.
2283Notice that zeros and empty strings at the end of this array are not
2284counted towards this number.
2285
2286For example:
2287
2288 setarray @array[0], 100, 200, 300, 400, 500, 600;
2289 set @arraysize,getarraysize(@array);
2290
2291This will make @arraysize == 6. But if you try this:
2292
2293 setarray @array[0], 100, 200, 300, 400, 500, 600, 0;
2294 set @arraysize,getarraysize(@array);
2295
2296@arraysize will still equal 6, even though you've set 7 values.
2297
2298---------------------------------------
2299
2300*getelementofarray(<array name>,<index>)
2301
2302This command retrieves the value of the element of given array at given index.
2303This is equivalent to using:
2304
2305 <array name>[<index>]
2306
2307The reason for this is, that this short form is internally converted into a call
2308to getelementofarray, when the script is loaded.
2309
2310Also useful when passing arrays to functions or accessing another npc's arrays:
2311 getelementofarray(getarg(0),<index>)
2312 getelementofarray(getvariableofnpc(.var, "testNPC"),<index>)
2313
2314---------------------------------------
2315
2316*readparam(<parameter number>{,"<character name>"})
2317*readparam(<parameter number>{,<char_id>})
2318
2319This function will return the specified stat of the invoking character, or, if a
2320character name or character id is specified, of that player. The stat can either
2321be a number or parameter name, defined in 'src/map/script_constants.h'.
2322
2323Some example parameters:
2324
2325StatusPoint, BaseLevel, SkillPoint, Class, Upper, Zeny, Sex, Weight, MaxWeight,
2326JobLevel, BaseExp, JobExp, NextBaseExp, NextJobExp, Hp, MaxHp, Sp, MaxSp,
2327BaseJob, Karma, Manner, bVit, bDex, bAgi, bStr, bInt, bLuk
2328
2329All of these also behave as variables, but don't expect to be able to just 'set'
2330them - some will not work for various internal reasons.
2331
2332Example 1:
2333
2334 // Returns how many status points you haven't spent yet.
2335 mes "Unused status points: " + readparam(9);
2336
2337Using this particular information as a function call is not required. Typing this
2338will return the same result:
2339
2340 mes "Unused status points: " + StatusPoint;
2341
2342Example 2:
2343
2344You can also use this command to get stat values.
2345
2346 if (readparam(bVit) > 77)
2347 mes "Only people with over 77 Vit are reading this!";
2348
2349---------------------------------------
2350
2351*getcharid(<type>{,"<character name>"})
2352
2353This function will return a unique ID number of the invoking character, or, if a
2354character name is specified, of that player.
2355
2356Type is the kind of associated ID number required:
2357
2358 0 - Character ID
2359 1 - Party ID
2360 2 - Guild ID
2361 3 - Account ID
2362 4 - Battle Ground ID
2363 5 - Clan ID
2364
2365For most purposes other than printing it, a number is better to have than a name
2366(people do horrifying things to their character names).
2367
2368If the character is not in a party or not in a guild, the function will return 0
2369if guild or party number is requested. If a name is specified and the character
2370is not found, 0 is returned.
2371
2372If getcharid(0) returns a zero, the script got called not by a character and
2373doesn't have an attached RID. Note that this will cause the map server to
2374print "player not attached!" error messages, so it is preferred to use
2375"playerattached" to check for the character attached to the script.
2376
2377if (getcharid(2) == 0)
2378 mes "Only members of a guild are allowed here!";
2379
2380---------------------------------------
2381
2382*getnpcid(<type>{,"<npc name>"});
2383
2384Retrieves IDs of the currently invoked NPC. If a unique npc name is
2385given, IDs of that NPC are retrieved instead. Type specifies what ID
2386to retrieve and can be one of the following:
2387
2388 0 - NPC Game ID
2389
2390If an invalid type is given or the NPC does not exist, 0 is returned.
2391
2392---------------------------------------
2393
2394*getchildid({<char_id>})
2395*getmotherid({<char_id>})
2396*getfatherid({<char_id>})
2397
2398These functions return the character ID of the attached player's child,
2399mother, mother, or father, respectively. It returns 0 if no ID is found.
2400
2401 if (getmotherid()) mes "Your mother's ID is: " + getmotherid();
2402
2403---------------------------------------
2404
2405*ispartneron({<char_id>})
2406
2407This function returns 1 if the invoking character's marriage partner is
2408currently online and 0 if they are not or if the character has no partner.
2409
2410---------------------------------------
2411
2412*getpartnerid({<char_id>})
2413
2414This function returns the character ID of the invoking character's marriage
2415partner, if any. If the invoking character is not married, it will return 0,
2416which is a quick way to see if they are married:
2417
2418 if (getpartnerid()) mes "I'm not going to be your girlfriend!";
2419 if (getpartnerid()) mes "You're married already!";
2420
2421---------------------------------------
2422
2423*getlook(<type>{,<char_id>})
2424
2425This function will return the number for the current character look value
2426specified by type. See 'setlook' for valid look types.
2427
2428This can be used to make a certain script behave differently for characters
2429dressed in black.
2430
2431---------------------------------------
2432
2433*getsavepoint(<information type>{,<char_id>})
2434
2435This function will return information about the invoking character's save point.
2436You can use it to let a character swap between several recorded save points.
2437Available information types are:
2438
2439 0 - Map name (a string)
2440 1 - X coordinate
2441 2 - Y coordinate
2442
2443---------------------------------------
2444
2445*getcharip({"<character name>"|<account id>|<char id>})
2446
2447This function will return the IP address of the invoking character, or, if a player
2448is specified, of that character. A blank string is returned if no player is attached.
2449
2450Examples:
2451
2452// Outputs IP address of attached player.
2453 mes "Your IP: " + getcharip();
2454
2455// Outputs IP address of character "Silver".
2456 mes "Silver's IP: " + getcharip("Silver");
2457
2458---------------------------------------
2459
2460*vip_status(<type>,{"<character name>"})
2461
2462Returns various information about a player's VIP status.
2463
2464Valid types:
2465 VIP_STATUS_ACTIVE - VIP status: true if the player is a VIP or false if not
2466 VIP_STATUS_EXPIRE - VIP expire timestamp if the player is VIP or 0 if not
2467 VIP_STATUS_REMAINING - VIP time remaining in seconds
2468
2469NOTE: This command is only available if the VIP System is enabled.
2470
2471---------------------------------------
2472
2473*vip_time <time>,{"<character name>"};
2474
2475Changes a player's VIP time (in minutes). A positive value will increase time, and a
2476negative value will decrease time.
2477
2478NOTE: This command is only available if the VIP System is enabled.
2479
2480---------------------------------------
2481
2482*addspiritball <count>,<duration>{,<char_id>};
2483
2484Adds spirit ball to player for 'duration' in milisecond.
2485
2486---------------------------------------
2487
2488*delspiritball <count>{,<char_id>};
2489
2490Deletes the spirit ball(s) from player.
2491
2492---------------------------------------
2493
2494*countspiritball {<char_id>};
2495
2496Counts the spirit ball that player has.
2497
2498---------------------------------------
2499
2500*ignoretimeout <flag>{,<char_id>};
2501
2502Disables the SECURE_NPCTIMEOUT function on the character invoking the script,
2503or by the given character ID/character name.
2504
2505Valid flag:
2506 0 - Enabled SECURE_NPCTIMEOUT.
2507 1 - Disable SECURE_NPCTIMEOUT.
2508
2509Note: SECURE_NPCTIMEOUT must be enabled for this to work.
2510
2511---------------------------------------
2512\\
25132,2 Item-related commands
2514\\
2515---------------------------------------
2516
2517*getequipid({<equipment slot>,<char_id>})
2518
2519This function returns the item ID of the item slot that calls the script
2520on the invoking character or the specified equipment slot. If nothing is
2521equipped there, it returns -1.
2522Valid equipment slots are:
2523
2524EQI_COMPOUND_ON (-1) - Item slot that calls this script (In context of item script)
2525EQI_ACC_L (0) - Accessory 1
2526EQI_ACC_R (1) - Accessory 2
2527EQI_SHOES (2) - Footgear (shoes, boots)
2528EQI_GARMENT (3) - Garment (mufflers, hoods, manteaux)
2529EQI_HEAD_LOW (4) - Lower Headgear (beards, some masks)
2530EQI_HEAD_MID (5) - Middle Headgear (masks, glasses)
2531EQI_HEAD_TOP (6) - Upper Headgear
2532EQI_ARMOR (7) - Armor (jackets, robes)
2533EQI_HAND_L (8) - Left hand (weapons, shields)
2534EQI_HAND_R (9) - Right hand (weapons)
2535EQI_COSTUME_HEAD_TOP (10) - Upper Costume Headgear
2536EQI_COSTUME_HEAD_MID (11) - Middle Costume Headgear
2537EQI_COSTUME_HEAD_LOW (12) - Lower Costume Headgear
2538EQI_COSTUME_GARMENT (13) - Costume Garment
2539EQI_AMMO (14) - Arrow/Ammunition
2540EQI_SHADOW_ARMOR (15) - Shadow Armor
2541EQI_SHADOW_WEAPON (16) - Shadow Weapon
2542EQI_SHADOW_SHIELD (17) - Shadow Shield
2543EQI_SHADOW_SHOES (18) - Shadow Shoes
2544EQI_SHADOW_ACC_R (19) - Shadow Accessory 2
2545EQI_SHADOW_ACC_L (20) - Shadow Accessory 1
2546
2547Notice that a few items occupy several equipment slots, and if the character is
2548wearing such an item, 'getequipid' will return its ID number for either slot.
2549
2550Can be used to check if you have something equipped, or if you haven't got
2551something equipped:
2552
2553 if (getequipid(EQI_HEAD_TOP) == 2234)
2554 mes "What a lovely Tiara you have on";
2555 else
2556 mes "Come back when you have a Tiara on";
2557 close;
2558
2559You can also use it to make sure people don't pass a point before removing an
2560item totally from them. Let's say you don't want people to wear Legion Plate
2561armor, but also don't want them to equip if after the check, you would do this:
2562
2563 if (getequipid(EQI_ARMOR) == 2341 || getequipid(EQI_ARMOR) == 2342) {
2564 mes "You are wearing some Legion Plate Armor, please drop that in your stash before continuing";
2565 close;
2566 }
2567 // the || is used as an or argument, there is 2341 and 2342 cause there are
2568 // two different legion plate armors, one with a slot one without.
2569
2570 if (countitem(2341) > 0 || countitem(2432) > 0) {
2571 mes "You have some Legion Plate Armor in your inventory, please drop that in your stash before continuing";
2572 close;
2573 }
2574 mes "I will lets you pass.";
2575 close2;
2576 warp "place",50,50;
2577 end;
2578
2579---------------------------------------
2580
2581*getequipuniqueid(<equipment slot>{,<char_id>})
2582
2583This function returns the unique ID (as a string) of the item equipped in the equipment slot
2584specified on the invoking character. If nothing is equipped there, it returns an empty string.
2585See 'getequipid' for a full list of valid equipment slots.
2586
2587---------------------------------------
2588
2589*getequipname(<equipment slot>{,<char_id>})
2590
2591Returns the jname of the item equipped in the specified equipment slot on the
2592invoking character, or an empty string if nothing is equipped in that position.
2593Does the same thing as getitemname(getequipid()). Useful for an NPC to state
2594what your are wearing, or maybe saving as a string variable.
2595See 'getequipid' for a full list of valid equipment slots.
2596
2597 if ( getequipname(EQI_HEAD_TOP) != "" )
2598 mes "So you are wearing a " + getequipname(EQI_HEAD_TOP) + " on your head";
2599 else
2600 mes "You are not wearing any head gear";
2601
2602---------------------------------------
2603
2604*getitemname(<item id>)
2605
2606Given the database ID number of an item, this function will return the text
2607stored in the 'japanese name' field (which, in rAthena, stores an English name
2608the players would normally see on screen.)
2609
2610---------------------------------------
2611
2612*getbrokenid(<number>{,<char_id>})
2613
2614This function will search the invoking character's inventory for any broken
2615items, and will return their item ID numbers. Since the character may have
2616several broken items, 1 given as an argument will return the first one found, 2
2617will return the second one, etc. Will return 0 if no such item is found.
2618
2619 // Let's see if they have anything broken:
2620 if (getbrokenid(1) == 0)
2621 mes "You don't have anything broken, quit bothering me.";
2622 else
2623 // They do, so let's print the name of the first broken item:
2624 mes "Oh, I see you have a broken " + getitemname(getbrokenid(1)) + " here!";
2625 end;
2626
2627---------------------------------------
2628
2629*getequipisequiped(<equipment slot>{,<char_id>})
2630
2631This functions will return 1 if there is an equipment placed on the specified
2632equipment slot and 0 otherwise. For a list of equipment slots
2633see 'getequipid'. Function originally used by the refining NPCs:
2634
2635 if (getequipisequiped(EQI_HEAD_TOP)) {
2636 mes "[Refiner]";
2637 mes "That's a fine hat you are wearing there...";
2638 close;
2639 } else {
2640 mes "[Refiner]";
2641 mes "Do you want me to refine your dumb head?";
2642 close;
2643 }
2644
2645---------------------------------------
2646
2647*getequipisenableref(<equipment slot>{,<char_id>})
2648
2649Will return 1 if the item equipped on the invoking character in the specified
2650equipment slot is refinable, and 0 if it isn't. For a list of equipment slots
2651see 'getequipid'.
2652
2653 if (getequipisenableref(EQI_HEAD_TOP)) {
2654 mes "[Refiner]";
2655 mes "Ok I can refine this";
2656 close;
2657 } else {
2658 mes "[Refiner]";
2659 mes "I can't refine this hat!...";
2660 close;
2661 }
2662
2663---------------------------------------
2664
2665*getequiprefinerycnt(<equipment slot>{,<char_id>})
2666
2667Returns the current number of pluses for the item in the specified equipment
2668slot. For a list of equipment slots see 'getequipid'.
2669
2670Can be used to check if you have reached a maximum refine value, default for
2671this is +10:
2672
2673 if (getequiprefinerycnt(EQI_HEAD_TOP) < 10)
2674 mes "I will now upgrade your " + getequipname(EQI_HEAD_TOP);
2675 else
2676 mes "Sorry, it's not possible to refine hats better than +10";
2677 close;
2678
2679---------------------------------------
2680
2681*getequipweaponlv(<equipment slot>{,<char_id>})
2682
2683This function returns the weapon level for the weapon equipped in the specified
2684equipment slot on the invoking character. For a list of equipment slots see
2685'getequipid'.
2686
2687Only EQI_HAND_L and EQI_HAND_R normally make sense, since only weapons have
2688a weapon level. You can, however, probably, use this field for other equippable
2689custom items as a flag or something.
2690
2691If no item is equipped in this slot, or if it doesn't have a weapon level
2692according to the database, 0 will be returned.
2693
2694Examples:
2695
2696// Right hand can only contain a weapon.
2697 switch (getequipweaponlv(EQI_HAND_R)) {
2698 case 1: mes "You are holding a lvl 1 weapon."; break;
2699 case 2: mes "You are holding a lvl 2 weapon."; break;
2700 case 3: mes "You are holding a lvl 3 weapon."; break;
2701 case 4: mes "You are holding a lvl 4 weapon."; break;
2702 case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break;
2703 default: mes "Seems you don't have a weapon on."; break;
2704 }
2705
2706// Left hand can hold either a weapon or shield.
2707 if (getequipid(EQI_HAND_R) == 0) {
2708 mes "Seems you have nothing equipped here.";
2709 close;
2710 }
2711 switch (getequipweaponlv(EQI_HAND_L)) {
2712 case 0: mes "You are holding a shield, so it doesn't have a level."; break;
2713 case 1: mes "You are holding a lvl 1 weapon."; break;
2714 case 2: mes "You are holding a lvl 2 weapon."; break;
2715 case 3: mes "You are holding a lvl 3 weapon."; break;
2716 case 4: mes "You are holding a lvl 4 weapon."; break;
2717 case 5: mes "You are holding a lvl 5 weapon, hm, must be a custom design..."; break;
2718 }
2719
2720---------------------------------------
2721
2722*getequippercentrefinery(<equipment slot>{,<enriched>,<char_id>})
2723
2724This function calculates and returns the percent value chance to successfully
2725refine the item found in the specified equipment slot of the invoking character
2726by +1. There is no actual formula, the success rate for a given weapon level of
2727a certain refine level is found in the db/(pre-)re/refine_db.yml file. For a list of
2728equipment slots see 'getequipid'.
2729
2730If enriched parameter is set to true, chance to successfully refine the item with
2731enriched material is returned instead.
2732
2733These values can be displayed for the player to see, or used to calculate the
2734random change of a refine succeeding or failing and then going through with it
2735(which is what the official NPC refinery scripts use it for)
2736
2737// This will find a random number from 0 - 99 and if that is equal to or more
2738// than the value recovered by this command it will go to L_Fail
2739 if (getequippercentrefinery(EQI_HAND_L)<=rand(100)) goto L_Fail;
2740
2741---------------------------------------
2742
2743*getequiprefinecost(<equipment slot>,<type>,<information>{,<char id>})
2744
2745This function returns refine cost for equipment in <equipment slot> based on
2746passed arguments <type> and <information>.
2747
2748Valid cost types are:
2749
2750REFINE_COST_NORMAL - For normal refining
2751REFINE_COST_OVER10 - For refining over +10
2752REFINE_COST_HD - For refining with HD ores
2753REFINE_COST_ENRICHED - For refining with enriched ores
2754REFINE_COST_OVER10_HD - For refining over +10 with HD ores
2755
2756This function will return required cost for refining based on <information> argument.
2757
2758Valid information types are:
2759
2760REFINE_ZENY_COST - Zeny
2761REFINE_MATERIAL_ID - Material Item ID
2762
2763This function will return -1 on failure. The function fails if the cost type
2764is invalid or if there is no item in the equipment slot.
2765
2766---------------------------------------
2767
2768*getareadropitem("<map name>",<x1>,<y1>,<x2>,<y2>,<item>)
2769
2770This function will count all the items with the specified ID number lying on the
2771ground on the specified map within the x1/y1-x2/y2 square on it and return that
2772number.
2773
2774This is the only function around where a parameter may be either a string or a
2775number! If it's a number, it means that only the items with that item ID number
2776will be counted. If it is a string, it is assumed to mean the 'english name'
2777field from the item database. If you give it an empty string, or something that
2778isn't found from the item database, it will count items number '512' (apples).
2779
2780---------------------------------------
2781
2782*getequipcardcnt(<equipment slot>)
2783
2784This function will return the number of cards that have been compounded onto a
2785specific equipped item for the invoking character. See 'getequipid' for a list
2786of possible equipment slots.
2787
2788---------------------------------------
2789
2790*getinventorylist {<char_id>};
2791
2792This command sets a bunch of arrays with a complete list of whatever the
2793invoking character has in their inventory, including all the data needed to
2794recreate these items perfectly if they are destroyed. Here's what you get:
2795
2796@inventorylist_id[] - array of item ids.
2797@inventorylist_amount[] - their corresponding item amounts.
2798@inventorylist_equip[] - on which position the item is equipped (see EQP_* constants)
2799 It will contain 0 if the item is not equipped.
2800@inventorylist_refine[] - for how much it is refined.
2801@inventorylist_identify[] - whether it is identified.
2802@inventorylist_attribute[] - whether it is broken.
2803@inventorylist_card1[] - These four arrays contain card data for the items.
2804@inventorylist_card2[] These data slots are also used to store names
2805@inventorylist_card3[] inscribed on the items, so you can explicitly check
2806@inventorylist_card4[] if the character owns an item made by a specific
2807 craftsman.
2808@inventorylist_expire[] - expire time (Unix time stamp). 0 means never expires.
2809@inventorylist_bound[] - the bound type of the items (see BOUND_* constants)
2810@inventorylist_count - the number of items in these lists.
2811
2812This could be handy to save/restore a character's inventory, since no other
2813command returns such a complete set of data, and could also be the only way to
2814correctly handle an NPC trader for carded and named items who could resell them
2815- since NPC objects cannot own items, so they have to store item data in
2816variables and recreate the items.
2817
2818Notice that the variables this command generates are all temporary, attached to
2819the character, and integer.
2820
2821Be sure to use @inventorylist_count to go through these arrays, and not
2822'getarraysize', because the arrays are not automatically cleared between runs
2823of 'getinventorylist'.
2824
2825---------------------------------------
2826
2827*cardscnt()
2828
2829This function will return the number of cards inserted into the equipment
2830from which the function is called.
2831
2832This function is intended for use in item scripts.
2833
2834---------------------------------------
2835
2836*getrefine()
2837
2838This function will return the refine count of the equipment from which the
2839function is called.
2840
2841This function is intended for use in item scripts.
2842
2843---------------------------------------
2844
2845*getnameditem(<item id>,"<name to inscribe>"|<char id>);
2846*getnameditem("<item name>","<name to inscribe>"|<char id>);
2847
2848This function is equivalent to using 'getitem', however, it will not just give
2849the character an item object, but will also inscribe it with a specified
2850character's name. You may not inscribe items with arbitrary strings, only with
2851names of characters that actually exist. While this isn't said anywhere
2852specifically, apparently, named items may not have cards in them, slots or no -
2853these data slots are taken by the character ID who's name is inscribed. Only one
2854remains free and it's not quite clear if a card may be there.
2855
2856This function will return 1 if an item was successfully created and 0 if it
2857wasn't for whatever reason. Like 'getitem', this function will also accept an
2858'english name' from the item database as an item name and will return 0 if no
2859such item exists.
2860
2861---------------------------------------
2862
2863*getitemslots(<item ID>)
2864
2865This function will look up the item with the specified ID number in the database
2866and return the number of slots this kind of items has - 0 if they are not
2867slotted. It will also be 0 for all non-equippable items, naturally, unless
2868someone messed up the item database. It will return -1 if there is no such item.
2869
2870Example:
2871
2872//.@slots now has the amount of slots of the item with ID 1205.
2873 .@slots = getitemslots(1205);
2874
2875---------------------------------------
2876
2877*getiteminfo(<item ID>,<type>)
2878
2879This function will look up the item with the specified ID number in the database
2880and return the info set by TYPE argument.
2881It will return -1 if there is no such item.
2882
2883Valid types are:
2884 0 - Buy Price
2885 1 - Sell Price
2886 2 - Type
2887 3 - maxchance (max drop chance of this item, e.g. 1 = 0.01%)
2888 if = 0, then monsters don't drop it at all (rare or a quest item)
2889 if = 10000, then this item is sold in NPC shops only
2890 4 - Gender
2891 5 - Loc
2892 6 - Weight
2893 7 - ATK
2894 8 - DEF
2895 9 - Range
2896 10 - Slot
2897 11 - View
2898 12 - eLV
2899 13 - wLV
2900 14 - SpriteID from 'db/item_avail.txt'
2901 15 - eLVMax
2902 16 - matk if RENEWAL is defined
2903
2904See the sample in 'doc/sample/getiteminfo.txt'.
2905
2906---------------------------------------
2907
2908*getequipcardid(<equipment slot>,<card slot>)
2909
2910Returns value from equipped item slot in the indicated slot (0, 1, 2, or 3).
2911
2912This function returns CARD ID, CARD0_FORGE, CARD0_CREATE, or CARD0_PET (for card 0, if the item is produced).
2913It's useful for when you want to check whether an item contains cards or if it's signed.
2914
2915---------------------------------------
2916
2917*mergeitem({,<char_id>});
2918
2919Open merge item window to merge available item can be merged.
2920
2921Examples
29221. See the NPC 'npc/re/other/merge_item.txt'.
29232. Simple usage:
2924 mes "Let's check if any item can be merged.";
2925 close2;
2926 mergeitem;
2927 end;
2928
2929---------------------------------------
2930
2931*mergeitem2({<item_id>{,<char_id>}});
2932*mergeitem2({"<item name>"{,<char_id>}});
2933
2934Merge all stackable items that separated by GUID flags
2935(either by flag 4 item_flag.txt or GUID in item_group).
2936If no item ID/name given, all possible items in player's inventory will be merged.
2937
2938---------------------------------------
2939
2940*getequiptradability(<equipment slot>{,<char id>});
2941
2942Returns true if the item in <equipment slot> is tradable.
2943Returns false otherwise.
2944
2945---------------------------------------
2946//
29472,1.- End of item-related commands.
2948//
2949---------------------------------------
2950
2951*getmapxy("<variable for map name>",<variable for x>,<variable for y>,<type>{,"<search string>"})
2952
2953This function will locate a character object, NPC object or pet's coordinates
2954and place their coordinates into the variables specified when calling it. It
2955will return 0 if the search was successful, and -1 if the parameters given were
2956not variables or the search was not successful.
2957
2958Type is the type of object to search for:
2959
2960 UNITTYPE_PC - Character object
2961 UNITTYPE_NPC - NPC object
2962 UNITTYPE_PET - Pet object
2963 UNITTYPE_HOM - Homunculus object
2964 UNITTYPE_MER - Mercenary object
2965 UNITTYPE_ELEM - Elemental object
2966
2967The search string is optional. If it is not specified, the location of the
2968invoking character will always be returned for types UNITTYPE_PC and UNITTYPE_PET,
2969the location of the NPC running this function for type 1.
2970
2971If a search string is specified, for types UNITTYPE_PC and UNITTYPE_NPC, the
2972character or NPC with the specified name will be located.
2973
2974If type is UNITTYPE_PET/UNITTYPE_HOM/UNITTYPE_MER/UNITTYPE_ELEM, the search
2975will locate the current object of the character who's name is given in the
2976search string, it will NOT locate the object by name.
2977
2978Example:
2979
2980 prontera,164,301,3%TAB%script%TAB%Meh%TAB%730,{
2981 mes "My name is Meh. I'm here so that Nyah can find me.";
2982 close;
2983 }
2984
2985 prontera,164,299,3%TAB%script%TAB%Nyah%TAB%730,{
2986 mes "My name is Nyah.";
2987 mes "I will now search for Meh all across the world!";
2988 if (getmapxy(@mapname$, @mapx, @mapy, UNITTYPE_NPC, "Meh") != 0) {
2989 mes "I can't seem to find Meh anywhere!";
2990 close;
2991 }
2992 mes "And I found him on map " + @mapname$ + " at X:" + @mapx + " Y:" + @mapy + " !";
2993 close;
2994 }
2995
2996Notice that NPC objects disabled with 'disablenpc' will still be located.
2997
2998---------------------------------------
2999
3000*mapid2name(<map ID>)
3001
3002Returns the map name of the given map ID. Returns an empty string if given
3003map ID doesn't exist.
3004
3005---------------------------------------
3006
3007*getgmlevel({<char_id>})
3008
3009This function will return the (GM) level associated with the player group to which
3010the invoking character belongs. If this is somehow executed from a console command,
301199 will be returned, and 0 will be returned if the account has no GM level.
3012
3013This allows you to make NPC's only accessible for certain GM levels, or behave
3014specially when talked to by GMs.
3015
3016 if (getgmlevel()) mes "What is your command, your godhood?";
3017
3018---------------------------------------
3019
3020*getgroupid({<char_id>})
3021
3022This function will return the group id to which the invoking player belongs.
3023
3024---------------------------------------
3025
3026*gettimetick(<tick type>)
3027
3028This function will return a tick depending on <tick type>:
3029 0: The server's tick, a measurement in milliseconds used by the server's timer
3030 system. This tick is an unsigned int which loops every ~50 days.
3031 1: The time, in seconds, since the start of the current day.
3032 2: The system time in UNIX epoch time, or the number of seconds elapsed since
3033 January 1st, 1970. Useful for reliably measuring time intervals.
3034
3035---------------------------------------
3036
3037*gettime(<type>)
3038
3039This function will return specified information about the current system time.
3040
3041DT_SECOND - Seconds (of the current minute)
3042DT_MINUTE - Minutes (of the current hour)
3043DT_HOUR - Hour (of the current day)
3044DT_DAYOFWEEK - Week day (constants for MONDAY to SUNDAY are available)
3045DT_DAYOFMONTH - Day of the current month
3046DT_MONTH - Month (constants for JANUARY to DECEMBER are available)
3047DT_YEAR - Year
3048DT_DAYOFYEAR - Day of the year
3049
3050It will only return numbers. If another type is supplied -1 will be returned.
3051
3052 if (gettime(DT_DAYOFWEEK) == SATURDAY) mes "It's a Saturday. I don't work on Saturdays.";
3053
3054---------------------------------------
3055
3056*gettimestr(<"time format">,<max length>{,<time_tick>})
3057
3058This function will return a string containing time data as specified by the
3059time format.
3060
3061This uses the C function 'strfmtime', which obeys special format characters. For
3062a full description see, for example, the description of 'strfmtime' at
3063http://www.delorie.com/gnu/docs/glibc/libc_437.html
3064All the format characters given in there should properly work.
3065Max length is the maximum length of a time string to generate.
3066
3067The example given in rAthena sample scripts works like this:
3068
3069 mes gettimestr("%Y-%m/%d %H:%M:%S",21);
3070
3071The example above will print the current date and time like 'YYYY-MM/DD HH:MM:SS'.
3072The following example will print the date and time when the player's VIP status
3073expires by the given <time_tick>:
3074
3075 mes gettimestr("%Y-%m/%d %H:%M:%S",21,vip_status(VIP_STATUS_EXPIRE));
3076
3077---------------------------------------
3078
3079*getusers(<type>)
3080
3081This function will return a number of users on a map or the whole server. What
3082it returns is specified by Type.
3083
3084Type can be one of the following values, which control what will be returned:
3085
3086 0 - Count of all characters on the map of the invoking character.
3087 1 - Count of all characters in the entire server.
3088 8 - Count of all characters on the map of the NPC the script is
3089 running in.
3090
3091---------------------------------------
3092
3093*getmapusers("<map name>")
3094
3095This function will return the number of users currently located on the specified
3096map.
3097
3098This is used officially in PVP scripts to check whether a room is filled to capacity.
3099
3100---------------------------------------
3101
3102*getareausers("<map name>",<x1>,<y1>,<x2>,<y2>)
3103
3104This function will return the count of connected characters which are located
3105within the specified area - an x1/y1-x2/y2 square on the specified map.
3106
3107This is useful for maps that are split into many buildings, such as all the
3108"*_in" maps, due to all the shops and houses.
3109
3110---------------------------------------
3111\\
31122,2.- Guild-related commands
3113\\
3114---------------------------------------
3115
3116*getguildname(<guild id>)
3117
3118This function returns a guild's name given an ID number. If there is no such
3119guild, "null" will be returned.
3120
3121Example:
3122 mes "The guild " + getguildname(10007) + " are all nice people.";
3123
3124---------------------------------------
3125
3126*getguildmember <guild id>{,<type>{,<array_variable>}};
3127
3128This command will find all members of a specified guild and returns their names
3129(or character id or account id depending on the value of "type") into an array
3130of temporary global variables.
3131
3132Upon executing this,
3133
3134$@guildmembername$[] is a global temporary string array which contains all the
3135 names of these guild members.
3136 (only set when type is 0 or not specified)
3137
3138$@guildmembercid[] is a global temporary number array which contains the
3139 character id of these guild members.
3140 (only set when type is 1)
3141
3142$@guildmemberaid[] is a global temporary number array which contains the
3143 account id of these guild members.
3144 (only set when type is 2)
3145
3146$@guildmembercount is the number of guild members that were found.
3147
3148The guild members will be found regardless of whether they are online or offline.
3149Note that the names come in no particular order.
3150
3151Be sure to use $@guildmembercount to go through this array, and not
3152'getarraysize', because it is not cleared between runs of 'getguildmember'.
3153
3154If 'array_variable' is set, the result will be stored to that variable instead
3155using global variable.
3156
3157For usage examples, see 'getpartymember'.
3158
3159---------------------------------------
3160
3161*getguildmaster(<guild id>)
3162
3163This function return the name of the master of the guild which has the specified
3164ID number. If there is no such guild, "null" will be returned.
3165
3166Example 1:
3167 // Prints the guild master of guild 10007, whoever that might be.
3168 mes getguildmaster(10007) + " runs " + getguildname(10007);
3169
3170Example 2:
3171 // Checks if the character is the guild master of the specified guild.
3172 .@GID = getcharid(2);
3173 if (.@GID == 0) {
3174 mes "Sorry, you are not in a guild.";
3175 close;
3176 }
3177 if (strcharinfo(0) != getguildmaster(.@GID)) {
3178 mes "Sorry, you don't own the guild you are in.";
3179 close;
3180 }
3181 mes "Welcome, guild master of " + getguildname(.@GID);
3182 close;
3183
3184---------------------------------------
3185
3186*getguildmasterid(<guild id>)
3187
3188This function will return the character ID number of the guild master of the
3189guild specified by the ID. 0 if the character is not a guild master of any guild.
3190
3191---------------------------------------
3192
3193*getcastlename("<map name>")
3194
3195This function returns the name of the castle when given the map name for that
3196castle. The data is read from 'db/castle_db.txt'.
3197
3198---------------------------------------
3199
3200*getcastledata("<map name>",<type of data>)
3201*setcastledata "<map name>",<type of data>,<value>;
3202
3203This function returns the castle ownership information for the castle referred
3204to by its map name. Castle information is stored in `guild_castle` SQL table.
3205
3206Types of data correspond to `guild_castle` table columns:
3207
3208 1 - `guild_id` - Guild ID.
3209 2 - `economy` - Castle Economy score.
3210 3 - `defense` - Castle Defense score.
3211 4 - `triggerE` - Number of times the economy was invested in today.
3212 5 - `triggerD` - Number of times the defense was invested in today.
3213 6 - `nextTime` - unused
3214 7 - `payTime` - unused
3215 8 - `createTime` - unused
3216 9 - `visibleC` - Is 1 if a Kafra was hired for this castle, 0 otherwise.
321710 - `visibleG0` - Is 1 if the 1st guardian is present (Soldier Guardian)
321811 - `visibleG1` - Is 1 if the 2nd guardian is present (Soldier Guardian)
321912 - `visibleG2` - Is 1 if the 3rd guardian is present (Soldier Guardian)
322013 - `visibleG3` - Is 1 if the 4th guardian is present (Archer Guardian)
322114 - `visibleG4` - Is 1 if the 5th guardian is present (Archer Guardian)
322215 - `visibleG5` - Is 1 if the 6th guardian is present (Knight Guardian)
322316 - `visibleG6` - Is 1 if the 7th guardian is present (Knight Guardian)
322417 - `visibleG7` - Is 1 if the 8th guardian is present (Knight Guardian)
3225
3226All types of data have their meaning determined by War of Emperium scripts,
3227with exception of:
3228 - `guild_id` that is always considered ID of the guild that owns the castle,
3229 - `defense` that is used in Guardians & Emperium HP calculations,
3230 - `visibleG` that is always considered to hold guardian presence bits.
3231
3232The 'setcastledata' command will behave identically, but instead of returning
3233values for the specified types of accessible data, it will alter them and cause
3234them to be sent to the char-server for storage.
3235
3236Changing Guild ID or Castle Defense will trigger additional actions, like
3237recalculating guardians' HP.
3238
3239---------------------------------------
3240
3241*getgdskilllv(<guild id>,<skill id>)
3242*getgdskilllv(<guild id>,"<skill name>")
3243
3244This function returns the level of the skill <skill id> of the guild <guild id>.
3245If the guild does not have that skill, 0 is returned.
3246If the guild does not exist, -1 is returned.
3247Refer to 'db/(pre-)re/skill_db.txt' for the full list of skills. (GD_* are guild skills)
3248
3249---------------------------------------
3250
3251*requestguildinfo <guild id>{,"<event label>"};
3252
3253This command requests the guild data from the char server and merrily continues
3254with the execution. Whenever the guild information becomes available (which
3255happens instantly if the guild information is already in memory, or later, if it
3256isn't and the map server has to wait for the char server to reply) it will run
3257the specified event as in a 'donpcevent' call.
3258
3259---------------------------------------
3260
3261*getmapguildusers("<map name>",<guild id>)
3262
3263Returns the amount of characters from the specified guild on the given map.
3264
3265Example:
3266
3267mes "You have " + getMapGuildUsers("prontera",getcharid(2)) + " guild members in Prontera.";
3268
3269---------------------------------------
3270//
32712,2.- End of guild-related commands
3272//
3273---------------------------------------
3274
3275*getskilllv(<skill id>)
3276*getskilllv("<skill name>")
3277
3278This function returns the level of the specified skill that the invoking
3279character has. If they don't have the skill, 0 will be returned. The full list
3280of character skills is available in 'db/(pre-)re/skill_db.txt'.
3281
3282There are two main uses for this function, it can check whether the character
3283has a skill or not, and it can tell you if the level is high enough.
3284
3285Example 1:
3286 if (getskilllv(152))
3287 mes "You have got the skill Throw Stone";
3288 else
3289 mes "You don't have Throw Stone";
3290 close;
3291
3292Example 2:
3293 if (getskilllv(28) >= 5)
3294 mes "Your heal lvl is 5 or more";
3295 else if (getskilllv(28) == 10)
3296 mes "Your heal lvl has been maxed";
3297 else
3298 mes "You heal skill is below lvl 5";
3299 close;
3300
3301---------------------------------------
3302
3303*getskilllist({<char_id>});
3304
3305This command sets a bunch of arrays with a complete list of skills the
3306invoking character has. Here's what you get:
3307
3308@skilllist_id[] - skill ids.
3309@skilllist_lv[] - skill levels.
3310@skilllist_flag[] - see 'skill' for the meaning of skill flags.
3311@skilllist_count - number of skills in the above arrays.
3312
3313While 'getskillv' is probably more useful for most situations, this is the
3314easiest way to store all the skills and make the character something else for a
3315while. Advanced job for a day? This could also be useful to see how many
3316skills a character has.
3317
3318This command does not count skills which are set as flag 4 (permament granted) (ALL_BUYING_STORE/ALL_INCCARRY)
3319
3320---------------------------------------
3321
3322*getmonsterinfo(<mob ID>,<type>)
3323
3324This function will look up the monster with the specified ID number in the
3325mob database and return the info set by TYPE argument.
3326It will return -1 if there is no such monster (or the type value is invalid),
3327or "null" if you requested the monster's name.
3328
3329Valid types are:
3330 MOB_NAME - monster's name, if there is no such monster "null" is returned
3331 MOB_LV - monster's level
3332 MOB_MAXHP - monster's maximum hp
3333 MOB_BASEEXP - monster's base experience
3334 MOB_JOBEXP - monster's job experience
3335 MOB_ATK1 - monster's atk
3336 MOB_ATK2 - monster's atk2
3337 MOB_DEF - monster's def
3338 MOB_MDEF - monster's mdef
3339 MOB_STR - monster's str
3340 MOB_AGI - monster's agi
3341 MOB_VIT - monster's vit
3342 MOB_INT - monster's int
3343 MOB_DEX - monster's dex
3344 MOB_LUK - monster's luk
3345 MOB_RANGE - monster's range
3346 MOB_RANGE2 - monster's range2
3347 MOB_RANGE3 - monster's range3
3348 MOB_SIZE - monster's size
3349 MOB_RACE - monster's race
3350 MOB_ELEMENT - monster's element(doesn't return the element level, only the element ID)
3351 MOB_MODE - monster's mode
3352 MOB_MVPEXP - monster's mvp experience
3353
3354For more details, see the sample in 'doc/sample/getmonsterinfo.txt'.
3355
3356---------------------------------------
3357
3358*getmobdrops(<mob id>)
3359
3360This command will find all drops of the specified mob and return the item IDs
3361and drop percentages into arrays of temporary global variables.
3362'getmobdrops' returns 1 if successful and 0 if the mob ID doesn't exist.
3363
3364Upon executing this,
3365
3366$@MobDrop_item[] is a global temporary number array which contains the
3367 item IDs of the monster's drops.
3368
3369$@MobDrop_rate[] is a global temporary number array which contains the
3370 drop percentages of each item. (1 = .01%)
3371
3372$@MobDrop_count is the number of item drops found.
3373
3374Be sure to use $@MobDrop_count to go through the arrays, and not
3375'getarraysize', because the temporary global arrays are not cleared between
3376runs of 'getmobdrops'. If a mob with 7 item drops is looked up, the arrays would
3377have 7 elements. But if another mob is looked up and it only has 5 item drops,
3378the server will not clear the arrays for you, overwriting the values instead. So
3379in addition to returning the 5 item drops, the 6th and 7th elements from the
3380last call remain, and you will get 5+2 item drops, of which the last 2 don't
3381belong to the new mob. $@MobDrop_count will always contain the correct number
3382(5), unlike 'getarraysize()' which would return 7 in this case.
3383
3384Example:
3385
3386 // get a Mob ID from the user
3387 input .@mob_id;
3388
3389 if (getmobdrops(.@mob_id)) { // 'getmobdrops' returns 1 on success
3390 // immediately copy global temporary variables into scope variables,
3391 // since we don't know when 'getmobdrops' will get called again for
3392 // another mob, overwriting your global temporary variables
3393 .@count = $@MobDrop_count;
3394 copyarray .@item[0],$@MobDrop_item[0],.@count;
3395 copyarray .@rate[0],$@MobDrop_rate[0],.@count;
3396
3397 mes getmonsterinfo(.@mob_id,MOB_NAME) + " - " + .@count + " drops found:";
3398 for( .@i = 0; .@i < .@count; .@i++ ) {
3399 mes .@item[.@i] + " (" + getitemname(.@item[.@i]) + ") " + .@rate[.@i]/100 + ((.@rate[.@i]%100 < 10) ? ".0":".") + .@rate[.@i]%100 + "%";
3400 }
3401 } else {
3402 mes "Unknown monster ID.";
3403 }
3404 close;
3405
3406---------------------------------------
3407
3408*skillpointcount({<char_id>})
3409
3410Returns the total amount of skill points a character possesses (SkillPoint+SP's used in skills)
3411This command can be used to check the currently attached characters total amount of skill points.
3412This means the skill points used in skill are counted, and added to SkillPoints (number of skill points not used).
3413This command does not count skills which are set as flag 4 (permament granted) (ALL_BUYING_STORE/ALL_INCCARRY)
3414
3415Example 1:
3416 .@skillPoints = skillpointcount();
3417 mes "You have " + .@skillPoints + " skill points in total!";
3418
3419Example 2:
3420 if (skillpointcount() > 20)
3421 mes "Wow, you have more then 20 Skill Points in total!";
3422
3423---------------------------------------
3424
3425*getscrate(<effect type>,<base rate>{,<GID>})
3426
3427This function will return the chance of a status effect affecting the invoking
3428character, in percent, modified by the their current defense against said
3429status. The 'base rate' is the base chance of the status effect being inflicted,
3430in percent.
3431
3432 if (rand(100) > getscrate(Eff_Blind, 50)) goto BlindHimNow;
3433
3434You can see the full list of available effect types you can possibly inflict in
3435'db/const.txt' under 'Eff_'.
3436
3437---------------------------------------
3438
3439========================
3440|3.- Checking commands.|
3441========================
3442-------------------------
3443
3444*playerattached()
3445
3446Returns the ID of the player currently attached to the script. It will return
34470 if no one is attached, or if the attached player no longer exists on the map
3448server. It is wise to check for the attached player in script functions that
3449deal with timers as there's no guarantee the player will still be logged on
3450when the timer triggers. Note that the ID of a player is actually their
3451account ID.
3452
3453---------------------------------------
3454
3455*getattachedrid();
3456
3457Returns RID from running script. Script may not be attached to any RID like
3458a floating script or function and will return 0.
3459
3460---------------------------------------
3461
3462*isloggedin(<account id>{,<char id>})
3463
3464This function returns 1 if the specified account is logged in and 0 if they
3465aren't. You can also pass the char id to check for both account and char id.
3466
3467---------------------------------------
3468
3469*checkweight(<item id>,<amount>{,<item id>,<amount>,<item id>,<amount>,...});
3470*checkweight("<item name>",<amount>{,"<item name>",<amount>,"<item name>",<amount>,...});
3471*checkweight2(<id_array>,<amount_array>);
3472
3473These functions will compute and return 1 if the total weight of the specified
3474number of specific items does not exceed the invoking character's carrying
3475capacity, and 0 otherwise. It is important to see if a player can carry the
3476items you expect to give them, failing to do that may open your script up to
3477abuse or create some very unfair errors.
3478
3479The second function will check an array of items and amounts, and also
3480returns 1 on success and 0 on failure.
3481
3482The functions, in addition to checking to see if the player is capable of
3483holding a set amount of items, also ensure the player has room in their
3484inventory for the item(s) they will be receiving.
3485
3486Like 'getitem', this function will also accept an 'english name' from the
3487database as an argument.
3488
3489Example 1:
3490
3491 if (checkweight(512,10)) {
3492 getitem 512,10;
3493 } else {
3494 mes "Sorry, you cannot hold this amount of apples!";
3495 }
3496
3497Example 2:
3498
3499 setarray .@item[0],512,513,514;
3500 setarray .@amount[0],10,5,5;
3501 if (!checkweight2(.@item,.@amount)) {
3502 mes "Sorry, you cannot hold this amount of fruit!";
3503 }
3504
3505---------------------------------------
3506
3507*basicskillcheck()
3508
3509This function will return the state of the configuration option
3510'basic_skill_check' in 'battle_athena.conf'. It returns 1 if the option is
3511enabled and 0 if it isn't. If the 'basic_skill_check' option is enabled, which
3512it is by default, characters must have a certain number of basic skill levels to
3513sit, request a trade, use emotions, etc. Making your script behave differently
3514depending on whether the characters must actually have the skill to do all these
3515things might in some cases be required.
3516
3517---------------------------------------
3518
3519*checkoption(<option number>{,<char_id>})
3520*checkoption1(<option number>{,<char_id>})
3521*checkoption2(<option number>{,<char_id>})
3522*setoption <option number>{,<flag>{,<char_id>}};
3523
3524The 'setoption' series of functions check for a so-called option that is set on
3525the invoking character. 'Options' are used to store status conditions and a lot
3526of other non-permanent character data of the yes-no kind. For most common cases,
3527it is better to use 'checkcart','checkfalcon','checkriding' and other similar
3528functions, but there are some options which you cannot get at this way. They
3529return 1 if the option is set and 0 if the option is not set.
3530
3531Option numbers valid for the first (option) version of this command are:
3532
35330x1 - Sight in effect.
35340x2 - Hide in effect.
35350x4 - Cloaking in effect.
35360x8 - Cart number 1 present.
35370x10 - Falcon present.
35380x20 - Peco Peco present.
35390x40 - GM Perfect Hide in effect.
35400x80 - Cart number 2 present.
35410x100 - Cart number 3 present.
35420x200 - Cart number 4 present.
35430x400 - Cart number 5 present.
35440x800 - Orc head present.
35450x1000 - The character is wearing a wedding sprite.
35460x2000 - Ruwach is in effect.
35470x4000 - Chasewalk in effect.
35480x8000 - Flying or Xmas suit.
35490x10000 - Sighttrasher.
35500x100000 - Warg present.
35510x200000 - The character is riding a warg.
3552
3553Option numbers valid for the second version (opt1) of this command are:
3554
35551 - Petrified.
35562 - Frozen.
35573 - Stunned.
35584 - Sleeping.
35596 - Petrifying (the state where you can still walk)
3560
3561Option numbers valid for the third version (opt2) of this command are:
3562
35630x1 - Poisoned.
35640x2 - Cursed.
35650x4 - Silenced.
35660x8 - Signum Crucis (plays a howl-like sound effect, but otherwise no visible effects are displayed)
35670x10 - Blinded.
35680x80 - Deadly poisoned.
3569
3570Option numbers (except for opt1) are bit-masks - you can add them up to check
3571for several states, but the functions will return true if at least one of them
3572is in effect.
3573
3574'setoption' will set options on the invoking character. There are no second and
3575third versions of this command, so you can only change the values in the first
3576list (cloak, cart, ruwach, etc). if flag is 1 (default when omitted),
3577the option will be added to what the character currently has; if 0, the option is removed.
3578
3579This is definitely not a complete list of available option flag numbers. Ask a
3580core developer (or read the source: src/map/status.h) for the full list.
3581
3582---------------------------------------
3583
3584*setcart {<type>{,<char_id>}};
3585*checkcart({<char_id>});
3586
3587If <type> is 0 this command will remove the cart from the character.
3588Otherwise it gives the invoking character a cart. The cart given will be
3589cart number <type> and will work regardless of whether the character is a
3590merchant class or not.
3591Note: the character needs to have the skill MC_PUSHCART to gain a cart
3592
3593The accompanying function will return 1 if the invoking character has a cart
3594(any kind of cart) and 0 if they don't.
3595
3596 if (checkcart()) mes "But you already have a cart!";
3597
3598---------------------------------------
3599
3600*setfalcon {<flag>{,<char_id>}};
3601*checkfalcon({<char_id>});
3602
3603If <flag> is 0 this command will remove the falcon from the character.
3604Otherwise it gives the invoking character a falcon. The falcon will be there
3605regardless of whether the character is a hunter or not. It will (probably) not
3606have any useful effects for non-hunters though.
3607Note: the character needs to have the skill HT_FALCON to gain a falcon
3608
3609The accompanying function will return 1 if the invoking character has a falcon
3610and 0 if they don't.
3611
3612 if (checkfalcon()) mes "But you already have a falcon!";
3613
3614---------------------------------------
3615
3616*setriding {<flag>{,<char_id>}};
3617*checkriding({<char_id>});
3618
3619If <flag> is 0 this command will remove the mount from the character.
3620Otherwise it gives the invoking character a PecoPeco (if they are a Knight
3621series class), a GrandPeco (if they are a Crusader series class), or
3622a Gryphon (if they are a Royal Guard). Unlike 'setfalcon' and 'setcart'
3623this will not work at all if they aren't of a class which can ride.
3624Note: the character needs to have the skill KN_RIDING to gain a mount
3625
3626The accompanying function will return 1 if the invoking character is riding a
3627bird and 0 if they aren't.
3628
3629 if (checkriding()) mes "PLEASE leave your bird outside! No riding birds on the floor here!";
3630
3631---------------------------------------
3632
3633*setdragon {<color>{,<char_id>}};
3634*checkdragon({<char_id>});
3635
3636The 'setdragon' function toggles mounting a dragon for the invoking character.
3637It will return 1 if successful, 0 otherwise.
3638
3639The available colors are:
3640 1 - Green Dragon (default)
3641 2 - Brown Dragon
3642 3 - Gray Dragon
3643 4 - Blue Dragon
3644 5 - Red Dragon
3645
3646Note: the character must be a Rune Knight and have the skill RK_DRAGONTRAINING to gain a mount
3647
3648The accompanying function will return 1 if the invoking character is riding a
3649dragon and 0 if they aren't.
3650
3651---------------------------------------
3652
3653*setmadogear {<flag>{,<char_id>}};
3654*checkmadogear({<char_id>});
3655
3656If <flag> is 0 this command will remove the mount from the character.
3657Otherwise it gives the invoking character a Mado (if they are a Mechanic).
3658
3659The accompanying function will return 1 if the invoking character has a
3660Mado and 0 if they don't.
3661
3662---------------------------------------
3663
3664*setmounting {<char_id>};
3665*ismounting({<char_id>});
3666
3667The 'setmounting' function toggles cash mount for the invoking character.
3668It will return 1 if successful, 0 otherwise.
3669
3670Note: Character must not be mounting a non-cash mount (eg. dragon, peco, wug, etc.)
3671
3672The accompanying function will return 1 if the invoking character has a
3673cash mount and 0 if they don't.
3674
3675---------------------------------------
3676
3677*checkwug({<char_id>});
3678
3679This function will return 1 if the invoking character has a
3680warg and 0 if they don't.
3681
3682---------------------------------------
3683
3684*checkvending({"<Player Name>"})
3685
3686Checks if the player is vending or has has a buyingstore. Additionally
3687it gives you the information whether the player uses autotrade or not.
3688Name is optional, and defaults to the attached player if omitted.
3689
3690The returned value is bitmask of.
3691 0 = doesn't have a vending or buyingstore (which also means he can't use autotrade)
3692 1 = normal vending
3693 2 = using @autotrade
3694 4 = has a buyingstore
3695
3696Examples:
3697 //This will check Aaron's state
3698 .@state = checkvending("Aaron");
3699 if (.@state&1)
3700 mes "Aaron is currently vending!";
3701 if (.@state&4)
3702 mes "Aaron has a buying store!";
3703 if (.@state&2)
3704 mes "Aaron is autotrading!";
3705
3706---------------------------------------
3707
3708*checkchatting({"<Player Name>"})
3709
3710Checks if the player is in a chatroom.
3711Name is optional, and defaults to the attached player if omitted.
3712Returns 1 if they are in a chat room, 0 if they are not.
3713
3714Examples:
3715 //This will check if the attached player in a chat room or not.
3716 if (checkchatting())
3717 mes "You are currently in a chat room!";
3718
3719---------------------------------------
3720
3721*checkidle({"<Player Name>"})
3722
3723Returns the time, in seconds, that the specified player has been idle.
3724Name is optional, and defaults to the attached player if omitted.
3725
3726---------------------------------------
3727
3728*agitcheck()
3729*agitcheck2()
3730*agitcheck3()
3731
3732These function will let you check whether the server is currently in WoE:FE mode
3733(agitcheck()), WoE:SE mode (agitcheck2()), or WoE:TE mode (agitcheck3()) and will
3734return true if War of Emperium is on and false if it isn't.
3735
3736---------------------------------------
3737
3738*isnight()
3739*isday()
3740
3741These functions will return 1 or 0 depending on whether the server is in night
3742mode or day mode. 'isnight' returns 1 if it's night and 0 if it isn't, 'isday'
3743the other way around. They can be used interchangeably, pick the one you like
3744more:
3745
3746 // These two are equivalent:
3747 if (isday()) mes "I only prowl in the night.";
3748 if (isnight() != 1) mes "I only prowl in the night.";
3749
3750---------------------------------------
3751
3752*checkre(<type>)
3753
3754Checks if a renewal feature is enabled or not in renewal.h, and returns 1 if
3755enabled and 0 for disabled.
3756
3757The renewal feature to check is determined by type.
3758 0 - RENEWAL (game renewal server mode)
3759 1 - RENEWAL_CAST (renewal cast time)
3760 2 - RENEWAL_DROP (renewal drop rate algorithms)
3761 3 - RENEWAL_EXP (renewal exp rate algorithms)
3762 4 - RENEWAL_LVDMG (renewal level modifier on damage)
3763 5 - RENEWAL_ASPD (renewal ASPD)
3764
3765---------------------------------------
3766\\
37673,1.- Item-related commands
3768\\
3769---------------------------------------
3770
3771*isequipped(<id>{,<id>{,<id>{,<id>}}})
3772
3773This function will return 1 if the invoking character has all of the item
3774IDs given equipped (if card IDs are passed, then it checks if the cards are
3775inserted into slots in the equipment they are currently wearing). Theoretically
3776there is no limit to the number of items that may be tested for at the same time.
3777If even one of the items given is not equipped, 0 will be returned.
3778
3779 // (Poring,Santa Poring,Poporing,Marin)
3780 if (isequipped(4001,4005,4033,4196)) mes "Wow! You're wearing a full complement of possible poring cards!";
3781 // (Poring)
3782 if (isequipped(4001)) mes "A poring card is useful, don't you think?";
3783
3784The function was meant for item scripts to support the cards released by Gravity
3785in February 2005, but it will work just fine in normal NPC scripts.
3786
3787---------------------------------------
3788
3789*isequippedcnt(<card id>{,<card id>{,<card id>{,<card id>}}})
3790
3791This function is similar to 'isequipped', but instead of 1 or 0, it will return
3792the number of cards in the list given that were found on the invoking character.
3793
3794If a given parameter is not a card, the function returns the amount of that
3795item equipped on the invoking character.
3796
3797 if (isequippedcnt(4001,4005,4033,4196) == 4) mes "Finally got all four poring cards?";
3798
3799---------------------------------------
3800
3801*checkequipedcard(<card id>)
3802
3803This function will return 1 if the card specified by its item ID number is
3804inserted into any equipment they have in their inventory, currently equipped or
3805not.
3806
3807---------------------------------------
3808//
38093,1.- End of item-related commands
3810//
3811---------------------------------------
3812
3813==============================
3814|4.- Player-related commands.|
3815==============================
3816-------------------------
3817
3818*attachrid(<account ID>)
3819*detachrid;
3820
3821These commands allow the manipulation of the script's currently attached player.
3822While 'attachrid' allows attaching of a different player by using its account id
3823for the parameter RID, 'detachrid' makes the following commands run as if the
3824script was never invoked by a player.
3825
3826The command returns 0 if the player cannot be attached (if the account is offline
3827or does not exist), and 1 upon success.
3828
3829-------------------------
3830
3831*addrid(<type>{,<flag>{,<parameters>}});
3832
3833This command will attach other RIDs to the current script without detaching the
3834invoking RID. It returns 1 if successful and 0 upon failure.
3835
3836<type> determines what RIDs are attached:
3837 0: All players in the server.
3838 1: All players in the map of the invoking player, or the invoking NPC if no player is attached.
3839 2: Party members of a specified party ID.
3840 [ Parameters: <party id> ]
3841 3: Guild members of a specified guild ID.
3842 [ Parameters: <guild id> ]
3843 4: All players in a specified area of the map of the invoking player (or NPC).
3844 [ Parameters: <x0>,<y0>,<x1>,<y1> ]
3845 5: All players in the map.
3846 [ Parameters: "<map name>" ]
3847 Account ID: If type is Account ID, attach the specified account ID.
3848
3849<flag> can prevent certain players from being attached:
3850 0: Players are always attached. (default)
3851 1: Players currently running another script will not be attached.
3852
3853---------------------------------------
3854
3855*rid2name(<rid>)
3856
3857Converts rid to name. Note: The player/monster/NPC must be online/enabled.
3858Good for PCKillEvent where you can convert 'killedrid' to the name of the player.
3859
3860Note: rid2name may not produce correct character names since rid = account id.
3861 It will return the current online character of the account only.
3862
3863---------------------------------------
3864
3865*message "<character name>","<message>";
3866
3867That command will send a message to the chat window of the character specified
3868by name. The text will also appear above the head of that character. It will not
3869be seen by anyone else.
3870
3871---------------------------------------
3872
3873*dispbottom "<message>"{,<color>{,<char_id>}};
3874
3875This command will send the given message with color into the invoking character's chat
3876window. The color format is in RGB (0xRRGGBB). The color is
3877by default green
3878
3879---------------------------------------
3880
3881*showscript "<message>"{,<GID>, <flag>};
3882
3883Makes attached player or GID says a message like shouting a skill name, the message
3884will be seen to everyone around but not in chat window.
3885flag: Specify target
3886 AREA - Message is sent to players in the vicinity of the source (default).
3887 SELF - Message is sent only to player attached.
3888
3889---------------------------------------
3890
3891*warp "<map name>",<x>,<y>{,<char id>};
3892
3893This command will take the invoking character or <char id>, if specified, to the specified map, and if
3894wanted, specified coordinates too, but these can be random.
3895
3896 warp "place",50,55;
3897
3898This would take them to X 50 Y 55 on the map called "place". If your X and Y
3899coordinates land on an unwalkable map square, it will send the warped character
3900to a random place. Same will happen if they are both zero:
3901
3902 warp "place",0,0;
3903
3904Notice that while warping people to coordinates 0,0 will normally get them into
3905a random place, it's not certain to always be so. Darned if I know where this is
3906actually coded, it might be that this happens because square 0,0 is unwalkable
3907on all official maps. If you're using custom maps, beware.
3908
3909There are also three special 'map names' you can use.
3910
3911"Random" will warp the player randomly on the current map.
3912"Save" and "SavePoint" will warp the player back to their save point.
3913
3914---------------------------------------
3915
3916*areawarp "<from map name>",<x1>,<y1>,<x2>,<y2>,"<to map name>",<x3>,<y3>{,<x4>,<y4>};
3917
3918This command is similar to 'warp', however, it will not refer to the invoking
3919character, but instead, all characters within a specified area, defined by the
3920x1/y1-x2/y2 square, will be warped. Nobody outside the area will be affected,
3921including the activating character, if they are outside the area.
3922
3923 areawarp "place",10,10,120,120,"place2",150,150;
3924
3925Everyone that is in the area between X 10 Y 10 and X 120 Y 120, in a square
3926shape, on the map called "place", will be affected, and warped to "place2" X 150
3927Y 150
3928
3929 areawarp "place",10,10,120,120,"place2",0,0;
3930
3931By using ,0,0; as the destination coordinates it will take all the characters in
3932the affected area to a random set of co-ordinates on "place2".
3933
3934 areawarp "place",10,10,120,120,"place2",150,150,200,200;
3935
3936By using the optional x4 and y4 parameters, the destination coordinates will be a
3937random place within the defined x3/y3-x4/y4 square.
3938
3939Like 'warp', areawarp will also explicitly warp characters randomly into the
3940current map if you give the 'to map name' as "Random".
3941
3942See also 'warp'.
3943
3944---------------------------------------
3945
3946*warpparty "<to_mapname>",<x>,<y>,<party_id>,{"<from_mapname>",<range x>,<range y>};
3947
3948Warps a party to specified map and coordinate given the party ID, which you can get with
3949getcharid(1). You can also request another party id given a member's name with getcharid(1,<player_name>).
3950
3951You can use the following "map names" for special warping behavior:
3952Random: All party members are randomly warped in their current map (as if they
3953 all used a fly wing)
3954SavePointAll: All party members are warped to their respective save point.
3955SavePoint: All party members are warped to the save point of the currently
3956 attached player (will fail if there's no player attached).
3957Leader: All party members are warped to the leader's position. The leader must
3958 be online and in the current map-server for this to work.
3959
3960If you specify a from_mapname, 'warpparty' will only affect those on that map.
3961
3962The <range x> and <range y> optional values allow for a randomization with the
3963player's warp point. The values will randomly add or subtract from the given <x>
3964and <y> coordinates.
3965
3966Example:
3967 mes "[Party Warper]";
3968 mes "Here you go!";
3969 close2;
3970 .@party_id = getcharid(1);
3971 warpparty "prontera",150,100,.@party_id;
3972 close;
3973
3974---------------------------------------
3975
3976*warpguild "<map name>",<x>,<y>,<guild_id>;
3977
3978Warps a guild to specified map and coordinate given the guild id, which you can get with
3979getcharid(2). You can also request another guild id given the member's name with getcharid(2,<player_name>).
3980
3981You can use the following "map names" for special warping behavior:
3982Random: All guild members are randomly warped in their current map (as if they
3983 all used a fly wing)
3984SavePointAll: All guild members are warped to their respective save point.
3985SavePoint: All guild members are warped to the save point of the currently
3986 attached player (will fail if there's no player attached).
3987
3988Example:
3989
3990warpguild "prontera",x,y,Guild_ID;
3991
3992---------------------------------------
3993
3994*warppartner("<map name>",<x>,<y>);
3995
3996This function will find the invoking character's marriage partner, if any, and
3997warp them to the map and coordinates given. It will return 1 upon success and
39980 if the partner is not online, the character is not married, or if there's no
3999invoking character (no RID). 0,0 will, as usual, normally translate to random coordinates.
4000
4001---------------------------------------
4002
4003*savepoint "<map name>",<x>,<y>{,{<range x>,<range y>,}<char_id>};
4004*save "<map name>",<x>,<y>{,{<range x>,<range y>,}<char_id>};
4005
4006These commands save where the invoking character will return to upon clicking
4007"Return to Save Point", after death and in some other cases. The two versions are
4008equivalent. They ignore any and all mapflags, and can make a character respawn where
4009no teleportation is otherwise possible.
4010
4011The <range x> and <range y> optional values allow for a randomization with the
4012player's save point. The values will randomly add or subtract from the given <x>
4013and <y> coordinates.
4014
4015 savepoint "place",350,75;
4016 savepoint "place",350,75,2,2; // Randomly save the character between 348,73 and 352,77
4017
4018---------------------------------------
4019
4020*heal <hp>,<sp>{,<char_id>};
4021
4022This command will heal a set amount of HP and/or SP on the invoking character.
4023
4024 heal 30000,0; // This will heal 30,000 HP
4025 heal 0,30000; // This will heal 30,000 SP
4026 heal 300,300; // This will heal 300 HP and 300 SP
4027
4028This command just alters the hit points and spell points of the invoking
4029character and produces no other output whatsoever.
4030
4031---------------------------------------
4032
4033*itemheal <hp>,<sp>{,<char_id>};
4034
4035This command heals relative amounts of HP and/or SP on the invoking character.
4036Unlike heal, this command is intended for use in item scripts. It applies
4037potion-related bonuses, such as alchemist ranking, cards, and status changes.
4038When used inside an NPC script, certain bonuses are omitted.
4039
4040The command also applies a SP/VIT-related bonus:
4041 heal = heal * [(100 + STATUS*2) / 100]
4042
4043Example:
4044 // If the player has 50 vit and no bonuses, this will heal
4045 // anything from 200 to 300 HP and 5 SP
4046 itemheal rand(100,150),5;
4047
4048---------------------------------------
4049
4050*percentheal <hp>,<sp>{,<char_id>};
4051
4052This command will heal the invoking character. It heals the character, but not
4053by a set value - it adds percent of their maximum HP/SP.
4054
4055 percentheal 100,0; // This will heal 100% HP
4056 percentheal 0,100; // This will heal 100% SP
4057 percentheal 50,50; // This will heal 50% HP and 50% SP
4058
4059So the amount that this will heal will depend on the total amount of HP or SP
4060you have maximum. Like 'heal', this will not call up any animations or effects.
4061
4062---------------------------------------
4063
4064*recovery <type>{,<option>,<revive_flag>{,<map name>}};
4065
4066This command will revive and fully restore the HP/SP of the selected characters.
4067It returns 1 upon successful use.
4068
4069<type> is the target, and determines the <option> parameter:
4070 0: Player -> Character ID number
4071 1: Party -> Party ID number
4072 2: Guild -> Guild ID number
4073 3: Map -> Map name (a string)
4074 4: All -> None (takes <revive_flag> as option)
4075
4076If no option is specified, the invoking player's character ID, party ID, guild ID,
4077or map will be used.
4078
4079<revive_flag> determines the action:
4080 1: Revive and heal all players (default)
4081 2: Heal living players only
4082 4: Revive dead players only
4083
4084<map name> can optionally be used to define a single map to execute the command on
4085for types 1 (party) and 2 (guild).
4086
4087Examples:
4088 // Only revive characters in invoking party on map "morocc"
4089 recovery 1,getcharid(1),4,"morocc";
4090
4091 // Fully heal (don't revive) all members of invoking character's guild
4092 recovery 2,getcharid(2),2;
4093
4094 // Revive and fully heal everyone in map "prontera"
4095 recovery 3,"prontera";
4096
4097 // Only revive all dead characters on server
4098 recovery 4,4;
4099
4100---------------------------------------
4101
4102*jobchange <job number>{,<upper flag>,<char_id>};
4103
4104This command will change the job class of the invoking character.
4105
4106 jobchange 1; // This would change your player into a Swordman
4107 jobchange 4002; // This would change your player into a Swordman High
4108
4109This command does work with numbers, but you can also use job names. The full
4110list of job names and the numbers they correspond to can be found in
4111'src/map/script_constants.h'.
4112
4113 // This would change your player into a Swordman
4114 jobchange Job_Swordman;
4115 // This would change your player into a Swordman High
4116 jobchange Job_Swordman_High;
4117
4118'upper flag' can alternatively be used to specify the type of job one changes
4119to. For example, jobchange Job_Swordman,1; will change the character to a high
4120swordsman. The upper values are:
4121-1 (or when omitted): preserves the current job type.
41220: Normal/standard classes
41231: High/Advanced classes
41242: Baby classes
4125
4126This command will also set a permanent character-based variable
4127'jobchange_level' which will contain the job level at the time right before
4128changing jobs, which can be checked for later in scripts.
4129
4130---------------------------------------
4131
4132*jobname(<job number>)
4133
4134This command retrieves the name of the given job using the map_msg entries 550->655.
4135
4136 mes "[Kid]";
4137 mes "I never thought I'd met a " + jobname(Class) + " here of all places.";
4138 close;
4139
4140---------------------------------------
4141
4142*eaclass({<job number>,<char_id>})
4143
4144This commands returns the "eA job-number" corresponding to the given class, and
4145uses the invoking player's class if none is given. The eA job-number is also a
4146class number system, but it's one that comes with constants which make it easy
4147to convert among classes. The command will return -1 if you pass it a job number
4148which doesn't have an eA job-number equivalent.
4149
4150 @eac = eaclass();
4151 if ((@eac&EAJ_BASEMASK) == EAJ_SWORDMAN)
4152 mes "Your base job is Swordman.";
4153 if (@eac&EAJL_UPPER)
4154 mes "You are a rebirth job.";
4155 if ((@eac&EAJ_UPPERMASK) == EAJ_SWORDMAN)
4156 mes "You must be a Swordman, Baby Swordman or High Swordman.";
4157
4158For more information on the eA Job System, see the docs/ea_job_system.txt file.
4159
4160---------------------------------------
4161
4162*roclass(<job number>{,<gender>})
4163
4164Does the opposite of eaclass. That is, given an eA job-number, it returns the
4165corresponding RO class number. A gender is required because both Bard and Dancers
4166share the same eA job-number (EAJ_BARDDANCER), and uses the invoking player's
4167gender if none is given (if no player is attached, male will be used by default).
4168The command will return -1 if there is no valid class to represent the specified
4169job (for example, if you try to get the baby version of a Taekwon class).
4170
4171 @eac = eaclass();
4172 //Check if class is already rebirth
4173 if (@eac&EAJL_UPPER) {
4174 mes "You look strong.";
4175 close;
4176 }
4177 @eac = roclass(@eac|EAJL_UPPER);
4178 //Check if class has a rebirth version
4179 if (@eac != -1) {
4180 mes "Bet you can't wait to become a " + jobname(@eac) + "!";
4181 close;
4182 }
4183
4184---------------------------------------
4185
4186*changebase <job ID number>{,<account ID>};
4187
4188This command will change a character's appearance to that of the specified job
4189class. Nothing but appearance will change.
4190
4191The command will run for the invoking character unless an account ID is given.
4192
4193 changebase Job_Novice; // Changes player to Novice sprite.
4194 changebase Class; // Changes player back to default sprite.
4195
4196---------------------------------------
4197
4198*classchange(<view id>{,"<NPC name>","<flag>"});
4199
4200This command is very ancient, its origins are clouded in mystery.
4201It will send a 'display id change' packet to everyone in the immediate area of
4202the NPC object, which will supposedly make the NPC look like a different sprite,
4203an NPC sprite ID, or a monster ID. This effect is not stored anywhere and will
4204not persist (Which is odd, cause it would be relatively easy to make it do so)
4205and most importantly, will not work at all since this command was broken with
4206the introduction of advanced classes. The code is written with the assumption
4207that the lowest sprite IDs are the job sprites and the anything beyond them is
4208monster and NPC sprites, but since the advanced classes rolled in, they got the
4209ID numbers on the other end of the number pool where monster sprites float.
4210
4211As a result it is currently impossible to call this command with a valid view
4212id. It will do nothing whatsoever if the view ID is below 4047. Getting it to
4213run will actually just crash the client.
4214
4215It could be a real gem if it can be gotten to actually do what it's supposed to
4216do, but this will only happen in a later SVN revision.
4217
4218Empty <NPC name> means attached NPC.
4219
4220Target for <flag>:
4221- bc_area : Sprite is sent to players in the vicinity of the source (default value).
4222- bc_self : Sprite is sent only to player attached.
4223
4224---------------------------------------
4225
4226*changesex({<char_id>});
4227
4228This command will change the gender for the attached character's account. If it
4229was male, it will become female, if it was female, it will become male. The
4230change will be written to the character server, the player will receive the
4231message: "Need disconnection to perform change-sex request..." and the player
4232will be immediately kicked to the login screen. When they log back in, they will
4233be the opposite sex.
4234
4235If there are any Dancer/Gypsy or Bard/Clown characters on the account,
4236they will also have their skills reset upon 'changesex'.
4237
4238---------------------------------------
4239
4240*changecharsex({<char_id>});
4241
4242This command will change the gender of the attached character. If it
4243was male, it will become female, if it was female, it will become male. The
4244change will be written to the character server, the player will receive the
4245message: "Need disconnection to perform change-sex request..." and the player
4246will be immediately kicked to the login screen. When they log back in, they will
4247be the opposite sex.
4248
4249If the character being changed is a Dancer/Gypsy or Bard/Clown class type,
4250the character will also have their skills reset upon 'changecharsex'.
4251
4252---------------------------------------
4253
4254*getexp <base_exp>,<job_exp>{,<char_id>};
4255
4256This command will give the invoking character a specified number of base and job
4257experience points. Used for a quest reward. Negative values won't work.
4258
4259The EXP values are adjustted by 'quest_exp_rate' config value, VIP bonus, Guild
4260Tax and EXP boost items such Battle Manual, Bubble Gum, or items that have
4261SC_EXPBOOST or SC_ITEMBOOST.
4262
4263 getexp 10000,5000;
4264
4265---------------------------------------
4266
4267*getexp2 <base_exp>,<job_exp>{,<char_id>};
4268
4269This command is safety version of 'set' command for BaseExp and JobExp. If using
4270'set' while the BaseExp or JobExp value is more than 2,147,483,647 (INT_MAX) will
4271causing overflow error.
4272
4273Unlike 'getexp', this command ignores the adjustment factors!
4274
4275---------------------------------------
4276
4277*setlook <look type>,<look value>{,<char_id>};
4278*changelook <look type>,<look value>{,<char_id>};
4279
4280'setlook' will alter the look data for the invoking character. It is used
4281mainly for changing the palette used on hair and clothes: you specify which look
4282type you want to change, then the palette you want to use. Make sure you specify
4283a palette number that exists/is usable by the client you use.
4284'changelook' works the same, but is only client side (it doesn't save the look value).
4285
4286 // This will change your hair color, so that it uses palette 8, what ever your
4287 // palette 8 is, your hair will use that color
4288
4289 setlook LOOK_HAIR_COLOR,8;
4290
4291 // This will change your clothes color, so they are using palette 1, whatever
4292 // your palette 1 is, your clothes will then use that set of colors.
4293
4294 setlook LOOK_CLOTHES_COLOR,1;
4295
4296Here are the possible look types:
4297
4298 LOOK_BASE - Base sprite
4299 LOOK_HAIR - Hairstyle
4300 LOOK_WEAPON - Weapon
4301 LOOK_HEAD_BOTTOM - Head bottom
4302 LOOK_HEAD_TOP - Head top
4303 LOOK_HEAD_MID - Head mid
4304 LOOK_HAIR_COLOR - Hair color
4305 LOOK_CLOTHES_COLOR - Clothes color
4306 LOOK_SHIELD - Shield
4307 LOOK_SHOES - Shoes
4308 LOOK_BODY2 - Body style
4309
4310Whatever 'shoes' means is anyone's guess, ask Gravity - the client does nothing
4311with this value. It still wants it from the server though, so it is kept, but
4312normally doesn't do a thing.
4313
4314Only the look data for hairstyle, hair color and clothes color are saved to the
4315char server's database and will persist. Body style will also persist if 'save_body_style'
4316configuration is enabled in '/conf/battle/client.conf'. The rest freely change as the character
4317puts on and removes equipment, changes maps, logs in and out and otherwise you
4318should not expect to set them. In fact, messing with them is generally
4319hazardous, do it at your own risk, it is not tested what will this actually do -
4320it won't cause database corruption and probably won't cause a server crash, but
4321it's easy to crash the client with just about anything unusual.
4322
4323However, it might be an easy way to quickly check for empty view IDs for
4324sprites, which is essential for making custom headgear.
4325
4326Since a lot of people have different palettes for hair and clothes, it's
4327impossible to tell you what all the color numbers are. If you want a serious
4328example, there is a Stylist script inside the default rAthena installation that
4329you can look at: 'npc/custom/stylist.txt'
4330
4331---------------------------------------
4332
4333*pushpc <direction>,<cells>;
4334
4335This command will push the currently attached player to given direction by given
4336amount of square cells. Direction is the same as used when declaring NPCs, and
4337can be specified by using one of the DIR_* constants (src/map/script_constants.h).
4338
4339The knock-back is not restricted by items or map flags, only obstacles are taken
4340into account. If there is not enough space to perform the push (e.g. due to a
4341wall), the character is pushed only up to the obstacle.
4342
4343 // pushes the character 5 cells in 3 o'clock direction from its
4344 // current position.
4345 pushpc DIR_EAST, 5;
4346
4347---------------------------------------
4348
4349*recalculatestat;
4350
4351This command will force a stat recalculation for the attached player.
4352
4353---------------------------------------
4354
4355*needed_status_point(<type>,<val>{,<char id>});
4356
4357Returns the number of stat points needed to change the specified stat <type> by <val>.
4358If <val> is negative, returns the number of stat points that would be needed to
4359raise the specified stat from (current value - <val>) to current value.
4360
4361---------------------------------------
4362
4363*jobcanentermap("<mapname>"{,<JobID>});
4364
4365Return true if player (decided by job) can enter the map, false otherwise.
4366
4367For optional 'JobID', see constant of Job_*, or use player's Class, BaseJob,
4368and BaseClass. If no player is attached, this param must have a value.
4369
4370See also db/[pre-]re/job_noenter_map.txt
4371
4372---------------------------------------
4373
4374*get_revision()
4375
4376This command will return the SVN revision number that the server is currently
4377running on.
4378
4379 if (get_revision() >= 15000)
4380 mes "Welcome to rAthena!";
4381
4382---------------------------------------
4383
4384*get_githash()
4385
4386This command will return the Git Hash that the server is currently running on.
4387
4388 mes "Welcome to rAthena! Git Hash: " + get_githash();
4389
4390---------------------------------------
4391\\
43924,1.- Item-related commands
4393\\
4394---------------------------------------
4395
4396*getitem <item id>,<amount>{,<account ID>};
4397*getitem "<item name>",<amount>{,<account ID>};
4398
4399This command will give an amount of specified items to the invoking character.
4400If an optional account ID is specified, and the target character is currently
4401online, items will be created in their inventory instead. If they are not
4402online, nothing will happen.
4403
4404In the first and most commonly used version of this command, items are
4405referred to by their database ID number found inside 'db/(pre-)re/item_db.txt'.
4406
4407 getitem 502,10 // The person will receive 10 apples
4408 getitem 617,1 // The person will receive 1 Old Violet Box
4409
4410This transaction is logged if the log script generated transactions option is
4411enabled.
4412
4413You may also create an item by its name in the 'english name' field in the
4414item database:
4415
4416 getitem "RED_POTION",10;
4417
4418Which will do what you'd expect. If it can't find that name in the database,
4419apples will be created anyway. It is often a VERY GOOD IDEA to use it like this.
4420
4421This is used in pretty much all NPC scripts that have to do with items and
4422quite a few item scripts. For more examples check just about any official script.
4423
4424---------------------------------------
4425
4426*getitem2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4427*getitem2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4428*getitem3 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4429*getitem3 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4430
4431This command will give an amount of specified items to the invoking character.
4432If an optional account ID is specified, and the target character is currently
4433online, items will be created in their inventory instead. If they are not
4434online, nothing will happen. It works essentially the same as 'getitem' but is
4435a lot more flexible.
4436
4437Those parameters that are different from 'getitem' are:
4438
4439identify - Whether you want the item to be identified (1) or not (0).
4440refine - For how many pluses will it be refined.
4441 It will not let you refine an item higher than the max refine.
4442attribute - Whether the item is broken (1) or not (0).
4443card1,2,3,4 - If you want a card compound to it, place the card ID number into
4444 the specific card slot.
4445
4446Card1-card4 values are also used to store name information for named items, as
4447well as the elemental property of weapons and armor. You can create a named item
4448in this manner, however, if you just need a named piece of standard equipment,
4449it is much easier to the 'getnameditem' function instead.
4450
4451You will need to keep these values if you want to destroy and then perfectly
4452recreate a named item, for this see 'getinventorylist'.
4453
4454If you still want to try creating a named item with this command because
4455'getnameditem' won't do it for you cause it's too limited, you can do it like
4456this. Careful, minor magic ahead.
4457
4458 // First, let's get an ID of a character who's name will be on the item.
4459 // Only an existing character's name may be there.
4460 // Let's assume our character is 'Adam' and find his ID.
4461 @charid = getcharid(0,"Adam");
4462
4463 // Now we split the character ID number into two portions with a binary
4464 // shift operation. If you don't understand what this does, just copy it.
4465 @card3 = @charid & 65535;
4466 @card4 = @charid >> 16;
4467
4468 // If you're inscribing non-equipment, @card1 must be 254.
4469 // Arrows are also not equipment.
4470 @card1 = 254;
4471
4472 // For named equipment, card2 means the Star Crumbs and elemental
4473 // crystals used to make this equipment. For everything else, it's 0.
4474 @card2 = 0;
4475
4476 // Now, let's give the character who invoked the script some
4477 // Adam's Apples:
4478 getitem2 512,1,1,0,0,@card1,@card2,@card3,@card4;
4479
4480This wasn't tested with all possible items, so I can't give any promises,
4481experiment first before relying on it.
4482
4483To create equipment, continue this example it like this:
4484
4485 // We've already have card3 and card4 loaded with correct
4486 // values so we'll just set up card1 and card2 with data
4487 // for an Ice Stiletto.
4488
4489 // If you're inscribing equipment, @card1 must be 255.
4490 @card1 = 255;
4491
4492 // That's the number of star crumbs in a weapon.
4493 @sc = 2;
4494
4495 // That's the number of elemental property of the weapon.
4496 @ele = 1;
4497
4498 // And that's the wacky formula that makes them into
4499 // a single number.
4500 @card2 = @ele+((@sc*5)<<8);
4501
4502 // That will make us an Adam's +2 VVS Ice Stiletto:
4503 getitem2 1216,1,1,2,0,@card1,@card2,@card3,@card4;
4504
4505Experiment with the number of star crumbs - I'm not certain just how much will
4506work most and what it depends on. The valid element numbers are:
4507
4508 1 - Ice, 2 - Earth 3 - Fire 4 - Wind.
4509
4510You can, apparently, even create duplicates of the same pet egg with this
4511command, creating a pet which is the same, but simultaneously exists in two
4512eggs, and may hatch from either, although, I'm not sure what kind of a mess will
4513this really cause.
4514
4515'getitem3' is advance version of 'getitem2' that also use Item Random Option as additional values.
4516<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4517<RandomValueArray> : Array variable of item random option's value.
4518<RandomParamArray> : Array variable of item random option's param.
4519
4520Example to get Crimson Weapon with Ghost property:
4521 // +9 Crimson Dagger [2]
4522 setarray .@OptID[0],RDMOPT_WEAPON_ATTR_TELEKINESIS;
4523 setarray .@OptVal[0],0;
4524 setarray .@OptParam[0],0;
4525 getitem3 28705,1,1,9,0,0,0,0,0,.@OptID,.@OptVal,.@OptParam;
4526
4527---------------------------------------
4528
4529*getitembound <item id>,<amount>,<bound type>{,<account ID>};
4530*getitembound "<item name>",<amount>,<bound type>{,<account ID>};
4531
4532This command behaves identically to 'getitem', but the items created will be
4533bound to the target character as specified by the bound type. All items created
4534in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in
4535some cases cannot be traded or stored.
4536
4537Valid bound types are:
4538 Bound_Account : Account Bound item
4539 Bound_Guild : Guild Bound item
4540 Bound_Party : Party Bound item
4541 Bound_Char : Character Bound item
4542
4543---------------------------------------
4544
4545*getitembound2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>{,<account ID>};
4546*getitembound2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>{,<account ID>};
4547*getitembound3 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4548*getitembound3 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4549
4550This command behaves identically to 'getitem2', but the items created will be
4551bound to the target character as specified by the bound type. All items created
4552in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in
4553some cases cannot be traded or stored.
4554
4555For a list of bound types see 'getitembound'.
4556
4557'getitembound3' is advance version of 'getitembound2' that also use Item Random Option as additional values.
4558<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4559<RandomValueArray> : Array variable of item random option's value.
4560<RandomParamArray> : Array variable of item random option's param.
4561
4562Example to get Crimson Weapon with Ghost property:
4563 // +9 Crimson Dagger [2]
4564 setarray .@OptID[0],RDMOPT_WEAPON_ATTR_TELEKINESIS;
4565 setarray .@OptVal[0],0;
4566 setarray .@OptParam[0],0;
4567 getitembound3 28705,1,1,9,0,0,0,0,0,BOUND_CHAR,.@OptID,.@OptVal,.@OptParam;
4568
4569---------------------------------------
4570
4571*getnameditem <item id>,<character name|character ID>;
4572*getnameditem "<item name>",<character name|character ID>;
4573
4574Create an item signed with the given character's name.
4575
4576The command returns 1 when the item is created successfully, or 0 if it fails.
4577Failure occurs when:
4578- There is no player attached.
4579- Item name or ID is not valid.
4580- The given character ID/name is offline.
4581
4582Example:
4583
4584//This will give the currently attached player a Aaron's Apple (if Aaron is online).
4585 getnameditem "Apple","Aaron";
4586
4587//Self-explanatory (I hope).
4588 if (getnameitem("Apple","Aaron")) {
4589 mes "You now have a Aaron's Apple!";
4590 }
4591
4592---------------------------------------
4593
4594*rentitem <item id>,<time>{,<account_id>};
4595*rentitem "<item name>",<time>{,<account_id>};
4596
4597Creates a rental item in the attached character's inventory. The item will expire
4598in <time> seconds and be automatically deleted. When receiving a rental item,
4599the character will receive a message in their chat window. The character will
4600also receive warning messages in their chat window before the item disappears.
4601
4602When rentals expire it will call the OnUnequip Script of the item. This can be used
4603for special cases such as removing a status change or resetting a variable or state
4604of the player.
4605
4606This command can not be used to rent stackable items. Rental items cannot be
4607dropped, traded, sold to NPCs, or placed in guild storage. (i.e. trade mask 75)
4608Note: 'delitem' in an NPC script can still remove rental items.
4609
4610---------------------------------------
4611
4612*rentitem2 <item id>,<time>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account_id>};
4613*rentitem2 "<item name>",<time>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account_id>};
4614*rentitem3 <item id>,<time>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account_id>};
4615*rentitem3 "<item name>",<time>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account_id>};
4616
4617Creates a rental item in the attached character's inventory. The item will expire
4618in <time> seconds and be automatically deleted. See 'rentitem' for further details.
4619
4620See 'getitem2' for an explanation of the expanded parameters.
4621
4622'rentitem3' is advance version of 'rentitem2' that also use Item Random Option as additional values.
4623<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4624<RandomValueArray> : Array variable of item random option's value.
4625<RandomParamArray> : Array variable of item random option's param.
4626
4627Example to get Crimson Weapon with Ghost property:
4628 // +9 Crimson Dagger [2]
4629 setarray .@OptID[0],RDMOPT_WEAPON_ATTR_TELEKINESIS;
4630 setarray .@OptVal[0],0;
4631 setarray .@OptParam[0],0;
4632 rentitem3 28705,(24*60*60),1,9,0,0,0,0,0,.@OptID,.@OptVal,.@OptParam;
4633
4634---------------------------------------
4635
4636*makeitem <item id>,<amount>,"<map name>",<X>,<Y>;
4637*makeitem "<item name>",<amount>,"<map name>",<X>,<Y>;
4638
4639This command will create an item on the specified cell of a map.
4640
4641As with any dropped items, the items created with this command will disappear after
4642a period of time. Using an amount greater than 1 will create a single stack of the
4643given amount, not multiple stacks of 1.
4644
4645Like 'getitem', it also accepts an 'english name' field from the database and creates
4646Apples if the name isn't found.
4647If the map name is given as "this", the map the invoking character is on will be used.
4648
4649---------------------------------------
4650
4651*makeitem2 <item id>,<amount>,"<map name>",<X>,<Y>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>;
4652*makeitem2 "<item name>",<amount>,"<map name>",<X>,<Y>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>;
4653*makeitem3 <item id>,<amount>,"<map name>",<X>,<Y>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>;
4654*makeitem3 "<item name>",<amount>,"<map name>",<X>,<Y>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>;
4655
4656This command will create an item on the specified cell of a map. See 'makeitem' for
4657further details.
4658
4659See 'getitem2' for an explanation of the expanded parameters.
4660
4661'makeitem3' is advance version of 'makeitem2' that also use Item Random Option as additional values.
4662<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4663<RandomValueArray> : Array variable of item random option's value.
4664<RandomParamArray> : Array variable of item random option's param.
4665
4666Example to get Crimson Weapon with Ghost property:
4667 // 0.5% chance to get +0 Valkyrie Shield [1]
4668 // with Neutral Resistance +10% and 5% damage reduction from Demi-Human or Player
4669 // when Valkyrie Randgris killed
4670 OnNPCKillEvent:
4671 if (killedrid == 1751 && rand(0,1000) > 950) { // Valkyrie Randgris
4672 getmapxy(.@map$,.@x,.@y,UNITTYPE_PC);
4673 setarray .@OptID[0],RDMOPT_ATTR_TOLERACE_NOTHING,RDMOPT_RACE_TOLERACE_HUMAN;
4674 setarray .@OptVal[0],10,5;
4675 setarray .@OptParam[0],0;
4676 makeitem3 2115,1,.@map$,.@x,.@y,0,0,0,0,0,0,0,.@OptID,.@OptVal,.@OptParam;
4677 }
4678 end;
4679
4680---------------------------------------
4681
4682*cleanarea "<map name>",<x1>,<y1>,<x2>,<y2>;
4683*cleanmap "<map name>";
4684
4685These commands will clear all items lying on the ground on the specified map, either
4686within the x1/y1-x2/y2 rectangle or across the entire map.
4687
4688---------------------------------------
4689
4690*searchitem <array name>,"<item name>";
4691
4692This command will fill the given array with the ID of items whose name matches
4693the given one. It returns the number of items found. For performance reasons,
4694the results array is limited to 10 items.
4695
4696 mes "What item are you looking for?";
4697 input .@name$;
4698 .@qty = searchitem(.@matches[0],.@name$);
4699 mes "I found " + .@qty + " items:";
4700 for (.@i = 0; .@i < .@qty; .@i++)
4701 // Display name (eg: "Apple[0]")
4702 mes getitemname(.@matches[.@i]) + "[" + getitemslots(.@matches[.@i]) + "]";
4703
4704---------------------------------------
4705
4706*delitem <item id>,<amount>{,<account ID>};
4707*delitem "<item name>",<amount>{,<account ID>};
4708
4709This command will remove a specified amount of items from the invoking/target character.
4710Like all the item commands, it uses the item ID found inside 'db/(pre-)re/item_db.txt'.
4711
4712 delitem 502,10; // The person will lose 10 apples
4713 delitem 617,1; // The person will lose 1 Old Violet Box
4714
4715It is always a good idea to check if the player actually has the items before you delete them.
4716If you try to delete more items that the player has, the player will lose the ones he/she has
4717and the script will terminate with an error.
4718
4719Like 'getitem', this command will also accept an 'english name' field from the
4720database. If the name is not found, nothing will be deleted.
4721
4722---------------------------------------
4723
4724*cartdelitem <item id>,<amount>{,<account ID>};
4725*cartdelitem "<item name>",<amount>{,<account ID>};
4726*storagedelitem <item id>,<amount>{,<account ID>};
4727*storagedelitem "<item name>",<amount>{,<account ID>};
4728*guildstoragedelitem <item id>,<amount>{,<account ID>};
4729*guildstoragedelitem "<item name>",<amount>{,<account ID>};
4730
4731This command behaves identically to 'delitem', but deletes items from the player's
4732cart, storage, or guild storage.
4733
4734If no cart is mounted, 'cartdelitem' will return -1.
4735If player is not in a guild or storage is open, 'guildstoragedelitem' will return -1.
4736
4737---------------------------------------
4738
4739*delitem2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4740*delitem2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4741*delitem3 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4742*delitem3 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>{,<account ID>};
4743
4744This command will remove a specified amount of items from the invoking/target character.
4745See 'getitem2' for an explanation of the expanded parameters.
4746
4747'delitem3' is advance version of 'delitem2' that also use Item Random Option as criteria.
4748<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4749<RandomValueArray> : Array variable of item random option's value.
4750<RandomParamArray> : Array variable of item random option's param.
4751
4752---------------------------------------
4753
4754*cartdelitem2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4755*cartdelitem2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4756*storagedelitem2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4757*storagedelitem2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4758*guildstoragedelitem2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4759*guildstoragedelitem2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<account ID>};
4760
4761This command behaves identically to 'delitem2', but deletes items from the player's
4762cart, storage, or guild storage.
4763
4764If no cart is mounted, 'cartdelitem2' will return -1.
4765If player is not in a guild or storage is open, 'guildstoragedelitem2' will return -1.
4766
4767---------------------------------------
4768
4769*countitem(<item id>)
4770*countitem("<item name>")
4771
4772This function will return the number of items for the specified item ID that the
4773invoking character has in the inventory.
4774
4775 mes "[Item Checker]";
4776 mes "Hmmm, it seems you have " + countitem(502) + " apples";
4777 close;
4778
4779Like 'getitem', this function will also accept an 'english name' from the
4780database as an argument.
4781
4782If you want to state the number at the end of a sentence, you can do it by
4783adding up strings:
4784
4785 mes "[Item Checker]";
4786 mes "Hmmm, the total number of apples you are holding is " + countitem("APPLE");
4787 close;
4788
4789---------------------------------------
4790
4791*cartcountitem(<item id>{,<accountID>})
4792*cartcountitem("<item name>"{,<accountID>})
4793*storagecountitem(<item id>{,<accountID>})
4794*storagecountitem("<item name>"{,<accountID>})
4795*guildstoragecountitem(<nameID>{,<accountID>})
4796*guildstoragecountitem("<item name>"{,<accountID>})
4797
4798This command behaves identically to 'countitem', but counts items from the player's
4799cart, storage, or guild storage.
4800
4801If no cart is mounted, 'cartcountitem' will return -1.
4802If player is not in a guild or storage is open, 'guildstoragecountitem' will return -1.
4803
4804---------------------------------------
4805
4806*countitem2(<item id>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>)
4807*countitem2("<item name>",<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>)
4808*countitem3(<item id>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>)
4809*countitem3("<item name>",<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<RandomIDArray>,<RandomValueArray>,<RandomParamArray>)
4810
4811Expanded version of 'countitem' function, used for created/carded/forged items.
4812
4813This function will return the number of items for the specified item ID and
4814other parameters that the invoking character has in the inventory.
4815See 'getitem2' for an explanation of the expanded parameters.
4816
4817'countitem3' is advance version of 'countitem2' that also use Item Random Option as criteria.
4818<RandomIDArray> : Array variable of ID for item random option, see db/[pre-]re/item_randomopt_db.txt
4819<RandomValueArray> : Array variable of item random option's value.
4820<RandomParamArray> : Array variable of item random option's param.
4821
4822---------------------------------------
4823
4824*cartcountitem2(<item id>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<accountID>})
4825*cartcountitem2("<item name>",<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<accountID>})
4826*storagecountitem2(<item id>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<accountID>})
4827*storagecountitem2("<item name>",<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>{,<accountID>})
4828*guildstoragecountitem2(<nameID>,<Identified>,<Refine>,<Attribute>,<Card0>,<Card1>,<Card2>,<Card3>{,<accountID>})
4829*guildstoragecountitem2("<item name>",<Identified>,<Refine>,<Attribute>,<Card0>,<Card1>,<Card2>,<Card3>{,<accountID>})
4830
4831This command behaves identically to 'countitem2', but counts items from the player's
4832cart, storage, or guild storage.
4833
4834If no cart is mounted, 'cartcountitem2' will return -1.
4835If player is not in a guild or storage is open, 'guildstoragecountitem2' will return -1.
4836
4837---------------------------------------
4838
4839*countbound({<bound type>{,<char_id>}})
4840
4841This function will return the number of bounded items in the character's
4842inventory, and sets an array @bound_items[] containing all item IDs of the
4843counted items. If a bound type is specified, only those items will be counted.
4844
4845For a list of bound types see 'getitembound'.
4846
4847Example:
4848 mes "You currently have " + countbound() + " bounded items.";
4849 next;
4850 mes "The list of bounded items include:";
4851 for(.@i = 0; .@i < getarraysize(@bound_items); .@i++)
4852 mes getitemname(@bound_items[.@i]);
4853 close;
4854
4855---------------------------------------
4856
4857*groupranditem <group id>{,<sub_group>};
4858
4859Returns the item_id of a random item picked from the group specified. The
4860different groups and their group number are specified in 'db/(pre-)re/item_group_db.txt'.
4861
4862When used in conjunction with other functions, you can get a random item. For
4863example, for a random pet lure:
4864
4865getitem groupranditem(IG_Taming),1;
4866
4867'sub_group' is used to get the available random items of item group from specified random
4868group. 0 for 'must' item group, and random item group is 1 until 5 (MAX_ITEMGROUP_RANDGROUP+1).
4869
4870More info, see doc/item_group.txt.
4871
4872---------------------------------------
4873
4874*getrandgroupitem <group_id>{,<quantity>{,<sub_group>{,<identify>{,<char_id>}}}};
4875
4876Similar to the above example, this command allows players to obtain the specified
4877quantity of a random item from the group "<group id>". The different groups and
4878their group number are specified in db/(pre-)re/item_group_db.txt
4879
4880If 'quantity' is not defined or 0, it will uses defined amount from Item Group list.
4881
4882If 'sub_group' is not defined the value will be 1 (since random group is 1 ~ 5, and 0 is
4883'must' item group).
4884
4885For item with type IT_WEAPON, IT_ARMOR, IT_PETARMOR, and IT_SHADOWGEAR will be given
4886as unidentified item (as defined by itemdb_isidentified in src/map/itemdb.cpp) except
4887if 'identify' is defined with value 1.
4888
4889More info, see doc/item_group.txt.
4890
4891---------------------------------------
4892
4893*getgroupitem <group_id>{,<identify>{,<char_id>}};
4894
4895Gives item(s) to the attached player based on item group contents.
4896This is not working like 'getrandgroupitem' which only give 1 item for specified
4897item group & sub_group.
4898
4899For item with type IT_WEAPON, IT_ARMOR, IT_PETARMOR, and IT_SHADOWGEAR will be given
4900as unidentified item (as defined by itemdb_isidentified in src/map/itemdb.cpp) except
4901if 'identify' is defined with value 1.
4902
4903More info, see doc/item_group.txt.
4904
4905---------------------------------------
4906
4907*enable_items;
4908*disable_items;
4909
4910These commands toggle the ability to change equipment while interacting with
4911an NPC. To avoid possible exploits, the commands affect the particular script
4912instance only. Note that if a different script also calls enable_items, it
4913will override the last call (so you may want to call this command at the start
4914of your script without assuming it is still in effect).
4915
4916The default setting, 'item_enabled_npc', is defined in 'conf/battle/items.conf'.
4917
4918---------------------------------------
4919
4920*itemskill <skill id>,<skill level>{,<keep requirement>};
4921*itemskill "<skill name>",<skill level>{,<keep requirement>};
4922
4923This command is meant for item scripts to replicate single-use skills in usable
4924items. It will not work properly if there is a visible dialog window or menu.
4925If the skill is self or auto-targeting, it will be used immediately; otherwise a
4926target cursor is shown.
4927
4928If <keep requirement> parameter is set to true, the skill's requirements will be checked.
4929By default, the requirements for item skills are not checked, and therefore the default value is false.
4930
4931// When Anodyne is used, it will cast Endure (8), Level 1, as if the actual
4932// skill has been used from skill tree.
4933605,Anodyne,Anodyne,11,2000,0,100,,,,,10477567,2,,,,,{ itemskill 8,1; },{}
4934
4935// When Sienna_Execrate_Scroll_1_5 is used, it will cast Sienna Execrate Level 5 and consume 2 Red_Gemstones.
493623194,Sienna_Execrate_Scroll_1_5,Level 5 Sienna Execrate,11,10,,10,,,,,0xFFFFFFFF,63,2,,,,,,{ itemskill "WL_SIENNAEXECRATE",5,true; },{},{}
4937
4938---------------------------------------
4939
4940*consumeitem <item id>{,<char_id>};
4941*consumeitem "<item name>"{,<char_id>};
4942
4943This command will run the item script of the specified item on the invoking
4944character. The character does not need to possess the item, and the item will
4945not be deleted. While this command is intended for usable items, it will run
4946for any item type.
4947
4948This command does not currently work with the 'itemskill' script command.
4949
4950---------------------------------------
4951
4952*produce <item level>;
4953
4954This command will open a crafting window on the client connected to the invoking
4955character. The 'item level' is a number which determines what kind of a crafting
4956window will pop-up.
4957
4958You can see the full list of such item levels in 'db/produce_db.txt' which determines
4959what can actually be produced. The window will not be empty only if the invoking
4960character can actually produce the items of that type and has the appropriate raw
4961materials in their inventory.
4962
4963The success rate to produce the item is the same as the success rate of the skill
4964associated with the item level. If there is no skill id, the success rate will be 50%.
4965
4966Valid item levels are:
4967
4968 1 - Level 1 Weapons
4969 2 - Level 2 Weapons
4970 3 - Level 3 Weapons
4971 21 - Blacksmith's Stones and Metals
4972 22 - Alchemist's Potions, Holy Water, Assassin Cross's Deadly Poison
4973 23 - Elemental Converters
4974
4975---------------------------------------
4976
4977*cooking <dish level>;
4978
4979This command will open a produce window on the client connected to the invoking
4980character. The 'dish level' is the number which determines what kind of dish
4981level you can produce. You can see the full list of dishes that can be produced in
4982'db/produce_db.txt'.
4983
4984The window will be shown empty if the invoking character does not have enough of
4985the required incredients to cook a dish.
4986
4987Valid dish levels are:
4988
498911 - Level 1 Dish
499012 - Level 2 Dish
499113 - Level 3 Dish
499214 - Level 4 Dish
499315 - Level 5 Dish
499416 - Level 6 Dish
499517 - Level 7 Dish
499618 - Level 8 Dish
499719 - Level 9 Dish
499820 - Level 10 Dish
4999
5000Although it's required to set a dish level, it doesn't matter if you set it to 1
5001and you want to cook a level 10 dish, as long as you got the required incredients
5002to cook the dish the command works.
5003
5004---------------------------------------
5005
5006*makerune <% success bonus>{,<char_id>};
5007
5008This command will open a rune crafting window on the client connected to the
5009invoking character. Since this command is officially used in rune ores, a bonus
5010success rate must be specified (which adds to the base formula).
5011
5012You can see the full list of runes that can be produced in 'db/produce_db.txt'.
5013The window will not be empty only if the invoking character can actually produce
5014a rune and has the appropriate raw materials in their inventory.
5015
5016---------------------------------------
5017
5018*successremovecards <equipment slot>;
5019
5020This command will remove all cards of the cards slots defined by item_db.txt
5021from the item found in the specified equipment slot of the invoking character,
5022create new card items and give them to the character.
5023If any cards were removed in this manner, it will also show a success effect.
5024
5025---------------------------------------
5026
5027*failedremovecards <equipment slot>,<type>;
5028
5029This command will remove all cards from the item found in the specified
5030equipment slot of the invoking character. 'type' determines what happens to the
5031item and the cards:
5032
5033 0 - will destroy both the item and the cards.
5034 1 - will keep the item, but destroy the cards.
5035 2 - will keep the cards, but destroy the item.
5036
5037Whatever the type is, it will also show a failure effect on screen.
5038
5039---------------------------------------
5040
5041*repair <broken item number>{,<char_id>};
5042
5043This command repairs a broken piece of equipment, using the same list of broken
5044items as available through 'getbrokenid'.
5045
5046---------------------------------------
5047
5048*repairall {<char_id>};
5049
5050This command repairs all broken equipment in the attached player's inventory.
5051A repair effect will be shown if any items are repaired, else the command will
5052end silently.
5053
5054---------------------------------------
5055
5056*successrefitem <equipment slot>{,<count>{,<char_id>}};
5057
5058This command will refine an item in the specified equipment slot of the invoking
5059character by +1, or a count if given. For a list of equipment slots see 'getequipid'.
5060This command will also display a 'refine success' effect on the character and put
5061appropriate messages into their chat window. It will also give the character fame
5062points if a weapon reached +10 this way, even though these will only take effect for
5063blacksmith who will later forge a weapon.
5064
5065---------------------------------------
5066
5067*failedrefitem <equipment slot>{,<char_id>};
5068
5069This command will fail to refine an item in the specified equipment slot of the
5070invoking character. The item will be destroyed. This will also display a 'refine
5071failure' effect on the character and put appropriate messages into their chat
5072window.
5073
5074---------------------------------------
5075
5076*downrefitem <equipment slot>{,<count>{,<char_id>}};
5077
5078This command will downgrade an item in the specified equipment slot of the invoking
5079character by -1, or a count if given. For a list of equipment slots see 'getequipid'.
5080This command will also display a 'refine failure' effect on the character and put
5081appropriate messages into their chat window.
5082
5083---------------------------------------
5084
5085*unequip <equipment slot>{,<char_id>};
5086
5087This command will unequip whatever is currently equipped in the invoking
5088character's specified equipment slot. For a full list of possible equipment
5089slots see 'getequipid'.
5090
5091If an item occupies several equipment slots, it will get unequipped from all of
5092them.
5093
5094---------------------------------------
5095
5096*delequip <equipment slot>{,<char_id>};
5097
5098This command will destroy whatever is currently equipped in the invoking
5099character's specified equipment slot. For a full list of possible equipment
5100slots see 'getequipid'.
5101
5102This command will return 1 if an item was deleted and 0 otherwise.
5103
5104---------------------------------------
5105
5106*breakequip <equipment slot>{,<char_id>};
5107
5108This command will break and unequip whatever is currently equipped in the
5109invoking character's specified equipment slot. For a full list of possible
5110equipment slots see 'getequipid'.
5111
5112This command will return 1 if an item was broken and 0 otherwise.
5113
5114---------------------------------------
5115
5116*clearitem {<char_id>};
5117
5118This command will destroy all items the invoking character has in their
5119inventory (including equipped items). It will not affect anything else, like
5120storage or cart.
5121
5122---------------------------------------
5123
5124*equip <item id>{,<char_id>};
5125*autoequip <item id>,<option>;
5126
5127These commands are to equip a equipment on the attached character.
5128The equip function will equip the item ID given when the player has
5129this item in his/her inventory, while the autoequip function will
5130equip the given item ID when this is looted. The option parameter of
5131the autoequip is 1 or 0, 1 to turn it on, and 0 to turn it off.
5132
5133Examples:
5134
5135//This will equip a 1104 (falchion) on the character if this is in the inventory.
5136 equip 1104;
5137
5138//The invoked character will now automatically equip a falchion when it's looted.
5139 autoequip 1104,1;
5140
5141//The invoked character will no longer automatically equip a falchion.
5142 autoequip 1104,0;
5143
5144---------------------------------------
5145
5146*buyingstore <slots>;
5147
5148Invokes buying store preparation window like the skill 'Open Buying Store',
5149without the item requirement. Amount of slots is limited by the server to
5150a maximum of 5 slots by default.
5151
5152Example:
5153 // Gives the player opportunity to buy 4 different kinds of items.
5154 buyingstore 4;
5155
5156---------------------------------------
5157
5158*searchstores <uses>,<effect>;
5159
5160Invokes the store search window, which allows to search for both vending
5161and buying stores. Parameter uses indicates, how many searches can be
5162started, before the window has to be reopened. Effect value affects,
5163what happens, when a result item is double-clicked and can be one of the
5164following:
5165
5166 0 = Shows the store's position on the mini-map and highlights the
5167 shop sign with yellow color, when the store is on same map
5168 as the invoking player.
5169 1 = Directly opens the shop, regardless of distance.
5170
5171Example:
5172 // Item Universal_Catalog_Gold (10 uses, effect: open shop)
5173 searchstores 10,1;
5174
5175---------------------------------------
5176
5177*enable_command;
5178*disable_command;
5179
5180These commands toggle the ability to use atcommand while interacting with an NPC.
5181
5182The default setting, 'atcommand_enable_npc', is defined in 'conf/battle/gm.conf'.
5183
5184---------------------------------------
5185//
51864,1.- End of item-related commands
5187//
5188---------------------------------------
5189
5190*openstorage;
5191
5192This will open character's Kafra storage window on the client connected to the
5193invoking character. It can be used from any kind of NPC or item script, not just
5194limited to Kafra Staff.
5195
5196The storage window opens regardless of whether there are open NPC dialogs or
5197not, but it is preferred to close the dialog before displaying the storage
5198window, to avoid any disruption when both windows overlap.
5199
5200 mes "Close this window to open your storage.";
5201 close2;
5202 openstorage;
5203 end;
5204
5205---------------------------------------
5206
5207*openstorage2 <storage_id>,<mode>{,<account_id>};
5208
5209Just like the 'openstorage' command, except this command can open additional storages
5210by the specified <storage_id>. For <storage_id>, please read the conf/inter_server.yml
5211for storage groups.
5212
5213Values for <mode> are:
5214 STOR_MODE_NONE : Player only can read the storage entries.
5215 STOR_MODE_GET : Player can get items from the storage.
5216 STOR_MODE_PUT : Player can put items in the storage.
5217
5218Example:
5219 if (vip_status(VIP_STATUS_ACTIVE)) {
5220 mes "I will open your Premium storage.";
5221 mes "Thank you for using our service.";
5222 close2;
5223 openstorage2 1,STOR_MODE_GET|STOR_MODE_PUT;
5224 } else {
5225 mes "Sorry, your Premium status is expired.";
5226 mes "Storage will be opened but you can't put any item into it.";
5227 close2;
5228 openstorage2 1,STOR_MODE_GET;
5229 }
5230 end;
5231
5232---------------------------------------
5233
5234*openmail({<char_id>});
5235
5236This will open a character's Mail window on the client connected to the
5237invoking character.
5238
5239 mes "Close this window to open your mail inbox.";
5240 close2;
5241 openmail;
5242 end;
5243
5244---------------------------------------
5245
5246*openauction({<char_id>});
5247
5248This will open the Auction window on the client connected to the invoking character.
5249
5250 mes "Close this window to open the Auction window.";
5251 close2;
5252 openauction;
5253 end;
5254
5255---------------------------------------
5256\\
52574,2.- Guild-related commands
5258\\
5259---------------------------------------
5260
5261*guildopenstorage()
5262
5263This function works the same as 'openstorage' but will open a guild storage
5264window instead for the guild storage of the guild the invoking character belongs
5265to. This is a function because it returns a value - 0 if the guild storage was
5266opened successfully and 1 if it wasn't. (Notice, it's a ZERO upon success.)
5267Since guild storage is only accessible to one character at one time, it may fail
5268if another character is accessing the guild storage at the same time.
5269
5270This will also fail and return 2 if the character does not belong to any guild.
5271
5272---------------------------------------
5273
5274*guildchangegm(<guild id>,<new master's name>)
5275
5276This function will change the Guild Master of a guild. The ID is the guild's
5277id, and the new guild master's name must be passed.
5278
5279Returns 1 on success, 0 otherwise.
5280
5281---------------------------------------
5282
5283*guildgetexp <amount>;
5284
5285This will give the specified amount of guild experience points to the guild the
5286invoking character belongs to. It will silently fail if they do not belong to
5287any guild.
5288
5289---------------------------------------
5290
5291*guildskill <skill id>,<level>
5292*guildskill "<skill name>",<level>
5293
5294This command will bump up the specified guild skill by the specified number of
5295levels. This refers to the invoking character and will only work if the invoking
5296character is a member of a guild AND its guild master, otherwise no failure
5297message will be given and no error will occur, but nothing will happen - same
5298about the guild skill trying to exceed the possible maximum. The full list of
5299guild skills is available in 'db/(pre-)re/skill_db.txt', these are all the GD_ skills at
5300the end.
5301
5302// This would give your character's guild one level of Approval (GD_APPROVAL ID
5303// 10000). Notice that if you try to add two levels of Approval, or add
5304// Approval when the guild already has it, it will only have one level of
5305// Approval afterwards.
5306 guildskill 10000,1,0;
5307
5308You might want to make a quest for getting a certain guild skill, make it hard
5309enough that all the guild needs to help or something. Doing this for the Glory
5310of the Guild skill, which allows your guild to use an emblem, is a good idea for
5311a fun quest.
5312
5313---------------------------------------
5314//
53154,2 End of guild-related commands.
5316//
5317---------------------------------------
5318
5319*resetlvl <action type>{,<char_id>};
5320
5321This is a character reset command, meant mostly for rebirth script supporting
5322Advanced jobs, which will reset the invoking character's stats and level
5323depending on the action type given. Valid action types are:
5324
5325 1 - Base level 1, Job level 1, 0 skill points, 0 base exp, 0 job exp, wipes the
5326 status effects (only the ones settable by 'setoption'), sets all stats to 1.
5327 If the new job is 'Novice High', give 100 status points, give First Aid and
5328 Play Dead skills.
5329 2 - Base level 1, Job level 1, 0 skill points, 0 base exp, 0 job exp.
5330 Skills and attribute values are not altered.
5331 3 - Base level 1, base exp 0. Nothing else is changed.
5332 4 - Job level 1, job exp 0. Nothing else is changed.
5333
5334In all cases everything the character has on will be unequipped.
5335
5336Even though it doesn't return a value, it is used as a function in the official
5337rebirth scripts. Ask AppleGirl why.
5338
5339---------------------------------------
5340
5341*resetstatus({<char_id>});
5342
5343This is a character reset command, which will reset the stats on the invoking
5344character and give back all the stat points used to raise them previously.
5345Nothing will happen to any other numbers about the character.
5346
5347Used in reset NPC's (duh!)
5348
5349---------------------------------------
5350
5351*resetskill({<char_id>});
5352
5353This command takes off all the skill points on the invoking character, so they
5354only have Basic Skill blanked out (lvl 0) left, and returns the points for them
5355to spend again. Nothing else will change but the skills. Quest skills will also
5356reset if 'quest_skill_reset' option is set to Yes in 'battle_athena.conf'. If
5357the 'quest_skill_learn' option is set in there, the points in the quest skills
5358will also count towards the total.
5359
5360Used in reset NPC's (duh!)
5361
5362---------------------------------------
5363
5364*sc_start <effect type>,<ticks>,<value 1>{,<rate>,<flag>{,<GID>}};
5365*sc_start2 <effect type>,<ticks>,<value 1>,<value 2>{,<rate>,<flag>{,<GID>}};
5366*sc_start4 <effect type>,<ticks>,<value 1>,<value 2>,<value 3>,<value 4>{,<rate>,<flag>{,<GID>}};
5367*sc_end <effect type>{,<GID>};
5368*sc_end_class {<char_id>{,<job_id>}};
5369
5370These commands will bestow a status effect on a character.
5371
5372The <effect type> determines which status is invoked. This can be either a number
5373or constant, with the common statuses (mostly negative) found in 'src/map/script_constants.h'
5374with the 'SC_' prefix. A full list is located in 'src/map/status.h', though
5375they are not currently documented.
5376
5377The duration of the status is given in <ticks>, or milleseconds.
5378
5379Certain status changes take an additional parameter <value 1>, which typically
5380modifies player stats by the given number or percentage. This differs for each
5381status, and is sometimes zero.
5382
5383Optional value <rate> is the chance that the status will be invoked (100 = 1%).
5384This is used primarily in item scripts. When used in an NPC script, a flag MUST
5385be defined for the rate to work.
5386
5387Optional value <flag> is how the status change start will be handled (a bitmask).
5388 SCSTART_NOAVOID : Status change cannot be avoided.
5389 SCSTART_NOTICKDEF : Tick cannot be reduced by stats (default).
5390 SCSTART_LOADED : sc_data loaded, so no value will be altered.
5391 SCSTART_NORATEDEF : Rate cannot be reduced.
5392 SCSTART_NOICON : Status icon won't be sent to client
5393
5394If a <GID> is given, the status change will be invoked on the specified character
5395instead of the one attached to the script. This can only be defined after setting
5396a rate and flag.
5397
5398'sc_start2' and 'sc_start4' allow extra parameters to be passed, and are used only
5399for effects that require them. The meaning of the extra values vary depending on the
5400effect type. For more infos, read status_change.txt containing a list of all Status Changes
5401and theirs val1, val2, val3, and val4 usage in source.
5402
5403'sc_end' will remove a specified status effect. If SC_ALL (-1) is given, it will
5404perform a complete removal of all statuses (although permanent ones will re-apply).
5405
5406'sc_end_class' works like 'sc_end' but will remove all status effects from any learned
5407skill on the invoking character. If <job_id> is provided it will end the effect for that job.
5408
5409Examples:
5410 // This will poison the invoking character for 10 minutes at 50% chance.
5411 sc_start SC_POISON,600000,0,5000;
5412
5413 // This will bestow the effect of Level 10 Blessing.
5414 sc_start SC_BLESSING,240000,10;
5415
5416 // Adjust element resistance by percentage. Sample with Resist_Fire item script:
5417 // val1: Water resistance
5418 // val2: Earth resistance
5419 // val3: Fire resistance
5420 // val4: Wind resistance
5421 sc_start4 SC_ARMOR_ELEMENT,1200000,-15,0,20,0;
5422
5423 // This will end the Freezing status for the invoking character.
5424 sc_end SC_FREEZE;
5425
5426 // This will end the effect of any learned skill for the invoking character.
5427 sc_end_class;
5428
5429 // This will end the effect of any learned skill for the character with the <char_id> 150000.
5430 // val1: <char_id>
5431 sc_end_class(150000);
5432
5433 // This will end the effect of any Arch Bishop skill for the invoking character.
5434 // val1: <char_id>
5435 // val2: <job_id> of Arch Bishop
5436 sc_end_class(getcharid(0),Job_Arch_Bishop);
5437
5438Note: to use SC_NOCHAT you should alter Manner
5439 set Manner, -5; // Will mute a user for 5 minutes
5440 set Manner, 0; // Will unmute a user
5441 set Manner, 5; // Will unmute a user and prevent the next use of 'Manner'
5442
5443---------------------------------------
5444
5445*getstatus(<effect type>{,<type>{,<char_id>}})
5446
5447Retrieve information about a specific status effect when called. Depending on <type>
5448specified the function will return different information.
5449
5450Possible <type> values:
5451 - 0 or undefined: whether the status is active
5452 - 1: the val1 of the status
5453 - 2: the val2 of the status
5454 - 3: the val3 of the status
5455 - 4: the val4 of the status
5456 - 5: the amount of time in milliseconds that the status has remaining
5457
5458If <type> is not defined or is set to 0, then the script function will either
5459return 1 if the status is active, or 0 if the status is not active. If the status
5460is not active when any of the <type> fields are provided, this script function
5461will always return 0.
5462
5463---------------------------------------
5464
5465*skilleffect <skill id>,<number>;
5466*skilleffect "<skill name>",<number>;
5467
5468This command displays visual and aural effects of given skill on currently
5469attached character. The number parameter is for skill whose visual effect
5470involves displaying of a number (healing or damaging). Note, that this command
5471will not actually use the skill, it is intended for scripts, which simulate
5472skill usage by the NPC, such as buffs, by setting appropriate status and
5473displaying the skill's effect.
5474
5475 mes "Be blessed!";
5476 // Heal of 2000 HP
5477 heal 2000,0;
5478 skilleffect 28,2000;
5479 // Blessing Level 10
5480 sc_start SC_BLESSING,240000,10;
5481 skilleffect 34,0;
5482 // Increase AGI Level 5
5483 sc_start SC_INCREASEAGI,140000,5;
5484 skilleffect 29,0;
5485
5486This will heal the character with 2000 HP, buff it with Blessing Lv 10 and
5487Increase AGI Lv 5, and display appropriate effects.
5488
5489---------------------------------------
5490
5491*npcskilleffect <skill id>,<number>,<x>,<y>;
5492*npcskilleffect "<skill name>",<number>,<x>,<y>;
5493
5494This command behaves identically to 'skilleffect', however, the effect will not
5495be centered on the invoking character's sprite, nor on the NPC sprite, if any,
5496but will be centered at map coordinates given on the same map as the invoking
5497character.
5498
5499---------------------------------------
5500
5501*specialeffect <effect number>{,<send_target>{,"<NPC Name>"}};
5502
5503This command will display special effect with the given number, centered on the
5504specified NPCs coordinates, if any. For a full list of special effect numbers
5505known see 'doc/effect_list.txt'. Some effect numbers are known not to work in
5506some client releases. (Notably, rain is absent from any client executables
5507released after April 2005.)
5508
5509<NPC name> parameter will display <effect number> on another NPC. If the NPC
5510specified does not exist, the command will do nothing. When specifying an NPC,
5511<send_target> must be specified when specifying an <NPC Name>, specifying AREA
5512will retain the default behavior of the command.
5513
5514 // this will make the NPC "John Doe#1"
5515 // show the effect "EF_HIT1" specified by
5516 // Jane Doe. I wonder what John did...
5517 mes "[Jane Doe]";
5518 mes "Well, I never!";
5519 specialeffect EF_HIT1,AREA,"John Doe#1";
5520 close;
5521
5522---------------------------------------
5523
5524*specialeffect2 <effect number>{,<send_target>{,"<Player Name>"}};
5525
5526This command behaves identically to 'specialeffect', but the effect will be
5527centered on the invoking character's sprite.
5528
5529<Player name> parameter will display <effect number> on another Player than the
5530one currently attached to the script. Like with specialeffect, when specifying
5531a player, <send_target> must be supplied, specifying AREA will retain the default
5532behavior of the command.
5533
5534---------------------------------------
5535
5536*statusup <stat>{,<char_id>};
5537
5538This command will change a specified stat of the invoking character up by one
5539permanently. Stats are to be given as number, but you can use these constants to
5540replace them:
5541
5542bStr - Strength
5543bVit - Vitality
5544bInt - Intelligence
5545bAgi - Agility
5546bDex - Dexterity
5547bLuk - Luck
5548
5549---------------------------------------
5550
5551*statusup2 <stat>,<amount>{,<char_id>};
5552
5553This command will change a specified stat of the invoking character by the
5554specified amount permanently. The amount can be negative. See 'statusup'.
5555
5556 // This will decrease a character's Vit forever.
5557 statusup2 bVit,-1;
5558
5559---------------------------------------
5560
5561*bonus <bonus type>,<val1>;
5562*bonus2 <bonus type>,<val1>,<val2>;
5563*bonus3 <bonus type>,<val1>,<val2>,<val3>;
5564*bonus4 <bonus type>,<val1>,<val2>,<val3>,<val4>;
5565*bonus5 <bonus type>,<val1>,<val2>,<val3>,<val4>,<val5>;
5566
5567These commands are meant to be used in item scripts. They will probably work
5568outside item scripts, but the bonus will not persist for long. They, as
5569expected, refer only to an invoking character.
5570
5571You can find the full list of possible bonuses and which command to use for each
5572kind in 'doc/item_bonus.txt'.
5573
5574---------------------------------------
5575
5576*autobonus <bonus script>,<rate>,<duration>{,<flag>,{<other script>}};
5577*autobonus2 <bonus script>,<rate>,<duration>{,<flag>,{<other script>}};
5578*autobonus3 <bonus script>,<rate>,<duration>,<skill id>,{<other script>};
5579*autobonus3 <bonus script>,<rate>,<duration>,"<skill name>",{<other script>};
5580
5581These commands are meant to be used in item scripts. They will probably work
5582outside item scripts, but the bonus will not persist for long. They, as
5583expected, refer only to an invoking character.
5584
5585What these commands do is 'attach' a script to the player which will get
5586executed on attack (or when attacked in the case of autobonus2).
5587
5588Rate is the trigger rate of the script (1000 = 100%).
5589
5590Duration is the time that the bonus will last for since the script has triggered.
5591
5592Skill ID/skill name the skill which will be used as trigger to start the bonus. (autobonus3)
5593
5594The optional argument 'flag' is used to classify the type of attack where the script
5595can trigger (it shares the same flags as the bAutoSpell bonus script):
5596
5597Range criteria:
5598 BF_SHORT: Trigger on melee attack
5599 BF_LONG: Trigger on ranged attack
5600 Default: BF_SHORT+BF_LONG
5601Attack type criteria:
5602 BF_WEAPON: Trigger on weapon skills
5603 BF_MAGIC: Trigger on magic skills
5604 BF_MISC: Trigger on misc skills
5605 Default: BF_WEAPON
5606Skill criteria:
5607 BF_NORMAL: Trigger on normal attacks
5608 BF_SKILL: Trigger on skills
5609 default: If the attack type is BF_WEAPON (only) BF_NORMAL is used,
5610 otherwise BF_SKILL+BF_NORMAL is used.
5611
5612The difference between the optional argument 'other script' and the 'bonus script' is that,
5613the former one triggers only when attacking(or attacked) and the latter one runs on
5614status calculation as well, which makes sure, within the duration, the "bonus" that get
5615lost on status calculation is restored. So, 'bonus script' is technically supposed to accept
5616"bonus" command only. And we usually use 'other script' to show visual effects.
5617
5618In all cases, when the script triggers, the attached player will be the one
5619who holds the bonus. There is currently no way of knowing within this script
5620who was the other character (the attacker in autobonus2, or the target in
5621autobonus and autobonus3).
5622
5623//Grants a 1% chance of starting the state "all stats +10" for 10 seconds when
5624//using weapon or misc attacks (both melee and ranged skills) and shows a special
5625//effect when the bonus is active.
5626 autobonus "{ bonus bAllStats,10; }",10,10000,BF_WEAPON|BF_MISC,"{ specialeffect2 EF_FIRESPLASHHIT; }";
5627
5628---------------------------------------
5629
5630*bonus_script "<script code>",<duration>{,<flag>{,<type>{,<status_icon>{,<char_id>}}}};
5631
5632This command will attach a script to a player for a given duration, in seconds.
5633After that time, the script will automatically expire. The same bonus cannot be
5634stacked. By default, this bonus will be stored on `bonus_script` table when player
5635logs out.
5636
5637Flags (bitmask):
5638 1 : Remove when dead.
5639 2 : Removable by Dispell.
5640 4 : Removable by Clearance.
5641 8 : Remove when player logs out.
5642 16 : Removeable by Banishing Buster.
5643 32 : Removable by Refresh.
5644 64 : Removable by Lux Anima.
5645 128 : Remove when Madogear is activated or deactivated.
5646 256 : Remove when receive damage.
5647 512 : Script is permanent, cannot be cleared by bonus_script_clear.
5648 1024: Force to replace duplicated script by expanding the duration.
5649 2048: Force to add duplicated script. This flag cannot be stacked with 1024,
5650 if both are defined, 1024 will be checked first and ignore this flag.
5651
5652Types:
5653 This will be used to decide negative or positive buff for 'debuff_on_logout'.
5654 0: Ignore the buff type and won't be removed if the flag is not &8 (Default)
5655 1: Buff
5656 2: Debuff
5657
5658Status_icon: See "Status Icon" section in 'src/map/script_constants.h'. Default is SI_BLANK (-1).
5659
5660Example:
5661 // Apple gives you +5 Str bonus for 1 minute when it's consumed.
5662 512,Apple,Apple,0,15,,20,,,,,0xFFFFFFFF,63,2,,,,,,{ bonus_script "{ bonus bStr,5; }",60; },{},{}
5663
5664---------------------------------------
5665
5666*bonus_script_clear {<flag>,{<char_id>}};
5667
5668Removes attached bonus_script from player. If no 'char_id' given, it will removes
5669from the invoker.
5670
5671If 'flag' is 1, means will clears all scripts even it's Permanent effect. By default,
5672it just removes non-permanent script.
5673
5674---------------------------------------
5675
5676*skill <skill id>,<level>{,<flag>};
5677*skill "<skill name>",<level>{,<flag>};
5678*addtoskill <skill id>,<level>{,<flag>};
5679*addtoskill "<skill name>",<level>{,<flag>};
5680
5681These commands will give the invoking character a specified skill. This is also
5682used for item scripts.
5683
5684Level is obvious. Skill id is the ID number of the skill in question as per
5685'db/(pre-)re/skill_db.txt'. It is not known for certain whether this can be used to give
5686a character a monster's skill, but you're welcome to try with the numbers given
5687in 'db/(pre-)re/mob_skill_db.txt'.
5688
5689Flag is 0 if the skill is given permanently (will get written with the character
5690data) or 1 if it is temporary (will be lost eventually, this is meant for card
5691item scripts usage.). The flag parameter is optional, and defaults to 1 in
5692'skill' and to 2 in 'addtoskill'.
5693
5694Flag 2 means that the level parameter is to be interpreted as a stackable
5695additional bonus to the skill level. If the character did not have that skill
5696previously, they will now at 0+the level given.
5697
5698Flag 3 is the same as flag 1 in that it saves to the database. However, these skills
5699are ignored when any action is taken that adjusts the skill tree (reset/job change).
5700
5701Flag constants:
5702 0 - SKILL_PERM
5703 1 - SKILL_TEMP
5704 2 - SKILL_TEMPLEVEL
5705 3 - SKILL_PERM_GRANT
5706
5707// This will permanently give the character Stone Throw (TF_THROWSTONE,152), at
5708// level 1.
5709 skill 152,1,0;
5710
5711---------------------------------------
5712
5713*nude {<char_id>};
5714
5715This command will unequip anything equipped on the invoking character.
5716
5717It is not required to do this when changing jobs since 'jobchange' will unequip
5718everything not equippable by the new job class anyway.
5719
5720---------------------------------------
5721
5722*sit {"<character name>"};
5723*stand {"<character name>"};
5724
5725These commands will make a character sit or stand.
5726If no character is specified, the command will run for the invoking character.
5727
5728Additionnally Sitting constant is true when the character is sitting, false otherwise.
5729
5730---------------------------------------
5731
5732*disguise <Monster ID>{,<char_id>};
5733*undisguise {<char_id>};
5734
5735This command disguises the current player with a monster sprite.
5736The disguise lasts until 'undisguise' is issued or the player logs out.
5737
5738Example:
5739
5740disguise 1002; // Disguise character as a Poring.
5741next;
5742undisguise; // Return to normal character sprite.
5743
5744---------------------------------------
5745
5746*transform <monster ID>,<duration>{,<sc type>,<val1>,<val2>,<val3>,<val4>};
5747*transform "<monster name>",<duration>{,<sc type>,<val1>,<val2>,<val3>,<val4>};
5748*active_transform <monster ID>,<duration>{,<sc type>,<val1>,<val2>,<val3>,<val4>};
5749*active_transform "<monster name>",<duration>{,<sc type>,<val1>,<val2>,<val3>,<val4>};
5750
5751This command will turn a player into a monster for a given duration and can grant
5752a SC attribute effect while transformed. Note that players cannot be transformed
5753during War of Emperium or if already disguised.
5754Can only be removed when you die or the duration ends.
5755
5756'transform' and 'active_transform' can stack on each other but using 'transform' or
5757'active_transform' twice will not stack (it will cancel the previous bonus for the new).
5758'active_transform' will take priority over transform for its duration.
5759
5760---------------------------------------
5761\\
57624,3 Marriage-related commands
5763\\
5764---------------------------------------
5765
5766*marriage("<spouse name>");
5767
5768This function will marry two characters, the invoking character and the one
5769referred to by name given, together, setting them up as each other's marriage
5770partner. No second function call has to be issued (in current SVN at least) to
5771make sure the marriage works both ways. The function returns 1 upon success, or
57720 if the marriage could not be completed, either because the other character
5773wasn't found or because one of the two characters is already married.
5774
5775This will do nothing else for the marriage except setting up the spouse ID for
5776both of these characters. No rings will be given and no effects will be shown.
5777
5778---------------------------------------
5779
5780*wedding;
5781
5782This command will call up wedding effects - the music and confetti - centered on
5783the invoking character. Example can be found in the wedding script.
5784
5785---------------------------------------
5786
5787*divorce({<char_id>})
5788
5789This function will "un-marry" the invoking character from whoever they were
5790married to. Both will no longer be each other's marriage partner, (at least in
5791current SVN, which prevents the cases of multi-spouse problems). It will return
57921 upon success or 0 if the character was not married at all.
5793
5794This function will also destroy both wedding rings and send a message to both
5795players, telling them they are now divorced.
5796
5797---------------------------------------
5798
5799*adopt("<parent_name>","<baby_name>");
5800*adopt(<parent_id>,<baby_id>);
5801
5802This function will send the client adoption request to the specified baby
5803character. The parent value can be either parent. Both parents and the baby
5804need to be online in order for adoption to work.
5805
5806Return values:
5807 ADOPT_ALLOWED - Sent message to Baby to accept or deny.
5808 ADOPT_ALREADY_ADOPTED - Character is already adopted.
5809 ADOPT_MARRIED_AND_PARTY - Parents need to be married and in a party with the baby.
5810 ADOPT_EQUIP_RINGS - Parents need wedding rings equipped.
5811 ADOPT_NOT_NOVICE - Baby is not a Novice.
5812 ADOPT_CHARACTER_NOT_FOUND - A parent or Baby was not found.
5813 ADOPT_MORE_CHILDREN - You cannot adopt more than 1 child. (client message)
5814 ADOPT_LEVEL_70 - Parents need to be at least level 70 in order to adopt someone. (client message)
5815 ADOPT_MARRIED - You cannot adopt a married person. (client message)
5816
5817---------------------------------------
5818//
58194,3.- End of marriage-related commands
5820//
5821---------------------------------------
5822
5823*pcfollow <id>,<target id>;
5824*pcstopfollow <id>;
5825
5826Makes a character follow or stop following someone. This command does the same
5827as the @follow command. The main difference is that @follow can use character
5828names, and this commands needs the account ID for the target.
5829
5830Examples:
5831 // This will make Aaron follow Bullah, when both of these characters are online.
5832 pcfollow getCharID(3,"Aaron"),getCharID(3,"Bullah");
5833
5834 // Makes Aaron stop following whoever he is following.
5835 pcstopfollow getCharID(3,"Aaron");
5836
5837---------------------------------------
5838
5839*pcblockmove <id>,<option>;
5840*unitblockmove <id>,<option>;
5841
5842Prevents the given GID from moving when the option is 1, and enables the ID to
5843move again when the option is 0. This command will run for the attached unit
5844if the given GID is zero.
5845
5846Examples:
5847 // Prevents the current char from moving away.
5848 pcblockmove getcharid(3),1;
5849
5850 // Enables the current char to move again.
5851 pcblockmove getcharid(3),0;
5852
5853---------------------------------------
5854
5855*pcblockskill <id>,<option>;
5856*unitblockskill <id>,<option>;
5857
5858Prevents the given GID from casting skills when the option is 1, and enables
5859the ID to cast skills again when the option is 0. This command will run for
5860the attached unit if the given GID is zero.
5861
5862Examples:
5863 // Prevents the current char from casting skills.
5864 pcblockskill getcharid(3),1;
5865
5866 // Enables the current char to cast skills again.
5867 pcblockskill getcharid(3),0;
5868
5869---------------------------------------
5870
5871==================================
5872|5.- Mob / NPC -related commands.|
5873==================================
5874---------------------------------------
5875
5876*monster "<map name>",<x>,<y>,"<name to show>",<mob id>,<amount>{,"<event label>",<size>,<ai>};
5877*areamonster "<map name>",<x1>,<y1>,<x2>,<y2>,"<name to show>",<mob id>,<amount>{,"<event label>",<size>,<ai>};
5878
5879This command will spawn a monster on the specified coordinates on the specified
5880map. If the script is invoked by a character, a special map name, "this", will
5881be recognized to mean the name of the map the invoking character is located at.
5882This command works fine in the item scripts.
5883
5884The same command arguments mean the same things as described above in the
5885beginning of this document when talking about permanent monster spawns. Monsters
5886spawned in this manner will not respawn upon being killed.
5887
5888Unlike the permanent monster spawns, if the mob id is -1, a random monster will
5889be picked from the entire database according to the rules configured in the
5890server for dead branches. This will work for all other kinds of non-permanent
5891monster spawns.
5892
5893The only very special thing about this command is an event label, which is an
5894optional parameter. This label is written like '<NPC object name>::<label name>'
5895and upon the monster being killed, it will execute the script inside of the
5896specified NPC object starting from the label given. The RID of the player
5897attached at this execution will be the RID of the killing character. The variable
5898'killedrid' is set to the Class (mob ID) of the monster killed.
5899
5900<size> can be:
5901 Size_Small (0) (default)
5902 Size_Medium (1)
5903 Size_Large (2)
5904
5905<ai> can be:
5906 AI_NONE (0) (default)
5907 AI_ATTACK (1) (attack/friendly)
5908 AI_SPHERE (2) (Alchemist skill)
5909 AI_FLORA (3) (Alchemist skill)
5910 AI_ZANZOU (4) (Kagerou/Oboro skill)
5911 AI_LEGION (5) (Sera skill)
5912 AI_FAW (6) (Mechanic skill)
5913
5914 monster "place",60,100,"Poring",1002,1,"NPCNAME::OnLabel";
5915
5916The coordinates of 0,0 will spawn the monster on a random place on the map.
5917
5918The 'areamonster' command works much like the 'monster' command and is not
5919significantly different, but spawns the monsters within a square defined by
5920x1/y1-x2/y2.
5921
5922Returned value is an array with the game ID of the spawned monster(s) depending
5923on the amount spawned. Array is stored in $@mobid[].
5924
5925Simple monster killing script:
5926
5927 <Normal NPC object definition. Let's assume you called him NPCNAME.>
5928 mes "[Summon Man]";
5929 mes "Want to start the Poring hunt?";
5930 next;
5931 if (select("Yes.:No.") == 2) {
5932 mes "[Summon Man]";
5933 mes "Come back later.";
5934 close;
5935 }
5936
5937 // Summon 10 Porings.
5938 // Using coordinates 0,0 will spawn them in a random location.
5939 monster "prontera",0,0,"Quest Poring",1002,10,"NPCNAME::OnPoringKilled";
5940
5941 mes "[Summon Man]";
5942 mes "Now go and kill all the Porings I summoned.";
5943 close;
5944
5945 OnPoringKilled:
5946 $PoringKilled++;
5947 if ($PoringKilled >= 10) {
5948 announce "Summon Man: Well done. All the Porings are dead!",3;
5949 $PoringKilled = 0;
5950 }
5951 end;
5952
5953For more good examples see just about any official 2-1 or 2-2 job quest script.
5954
5955---------------------------------------
5956
5957*areamobuseskill "<map name>",<x>,<y>,<range>,<mob id>,<skill id>,<skill level>,<cast time>,<cancelable>,<emotion>,<target type>;
5958*areamobuseskill "<map name>",<x>,<y>,<range>,<mob id>,"<skill name>",<skill level>,<cast time>,<cancelable>,<emotion>,<target type>;
5959
5960This command will make all monsters of the specified mob ID in the specified
5961area use the specified skill. Map name, x, and y define the center of the area,
5962which extending <range> cells in each direction (ex: a range of 3 would create
5963a 7x7 square). The skill can be specified by skill ID or name. <cast time> is in
5964milliseconds (1000 = 1 second), and the rest should be self-explanatory.
5965
5966<target type> can be:
5967 0 = self
5968 1 = the mob's current target
5969 2 = the mob's master
5970 3 = random target
5971
5972Example:
5973
5974 // spawn 1 Shining Plant in the 5x5 area centered on (155,188)
5975 areamonster "prontera",153,186,157,190,"Shining Plant",1083,1;
5976 // make the plant cast level 10 Cold Bolt on a random target
5977 areamobuseskill "prontera",155,188,2,1083,"MG_COLDBOLT",10,3000,1,ET_KEK,3;
5978
5979---------------------------------------
5980
5981*killmonster "<map name>","<event label>"{,<type>};
5982
5983This command will kill all monsters that were spawned with 'monster' or
5984'addmonster' and have a specified event label attached to them. Commonly used to
5985get rid of remaining quest monsters once the quest is complete.
5986
5987If the label is given as "All", all monsters which have their respawn times set
5988to -1 (like all the monsters summoned with 'monster' or 'areamonster' script
5989command, and all monsters summoned with GM commands, but no other ones - that
5990is, all non-permanent monsters) on the specified map will be killed regardless
5991of the event label value.
5992
5993As of r12876 killmonster now supports an optional argument type. Using 1 for type
5994will make the command fire "OnMyMobDead" events from any monsters that do die
5995as a result of this command.
5996
5997---------------------------------------
5998
5999*killmonsterall "<map name>"{,<type>};
6000
6001This command will kill all monsters on a specified map name, regardless of how
6002they were spawned or what they are. As of r12873, The behavior has changed slightly.
6003In light of a label behavior fix for mob spawning commands that will now allow the label to
6004trigger when there is no player, killmonsterall has also been modified to support this.
6005
6006Using this the normal/old way means labels don't trigger when a player didn't
6007attack/kill a monster. This is because it breaks compatibility with older scripts if
6008forced to use the new method. However, if you wish to use the new label type with this
6009command, simply use 1 for type. Any other number won't be recognized.
6010
6011---------------------------------------
6012
6013*strmobinfo(<type>,<monster id>);
6014
6015This function will return information about a monster record in the database, as
6016per 'db/(pre-)re/mob_db.txt'. Type is the kind of information returned. Valid types are:
6017It will return 0 if there is no such monster (or the type value is invalid),
6018or an empty string if you requested the monster's name.
6019
6020 1 - 'english name' field in the database, a string.
6021 2 - 'japanese name' field in the database, a string.
6022 All other returned values are numbers:
6023 3 - Level.
6024 4 - Maximum HP.
6025 5 - Maximum SP.
6026 6 - Experience reward.
6027 7 - Job experience reward.
6028
6029---------------------------------------
6030
6031*mobcount("<map name>","<event label>")
6032
6033This function will count all the monsters on the specified map that have a given
6034event label and return the number or 0 if it can't find any. Naturally, only
6035monsters spawned with 'monster' and 'areamonster' script commands can have non-empty
6036event label.
6037If you pass this function an empty string for the event label, it will return
6038the total count of monster without event label, including permanently spawning monsters.
6039With the dynamic mobs system enabled, where mobs are not kept
6040in memory for maps with no actual people playing on them, this will return a 0
6041for any such map.
6042If the event label is given as "all", all monsters will be counted, regardless of
6043having any event label attached.
6044
6045If the map name is given as "this", the map the invoking character is on will
6046be used. If the map is not found, or the invoker is not a character while the map
6047is "this", it will return -1.
6048
6049---------------------------------------
6050
6051*clone "<map name>",<x>,<y>,"<event>",<char id>{,<master_id>{,<mode>{,<flag>,<duration>}}}
6052
6053This command creates a monster which is a copy of another player. The first
6054four arguments serve the same purpose as in the monster script command, The
6055<char id> is the character id of the player to clone (player must be online).
6056If <master id> is given, the clone will be a 'slave/minion' of it. Master_id
6057must be a character id of another online player.
6058
6059The mode can be specified to determine the behavior of the clone. Its
6060values are the same as the ones used for the mode field in the mob_db. The
6061default mode is aggressive, assists, can move, can attack.
6062
6063Flag can be either zero or one currently. If zero, the clone is a normal
6064monster that'll target players, if one, it is considered a summoned monster,
6065and as such, it'll target other monsters. Defaults to zero.
6066
6067The duration specifies how long the clone will live before it is auto-removed.
6068Specified in seconds, defaults to no limit (zero).
6069
6070Returned value is the monster ID of the spawned clone. If command fails,
6071returned value is zero.
6072
6073---------------------------------------
6074
6075*summon "monster name",<monster id>{,<Time Out>{,"event label"}};
6076
6077This command will summon a monster. (see also 'monster') Unlike monsters spawned
6078with other commands, this one will set up the monster to fight to protect the
6079invoking character. Monster name and mob id obey the same rules as the one given
6080at the beginning of this document for permanent monster spawns with the
6081exceptions mentioned when describing 'monster' command.
6082
6083The effect for the skill 'Call Homunculus' will be displayed centered on the
6084invoking character.
6085
6086Timeout is the time in milliseconds the summon lives, and is set default
6087to 60000 (1 minute). Note that also the value 0 will set the timer to default,
6088and it is not possible to create a spawn that lasts forever.
6089If an event label is given, upon the monster being killed, the event label will
6090run as if by 'donpcevent'.
6091
6092Returned value is the game ID of the spawned monster.
6093
6094// Will summon a dead branch-style monster to fight for the character.
6095summon "--ja--",-1;
6096
6097---------------------------------------
6098
6099*addmonsterdrop <monster id>,<item id>,<rate>;
6100*addmonsterdrop "<monster name>",<item id>,<rate>;
6101*delmonsterdrop <monster id>,<item id>;
6102*delmonsterdrop "<monster name>",<item id>;
6103
6104These commands will temporarily add or delete a monster drop, which will be reset
6105when the mob database reloads or the server shuts down. They return 1 upon success.
6106
6107If the monster already drops the specified item, its drop rate will be updated with
6108the given rate (100 = 1%).
6109
6110Examples:
6111 // Makes Owl Baron drop Honey at an 80% rate.
6112 addmonsterdrop 1295,518,8000;
6113
6114 // Deletes Executioner's Mitten from Rybio.
6115 delmonsterdrop 1201,7017;
6116
6117---------------------------------------
6118
6119*disablenpc "<NPC object name>";
6120*enablenpc "<NPC object name>";
6121
6122These two commands will disable and enable, respectively, an NPC object
6123specified by name. The disabled NPC will disappear from sight and will no longer
6124be triggerable in the normal way. It is not clear whether it will still be
6125accessible through 'donpcevent' and other triggering commands, but it probably
6126will be. You can disable even warp NPCs if you know their object names, which is
6127an easy way to make a map only accessible through walking half the time. Then
6128you 'enablenpc' them back.
6129
6130You can also use these commands to create the illusion of an NPC switching
6131between several locations, which is often better than actually moving the NPC -
6132create one NPC object with a visible and a hidden part to their name, make a few
6133copies, and then disable all except one.
6134
6135---------------------------------------
6136
6137*hideonnpc "<NPC object name>";
6138*hideoffnpc "<NPC object name>";
6139
6140These commands will make the NPC object specified display as hidden/visible,
6141even though not actually disabled per se. Hidden as in thief Hide skill, but
6142unfortunately, not detectable by Ruwach or Sight.
6143
6144As they are now, these commands are pointless, it is suggested to use
6145'disablenpc'/'enablenpc', because these two commands actually unload the NPC
6146sprite location and other accompanying data from memory when it is not used.
6147However, you can use these for some quest ideas (such as cloaking NPCs talking
6148while hidden then revealing.... you can wonder around =P
6149
6150---------------------------------------
6151
6152*unloadnpc "<NPC object name>";
6153
6154This command will fully unload a NPC object and all of it's duplicates.
6155
6156---------------------------------------
6157
6158*doevent "<NPC object name>::<event label>";
6159
6160This command will start a new execution thread in a specified NPC object at the
6161specified label. The execution of the script running this command will not stop,
6162and the event called by the 'doevent' command will not run until the invoking
6163script has terminated. No parameters may be passed with a doevent call.
6164
6165The script of the NPC object invoked in this manner will run as if it's been
6166invoked by the RID that was active in the script that issued a 'doevent'. As
6167such, the command will not work if an RID is not attached.
6168
6169 place,100,100,1%TAB%script%TAB%NPC%TAB%53,{
6170 mes "This is what you will see when you click me";
6171 close;
6172 OnLabel:
6173 mes "This is what you will see if the doevent is activated";
6174 close;
6175 }
6176
6177 ....
6178
6179 doevent "NPC::OnLabel";
6180
6181---------------------------------------
6182
6183*donpcevent "<NPC object name>::<event label>";
6184
6185This command invokes the event label code within an another NPC or NPCs. It
6186starts a separate instance of execution, and the invoking NPC will resume
6187execution its immediately.
6188
6189If the supplied event label has the form "NpcName::OnLabel", then only given
6190NPC's event label will be invoked (much like 'goto' into another NPC). If the
6191form is "::OnLabel" (NPC name omitted), the event code of all NPCs with given
6192label will be invoked, one after another. In both cases the invoked script
6193will run without an attached RID, whether or not the invoking script was
6194attached to a player. The event label name is required to start with "On".
6195
6196This command can be used to make other NPCs act, as if they were responding to
6197the invoking NPC's actions, such as using an emotion or talking.
6198
6199 place,100,100,1%TAB%script%TAB%NPC1%TAB%53,{
6200 mes "NPC2 copies my actions!";
6201 close2;
6202 donpcevent "NPC2::OnEmote";
6203 end;
6204 OnEmote:
6205 emotion rand(1,30);
6206 end;
6207 }
6208
6209 place,102,100,1%TAB%script%TAB%NPC2%TAB%53,{
6210 mes "NPC1 copies my actions!";
6211 close2;
6212 donpcevent "NPC1::OnEmote";
6213 end;
6214 OnEmote:
6215 emotion rand(1,30);
6216 end;
6217 }
6218
6219Whichever of the both NPCs is talked to, both will show a random emotion at the
6220same time.
6221
6222As of r16564, command now returns 1 or 0 on success and failure.
6223A debug message also shows on the console when no events are triggered.
6224
6225---------------------------------------
6226
6227*cmdothernpc "<npc name>","<command>";
6228
6229This is simply "donpcevent <npc name>::OnCommand<command>".
6230It is an approximation of official server script language's 'cmdothernpc'.
6231
6232Returns true if the command was executed on the other NPC successfully, false if not.
6233
6234---------------------------------------
6235
6236*npctalk "<message>"{,"<NPC name>","<flag>"};
6237
6238This command will display a message as if the NPC object running it was a player
6239talking - that is, above their head and in the chat window.
6240The display name of the NPC won't get appended in front of the message.
6241If the <NPC name> option is given and not empty, then that NPC will display the message,
6242else the attached NPC will display the message.
6243
6244Target for <flag>:
6245- bc_all : Broadcast message is sent server-wide (only in the chat window).
6246- bc_map : Message is sent to everyone in the same map as the source of the npc.
6247- bc_area : Message is sent to players in the vicinity of the source (default value).
6248- bc_self : Message is sent only to player attached.
6249
6250 // This will make everyone in the area see the NPC greet the character
6251 // who just invoked it.
6252 npctalk "Hello " + strcharinfo(0) + ", how are you?";
6253
6254---------------------------------------
6255
6256*chatmes "<message>"{,"<NPC name>"};
6257
6258This command will display a message in the waitingroom (chat) of the NPC.
6259If the <NPC name> option is given, then that NPC will display the message, else
6260the attached NPC will display the message.
6261If the NPC is not in a waitingroom, nothing happens.
6262
6263 // Everyone in the waitingroom will see this message:
6264 chatmes "Waiting 5 minutes until the next match will start";
6265
6266---------------------------------------
6267
6268*setnpcdisplay("<npc name>", "<display name>", <class id>, <size>)
6269*setnpcdisplay("<npc name>", "<display name>", <class id>)
6270*setnpcdisplay("<npc name>", "<display name>")
6271*setnpcdisplay("<npc name>", <class id>)
6272
6273Changes the display name and/or display class of the target NPC.
6274Returns 0 is successful, 1 if the NPC does not exist.
6275Size is 0 = normal 1 = small 2 = big.
6276
6277---------------------------------------
6278\\
62795,1.- Time-related commands
6280\\
6281---------------------------------------
6282
6283*addtimer <ticks>,"NPC::OnLabel";
6284*deltimer "NPC::OnLabel";
6285*addtimercount <ticks>,"NPC::OnLabel";
6286
6287These commands will create, destroy, and delay a countdown timer - 'addtimer' to
6288create, 'deltimer' to destroy and 'addtimercount' to delay it by the specified
6289number of ticks. For all three cases, the event label given is the identifier of
6290that timer. The timer runs on the character object that is attached to the script,
6291and can have multiple instances. When the label is run, it is run as if the player that
6292the timer runs on has clicked the NPC.
6293
6294When this timer runs out, a new execution thread will start in the specified NPC
6295object at the specified label.
6296
6297The ticks are given in 1/1000ths of a second.
6298
6299One more thing. These timers are stored as part of player data. If the player
6300logs out, all of these get immediately deleted, without executing the script.
6301If this behavior is undesirable, use some other timer mechanism (like 'sleep').
6302
6303Example:
6304<NPC Header> {
6305 dispbottom "Starting a 5 second timer...";
6306 addtimer 5000, strnpcinfo(3) + "::On5secs";
6307 end;
6308On5secs:
6309 dispbottom "5 seconds have passed!";
6310 end;
6311}
6312
6313---------------------------------------
6314
6315*initnpctimer{ "<NPC name>" {, <Attach Flag>} } |
6316 { "<NPC name>" | <Attach Flag> };
6317*stopnpctimer{ "<NPC name>" {, <Detach Flag>} } |
6318 { "<NPC name>" | <Detach Flag> };
6319*startnpctimer{ "<NPC name>" {, <Attach Flag>} } |
6320 { "<NPC name>" | <Attach Flag> };
6321*setnpctimer <tick>{,"<NPC name>"};
6322*getnpctimer(<type of information>{,"<NPC name>"})
6323*attachnpctimer {"<character name>"};
6324*detachnpctimer {"<NPC name>"};
6325
6326This set of commands and functions will create and manage an NPC-based timer.
6327The NPC name may be omitted, in which case the calling NPC is used as target.
6328
6329Contrary to addtimer/deltimer commands which let you have many different timers
6330referencing different labels in the same NPC, each with their own countdown,
6331'initnpctimer' can only have one per NPC object. But it can trigger many labels
6332and let you know how many were triggered already and how many still remain.
6333
6334This timer is counting up from 0 in ticks of 1/1000ths of a second each. Upon
6335creating this timer, the execution will not stop, but will happily continue
6336onward. The timer will then invoke new execution threads at labels
6337"OnTimer<time>:" in the NPC object it is attached to.
6338
6339To create the timer, use the 'initnpctimer', which will start it running.
6340'stopnpctimer' will pause the timer, without clearing the current tick, while
6341'startnpctimer' will let the paused timer continue.
6342
6343By default timers do not have a RID attached, which lets them continue even
6344if the player that started them logs off. To attach a RID to a timer, you can
6345either use the optional "attach flag" when using 'initnpctimer/startnpctimer',
6346or do it manually by using 'attachnpctimer'. Likewise, the optional flag of
6347stopnpctimer lets you detach any RID after stopping the timer, and by using
6348'detachnpctimer' you can detach a RID at any time.
6349
6350Normally there is only a single timer per NPC, but as an exception, as long as
6351you attach a player to the timer, you can have multiple timers running at once,
6352because these will get stored on the players instead of the NPC.
6353NOTE: You need to attach the RID before the timer _before_ you start it to
6354get a player-attached timer. Otherwise it'll stay a NPC timer (no effect).
6355
6356If the player that is attached to the npctimer logs out, the "OnTimerQuit:"
6357event label of that NPC will be triggered, so you can do the appropriate
6358cleanup (the player is still attached when this event is triggered).
6359
6360The 'setnpctimer' command will explicitly set the timer to a given tick.
6361'getnpctimer' provides timer information. Its parameter defines what type:
6362
6363 0 - Will return the current tick count of the timer.
6364 1 - Will return 1 if there are remaining "OnTimer<ticks>:" labels in the
6365 specified NPC waiting for execution.
6366 2 - Will return the number of times the timer has triggered and will trigger
6367 an "OnTimer<tick>:" label in the specified NPC.
6368
6369Example 1:
6370
6371 <NPC Header> {
6372 // We need to use attachnpctimer because the mes command below needs RID attach
6373 attachnpctimer;
6374 initnpctimer;
6375 npctalk "I cant talk right now, give me 10 seconds";
6376 end;
6377 OnTimer5000:
6378 npctalk "Ok 5 seconds more";
6379 end;
6380 OnTimer6000:
6381 npctalk "4";
6382 end;
6383 OnTimer7000:
6384 npctalk "3";
6385 end;
6386 OnTimer8000:
6387 npctalk "2";
6388 end;
6389 OnTimer9000:
6390 npctalk "1";
6391 end;
6392 OnTimer10000:
6393 stopnpctimer;
6394 mes "[Man]";
6395 mes "Ok we can talk now";
6396 detachnpctimer;
6397 // and remember attachnpctimer and detachnpctimer can only use while the NPC timer is not running !
6398 }
6399
6400Example 2:
6401
6402 OnTimer15000:
6403 npctalk "Another 15 seconds have passed.";
6404
6405 // You have to use 'initnpctimer' instead of 'setnpctimer 0'.
6406 // This is equal to 'setnpctimer 0' + 'startnpctimer'.
6407 // Alternatively, you can also insert another 'OnTimer15001' label so that the timer won't stop. */
6408 initnpctimer;
6409 end;
6410
6411 // This OnInit label will run when the script is loaded, so that the timer
6412 // is initialized immediately as the server starts. It is dropped back to 0
6413 // every time the NPC says something, so it will cycle continuously.
6414 OnInit:
6415 initnpctimer;
6416 end;
6417
6418Example 3:
6419
6420 mes "[Man]";
6421 mes "I have been waiting " + (getnpctimer(0)/1000) + " seconds for you.";
6422 // We divide the timer returned by 1000 to convert milliseconds to seconds.
6423 close;
6424
6425Example 4:
6426
6427 mes "[Man]";
6428 mes "Ok, I will let you have 30 more seconds...";
6429 close2;
6430 setnpctimer (getnpctimer(0)-30000);
6431 // Notice the 'close2'. If there were a 'next' there the timer would be
6432 // changed only after the player pressed the 'next' button.
6433 end;
6434
6435---------------------------------------
6436
6437*sleep {<milliseconds>};
6438*sleep2 {<milliseconds>};
6439*awake "<NPC name>";
6440
6441These commands are used to control the pause of a NPC.
6442sleep and sleep2 will pause the script for the given amount of milliseconds.
6443Awake is used to cancel a sleep. When awake is called on a NPC it will run as
6444if the sleep timer ran out, and thus making the script continue. Sleep and sleep2
6445basically do the same, but the main difference is that sleep will not keep the rid,
6446while sleep2 does. Also sleep2 will stop the script if there is no unit attached.
6447
6448Examples:
6449 sleep 10000; //pause the script for 10 seconds and ditch the RID (so no player is attached anymore)
6450 sleep2 5000; //pause the script for 5 seconds, and continue with the RID attached.
6451 awake "NPC"; //Cancels any running sleep timers on the NPC 'NPC'.
6452
6453---------------------------------------
6454
6455*progressbar "<color>",<seconds>;
6456
6457This command works almost like sleep2, but displays a progress bar
6458above the head of the currently attached character (like cast bar).
6459Once the given amount of seconds passes, the script resumes. If the
6460character moves while the progress bar progresses, it is aborted and
6461the script ends. The color format is in RGB (RRGGBB). The color is
6462currently ignored by the client and appears always green.
6463
6464---------------------------------------
6465
6466*progressbar_npc "<color>",<seconds>{,<"NPC Name">};
6467
6468This command works like progressbar, but displays a progress bar
6469above the head of the currently attached (or given) NPC. Once the
6470given amount of seconds passes, the script resumes. The color format
6471is in RGB (RRGGBB). The color is currently ignored by the client and
6472appears always green.
6473
6474Note: If a player is attached to the NPC, they are detached from the NPC
6475as soon as the progress bar activates.
6476
6477---------------------------------------
6478//
64795,1.- End of time-related commands
6480//
6481---------------------------------------
6482
6483*announce "<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}};
6484
6485This command will broadcast a message to all or most players, similar to
6486@kami/@kamib GM commands.
6487
6488 announce "This will be shown to everyone at all in yellow.",0;
6489
6490The region the broadcast is heard in (target), source of the broadcast
6491and the color the message will come up as is determined by the flags.
6492
6493The flag values are coded as constants in 'src/map/script_constants.h' to make them easier to use.
6494
6495Target flags:
6496- bc_all: Broadcast message is sent server-wide (default).
6497- bc_map: Message is sent to everyone in the same map as the source of the broadcast (see below).
6498- bc_area: Message is sent to players in the vicinity of the source.
6499- bc_self: Message is sent only to current player.
6500You cannot use more than one target flag.
6501
6502Source flags:
6503- bc_pc: Broadcast source is the attached player (default).
6504- bc_npc: Broadcast source is the NPC, not the player attached to the script
6505 (useful when a player is not attached or the message should be sent to those
6506 nearby the NPC).
6507You cannot use more than one source flag.
6508
6509Special flags:
6510- bc_yellow: Broadcast will be displayed in yellow color (default).
6511- bc_blue: Broadcast will be displayed in blue color.
6512- bc_woe: Indicates that this broadcast is 'WoE Information' that can be disabled client-side.
6513Due to the way client handles broadcasts, it is impossible to set both bc_blue and bc_woe.
6514
6515The optional parameters allow usage of broadcasts in custom colors, font-weights, sizes etc.
6516If any of the optional parameters is used, special flag is ignored.
6517Optional parameters may not work well (or at all) depending on a game client used.
6518
6519The color parameter is a single number which can be in hexadecimal notation.
6520For example:
6521 announce "This will be shown to everyone at all in green.",bc_all,0x00FF00;
6522Will display a global announce in green. The color format is in RGB (0xRRGGBB).
6523
6524In official scripts only two font-weights (types) are used:
6525 - normal (FW_NORMAL = 400, default),
6526 - bold (FW_BOLD = 700).
6527
6528Default font size is 12.
6529
6530Using this for private messages to players is probably not that good an idea,
6531but it can be used instead in NPCs to "preview" an announce.
6532
6533 // This will be a private message to the player using the NPC that made the
6534 // announcement
6535 announce "This is my message just for you",bc_blue|bc_self;
6536
6537 // This will be shown on everyones screen that is in sight of the NPC.
6538 announce "This is my message just for you people here",bc_npc|bc_area;
6539
6540---------------------------------------
6541
6542*mapannounce "<map name>","<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}}};
6543
6544This command will work like 'announce' but will only broadcast to characters
6545currently residing on the specified map. The flag and optional parameters
6546parameters are the same as in 'announce', but target and source flags are ignored.
6547
6548---------------------------------------
6549
6550*areaannounce "<map name>",<x1>,<y1>,<x2>,<y2>,"<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}}};
6551
6552This command works like 'announce' but will only broadcast to characters
6553residing in the specified x1/y1-x2/y2 rectangle on the map given. The flags and
6554optional parameters are the same as in 'announce', but target and source flags are ignored.
6555
6556 areaannounce "prt_church",0,0,350,350,"God's in his heaven, all right with the world",0;
6557
6558---------------------------------------
6559
6560*callshop "<name>",<option>;
6561
6562These are a series of commands used to create dynamic shops.
6563The 'callshop' function calls an invisible shop (view -1) as if the player clicked on it.
6564
6565The options are:
6566 0 = The normal window (buy, sell and cancel)
6567 1 = The buy window
6568 2 = The sell window
6569
6570Note: The <option> parameter only works on the 'shop' type NPC.
6571
6572A shop called with this command will trigger the labels "OnBuyItem" and "OnSellItem"
6573(as long as an npcshop* command is executed from that NPC, see note below). These
6574labels, if used, will replace how the shop handles the buying and selling of items,
6575allowing for the creation of dynamic shops.
6576
6577The label "OnBuyItem" sets the following arrays:
6578 @bought_nameid - item ID bought
6579 @bought_quantity - amount bought
6580
6581The label "OnSellItem" sets the following arrays:
6582 @sold_nameid - item ID sold
6583 @sold_quantity - amount sold
6584 @sold_refine - refine count
6585 @sold_attribute - if the item is broken (1) or not (0)
6586 @sold_identify - if the item is identified (1) or not (0)
6587 @sold_card1 - card slot 1
6588 @sold_card2 - card slot 2
6589 @sold_card3 - card slot 3
6590 @sold_card4 - card slot 4
6591 @sold_option_id1 - random option ID 1
6592 @sold_option_val1 - random option value 1
6593 @sold_option_param1 - random option param 1
6594 @sold_option_id2 - random option ID 2
6595 @sold_option_val2 - random option value 2
6596 @sold_option_param2 - random option param 2
6597 @sold_option_id3 - random option ID 3
6598 @sold_option_val3 - random option value 3
6599 @sold_option_param3 - random option param 3
6600 @sold_option_id4 - random option ID 4
6601 @sold_option_val4 - random option value 4
6602 @sold_option_param4 - random option param 4
6603 @sold_option_id5 - random option ID 5
6604 @sold_option_val5 - random option value 5
6605 @sold_option_param5 - random option param 5
6606
6607Note: These labels will only be triggered if an npcshop* command is executed because these
6608commands set a special data on the shop NPC, named master_nd in the source. The above labels
6609are triggered in the NPC whose master_nd is given in the shop.
6610
6611A full example of a dynamic shop can be found in doc/sample/npc_dynamic_shop.txt.
6612
6613---------------------------------------
6614
6615*npcshopitem "<name>",<item id>,<price>{,<item id>,<price>{,<item id>,<price>{,...}}};
6616
6617This command lets you override the contents of an existing NPC shop or cashshop. The
6618current sell list will be wiped, and only the items specified with the price
6619specified will be for sale.
6620
6621The function returns 1 if shop was updated successfully, or 0 if not found.
6622
6623NOTES:
6624 - That you cannot use -1 to specify default selling price!
6625 - If attached shop type is market shop, need an extra param after price, it's <qty>
6626 and make sure don't add duplication item!
6627
6628---------------------------------------
6629
6630*npcshopadditem "<name>",<item id>,<price>{,<item id>,<price>{,<item id>,<price>{,...}}};
6631
6632This command will add more items at the end of the selling list for the
6633specified NPC shop or cashshop. If you specify an item already for sell, that item will
6634appear twice on the sell list.
6635
6636The function returns 1 if shop was updated successfully, or 0 if not found.
6637
6638NOTES:
6639 - That you cannot use -1 to specify default selling price!
6640 - If attached shop type is market shop, need an extra param after price, it's <qty>
6641 and make sure don't add duplication item!
6642
6643---------------------------------------
6644
6645*npcshopdelitem "<name>",<item id>{,<item id>{,<item id>{,...}}};
6646
6647This command will remove items from the specified NPC shop or cashshop.
6648If the item to remove exists more than once on the shop, all instances will be
6649removed.
6650
6651Note that the function returns 1 even if no items were removed. The return
6652value is only to confirm that the shop was indeed found.
6653
6654---------------------------------------
6655
6656*npcshopattach "<name>"{,<flag>};
6657
6658This command will attach the current script to the given NPC shop.
6659When a script is attached to a shop, the events "OnBuyItem" and "OnSellItem"
6660of your script will be executed whenever a player buys/sells from the shop.
6661Additionally, the arrays @bought_nameid[], @bought_quantity[] or @sold_nameid[]
6662and @sold_quantity[] will be filled up with the items and quantities
6663bought/sold.
6664
6665The optional parameter specifies whether to attach ("1") or detach ("0") from
6666the shop (the default is to attach). Note that detaching will detach any NPC
6667attached to the shop, even if it's from another script, while attaching will
6668override any other script that may be already attached.
6669
6670The function returns 0 if the shop was not found, 1 otherwise.
6671
6672NOTES:
6673 - If attached shop type is market shop, will be default to call the 'buy' window.
6674
6675---------------------------------------
6676
6677*npcshopupdate "<name>",<item_id>,<price>{,<stock>}
6678
6679Update an entry from shop. If price is 0 means don't change the price, maybe used for
6680marketshop to update the stock quantity. Except marketshop type, 'stock' value means
6681nothing.
6682
6683---------------------------------------
6684
6685*waitingroom "<chatroom name>",<limit>{,"<event label>"{,<trigger>{,<required zeny>{,<min lvl>{,<max lvl>}}}}};
6686
6687This command will create a chat room, owned by the NPC object running this
6688script and displayed above the NPC sprite.
6689The maximum length of a chat room name is 60 letters.
6690
6691The limit is the maximum number of people allowed to enter the chat room.
6692The attached NPC is included in this count. If the optional event and trigger
6693parameters are given, the event label ("<NPC object name>::<label name>")
6694will be invoked as if with a 'doevent' upon the number of people in the chat
6695room reaching the given triggering amount.
6696
6697// The NPC will just show a box above its head that says "Hello World", clicking
6698// it will do nothing, since the limit is zero.
6699 waitingroom "Hello World",0;
6700
6701// The NPC will have a box above its head, it will say "Disco - Waiting Room"
6702// and will have 8 waiting slots. Clicking this will enter the chat room, where
6703// the player will be able to wait until 7 players accumulate. Once this happens,
6704// it will cause the NPC "Bouncer" run the label "OnStart".
6705
6706 waitingroom "Disco - Waiting Room",8,"Bouncer::OnStart",7;
6707
6708// The NPC will have a box above its head, it will say "Party - Waiting Room"
6709// and will have 8 waiting slots. Clicking this will allow a player who has
6710// 5000 zeny and lvl 50~99 to enter the chat room, where the player will be
6711// able to wait until 7 players accumulate. Once this happens, it will cause
6712// the NPC "Bouncer" run the label "OnStart".
6713
6714 waitingroom "Party - Waiting Room",8,"Bouncer::OnStart",7,5000,50,99;
6715
6716Creating a waiting room does not stop the execution of the script and it will
6717continue to the next line.
6718
6719For more examples see the 2-1 and 2-2 job quest scripts which make extensive use
6720of waiting rooms.
6721
6722---------------------------------------
6723
6724*delwaitingroom {"<NPC object name"};
6725
6726This command will delete a waiting room. If no parameter is given, it will
6727delete a waiting room attached to the NPC object running this command, if it is,
6728it will delete a waiting room owned by another NPC object. This is the only way
6729to get rid of a waiting room, nothing else will cause it to disappear.
6730
6731It's not clear what happens to a waiting room if the NPC is disabled with
6732'disablenpc', by the way.
6733
6734---------------------------------------
6735
6736*enablewaitingroomevent {"<NPC object name>"};
6737*disablewaitingroomevent {"<NPC object name>"};
6738*enablearena;
6739*disablearena;
6740
6741This will enable and disable triggering the waiting room event (see
6742'waitingroom') respectively. Optionally giving an NPC object name will do that
6743for a specified NPC object. The chat room will not disappear when triggering is
6744disabled and enabled in this manner and players will not be kicked out of it.
6745Enabling a chat room event will also cause it to immediately check whether the
6746number of users in it exceeded the trigger amount and trigger the event
6747accordingly.
6748
6749Normally, whenever a waiting room was created to make sure that only one
6750character is, for example, trying to pass a job quest trial, and no other
6751characters are present in the room to mess up the script.
6752
6753The 'enablearena'/'disablearena' commands are just aliases with no parameter.
6754These are supposedly left here for compatibility with official server scripts,
6755but no rAthena script uses these at the moment.
6756
6757---------------------------------------
6758
6759*getwaitingroomstate(<information type>{,"<NPC object name>"})
6760
6761This function will return information about the waiting room state for the
6762attached waiting room or for a waiting room attached to the specified NPC if
6763any.
6764
6765The valid information types are:
6766
6767 0 - Number of users currently chatting.
6768 1 - Maximum number of users allowed.
6769 2 - Will return 1 if the waiting room has a trigger set.
6770 0 otherwise.
6771 3 - Will return 1 if the waiting room is currently disabled.
6772 0 otherwise.
6773 4 - The Title of the waiting room (string)
6774 5 - Password of the waiting room, if any. Pointless, since there is no way to
6775 set a password on a waiting room right now.
6776 16 - Event name of the waiting room (string)
6777 32 - Whether or not the waiting room is full.
6778 33 - Whether the amount of users in the waiting room is higher than the trigger
6779 number.
6780
6781---------------------------------------
6782
6783*warpwaitingpc "<map name>",<x>,<y>{,<number of people>};
6784
6785This command will warp the amount of characters equal to the trigger number of
6786the waiting room chat attached to the NPC object running this command to the
6787specified map and coordinates, kicking them out of the chat. Those waiting the
6788longest will get warped first. It can also do a random warp on the same map
6789("Random" instead of map name) and warp to the save point ("SavePoint").
6790
6791The list of characters to warp is taken from the list of the chat room members.
6792Those not in the chat room will not be considered even if they are talking to
6793the NPC in question. If the number of people is given, exactly this much people
6794will be warped.
6795
6796This command can also keep track of who just got warped. It does this by setting
6797special variables:
6798
6799$@warpwaitingpc[] is an array containing the account_id numbers of the
6800 characters who were just warped.
6801$@warpwaitingpcnum contains the number of the character it just warped.
6802
6803See also 'getpartymember' for advice on what to do with those variables.
6804
6805The obvious way of using this effectively would be to set up a waiting room for
6806two characters to be warped onto a random PVP map for a one-on-one duel, for
6807example.
6808
6809---------------------------------------
6810
6811*waitingroomkick "<NPC object name>" , "<character name>";
6812
6813This command kicks the given character from the waiting room attached to the given NPC.
6814
6815---------------------------------------
6816
6817*getwaitingroomusers "<NPC object name>";
6818
6819This command get all the characters in the waiting room of the given NPC and stores
6820their gids in the array .@waitingroom_users[]. Also, stores the the number of characters
6821in the variable .@waitingroom_usercount
6822
6823---------------------------------------
6824
6825*kickwaitingroomall {"<NPC object name>"};
6826
6827This command kicks everybody out of a specified waiting room chat.
6828
6829---------------------------------------
6830
6831*setmapflagnosave "<map name>","<alternate map name>",<x>,<y>;
6832
6833This command sets the 'nosave' flag for the specified map and also gives an
6834alternate respawn-upon-relogin point.
6835
6836It does not make a map impossible to make a save point on as you would normally
6837think, 'savepoint' will still work. It will, however, make the specified map
6838kick the reconnecting players off to the alternate map given to the coordinates
6839specified.
6840
6841---------------------------------------
6842
6843*setmapflag "<map name>",<flag>{,<zone>{,<type>}};
6844
6845This command marks a specified map with the given map flag, which will alter the
6846behavior of the map. A full list of mapflags is located in 'src/map/script_constants.h' with
6847the 'mf_' prefix, and documentation can be found in 'doc/mapflags.txt'.
6848
6849The map flags alter the behavior of the map regarding teleporting (mf_nomemo,
6850mf_noteleport, mf_nowarp, mf_nogo), storing location when disconnected
6851(mf_nosave), dead branch usage (mf_nobranch), penalties upon death
6852(mf_nopenalty, mf_nozenypenalty), PVP behavior (mf_pvp, mf_pvp_noparty,
6853mf_pvp_noguild), WoE behavior (mf_gvg,mf_gvg_noparty), ability to use
6854skills or open up trade deals (mf_notrade, mf_novending, mf_noskill, mf_noicewall),
6855current weather effects (mf_snow, mf_fog, mf_sakura, mf_leaves, mf_rain, mf_clouds,
6856mf_fireworks) and whether night will be in effect on this map (mf_nightenabled).
6857
6858The optional parameter 'zone' is used to set the zone for restricted mapflags.
6859
6860For the 'skill_damage' mapflag, 'zone' functions as 'value' (-100 to 100000) and
6861'type' can be:
6862 1: damage against players
6863 2: damage against mobs
6864 3: damage against bosses
6865 4: damage against other
6866 5: caster type
6867
6868---------------------------------------
6869
6870*removemapflag "<map name>",<flag>{,<zone>};
6871
6872This command removes a mapflag from a specified map.
6873See 'setmapflag' for a list of mapflags.
6874
6875The optional parameter 'zone' is used to remove the zone from restricted mapflags.
6876
6877---------------------------------------
6878
6879*getmapflag("<map name>",<flag>{,<type>})
6880
6881This command checks the status of a given mapflag and returns the mapflag's state.
68820 means OFF, and 1 means ON. See 'setmapflag' for a list of mapflags.
6883
6884The optional parameter 'type' is used in the 'skill_damage' mapflag:
6885 0: if mapflag is set (default)
6886 1: damage against players
6887 2: damage against mobs
6888 3: damage against bosses
6889 4: damage against other
6890 5: caster type
6891
6892---------------------------------------
6893
6894*setbattleflag "<battle flag>",<value>{,<reload>};
6895*getbattleflag("<battle flag>")
6896
6897Sets or gets the value of the given battle flag.
6898Battle flags are the flags found in the battle / *.conf files and is also used in Lupus' variable rates script.
6899If the reload value is given then the server will attempt to reload monster data
6900to properly apply the new rates. This applies to EXP/Drop type configs. The server
6901will only attempt to reload specific configs.
6902
6903Examples:
6904
6905// Will set the base experience rate to 20x (2000%) - Monster data will continue to use previous rates at server start
6906 setBattleFlag "base_exp_rate",2000;
6907
6908// Will set the base experience rate to 20x (2000%) - Monster data will be reloaded to new value
6909 setBattleFlag "base_exp_rate",2000,true;
6910
6911// Will return the value of the base experience rate (when used after the above example, it would print 2000).
6912 mes getBattleFlag("base_exp_rate");
6913
6914---------------------------------------
6915
6916*warpportal <source x>,<source y>,"<map name>",<target x>,<target y>;
6917
6918Creates a warp portal identical to the Acolyte "Warp Portal" skill.
6919The source coordinates specify the portal's location on the map of the invoking NPC.
6920The target map and coordinates determine the destination of the portal.
6921
6922Examples:
6923
6924// Will create a warp portal on the NPC's map at 150,150 leading to prontera, coords 150,180.
6925 warpportal 150,150,"prontera",150,180;
6926
6927---------------------------------------
6928
6929*mapwarp "<from map>","<to map>",<x>,<y>{,<type>,<ID>};
6930
6931This command will collect all characters located on the From map and warp them
6932wholesale to the same point on the To map, or randomly distribute them there if
6933the coordinates are zero. "Random" is understood as a special To map name and
6934will mean randomly shuffling everyone on the same map.
6935
6936Optionally, a type and ID can be specified. Available types are:
6937
6938 0 - Everyone
6939 1 - Guild
6940 2 - Party
6941
6942Example:
6943
6944// Will warp all members of guild with ID 63 on map prontera to map alberta.
6945 mapwarp "prontera","alberta",150,150,1,63;
6946
6947---------------------------------------
6948\\
69495,2.- Guild-related commands
6950\\
6951---------------------------------------
6952
6953*maprespawnguildid "<map name>",<guild id>,<flag>;
6954
6955This command goes through the specified map and for each player and monster
6956found there does stuff.
6957
6958Flag is a bit-mask (add up numbers to get effects you want)
6959 1 - warp all guild members to their save points.
6960 2 - warp all non-guild members (including guildless players) to their save points.
6961 4 - remove all monsters which are not guardian or Emperium.
6962
6963Flag 7 will, therefore, mean 'wipe all mobs but guardians and the Emperium and
6964kick all characters out', which is what the official scripts do upon castle
6965surrender. Upon start of WoE, the scripts do 2 (warp all intruders out).
6966
6967For examples, check the WoE scripts in the distribution.
6968
6969---------------------------------------
6970
6971*agitstart;
6972*agitend;
6973*agitstart2;
6974*agitend2;
6975*agitstart3;
6976*agitend3;
6977
6978These commands will start and end War of Emperium FE, War of Emperium SE,
6979or War of Emperium TE.
6980
6981This is a bit more complex than it sounds, since the commands themselves won't
6982actually do anything interesting, except causing all 'OnAgitStart:' and
6983'OnAgitEnd:', 'OnAgitStart2:' and 'OnAgitEnd2:', or 'OnAgitStart3:' and
6984'OnAgitEnd3:' in the case of latter two commands, events to run everywhere,
6985respectively. They are used as simple triggers to run a lot of complex scripts
6986all across the server, and they, in turn, are triggered by clock with an
6987'OnClock<time>:' time-triggering label.
6988
6989---------------------------------------
6990
6991*gvgon "<map name>";
6992*gvgoff "<map name>";
6993
6994These commands will turn GVG mode for the specified maps on and off, setting up
6995appropriate map flags. In GVG mode, maps behave as if during the time of WoE,
6996even though WoE itself may or may not actually be in effect.
6997
6998---------------------------------------
6999
7000*gvgon3 "<map name>";
7001*gvgoff3 "<map name>";
7002
7003Theses commands behave identically to gvgon/gvgoff, but apply GVG_TE mapflag.
7004
7005---------------------------------------
7006
7007*flagemblem <guild id>;
7008
7009This command only works when run by the NPC objects which have sprite id 722,
7010which is a 3D guild flag sprite. If it isn't, the data will change, but nothing
7011will be seen by anyone. If it is invoked in that manner, the emblem of the
7012specified guild will appear on the flag, though, if any players are watching it
7013at this moment, they will not see the emblem change until they move out of sight
7014of the flag and return.
7015
7016This is commonly used in official guildwar scripts with a function call which
7017returns a guild id:
7018
7019// This will change the emblem on the flag to that of the guild that owns
7020// "guildcastle"
7021
7022 flagemblem GetCastleData("guildcastle",1);
7023
7024---------------------------------------
7025
7026*guardian "<map name>",<x>,<y>,"<name to show>",<mob id>{,"<event label>"{,<guardian index>}};
7027
7028This command is roughly equivalent to 'monster', but is meant to be used with
7029castle guardian monsters and will only work with them. It will set the guardian
7030characteristics up according to the castle's investment values and otherwise
7031set the things up that only castle guardians need.
7032
7033Since trunk r12524:
7034Returns the id of the mob or 0 if an error occurred.
7035When 'guardian index' isn't supplied it produces a temporary guardian.
7036Temporary guardians are not saved with the castle and can't be accessed by guardianinfo.
7037
7038---------------------------------------
7039
7040*guardianinfo("<map name>", <guardian number>, <type>);
7041
7042This function will return various info about the specified guardian, or -1
7043if it fails for some reason. It is primarily used in the castle manager NPC.
7044
7045Map name and guardian number (value between 0 and 7) define the target.
7046Type indicates what information to return:
7047 0 - visibility (whether the guardian is installed or not)
7048 1 - max. hp
7049 2 - current hp
7050
7051---------------------------------------
7052
7053*getguildalliance(<guild id1>, <guild id2>);
7054
7055This command will return the relation between 2 guilds.
7056
7057NOTE: This should be used in collaboration with 'requestguildinfo' as the
7058map-server needs to request for information from the char-server.
7059
7060Return values:
7061 -2 - Guild ID1 does not exist
7062 -1 - Guild ID2 does not exist
7063 0 - Both guilds have no relation OR guild ID aren't given
7064 1 - Both guilds are allies
7065 2 - Both guilds are antagonists
7066
7067---------------------------------------
7068//
70695,2.- End of guild-related commands
7070//
7071---------------------------------------
7072
7073*npcspeed <speed value>;
7074*npcwalkto <x>,<y>;
7075*npcstop;
7076
7077These commands will make the NPC object in question move around the map. As they
7078currently are, they are a bit buggy and are not useful for much more than making
7079an NPC move randomly around the map.
7080
7081'npcspeed' will set the NPCs walking speed to a specified value. As in the
7082@speed GM command, 200 is the slowest possible speed while 0 is the fastest
7083possible (instant motion). 100 is the default character walking speed.
7084
7085'npcwalkto' will start the NPC sprite moving towards the specified coordinates
7086on the same map it is currently on. The script proceeds immediately after the
7087NPC begins moving.
7088
7089'npcstop' will stop the motion.
7090
7091While in transit, the NPC will be clickable, but invoking it will cause it to
7092stop moving, which will make its coordinates different from what the client
7093computed based on the speed and motion coordinates. The effect is rather
7094unnerving.
7095
7096Only a few NPC sprites have walking animations, and those that do, do not get
7097the animation invoked when moving the NPC, due to the problem in the NPC walking
7098code, which looks a bit silly. You might have better success by defining a job-
7099sprite based sprite id in 'db/mob_avail.txt' with this.
7100
7101---------------------------------------
7102
7103*movenpc "<NPC name>",<x>,<y>{,<dir>};
7104
7105This command looks like the NPCWalkToxy function,but is a little different.
7106
7107While NPCWalkToXY just makes the NPC 'walk' to the coordinates given (which
7108sometimes gives problems if the path isn't a straight line without objects),
7109this command just moves the NPC. It basically warps out and in on the current
7110and given spot. Direction can be used to change the NPC's facing direction.
7111
7112Example:
7113
7114// This will move Bugga from it's old coordinates to the new coordinates at 100,20 (if those coordinates are legit).
7115 moveNPC "Bugga",100,20;
7116
7117---------------------------------------
7118
7119=====================
7120|6.- Other commands.|
7121=====================
7122---------------------------------------
7123
7124*debugmes "<message>";
7125
7126This command will send the message to the server console (map-server window). It
7127will not be displayed anywhere else.
7128
7129 // Displays "NAME has clicked me!" in the map-server window.
7130 debugmes strcharinfo(0) + " has clicked me!";
7131
7132---------------------------------------
7133
7134*logmes "<message>";
7135
7136This command will write the message given to the map server NPC log file, as
7137specified in 'conf/log_athena.conf'. In the TXT version of the server, the log
7138file is 'log/npclog.log' by default. In the SQL version, if SQL logging is
7139enabled, the message will go to the 'npclog' table, otherwise, it will go to the
7140same log file.
7141
7142If logs are not enabled, nothing will happen.
7143
7144---------------------------------------
7145
7146*globalmes "<message>"{,"<NPC name>"};
7147
7148This command will send a message to the chat window of all currently connected
7149characters.
7150
7151If NPC name is specified, the message will be sent as if the sender would be
7152the NPC with the said name.
7153The display name of the NPC won't get appended in front of the message.
7154
7155---------------------------------------
7156
7157*rand(<number>{,<number>});
7158
7159This function returns a number ...
7160(if you specify one) ... randomly positioned between 0 and the number you specify -1.
7161(if you specify two) ... randomly positioned between the two numbers you specify.
7162
7163rand(10) would result in 0,1,2,3,4,5,6,7,8 or 9
7164rand(0,9) would result in 0,1,2,3,4,5,6,7,8 or 9
7165rand(2,5) would result in 2,3,4 or 5
7166
7167---------------------------------------
7168
7169*viewpoint <action>,<x>,<y>,<point number>,<color>;
7170
7171This command will mark places on the mini map in the client connected to the
7172invoking character. It uses the normal X and Y coordinates from the main map.
7173The colors of the marks are defined using a hexadecimal number, same as the ones
7174used to color text in 'mes' output, but are written as hexadecimal numbers in C.
7175(They look like 0x<six numbers>.)
7176
7177Action is what you want to do with a point, 1 will set it, while 2 will clear
7178it. 0 will also set it, but automatically removes the point after 15 seconds.
7179Point number is the number of the point - you can have several. If more than
7180one point is drawn at the same coordinates, they will cycle, which can be used
7181to create flashing marks.
7182
7183 // This command will show a mark at coordinates X 30 Y 40, is mark number 1,
7184 // and will be red.
7185
7186 viewpoint 1,30,40,1,0xFF0000;
7187
7188This will create three points:
7189
7190 viewpoint 1,30,40,1,0xFF0000;
7191 viewpoint 1,35,45,2,0xFF0000;
7192 viewpoint 1,40,50,3,0xFF0000;
7193
7194And this is how you remove them:
7195
7196 viewpoint 2,30,40,1,0xFF0000;
7197 viewpoint 2,35,45,2,0xFF0000;
7198 viewpoint 2,40,50,3,0xFF0000;
7199
7200The client determines what it does with the points entirely, the server keeps no
7201memory of where the points are set whatsoever.
7202
7203---------------------------------------
7204
7205*cutin "<filename>",<position>;
7206
7207This command will display a picture, usually an NPC illustration, also called
7208cutin, for the currently attached client. The position parameter determines the
7209placement of the illustration and takes following values:
7210
7211 0 - bottom left corner
7212 1 - bottom middle
7213 2 - bottom right corner
7214 3 - middle of screen in a movable window with an empty title bar
7215 4 - middle of screen without the window header, but still movable
7216
7217The picture is read from data\texture\ìœ ì €ì¸í„°íŽ˜ì´ìŠ¤\illust, from both the GRF archive
7218and data folder, and is required to be a bitmap. The file extension .bmp can be
7219omitted. Magenta color (#ff00ff) is considered transparent. There is no limit
7220placed on the size of the illustrations by the client, although loading of large
7221pictures (about 700x700 and larger) causes the client to freeze shortly (lag).
7222Typically the size is about 320x480. New illustrations can be added by just
7223putting the new file into the location above.
7224
7225The client is able to display only one cutin at the same time and each new one
7226will cause the old one to disappear. To delete the currently displayed
7227illustration without displaying a new one, an empty file name and position 255
7228must be used.
7229
7230 // Displays the Comodo Kafra illustration in lower right corner.
7231 cutin "kafra_07",2;
7232
7233 // Typical way to end a script, which displayed an illustration during a
7234 // dialog with a player.
7235 mes "See you.";
7236 close2;
7237 cutin "",255;
7238 end;
7239
7240---------------------------------------
7241
7242*emotion <emotion number>{,<target>};
7243
7244This command makes an object display an emotion sprite above their own as
7245if they were doing that emotion. For a full list of emotion numbers,
7246see 'src/map/script_constants.h' under 'ET_'. The not so obvious ones are 'ET_QUESTION'
7247(a question mark) and 'ET_SURPRISE' (the exclamation mark).
7248
7249The optional target parameter specifies who will get the emotion on top of
7250their head. Use the target Game ID (GID).
7251
7252---------------------------------------
7253
7254*misceffect <effect number>;
7255
7256This command, if run from an NPC object that has a sprite, will call up a
7257specified effect number, centered on the NPC sprite. If the running code does
7258not have an object ID (a 'floating' NPC) or is not running from an NPC object at
7259all (an item script) the effect will be centered on the character who's RID got
7260attached to the script, if any. For usable item scripts, this command will
7261create an effect centered on the player using the item.
7262
7263A full list of known effects is found in 'doc/effect_list.txt'. The list of
7264those that actually work may differ greatly between client versions.
7265
7266---------------------------------------
7267
7268*soundeffect "<effect filename>",<type>;
7269*soundeffectall "<effect filename>",<type>{,"<map name>"}{,<x0>,<y0>,<x1>,<y1>};
7270
7271These two commands will play a sound effect to either the invoking character
7272only ('soundeffect') or multiple characters ('soundeffectall'). If the running
7273code does not have an object ID (a 'floating' NPC) or is not running from an NPC
7274object at all (an item script) the sound will be centered on the character who's
7275RID got attached to the script, if any. If it does, it will be centered on that
7276object. (an NPC sprite)
7277
7278Effect filename is the filename in a GRF. It must have the .wav extension.
7279
7280It's not quite certain what the 'type' actually does, it is sent to the client
7281directly. It probably determines which directory to play the effect from.
7282It's certain that giving 0 for the number will play sound files from '\data\wav\',
7283but where the other numbers will read from is unclear.
7284
7285The sound files themselves must be in the PCM format, and file names should also
7286have a maximum length of 23 characters including the .wav extension:
7287
7288soundeffect "1234567890123456789.wav", 0; // this will play the soundeffect
7289soundeffect "12345678901234567890.wav", 0; // throw gravity error
7290
7291You can add your own effects this way, naturally.
7292
7293---------------------------------------
7294
7295*playBGM "<BGM filename>";
7296*playBGMall "<BGM filename>"{,"<map name>"{,<x0>,<y0>,<x1>,<y1>}};
7297
7298These two commands will play a Background Music to either the invoking character
7299only ('playBGM') or multiple characters ('playBGMall').
7300
7301BGM filename is the filename in /BGM/ folder. It has to be in .mp3 extension.
7302
7303It's not required to specify the extension inside the script.
7304If coordinates are omitted, BGM will be broadcasted on the entire map. If the map name
7305is omitted as well the BGM will be played for the entire server.
7306
7307You can add your own BGMs this way, naturally.
7308
7309---------------------------------------
7310
7311*pvpon "<map name>";
7312*pvpoff "<map name>";
7313
7314These commands will turn PVP mode for the specified maps on and off. Beside
7315setting the flags referred to in 'setmapflag', 'pvpon' will also create a PVP
7316timer and ranking as will @pvpon GM command do.
7317
7318---------------------------------------
7319
7320*atcommand "<command>";
7321
7322This command will run the given command line exactly as if it was typed in from
7323the keyboard by the player connected to the invoking character, and that
7324character belonged to an account which had GM level 99.
7325
7326 // This will ask the invoker for a character name and then use the '@nuke'
7327 // GM command on them, killing them mercilessly.
7328 input .@player$;
7329 atcommand "@nuke " + .@player$;
7330
7331Note that for atcommands bound using 'bindatcmd', this command will execute the
7332original atcommand, not the script-bound atcommand.
7333
7334---------------------------------------
7335
7336*charcommand "<command>";
7337
7338This command will run the given command line exactly as if it was typed in from
7339the keyboard from a character that belonged to an account which had GM level 99.
7340
7341The commands can also run without an attached rid.
7342
7343 // This would do the same as above, but now
7344 // it doesn't need a player attached by default.
7345 charcommand "#option 0 0 0 Roy";
7346
7347---------------------------------------
7348
7349*bindatcmd "<command>","<NPC object name>::<event label>"{,<atcommand level>,<charcommand level>};
7350
7351This command will bind a NPC event label to an atcommand. Upon execution of the
7352atcommand, the user will invoke the NPC event label. Each atcommand is only allowed
7353one binding. If you rebind, it will override the original binding.
7354Note: The default level for atcommand is 0 while the default level for charcommand is 100.
7355
7356The following variables are set upon execution:
7357 .@atcmd_command$ = The name of the @command used.
7358 .@atcmd_parameters$[] = Array containing the given parameters, starting from an index of 0.
7359 .@atcmd_numparameters = The number of parameters defined.
7360
7361Example:
7362
7363 When a user types the command "@test", an angel effect will be shown.
7364
7365 - script atcmd_example -1,{
7366 OnInit:
7367 bindatcmd "test",strnpcinfo(3) + "::OnAtcommand";
7368 end;
7369 OnAtcommand:
7370 specialeffect2 EF_ANGEL2;
7371 end;
7372 }
7373
7374---------------------------------------
7375
7376*unbindatcmd "<command>";
7377
7378This command will unbind a NPC event label from an atcommand.
7379
7380---------------------------------------
7381
7382*useatcmd "<command>";
7383
7384This command will execute a script-bound atcommand for the attached RID. If the
7385supplied command is not bound to any script, this command will act like 'atcommand'
7386and attempt to execute a source-defined command.
7387
7388The three .@atcmd_***** variables will NOT be set when invoking script-bound atcommands
7389in this way.
7390
7391---------------------------------------
7392\\
73936,1.- Unit-related commands
7394\\
7395---------------------------------------
7396
7397*unitwalk <GID>,<x>,<y>{,"<event label>"};
7398*unitwalkto <GID>,<Target GID>{,"<event label>"};
7399
7400This command will tell a <GID> to walk to a position, defined either as a set of
7401coordinates or another object. The command returns a 1 for success and 0 upon failure.
7402
7403If coordinates are passed, the <GID> will walk to the given x,y coordinates on the
7404unit's current map. While there is no way to move across an entire map with 1 command
7405use, this could be used in a loop to move long distances.
7406
7407If an object ID is passed, the initial <GID> will walk to the <Target GID> (similar to
7408walking to attack). This is based on the distance from <GID> to <Target ID>. This command
7409uses a hard walk check, so it will calculate a walk path with obstacles. Sending a bad
7410target ID will result in an error.
7411
7412An optional Event Label can be passed as well which will execute when the <GID> has reached
7413the given coordinates or <Target GID>.
7414
7415Examples:
7416
7417// Makes player walk to the coordinates (150,150).
7418 unitwalk getcharid(3),150,150;
7419
7420// Performs a conditional check with the command and reports success or failure to the player.
7421 if (unitwalk(getcharid(3),150,150))
7422 dispbottom "Walking you there...";
7423 else
7424 dispbottom "That's too far away, man.";
7425
7426// Makes player walk to another character named "WalkToMe".
7427 unitwalkto getcharid(3),getcharid(3,"WalkToMe");
7428
7429---------------------------------------
7430
7431*unitattack <GID>,<Target ID>{,<action type>};
7432*unitattack <GID>,"<Target Name>"{,<action type>};
7433
7434This command will make a <GID> attack the specified target. It returns true upon
7435success and false for all failures.
7436
7437If <GID> is a player and a non-zero <action type> is given, the unit will perform a
7438continuous attack instead of a single attack.
7439
7440Note:
7441Using unitattack with <GID> 0 means that it will use the currently attached unit.
7442For players any attack requests will fail, because talking to an NPC prevents attacking a monster.
7443Therefore you need to detach the player from the NPC before using this command.
7444
7445---------------------------------------
7446
7447*unitkill <GID>;
7448
7449This command will kill a <GID>.
7450
7451---------------------------------------
7452
7453*unitwarp <GID>,"<map name>",<x>,<y>;
7454
7455This command will warp a <GID> to the specified map and coordinates.
7456
7457If <GID> is zero, the command runs for the unit that invoked the script. This can be
7458used with "OnTouch" to warp monsters:
7459
7460OnTouch:
7461 unitwarp 0,"this",-1,-1;
7462
7463---------------------------------------
7464
7465*unitstopattack <GID>;
7466
7467This command will make a <GID> stop attacking.
7468
7469---------------------------------------
7470
7471*unitstopwalk <GID>{,<flag>};
7472
7473This command will make a <GID> stop moving.
7474
7475Note: If this is called from OnTouch, then the walktimer attached to the unit is
7476removed from OnTouch which causes this command to not stop the unit from walking.
7477Suggest to use 'unitblockmove' to forcefully stop the unit with OnTouch.
7478
7479The <flag> value affects how the unit is stopped. The following flags are bitwise
7480values (can be combined using the pipe operator):
7481 USW_NONE = Unit will keep walking to their original destination.
7482 USW_FIXPOS = Issue a fixpos packet afterwards.
7483 USW_MOVE_ONCE = Force the unit to move one cell if it hasn't yet.
7484 USW_MOVE_FULL_CELL = Enable moving to the next cell when unit was already half-way there (may cause on-touch/place side-effects, such as a scripted map change).
7485 USW_FORCE_STOP = Force stop moving.
7486
7487---------------------------------------
7488
7489*unittalk <GID>,"<text>"{,flag};
7490
7491This command will make a <GID> say a message. The display name of the <GID> won't get appended in front of the message.
7492flag: Specify target
7493 bc_area - Message is sent to players in the vicinity of the source (default).
7494 bc_self - Message is sent only to player attached.
7495
7496---------------------------------------
7497
7498*unitskilluseid <GID>,<skill id>,<skill lvl>{,<target id>,<casttime>};
7499*unitskilluseid <GID>,"<skill name>",<skill lvl>{,<target id>,<casttime>};
7500*unitskillusepos <GID>,<skill id>,<skill lvl>,<x>,<y>{,<casttime>};
7501*unitskillusepos <GID>,"<skill name>",<skill lvl>,<x>,<y>{,<casttime>};
7502
7503This is the replacement of the older commands, these use the same values for
7504GID as the other unit* commands (See 'GID').
7505
7506Skill ID is the ID of the skill, skill level is the level of the skill.
7507Cast time is the amount of seconds to add or remove from the skill. Use a positive value to
7508add and negative value to subtract. Using 0 or no value will use the default skill cast time.
7509For the position, the x and y are given in the UnitSkillUsePos.
7510
7511---------------------------------------
7512
7513*unitexists <GID>;
7514
7515Checks if the given Game ID exists. Returns false if the object doesn't exist, or true if
7516it does.
7517
7518---------------------------------------
7519
7520*getunittype <GID>;
7521
7522Returns the type of object from the given Game ID. Returns -1 if the given GID does not
7523exist.
7524
7525 UNITTYPE_PC 0
7526 UNITTYPE_NPC 1
7527 UNITTYPE_PET 2
7528 UNITTYPE_MOB 3
7529 UNITTYPE_HOM 4
7530 UNITTYPE_MER 5
7531 UNITTYPE_ELEM 6
7532
7533---------------------------------------
7534
7535*getunitname <GID>;
7536
7537Gets the name of the given unit. Supported types are monster, homunculus, pet, and NPC.
7538Mercenary and Elemental don't support custom names.
7539
7540Returns "Unknown" if unit is not found.
7541
7542---------------------------------------
7543
7544*setunitname <GID>,"<new name>";
7545
7546Changes the name of the given unit to the new name given. Supported types are monster,
7547homunculus, and pet. To change an NPC's name, see 'setnpcdisplay'. Mercenary and
7548Elemental don't support custom names.
7549
7550Changing a homunculus or pet name will be permanent.
7551
7552Returns "Unknown" if unit is not found.
7553
7554---------------------------------------
7555
7556*getunitdata <GID>,<arrayname>;
7557*setunitdata <GID>,<parameter>,<new value>;
7558
7559This is used to get and set special data related to the unit.
7560With getunitdata, the array given will be filled with the current data. In setunitdata
7561the indexes in the array would be used to set that data on the unit.
7562
7563Both getunitdata and setunitdata will return -1 if the given GID does not exist.
7564
7565Note: When adjusting a unit's stat (STR, AGI, etc) the unit's respective statuses are
7566 recalculated (HIT, FLEE, etc) automatically. Keep in mind that some stats don't
7567 affect a unit's status and will have to directly be modified.
7568
7569Parameters (indexes) for monsters are:
7570 UMOB_SIZE
7571 UMOB_LEVEL
7572 UMOB_HP
7573 UMOB_MAXHP
7574 UMOB_MASTERAID
7575 UMOB_MAPID
7576 UMOB_X
7577 UMOB_Y
7578 UMOB_SPEED
7579 UMOB_MODE
7580 UMOB_AI
7581 UMOB_SCOPTION
7582 UMOB_SEX
7583 UMOB_CLASS
7584 UMOB_HAIRSTYLE
7585 UMOB_HAIRCOLOR
7586 UMOB_HEADBOTTOM
7587 UMOB_HEADMIDDLE
7588 UMOB_HEADTOP
7589 UMOB_CLOTHCOLOR
7590 UMOB_SHIELD
7591 UMOB_WEAPON
7592 UMOB_LOOKDIR
7593 UMOB_CANMOVETICK
7594 UMOB_STR
7595 UMOB_AGI
7596 UMOB_VIT
7597 UMOB_INT
7598 UMOB_DEX
7599 UMOB_LUK
7600 UMOB_SLAVECPYMSTRMD
7601 UMOB_DMGIMMUNE
7602 UMOB_ATKRANGE
7603 UMOB_ATKMIN
7604 UMOB_ATKMAX
7605 UMOB_MATKMIN
7606 UMOB_MATKMAX
7607 UMOB_DEF
7608 UMOB_MDEF
7609 UMOB_HIT
7610 UMOB_FLEE
7611 UMOB_PDODGE
7612 UMOB_CRIT
7613 UMOB_RACE
7614 UMOB_ELETYPE
7615 UMOB_ELELEVEL
7616 UMOB_AMOTION
7617 UMOB_ADELAY
7618 UMOB_DMOTION
7619
7620-----
7621
7622Parameter (indexes) for homunculi are:
7623 UHOM_SIZE
7624 UHOM_LEVEL
7625 UHOM_HP
7626 UHOM_MAXHP
7627 UHOM_SP
7628 UHOM_MAXSP
7629 UHOM_MASTERCID
7630 UHOM_MAPID
7631 UHOM_X
7632 UHOM_Y
7633 UHOM_HUNGER
7634 UHOM_INTIMACY
7635 UHOM_SPEED
7636 UHOM_LOOKDIR
7637 UHOM_CANMOVETICK
7638 UHOM_STR
7639 UHOM_AGI
7640 UHOM_VIT
7641 UHOM_INT
7642 UHOM_DEX
7643 UHOM_LUK
7644 UHOM_DMGIMMUNE
7645 UHOM_ATKRANGE
7646 UHOM_ATKMIN
7647 UHOM_ATKMAX
7648 UHOM_MATKMIN
7649 UHOM_MATKMAX
7650 UHOM_DEF
7651 UHOM_MDEF
7652 UHOM_HIT
7653 UHOM_FLEE
7654 UHOM_PDODGE
7655 UHOM_CRIT
7656 UHOM_RACE
7657 UHOM_ELETYPE
7658 UHOM_ELELEVEL
7659 UHOM_AMOTION
7660 UHOM_ADELAY
7661 UHOM_DMOTION
7662
7663-----
7664
7665Parameter (indexes) for pets are:
7666 UPET_SIZE
7667 UPET_LEVEL
7668 UPET_HP
7669 UPET_MAXHP
7670 UPET_MASTERAID
7671 UPET_MAPID
7672 UPET_X
7673 UPET_Y
7674 UPET_HUNGER
7675 UPET_INTIMACY
7676 UPET_SPEED
7677 UPET_LOOKDIR
7678 UPET_CANMOVETICK
7679 UPET_STR
7680 UPET_AGI
7681 UPET_VIT
7682 UPET_INT
7683 UPET_DEX
7684 UPET_LUK
7685 UPET_DMGIMMUNE
7686 UPET_ATKRANGE
7687 UPET_ATKMIN
7688 UPET_ATKMAX
7689 UPET_MATKMIN
7690 UPET_MATKMAX
7691 UPET_DEF
7692 UPET_MDEF
7693 UPET_HIT
7694 UPET_FLEE
7695 UPET_PDODGE
7696 UPET_CRIT
7697 UPET_RACE
7698 UPET_ELETYPE
7699 UPET_ELELEVEL
7700 UPET_AMOTION
7701 UPET_ADELAY
7702 UPET_DMOTION
7703
7704-----
7705
7706Parameter (indexes) for mercenaries are:
7707 UMER_SIZE
7708 UMER_HP
7709 UMER_MAXHP
7710 UMER_MASTERCID
7711 UMER_MAPID
7712 UMER_X
7713 UMER_Y
7714 UMER_KILLCOUNT
7715 UMER_LIFETIME
7716 UMER_SPEED
7717 UMER_LOOKDIR
7718 UMER_CANMOVETICK
7719 UMER_STR
7720 UMER_AGI
7721 UMER_VIT
7722 UMER_INT
7723 UMER_DEX
7724 UMER_LUK
7725 UMER_DMGIMMUNE
7726 UMER_ATKRANGE
7727 UMER_ATKMIN
7728 UMER_ATKMAX
7729 UMER_MATKMIN
7730 UMER_MATKMAX
7731 UMER_DEF
7732 UMER_MDEF
7733 UMER_HIT
7734 UMER_FLEE
7735 UMER_PDODGE
7736 UMER_CRIT
7737 UMER_RACE
7738 UMER_ELETYPE
7739 UMER_ELELEVEL
7740 UMER_AMOTION
7741 UMER_ADELAY
7742 UMER_DMOTION
7743
7744-----
7745
7746Parameter (indexes) for elementals are:
7747 UELE_SIZE
7748 UELE_HP
7749 UELE_MAXHP
7750 UELE_SP
7751 UELE_MAXSP
7752 UELE_MASTERCID
7753 UELE_MAPID
7754 UELE_X
7755 UELE_Y
7756 UELE_LIFETIME
7757 UELE_MODE
7758 UELE_SPEED
7759 UELE_LOOKDIR
7760 UELE_CANMOVETICK
7761 UELE_STR
7762 UELE_AGI
7763 UELE_VIT
7764 UELE_INT
7765 UELE_DEX
7766 UELE_LUK
7767 UELE_DMGIMMUNE
7768 UELE_ATKRANGE
7769 UELE_ATKMIN
7770 UELE_ATKMAX
7771 UELE_MATKMIN
7772 UELE_MATKMAX
7773 UELE_DEF
7774 UELE_MDEF
7775 UELE_HIT
7776 UELE_FLEE
7777 UELE_PDODGE
7778 UELE_CRIT
7779 UELE_RACE
7780 UELE_ELETYPE
7781 UELE_ELELEVEL
7782 UELE_AMOTION
7783 UELE_ADELAY
7784 UELE_DMOTION
7785
7786-----
7787
7788Parameter (indexes) for NPCs are:
7789 UNPC_DISPLAY
7790 UNPC_LEVEL
7791 UNPC_HP
7792 UNPC_MAXHP
7793 UNPC_MAPID
7794 UNPC_X
7795 UNPC_Y
7796 UNPC_LOOKDIR
7797 UNPC_STR
7798 UNPC_AGI
7799 UNPC_VIT
7800 UNPC_INT
7801 UNPC_DEX
7802 UNPC_LUK
7803 UNPC_PLUSALLSTAT
7804 UNPC_DMGIMMUNE
7805 UNPC_ATKRANGE
7806 UNPC_ATKMIN
7807 UNPC_ATKMAX
7808 UNPC_MATKMIN
7809 UNPC_MATKMAX
7810 UNPC_DEF
7811 UNPC_MDEF
7812 UNPC_HIT
7813 UNPC_FLEE
7814 UNPC_PDODGE
7815 UNPC_CRIT
7816 UNPC_RACE
7817 UNPC_ELETYPE
7818 UNPC_ELELEVEL
7819 UNPC_AMOTION
7820 UNPC_ADELAY
7821 UNPC_DMOTION
7822
7823*Notes:
7824 - *_SIZE: small (0); medium (1); large (2)
7825 - *_MAPID: this refers to the map_data index (from src/map/map.c), not the mapindex_db index (from src/common/mapindex.c)
7826 -- For 'setunitdata', map name can also be passed in as a valid value instead of map ID
7827 - *_SPEED: 20 - 1000
7828 - *_MODE: see doc/mob_db_mode_list.txt
7829 - *_LOOKDIR: north (0), northwest (1), west (2), etc
7830 - *_CANMOVETICK: seconds * 1000 the unit will be unable to move
7831 - *_DMGIMMUNE: unit will be immune to damage (1), or will receive damage (0)
7832 - *_HUNGER: 0 - 100
7833 - *_INTIMACY: 0 - 1000
7834 - *_LIFETIME: seconds * 1000 the unit will be 'alive' for
7835 - *_AMOTION: see doc/mob_db.txt
7836 - *_ADELAY: see doc/mob_db.txt
7837 - *_DMOTION: see doc/mob_db.txt
7838
7839 - UMOB_AI: none (0); attack (1); marine sphere (2); flora (3); zanzou (4); legion (5); faw (6)
7840 - UMOB_SCOPTION: see the 'Variables' section at the top of this document
7841 - UMOB_SLAVECPYMSTRMD: make the slave copy the master's mode (1), or not (0)
7842
7843 - UNPC_PLUSALLSTAT: same as 'bAllStats'; increases/decreses all stats by given amount
7844
7845Example:
7846 // Spawn some Porings and save the Game ID.
7847 // - Keep in mind, when the 'monster' script command is used,
7848 // - all the spawned monster GID's are stored in an array
7849 // - called $@mobid[].
7850 monster "prontera",149,190,"Poring",1002,10;
7851 .GID = $@mobid[9]; // Store and modify the 10th Poring spawned to make him stronger!
7852
7853 // Save the strong Poring's mob data in the @por_arr[] variable. (@por_arr[1] being level, @por_arr[13] being class, etc.)
7854 // With this data we can have the NPC display or manipulate it how we want. This does not have to be ran before 'setunitdata'.
7855 getunitdata .GID,@por_arr;
7856
7857 // Set the max HP of the Poring to 1000 (current HP will also get updated to 1000).
7858 setunitdata .GID,UMOB_MAXHP,1000;
7859
7860---------------------------------------
7861
7862*geteleminfo <type>{,<char_id>};
7863
7864Get info of elemental of attached player or player by char_id.
7865Other info can be obtained by 'getunitdata' command.
7866
7867Valid types are:
7868 0: Elemental ID
7869 1: Elemental Game ID
7870
7871---------------------------------------
7872\\
78736,1.- End of unit-related commands
7874\\
7875---------------------------------------
7876
7877*npcskill <skill id>,<skill lvl>,<stat point>,<NPC level>;
7878*npcskill "<skill name>",<skill lvl>,<stat point>,<NPC level>;
7879
7880This command causes the attached NPC object to cast a skill on the attached
7881player. The skill will have no cast time or cooldown. The player must be
7882within the default skill range or the command will fail silently.
7883
7884The "stat point" parameter temporarily sets all NPC stats to the given value,
7885and "NPC level" is the temporary level of the NPC (used in some skills).
7886Neither value can be greater than the max level defined in config, and will
7887not work properly if the NPC has a mob sprite.
7888
7889Before using skills, NPCs must have basic stats applied to them depending on the
7890skill being used: UNPC_ATKMIN, UNPC_ATKMAX, UNPC_MATKMIN, UNPC_MATKMAX, UNPC_STR,
7891UNPC_AGI, UNPC_VIT, UNPC_INT, UNPC_DEX, UNPC_LUK.
7892See 'setunitdata' for more information on usage.
7893
7894 // Casts Level 10 Heal on the attached player, calculated with
7895 // all stats 99 and base level 60.
7896 npcskill "AL_HEAL",10,99,60;
7897
7898---------------------------------------
7899
7900*day;
7901*night;
7902
7903These two commands will switch the entire server between day and night mode
7904respectively. If your server is set to cycle between day and night by
7905configuration, it will eventually return to that cycle.
7906
7907Example:
7908
7909- script DayNight -1,{
7910OnClock0600:
7911 day;
7912 end;
7913OnInit:
7914 // setting correct mode upon server start-up
7915 if (gettime(DT_HOUR)>=6 && gettime(DT_HOUR)<18) end;
7916OnClock1800:
7917 night;
7918 end;
7919}
7920
7921This script allows to emulate the day/night cycle as the server does, but also
7922allows triggering additional effects upon change, like announces, gifts, etc.
7923The day/night cycle set by configuration should be disabled when this script is used.
7924
7925---------------------------------------
7926
7927*defpattern <set number>,"<regular expression pattern>","<event label>";
7928*activatepset <set number>;
7929*deactivatepset <set number>;
7930*deletepset <set number>;
7931
7932This set of commands is only available if the server is compiled with regular
7933expressions library enabled. Default compilation and most binary distributions
7934aren't, which is probably bad, since these, while complex to use, are quite
7935fascinating.
7936
7937They will make the NPC object listen for text spoken publicly by players and
7938match it against regular expression patterns, then trigger labels associated
7939with these regular expression patterns.
7940
7941Patterns are organized into sets, which are referred to by a set number. You can
7942have multiple sets patterns, and multiple patterns may be active at once.
7943Numbers for pattern sets start at 1.
7944
7945'defpattern' will associate a given regular expression pattern with an event
7946label. This event will be triggered whenever something a player says is matched
7947by this regular expression pattern, if the pattern is currently active.
7948
7949'activatepset' will make the pattern set specified active. An active pattern
7950will enable triggering labels defined with 'defpattern', which will not happen
7951by default.
7952'deactivatepset' will deactivate a specified pattern set. Giving -1 as a pattern
7953set number in this case will deactivate all pattern sets defined.
7954
7955'deletepset' will delete a pattern set from memory, so you can create a new
7956pattern set in its place.
7957
7958Using regular expressions is high wizardry. But with this high wizardry comes
7959unparalleled power of text manipulation. For an explanation of what a regular
7960expression pattern is, see a few web pages:
7961
7962http://www.regular-expressions.info/
7963http://www.weitz.de/regex-coach/
7964
7965For an example of this in use, see doc/sample/npc_test_pcre.txt
7966
7967With this you could, for example, automatically punish players for asking for
7968Zeny in public places, or alternatively, automatically give them Zeny instead if
7969they want it so much.
7970
7971---------------------------------------
7972
7973*pow(<number>,<power>)
7974
7975Returns the result of the calculation.
7976
7977Example:
7978 .@i = pow(2,3); // .@i will be 8
7979
7980---------------------------------------
7981
7982*sqrt(<number>)
7983
7984Returns the square-root of a number.
7985
7986Example:
7987 .@i = sqrt(25); // .@i will be 5
7988
7989---------------------------------------
7990
7991*distance(<x0>,<y0>,<x1>,<y1>)
7992
7993Returns distance between 2 points.
7994
7995Example:
7996 .@i = distance(100,200,101,202);
7997
7998---------------------------------------
7999
8000*min(<number or array>{,<number or array>,...})
8001*minimum(<number or array>{,<number or array>,...})
8002*max(<number or array>{,<number or array>,...})
8003*maximum(<number or array>{,<number or array>,...})
8004
8005Returns the smallest (or biggest) from the set of given parameters.
8006These parameters have to be either numbers or number arrays.
8007
8008Example:
8009 .@minimum = min( 1, -6, -2, 8, 2 ); // .@minimum will be equal to -6
8010 .@maximum = max( 0, 5, 10, 4 ); // .@maximum will be equal to 10
8011 .@level = min( BaseLevel, 70 ); // .@level will be the character's base level, capped to 70
8012
8013 setarray .@testarray, 4, 5, 12, 6, 7, 3, 8, 9, 10;
8014
8015 .@minimum = min( .@testarray ); // .@minimum will be equal to 3
8016 .@maximum = max( .@testarray ); // .@maximum will be equal to 12
8017
8018 .@minimum = min( -6, 1, 2, 3, .@testarray ); // .@minimum will be equal to -6
8019 .@maximum = max( -6, 1, 2, 3, .@testarray ); // .@maximum will be equal to 12
8020
8021---------------------------------------
8022
8023*round(<number>,<precision>);
8024*ceil(<number>,<precision>);
8025*floor(<number>,<precision>);
8026
8027Returns <number> rounded to multiple of <precision>.
8028
8029`round` function will round the <number> up if its division with <precision> yield a remainder
8030with a value equals to or more than half of <precision>. Otherwise, it rounds the <number> down.
8031`ceil` always round the <number> up.
8032`floor` always round the <number> down.
8033
8034---------------------------------------
8035
8036*md5("<string>")
8037
8038Returns the md5 checksum of a number or string.
8039
8040Example:
8041 mes md5(12345);
8042 mes md5("12345"); // Will both display 827ccb0eea8a706c4c34a16891f84e7b
8043 mes md5("qwerty"); // Will display d8578edf8458ce06fbc5bb76a58c5ca4
8044
8045---------------------------------------
8046
8047*query_sql("your MySQL query"{, <array variable>{, <array variable>{, ...}}});
8048*query_logsql("your MySQL query"{, <array variable>{, <array variable>{, ...}}});
8049
8050Executes an SQL query. A 'select' query can fill array variables with up to 2 billion rows of
8051values, and will return the number of rows (i.e. array size) or -1 on failure.
8052
8053Note that 'query_sql' runs on the main database while 'query_logsql' runs on the log database.
8054
8055Example:
8056 .@nb = query_sql("select name,fame from `char` ORDER BY fame DESC LIMIT 5", .@name$, .@fame);
8057 mes "Hall Of Fame: TOP5";
8058 mes "1." + .@name$[0] + "(" + .@fame[0] + ")"; // largest fame value.
8059 mes "2." + .@name$[1] + "(" + .@fame[1] + ")";
8060 mes "3." + .@name$[2] + "(" + .@fame[2] + ")";
8061 mes "4." + .@name$[3] + "(" + .@fame[3] + ")";
8062 mes "5." + .@name$[4] + "(" + .@fame[4] + ")";
8063
8064---------------------------------------
8065
8066*escape_sql(<value>)
8067
8068Converts the value to a string and escapes special characters so that it is safe to
8069use in query_sql(). Returns the escaped form of the given value.
8070
8071Example:
8072 .@name$ = "John's Laptop";
8073 .@esc_str$ = escape_sql(.@name$); // Escaped string: John\'s Laptop
8074
8075---------------------------------------
8076
8077*setiteminfo(<item id>,<type>,<value>)
8078
8079This function will set some value of an item.
8080Returns the new value on success, or -1 on fail (item_id not found or invalid type).
8081
8082Valid types are:
8083 0 - Buy Price; 1 - Sell Price; 2 - Item Type;
8084 3 - maxchance (Max drop chance of this item e.g. 1 = 0.01% , etc..
8085 if = 0, then monsters don't drop it at all (rare or a quest item)
8086 if = 10000, then this item is sold in NPC shops only
8087 4 - sex; 5 - equip; 6 - weight; 7 - atk; 8 - def; 9 - range;
8088 10 - slot; 11 - look; 12 - elv; 13 - wlv; 14 - view id
8089
8090Example:
8091 setiteminfo 7049,6,9990; // Stone now weighs 999.0
8092
8093---------------------------------------
8094
8095*setitemscript(<item id>,<"{ new item script }">{,<type>});
8096
8097Set a new script bonus to the Item. Very useful for game events.
8098You can remove an item's itemscript by leaving the itemscript argument empty.
8099Returns 1 on success, or 0 on fail (item_id not found or new item script is invalid).
8100Type can optionally be used indicates which script to set (default is 0):
8101 0 - Script
8102 1 - OnEquip_Script
8103 2 - OnUnequip_Script
8104
8105Example:
8106 setitemscript 2637,"{ if (isequipped(2236) == 0)end; if (getskilllv(26)){skill 40,1;}else{skill 26,1+isequipped(2636);} }";
8107 setitemscript 2637,"";
8108
8109---------------------------------------
8110
8111*atoi("<string>")
8112*axtoi("<string>")
8113*strtol("<string>", base)
8114
8115These commands are used to convert strings to numbers. 'atoi' will interpret
8116given string as a decimal number (base 10), while 'axtoi' interprets strings as
8117hexadecimal numbers (base 16). 'strtol' lets the user specify a base (valid range
8118is between 2 and 36 inclusive, or the special value0, which means auto-detection).
8119
8120The 'atoi' and 'strtol' functions conform to the C functions with the same names,
8121and 'axtoi' is the same as strtol, with a base of 16. Results are clamped to signed
812232 bit int range (INT_MIN ~ INT_MAX).
8123
8124Examples:
8125
8126 .@var = atoi("11"); // Sets .@var to 11
8127 .@var = axtoi("FF"); // Sets .@var to 255
8128 mes axtoi("11"); // Displays 17 (1 = 1, 10 = 16)
8129 .@var = strtol("11", 10); // Sets .@var to 11 (11 base 10)
8130 .@var = strtol("11", 16); // Sets .@var to 17 (11 base 16)
8131 .@var = strtol("11", 0); // Sets .@var to 11 (11 base 10, auto-detected)
8132 .@var = strtol("0x11", 0); // Sets .@var to 17 (11 base 16, auto-detected because of the "0x" prefix)
8133 .@var = strtol("011", 0); // Sets .@var to 9 (11 base 8, auto-detected because of the "0" prefix)
8134 .@var = strtol("11", 2); // Sets .@var to 3 (binary 11)
8135
8136---------------------------------------
8137
8138*compare("<string>","<substring>")
8139
8140This command returns 1 or 0 when the substring is in the main string (1) or not (0).
8141This command is not case sensitive.
8142
8143Examples:
8144 //dothis; will be executed ('Bloody Murderer' contains 'Blood').
8145 if (compare("Bloody Murderer","Blood"))
8146 dothis;
8147
8148 //dothat; will not be executed ('Blood butterfly' does not contain 'Bloody').
8149 if (compare("Blood Butterfly","Bloody"))
8150 dothat;
8151
8152---------------------------------------
8153
8154*strcmp("<string>","<string>")
8155
8156This command compares two strings are returns a value:
8157 1: string 1 > string 2
8158 0: strings are equal
8159 -1: string 1 < string 2
8160
8161---------------------------------------
8162
8163*getstrlen("<string>")
8164
8165This function will return the length of the string given as an argument. It is
8166useful to check if anything input by the player exceeds name length limits and
8167other length limits and asking them to try to input something else.
8168
8169---------------------------------------
8170
8171*charisalpha("<string>",<position>)
8172
8173This function will return 1 if the character number Position in the given string
8174is a letter, 0 if it isn't a letter but a digit or a space.
8175The first letter is position 0.
8176
8177---------------------------------------
8178
8179*charat(<string>,<index>)
8180
8181Returns char at specified index. If index is out of range, returns empty string.
8182The first letter of a string is index 0.
8183
8184Example:
8185 charat("This is a string", 10); //returns "s"
8186
8187---------------------------------------
8188
8189*setchar(<string>,<char>,<index>)
8190
8191Returns the original string with the char at the specified index set to the
8192specified char. If index out of range, the original string will be returned.
8193Only the 1st char in the <char> parameter will be used.
8194
8195Example:
8196 setchar("Cat", "B", 0); //returns "Bat"
8197
8198---------------------------------------
8199
8200*insertchar(<string>,<char>,<index>)
8201
8202Returns the original string with the specified char inserted at the specified
8203index. If index is out of range, the char will be inserted on the end of the
8204string that it is closest. Only the 1st char in the <char> parameter will be used.
8205
8206Example:
8207 insertchar("laughter", "s", 0); //returns "slaughter"
8208
8209---------------------------------------
8210
8211*delchar(<string>,<index>)
8212
8213Returns the original string with the char at the specified index removed.
8214If index is out of range, original string will be returned.
8215
8216Example:
8217 delchar("Diet", 3); //returns "Die"
8218
8219---------------------------------------
8220
8221*strtoupper(<string>)
8222*strtolower(<string>)
8223
8224Returns the specified string in its uppercase/lowercase form.
8225All non-alpha characters will be preserved.
8226
8227Example:
8228 strtoupper("The duck is blue!!"); //returns "THE DUCK IS BLUE!!"
8229
8230---------------------------------------
8231
8232*charisupper(<string>,<index>)
8233*charislower(<string>,<index>)
8234
8235Returns 1 if character at specified index of specified string is
8236uppercase/lowercase. Otherwise, 0. Characters not of the alphabet will return 0.
8237
8238Example:
8239 charisupper("rAthena", 1); //returns 1
8240
8241---------------------------------------
8242
8243*substr(<string>,<start_index>,<end_index>)
8244
8245Returns the sub-string of the specified string inclusively between the set
8246indexes. If indexes are out of range, or the start index is after the end
8247index, an empty string will be returned.
8248
8249Example:
8250 substr("foobar", 3, 5); //returns "bar"
8251
8252---------------------------------------
8253
8254*explode(<dest_array>,<string>,<delimiter>)
8255
8256Breaks a string up into substrings based on the specified delimiter. Substrings
8257will be stored within the specified string array. Only the 1st char of the
8258delimiter parameter will be used. If an empty string is passed as a delimiter,
8259the string will be placed in the array in its original form.
8260
8261Example:
8262 explode(.@my_array$, "Explode:Test:1965:red:PIE", ":");
8263 //.@my_array$ contents will be...
8264 //.@my_array$[0]: "Explode"
8265 //.@my_array$[1]: "Test"
8266 //.@my_array$[2]: "1965"
8267 //.@my_array$[3]: "red"
8268 //.@my_array$[4]: "PIE"
8269
8270---------------------------------------
8271
8272*implode(<string_array>{,<glue>})
8273
8274Combines all substrings within the specified string array into a single string.
8275If the glue parameter is specified, it will be inserted inbetween each substring.
8276
8277Example:
8278 setarray .@my_array$[0], "This", "is", "a", "test";
8279 implode(.@my_array$, " "); //returns "This is a test"
8280
8281---------------------------------------
8282
8283*sprintf(<format>[,param[,param[,...]]])
8284
8285C style sprintf. The resulting string is returned same as in PHP. All C format
8286specifiers are supported except %n. More info: sprintf @ www.cplusplus.com.
8287The number of params is only limited by rA's script engine.
8288
8289Example:
8290 .@format$ = "The %s contains %d monkeys";
8291 dispbottom(sprintf(.@format$, "zoo", 5)); //prints "The zoo contains 5 monkeys"
8292 dispbottom(sprintf(.@format$, "barrel", 82)); //prints "The barrel contains 82 monkeys"
8293
8294---------------------------------------
8295
8296*sscanf(<string>,<format>[,param[,param[,...]]])
8297
8298C style sscanf. All C format specifiers are supported.
8299More info: sscanf @ www.cplusplus.com. The number of params is only limited
8300by rA's script engine.
8301
8302Example:
8303 sscanf("This is a test: 42 foobar", "This is a test: %d %s", .@num, .@str$);
8304 dispbottom(.@num + " " + .@str$); //prints "42 foobar"
8305
8306---------------------------------------
8307
8308*strpos(<haystack>,<needle>{,<offset>})
8309
8310PHP style strpos. Finds a substring (needle) within a string (haystack).
8311The offset parameter indicates the index of the string to start searching.
8312Returns index of substring on successful search, else -1.
8313Comparison is case sensitive.
8314
8315Example:
8316 strpos("foobar", "bar", 0); //returns 3
8317 strpos("foobarfoo", "foo", 0); //returns 0
8318 strpos("foobarfoo", "foo", 1); //returns 6
8319
8320---------------------------------------
8321
8322*replacestr(<input>, <search>, <replace>{, <usecase>{, <count>}})
8323
8324Replaces all instances of a search string in the input with the specified
8325replacement string. By default is case sensitive unless <usecase> is set
8326to 0. If specified it will only replace as many instances as specified
8327in the count parameter.
8328
8329Example:
8330 replacestr("testing tester", "test", "dash"); //returns "dashing dasher"
8331 replacestr("Donkey", "don", "mon", 0); //returns "monkey"
8332 replacestr("test test test test test", "test", "yay", 0, 3); //returns "yay yay yay test test"
8333
8334---------------------------------------
8335
8336*countstr(<input>, <search>{, <usecase>})
8337
8338Counts all instances of a search string in the input. By default is case
8339sensitive unless <usecase> is set to 0.
8340
8341Example:
8342 countstr("test test test Test", "test"); //returns 3
8343 countstr("cake Cake", "Cake", 0); //returns 2
8344
8345---------------------------------------
8346
8347*preg_match(<regular expression pattern>,<string>{,<offset>})
8348
8349Searches a string for a match to the regular expression provided. The
8350offset parameter indicates the index of the string to start searching.
8351Returns offsets to captured substrings, or 0 if no match is found.
8352
8353This command is only available if the server is compiled with the regular
8354expressions library enabled.
8355
8356---------------------------------------
8357
8358*setfont <font>;
8359
8360This command sets the current RO client interface font to one of the
8361fonts stored in data\*.eot by using an ID of the font. When the ID
8362of the currently used font is used, default interface font is used
8363again.
8364
8365 0 - Default
8366 1 - RixLoveangel
8367 2 - RixSquirrel
8368 3 - NHCgogo
8369 4 - RixDiary
8370 5 - RixMiniHeart
8371 6 - RixFreshman
8372 7 - RixKid
8373 8 - RixMagic
8374 9 - RixJJangu
8375
8376---------------------------------------
8377
8378*showdigit <value>{,<type>};
8379
8380Displays given numeric 'value' in large digital clock font on top of
8381the screen. The optional parameter 'type' specifies visual aspects
8382of the "clock" and can be one of the following values:
8383
8384 0 - Displays the value for 5 seconds (default).
8385 1 - Incremental counter (1 tick/second).
8386 2 - Decremental counter (1 tick/second). Does not stop at zero,
8387 but overflows.
8388 3 - Decremental counter (2 ticks/second). Two digits only, stops
8389 at zero.
8390
8391Except for type 3 the value is interpreted as seconds and formatted
8392as time in days, hours, minutes and seconds. Note, that the official
8393script command does not have the optional parameter.
8394
8395 // displays 23:59:59 for 5 seconds
8396 showdigit 86399;
8397
8398 // counter that starts at 60 and runs for 30 seconds
8399 showdigit 60,3;
8400
8401---------------------------------------
8402
8403*setcell "<map name>",<x1>,<y1>,<x2>,<y2>,<type>,<flag>;
8404
8405Each map cell has several 'flags' that specify the properties of that cell.
8406These include terrain properties (walkability, shootability, presence of water),
8407skills (basilica, land protector, ...) and other (NPC nearby, no vending, ...).
8408Each of these can be 'on' or 'off'. Together they define a cell's behavior.
8409
8410This command lets you alter these flags for all map cells in the specified
8411(x1,y1)-(x2,y2) rectangle. The 'flag' can be 0 or 1 (0:clear flag, 1:set flag).
8412The 'type' defines which flag to modify. Possible options see 'src/map/script_constants.h'.
8413
8414Example:
8415
8416 setcell "arena",0,0,300,300,cell_basilica,1;
8417 setcell "arena",140,140,160,160,cell_basilica,0;
8418 setcell "arena",135,135,165,165,cell_walkable,0;
8419 setcell "arena",140,140,160,160,cell_walkable,1;
8420
8421This will add a makeshift ring into the center of the map. The ring will be
8422surrounded by a 5-cell wide 'gap' to prevent interference from outside, and
8423the rest of the map will be marked as 'basilica', preventing observers from
8424casting any offensive skills or fighting among themselves. Note that the wall
8425will not be shown nor known client-side, which may cause movement problems.
8426
8427Another example:
8428
8429OnBarricadeDeploy:
8430 setcell "schg_cas05",114,51,125,51,cell_walkable,0;
8431 end;
8432OnBarricadeBreak:
8433 setcell "schg_cas05",114,51,125,51,cell_walkable,1;
8434 end;
8435
8436This could be a part of the WoE:SE script, where attackers are not allowed
8437to proceed until all barricades are destroyed. This script would place and
8438remove a nonwalkable row of cells after the barricade mobs.
8439
8440---------------------------------------
8441
8442*checkcell ("<map name>",<x>,<y>,<type>);
8443
8444This command will return 1 or 0, depending on whether the specified cell has
8445the 'type' flag set or not. There are various types to check, all mimicking
8446the server's cell_chk enumeration. The types can be found in 'src/map/script_constants.h'.
8447
8448The meaning of the individual types can be confusing, so here's an overview:
8449 - cell_chkwall/water/cliff
8450 these check directly for the 'terrain component' of the specified cell
8451 - cell_chkpass/reach/nopass/noreach
8452 passable = not wall & not cliff, reachable = passable wrt. no-stacking mod
8453 - cell_chknpc/basilica/landprotector/novending/nochat
8454 these check for specific dynamic flags (their name indicates what they do)
8455
8456Example:
8457 mes "Pick a destination map.";
8458 input .@map$;
8459 mes "Alright, now give me the coordinates.";
8460 input .@x;
8461 input .@y;
8462 if ( !checkcell(.@map$,.@x,.@y,cell_chkpass) ) {
8463 mes "Can't warp you there, sorry!";
8464 close;
8465 } else {
8466 mes "Ok, get ready...";
8467 close2;
8468 warp .@map$, .@x, .@y;
8469 end;
8470 }
8471
8472---------------------------------------
8473
8474*getfreecell "<map name>",<rX>,<rY>{,<x>,<y>,<rangeX>,<rangeY>,<flag>};
8475
8476Finds a free cell on the given map and stores the reference to the found cell
8477in <rX> and <rY>. Passing <x> and <y> with <rangeX> and <rangeY> allows for
8478searching within a specified area on the given map. The <flag> is a bitmask
8479and has the following possible values:
8480 - 1 = Random cell on the map or from <x>,<y> range. (default)
8481 - 2 = The target should be able to walk to the target tile.
8482 - 4 = There shouldn't be any players around the target tile (use the no_spawn_on_player setting).
8483
8484Examples:
8485 getfreecell("prontera",.@x,.@y); // Find a random empty cell in Prontera and store it within .@x and .@y
8486 getfreecell("prontera",.@x,.@y,150,150,5,5); // Find a random empty cell on 150,150 (with a range of 5x5) in Prontera and store it within .@x and .@y
8487
8488---------------------------------------
8489
8490*setwall "<map name>",<x>,<y>,<size>,<dir>,<shootable>,"<name>";
8491*delwall "<name>";
8492
8493Creates an invisible wall, an array of "setcell" starting from x,y and doing a
8494line of the given size in the given direction. The difference with setcell is
8495this one update client part too to avoid the glitch problem. Directions are the
8496same as NPC sprite facing directions: 0=north, 1=northwest, 2=west, etc.
8497
8498---------------------------------------
8499
8500*readbook <book id>,<page>;
8501
8502This command will open a book item at the specified page.
8503
8504---------------------------------------
8505
8506========================
8507|7.- Instance commands.|
8508========================
8509---------------------------------------
8510
8511*instance_create("<instance name>"{,<instance mode>{,<owner id>}});
8512
8513Creates an instance for the <owner id> of <mode>. The instance name, along with
8514all other instance data, is read from 'db/(pre-)re/instance_db.txt'. Upon success,
8515the command generates a unique instance ID, duplicates all listed maps and NPCs,
8516sets the alive time, and triggers the "OnInstanceInit" label in all NPCs inside
8517the instance.
8518
8519Instance Mode options:
8520 IM_NONE: Attached to no one.
8521 IM_CHAR: Attached to a single character.
8522 IM_PARTY: Attached to a party (default instance mode).
8523 IM_GUILD: Attached to a guild.
8524 IM_CLAN: Attached to a clan.
8525
8526The command returns the instance ID upon success, and these values upon failure:
8527 -1: Invalid type.
8528 -2: Character/Party/Guild/Clan not found.
8529 -3: Instance already exists.
8530 -4: No free instances (MAX_INSTANCE exceeded).
8531
8532---------------------------------------
8533
8534*instance_destroy {<instance id>};
8535
8536Destroys instance with the ID <instance id>. If no ID is specified, the instance
8537the script is attached to is used. If the script is not attached to an instance,
8538the instance of the currently attached player is used (if it is a character, party,
8539guild or clan mode). If it is not owned by anyone, no player needs to be attached. If
8540that fails, the script will come to a halt. This will also trigger the "OnInstanceDestroy"
8541label in all NPCs inside the instance.
8542
8543---------------------------------------
8544
8545*instance_enter("<instance name>",{<x>,<y>,<char_id>,<instance id>});
8546
8547Warps player to the specified instance after the script terminates. The map and
8548coordinates are located in 'db/(pre-)re/instance_db.txt'.
8549
8550The command returns IE_OK upon success, and these values upon failure:
8551 IE_NOMEMBER: Party/Guild/Clan not found (for party/guild/clan modes).
8552 IE_NOINSTANCE: Character/Party/Guild/Clan does not have an instance.
8553 IE_OTHER: Other errors (invalid instance name, instance doesn't match with character/party/guild/clan).
8554
8555Put -1 for x and y if want to warp player with default entrance coordinates.
8556
8557---------------------------------------
8558
8559*instance_npcname("<npc name>"{,<instance id>})
8560
8561Returns the unique name of the instanced script. If no ID is specified,
8562the instance the script is attached to is used. If the script is not attached to
8563an instance, the instance of the currently attached NPC, player, party, guild
8564or clan is used. If that fails, the script will come to a halt.
8565
8566---------------------------------------
8567
8568*instance_mapname("<map name>"{,<instance id>})
8569
8570Returns the unique name of the instanced map. If no instance ID is specified,
8571the instance the script is attached to is used. If the script is not attached to
8572an instance, the instance of the currently attached player is used (if it is a
8573character, party, guild or clan mode). If it is not owned by anyone, no player needs
8574to be attached. If that fails, the command returns an empty string instead.
8575
8576---------------------------------------
8577
8578*instance_id()
8579
8580Returns the unique instance id of the attached script. If the script is not
8581attached to an instance, the instance of the currently attached player is
8582used (if it is a character, party, guild or clan mode). If it is not owned by anyone, no
8583player needs to be attached. If that fails, the function will return 0.
8584
8585---------------------------------------
8586
8587*instance_warpall "<map name>",<x>,<y>{,<instance id>};
8588
8589Warps all players in the instance <instance id> to <map name> at given
8590coordinates. If no ID is specified, the instance the script is attached to
8591is used. If the script is not attached to an instance, the instance of the
8592currently attached player is used (if it is a character, party, guild or clan
8593mode). If it is not owned by anyone, no player needs to be attached. If that
8594fails, the script will come to a halt.
8595
8596---------------------------------------
8597
8598*instance_announce <instance id>,"<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}};
8599
8600Broadcasts a message to all players in the instance <instance id> currently
8601residing on an instance map. If 0 is specified for <instance id>, the instance
8602the script is attached to is used. If the script is not attached to an instance,
8603the instance of the currently attached player is used (if it is a character,
8604party, guild or clan mode). If it is not owned by anyone, no player needs to be attached.
8605
8606For details on the other parameters, see 'announce'.
8607
8608---------------------------------------
8609
8610*instance_check_party(<party id>{,<amount>{,<min>{,<max>}}})
8611
8612This function checks if a party meets certain requirements, returning 1 if all
8613conditions are met and 0 otherwise. It will only check online characters.
8614
8615amount - number of online party members (default is 1).
8616min - minimum level of all characters in the party (default is 1).
8617max - maximum level of all characters in the party (default is max level in conf).
8618
8619Example:
8620
8621if (instance_check_party(getcharid(1),2,2,149)) {
8622 mes "Your party meets the Memorial Dungeon requirements.",
8623 mes "All online members are between levels 1-150 and at least two are online.";
8624 close;
8625} else {
8626 mes "Sorry, your party does not meet requirements.";
8627 close;
8628}
8629
8630---------------------------------------
8631
8632*instance_check_guild(<guild id>{,<amount>{,<min>{,<max>}}})
8633
8634This function checks if a guild meets certain requirements, returning 1 if all
8635conditions are met and 0 otherwise. It will only check online characters.
8636
8637amount - number of online guild members (default is 1).
8638min - minimum level of all characters in the guild (default is 1).
8639max - maximum level of all characters in the guild (default is max level in conf).
8640
8641Example:
8642
8643if (instance_check_guild(getcharid(2),2,2,149)) {
8644 mes "Your guild meets the Memorial Dungeon requirements.",
8645 mes "All online members are between levels 1-150 and at least two are online.";
8646 close;
8647} else {
8648 mes "Sorry, your guild does not meet requirements.";
8649 close;
8650}
8651
8652---------------------------------------
8653
8654*instance_check_clan(<clan id>{,<amount>{,<min>{,<max>}}})
8655
8656This function checks if a clan meets certain requirements, returning 1 if all
8657conditions are met and 0 otherwise. It will only check online characters.
8658
8659amount - number of online clan members (default is 1).
8660min - minimum level of all characters in the clan (default is 1).
8661max - maximum level of all characters in the clan (default is max level in conf).
8662
8663Example:
8664
8665if (instance_check_clan(getcharid(5),2,2,149)) {
8666 mes "Your clan meets the Memorial Dungeon requirements.",
8667 mes "All online members are between levels 1-150 and at least two are online.";
8668 close;
8669} else {
8670 mes "Sorry, your clan does not meet requirements.";
8671 close;
8672}
8673
8674---------------------------------------
8675
8676*instance_info("<instance name>",<info type>{,<instance_db map index>});
8677
8678Returns the specified <info type> of the given <instance name> from the instance database.
8679If the <instance name> is unknown or an invalid <info type> is supplied -1 will be returned.
8680
8681Valid info types:
8682 IIT_ID: Instance database ID as integer.
8683 IIT_TIME_LIMIT: Instance database total life time as integer.
8684 IIT_IDLE_TIMEOUT: Instance database timeout time as integer.
8685 IIT_ENTER_MAP: Instance database enter map as string.
8686 IIT_ENTER_X: Instance database enter X location as integer.
8687 IIT_ENTER_Y: Instance database enter Y location as integer.
8688 IIT_MAPCOUNT: Instance database total maps as integer.
8689 IIT_MAP: Instance database map name from the given <instance_db map index> as string.
8690 If the index is invalid an empty string will be returned.
8691
8692Example:
8693
8694.@name$ = "Endless Tower";
8695mes .@name$ + " will be destroyed if no one is in the instance for " + instance_info(.@name$,IIT_IDLETIMEOUT) + " seconds.";
8696// Endless Tower will be destroyed if no one is in the instance for 300 seconds.
8697
8698---------------------------------------
8699
8700=========================
8701|8.- Quest Log commands.|
8702=========================
8703---------------------------------------
8704
8705*questinfo <Quest ID>,<Icon>{,<Map Mark Color>{,<Job Class>}};
8706
8707This is esentially a combination of checkquest and showevent. Use this only
8708in an OnInit label. For the Quest ID, specify the quest ID that you want
8709checked if it has been started yet.
8710
8711For Icon, use one of the following:
8712
8713No Icon : QTYPE_NONE
8714! Quest Icon : QTYPE_QUEST
8715? Quest Icon : QTYPE_QUEST2
8716! Job Icon : QTYPE_JOB
8717? Job Icon : QTYPE_JOB2
8718! Event Icon : QTYPE_EVENT
8719? Event Icon : QTYPE_EVENT2
8720Warg : QTYPE_WARG
8721Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410)
8722
8723Map Mark Color, when used, creates a mark in the user's mini map on the position of the NPC,
8724the available color values are:
8725
87260 - No Marker (default)
87271 - Yellow Marker
87282 - Green Marker
87293 - Purple Marker
8730
8731When a user shows up on a map, each NPC is checked for questinfo that has been set.
8732If questinfo is present, it will check if the quest has been started, if it has not, the bubble will appear.
8733
8734Optionally, you can also specify a Job Class if the quest bubble should only appear for a certain class.
8735
8736Example
8737izlude,100,100,4 script Test 844,{
8738 mes "[Test]";
8739 mes "Hello World.";
8740 close;
8741
8742 OnInit:
8743 questinfo 1001, QTYPE_QUEST, 0, Job_Novice;
8744 end;
8745}
8746
8747---------------------------------------
8748
8749*setquestinfo_level <quest_id>,<min_level>,<max_level>;
8750
8751Add level range criteria for quest info with quest id 'quest_id'.
8752
8753This command must be used after 'questinfo'.
8754
8755---------------------------------------
8756
8757*setquestinfo_req <quest_id>,<req_quest_id>,<state>{,<req_quest_id>,<state>,...};
8758
8759Add 'req_quest_id' as requirement for quest info with quest id 'quest_id'.
8760
8761Value os 'state' are:
8762 0: Player doesn't started 'req_quest_id'.
8763 1: Player has 'req_quest_id' (state is either "inactive" or "active").
8764 2: Player has 'req_quest_id' completed
8765
8766This command must be used after 'questinfo'.
8767
8768---------------------------------------
8769
8770*setquestinfo_job <quest_id>,<job_id>{,<job_id>...};
8771
8772Add job criteria for quest info with quest id 'quest_id'.
8773The job criteria may more than one job_id.
8774
8775This command must be used after 'questinfo'.
8776
8777---------------------------------------
8778
8779*setquest <ID>{,<char_id>};
8780
8781Place quest of <ID> in the users quest log, the state of which is "active".
8782
8783If *questinfo is set, and the same ID is specified here, the icon will be cleared when the quest is set.
8784
8785---------------------------------------
8786
8787*completequest <ID>{,<char_id>};
8788
8789Change the state for the given quest <ID> to "complete" and remove from the users quest log.
8790
8791---------------------------------------
8792
8793*erasequest <ID>{,<char_id>};
8794
8795Remove the quest of the given <ID> from the user's quest log.
8796
8797---------------------------------------
8798
8799*changequest <ID>,<ID2>{,<char_id>};
8800
8801Remove quest of the given <ID> from the user's quest log.
8802Add quest of the <ID2> to the the quest log, and the state is "active".
8803
8804---------------------------------------
8805
8806*checkquest(<ID>{,PLAYTIME|HUNTING{,<char_id>}})
8807
8808If no additional argument supplied, return the state of the quest:
8809 -1 = Quest not started (not in quest log)
8810 0 = Quest has been given, but the state is "inactive"
8811 1 = Quest has been given, and the state is "active"
8812 2 = Quest completed
8813
8814If parameter "PLAYTIME" is supplied:
8815 -1 = Quest not started (not in quest log)
8816 0 = the time limit has not yet been reached
8817 1 = the time limit has not been reached but the quest is marked as complete
8818 2 = the time limit has been reached
8819
8820If parameter "HUNTING" is supplied:
8821 -1 = Quest not started (not in quest log)
8822 0 = you haven't killed all of the target monsters and the time limit has not been reached.
8823 1 = you haven't killed all of the target monsters but the time limit has been reached.
8824 2 = you've killed all of the target monsters
8825
8826---------------------------------------
8827
8828*isbegin_quest(<ID>{,<char_id>})
8829
8830Return the state of the quest:
8831 0 = Quest not started (not in quest log)
8832 1 = Quest has been given (state is either "inactive" or "active")
8833 2 = Quest completed
8834
8835---------------------------------------
8836
8837*showevent <icon>{,<mark color>{,<char_id>}}
8838
8839Show an emotion on top of a NPC, and optionally,
8840a colored mark in the mini-map like "viewpoint".
8841This is used to indicate that a NPC has a quest or an event to
8842a certain player.
8843
8844Available Icons:
8845
8846Remove Icon : QTYPE_NONE
8847! Quest Icon : QTYPE_QUEST
8848? Quest Icon : QTYPE_QUEST2
8849! Job Icon : QTYPE_JOB
8850? Job Icon : QTYPE_JOB2
8851! Event Icon : QTYPE_EVENT
8852? Event Icon : QTYPE_EVENT2
8853Warg : QTYPE_WARG
8854Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410)
8855
8856Mark Color:
88570 - No Mark
88581 - Yellow Mark
88592 - Green Mark
88603 - Purple Mark
8861
8862---------------------------------------
8863
8864============================
8865|9.- Battleground commands.|
8866============================
8867---------------------------------------
8868
8869*waitingroom2bg_single(<battle group>,{"<map name>",<x>,<y>{,"<npc name>"}});
8870
8871Adds the first waiting player from the chat room of the given NPC to an existing battleground group.
8872The player will also be warped to the default spawn point of the battle group or to the specified coordinates <x> and <y> on the given <map>.
8873
8874---------------------------------------
8875
8876*waitingroom2bg("<map name>",<x>,<y>,{"<On Quit Event>","<On Death Event>"{,"<NPC Name>"}});
8877
8878<map name>,<x>,<y> refer to where the "respawn" base is, where the player group will respawn when they die.
8879<On Quit Event> refers to an NPC label that attaches to the character and is run when they relog. (Optional)
8880<On Death Event> refers to an NPC label that attaches to the character and is run when they die. (Optional)
8881
8882Unlike the prior command, the latter will attach a GROUP in a waiting room to the battleground, and
8883sets the array $@arenamembers[0] where 0 holds the IDs of the first group, and 1 holds the IDs of the second.
8884
8885If the optional NPC Name parameter is left out, the waiting room of the current NPC is used.
8886
8887Example:
8888 // Battle Group will be referred to as $@KvM01BG_id1, and when they die, respawn at bat_c01,52,129.
8889 set $@KvM01BG_id1, waitingroom2bg("bat_c01",52,129,"KvM01_BG::OnGuillaumeQuit","KvM01_BG::OnGuillaumeDie");
8890 end;
8891
8892---------------------------------------
8893
8894*bg_create("<map name>",<x>,<y>{,"<On Quit Event>","<On Death Event>"});
8895
8896Creates an instance of battleground battle group that can be used with other battleground commands.
8897
8898<map name>,<x>,<y> refer to where the "respawn" base is, where the player group will respawn when they die.
8899<On Quit Event> refers to an NPC label that attaches to the character and is run when they relog. (Optional)
8900<On Death Event> refers to an NPC label that attaches to the character and is run when they die. (Optional)
8901
8902Returns battle group ID on success. Returns 0 on failure.
8903
8904---------------------------------------
8905
8906*bg_join(<battle group>,{"<map name>",{<x>,<y>{,<char id>}});
8907
8908Adds an attached player or <char id> if specified to an existing battleground group. The player will also be warped to the default spawn point of the battle group or to the specified coordinates <x> and <y> on the given <map>.
8909
8910Returns true on success. Returns false on failure.
8911
8912---------------------------------------
8913
8914*bg_team_setxy <Battle Group ID>,<x>,<y>;
8915
8916Updates the respawn point of the given Battle Group to x,y on the same map. <Battle Group ID> can be retrieved using getcharid(4).
8917
8918Example:
8919 bg_team_setxy getcharid(4),56,212;
8920 mapannounce "bat_a01", "Group [1] has taken the work shop, and will now respawn there.",bc_map,"0xFFCE00";
8921 end;
8922
8923---------------------------------------
8924
8925*bg_warp <Battle Group>,"<map name>",<x>,<y>;
8926
8927Similar to the 'warp' command.
8928Places all members of <Battle Group> at the specified map and coordinates.
8929
8930Example:
8931 //place the battle group one for Tierra Gorge at starting position.
8932 bg_warp $@TierraBG1_id1,"bat_a01",352,342;
8933 end;
8934
8935---------------------------------------
8936
8937*bg_monster <Battle Group>,"<map name>",<x>,<y>,"<name to show>",<mob id>,"<event label>";
8938*bg_monster(<Battle Group>,"<map name>",<x>,<y>,"<name to show>",<mob id>,"<event label>");
8939
8940Similar to the 'monster' command.
8941Spawns a monster with allegiance to the given Battle Group.
8942Does not allow for the summoning of multiple monsters.
8943Monsters are similar to those in War of Emperium, in that the specified Battle Group is considered friendly.
8944
8945Example:
8946 // It can be used in two different ways.
8947 bg_monster $@TierraBG1_id2,"bat_a01",167,50,"Food Depot",1910,"Feed Depot#1::OnMyMobDead";
8948 end;
8949
8950 // Alternatively, you can set an ID for the monster using "set".
8951 // This becomes useful when used with the command below.
8952 set $@Guardian_3, bg_monster($@TierraBG1_id2,"bat_a01",268,204,"Guardian",1949,"NPCNAME::OnMyMobDead");
8953 end;
8954
8955---------------------------------------
8956
8957*bg_monster_set_team <GID>,<Battle Group>;
8958
8959This command will change the allegiance if a monster in a battle ground.
8960GID can be set when spawning the monster via the 'bg_monster' command.
8961
8962Example:
8963
8964 end;
8965
8966OnEnable:
8967 mapannounce "A guardian has been summoned for Battle Group 2!",bc_map,"0xFFCE00";
8968 set $@Guardian, bg_monster($@BG_2,"bat_a01",268,204,"Guardian",1949,"NPCNAME::OnMyMobDead");
8969 initnpctimer;
8970 end;
8971
8972OnTimer1000:
8973 stopnpctimer;
8974 mapannounce "Erm, sorry about that! This monster was meant for Battle Group 1.",bc_map,"0xFFCE00";
8975 bg_monster_set_team $@Guardian, $@BG_1;
8976 end;
8977
8978---------------------------------------
8979
8980*bg_leave {<char_id>};
8981
8982Removes attached player from their Battle Group.
8983
8984---------------------------------------
8985
8986*bg_destroy <Batte Group>;
8987
8988Destroys the Battle Group created for that battle ground.
8989
8990---------------------------------------
8991
8992*areapercentheal "<map name>",<x1>,<y1>,<x2>,<y2>,<hp>,<sp>;
8993
8994Restores a percentage of the maximum HP/SP of players within a defined area.
8995This is primarily used in battleground scripts, but is not limited to them.
8996
8997Example:
8998 areapercentheal "bat_a01",52,208,61,217,100,100;
8999 end;
9000
9001---------------------------------------
9002
9003*bg_get_data(<Battle Group>,<type>);
9004
9005Retrieves data related to given Battle Group. Type can be one of the following:
9006
9007 0 - Amount of players currently belonging to the group.
9008 1 - Store GID of players in <Battle Group> in a temporary global array $@arenamembers
9009 and returns amount of players currently belonging to the group.
9010
9011---------------------------------------
9012
9013*bg_getareausers(<Battle Group>,"<map name>",<x0>,<y0>,<x1>,<y1>);
9014
9015Retrieves the amount of players belonging to the given Battle Group on the given
9016map within the specified rectangular area.
9017
9018---------------------------------------
9019
9020*bg_updatescore "<map name>",<Guillaume Score>,<Croix Score>;
9021
9022This command will force the update of the displayed scoreboard.
9023It is only usable when the map is defined as a Type 2 Battleground:
9024mapflag <map name> battleground 2
9025
9026---------------------------------------
9027
9028====================
9029|10.- Pet commands.|
9030====================
9031---------------------------------------
9032
9033*bpet;
9034*birthpet;
9035
9036This command opens up a pet hatching window on the client connected to the
9037invoking character. It is used in item script for the pet incubators and will
9038let the player hatch an owned egg. If the character has no eggs, it will just
9039open up an empty incubator window.
9040This is still usable outside item scripts.
9041
9042---------------------------------------
9043
9044*pet <pet id>;
9045*catchpet <pet id>;
9046
9047This command is used in all the item scripts for taming items. Running this
9048command will make the pet catching cursor appear on the client connected to the
9049invoking character, usable on the monsters with the specified pet ID number. It
9050will still work outside an item script.
9051If the <pet id> is PET_CATCH_UNIVERSAL the item will attempt to catch the targeted
9052monster as long as it is in the pet database and does not have the MD_STATUS_IMMUNE
9053monster mode.
9054If the <pet id> is PET_CATCH_UNIVERSAL_ITEM the item will attempt to catch the targeted
9055monster as long as it is in the pet database and the targeted monster requires the lure
9056item used.
9057See 'doc/mob_db_mode_list.txt' for more information about monster modes.
9058
9059A full list of pet IDs can be found inside 'db/(pre-)re/pet_db.txt'.
9060
9061---------------------------------------
9062
9063*makepet <pet id>;
9064
9065This command will create a pet egg and put it in the invoking character's
9066inventory. The kind of pet is specified by pet ID numbers listed in
9067'db/(pre-)re/pet_db.txt'. The egg is created exactly as if the character just successfully
9068caught a pet in the normal way.
9069
9070 // This will make you a poring:
9071 makepet 1002;
9072
9073Notice that you absolutely have to create pet eggs with this command. If you try
9074to give a pet egg with 'getitem', pet data will not be created by the char
9075server and the egg will disappear when anyone tries to hatch it.
9076
9077---------------------------------------
9078
9079*getpetinfo(<type>{,<char_id>})
9080
9081This function will return pet information for the pet the invoking character
9082currently has active. Valid types are:
9083
9084 PETINFO_ID - Pet ID
9085 PETINFO_CLASS - Pet class number as per 'db/(pre-)re/pet_db.txt' - will tell you what kind of a pet it
9086 is.
9087 PETINFO_NAME - Pet name. Will return "null" if there's no pet.
9088 PETINFO_INTIMATE - Pet friendly level (intimacy score). 1000 is full loyalty.
9089 PETINFO_HUNGRY - Pet hungry level. 100 is completely full.
9090 PETINFO_RENAMED - Pet rename flag. 0 means this pet has not been named yet.
9091 PETINFO_LEVEL - Pet level
9092 PETINFO_BLOCKID - Pet Game ID
9093
9094---------------------------------------
9095
9096=============================
9097|10.1.- The Pet AI commands.|
9098=============================
9099---------------------------------------
9100
9101These commands will only work if the invoking character has a pet, and are meant
9102to be executed from pet scripts. They will modify the pet AI decision-making for
9103the current pet of the invoking character, and will NOT have any independent
9104effect by themselves, which is why only one of them each may be in effect at any
9105time for a specific pet. A pet may have 'petloot', 'petskillbonus',
9106'petskillattack' OR 'petpetskillattack2' and 'petskillsupport'.
9107
9108All commands with delays and durations will only make the behavior active for
9109the specified duration of seconds, with a delay of the specified number of
9110seconds between activations. Rates are a chance of the effect occurring and are
9111given in percent. 'bonusrate' is added to the normal rate if the pet intimacy is
9112at the maximum possible.
9113
9114The behavior modified with the below mentioned commands will only be exhibited if
9115the pet is loyal and appropriate configuration options are set in
9116'battle_athena.conf'.
9117
9118Pet scripts in the database normally run whenever a pet of that type hatches
9119from the egg. Other commands usable in item scripts (see 'bonus') will also
9120happily run from pet scripts. Apparently, the pet-specific commands will also
9121work in NPC scripts and modify the behavior of the current pet up until the pet
9122is hatched again. (Which will also occur when the character is logged in again
9123with the pet still out of the egg.) It is not certain for how long the effect of
9124such command running from an NPC script will eventually persist, but apparently,
9125it is possible to usefully employ them in usable item scripts to create pet
9126buffing items.
9127
9128Nobody tried this before, so you're essentially on your own here.
9129
9130---------------------------------------
9131
9132*petskillbonus <bonus type>,<value>,<duration>,<delay>;
9133
9134This command will make the pet give a bonus to the owner's stat in certain
9135duration in seconds and will be repeated for certain delay in seconds.
9136
9137For a full bonus list, see 'doc/item_bonus.txt'
9138NOTE: Currently ONLY supported for bonuses that used by 'bonus' script.
9139
9140---------------------------------------
9141
9142*petrecovery <status type>,<delay>;
9143
9144This command will make the pet cure a specified status condition. The curing
9145actions will occur once every Delay seconds. For a full list of status
9146conditions that can be cured, see the list of 'SC_' status condition constants
9147in 'src/map/script_constants.h'.
9148
9149---------------------------------------
9150
9151*petloot <max items>;
9152
9153This command will turn on pet looting, with a maximum number of items to loot
9154specified. Pet will store items and return them when the maximum is reached or
9155when pet performance is activated.
9156
9157---------------------------------------
9158
9159*petskillsupport <skill id>,<skill level>,<delay>,<percent hp>,<percent sp>;
9160*petskillsupport "<skill name>",<skill level>,<delay>,<percent hp>,<percent sp>;
9161
9162This will make the pet use a specified support skill on the owner whenever the
9163HP and SP are below the given percent values, with a specified delay time
9164between activations. The skill numbers are as per 'db/(pre-)re/skill_db.txt'.
9165
9166It's not quite certain who's stats will be used for the skills cast, the
9167character's or the pets. Probably, Skotlex can answer that question.
9168
9169---------------------------------------
9170
9171*petskillattack <skill id>,<skill level>,<rate>,<bonusrate>;
9172*petskillattack "<skill name>",<skill level>,<rate>,<bonusrate>;
9173*petskillattack2 <skill id>,<damage>,<number of attacks>,<rate>,<bonusrate>;
9174*petskillattack2 "<skill name>",<damage>,<number of attacks>,<rate>,<bonusrate>;
9175
9176These two commands will make the pet cast an attack skill on the enemy the pet's
9177owner is currently fighting. Skill IDs and levels are as per 'petskillsupport'.
9178'petskillattack2' will make the pet cast the skill with a fixed amount of damage
9179inflicted and the specified number of attacks.
9180
9181Value of 'rate' is between 1 and 100. 100 = 100%
9182
9183---------------------------------------
9184
9185===========================
9186|11.- Homunculus commands.|
9187===========================
9188---------------------------------------
9189
9190*homevolution;
9191
9192This command will try to evolve the current player's homunculus.
9193If it doesn't work, the /swt emotion is shown.
9194
9195To evolve a homunculus, the invoking player must have a homunculus,
9196the homunculus must not be the last evolution and
9197the homunculus must have above 91000 intimacy with its owner.
9198
9199---------------------------------------
9200
9201*morphembryo;
9202
9203This command will try to put the invoking player's Homunculus in an
9204uncallable state, required for mutation into a Homunculus S. The player
9205will also receive a Strange Embryo (ID 6415) in their inventory if
9206successful, which is deleted upon mutation.
9207
9208The command will fail if the invoking player does not have an evolved
9209Homunculus at level 99 or above. The /swt emotion is shown upon failure.
9210
9211Returns 1 upon success and 0 for all failures.
9212
9213---------------------------------------
9214
9215*hommutate {<ID>};
9216
9217This command will try to mutate the invoking player's Homunculus into
9218a Homunculus S. The Strange Embryo (ID 6415) is deleted upon success.
9219
9220The command will fail if the invoking player does not have an evolved
9221Homunculus at level 99 or above, if it is not in the embryo state
9222(from the 'morphembryo' command), or if the invoking player does not
9223possess a Strange Embryo. The /swt emotion is shown upon failure.
9224
9225If the optional parameter <ID> is set, the invoking player's Homunculus
9226will change into the specified Homunculus ID. Otherwise, a random Homunculus S
9227will be chosen. See 'db/homunculus_db.txt' for a full list of IDs.
9228
9229Returns 1 upon success and 0 for all failures.
9230
9231---------------------------------------
9232
9233*checkhomcall()
9234
9235This function checks if the attached player's Homunculus is active,
9236and will return the following values:
9237 -1: The player has no Homunculus.
9238 0: The player's Homunculus is active.
9239 1: The player's Homunculus is vaporized.
9240 2: The player's Homunculus is in morph state.
9241
9242---------------------------------------
9243
9244*gethominfo(<type>{,<char_id>})
9245
9246This function will return Homunculus information for the Homunculus of the
9247invoking character, regardless of its vaporize state. It returns zero or
9248"null" if the player does not own a Homunculus.
9249
9250Valid types are:
9251 0 - Homunculus ID
9252 1 - Homunculus Class
9253 2 - Homunculus Name
9254 3 - Homunculus friendly level (intimacy score). 100000 is full loyalty.
9255 4 - Homunculus hungry level. 100 is completely full.
9256 5 - Homunculus rename flag. 0 means this homunculus has not been named yet.
9257 6 - Homunculus level
9258 7 - Homunculus Game ID
9259
9260---------------------------------------
9261
9262*homshuffle;
9263
9264This will recalculate the homunculus stats according to its level, of the
9265current invoking character.
9266
9267---------------------------------------
9268
9269==========================
9270|12.- Mercenary commands.|
9271==========================
9272---------------------------------------
9273
9274*mercenary_create <class>,<contract time>;
9275
9276This command summons a mercenary for a given time (in milliseconds). For a
9277list of all available classes, see 'db/mercenary_db.txt'.
9278
9279This command is typically used in item scripts of mercenary scrolls.
9280
9281---------------------------------------
9282
9283*mercenary_heal <hp>,<sp>;
9284
9285This command works like 'heal', but affects the mercenary of the
9286currently attached character.
9287
9288---------------------------------------
9289
9290*mercenary_sc_start <type>,<tick>,<val1>;
9291
9292This command works like 'sc_start', but affects the mercenary of the
9293currently attached character.
9294
9295---------------------------------------
9296
9297*mercenary_get_calls(<guild>);
9298*mercenary_set_calls <guild>,<value>;
9299
9300Sets or gets the mercenary calls value for given guild for currently
9301attached character. Guild can be one or the following constants:
9302
9303 ARCH_MERC_GUILD
9304 SPEAR_MERC_GUILD
9305 SWORD_MERC_GUILD
9306
9307---------------------------------------
9308
9309*mercenary_get_faith(<guild>);
9310*mercenary_set_faith <guild>,<value>;
9311
9312Sets or gets the mercenary faith value for given guild for currently
9313attached character. Guild can be one or the following constants:
9314
9315 ARCH_MERC_GUILD
9316 SPEAR_MERC_GUILD
9317 SWORD_MERC_GUILD
9318
9319---------------------------------------
9320
9321*getmercinfo(<type>{,<char id>});
9322
9323Retrieves information about mercenary of the currently attached
9324character. If char id is given, the information of that character is
9325retrieved instead. Type specifies what information to retrieve and
9326can be one of the following:
9327
9328 0 - Mercenary ID
9329 1 - Mercenary Class
9330 2 - Mercenary Name
9331 3 - Mercenary faith value for this mercenary's guild, if any
9332 4 - Mercenary calls value for this mercenary's guild, if any
9333 5 - Mercenary kill count
9334 6 - Mercenary remaining life time in msec
9335 7 - Mercenary level
9336 8 - Mercenary Game ID
9337
9338If the character does not have a mercenary, the command returns ""
9339for name and 0 for all other types.
9340
9341---------------------------------------
9342
9343======================
9344|13.- Party commands.|
9345======================
9346---------------------------------------
9347
9348*getpartyname(<party id>)
9349
9350This function will return the name of a party that has the specified ID number.
9351If there is no such party ID, "null" will be returned.
9352
9353Lets say the ID of a party was saved as a global variable:
9354
9355 // This would return the name of the party from the ID stored in a variable
9356 mes "You're in the '" + getpartyname($@var) + "' party, I know!";
9357
9358---------------------------------------
9359
9360*getpartymember <party id>{,<type>{,<array_variable>}};
9361
9362This command will find all members of a specified party and returns their names
9363(or character id or account id depending on the value of "type") into an array
9364of temporary global variables. There's actually quite a few commands like this
9365which will fill a special variable with data upon execution and not do anything
9366else.
9367
9368Upon executing this,
9369
9370$@partymembername$[] is a global temporary string array which contains all the
9371 names of these party members
9372 (only set when type is 0 or not specified)
9373
9374$@partymembercid[] is a global temporary number array which contains the
9375 character id of these party members.
9376 (only set when type is 1)
9377
9378$@partymemberaid[] is a global temporary number array which contains the
9379 account id of these party members.
9380 (only set when type is 2)
9381
9382$@partymembercount is the number of party members that were found.
9383
9384The party members will (apparently) be found regardless of whether they are
9385online or offline. Note that the names come in no particular order.
9386
9387Be sure to use $@partymembercount to go through this array, and not
9388'getarraysize', because it is not cleared between runs of 'getpartymember'. If
9389someone with 7 party members invokes this script, the array would have 7
9390elements. But if another person calls up the NPC, and he has a party of 5, the
9391server will not clear the array for you, overwriting the values instead. So in
9392addition to returning the 5 member names, the 6th and 7th elements from the last
9393call remain, and you will get 5+2 members, of which the last 2 don't belong to
9394the new guy's party. $@partymembercount will always contain the correct number,
9395(5) unlike 'getarraysize()' which will return 7 in this case.
9396
9397If 'array_variable' is set, the result will be stored to that variable instead
9398using global variable.
9399
9400Example 1: list party member names
9401
9402 // get the party member names
9403 getpartymember getcharid(1),0;
9404
9405 // It's a good idea to copy the global temporary $@partymember*****
9406 // variables to your own scope variables because if you have pauses in this
9407 // script (sleep, sleep2, next, close2, input, menu, select, or prompt),
9408 // another player could click this NPC, trigger 'getpartymember', and
9409 // overwrite the $@partymember***** variables.
9410 .@count = $@partymembercount;
9411 copyarray .@name$[0], $@partymembername$[0], $@partymembercount;
9412
9413 // list the party member names
9414 for (.@i = 0; .@i < .@count; .@i++)
9415 mes (.@i +1) + ". ^0000FF" + .@name$[.@i] + "^000000";
9416 close;
9417
9418
9419Example 2: check party count (with a 'next' pause), before warping to event
9420
9421 .register_num = 5; // How many party members are required?
9422
9423 // get the charID and accountID of character's party members
9424 getpartymember getcharid(1), 1;
9425 getpartymember getcharid(1), 2;
9426
9427 if ( $@partymembercount != .register_num ) {
9428 mes "Please form a party of " + .register_num + " to continue";
9429 close;
9430 }
9431
9432 // loop through both and use 'isloggedin' to count online party members
9433 for ( .@i = 0; .@i < $@partymembercount; .@i++ )
9434 if ( isloggedin( $@partymemberaid[.@i], $@partymembercid[.@i] ) )
9435 .@count_online++;
9436
9437 // We search accountID & charID because a single party can have multiple
9438 // characters from the same account. Without searching through the charID,
9439 // if a player has 2 characters from the same account inside the party but
9440 // only 1 char online, it would count their online char twice.
9441
9442 if ( .@count_online != .register_num ) {
9443 mes "All your party members must be online to continue";
9444 close;
9445 }
9446
9447 // copy the array to prevent players cheating the system
9448 copyarray .@partymembercid, $@partymembercid, .register_num;
9449
9450 mes "Are you ready ?";
9451 next; // careful here
9452 select("Yes");
9453
9454 // When a script hits a next, menu, sleep or input that pauses the script,
9455 // players can invite or /leave and make changes in their party. To prevent
9456 // this, we call getpartymember again and compare with the original values.
9457
9458 getpartymember getcharid(1), 1;
9459 if ( $@partymembercount != .register_num ) {
9460 mes "You've made changes to your party !";
9461 close;
9462 }
9463 for ( .@i = 0; .@i < $@partymembercount; .@i++ ) {
9464 if ( .@partymembercid[.@i] != $@partymembercid[.@i] ) {
9465 mes "You've made changes to your party !";
9466 close;
9467 }
9468 }
9469
9470 // Finally, it's safe to start the event!
9471 warpparty "event_map", 0,0, getcharid(1);
9472
9473---------------------------------------
9474
9475*getpartyleader(<party id>{,<type>})
9476
9477This function returns some information about the given party-id's leader.
9478When type is omitted, the default information retrieved is the leader's name.
9479Possible types are:
9480
9481 1: Leader account id
9482 2: Leader character id
9483 3: Leader's class
9484 4: Leader's current map name
9485 5: Leader's current level as stored on the party structure (may not be
9486 current level if leader leveled up recently).
9487
9488If retrieval fails (leader not found or party does not exist), this function
9489returns "null" instead of the character name, and -1 for the other types.
9490
9491---------------------------------------
9492
9493*party_create("<party name>"{,<character id>{,<item share>,<item share type>}});
9494
9495Organizes a party with the attached or specified character as leader. If
9496successful, the command returns 1 and sets the global temporary variable
9497"$@party_create_id" to the ID of the party created.
9498
9499Additionally, item sharing options can be provided:
9500 - Item Share: 0-Each Take (default), 1-Party Share
9501 - Item Share Type: 0-Each Take (default), 1-Even Share
9502
9503These values are returned upon failure:
9504 0: Unknown error.
9505-1: Player not found.
9506-2: Player already has a party.
9507-3: Party name exists.
9508
9509---------------------------------------
9510
9511*party_destroy(<party id>);
9512
9513Disbands a party. The command returns 1 upon success and 0 upon failure.
9514
9515---------------------------------------
9516
9517*party_addmember(<party id>,<character id>);
9518
9519Adds a player to an existing party.
9520
9521The command returns 1 upon success, and these values upon failure:
9522 0: Unknown error.
9523-1: Player not found.
9524-2: Player already has a party.
9525-3: Party not found.
9526-4: Party is full.
9527-5: Another character from the same account is already in the party.
9528
9529---------------------------------------
9530
9531*party_delmember({<character id>,<party id>});
9532
9533Removes a player from his/her party. If no player is specified, the command
9534will run for the invoking player. If that player is the only party member
9535remaining, the party will be disbanded.
9536
9537The command returns 1 upon success, and these values upon failure:
9538 0: Unknown error.
9539-1: Player not found.
9540-2: Party not found.
9541-3: Player is not in the party.
9542
9543---------------------------------------
9544
9545*party_changeleader(<party id>,<character id>);
9546
9547Transfers leadership of a party to the specified character.
9548
9549The command returns 1 upon success, and these values upon failure:
9550 0: Unknown error.
9551-1: Party not found.
9552-2: Player not found.
9553-3: Player is not in the party.
9554-4: Player is already party leader.
9555
9556---------------------------------------
9557
9558*party_changeoption(<party id>,<option>,<flag>);
9559
9560Changes a party option.
9561
9562Valid options are:
9563 0 - Exp Share (flags: 0-Each Take, 1-Even Share)
9564 1 - Item Share (flags: 0-Each Take, 1-Party Share)
9565 2 - Item Share Type (flags: 0-Each Take, 1-Even Share)
9566
9567The command returns 1 upon success, and these values upon failure:
9568 0: Invalid option.
9569-1: Party not found.
9570
9571---------------------------------------
9572
9573*opendressroom(<flag>{,<char_id>});
9574
9575This will open the Dress Room window on the client connected to the invoking character.
9576
9577 mes "Close this window to open the Dress Room window.";
9578 close2;
9579 opendressroom(1);
9580 end;
9581
9582Valid flag are:
9583 1 - Open the Dress Room window
9584
9585---------------------------------------
9586
9587*navigateto("<map>"{,<x>,<y>,<flag>,<hide_window>,<monster_id>,<char_id>});
9588
9589Generates a navigation for attached or specified character. Requires client
95902011-10-10aRagEXE or newer.
9591
9592The flag specifies how the client will calculate the specific route.
9593
9594Valid flags are:
9595 NAV_NONE - No services
9596 NAV_AIRSHIP_ONLY - Airship only
9597 NAV_SCROLL_ONLY - Scroll only
9598 NAV_AIRSHIP_AND_SCROLL - Airship and Scroll
9599 NAV_KAFRA_ONLY - Kafra only
9600 NAV_KAFRA_AND_AIRSHIP - Kafra and Airship
9601 NAV_KAFRA_AND_SCROLL - Kafra and Scroll
9602 NAV_ALL - All services
9603
9604When flag is not specified, the default value is NAV_KAFRA_AND_AIRSHIP.
9605
9606The hide_window specifies whether to display (0) or hide (1) the navigation window.
9607By default the window is hidden.
9608
9609You can specify the monster_id in combination with a mapname to make the
9610navigation system tell you, that you have reached the desired mob.
9611
9612Note:
9613The client requires custom monster spawns be in the navigation file
9614for using the embedded client Navigation feature to work properly. In this
9615instance sending the player to the map where the monster spawns is a simpler
9616solution rather than sending the map and the monster_id.
9617
9618---------------------------------------
9619
9620*hateffect(<Hat Effect ID>,<State>);
9621
9622This will set a Hat Effect onto the player. The state field allows you to
9623enable (true) or disable (false) the effect on the player.
9624The Hat Effect constants can be found in 'src/map/script_constants.h' starting
9625with HAT_EF_*.
9626
9627Requires client 2015-05-13aRagEXE or newer.
9628
9629---------------------------------------
9630
9631*getrandomoptinfo(<type>);
9632
9633Returns value of an attribute of current random option.
9634
9635Valid attributes are:
9636ROA_ID - ID of current option
9637ROA_VALUE - Value field of current option
9638ROA_PARAM - Param field of current option
9639
9640This script command is intended for using in random option scripts.
9641
9642---------------------------------------
9643
9644*getequiprandomoption(<equipment index>,<index>,<type>{,<char id>});
9645
9646Returns value of an attribute of a random option on an equipped item.
9647
9648See 'getequipid' for a full list of valid equipment slots.
9649
9650index parameter can be 0 to MAX_ITEM_RDM_OPT-1 (default 0-4).
9651
9652For valid attribute types, see `getrandomoptinfo` command reference.
9653
9654---------------------------------------
9655
9656*setrandomoption(<equipment slot>,<index>,<id>,<value>,<param>{,<char id>});
9657
9658Sets <index+1>th random option for equipment equipped at <equipment slot>
9659to <id>, <value> and <param>.
9660
9661See 'getequipid' for a full list of valid equipment slots.
9662
9663index parameter can be 0 to MAX_ITEM_RDM_OPT-1 (default 0-4).
9664
9665ID - ID of random option. See db/const.txt for constants.
9666Value - Value of random option
9667Param - Parameter of random option
9668
9669---------------------------------------
9670
9671*clan_join(<clan id>{,<char id>});
9672
9673The attached player joins the clan with the <clan id>. On a successful join,
9674true is returned, else false if the join failed.
9675If <char id> is specified, the specified player is used rather than the attached one.
9676
9677---------------------------------------
9678
9679*clan_leave({<char id>});
9680
9681The attached player will leave their clan. On a successful leave, true is returned,
9682else false if the leave failed.
9683If <char id> is specified, the specified player is used rather than the attached one.
9684
9685---------------------------------------
9686
9687========================
9688|14.- Channel commands.|
9689========================
9690---------------------------------------
9691
9692*channel_create "<chname>","<alias>"{,"<password>"{<option>{,<delay>{,<color>{,<char_id>}}}}};
9693
9694Creates a public channel with <chname> as the channel name. To protect the
9695channel, use <password> or write "null" to create it without a password.
9696Channel name must start with '#' and cannot be the same as the map or ally
9697channel names.
9698
9699<alias> will be used to change the channel name when the channel message
9700is displayed.
9701
9702<option> values are:
9703 CHAN_OPT_BASE - Default option including CHAN_OPT_ANNOUNCE_SELF|CHAN_OPT_MSG_DELAY|CHAN_OPT_CAN_CHAT|CHAN_OPT_CAN_LEAVE
9704 CHAN_OPT_ANNOUNCE_SELF - Show info for player itself if player has joined/leaves the channel
9705 CHAN_OPT_ANNOUNCE_JOIN - Display message when player is joining the channel
9706 CHAN_OPT_ANNOUNCE_LEAVE - Display message when player is leaving the channel
9707 CHAN_OPT_MSG_DELAY - Enable chat delay for the channel
9708 CHAN_OPT_COLOR_OVERRIDE - Player's unique font color will override channel's color
9709 CHAN_OPT_CAN_CHAT - Player can chat in the channel
9710 CHAN_OPT_CAN_LEAVE - Player can leave the channel
9711 CHAN_OPT_AUTOJOIN - Players will auto join the channel at login
9712
9713The <delay> is the minimum chat delay in millisecond for a single player before
9714the player can chat again in the same channel.
9715
9716Use <color> hex code to set the color for this channel, if not defined, default
9717channel color will be used.
9718
9719If <char_id> is defined, the channel will be a private channel and the player
9720will be the the channel owner.
9721
9722Returns 1 on success.
9723
9724 /**
9725 * This example will shows the message on this channel as
9726 * [rAthena] Admin : Hello world!
9727 * instead of
9728 * #rathena Admin : Hello world!
9729 **/
9730 channel_create("#rathena","[rAthena]");
9731 channel_create("#vip","[VIP]","vipmemberonly");
9732
9733---------------------------------------
9734
9735*channel_setopt "<chname>",<option>,<value>;
9736
9737Set option for the channel. Use 1 in <value> to set it, or 0 to unset.
9738The <option> values are the same as the 'channel_create' options.
9739
9740For CHAN_OPT_MSG_DELAY, the delay in millisecond must be sent or use 0
9741to remove the delay at <value>.
9742
9743Returns 1 on success.
9744
9745 // Example to set delay
9746 channel_setopt("#global",CHAN_OPT_MSG_DELAY,5000);
9747
9748Only for public and private channel.
9749
9750---------------------------------------
9751
9752*channel_setcolor "<chname>",<color>;
9753
9754To change channel color.
9755<color> uses hex RGB values.
9756
9757Returns 1 on success.
9758
9759---------------------------------------
9760
9761*channel_setpass "<chname>","<password>";
9762
9763To set, unset, or change password of a channel.
9764Use "null" to remove the password.
9765
9766Returns 1 on success.
9767Only for public and private channel.
9768
9769---------------------------------------
9770
9771*channel_setgroup "<chname>",<group_id>{,...,<group_id>};
9772*channel_setgroup2 "<chname>",<array_of_groups>;
9773
9774Set group restriction for a channel. Only player with matching <group_id>
9775are allowed to to join the channel.
9776
9777By using 0 in the first group channel, the group restriction will be
9778removed from the channel config.
9779
9780'channel_setgroup2' receives input for group list as an array.
9781
9782Returns 0 on failure, and 1 (or n groups count) on success.
9783
9784 // Example 1: Remove groups
9785 channel_setgroup("#event",0);
9786
9787 // Example 2: Multiple values
9788 channel_setgroup("#vip",2,5);
9789
9790 // Example 3: Using array
9791 setarray .@staffs[0],2,3,4,10,99;
9792 channel_setgroup("#staff",.@staffs);
9793
9794Only for public and private channel.
9795
9796---------------------------------------
9797
9798*channel_chat "<chname>","<message>"{,<color>};
9799
9800Sends message to the channel.
9801Returns 1 on success.
9802
9803 // Example if channel doesn't have alias
9804 channel_chat(#rathena,"Hello World!"); // #rathena Hello World!
9805
9806 // Example if channel has alias
9807 channel_chat(#rathena,"Hello World!"); // [rAthena] Hello World!
9808
9809---------------------------------------
9810
9811*channel_ban "<chname>",<char_id>;
9812
9813Ban player from a public or private channel.
9814Channel's owner or group with PC_PERM_CHANNEL_ADMIN cannot be banned.
9815Returns 1 on success.
9816
9817---------------------------------------
9818
9819*channel_unban "<chname>",<char_id>;
9820
9821Unban player from a public or private channel.
9822Returns 1 on success.
9823
9824---------------------------------------
9825
9826*channel_kick "<chname>",<char_id>;
9827*channel_kick "<chname>","<char_name>";
9828
9829Kick player from a public or private channel.
9830Channel's owner or group with PC_PERM_CHANNEL_ADMIN cannot be kicked.
9831Returns 1 on success.
9832
9833---------------------------------------
9834
9835*channel_delete "<chname>";
9836
9837Delete an existing public or private channel. Cannot delete ally or
9838local map channel.
9839Returns 0 on success.
9840
9841---------------------------------------
9842
9843============================
9844|15.- Achievement commands.|
9845============================
9846---------------------------------------
9847
9848*achievementadd(<achievement id>{,<char id>})
9849
9850This function will add an achievement to the player's log for the attached
9851player or the supplied <char id>. The objective requirements are not ignored
9852when using this function.
9853Returns true on success and false on failure.
9854
9855---------------------------------------
9856
9857*achievementremove(<achievement id>{,<char id>})
9858
9859This function will remove an achievement from the player's log for the attached
9860player or the supplied <char id>.
9861Returns true on success and false on failure.
9862
9863---------------------------------------
9864
9865*achievementinfo(<achievement id>,<type>{,<char id>})
9866
9867This function will return the specified <type> value for an achievement of the
9868attached player or the supplied <char id>. If the player doesn't have the
9869achievement active (no progress has been made): if the achievement doesn't
9870exist -1 will be returned, or -2 will be returned on any other error such as
9871an invalid <type>.
9872
9873Valid types:
9874- ACHIEVEINFO_COUNT1
9875- ACHIEVEINFO_COUNT2
9876- ACHIEVEINFO_COUNT3
9877- ACHIEVEINFO_COUNT4
9878- ACHIEVEINFO_COUNT5
9879- ACHIEVEINFO_COUNT6
9880- ACHIEVEINFO_COUNT7
9881- ACHIEVEINFO_COUNT8
9882- ACHIEVEINFO_COUNT9
9883- ACHIEVEINFO_COUNT10
9884- ACHIEVEINFO_COMPLETE
9885- ACHIEVEINFO_COMPLETEDATE
9886- ACHIEVEINFO_GOTREWARD
9887- ACHIEVEINFO_LEVEL (<achievement id> is useless for this)
9888- ACHIEVEINFO_SCORE (<achievement id> is useless for this)
9889
9890---------------------------------------
9891
9892*achievementcomplete(<achievement id>{,<char id>})
9893
9894This function will complete an achievement for the attached player or the supplied
9895<char id>. The objective requirements are ignored when using this function.
9896Returns true on success and false on failure.
9897
9898---------------------------------------
9899
9900*achievementexists(<achievement id>{,<char id>});
9901
9902This function will return if the achievement exists on the player or the supplied
9903<char id>.
9904Returns true on success and false on failure.
9905
9906---------------------------------------
9907
9908*achievementupdate(<achievement id>,<type>,<value>{,<char id>})
9909
9910This function will update an achievement's value for an achievement of the attached
9911player or the supplied <char id>. If the player does not have the achievement active
9912(no progress has been made) it will be added to the player's log first before updating
9913the <type> value.
9914Returns true on success and false on failure.
9915
9916See 'achievementinfo' for valid <type> values.
9917- ACHIEVEINFO_COMPLETE, ACHIEVEINFO_COMPLETEDATE, and ACHIEVEINFO_GOTREWARD require the
9918 specific value returned from 'gettimetick(2)'.
9919- Excludes ACHIEVEINFO_LEVEL and ACHIEVEINFO_SCORE.
9920
9921---------------------------------------