doc/script_commands.txt | 1620 ++++++++++++++++++++++++-----------------------
1 file changed, 825 insertions(+), 795 deletions(-)
diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 767aa54..7eaaa71 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -28,30 +28,57 @@ help.
A little learning never caused anyone's head to explode.
-Structure
----------
-
-The commands and functions are listed in no particular order:
-
-*Name of the command and how to call it.
-
-Descriptive text
-
- Small example if possible. Will usually be incomplete, it's there just
- to give you an idea of how it works in practice.
-To find a specific command, use Ctrl+F, (or whatever keys call up a search
-function in whatever you're reading this with) put an * followed by the
-command name, and it should find the command description for you.
+Structure and Table of Contents
+-------------------------------
+(*TableContents)
+
+The structure of the document is below. Also, a unique code has been put
+in each section so that you can easily find it with Ctrl+F (or whatever
+keys call up a search function in whatever you're reading this with).
+There will be only 2 coincidences when using these codes: this very Table
+of Contents and that section in particular, so the search function should
+find whatever you want right away. Only section without search code is the
+headers and introduction above.
+
+Search codes are preceded by an asterisk (*).
+
+If you find anything omitted througout all the document, please tell us.
+
+Table of Contents:
+
+1. Headers and introduction ( - )
+2. Structure and Table of Contents (*TableContents)
+3. Understanding this document (*UnderstandThis)
+4. Script loading structure (*LoadingScripts)
+5. Top level commands (*TopLevel)
+ 1. Warning about NPC names (*NPCNameWarning)
+ 2. Setting map flags (*TopMapflag)
+ 3. Creating a permanent monster spawn (*TopMonster)
+ (*TopBossMonster)
+ 4. Defining a warp point (*TopWarp)
+ 5. Defining NPC objects (scripts) (*TopScript)
+ 6. Placing shops or cashshops (*TopShop)
+ (*TopCashShop)
+ 7. Adding duplicates (*TopDuplicate)
+ 1. Adding warp duplicates (*TopDuplicateWarp)
+ 2. Adding script duplicates (*TopDuplicateScript)
+ 3. Adding shop or cashshop duplicates (*TopDuplicateShop)
+ (*TopDuplicateCashShop)
+ 8. Defining function objects (*TopFunction)
-If you find anything omitted, please tell us. :)
+
+
+
-Syntax
-------
+
+Understanding this document
+---------------------------
+(*UnderstandThis)
Throughout this document, wherever a command wants an argument, it is
given in <angle brackets>. This doesn't mean you should type the angle
-brackets. :) If an argument of a command is optional, it is given in
+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
@@ -67,24 +94,41 @@ 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'.
+The top level commands need the use of tabulation spaces so, for
+preventing problems and confusion, the tab symbols are written as '%TAB%'
+or '<TAB>' throughout this document, even though this makes the text a bit
+less readable. Using an invisible symbol to denote arguments is one of the
+bad things about this language, but we're stuck with it for now.
+Wherever you refer to a map, use 'mapname' instead of 'mapname.gat'.
+However, old scripts that keep the .gat will still work.
Script loading structure
------------------------
+(*LoadingScripts)
+
+As an exception to the just above section, the only parameter these
+instructions take is a string that shouldn't be enclosed between quotes.
+
+Map server automatically loads any available scripts that are referenced
+in the 'npc/re/scripts_main.conf' file for Renewal enabled servers or in
+the 'npc/pre-re/scripts_main.conf' file for Pre-Renewal servers. This file
+itself contains references to other files, just like this:
-Scripts are loaded by the map server as referenced in the
-'conf/map-server.conf' configuration file, but in the default
-configuration, it doesn't load any script files itself. Instead, it loads
-the file 'npc/scripts_main.conf' which itself contains references to other
-files. The actual scripts are loaded from txt files, which are linked up
-like this:
+import: <path to a filename>
+
+This will make the map server look on the specified filename for more file
+references or npc loading sentences, which are covered next. Nothing nice
+happens when you try to import the same file recursively or in a loop.
+
+The actual scripts are loaded from text files, which are linked up like
+this:
npc: <path to a filename>
-Any line like this, invoked, ultimately, by 'map-server.conf' will load up
-the script contained in this file, which will make the script available.
-No file will get loaded twice, to prevent possible errors.
+Any line like this will load up the script contained in this file, which
+will make the script available. No file will get loaded twice, to prevent
+possible errors.
Another configuration file option of relevance is:
@@ -93,241 +137,569 @@ delnpc: <path to a filename>
This will unload a specified script filename from memory, which, while
seemingly useless, may sometimes be required.
-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.
+File extensions don't matter when messing with these ones as long as you
+provide the correct file extension the files have themselves. This means
+you can save your scripts in .c extension if you want, so that you'll have
+some C syntax highlighting (which is quite similar to the scripts we have
+here) if you use some adequate text editors. Saving them in .txt is just
+a convention we follow.
-Block comments can also be used, where you can place /* and */ between any
-text you wish Hercules to ignore.
-
-Example:
-/* This text,
- * no matter which new line you start
- * is ignored, until the following
- * symbol is encountered: */
-
-The asterisks (*) in front of each line is a personal preference, and is
-not required.
+Top Level Commands
+------------------
+(*TopLevel)
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
+them.
+
+The top-level commands the scripting are pretty confusing, since
they aren't structured like you would expect commands, command name first,
but rather, normally start with a map name.
What's more confusing about the top-level commands is that most of them
-use a tab symbol to divide their arguments.
-
-To prevent problems and confusion, the tab symbols are written as '%TAB%'
-or '<TAB>' throughout this document, even though this makes the text a bit
-less readable. Using an invisible symbol to denote arguments is one of the
-bad things about this language, but we're stuck with it for now. :)
+use a tab symbol to divide their arguments. Remember that the tab symbols
+are written as '%TAB%' or '<TAB>' throughout this document.
Here is a list of valid top-level commands:
+* mapflag
+* monster
+* boss_monster
+* warp
+* script
+* shop
+* cashshop
+* duplicate
+* function
-** Set a map flag:
-
-<map name>%TAB%mapflag%TAB%<flag>
+They'll be explained like this:
-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'.
+Top level command and how to call it, with full list of parameters.
-** Create a permanent monster spawn:
+-> Description:
+ Short descriptive text about what it does.
+-> Parameters:
+ Any required or optional parameters it needs for working. Some
+ parameters will be explained together since it'll make for a better
+ explanation like this.
+-> Notes:
+ Notes about it. It'll be only present if needed.
+-> Examples:
+ Small example(s) so that you can get familiar with it.
-<map name>,<x>,<y>,<xs>,<ys>%TAB%monster%TAB%<monster name>%TAB%<mob id>,<amount>,<delay1>,<delay2>,<event>{,<mob size>,<mob ai>}
-Map name is the name of the map the monsters will spawn on. X,Y are the
-coordinates where the mob should spawn. If X's and Y's are non-zero, they
-specify the 'radius' of a spawn-rectangle area centered at x,y. Putting
-zeros instead of these coordinates will spawn the monsters randomly. Note
-this is only the initial spawn zone, as mobs random-walk, they are free to
-move away from their specified spawn region.
+But let's start with a warning about NPC names first:
-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).
+### Warning about NPC names ###
+(*NPCNameWarning)
-Amount is the amount of monsters that will be spawned when this command is
-executed, it is affected by spawn rates in 'battle.conf'.
-
-Delay1 and delay2 control monster respawn delays - the first one is the
-fixed base respawn time, and the second is random variance on top of the
-base time. Both values are given in milliseconds (1000 = 1 second). Note
-that the server also enforces a minimum respawn delay of 5 seconds.
-
-You can specify a custom level to use for the mob different from the one
-of the database by adjoining the level after the name with a comma. eg:
-"Poring,50" for a name will spawn a monster with name Poring and level 50.
-
-Event is a script event to be executed when the mob is killed. The event
-must be in the form "NPCName::OnEventName" to execute, and the event name
-label should start with "On". As with all events, if the NPC is an
-on-touch NPC, the player who triggers the script must be within 'trigger'
-range for the event to work.
-
-There are two optional fields for monster size and AI. Size can be 0
-(medium), 1 (small), or 2 (big). AI can be 0 (default), 1
-(attack/friendly), 2 (sphere), 3 (flora), or 4 (zanzou).
-
-Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able to be
-detected on the map with the SC_CASH_BOSS_ALARM status (used by Convex Mirror, item ID# 12214).
-
-** NPC names
-
-/!\ WARNING: this applies to warps, NPCs, duplicates and shops /!\
-
-NPC names are kinda special and are formatted this way:
+This applies to warps, NPCs, duplicates and shops, since they are the only
+scripts with a name. Their names are kinda special and are formatted this
+way:
<Display name>{::<Unique name>}
-All NPCs need to have a unique name that is used for identification
-purposes. When you have to identify a NPC by it's name, you should use
-<Unique name>. If <Unique name> is not provided, use <Display name>
-instead.
-
-The client has a special feature when displaying names: if the display
-name contains a '#' character, it hides that part of the name.
-Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter'
+All of them need to have a name that should be unique for identification
+purposes. The NPC name used for identification is its <Unique name> or, if
+it isn't provided, they are identified by their <Display name> instead.
+Remember:
<Display name> must be at most 24 characters in length.
<Unique name> must be at most 24 characters in length.
-** Define a warp point
+Any name too long for a NPC will just be truncated.
+
+Also, the client has a special feature when displaying names: if the
+display name contains a '#' character, it hides the rest of the name,
+starting from that '#'. Keep in mind that character also counts
+towards the limit.
+
+Examples with NPC names:
+
+Original NPC name | Displayed name | NPC identification name
+----------------------------------------------------------------------------
+MyNPCName | MyNPCName | MyNPCname
+----------------------------------------------------------------------------
+Hunter#hunter1 | Hunter | Hunter#hunter1
+----------------------------------------------------------------------------
+ThisNameIsTooLongForANPC | ThisNameisTooLongForANP | ThisNameisTooLongForANP
+----------------------------------------------------------------------------
+#hiddenName | (no displayed name) | #hiddenName
+----------------------------------------------------------------------------
+NPCName#91::MyUniqueName | NPCName | MyUniqueName
+----------------------------------------------------------------------------
+
+And one last thing about it: avoid putting the same identification names
+to NPCs (and truncated NPC names if applicable). Map server will warn you
+and automatically set or change their unique name in this fashion:
+
+<number of duplicate names>_<NPC's mapID in map server>_<x pos>_<y pos>
+
+For more details about this, please refer to the particular sections of
+the respective top level commands.
+
+### Setting map flags ###
+(*TopMapflag)
+
+<map name>%TAB%mapflag%TAB%<flag>{%TAB<optional parameter>}+
+-> Description:
+ When loaded, this will set the specified map flag on the selected map,
+ which will change the behavior of the map depending on the mapflag you
+ set. They're normally in files inside 'npc/mapflag', but you can also
+ see them on the same file as other scripts too.
+-> Parameters:
+ * map name: The name of the map you'll use to load the mapflag;
+ * mapflag: Keep it as is, this is the top level command;
+ * flag: the mapflag you'll load on the specified map. You can see a
+ list of the available map flags in 'db/const.txt' with the 'mf_'
+ prefix. You must __NOT__ copy the 'mf_' prefix as it's required
+ on the 'setmapflag' script command.
+ * optional parameter: For most map flags you can send them 'off' to
+ disable them. Some others may require this parameter (or even
+ more than one parameter separated with commas as it's the case of
+ the mf_nightmaredrop map flag). The type of optional parameter
+ also depends on the nature of the map flag you're setting.
+-> Notes: Not all map flags can be deactivated with the 'off' optional
+ parameter. Also some mapflags may not work if you don't provide them
+ the mapflag they require. You can also set map flags inside a script
+ by using the 'setmapflag' script command.
+-> Examples:
+ * Setting Prontera as PvP map:
+ prontera%TAB%mapflag%TAB%pvp
+ * Removing the GvG mapflag from guild_vs2:
+ guild_vs2%TAB%mapflag%TAB%gvg%TAB%off
+ * Changing the base exp you get on pay_fild04 to 2.50x (250):
+ pay_fild02%TAB%mapflag%TAB%bexp%TAB%250
+ * Making aldeg_cas01 castle have a random nightmare drop of
+ equipment of 70%:
+ aldeg_cas01%TAB%mapflag%TAB%nightmaredrop%TAB%random,equip,7000
+
+
+### Creating a permanent monster spawn ###
+(*TopMonster)
+(*TopBossMonster)
+
+<map name>,<x>,<y>{,<xs>{,<ys>}}%TAB%monster%TAB%<monster name>{,<mob level>}%TAB%<mob id>,<amount>{,<delay1>{,<delay2>{,<event>{,<mob size>,{<mob ai>}}}}}+<map name>,<x>,<y>{,<xs>{,<ys>}}%TAB%boss_monster%TAB%<monster name>{,<mob level>}%TAB%<mob id>,<amount>{,<delay1>{,<delay2>{,<event>{,<mob size>{,<mob ai>}}}}}+
+-> Description:
+ When parsed, this will make a permanent mob spawn (until server reboot
+ or script reload) with the specified characteristics.
+-> Parameters:
+ * map name: The map name in which the monster(s) will be spawned.
+ * x,y: They are the x and y coordinates on the specified map, in
+ which the monsters will be spawned or the center of the spawn
+ rectangle if xs or ys are greater than 0. If both x and y are 0,
+ the monsters will be spawned on a random position of the map. Be
+ warned that mobs walk around randomly, so that they may eventually
+ walk over the entire map as long as there's a walkable path!
+ * xs,ys: They are the horizontal and vertical span (ie, width and
+ height) of a spawn rectangle centered in x,y. Think of this as the
+ amount of squares you'd like to have your monster(s) spawned from
+ the center to both sides. For example, if xs is 6 and ys is 1, the
+ result would be a 6+1+6 width by 1+1+1 height spawn rectangle:
+ -------------
+ | C |
+ -------------
+ where that C is the center of that spawn rectangle. Even if both
+ of them are optional, you'd better set them together
+ * monster: __Mutually excluyent with boss_monster__. Specifies the
+ parser to spawn regular monsters with no special treatment.
+ * boss_monster: __Mutually excluyent with monster__. Specifies the
+ parser to spawn special monsters (usually MvPs) which can be
+ detected by the SC_CASH_BOSS_ALARM status (Convex Mirror). Please
+ note this will __not__ mark the mob as boss-type.
+ * monster name: The name the monsters will use, at your choice,
+ with a max of 24 characters by default. You could use some special
+ names as "--ja--", which will use the 'japanese name' of its
+ record in the monster database (that is, in fact, an English name)
+ or "--en--", which will use its 'english name' (that is that same
+ name in uppercase).
+ * mob level: If specified, spawned monsters will forcely be this
+ level, but they won't get any status changed other than this one.
+ * mob id: The actual mob id of the monsters you'll be spawning from
+ the mob db.
+ * amount: The amount of monsters you want to spawn. It's affected by
+ the mob_count_rate configuration in conf/battle/monster.conf
+ * delay 1: Minimum time, in milliseconds (1000 = 1 second) that,
+ after killing a monster from this respawn, the server will take to
+ spawn that monster again. This is known as base respawn time.
+ * delay 2: Random time, from 0 to this value (in milliseconds), that
+ will be added on top of the base respawn time to respawn a dead
+ monster from this respawn. Server always enforces a minimum of a
+ total 5000 milliseconds before respawning a mob.
+ * event: An NPC name and event to be executed on every death of any
+ of the spawned monsters (and, if an user has killed that mob, the
+ event will be executed attached to that user). The event must be
+ in the form "NPCName::OnEventName" for being executed, and the
+ event name label should start with "On". If you don't want to
+ execute any event, just set this value to 0 or 1. For more
+ information about labels, please see the 'Labels' section.
+ * mob size: This optional parameter will determine the size of the
+ summoned monsters on the spawn. Set it to 0 if you don't want to
+ alter the monster's size, 1 if you want them to be small and 2 if
+ you want to make the monsters big. Formerly, a summoned monster
+ with altered size had its stats, drop rates and experience doubled
+ on size = 2, or halved if size = 1, but now it's disabled by
+ default. You can enable this feature if you want by changing the
+ mob_size_influence configuration in conf/battle/monster.conf
+ * mob ai: The special AI the mob will have. It's not like the one
+ you set in the mob db, but a special extra behavior you may want
+ to set. 0 means no special behavior; 1 means the spawned monsters
+ will attack other monsters; 2 makes their behavior as if summoned
+ by Alchemist's Marine Sphere skill; 3 makes them behave as if
+ summoned by Alchemist's Summon Flora and 4 makes them behave as if
+ summoned as from Kagerou/Oboro's Zanzou skill.
+-> Notes:
+ Please note that by using this you'll make a __permanent__ monster
+ spawn, there's no way of unloading them from the server unless you
+ reboot or issue @reloadscript. If you want to make a mob spawn for
+ once or limited times, please refer to the 'monster' and 'areamonster'
+ script commands. Also note that if you want to put an optional
+ parameter and there are some others before, you'll have to fill the
+ ones before (mostly with zeros).
+-> Examples:
+ * Spawn a shining plant (ID# 1083) with its default name on prontera,
+ x=150, y=170 that will respawn every 5s (minimum default):
+ prontera,150,170%TAB%monster%TAB%--ja--%TAB%1083,1
+ * Spawn 10 boss level 99 porings (ID# 1002) named Satan Morroc at a
+ random place on prontera, which will respawn around 1~1:30 hours
+ after being killed (from 3600000 to 5400000 ms):
+ prontera,0,0%TAB%monster%TAB%Satan Morroc,99%TAB%1002,10,3600000,1800000
+ * Spawn 4 big Poporing on a 3x4 square around prontera,150,170,
+ which will attack other mobs and trigger the 'OnMyPopoDie' label
+ from 'MyNPCName' when killed (default respawn time):
+ prontera,150,170,3,4%TAB%monster%TAB%Poporing%TAB%1031,4,0,0,"MyNPCName::OnMyPopoDie",2,1
+
+
+### Defining a warp point ###
+(*TopWarp)
<from map name>,<fromX>,<fromY>{,<facing>}%TAB%warp%TAB%<warp name>%TAB%<spanx>,<spany>,<to map name>,<toX>,<toY>
-This will define a warp NPC that will warp a player between maps, and
-while most arguments of that are obvious, some deserve special mention.
-
-SpanX and SpanY will make the warp sensitive to a character who didn't
-step directly on it, but walked into a zone which is centered on the warp
-from coordinates and is SpanX in each direction across the X axis and
-SpanY in each direction across the Y axis.
-
-Warp NPC objects also have a name, because you can use it to refer to them
-later with 'enablenpc'/'disablenpc'.
-
-Facing of a warp object is irrelevant, it is not used in the code and all
-current scripts have a zero in there.
-
-** Define an NPC object.
-
+-> Description:
+ When parsed, this will make a warp NPC with its respective sprite,
+ that will warp users when they enter on their area of effect. They're
+ mostly used to connect all of the maps throughout Hercules.
+-> Parameters:
+ * from map name: The map name the warp npc will appear in.
+ * fromX,fromY: The x,y coordinates in which the warp NPC will be
+ placed.
+ * facing: Just an optional and useless parameter. All current warps
+ have a 0 in there, since warp NPCs have no orientations.
+ * warp: This tells the parser to parse a warp. Mandatory.
+ * warp name: The name of the warp so that you can manipulate it via
+ scripting for example with 'enablenpc', 'disablenpc' or 'movenpc'
+ script commands.
+ * spanx, spany: They are, respectively, the horizontal and vertical
+ span of the area of effect the warp will have. Their typical
+ values are 1, so that the warp area of effect will span througout
+ all of the NPC sprite (9 squares total).
+ * to map name: The destination map name the warp will send users to.
+ * toX, toY: The map coordinates the users will be sent to.
+-> Notes:
+ You can unload these warps by kicking them using the GM context menu
+ ingame (right clicking them while having a GM sprite set by the
+ clientinfo file).
+-> Examples:
+ * Current Hercules warp, from the south of Prontera to the fields:
+ prontera,156,22,0%TAB%warp%TAB%prt001%TAB%3,2,prt_fild08,170,375
+ * Same version of that warp without the deprecated facing parameter:
+ prontera,156,22%TAB%warp%TAB%prt001%TAB%3,2,prt_fild08,170,375
+
+
+### Defining NPC objects (scripts) ###
+(*TopScript)
+
+Three different ways:
<map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite id>,{<code>} <map name>,<x>,<y>,<facing>%TAB%script%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>,{<code>}-
-This will place an NPC object on a specified map at the specified
-location, and is a top-level command you will use the most in your custom
-scripting. The NPCs are triggered by clicking on them, and/or by walking
-in their trigger area, if defined. See that below.
-
-Facing is a direction the NPC sprite will face in. Not all NPC sprites
-have different images depending on the direction you look from, so for
-some facing will be meaningless. Facings are counted counterclockwise in
-increments of 45 degrees, where 0 means facing towards the top of the map.
-(So to turn the sprite towards the bottom of the map, you use facing 4,
-and to make it look southeast it's facing 5.)
-
-Sprite id is the sprite number used to display this particular NPC. For a
-full list of sprite id numbers see http://kalen.s79.xrea.com/npc/npce.shtml
-You may also use a monster's ID number instead to display a monster sprite
-for this NPC. It is possible to use a job sprite as well, but you must
-first define it as a monster sprite in 'mob_avail.txt', a full description
-on how to do this is not in the scope of this manual.
-A '-1' sprite id will make the NPC invisible (and unclickable).
-A '111' sprite id will make an NPC which does not have a sprite, but is
-still clickable, which is useful if you want to make a clickable object of
-the 3D terrain.
-
-TriggerX and triggerY, if given, will define an area, centered on NPC and
-spanning triggerX cells in every direction across X and triggerY in every
-direction across Y. Walking into that area will trigger the NPC. If no
-'OnTouch:' special label is present in the NPC code, the execution will
-start from the beginning of the script, otherwise, it will start from the
-'OnTouch:' label. Monsters can also trigger the NPC, though the label
-'OnTouchNPC:' is used in this case.
-
-The code part is the script code that will execute whenever the NPC is
-triggered. It may contain commands and function calls, descriptions of
-which compose most of this document. It has to be in curly brackets,
-unlike elsewhere where we use curly brackets, these do NOT signify an
-optional parameter.
-
-** Define a 'floating' NPC object.
-
-%TAB%script%TAB%<NPC Name>%TAB%-1,{<code>}
-This will define an NPC object not triggerable by normal means. This would
-normally mean it's pointless since it can't do anything, but there are
-exceptions, mostly related to running scripts at specified time, which is
-what these floating NPC objects are for. More on that below.
+IMPORTANT NOTE: We have decided to put all possibilities here instead of
+just showing that triggerX and triggerY are optional parameters since, as
+an exception to general notation rule on this document, __curly brackets
+around the code are required for your NPC to work__.
+
+-> Description:
+ This will place a NPC object on the specified place (except the last
+ one, that will make a 'floating' NPC that won't be on any specific
+ map), which are usually triggered by being clicked, but you can make
+ them get triggered some other ways such as being whispered or at
+ certain times of a day. Once triggered, they'll run part or all of the
+ code that has been written on it, depending on how you triggered it.
+-> Parameters:
+ * map name: The map name the NPC will be put in. Must be valid.
+ * x,y: The x and y coordinates to place the NPC at. You can safely
+ put the NPC on a non walkable cell if you want, as long as it's
+ inside of the map.
+ * facing: The direction the NPC will be facing in. Not all sprites
+ have an image for each of the directions, so this value can be
+ useless if you use sprites without different images for the
+ directions. Its range is between 0 and 7. 0 means the NPC is
+ looking north, then sum in incrementes of 45 degrees for each
+ number. For example: 2 means the NPC is facing west, 4 means it's
+ facing south and 5 means he's facing southeast.
+ * script: Required for this to be parsed as a script.
+ * NPC name: The name the NPC will have. Please take a look at the
+ previous name warning to prevent problems with them.
+ * sprite id: The sprite number used to display the NPC. You can also
+ use a monster ID as sprite ID to display a monster's sprite, or
+ even use a job sprite if you previously define it in the
+ 'db/mob_avail.txt' file. Interesting sprite IDs could be 45 (a
+ warp NPC sprite, for making warps via NPC scripts); 111, which is
+ an invisible yet clickable NPC sprite (you can use it to make
+ clickable objects on the map 3D land); and -1, which is an
+ invisible and unclickable NPC sprite, mostly to be used with
+ floating NPCs (they'll be further explained on the notes).
+ For an full and updated NPC list with IDs, please check this URL:
+ http://nn.nachtwolke.com/dev/npclist/
+ Note that you can actually set other sprite than 1 for floating
+ NPCs, but that'll be an useless assignment since nobody will be
+ ever able to see them.
+ * triggerX,triggerY: They are the trigger span area of the NPC. If
+ set (they're optional), this defines the horizontal and vertical
+ squares (from both sides) in which you can 'touch' this NPC. This
+ will also trigger the 'OnTouch:' or 'OnTouch_:' labels from
+ the NPC if present (if the NPC doesn't have it, the script will
+ run from the start). You could also make part of the NPC to run
+ when 'touched' by monsters if you make use of the 'OnTouchNPC:'
+ label. Please refer to the 'Labels' section for more information.
+ * code: The script code which the NPC will actually run when
+ triggered. Most of this document is composed of these script
+ commands descriptions. Please remember that the curly brackets are
+ mandatory here.
+-> Notes:
+ In case the NPC is 'touchable' and its code has both an 'OnTouch:' and
+ an 'OnTouch_:' label, only the 'OnTouch_:' label will be triggered;
+ You can make the NPC a 'floating' NPC if you put only a - (dash) as
+ the four first parameters. These NPCs can't be triggered by being
+ clicked or touched, but you may make them react to whispers or some
+ other events as if a player actually clicked it. Or you can even make
+ them work as an automated script, without the need of being activated
+ by someone. This will be explained later on, in more detail.
+-> Examples (without any code, since you don't know yet):
+ * A NPC in prontera, 156,200 with the sprite from the priest inside
+ Prontera church (60), named 'Pater Nostrum', looking southeast:
+ prontera,156,200,5%TAB%script%TAB%Pater Nostrum%TAB%60,{<code>}+ * Same NPC, but this time looking east (to the right) and can be
+ triggered on touch on a rectangle up to 2 cells from left or right
+ and up to 3 cells from up or down:
+ prontera,156,200,6%TAB%script%TAB%Pater Nostrum%TAB%60,2,3,{<code>}+ * A floating NPC named MyHiddenNPC:
+ -%TAB%script%TAB%MyHiddenNPC%TAB%-1,{<code>}+
+
+### Placing shops or cashshops ###
+*TopShop
+*TopCashShop
** Define a shop/cashshop NPC.
--%TAB%shop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}+Two different ways:
<map name>,<x>,<y>,<facing>%TAB%shop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}-
-This will define a shop NPC, which, when triggered (which can only be done
-by clicking) will cause a shop window to come up. No code whatsoever runs
-in shop NPCs and you can't change the prices otherwise than by editing the
-script itself (no variables even exist at this point of scripting, so
-don't even bother trying to use them).
-
-The item id is the number of item in the 'item_db.txt' database. If Price
-is set to -1, the 'buy price' given in the item database will be used.
-Otherwise, the price you gave will be used for this item, which is how you
-create differing prices for items in different shops.
-
-You can alternatively use "cashshop" in place of "shop" to use the Cash
-Shop interface, allowing you to buy items with special points (Currently
-stored as account vars in global_reg #CASHPOINTS and #KAFRAPOINTS). This
-type of shop will not allow you to sell items at it, you may only purchase
-items here. The layout used to define sale items still count, and
-"<price>" refers to how many points will be spent purchasing the them.
-
-** Define an warp/shop/cashshop/NPC duplicate.
-
-warp: <map name>,<x>,<y>{,<facing>}%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany>-shop/cashshop/npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>
-shop/cashshop/npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>
-npc: -%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>
-npc: <map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>,<triggerX>,<triggerY>
-
-This will duplicate an warp/shop/cashshop/NPC referred to by 'label'.
-Warp duplicates inherit the target location.
-Shop/cashshop duplicates inherit the item list.
-NPC duplicates inherit the script code.
-The rest (name, location, facing, sprite ID, span/trigger area) is
-obtained from the definition of the duplicate (not inherited).
-
-** Define a function object
+<map name>,<x>,<y>,<facing>%TAB%cashshop%TAB%<NPC Name>%TAB%<sprite id>,<itemid>:<price>{,<itemid>:<price>...}+-%TAB%shop%TAB%<NPC Name>%TAB%-1,<itemid>:<price>{,<itemid>:<price>...}+-%TAB%cashshop%TAB%<NPC Name>%TAB%-1,<itemid>:<price>{,<itemid>:<price>...}+
+-> Description:
+ This will place a shop or cash shop NPC where specified, with a
+ special code that will run upon trigger which lets you buy from it the
+ stated items, at the stated price.
+-> Parameters:
+ * map name,x,y,facing: The same as in script NPCs. Please see the
+ script top level command (just above) for more details. As you can
+ see, you can also put a dash (-) instead of them to make it a
+ "floating" shop, only triggerable for players by script NPCs via
+ the callshop script command.
+ * shop: __Mutually excluyent with cashshop__. Sets a regular shop
+ that will trade items (buy the stated items or sell any of your
+ own that you're allowed to sell) for zeny, and whose prices can
+ be influenced by skills such as Merchant's Discount and Overcharge.
+ * cashshop: __Mutually excluyent with shop__. Sets a cash shop,
+ which will use special points as currency. These points are stored
+ in the account variables #CASHPOINTS and #KAFRAPOINTS, and their
+ amounts will be reduced when buying something from them. You
+ usually can't sell items to cash shops. Also, Merchant's Discount
+ and similar skills will have no use here. Please see the Variables
+ section for more information about variables.
+ * sprite id: Just the same as in regular script NPCs. Please see the
+ above section for more information.
+ * itemid,price: The item ID (from the item db) of the item this shop
+ is selling and its respective price. Invalid item IDs will be
+ skipped when parsing a shop. The maximum amount of items a shop
+ can currently sell is 100 possibly due to client-side limitations,
+ so server-side limit is also 100. You can sell items for free (and
+ receive a warning in the map-server console) if you set the price
+ to 0, or sell them for the default buying price in the item db if
+ you specify a negative number (typically -1) for the price. Cash
+ shop items have no default buying price, so be warned that if you
+ put a negative number as the price, it will be sold for free. You
+ will also get a warning if there's an item in your shop that can
+ be sold (with overcharge) at a greater price than its discounted
+ amount. Please note that they both are in a special format (pairs
+ itemID:price) so that there won't be any confusions with prices.
+ You can sell the same item multiple times if you want, even at the
+ same price
+-> Notes:
+ Map server will ignore empty shops because they haven't any reasons
+ for existence. For a blank NPC, please use a script instead. Shops can
+ also be controlled by the script commands that start by npcshop.
+-> Examples:
+ * Actual Vendor from Milk Ranch shop NPC in Prontera:
+ prontera,73,134,0%TAB%shop%TAB%Vendor from Milk Ranch#p%TAB%90,519:-1
+ * Same shop but selling milk bottles for 500 Zeny:
+ prontera,73,134,0%TAB%shop%TAB%Vendor from Milk Ranch#p%TAB%90,519:500
+ * Same shop but selling milk for 10 cash points:
+ prontera,73,134,0%TAB%cashshop%TAB%Vendor from Milk Ranch#p%TAB%90,519:10
+ * Sample of actual Gonryun's tool shop (with many items):
+ gonryun,147,84,5%TAB%shop%TAB%Tool Dealer#gon%TAB%777,1750:-1,1770:-1,611:-1,501:-1,502:-1,503:-1,504:-1,506:-1,645:-1,656:-1,601:-1,602:-1,1065:-1
+ * Floating apple shop, default price (usually taken as dummy shop
+ for being controlled by script NPCs:
+ -%TAB%shop%TAB%Apple shop%TAB%-1,512:-1
+
+
+### Adding duplicates ###
+(*TopDuplicate)
+
+<map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<extra>
+-%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany>
+
+-> Description:
+ This is a special top level command, since its syntax varies on
+ whatever you want to duplicate. Keep in mind that you can only
+ duplicate NPCs with a name, so if you want to duplicate a mob spawn or
+ a mapflag, you should make a new declaration. Also, functions (seen
+ right after this section) can't be duplicated because it'd be nonsense
+ given its functionality. All duplicated NPC inherit some of the
+ features of the original NPC, which will be explained in each case.
+-> Parameters:
+ * map name,x,y,facing: Much like their respective counterparts,
+ these are the coordinates and facing your duplicate will be in.
+ And also changing them all to a dash (not valid for warp NPCs)
+ still retains the same meaning for floating shops or scripts.
+ * duplicate: Required for duplicating a NPC.
+ * label: The name of the _original_ NPC you wish to duplicate.
+ * NPC name: The name of the _new_ duplicated NPC. Beware of
+ duplicated NPC names since that rule still applies here. A good
+ idea for having same NPC names without fearing of duplicates is
+ using the hidden part of the display name.
+ * extra: Varies depending of the kind of NPC you wish to duplicate,
+ but also works the same way as the original ones.
+
+#### Adding warp duplicates ####
+(*TopDuplicateWarp)
+
+<map name>,<x>,<y>{,<facing>}%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<spanx>,<spany>+
+-> Description:
+ Duplicates the warp called the same as the label. The duplicate will
+ inherit original NPC's target location.
+-> Notes:
+ You can't make a floating warp with duplicates, just the same that
+ happened with regular warps.
+-> Example:
+ * Generating a copy of the example warp of before, right next to the
+ original warp NPC (just the duplicate):
+ prontera,159,22%TAB%duplicate(prt001)%TAB%prt001#2%TAB%,3,2
+
+#### Adding script duplicates ####
+(*TopDuplicateScript)
+
+<map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>{,<triggerX>,<triggerY>}+-%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%-1
+
+-> Description:
+ Duplicates the script referenced on the label parameter. Duplicates
+ will inherit the script code and will also share the same NPC
+ variables (.variables) and their values from one NPC to the other.
+ This doesn't happen with any other kind of variables, just this one.
+ For more information, please refer to the 'variables' section.
+-> Example:
+ * An actual duplicate of the Maroll Battle Recruiter script:
+ prontera,123,83,3%TAB%duplicate(BatRecruit)%TAB%Maroll Battle Recruiter::BatRecruit1%TAB%728
+
+#### Adding shop or cashshop duplicates ####
+(*TopDuplicateShop)
+(*TopDuplicateCashShop)
+
+<map name>,<x>,<y>,<facing>%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%<sprite id>
+-%TAB%duplicate(<label>)%TAB%<NPC Name>%TAB%-1
+
+-> Description:
+ Duplicates the shop referenced on the label parameter. Duplicated
+ shops will inherit the item list sold by the original NPC, along with
+ their respective prices.
+-> Example:
+ * Duplicating the actual Vendor from Milk Ranch shop NPC in
+ Prontera, right next to the original with a different name:
+ prontera,74,134,0%TAB%duplicate(Vendor from Milk Ranch#p)%TAB%Milk Vendor%TAB%90
+
+
+### Defining function objects ###
+(*TopFunction)
function%TAB%script%TAB%<function name>%TAB%{<code>}
-This will define a function object, callable with the 'callfunc' command
-(see below). This object will load on every map server separately, so you
-can get at it from anywhere. It's not possible to call the code in this
-object by anything other than the 'callfunc' script command.
+IMPORTANT NOTE: As an exception to general notation rule on this document,
+__curly brackets around the code are required for your function to work__.
+
+-> Description:
+ Upon parsing, this will define a function you can only call by using
+ the 'callfunc' script command, which will be available to every script
+ on the map server. The assigned code will be run once the function has
+ been called. Functions can have their own NPC variables (.variables),
+ however, they __can't__ be accessed by the script command
+ 'getvariableofnpc'. Also, you can pass some variables to the functions
+ when calling them. For more documentation about variables, please see
+ the 'variables' section.
+-> Parameters:
+ * function: Specifies this is a function. Think of this as another
+ kind of floating NPC, but with special properties that are only
+ enabled if you tell the server this is a function, not a regular
+ floating script. Required for being parsed as a function.
+ * script: Required for being parsed as a function.
+ * function name: The name you will be setting to the function so
+ that you can call it with 'callfunc'. Please note that if you try
+ to parse a new function with the name of an existing one, you'll
+ overload it (server will use the new one and 'forget' the old one
+ existed) along with a map server warning about it.
+ * code: The actual script commands the function will run when the
+ function is called. Most of this document is dedicated to describe
+ what these script commands do. Please remember that the curly
+ brackets are mandatory here.
+-> Example (without any code, since you don't know yet):
+ * Making a new function, called dec2bin:
+ function%TAB%script%TAB%dec2bin%TAB%{<code>}+
+
-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.
+Syntax
+------
+
+Whenever '//' is encountered in a line upon reading, everything beyond
+this on that line is considered to be a comment and is ignored. This works
+wherever you place it.
+
+// This line will be ignored when processing the script.
+
+Block comments can also be used, where you can place /* and */ between any
+text you wish Hercules to ignore.
+
+Example:
+/* This text,
+ * no matter which new line you start
+ * is ignored, until the following
+ * symbol is encountered: */
+
+The asterisks (*) in front of each line is a personal preference, and is
+not required.
-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.
+You can place comments wherever you want in a script, even outside a
+script. Just make sure to use them wisely and avoid doing weird things.
~ RID? GID? ~
@@ -406,7 +778,7 @@ Also notice that if you try to 'mes 0x10' it will print '16'.
Number values can't exceed the limits of an integer variable: Any number
greater than INT_MAX (2147483647) or smaller than INT_MIN (-2147483648) will
-be capped to those values and will cause a warning to be reported.
+be capped to those values and will cause a warning to be reported.
Variables
---------
@@ -414,10 +786,7 @@ Variables
The meat of every programming language is variables - places where you
store data.
-In Hercules scripting language, variable names are case sensitive. Even though
-at the current time the script engine accepts them even with the incorrect
-case, it is not advised to rely on this behavior, as it may change at any
-time.
+In Hercules scripting language, variable names are not case sensitive.
Variables are divided into and uniquely identified by the combination of:
prefix - determines the scope and extent (or lifetime) of the variable
@@ -445,7 +814,7 @@ nothing - A permanent variable attached to the character, the default
"$" - 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
+ Thhey 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
@@ -522,9 +891,7 @@ JobExp - Amount of job experience points.
NextBaseExp - Amount of base experience points needed to reach next level.
NextJobExp - Amount of job experience points needed to reach next level.
Weight - Amount of weight the character currently carries.
- Display as in Weight/10.
MaxWeight - Maximum weight the character can carry.
- Display as in MaxWeight/10.
Sex - 0 if female, 1 if male.
Class - Character's job.
Upper - 0 if the character is normal class, 1 if advanced, 2 if baby.
@@ -639,8 +1006,8 @@ even a value from an another array) to get at an array value:
This will make @arrayofnumbers[100] equal to 10.
-Notice that index numbering always starts with 0. Arrays can hold over
-2 billion variables.
+Notice that index numbering always starts with 0. Arrays cannot hold more
+than 128 variables (so the last one can't have a number higher than 127).
And array indexes probably can't be negative. Nobody tested what happens
when you try to get a negatively numbered variable from an array, but it's
@@ -727,12 +1094,6 @@ other, but you can not compare numbers to strings.
> - True if the first value greater than the second value.
< - True if the first value is less than the second value.
!= - True if the first value IS NOT equal to the second one.
- ~= - True if the second value (as regular expression) matches the first
- value. Both values must be strings. See the script function pcre_match
- for more details and advanced features.
- ~! - True if the second value (as regular expression) DOES NOT match the
- first value. Both values must be strings. See script function pcre_match
- for more details and advanced features.
Examples:
@@ -740,9 +1101,9 @@ Examples:
1<2 is True while 1>2 is False.
@x>2 is True if @x is equal to 3. But it isn't true if @x is 2.
-Only '==', '!=', '~=' and '~!' have been tested for comparing strings. Since
-there's no way to code a seriously complex data structure in this language,
-trying to sort strings by alphabet would be pointless anyway.
+Only '==' and '!=' have been tested for comparing strings. Since there's
+no way to code a seriously complex data structure in this language, trying
+to sort strings by alphabet would be pointless anyway.
Comparisons can be stacked in the same condition:
@@ -890,9 +1251,9 @@ Operator Precedence and Associativity
Operator precedence and associativity work more or less like they do in
mathematics. The rules can be summarized with the following table:
-Precedence | Description | Associativity
+Precedence | Operator (Description) | Associativity
---------------------------------------------------------------------------
-1 (highest) | [] Array subscripting | None
+1 (highest) | [] (Array subscripting) | None
---------------------------------------------------------------------------
2 | ++ Increment | None
| -- Decrement |
@@ -918,8 +1279,6 @@ Precedence | Description | Associativity
---------------------------------------------------------------------------
7 | == Equal to | Left to right
| != Not equal to |
- | ~= Regexp match |
- | ~! Regexp non-match |
---------------------------------------------------------------------------
8 | & Bitwise AND | Left to right
---------------------------------------------------------------------------
@@ -1110,41 +1469,46 @@ multiple commands on one line if you properly terminate them with a ';',
but it's better if you don't, since it is not certain just whether the
scripting engine will behave nicely if you do.
-Please note that command and function names are case sensitive. Even though at
-the current time the script engine accepts them with the incorrect case, it is
-not advised to rely on this behavior as it may change at any time.
-
-------------------------
-From here on, we will have the commands sorted as followed:
+From here on, we will have the commands sorted as follow:
-1 - Basic Commands
-2 - Information-Retrieving Commands
- -- 2.1: Information Item-Related Commands
- -- 2.2: Information Guild-Related Commands
-3 - Checking Commands
- -- 3.1: Checking Item-Related Commands
-4 - Player-Related Commands
- -- 4.1: Player Item-Related Commands
- -- 4.2: Guild-Related Commands
- -- 4.3: Marriage-Related Commands
-5 - Mob / NPC Related commands
- -- 5.1: Time-Related Commands
- -- 5.2: Guild-Related Commands
-6 - Other Commands
-7 - Instance Commands
-8 - Quest Log Commands
-9 - Battleground Commands
-10 - Mercenary Commands
-11 - Queue Commands
-12 - NPC Trader Commands
+1.- Basic commands.
+2.- Information-retrieving commands.
+3.- Checking commands.
+4.- Player-related commands.
+5.- Mob / NPC -related commands.
+6.- Other commands.
+7.- Instance commands.
+8.- Quest Log commands.
+9.- Battleground commands.
+10.- Mercenary commands.
+11.- Queue commands.
+The commands and functions are listed in no particular order inside their
+own categories. They're structured just like this:
----------------------------------------
-//=====================================
-1 - Basic Commands
-//=====================================
+*Name of the command and how to call it, with a full list of parameters.
+
+-> Short description:
+ Short descriptive text about what the command does.
+-> Parameters:
+ Any required or optional parameters the command needs for working.
+-> Returns:
+ What the command usually returns. Expect sometimes a list in case one
+ of the parameters specifies a type of return.
+-> Notes:
+ Notes about the script command. It'll be only present if needed.
+-> Examples:
+ Small example if possible/needed. Will usually be incomplete, it's
+ there just to give you an idea of how it works in practice. Some
+ commands will have more than one example.
+
+
+=====================
+|1.- Basic commands.|
+=====================
---------------------------------------
*mes "<string>"{,"<string>"..."<string>"};@@ -2269,16 +2633,10 @@ an array, shifting all the elements beyond this towards the beginning.
deletearray @array[1],3
---------------------------------------
-//=====================================
-1 - End of Basic-Related Commands
-//=====================================
----------------------------------------
-
----------------------------------------
-//=====================================
-2 - Information-retrieving Related Commands
-//=====================================
+======================================
+|2.- Information-retrieving commands.|
+======================================
---------------------------------------
*strcharinfo(<type>)
@@ -2378,11 +2736,6 @@ You can also use this command to get stat values.
if (readparam(bVit) > 77)
mes "Only people with over 77 Vit are reading this!";
-Example 3:
-
- // Display your current weight
- mes "Your current weight is "+( Weight/10 )+"/"+( MaxWeight/10 );
-
---------------------------------------
*getcharid(<type>{,"<character name>"})@@ -2655,9 +3008,9 @@ If the character is sitting, it will return 1, otherwise (standing) it will retu
In case no player is specified, the function will return the state of the attached player.
---------------------------------------
-//=====================================
-2.1 - Item-Related Commands
-//=====================================
+\\
+2,2 Item-related commands
+\\
---------------------------------------
*getequipid(<equipment slot>)
@@ -2679,13 +3032,6 @@ EQI_HEAD_LOW (10) - Lower Headgear (beards, some masks)
EQI_COSTUME_HEAD_LOW (11) - Lower Costume Headgear
EQI_COSTUME_HEAD_MID (12) - Middle Costume Headgear
EQI_COSTUME_HEAD_TOP (13) - Upper Costume Headgear
-EQI_COSTUME_GARMENT (14) - Costume Garment
-EQI_SHADOW_ARMOR (15) - Shadow Armor
-EQI_SHADOW_WEAPON (16) - Shadow Weapon
-EQI_SHADOW_SHIELD (17) - Shadow Shield
-EQI_SHADOW_SHOES (18) - Shadow Shoes
-EQI_SHADOW_ACC_R (19) - Shadow Accessory 2
-EQI_SHADOW_ACC_L (20) - Shadow Accessory 1
Notice that a few items occupy several equipment slots, and if the
character is wearing such an item, 'getequipid' will return it's ID number
@@ -2707,8 +3053,9 @@ Plate armor, but also don't want them to equip if after the check, you
would do this:
if ((getequipid(EQI_ARMOR) == 2341) || (getequipid(EQI_ARMOR) == 2342) goto L_EquipedLegionPlate;
- // the || is used as an or argument, there is 2341 and 2342 'cause there
- // are two different legion plate armors; one with a slot and one without.
+ // the || is used as an or argument, there is 2341 and 2342 cause
+ // there are two different legion plate armors, one with a slot one
+ // without.
if ((countitem(2341) > 0) || (countitem(2432) > 0) goto L_InventoryLegionPlate;
mes "I will lets you pass";
close2;
@@ -2723,7 +3070,7 @@ would do this:
---------------------------------------
-*getequipname(<equipment slot>)
+*getequipname(<equpment slot>)
Returns the jname of the item equipped in the specified equipment slot on
the invoking character, or an empty string if nothing is equipped in that
@@ -2735,7 +3082,7 @@ See 'getequipid' for a full list of valid equipment slots.
if( getequipname(EQI_HEAD_TOP) != "" )
mes "So you are wearing a "+getequipname(EQI_HEAD_TOP)+" on your head";
else
- mes "You are not wearing a head gear";
+ mes "You are not wearing any head gear";
---------------------------------------
@@ -2916,7 +3263,6 @@ recreate these items perfectly if they are destroyed. Here's what you get:
@inventorylist_expire[] - expire time (Unix time stamp). 0 means never
expires.
@inventorylist_count - the number of items in these lists.
-@inventorylist_bound - whether it is an account bounded item or not.
This could be handy to save/restore a character's inventory, since no
other command returns such a complete set of data, and could also be the
@@ -3015,9 +3361,9 @@ produced). It's useful for when you want to check whether an item contains
cards or if it's signed.
---------------------------------------
-//=====================================
-2.1 - End of Item-Related Commands
-//=====================================
+//
+2,1.- End of item-related commands.
+//
---------------------------------------
*getmapxy("<variable for map name>",<variable for x>,<variable for y>,<type>{,"<search string>"})@@ -3192,11 +3538,10 @@ window (see 'mes') paging it by 10 names as if with the 'next' command.
You need to put a 'close' after that yourself.
---------------------------------------
-//=====================================
-2.2 - Guild-Related Commands
-//=====================================
+\\
+2,2.- Guild-related commands
+\\
---------------------------------------
-
*getguildname(<guild id>)
This function returns a guild's name given an ID number. If there is no
@@ -3330,9 +3675,9 @@ Example:
mes "You have "+getMapGuildUsers("prontera",getcharid(2))+" guild members in Prontera.";
---------------------------------------
-//=====================================
-2.2 - End of Guild-Related Commands
-//=====================================
+//
+2,2.- End of guild-related commands
+//
---------------------------------------
*getskilllv(<skill id>)
@@ -3457,39 +3802,6 @@ Check sample in doc/sample/getmonsterinfo.txt
---------------------------------------
-*addmonsterdrop(<mob id or name>, <item id>, <rate>)
-
-This command will temporarily add a drop to an existing monster. If the
-monster already drops the specified item, its drop rate will be updated to the
-given value.
-
-Both the monster and the item must be valid. Acceptable values for the drop
-rate are in the range [1:10000].
-
-Return value will be 1 in case of success (the item was added or its drop rate
-was updated), and 0 otherwise (there were no free item drop slots).
-
-Example:
- // Add Poring Doll (741) to the Poring's (1002) drops, with 1% (100) rate
- addmonsterdrop(1002, 741, 100);
-
----------------------------------------
-
-*delmonsterdrop(<mob id or name>, <item id>)
-
-This command will temporarily remove a drop from an existing monster.
-
-Both the monster and the item must be valid.
-
-Return value will be 1 in case of success (the item was removed), and 0
-otherwise (the monster didn't have the specified item in its drop list).
-
-Example:
- // Remove Jellopy (909) from the Poring's (1002) drops
- delmonsterdrop(1002, 909);
-
----------------------------------------
-
*getmobdrops(<mob id>)
This command will find all drops of the specified mob and return the item
@@ -3578,10 +3890,11 @@ You can see the full list of available effect types you can possibly
inflict in 'db/const.txt' under 'Eff_'.
---------------------------------------
-//=====================================
-3 - Checking-Related Commands
-//=====================================
----------------------------------------
+
+========================
+|3.- Checking commands.|
+========================
+-------------------------
*playerattached()
@@ -3893,11 +4206,10 @@ by the type parameter.
6 - RENEWAL_ASPD (renewal ASPD)
---------------------------------------
-//=====================================
-3.1 - Checking Item-Related Commands
-//=====================================
+\\
+3,1.- Item-related commands
+\\
---------------------------------------
-
*isequipped(<id>{,<id>{,<id>{,<id>}}})
This function will return 1 if the invoking character has all of the item
@@ -3945,16 +4257,15 @@ equipment slot, which makes this script command kinda pointless.
For a list of equipment slots see 'getequipid'.
---------------------------------------
-//=====================================
-3.0 & 3.1 - End of Checking/Item-Related Commands
-//=====================================
+//
+3,1.- End of item-related commands
+//
---------------------------------------
----------------------------------------
-//=====================================
-4 - Player-Related Commands
-//=====================================
----------------------------------------
+==============================
+|4.- Player-related commands.|
+==============================
+-------------------------
*attachrid(<account ID>)
*detachrid;
@@ -4156,26 +4467,17 @@ character and produces no other output whatsoever.
*itemheal <hp>,<sp>;
-This command heals given relative amounts of HP and/or SP on the invoking
+This command heals given absolute amounts of HP and/or SP on the invoking
character. Unlike heal, this command is intended for use in item scripts.
-It applies potion-related bonuses, such as alchemist ranking, cards,
-status changes.
-It also applies a sp/vit-related bonus that is calculated by:
- heal = heal*[(100+STATUS*2)/100]
-So if a player has 99 vit and the script is 'itemheal 5,0':
- heal(hp) = 5*[(100+99*2)/100]
- heal(hp) = 14,9
- heal(hp) = 14
- heal(sp) = 0
-
-When used inside an NPC script, potion-related bonuses are omitted.
+It applies potion-related bonuses, such as alchemist ranking, cards and
+status changes. When used inside an NPC script, certain bonuses are
+omitted.
There is also a nice example on using this with the 'rand' function, to
give you a random amount of healing.
- // If the player has 50 vit and no bonuses this will heal
- // anything from 200 to 300 HP and 5 SP
- itemheal rand(100,150),5;
+ // This will heal anything thing from 100 to 150 HP and no SP
+ itemheal rand(100,150),0;
---------------------------------------
@@ -4446,12 +4748,12 @@ server is currently running on (depends on whether you used a SVN or Git
client for getting Hercules).
if ( get_version() >= 15000 )
- mes "Welcome to Hercules!";
+ mes "Welcome Hercules!";
---------------------------------------
-//=====================================
-4.1 - Player Item-Related Commands
-//=====================================
+\\
+4,1.- Item-related commands
+\\
---------------------------------------
*getitem <item id>,<amount>{,<account ID>};@@ -4596,51 +4898,6 @@ two eggs, and may hatch from either, although, I'm not sure what kind of a
mess will this really cause.
---------------------------------------
-*getitembound <item id>,<amount>,<bound type>{,<account ID>};-*getitembound "<item name>",<amount>,<bound type>{,<account ID>};-
-This command behaves identically to 'getitem', but the items created will be
-bound to the target character as specified by the bound type. All items created
-in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in
-some cases cannot be traded or stored.
-
-Valid bound types are:
- 1 - Account Bound
- 2 - Guild Bound
- 3 - Party Bound
- 4 - Character Bound
-
----------------------------------------
-
-*getitembound2 <item id>,<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>;
-*getitembound2 "<item name>",<amount>,<identify>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>,<bound type>;
-
-This command behaves identically to 'getitem2', but the items created will be
-bound to the target character as specified by the bound type. All items created
-in this manner cannot be dropped, sold, vended, auctioned, or mailed, and in
-some cases cannot be traded or stored.
-
-For a list of bound types see 'getitembound'.
-
----------------------------------------
-
-*countbound({<bound type>})-
-This function will return the number of bounded items in the character's
-inventory, and sets an array @bound_items[] containing all item IDs of the
-counted items. If a bound type is specified, only those items will be counted.
-
-For a list of bound types see 'getitembound'.
-
-Example:
- mes "You currently have "+countbound()+" bounded items.";
- next;
- mes "The list of bounded items include:";
- for(set .@i,0; .@i<getarraysize(@bound_items); set .@i,.@i+1)
- mes getitemname(@bound_items[.@i]);
- close;
-
----------------------------------------
*getnameditem <item id>,<character name|character ID>;
*getnameditem "<item name>",<character name|character ID>;
@@ -4857,9 +5114,8 @@ skill requirements.
---------------------------------------
-*itemeffect <item id>;
-*itemeffect "<item name>";
-*consumeitem is an alias of itemeffect (added for compatibility)
+itemeffect <item id>;
+itemeffect "<item name>";
This command will run the item script of the specified item on the
invoking character. The character does not need to posess the item, and
@@ -4979,17 +5235,21 @@ the command will end silently.
---------------------------------------
-*successrefitem <equipment slot>{,<upgrade_count>};+*successrefitem <equipment slot>;
This command will refine an item in the specified equipment slot of the
-invoking character by +1 (unless <upgrade_count> is specified).
-For a list of equipment slots see 'getequipid'.
-This command will also display a 'refine success'
+invoking character by +1. For a list of equipment slots see 'getequipid'.
+This command will not only add the +1, but also display a 'refine success'
effect on the character and put appropriate messages into their chat
window. It will also give the character fame points if a weapon reached
+10 this way, even though these will only take effect for blacksmith who
will later forge a weapon.
+The official scripts seems to use the 'successrefitem' command as a
+function instead: 'successrefitem(<number>)' but it returns nothing on the
+stack. This is since jAthena, so probably nobody knows for sure why is it
+so.
+
---------------------------------------
*failedrefitem <equipment slot>;
@@ -5010,11 +5270,15 @@ so.
This command will downgrade an item by - 1 (unless optional <downgrade_count> is provided)
in the specified equipment slot of the invoking character.
-So the item will not be destroyed unlike in the
+So the item will not be destroyed unlike in the
failedrefitem script command. This will also display a 'refine failure'
effect on the character and put appropriate messages into their chat
window.
+The official scripts seems to use the 'downrefitem' command as a function
+instead: 'downrefitem(<number>)' but it returns nothing on the stack.
+This is since jAthena, so probably nobody knows for sure why is it so.
+
---------------------------------------
*unequip <equipment slot>;
@@ -5037,7 +5301,7 @@ like storage or cart.
---------------------------------------
*equip <item id>;
-*autoequip <item id>,<option>;
+*autoEquip <item id>,<option>;
These commands are to equip a equipment on the attached character.
The equip function will equip the item ID given when the player has this
@@ -5092,9 +5356,9 @@ Example:
searchstores 10,1;
---------------------------------------
-//=====================================
-4.1 - End of Player Item-Related Commands
-//=====================================
+//
+4,1.- End of item-related commands
+//
---------------------------------------
*openstorage;
@@ -5137,9 +5401,9 @@ character.
end;
---------------------------------------
-//=====================================
-4.2 - Guild-Related Commands
-//=====================================
+\\
+4,2.- Guild-related commands
+\\
---------------------------------------
*guildopenstorage()
@@ -5199,9 +5463,9 @@ a good idea for a fun quest. (Wasting a level point on that is really
annoying :D)
---------------------------------------
-//=====================================
-4.2 - End of Guild-Related Commands
-//=====================================
+//
+4,2 End of guild-related commands.
+//
---------------------------------------
*resetlvl <action type>;
@@ -5518,6 +5782,10 @@ Flag 3 is the same as flag 0 in that it saves to the database. However,
these skills are ignored when any action is taken that adjusts the skill
tree (reset/job change).
+Flag 4 is the same as flag 1 in that it saves to the database. However,
+these skills are ignored when any action is taken that adjusts the skill
+tree (reset/job change).
+
---------------------------------------
*nude;
@@ -5542,9 +5810,9 @@ next;
undisguise; // Return to normal character sprite.
---------------------------------------
-//=====================================
-4.3 - Marriage-Related Commands
-//=====================================
+\\
+4,3 Marriage-related commands
+\\
---------------------------------------
*marriage("<spouse name>");@@ -5583,9 +5851,9 @@ This function will also destroy both wedding rings and send a message to
both players, telling them they are now divorced.
---------------------------------------
-//=====================================
-4.3 - End of Marriage-Related Commands
-//=====================================
+//
+4,3.- End of marriage-related commands
+//
---------------------------------------
*pcfollow <id>,<target id>;
@@ -5621,17 +5889,11 @@ Examples:
// Enables the current char to move again.
pcblockmove getcharid(3),0;
+---------------------------------------
----------------------------------------
-//=====================================
-4 - End of Player-Related Commands
-//=====================================
----------------------------------------
-
----------------------------------------
-//=====================================
-5 - Mob / NPC Related Commands
-//=====================================
+==================================
+|5.- Mob / NPC -related commands.|
+==================================
---------------------------------------
*monster "<map name>",<x>,<y>,"<name to show>",<mob id>,<amount>{,"<event label>",<size>,<ai>};@@ -5807,11 +6069,9 @@ commands can have non-empty event label.
If you pass this function an empty string for the event label, it will
return the total count of monster without event label, including
permanently spawning monsters.
-
With the dynamic mobs system enabled, where mobs are not kept in memory
for maps with no actual people playing on them, this will return a 0 for
any such map.
-
If the event label is given as "all", all monsters will be counted,
regardless of having any event label attached.
@@ -5880,46 +6140,20 @@ above 91000 intimacy with its owner.
---------------------------------------
-*gethominfo(<type>)
-
-This function works as a direct counterpart of 'getpetinfo':
- 0 - Homunculus unique ID
- 1 - Homunculus Class
- 2 - Name
- 3 - Friendly level (intimacy score). 100000 is full loyalty.
- 4 - Hungry level. 100 is completely full.
- 5 - Rename flag. 0 means this homunculus has not been named yet.
- 6 - Homunculus level
-
----------------------------------------
-
-*morphembryo;
-
-This command will try to put the invoking player's Homunculus in an
-uncallable state, required for mutation into a Homunculus S. The player
-will also receive a Strange Embryo (ID 6415) in their inventory if
-successful, which is deleted upon mutation.
-
-The command will fail if the invoking player does not have an evolved
-Homunculus at level 99 or above. The /swt emotion is shown upon failure.
-
-Returns 1 upon success and 0 for all failures.
-
----------------------------------------
-
*hommutate {<ID>};
-This command will try to mutate the invoking player's Homunculus into
-a Homunculus S. The Strange Embryo (ID 6415) is deleted upon success.
+This command will try to mutate the invoking player's Homunculus into a
+Homunculus S. The Strange Embryo (ID 6415) is deleted upon success.
-The command will fail if the invoking player does not have an evolved
-Homunculus at level 99 or above, if it is not in the embryo state
-(from the 'morphembryo' command), or if the invoking player does not
-possess a Strange Embryo. The /swt emotion is shown upon failure.
+The command will fail if the invoking player does not have an evolved
+Homunculus at level 99 or above, if it is not in the embryo state (from
+the 'morphembryo' command), or if the invoking player does not possess a
+Strange Embryo. The /swt emotion is shown upon failure.
-If the optional parameter <ID> is set, the invoking player's Homunculus
-will change into the specified Homunculus ID. Otherwise, a random Homunculus S
-will be chosen. See 'db/homunculus_db.txt' for a full list of IDs.
+If the optional parameter <ID> is set, the invoking player's Homunculus
+will change into the specified Homunculus ID. Otherwise, a random
+Homunculus S will be chosen. See 'db/homunculus_db.txt' for a full list of
+IDs.
Returns 1 upon success and 0 for all failures.
@@ -5936,12 +6170,26 @@ and will return the following values:
---------------------------------------
+*gethominfo(<type>)
+
+This function works as a direct counterpart of 'getpetinfo':
+ 0 - Homunculus unique ID
+ 1 - Homunculus Class
+ 2 - Name
+ 3 - Friendly level (intimacy score). 100000 is full loyalty.
+ 4 - Hungry level. 100 is completely full.
+ 5 - Rename flag. 0 means this homunculus has not been named yet.
+ 6 - Homunculus level
+
+---------------------------------------
+
*unitwalk <GID>,<x>,<y>;
-*unitwalk <GID>,<target_GID>;
+*unitwalk <GID>,<mapid>;
This is one command, but can be used in two ways. If only the first
argument is given, the unit whose GID is given will start walking towards
-the target whose GID is given.
+the map with the given mapid (we believe these are the map-indexes found
+in db/map_index.txt).
When 2 arguments are passed, the given unit will walk to the given x,y
coordinates on the map where the unit currently is.
@@ -5951,8 +6199,9 @@ Examples:
//Will move/walk the poring we made to the coordinates 150,150
unitwalk .GID,150,150;
-//NPC will move towards the attached player.
- unitwalk .GID,getcharid(3);//a player's GID is their account ID
+//Will move the poring towards alberta (if my assumed map-indexes are
+//correct).
+ unitwalk .GID,3;
---------------------------------------
@@ -6108,11 +6357,10 @@ Returns 0 is successful, 1 if the NPC does not exist.
Size is 0 = normal 1 = small 2 = big.
---------------------------------------
-//=====================================
-5.1 - Time-Related Commands
-//=====================================
+\\
+5,1.- Time-related commands
+\\
---------------------------------------
-
*addtimer <ticks>,"NPC::OnLabel";
*deltimer "NPC::OnLabel";
*addtimercount <ticks>,"NPC::OnLabel";
@@ -6312,10 +6560,9 @@ color format is in RGB (0xRRGGBB). The color is currently ignored by the
client and appears always green.
---------------------------------------
-//=====================================
-5.1 - End of Time-related commands
-//=====================================
----------------------------------------
+//
+5,1.- End of time-related commands
+//
*announce "<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}};
@@ -6735,9 +6982,9 @@ Example:
mapwarp "prontera","alberta",150,150,1,63;
---------------------------------------
-//=====================================
-5.2 - Guild-Related Commands
-//=====================================
+\\
+5,2.- Guild-related Commands
+\\
---------------------------------------
*maprespawnguildid "<map name>",<guild id>,<flag>;
@@ -6835,9 +7082,9 @@ Type indicates what information to return:
2 - current hp
---------------------------------------
-//=====================================
-5.2 - End of Guild-Related Commands
-//=====================================
+//
+5,2.- End of guild-related commands
+//
---------------------------------------
*npcspeed <speed value>;
@@ -6886,20 +7133,20 @@ Example:
moveNPC "Bugga",100,20;
---------------------------------------
-//=====================================
-6 - Other Commands
-//=====================================
+
+=====================
+|6.- Other commands.|
+=====================
---------------------------------------
*debugmes "<message>";
This command will send the message to the server console (map-server
window). It will not be displayed anywhere else.
-//
+
// Displays "NAME has clicked me!" in the map-server window.
debugmes strcharinfo(0)+" has clicked me!";
-
- // debugmes "\033[38D\033[K ==Message== \n"; // enable colour code.
+
---------------------------------------
*logmes "<message>";
@@ -7081,8 +7328,8 @@ You can add your own effects this way, naturally.
---------------------------------------
-*playbgm "<BGM filename>";
-*playbgmall "<BGM filename>"{,"<map name>"{,<x0>,<y0>,<x1>,<y1>}};+*playBGM "<BGM filename>";
+*playBGMall "<BGM filename>"{,"<map name>"{,<x0>,<y0>,<x1>,<y1>}};
These two commands will play a Background Music to either the invoking
character only ('playBGM') or multiple characters ('playBGMall').@@ -7245,54 +7492,15 @@ script is used.
---------------------------------------
-*pcre_match("<string>","<regex>");-
-This command is only available if the server is compiled with regular
-expressions library enabled.
-
-The string <string> will be searched for a match to the regular expression
-<regex>, and the number of matches will be returned.
-
-An alternative way to invoke this command is to use the operators '~=' or '~!'.
-The operator '~=' is exactly the same as pcre_match, while the operator '~!'
-will return 1 if no matches were found, or 0 if at least a match was found.
-
- if (pcre_match("string", "regex")) mes "There was a match.";- if ("string" ~= "regex") mes "There was a match.";- if ("string" ~! "regex") mes "There were no matches.";-
-You can find more usage examples in the test script npc/custom/test.txt.
-
-Using regular expressions is high wizardry. But with this high wizardry
-comes unparalleled power of text manipulation. For an explanation of what
-a regular expression pattern is, see a few web pages:
-
-http://www.regular-expressions.info/
-http://www.weitz.de/regex-coach/
-
-Additionally, the following temporary variables will be filled (unless the
-command is invoked as '~!'):
-
-- $@regexmatchcount: The number of matches detected, including any
- parenthesized capture-groups.
-- $@regexmatch$[0]: The part of <string> That matched the full <regex> pattern.
-- $@regexmatch$[1 .. $@regexmatchcount]: The parts of <string> that matched
- each of the parenthesized capture-groups in <pattern>.
-
-A capture group is a part of a regex enclosed in (parentheses) in order to
-store in a variable the part of the expression that was matched by that part of
-the regex. For more details, see the links above, as this is not intended to be
-a regex tutorial.
-
----------------------------------------
-
*defpattern <set number>,"<regular expression pattern>","<event label>";
*activatepset <set number>;
*deactivatepset <set number>;
*deletepset <set number>;
This set of commands is only available if the server is compiled with
-regular expressions library enabled.
+regular expressions library enabled. Default compilation and most binary
+distributions aren't, which is probably bad, since these, while complex to
+use, are quite fascinating.
They will make the NPC object listen for text spoken publicly by players
and match it against regular expression patterns, then trigger labels
@@ -7316,6 +7524,13 @@ pattern set number in this case will deactivate all pattern sets defined.
'deletepset' will delete a pattern set from memory, so you can create a
new pattern set in its place.
+Using regular expressions is high wizardry. But with this high wizardry
+comes unparalleled power of text manipulation. For an explanation of what
+a regular expression pattern is, see a few web pages:
+
+http://www.regular-expressions.info/
+http://www.weitz.de/regex-coach/
+
For an example of this in use, see doc/sample/npc_test_pcre.txt
With this you could, for example, automatically punish players for asking
@@ -7431,31 +7646,20 @@ setitemscript 2637,"";
---------------------------------------
-*atoi("<string>")-*axtoi("<string>")-*strtol("string", base)+*atoi ("<string>")+*axtoi ("<string>")
These commands are used to convert strings to numbers. 'atoi' will
interpret given string as a decimal number (base 10), while 'axtoi'
-interprets strings as hexadecimal numbers (base 16). 'strtol' lets
-the user specify a base (valid range is between 2 and 36 inclusive,
-or the special value0, which means auto-detection).
+interprets strings as hexadecimal numbers (base 16).
-The atoi and strtol functions conform to the C functions with the same
-names, and axtoi is the same as strtol, with a base of 16. Results are
-clamped to signed 32 bit int range (INT_MIN ~ INT_MAX)
+Hexadecimal number set: {0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F}
Example:
-.@var = atoi("11"); // Sets .@var to 11-.@var = axtoi("FF"); // Sets .@var to 255-mes axtoi("11"); // Displays 17 (1 = 1, 10 = 16)-.@var = strtol("11", 10); // Sets .@var to 11 (11 base 10)-.@var = strtol("11", 16); // Sets .@var to 17 (11 base 16)-.@var = strtol("11", 0); // Sets .@var to 11 (11 base 10, auto-detected)-.@var = strtol("0x11", 0); // Sets .@var to 17 (11 base 16, auto-detected because of the "0x" prefix)-.@var = strtol("011", 0); // Sets .@var to 9 (11 base 8, auto-detected because of the "0" prefix)-.@var = strtol("11", 2); // Sets .@var to 3 (binary 11)+set @var, atoi("11"); // Sets @var to 11+set @var, axtoi("FF"); // Sets @var to 255+mes axtoi("11"); // Displays 17 (1 = 1, 10 = 16)
---------------------------------------
@@ -7661,7 +7865,7 @@ in the count parameter.
Example:
replacestr("testing tester", "test", "dash"); //returns "dashing dasher" replacestr("Donkey", "don", "mon", 0); //returns "monkey"- replacestr("test test test test test", "test", "yay", 0, 3); //returns "yay yay yay test test"+ replacestr("test test test test test", "test", "yay", 0, 3); //returns "yay yay yay test test"
---------------------------------------
@@ -7931,9 +8135,10 @@ Directions are the same as NPC sprite facing directions: 0=north,
This will open a book item at the specified page.
---------------------------------------
-//=====================================
-7 - Instance-Related Commands
-//=====================================
+
+========================
+|7.- Instance commands.|
+========================
---------------------------------------
*instance_create("<instance name>",<owner id>{,<optional owner_type>});@@ -8042,14 +8247,6 @@ Returns name of the instanced map on success, otherwise an empty string.
---------------------------------------
-*has_instance2("<map name>");-
-Same as has_instance, with exception it returns the instance id of the map,
-as long as the user is assigned to a instance containing that map.
-It will return -1 upon failure, valid instance ids are >= 0.
-
----------------------------------------
-
*instance_id();
Retrieves the instance id of the script it is being run on.
@@ -8102,91 +8299,16 @@ if (instance_check_party(getcharid(1),2,2,149)) { }
---------------------------------------
-*instance_set_respawn(<map_name>,<x>,<y>{,<instance_id>});-
-Updates the 'reload spawn' position of a instance,
-that is where players in the instance are sent to upon @reloadscript,
-uses the npc instance (if any) when instance_id is not provided,
-handy to update a instance's progress so that when/if @reloadscript happens
-the damage to the players progress is reduced.
-It is most effective when used with instance variables (which are @reloadscript persistent)
-
-If a player warps into a instance before this command has been used,
-it will use the player's warp destination as the initial respawn point,
-it can of course be modified by using this script command at any point.
-
----------------------------------------
-*instance_mapname("<map name>"{,<instance id>})-
-Returns the unique name of the instanced map. If no instance ID is specified,
-the instance the script is attached to is used. If the script is not attached to
-an instance, the instance of the currently attached player's party is used. If
-that fails, the command returns an empty string instead.
-
-
----------------------------------------
-//=====================================
-7 - End of Instance-Related Commands
-//=====================================
----------------------------------------
-
-
----------------------------------------
-//=====================================
-8 - Quest Log-Related Commands
-//=====================================
----------------------------------------
-
-*questinfo <Quest ID>, <Icon> {, <Map Mark Color>{, <Job Class>}};-
-This is esentially a combination of checkquest and showevent. Use this only
-in an OnInit label. For the Quest ID, specify the quest ID that you want
-checked if it has been started yet.
-
-For Icon, use one of the following:
-
-No Icon : QTYPE_NONE
-! Quest Icon : QTYPE_QUEST
-? Quest Icon : QTYPE_QUEST2
-! Job Icon : QTYPE_JOB
-? Job Icon : QTYPE_JOB2
-! Event Icon : QTYPE_EVENT
-? Event Icon : QTYPE_EVENT2
-Warg : QTYPE_WARG
-Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410)
-
-Map Mark Color, when used, creates a mark in the user's mini map on the position of the NPC,
-the available color values are:
-
-0 - No Marker
-1 - Yellow Marker
-2 - Green Marker
-3 - Purple Marker
-
-When a user shows up on a map, each NPC is checked for questinfo that has been set.
-If questinfo is present, it will check if the quest has been started, if it has not, the bubble will appear.
-
-Optionally, you can also specify a Job Class if the quest bubble should only appear for a certain class.
-
-Example
-izlude,100,100,4 script Test 844,{- mes "[Test]";
- mes "Hello World.";
- close;
-
- OnInit:
- questinfo 1001, QTYPE_QUEST, 0, Job_Novice;
- end;
-}
+=========================
+|8.- Quest Log commands.|
+=========================
---------------------------------------
*setquest <ID>;
Place quest of <ID> in the users quest log, the state of which is "active".
-If *questinfo is set, and the same ID is specified here, the icon will be cleared when the quest is set.
-
---------------------------------------
*completequest <ID>;
@@ -8234,42 +8356,33 @@ If parameter "HUNTING" is supplied:
---------------------------------------
-*showevent <icon>{,<mark color>}+*showevent <state>, <color>;
-Show an emotion on top of a NPC, and optionally,
-a colored mark in the mini-map like "viewpoint".
-This is used to indicate that a NPC has a quest or an event to
-a certain player.
+Show a colored mark in the mini-map like "viewpoint" and an emotion on top
+of a NPC. This is used to indicate that a NPC has a quest or an event to
+certain player/s.
-Available Icons:
+state can be:
+ 0 = disable ( Used to disable and remove the mark and the emotion from
+ the NPC. )
+ 1 = exclamation emotion ( Used to show an important quest event to
+ certain player. )
+ 2 = interrogation emotion ( Used to show an non-important quest event
+ to certain player. )
+Other value may cause client crashes.
-Remove Icon : QTYPE_NONE
-! Quest Icon : QTYPE_QUEST
-? Quest Icon : QTYPE_QUEST2
-! Job Icon : QTYPE_JOB
-? Job Icon : QTYPE_JOB2
-! Event Icon : QTYPE_EVENT
-? Event Icon : QTYPE_EVENT2
-Warg : QTYPE_WARG
-Warg Face : QTYPE_WARG2 (Only for packetver >= 20120410)
+color can be:
+ 0 = yellow "Quest"
+ 1 = orange "Job"
+ 2 = green "Event"
+ 3 = an MVP flag
+Other values show a transparent mark in the mini-map.
-Mark Color:
-0 - No Mark
-1 - Yellow Mark
-2 - Green Mark
-3 - Purple Mark
+----------------------------------------
----------------------------------------
-//=====================================
-8 - End of Quest Log-Related Commands
-//=====================================
----------------------------------------
-
-
----------------------------------------
-//=====================================
-9 - Battlegrounds-Related Commands
-//=====================================
+============================
+|9.- Battleground commands.|
+============================
---------------------------------------
*waitingroom2bg_single(<battle group>,"<mapname>",<x>,<y>,"<npc name>");
@@ -8417,17 +8530,11 @@ This command will force the update of the displayed scoreboard.
It is only usable when the map is defined as a Type 2 Battleground:
mapflag%TAB%<mapname>%TAB%battleground%TAB%2
----------------------------------------
-//=====================================
-9 - End of Battlegrounds-Related Commands
-//=====================================
----------------------------------------
-
+----------------------------------------
----------------------------------------
-//=====================================
-10 - Mercenary Commands
-//=====================================
+==========================
+|10.- Mercenary commands.|
+==========================
---------------------------------------
*mercenary_create <class>,<contract time>;
@@ -8494,17 +8601,11 @@ following:
If the character does not have a mercenary, the command returns ""
for name and 0 for all other types.
----------------------------------------
-//=====================================
-10 - End of Mercenary-Related Commands
-//=====================================
----------------------------------------
-
+----------------------------------------
----------------------------------------
-//=====================================
-11 - Queue-Related Commands
-//=====================================
+======================
+|11.- Queue Commands.|
+======================
---------------------------------------
*queue();
@@ -8588,75 +8689,4 @@ Example:
Deletes a queue iterator from memory and returns 1 when it fails,
otherwise 0 is returned.
----------------------------------------
-//=====================================
-11 - End of Queue-Related Commands
-//=====================================
----------------------------------------
-
----------------------------------------
-//=====================================
-12 - NPC Trader-Related Commands
-//=====================================
-Commands that control NPC Trader Shops
-See /doc/sample/npc_trader_sample.txt
----------------------------------------
-
-*openshop({NPC_Name});-
-opens the trader shop from the currently-attached npc unless,
-when the optional NPC_Name param is used.
-
----------------------------------------
-
-*sellitem <Item_ID>{,<price>{,<qty>}};-
-adds (or modifies) <Item_ID> data to the shop,
-when <price> is not provided (or when it is -1) itemdb default is used.
-qty is only necessary for NST_MARKET trader types.
-
-when <Item_ID> is already in the shop,
-the previous data (price/qty), is overwritten with the new.
-
----------------------------------------
-
-*stopselling <Item_ID>;
-
-attempts to remove <Item_ID> from the current shop list.
-
----------------------------------------
-
-*setcurrency <Val1>{,<Val2>};-
-updates the currently attached player shop funds,
-to be used within a "OnCountFunds" event of a NST_CUSTOM trader type.
-
-<Val1> is the value used in the *Cash* Points field
-<Val2> is the value used in the Kafra Points field
-
----------------------------------------
-
-*tradertype(<Type>);
-
-Modifies the npc trader type, item list is cleared upon modifiying the value.
-By default, all npcs staart with tradertype(NST_ZENY);
-
-- NST_ZENY (0) Normal Zeny Shop
-- NST_CASH (1) Normal Cash Shop
-- NST_MARKET (2) Normal NPC Market Shop (where items have limited availability and need to be refurbished)
-- NST_CUSTOM (3) Custom Shop (any currency, item/var/etca, check sample)
-
----------------------------------------
-
-*purchaseok();
-
-Signs that the transaction (on a NST_CUSTOM trader) has been successful,
-to be used within a "OnPayFunds" event of a NST_CUSTOM trader.
-
----------------------------------------
-
-*shopcount(<Item_ID>);
-
-Returns the amount of still-available <Item_ID> in the shop (on a NST_MARKET trader).
-
----------------------------------------
+---------------------------------------
\ No newline at end of file