From 84d86640562005f2a395d31296a764058480e80b Mon Sep 17 00:00:00 2001 From: gumi Date: Mon, 18 Sep 2017 15:53:57 -0400 Subject: clean trailing whitespaces in script documentation --- doc/script_commands.txt | 3102 +++++++++++++++++++++++------------------------ 1 file changed, 1551 insertions(+), 1551 deletions(-) diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 3457d50f0..15026cd7c 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -7,23 +7,23 @@ //= Commands are sorted depending on their functionality. //============================================================ -This document is a reference manual for all the scripting commands and -functions available in current Hercules GIT. It is not a simple tutorial. +This document is a reference manual for all the scripting commands and +functions available in current Hercules GIT. It is not a simple tutorial. When people tell you to "Read The F***ing Manual", they mean this. -The information was mostly acquired through looking up how things actually -work in the source code of the server, which was written by many people -over time, and lots of them don't speak English and never left any notes - -or are otherwise not available for comments. As such, anything written in -here might not be correct, it is only correct to the best of our +The information was mostly acquired through looking up how things actually +work in the source code of the server, which was written by many people +over time, and lots of them don't speak English and never left any notes - +or are otherwise not available for comments. As such, anything written in +here might not be correct, it is only correct to the best of our knowledge, which is limited. -This is not a place to teach you basic programming. This document will not -teach you basic programming by itself. It's more of a reference for those -who have at least a vague idea of what they want to do and want to know -what tools they have available to do it. We've tried to keep it as simple -as feasible, but if you don't understand it, getting a clear book on -programming in general will help better than yelling around the forum for +This is not a place to teach you basic programming. This document will not +teach you basic programming by itself. It's more of a reference for those +who have at least a vague idea of what they want to do and want to know +what tools they have available to do it. We've tried to keep it as simple +as feasible, but if you don't understand it, getting a clear book on +programming in general will help better than yelling around the forum for help. A little learning never caused anyone's head to explode. @@ -37,11 +37,11 @@ The commands and functions are listed in no particular order: Descriptive text - Small example if possible. Will usually be incomplete, it's there just + Small example if possible. Will usually be incomplete, it's there just to give you an idea of how it works in practice. -To find a specific command, use Ctrl+F, (or whatever keys call up a search -function in whatever you're reading this with) put an * followed by the +To find a specific command, use Ctrl+F, (or whatever keys call up a search +function in whatever you're reading this with) put an * followed by the command name, and it should find the command description for you. If you find anything omitted, please tell us. :) @@ -49,22 +49,22 @@ If you find anything omitted, please tell us. :) Syntax ------ -Throughout this document, wherever a command wants an argument, it is -given in . This doesn't mean you should type the angle -brackets. :) If an argument of a command is optional, it is given in -{curly brackets}. You've doubtlessly seen this convention somewhere, if -you didn't, get used to it, that's how big boys do it. If a command can -optionally take an unspecified number of arguments, you'll see a list like +Throughout this document, wherever a command wants an argument, it is +given in . This doesn't mean you should type the angle +brackets. :) If an argument of a command is optional, it is given in +{curly brackets}. You've doubtlessly seen this convention somewhere, if +you didn't, get used to it, that's how big boys do it. If a command can +optionally take an unspecified number of arguments, you'll see a list like this: command({, ...}) This still means they will want to be separated by commas. -Where a command wants a string, it will be given in "quotes", if it's a -number, it will be given without them. Normally, you can put an -expression, like a bunch of functions or operators returning a value, in -(round brackets) instead of most numbers. Round brackets will not always +Where a command wants a string, it will be given in "quotes", if it's a +number, it will be given without them. Normally, you can put an +expression, like a bunch of functions or operators returning a value, in +(round brackets) instead of most numbers. Round brackets will not always be required, but they're often a good idea. Wherever you refer to a map, use 'mapname' instead of 'mapname.gat'. @@ -98,39 +98,39 @@ npc_removed_list: ( Script file format ------------------ -Whenever '//' is encountered in a line upon reading, everything beyond -this on that line is considered to be a comment and is ignored. This works +Whenever '//' is encountered in a line upon reading, everything beyond +this on that line is considered to be a comment and is ignored. This works wherever you place it. // This line will be ignored when processing the script. -Block comments can also be used, where you can place /* and */ between any +Block comments can also be used, where you can place /* and */ between any text you wish Hercules to ignore. Example: /* This text, * no matter which new line you start - * is ignored, until the following + * is ignored, until the following * symbol is encountered: */ - -The asterisks (*) in front of each line is a personal preference, and is + +The asterisks (*) in front of each line is a personal preference, and is not required. -Upon loading all the files, the server will execute all the top-level -commands in them. No variables exist yet at this point, no commands can be -called other than those given in this section. These commands set up the -basic server script structure - create NPC objects, spawn monster objects, -set map flags, etc. No code is actually executed at this point except -them. The top-level commands the scripting are pretty confusing, since -they aren't structured like you would expect commands, command name first, +Upon loading all the files, the server will execute all the top-level +commands in them. No variables exist yet at this point, no commands can be +called other than those given in this section. These commands set up the +basic server script structure - create NPC objects, spawn monster objects, +set map flags, etc. No code is actually executed at this point except +them. The top-level commands the scripting are pretty confusing, since +they aren't structured like you would expect commands, command name first, but rather, normally start with a map name. -What's more confusing about the top-level commands is that most of them +What's more confusing about the top-level commands is that most of them use a tab symbol to divide their arguments. -To prevent problems and confusion, the tab symbols are written as '%TAB%' -or '' throughout this document, even though this makes the text a bit -less readable. Using an invisible symbol to denote arguments is one of the +To prevent problems and confusion, the tab symbols are written as '%TAB%' +or '' throughout this document, even though this makes the text a bit +less readable. Using an invisible symbol to denote arguments is one of the bad things about this language, but we're stuck with it for now. :) Here is a list of valid top-level commands: @@ -139,55 +139,55 @@ Here is a list of valid top-level commands: %TAB%mapflag%TAB% -This will, upon loading, set a specified map flag on a map you like. These -are normally in files inside 'npc/mapflag' and are loaded first, so by the -time the server's up, all the maps have the flags they should have. Map -flags determine the behavior of the map regarding various common problems, +This will, upon loading, set a specified map flag on a map you like. These +are normally in files inside 'npc/mapflag' and are loaded first, so by the +time the server's up, all the maps have the flags they should have. Map +flags determine the behavior of the map regarding various common problems, for a better explanation, see 'setmapflag'. ** Create a permanent monster spawn: ,,,,%TAB%monster%TAB%%TAB%,,,,{,,} -Map name is the name of the map the monsters will spawn on. X,Y are the -coordinates where the mob should spawn. If X's and Y's are non-zero, they -specify the 'radius' of a spawn-rectangle area centered at x,y. Putting -zeros instead of these coordinates will spawn the monsters randomly. Note -this is only the initial spawn zone, as mobs random-walk, they are free to +Map name is the name of the map the monsters will spawn on. X,Y are the +coordinates where the mob should spawn. If X's and Y's are non-zero, they +specify the 'radius' of a spawn-rectangle area centered at x,y. Putting +zeros instead of these coordinates will spawn the monsters randomly. Note +this is only the initial spawn zone, as mobs random-walk, they are free to move away from their specified spawn region. -Monster name is the name the monsters will have on screen, and has no -relation whatsoever to their names anywhere else. It's the mob id that -counts, which identifies monster record in 'mob_db.txt' database of -monsters. If the mob name is given as "--ja--", the 'japanese name' field -from the monster database is used, (which, in Hercules, actually contains -an English name) if it's "--en--", it's the 'english name' from the -monster database (which contains an uppercase name used to summon the +Monster name is the name the monsters will have on screen, and has no +relation whatsoever to their names anywhere else. It's the mob id that +counts, which identifies monster record in 'mob_db.txt' database of +monsters. If the mob name is given as "--ja--", the 'japanese name' field +from the monster database is used, (which, in Hercules, actually contains +an English name) if it's "--en--", it's the 'english name' from the +monster database (which contains an uppercase name used to summon the monster with a GM command). -Amount is the amount of monsters that will be spawned when this command is +Amount is the amount of monsters that will be spawned when this command is executed, it is affected by spawn rates in 'conf/map/battle.conf'. -Delay1 and delay2 control monster respawn delays - the first one is the -fixed base respawn time, and the second is random variance on top of the -base time. Both values are given in milliseconds (1000 = 1 second). Note +Delay1 and delay2 control monster respawn delays - the first one is the +fixed base respawn time, and the second is random variance on top of the +base time. Both values are given in milliseconds (1000 = 1 second). Note that the server also enforces a minimum respawn delay of 5 seconds. -You can specify a custom level to use for the mob different from the one -of the database by adjoining the level after the name with a comma. eg: +You can specify a custom level to use for the mob different from the one +of the database by adjoining the level after the name with a comma. eg: "Poring,50" for a name will spawn a monster with name Poring and level 50. -Event is a script event to be executed when the mob is killed. The event -must be in the form "NPCName::OnEventName" to execute, and the event name -label should start with "On". As with all events, if the NPC is an -on-touch NPC, the player who triggers the script must be within 'trigger' +Event is a script event to be executed when the mob is killed. The event +must be in the form "NPCName::OnEventName" to execute, and the event name +label should start with "On". As with all events, if the NPC is an +on-touch NPC, the player who triggers the script must be within 'trigger' range for the event to work. -There are two optional fields for monster size and AI. Size can be 0 -(medium), 1 (small), or 2 (big). AI can be 0 (default), 1 +There are two optional fields for monster size and AI. Size can be 0 +(medium), 1 (small), or 2 (big). AI can be 0 (default), 1 (attack/friendly), 2 (sphere), 3 (flora), or 4 (zanzou). -Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able to be +Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able to be detected on the map with the SC_CASH_BOSS_ALARM status (used by Convex Mirror, item ID# 12214). ** NPC names @@ -198,12 +198,12 @@ NPC names are kinda special and are formatted this way: {::} -All NPCs need to have a unique name that is used for identification -purposes. When you have to identify a NPC by it's name, you should use -. If is not provided, use +All NPCs need to have a unique name that is used for identification +purposes. When you have to identify a NPC by it's name, you should use +. If is not provided, use instead. -The client has a special feature when displaying names: if the display +The client has a special feature when displaying names: if the display name contains a '#' character, it hides that part of the name. Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter' @@ -214,18 +214,18 @@ Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter' ,,{,}%TAB%warp%TAB%%TAB%,,,, -This will define a warp NPC that will warp a player between maps, and +This will define a warp NPC that will warp a player between maps, and while most arguments of that are obvious, some deserve special mention. -SpanX and SpanY will make the warp sensitive to a character who didn't -step directly on it, but walked into a zone which is centered on the warp -from coordinates and is SpanX in each direction across the X axis and +SpanX and SpanY will make the warp sensitive to a character who didn't +step directly on it, but walked into a zone which is centered on the warp +from coordinates and is SpanX in each direction across the X axis and SpanY in each direction across the Y axis. -Warp NPC objects also have a name, because you can use it to refer to them +Warp NPC objects also have a name, because you can use it to refer to them later with 'enablenpc'/'disablenpc'. -Facing of a warp object is irrelevant, it is not used in the code and all +Facing of a warp object is irrelevant, it is not used in the code and all current scripts have a zero in there. ** Define an NPC object. @@ -233,54 +233,54 @@ current scripts have a zero in there. ,,,%TAB%script%TAB%%TAB%,{} ,,,%TAB%script%TAB%%TAB%,,,{} -This will place an NPC object on a specified map at the specified -location, and is a top-level command you will use the most in your custom -scripting. The NPCs are triggered by clicking on them, and/or by walking +This will place an NPC object on a specified map at the specified +location, and is a top-level command you will use the most in your custom +scripting. The NPCs are triggered by clicking on them, and/or by walking in their trigger area, if defined. See that below. -Facing is a direction the NPC sprite will face in. Not all NPC sprites -have different images depending on the direction you look from, so for -some facing will be meaningless. Facings are counted counterclockwise in -increments of 45 degrees, where 0 means facing towards the top of the map. -(So to turn the sprite towards the bottom of the map, you use facing 4, +Facing is a direction the NPC sprite will face in. Not all NPC sprites +have different images depending on the direction you look from, so for +some facing will be meaningless. Facings are counted counterclockwise in +increments of 45 degrees, where 0 means facing towards the top of the map. +(So to turn the sprite towards the bottom of the map, you use facing 4, and to make it look southeast it's facing 5.) -Sprite is the sprite identifier used to display this particular NPC. For a +Sprite is the sprite identifier used to display this particular NPC. For a full list of sprite numbers see http://kalen.s79.xrea.com/npc/npce.shtml as well as db/constants.conf. -You may also use a monster's ID constant instead to display a monster sprite +You may also use a monster's ID constant instead to display a monster sprite for this NPC, in npcs that have view ids of mobs it's encouraged to use OnTouch events with a 2,2 range and with an 'end' after the header to avoid bugs (for more info on why see npc_click@map/npc.c). It is possible to use a job sprite as well, but you must first define it as a monster sprite in 'mob_avail.txt', a full description on how to do this is not in the scope of this manual. A 'FAKE_NPC' sprite will make the NPC invisible (and unclickable). -A 'HIDDEN_NPC' sprite will make an NPC which does not have a sprite, but is -still clickable, which is useful if you want to make a clickable object of +A 'HIDDEN_NPC' sprite will make an NPC which does not have a sprite, but is +still clickable, which is useful if you want to make a clickable object of the 3D terrain. -TriggerX and triggerY, if given, will define an area, centered on NPC and -spanning triggerX cells in every direction across X and triggerY in every -direction across Y. Walking into that area will trigger the NPC. If no -'OnTouch:' special label is present in the NPC code, the execution will -start from the beginning of the script, otherwise, it will start from the -'OnTouch:' label. Monsters can also trigger the NPC, though the label +TriggerX and triggerY, if given, will define an area, centered on NPC and +spanning triggerX cells in every direction across X and triggerY in every +direction across Y. Walking into that area will trigger the NPC. If no +'OnTouch:' special label is present in the NPC code, the execution will +start from the beginning of the script, otherwise, it will start from the +'OnTouch:' label. Monsters can also trigger the NPC, though the label 'OnTouchNPC:' is used in this case. If player left area npc will called if present label 'OnUnTouch'. -The code part is the script code that will execute whenever the NPC is -triggered. It may contain commands and function calls, descriptions of -which compose most of this document. It has to be in curly brackets, -unlike elsewhere where we use curly brackets, these do NOT signify an +The code part is the script code that will execute whenever the NPC is +triggered. It may contain commands and function calls, descriptions of +which compose most of this document. It has to be in curly brackets, +unlike elsewhere where we use curly brackets, these do NOT signify an optional parameter. ** Define a 'floating' NPC object. -%TAB%script%TAB%%TAB%FAKE_NPC,{} -This will define an NPC object not triggerable by normal means. This would -normally mean it's pointless since it can't do anything, but there are -exceptions, mostly related to running scripts at specified time, which is +This will define an NPC object not triggerable by normal means. This would +normally mean it's pointless since it can't do anything, but there are +exceptions, mostly related to running scripts at specified time, which is what these floating NPC objects are for. More on that below. ** Define a shop/cashshop NPC. @@ -288,22 +288,22 @@ what these floating NPC objects are for. More on that below. -%TAB%shop%TAB%%TAB%,:{,:...} ,,,%TAB%shop%TAB%%TAB%,:{,:...} -This will define a shop NPC, which, when triggered (which can only be done -by clicking) will cause a shop window to come up. No code whatsoever runs -in shop NPCs and you can't change the prices otherwise than by editing the -script itself (no variables even exist at this point of scripting, so +This will define a shop NPC, which, when triggered (which can only be done +by clicking) will cause a shop window to come up. No code whatsoever runs +in shop NPCs and you can't change the prices otherwise than by editing the +script itself (no variables even exist at this point of scripting, so don't even bother trying to use them). -The item id is the number of item in the 'item_db.txt' database. If Price -is set to -1, the 'buy price' given in the item database will be used. -Otherwise, the price you gave will be used for this item, which is how you +The item id is the number of item in the 'item_db.txt' database. If Price +is set to -1, the 'buy price' given in the item database will be used. +Otherwise, the price you gave will be used for this item, which is how you create differing prices for items in different shops. -You can alternatively use "cashshop" in place of "shop" to use the Cash -Shop interface, allowing you to buy items with special points (Currently -stored as account vars in #CASHPOINTS and #KAFRAPOINTS). This -type of shop will not allow you to sell items at it, you may only purchase -items here. The layout used to define sale items still count, and +You can alternatively use "cashshop" in place of "shop" to use the Cash +Shop interface, allowing you to buy items with special points (Currently +stored as account vars in #CASHPOINTS and #KAFRAPOINTS). This +type of shop will not allow you to sell items at it, you may only purchase +items here. The layout used to define sale items still count, and "" refers to how many points will be spent purchasing the them. ** Define a trader NPC @@ -341,24 +341,24 @@ This will duplicate an warp/shop/cashshop/NPC referred to by 'label'. Warp duplicates inherit the target location. Shop/cashshop duplicates inherit the item list. NPC duplicates inherit the script code. -The rest (name, location, facing, sprite, span/trigger area) is +The rest (name, location, facing, sprite, span/trigger area) is obtained from the definition of the duplicate (not inherited). ** Define a function object function%TAB%script%TAB%%TAB%{} -This will define a function object, callable with the 'callfunc' command -(see below). This object will load on every map server separately, so you -can get at it from anywhere. It's not possible to call the code in this +This will define a function object, callable with the 'callfunc' command +(see below). This object will load on every map server separately, so you +can get at it from anywhere. It's not possible to call the code in this object by anything other than the 'callfunc' script command. -The code part is the script code that will execute whenever the function -is called with 'callfunc'. It has to be in curly brackets, unlike -elsewhere where we use curly brackets, these do NOT signify an optional +The code part is the script code that will execute whenever the function +is called with 'callfunc'. It has to be in curly brackets, unlike +elsewhere where we use curly brackets, these do NOT signify an optional parameter. -Once an object is defined which has a 'code' field to it's definition, it +Once an object is defined which has a 'code' field to it's definition, it contains script commands which can actually be triggered and executed. ~ RID? GID? ~ @@ -366,74 +366,74 @@ contains script commands which can actually be triggered and executed. What a RID is and why do you need to know ----------------------------------------- -Most scripting commands and functions will want to request data about a -character, store variables referenced to that character, send stuff to the -client connected to that specific character. Whenever a script is invoked -by a character, it is passed a so-called RID - this is the account ID -number of a character that caused the code to execute by clicking on it, +Most scripting commands and functions will want to request data about a +character, store variables referenced to that character, send stuff to the +client connected to that specific character. Whenever a script is invoked +by a character, it is passed a so-called RID - this is the account ID +number of a character that caused the code to execute by clicking on it, walking into it's OnTouch zone, or otherwise. -If you are only writing common NPCs, you don't need to bother with it. -However, if you use functions, if you use timers, if you use clock-based -script activation, you need to be aware of all cases when a script -execution can be triggered without a RID attached. This will make a lot of -commands and functions unusable, since they want data from a specific -character, want to send stuff to a specific client, want to store -variables specific to that character, and they would not know what +If you are only writing common NPCs, you don't need to bother with it. +However, if you use functions, if you use timers, if you use clock-based +script activation, you need to be aware of all cases when a script +execution can be triggered without a RID attached. This will make a lot of +commands and functions unusable, since they want data from a specific +character, want to send stuff to a specific client, want to store +variables specific to that character, and they would not know what character to work on if there's no RID. -Unless you use 'attachrid' to explicitly attach a character to the script +Unless you use 'attachrid' to explicitly attach a character to the script first (see player-related commands). -Whenever we say 'invoking character', we mean 'the character who's RID is +Whenever we say 'invoking character', we mean 'the character who's RID is attached to the running script. The script function playerattached() can -be used to check which is the currently attached player to the script (it -will return 0 if the there is no player attached or the attached player no +be used to check which is the currently attached player to the script (it +will return 0 if the there is no player attached or the attached player no longer is logged on to the map-server). But what about GID? --- ---- ----- ---- -GID stands for the Game ID of something, this can either be the GID of a +GID stands for the Game ID of something, this can either be the GID of a mob obtained through the monster() script command (if only summoned one), the GID of a NPC obtained through the getnpcid() script command or the -account ID of a character (same as its RID). Another way would be to right +account ID of a character (same as its RID). Another way would be to right click on a mob, NPC or char as GM sprited char to view its GID. Item and pet scripts -------------------- -Each item in the item database has three special fields - Script, -OnEquip_Script and OnUnequip_Script. The first is script code run every -time a character equips the item, with the RID of the equipping character. -Every time they unequip an item, all temporary bonuses given by the script -commands are cleared, and all the scripts are executed once again to -rebuild them. This also happens in several other situations (like upon +Each item in the item database has three special fields - Script, +OnEquip_Script and OnUnequip_Script. The first is script code run every +time a character equips the item, with the RID of the equipping character. +Every time they unequip an item, all temporary bonuses given by the script +commands are cleared, and all the scripts are executed once again to +rebuild them. This also happens in several other situations (like upon login) but the full list is currently unknown. -OnEquip_Script is a piece of script code run whenever the item is used by -a character by double-clicking on it. OnUnequip_Script runs whenever the +OnEquip_Script is a piece of script code run whenever the item is used by +a character by double-clicking on it. OnUnequip_Script runs whenever the equipment is unequipped by a character. -Not all script commands work properly in the item scripts. Where commands -and functions are known to be meant specifically for use in item scripts, +Not all script commands work properly in the item scripts. Where commands +and functions are known to be meant specifically for use in item scripts, they are described as such. -Every pet in the pet database has a PetScript field, which determines pet -behavior. It is invoked wherever a pet of the specified type is spawned -(hatched from an egg, or loaded from the char server when a character who -had that pet following them connects). This may occur in some other -situations as well. Don't expect anything other than commands definitely +Every pet in the pet database has a PetScript field, which determines pet +behavior. It is invoked wherever a pet of the specified type is spawned +(hatched from an egg, or loaded from the char server when a character who +had that pet following them connects). This may occur in some other +situations as well. Don't expect anything other than commands definitely marked as usable in pet scripts to work in there reliably. Numbers ------- -Beside the common decimal numbers, which are nothing special whatsoever -(though do not expect to use fractions, since ALL numbers are integer in -this language), the script engine also handles hexadecimal numbers, which -are otherwise identical. Writing a number like '0x' will make -it recognized as a hexadecimal value. Notice that 0x10 is equal to 16. +Beside the common decimal numbers, which are nothing special whatsoever +(though do not expect to use fractions, since ALL numbers are integer in +this language), the script engine also handles hexadecimal numbers, which +are otherwise identical. Writing a number like '0x' will make +it recognized as a hexadecimal value. Notice that 0x10 is equal to 16. Also notice that if you try to 'mes 0x10' it will print '16'. Number values can't exceed the limits of an integer variable: Any number @@ -443,7 +443,7 @@ be capped to those values and will cause a warning to be reported. Variables --------- -The meat of every programming language is variables - places where you +The meat of every programming language is variables - places where you store data. In Hercules scripting language, variable names are case sensitive. Even though @@ -469,20 +469,20 @@ permanent - They still exist when the server resets. temporary - They cease to exist when the server resets. Prefix: scope and extent -nothing - A permanent variable attached to the character, the default +nothing - A permanent variable attached to the character, the default variable type. -"@" - A temporary variable attached to the character. +"@" - A temporary variable attached to the character. They disappear when the character logs out. -"$" - A global permanent variable. +"$" - A global permanent variable. They are stored in database table `mapreg`. "$@" - A global temporary variable. They are important for scripts which are called with no RID attached, that is, not triggered by a specific character object. "." - A NPC variable. - They exist in the NPC and disappear when the server restarts or - the NPC is reloaded. Can be accessed from inside the NPC or by - calling 'getvariableofnpc'. Function objects can also have - .variables which are accessible from inside the function, + They exist in the NPC and disappear when the server restarts or + the NPC is reloaded. Can be accessed from inside the NPC or by + calling 'getvariableofnpc'. Function objects can also have + .variables which are accessible from inside the function, however 'getvariableofnpc' does NOT work on function objects. ".@" - A scope variable. They are unique to the character, script and scope. Each script @@ -492,17 +492,17 @@ nothing - A permanent variable attached to the character, the default variables are converted to values ('return .@var;' returns a value, not a reference). "'" - An instance variable. - These are used with the instancing system, and are unique to + These are used with the instancing system, and are unique to each instance. "#" - A permanent local account variable. -"##" - A permanent global account variable stored by the login server. - The only difference you will note from normal # variables is - when you have multiple char-servers connected to the same - login-server. The # variables are unique to each char-server, +"##" - A permanent global account variable stored by the login server. + The only difference you will note from normal # variables is + when you have multiple char-servers connected to the same + login-server. The # variables are unique to each char-server, while the ## variables are shared by all these char-servers. Postfix: integer or string -nothing - integer variable, can store positive and negative numbers, but +nothing - integer variable, can store positive and negative numbers, but only whole numbers (so don't expect to do any fractional math). '$' - string variable, can store text. @@ -526,10 +526,10 @@ $@name$ - temporary global string variable ##name - permanent global account integer variable ##name$ - permanent global account string variable -If a variable was never set, it is considered to equal zero for integer -variables or an empty string ("", nothing between the quotes) for string -variables. Once you set it to that, the variable is as good as forgotten -forever, and no trace remains of it even if it was stored with character +If a variable was never set, it is considered to equal zero for integer +variables or an empty string ("", nothing between the quotes) for string +variables. Once you set it to that, the variable is as good as forgotten +forever, and no trace remains of it even if it was stored with character or account data. The maximum length of variable name including prefix and suffix is 32. @@ -562,43 +562,43 @@ Sex - Character's gender (SEX_MALE or SEX_FEMALE). Class - Character's job. Upper - 0 if the character is normal class, 1 if advanced, 2 if baby. BaseClass - The character's 1-1 'normal' job, regardless of Upper value. - For example, this will return Job_Acolyte for Acolyte, - Priest/Monk, High Priest/Champion, and Arch Bishop/Sura. - If the character has not reached a 1-1 class, it will return + For example, this will return Job_Acolyte for Acolyte, + Priest/Monk, High Priest/Champion, and Arch Bishop/Sura. + If the character has not reached a 1-1 class, it will return Job_Novice. BaseJob - The character's 'normal' job, regardless of Upper value. For example, this will return Job_Acolyte for Acolyte, Baby Acolyte, and High Acolyte. -Karma - The character's karma. Karma system is not fully functional, +Karma - The character's karma. Karma system is not fully functional, but this doesn't mean this doesn't work at all. Not tested. -Manner - The character's manner rating. Becomes negative if the - player utters words forbidden through the use of +Manner - The character's manner rating. Becomes negative if the + player utters words forbidden through the use of 'manner.txt' client-side file. -While these behave as variables, do not always expect to just set them - -it is not certain whether this will work for all of them. Whenever there -is a command or a function to set something, it's usually preferable to -use that instead. The notable exception is Zeny, which you can and often -will address directly - setting it will make the character own this number -of Zeny. If you try to set Zeny to a negative number, the script will be +While these behave as variables, do not always expect to just set them - +it is not certain whether this will work for all of them. Whenever there +is a command or a function to set something, it's usually preferable to +use that instead. The notable exception is Zeny, which you can and often +will address directly - setting it will make the character own this number +of Zeny. If you try to set Zeny to a negative number, the script will be terminated with an error. Assigning variables --------- --------- -Variables can be accessed and assigned values directly without the use of -the built-in 'set' function. This means that variables can be accessed and +Variables can be accessed and assigned values directly without the use of +the built-in 'set' function. This means that variables can be accessed and modified much like other programming languages. .@x = 100; .@x = .@y = 100; -Support for modifying variable values using 'set' is still supported (and -required to exist for this method to work) so previous scripts will +Support for modifying variable values using 'set' is still supported (and +required to exist for this method to work) so previous scripts will continue working. Its usage, though, is deprecated, and it should never be used in new scripts unless there are special reasons to do so. -When assigning values, all operator methods are supported which exist in +When assigning values, all operator methods are supported which exist in the below 'Operators' section. For instance: .@x += 100; @@ -609,9 +609,9 @@ the below 'Operators' section. For instance: .@x >>= 2; .@x <<= 2; -Will all work. For more information on available operators, see the -Operators section described below. All operators listed there may be -placed in-front of the '=' sign when modifying variables to perform the +Will all work. For more information on available operators, see the +Operators section described below. All operators listed there may be +placed in-front of the '=' sign when modifying variables to perform the action as required. Increment and decrement operators are also provided, for your convenience. @@ -639,8 +639,8 @@ least not slower) than their respective post- equivalent. Note: - !! Currently the scripting engine does not support directly copying array - !! variables. In order to copy arrays between variables the use of + !! Currently the scripting engine does not support directly copying array + !! variables. In order to copy arrays between variables the use of !! 'copyarray' function is still required. Strings @@ -654,16 +654,16 @@ quote symbol (") in a string you need to escape it with a blackslash: Arrays ------ -Arrays (in Hercules at least) are essentially a set of variables going -under the same name. You can tell between the specific variables of an +Arrays (in Hercules at least) are essentially a set of variables going +under the same name. You can tell between the specific variables of an array with an 'array index', a number of a variable in that array: [] All variable types can be used as arrays. -Variables stored in this way, inside an array, are also called 'array -elements'. Arrays are specifically useful for storing a set of similar +Variables stored in this way, inside an array, are also called 'array +elements'. Arrays are specifically useful for storing a set of similar data (like several item IDs for example) and then looping through it. You can address any array variable as if it was a normal variable: @@ -674,7 +674,7 @@ array) as array index: .@x = 100; .@arrayofnumbers[.@x] = 10; - + This will make .@arrayofnumbers[100] equal to 10. Index numbering always starts with 0 and arrays can hold over 2 billion @@ -687,7 +687,7 @@ If the array index is omitted, it defaults to zero. Writing Arrays can naturally store strings: .@menulines$[0] is the 0th element of the .@menulines$ array of strings. -Notice the '$', normally denoting a string variable, before the square +Notice the '$', normally denoting a string variable, before the square brackets that denotes an array index. Variable References @@ -710,7 +710,7 @@ MAX_CART - Maximum cart items MAX_INVENTORY - Maximum inventory items MAX_ZENY - Maximum Zeny in the inventory MAX_BANK_ZENY - Maximum Zeny in the bank -MAX_BG_MEMBERS - Maximum BattleGround members +MAX_BG_MEMBERS - Maximum BattleGround members MAX_CHAT_USERS - Maximum Chat users MAX_REFINE - Maximum Refine level @@ -721,32 +721,32 @@ currently use them. Operators --------- -Operators are things you can do to variables and numbers. They are either +Operators are things you can do to variables and numbers. They are either the common mathematical operations or conditional operators: -+ - will add two numbers. If you try to add two strings, the result will - be a string glued together at the +. You can add a number to a string, - and the result will be a string. No other math operators work with ++ - will add two numbers. If you try to add two strings, the result will + be a string glued together at the +. You can add a number to a string, + and the result will be a string. No other math operators work with strings. -- - will subtract two numbers. +- - will subtract two numbers. * - will multiply two numbers. ** - will raise the first number to the power of the second number. / - will divide two numbers. Note that this is an integer division, i.e. 7/2 is not equal 3.5, it's equal 3. % - will give you the remainder of the division. 7%2 is equal to 1. -There are also conditional operators. This has to do with the conditional -command 'if' and they are meant to return either 1 if the condition is -satisfied and 0 if it isn't. That's what they call 'boolean' variables. 0 -means 'False'. Anything except the zero is 'True'. Odd as it is, -1 and -5 +There are also conditional operators. This has to do with the conditional +command 'if' and they are meant to return either 1 if the condition is +satisfied and 0 if it isn't. That's what they call 'boolean' variables. 0 +means 'False'. Anything except the zero is 'True'. Odd as it is, -1 and -5 and anything below zero will also be True.) -You can compare numbers to each other and you compare strings to each +You can compare numbers to each other and you compare strings to each other, but you can not compare numbers to strings. - == - Is true if both sides are equal. For strings, it means they contain + == - Is true if both sides are equal. For strings, it means they contain the same value. - >= - True if the first value is equal to, or greater than, the second + >= - True if the first value is equal to, or greater than, the second value. <= - True if the first value is equal to, or less than, the second value. > - True if the first value greater than the second value. @@ -783,9 +783,9 @@ Logical bitwise operators work only on numbers, and they are the following: << - Left shift. >> - Right shift. - Left shift moves the binary 1(s) of a number n positions to the left, + Left shift moves the binary 1(s) of a number n positions to the left, which is the same as multiplying by 2, n times. - In the other hand, Right shift moves the binary 1(s) of a number n + In the other hand, Right shift moves the binary 1(s) of a number n positions to the right, which is the same as dividing by 2, n times. Example: b = 2; @@ -799,21 +799,21 @@ Logical bitwise operators work only on numbers, and they are the following: 16 / 2 = 8; 8 / 2 = 4. & - And. | - Or. - The bitwise operator AND (&) is used to test two values against each - other, and results in setting bits which are active in both arguments. - This can be used for a few things, but in Hercules this operator is + The bitwise operator AND (&) is used to test two values against each + other, and results in setting bits which are active in both arguments. + This can be used for a few things, but in Hercules this operator is usually used to create bit-masks in scripts. - - The bitwise operator OR (|) sets to 1 a binary position if the binary - position of one of the numbers is 1. This way a variable can hold - several values we can check, known as bit-mask. A variable currently - can hold up to 32 bit-masks (from position 0 to position 1). This is a - cheap(skate) and easy way to avoid using arrays to store several + + The bitwise operator OR (|) sets to 1 a binary position if the binary + position of one of the numbers is 1. This way a variable can hold + several values we can check, known as bit-mask. A variable currently + can hold up to 32 bit-masks (from position 0 to position 1). This is a + cheap(skate) and easy way to avoid using arrays to store several checks that a player can have. - - A bit-mask basically is (ab)using the variables bits to set various - options in one variable. With the current limit in variables it is - possible to store 32 different options in one variable (by using the + + A bit-mask basically is (ab)using the variables bits to set various + options in one variable. With the current limit in variables it is + possible to store 32 different options in one variable (by using the bits on position 0 to 31). Example(s): @@ -822,8 +822,8 @@ Logical bitwise operators work only on numbers, and they are the following: Why? : 10 = 2^1 + 2^3 (2 + 8), so in bits, it would be 1010 2 = 2^1 (2), so in bits (same size) it would be 0010 - The & (AND) operator sets bits which are active (1) in both - arguments, so in the example 1010 & 0010, only the 2^1 bit is + The & (AND) operator sets bits which are active (1) in both + arguments, so in the example 1010 & 0010, only the 2^1 bit is active (1) in both. Resulting in the bit 0010, which is 2. - Basic example of creating and using a bit-mask: .@options = 2|4|16; // (note: this is the same as 2+4+16, or 22) @@ -840,10 +840,10 @@ Logical bitwise operators work only on numbers, and they are the following: This would print the messages about option 2, 3 and 5 (since we've set the 2,4 and 16 bit to 1). ^ - Xor. - The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if - both numbers have the same value in the said position. On the other - hand, it sets to 1 if they have different values in the said binary - position. This is another way of setting and unsetting bits in + The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if + both numbers have the same value in the said position. On the other + hand, it sets to 1 if they have different values in the said binary + position. This is another way of setting and unsetting bits in bit-masks. Example: @@ -856,7 +856,7 @@ Logical bitwise operators work only on numbers, and they are the following: mes("Quest 2: find a newbie and be helpful to him for an hour."); close(); } - - After spending some time reading info on Xor's, the player finally + - After spending some time reading info on Xor's, the player finally completes quest 1: if (inProgress&1 && isComplete) { // this will unset the bit for quest 1 (inProgress has that bit set to 1) @@ -865,11 +865,11 @@ Logical bitwise operators work only on numbers, and they are the following: close(); } -Unary operators with only with a single number, which follows the +Unary operators with only with a single number, which follows the operator, and are the following: - - Negation. - The sign of the number will be reversed. If the number was positive, + The sign of the number will be reversed. If the number was positive, it will become negative and vice versa. Example: @@ -887,16 +887,16 @@ operator, and are the following: } ~ - Bitwise Not. - Reverses each bit in a number, also known as one's complement. Cleared + Reverses each bit in a number, also known as one's complement. Cleared bits are set, and set bits are cleared. Example: - - Ensure, that quest 2 is disabled, while keeping all other active, if + - Ensure, that quest 2 is disabled, while keeping all other active, if they are. inProgress = inProgress&(~2); // same as set inProgress, inProgress&0xfffffffd -Ternary operators take three expressions (numbers, strings or boolean), +Ternary operators take three expressions (numbers, strings or boolean), and are the following: ?: - Conditional operator @@ -995,7 +995,7 @@ Within executable script code, some lines can be labels: