diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/script_commands.txt | 271 |
1 files changed, 247 insertions, 24 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 0af9644dd..ec8274716 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -974,14 +974,14 @@ Within executable script code, some lines can be labels: <label name>: Labels are points of reference in your script, which can be used to route -execution with 'goto', 'menu' and 'jump_zero' commands, invoked with -'doevent' and 'donpcevent' commands and are otherwise essential. A label's -name may not be longer than 22 characters. (23rd is the ':'.) There is -some confusion in the source about whether it's 22, 23 or 24 all over the -place, so keeping labels under 22 characters could be wise. It may only -contain alphanumeric characters and underscore. In addition to labels you -name yourself, there are also some special labels which the script engine -will start execution from if a special event happens: +execution with 'goto' and 'menu' commands, invoked with 'doevent', 'donpcevent' +and 'callsub' commands and are otherwise essential. A label's name may not be +longer than 22 characters. (23rd is the ':'.) There is some confusion in the +source about whether it's 22, 23 or 24 all over the place, so keeping labels +under 22 characters could be wise. It may only contain alphanumeric characters +and underscore. In addition to labels you name yourself, there are also some +special labels which the script engine will start execution from if a special +event happens: OnClock<hour><minute>: OnMinute<minute>: @@ -2058,6 +2058,14 @@ else if (<condition 2>) { *jump_zero (<condition>),<label>; + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it is +scheduled to be removed at any time on or after November 27th, 2014. Please +consider using 'if', 'switch', 'for', 'while', as appropriate. + This command works like an 'if'+'goto' combination in one go. (See 'if'). If the condition is false (equal to zero) this command will immediately jump to the specified label like in 'goto'. @@ -2788,6 +2796,13 @@ such item is found. --------------------------------------- +*getbrokencount() + +This function will return the total amount of broken equipment on the +invoking character. + +--------------------------------------- + *getequipisequiped(<equipment slot>) This functions will return 1 if there is an equipment placed on the @@ -3812,9 +3827,66 @@ falcon and 0 if they don't. --------------------------------------- +*setmount {<flag>}; +*checkmount() + +If <flag> is MOUNT_NONE (or 0) this command will remove the mount from the +character. + +Otherwise it gives the invoking character the desired combat mount, where +allowed by their class and skills. + +If no flag is specified, the mount is automatically chosen according to the +character's class and skills. + +The following flag values are accepted: + + MOUNT_NONE: + - Dismount + MOUNT_PECO: + - PecoPeco (Knight series class) + - GrandPeco (Crusader series class) + - Gryphon (Royal Guard) + MOUNT_WUG: + - Warg (Ranger) + MOUNT_MADO: + - Mado Gear (Mechanic) + MOUNT_DRAGON: + MOUNT_DRAGON_GREEN: + MOUNT_DRAGON_BROWN: + MOUNT_DRAGON_GRAY: + MOUNT_DRAGON_BLUE: + MOUNT_DRAGON_RED: + - Dragon (Rune Knight) + if MOUNT_DRAGON is specified, a the default (green) dragon will be used. + +Unlike 'setfalcon' and 'setcart' this will not work at all if they aren't of a +class which can ride a mount. + +The accompanying function will return 0 if the invoking character is not on a +mount, and a non-zero value (according to the above constants) if they are. +Note: in case of dragons, the returned value will always be MOUNT_DRAGON, +regardless of color. + + if (checkmount()) + mes "Leave your mount outside! No riding mounts on the floor here!"; + + if (checkmount() == MOUNT_DRAGON) + mes "Wow, your dragon is cool! Can I pet it?"; + +--------------------------------------- + *setriding {<flag>}; *checkriding() + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after November 30th, 2014. Please consider +using setmount and checkmount() instead. + If <flag> is 0 this command will remove the mount from the character. Otherwise it gives the invoking character a PecoPeco (if they are a Knight series class), a GrandPeco (if they are a Crusader series class), or @@ -3832,6 +3904,14 @@ riding a bird and 0 if they aren't. *setdragon {<color>}; *checkdragon() + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after November 30th, 2014. Please consider +using setmount and checkmount() instead. + The 'setdragon' function toggles mounting a dragon for the invoking character. It will return 1 if successful, 0 otherwise. @@ -3853,6 +3933,14 @@ riding a dragon and 0 if they aren't. *setmadogear {<flag>}; *checkmadogear() + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after November 30th, 2014. Please consider +using setmount and checkmount() instead. + If <flag> is 0 this command will remove the mount from the character. Otherwise it gives the invoking character a Mado (if they are a Mechanic). @@ -3861,10 +3949,10 @@ Mado and 0 if they don't. --------------------------------------- -*setmounting; -*ismounting() +*setcashmount; +*hascashmount() -The 'setmounting' function toggles cash mount for the invoking character. +The 'setcashmount' function toggles cash mount for the invoking character. It will return 1 if successful, 0 otherwise. Note: Character must not be mounting a non-cash mount (eg. dragon, peco, @@ -4187,7 +4275,6 @@ character is not married, or if there's no invoking character (no RID). --------------------------------------- *savepoint "<map name>",<x>,<y>; -*save "<map name>",<x>,<y>; This command saves where the invoking character will return to upon 'return to save point', if dead or in some other cases. The two versions @@ -4197,6 +4284,16 @@ character respawn where no teleportation is otherwise possible. savepoint "place",350,75; +*save "<map name>",<x>,<y>; + + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after December 2nd, 2014. Please consider +using savepoint() instead. + --------------------------------------- *heal <hp>,<sp>; @@ -6179,6 +6276,14 @@ A debug message also shows on the console when no events are triggered. *cmdothernpc "<npc name>","<command>"; + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after December 2nd, 2014. Please consider +using donpcevent() instead. + This is simply "donpcevent <npc name>::OnCommand<command>". It is an approximation of official server script language's 'cmdothernpc'. @@ -6654,8 +6759,6 @@ It's not clear what happens to a waiting room if the NPC is disabled with *enablewaitingroomevent {"<NPC object name>"}; *disablewaitingroomevent {"<NPC object name>"}; -*enablearena; -*disablearena; This will enable and disable triggering the waiting room event (see 'waitingroom') respectively. Optionally giving an NPC object name will do @@ -6669,6 +6772,17 @@ Normally, whenever a waiting room was created to make sure that only one character is, for example, trying to pass a job quest trial, and no other characters are present in the room to mess up the script. +*enablearena; +*disablearena; + + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after December 2nd, 2014. Please consider +using enablewaitingroomevent and disablewaitingroomevent instead. + The 'enablearena'/'disablearena' commands are just aliases with no parameter. These are supposedly left here for compatibility with official server scripts, but no Hercules script uses these at the moment. @@ -7250,12 +7364,16 @@ when not provided, "group level char" defaults to 99. (1 = log, 0 = no log), default is to not log. The following variables are set upon execution: - .@atcmd_command$ = The name of the @command used. - .@atcmd_parameters$[] = Array containing the given parameters, - starting from an index of 0. - .@atcmd_numparameters = The number of parameters defined. + .@atcmd_command$ = The name of the @command used. + .@atcmd_parameters$[] = Array containing the given parameters, + starting from an index of 0. + .@atcmd_numparameters = The number of parameters defined. -Example: +Parameters are split on spaces. Multiple spaces aren't grouped together, and +will create multiple (empty) arguments. +Any leading spaces before the first parameter will be omitted. + +Usage example: When a user types the command "@test", an angel effect will be shown. @@ -7268,6 +7386,50 @@ OnAtcommand: end; } +Parameter splitting example: + @mycommand + .@atcmd_numparameters -> 0 + .@atcmd_parameters$ -> { } + @mycommand<space><space> + .@atcmd_numparameters -> 0 + .@atcmd_parameters$ -> { } + @mycommand<space>foo + .@atcmd_numparameters -> 1 + .@atcmd_parameters$ -> { "foo" } + @mycommand<space><space>foo + .@atcmd_numparameters -> 1 + .@atcmd_parameters$ -> { "foo" } + @mycommand<space>foo<space>bar + .@atcmd_numparameters -> 2 + .@atcmd_parameters$ -> { "foo", "bar" } + @mycommand<space>foo<space><space>bar + .@atcmd_numparameters -> 3 + .@atcmd_parameters$ -> { "foo", "", "bar" } + @mycommand<space>foo<space> + .@atcmd_numparameters -> 2 + .@atcmd_parameters$ -> { "foo", "" } + @mycommand<space>foo<space><space> + .@atcmd_numparameters -> 3 + .@atcmd_parameters$ -> { "foo", "", "" } + +The called event label needs to take care of joining arguments together, in +case it expects spaces. For example: + +- script atcmd_example -1,{ +OnInit: + bindatcmd "test",strnpcinfo(3)+"::OnAtcommand"; + end; +OnAtcommand: + // This command expects a character name (that may contain spaces) as + // the only parameter. + .@name$ = ""; + for (.@i = 0; .@i < .@atcmd_numparameters; ++.@i) { + .@name$ += (.@i > 0 ? " " : "") + .@atcmd_parameters$[.@i]; + } + dispbottom("The specified name is: '" + .@name$ + "'"); + end; +} + --------------------------------------- *unbindatcmd "command"; @@ -7450,6 +7612,18 @@ Example: --------------------------------------- +*min(<number>{,<number>...<number>}) +*max(<number>{,<number>...<number>}) + +Returns the smallest (or biggest) from the set of given numbers. + +Example: + .@minimum = min(1, -6, -2, 8, 2); // .@minimum will be equal to -6 + .@maximum = max(0, 5, 10, 4); // .@maximum will be equal to 10 + .@level = min(BaseLevel, 70); // .@level will be the character's base level, capped to 70 + +--------------------------------------- + *md5("<string>") Returns the md5 checksum of a number or string. @@ -7853,17 +8027,24 @@ reached or when pet performance is activated. *petskillsupport <skill id>,<skill level>,<delay>,<percent hp>,<percent sp>; *petskillsupport "<skill name>",<skill level>,<delay>,<percent hp>,<percent sp>; -*petheal <level>,<delay>,<percent hp>,<percent sp>; This will make the pet use a specified support skill on the owner whenever the HP and SP are below the given percent values, with a specified delay time between activations. The skill numbers are as per 'db/(pre-)re/skill_db.txt'. -'petheal' works the same as 'petskillsupport' but has the skill ID -hard-coded to 28 (Heal). This command is deprecated. It's not quite certain who's stats will be used for the skills cast, the character's or the pets. Probably, Skotlex can answer that question. +*petheal <level>,<delay>,<percent hp>,<percent sp>; + + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +The petheal command is deprecated and it should not be used in new scripts, as +it is scheduled to be removed after November 27th, 2014. Please consider using +petskillsupport by specifying the AL_HEAL skill id instead. + *petskillattack <skill id>,<skill level>,<rate>,<bonusrate>; *petskillattack "<skill name>",<skill level>,<rate>,<bonusrate>; *petskillattack2 <skill id>,<damage>,<number of attacks>,<rate>,<bonusrate>; @@ -8284,17 +8465,23 @@ If *questinfo is set, and the same ID is specified here, the icon will be cleare --------------------------------------- -*completequest <ID>; +*completequest <ID>{,<ID2>}; Change the state for the given quest <ID> to "complete" and remove from the users quest log. +If a second quest id of greater value is specified, all quests between the two +will be completed. + --------------------------------------- -*erasequest <ID>; +*erasequest <ID>{,<ID2>}; Remove the quest of the given <ID> from the user's quest log. +If a second quest id of greater value is specified, all quests between the two +will be erased. + --------------------------------------- *changequest <ID>,<ID2>; @@ -8306,6 +8493,14 @@ Add quest of the <ID2> to the the quest log, and the state is "active". *checkquest(<ID>{,PLAYTIME|HUNTING}) + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + @ /!\ This command is deprecated @ + @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +This command is deprecated and it should not be used in new scripts, as it +is scheduled to be removed on or after November 28th, 2014. Please consider +using questprogress() instead. Or, in special cases, questactive(). + If no additional argument supplied, return the state of the quest: -1 = Quest not started (not in quest log) 0 = Quest has been given, but the state is "inactive" @@ -8329,6 +8524,34 @@ If parameter "HUNTING" is supplied: --------------------------------------- +*questprogress(<ID>{,PLAYTIME|HUNTING}) + +If no additional argument supplied, return the state of the quest: + 0 = Quest not started (not in quest log) + 1 = Quest has been given + 2 = Quest completed + +If parameter 'PLAYTIME' is supplied: + 0 = Quest not started (not in quest log) + 1 = The time limit has not yet been reached + 2 = The time limit has been reached + +If parameter 'HUNTING' is supplied: + 0 = Quest not started (not in quest log) + 1 = Player hasn't killed all of the target monsters + 2 = Player has killed all of the target monsters + +--------------------------------------- + +*questactive(<ID>) + +Check whether the given quest is in its active state. + +Returns true if the quest is active, false otherwise (quest not started, +inactive or completed) + +--------------------------------------- + *showevent <icon>{,<mark color>} Show an emotion on top of a NPC, and optionally, |