From 91d87f7a903545b70e23e3aa0edbd2e3ee2b67bc Mon Sep 17 00:00:00 2001 From: ai4rei Date: Wed, 8 Dec 2010 23:41:55 +0000 Subject: * Applied some script command documentation updates and fixes as already done inside the wiki. - Updated description for 'next', 'return', 'attachrid', 'detachrid', 'itemskill', 'openstorage', 'skilleffect', 'donpcevent', 'day', 'night', 'atoi' and 'axtoi' to resolve inaccuracies, missing information or unverified behavior. - Clarified the purpose of the 'jump_zero' and 'getelementofarray' script commands. - Fixed 'changebase' stating, that it only works in item scripts (since r2402). - Fixed 'kickwaitingroomall' stating, that it is not properly linked into the script engine, thus not working (since r13732). - Updated the description for 'cutin' so that it does not give the impression, that the client is able to display multiple illustrations at once, and being less confusing about the maximum size of illustrations. git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@14570 54d463be-8e91-2dee-dedb-b68131a5f0ec --- doc/script_commands.txt | 266 +++++++++++++++++++++++------------------------- 1 file changed, 127 insertions(+), 139 deletions(-) (limited to 'doc') diff --git a/doc/script_commands.txt b/doc/script_commands.txt index b2594ddd2..b3a4ff35d 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -4,7 +4,7 @@ //= A reference manual for the eAthena scripting language. //= Commands are sorted depending on their functionality. //===== Version =========================================== -//= 3.28.20091119 +//= 3.32.20101208 //========================================================= //= 1.0 - First release, filled will as much info as I could //= remember or figure out, most likely there are errors, @@ -143,6 +143,11 @@ //= 'mercenary_get_faith' and 'mercenary_set_faith' commands. [Ai4rei] //= 3.31.20101130 //= Added 'progressbar' command. [Ai4rei] +//= 3.32.20101208 +//= Updated description for commands 'next', 'return', 'attachrid', +//= 'detachrid', 'itemskill', 'openstorage', 'skilleffect', 'donpcevent', +//= 'day', 'night', 'atoi', 'axtoi', 'jump_zero', 'getelementofarray', +//= 'changebase', 'kickwaitingroomall', 'cutin' and 'charcommand'. [Ai4rei] //========================================================= This document is a reference manual for all the scripting commands and functions @@ -1114,9 +1119,14 @@ either side solves the problem. *next; -This command will create a 'next' button in the message window for the invoking -character. If no window is currently on screen, it will be created. Used to -segment NPC talking, this command is used A LOT. See 'mes'. +This command will display a 'next' button in the message window for the +invoking character. Clicking on it will cause the window to clear and display +a new one. Used to segment NPC-talking, next is often used in combination with +'mes' and 'close'. + +If no window is currently on screen, one will be created, but once the invoking +character clicks on it, a warning is thrown on the server console and the script +will terminate. mes "[Woman]"; mes "This would appear on the page"; @@ -1653,9 +1663,13 @@ in the previous example getarg(2,-1) would be 3 and getarg(3,-1) would be -1 *return {}; -When you use callsub or callfunc, this command allows you to go back to the -calling script. You can optionally return with a value telling the calling -program what exactly happened. +This command causes the script execution to leave previously called function +with callfunc or script with callsub and return to the location, where the call +originated from. Optionally a return value can be supplied, when the call was +done using the function form. + +Using this command outside of functions or scripts referenced by callsub will +result in error and termination of the script. callfunc "";// when nothing is returned set ,callfunc("");// when a value is being returned @@ -1909,10 +1923,12 @@ else if () This command works kinda 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'. +the specified label like in 'goto'. While 'if' is more generally useful, for +some cases this could be an optimization. -While 'if' is more generally useful, for some cases this could be an -optimisation. +The main reason for this command is that other control statements, like +'switch', 'for' or 'while', are disassembled into simple expressions together +with this command when a script is parsed. --------------------------------------- @@ -2145,16 +2161,13 @@ This will make @arraysize == 6. But if you try this: *getelementofarray(,) -This function will return an array's element when given an index. - - // This will find the 2nd array value - getelementofarray(@array,1) - -Pretty pointless now when we have +This command retrieves the value of the element of given array at given index. +This is equivalent to using: - @array[1] + array[index] -which has the same effect. +The reason for this is, that this short form is internally converted into a call +to getelementofarray, when the script is loaded. --------------------------------------- @@ -3527,18 +3540,13 @@ For a list of equipment slots see 'getequipid'. *attachrid() *detachrid; -A 'RID' is an ID of a character who caused the NPC script to run, as has been -explained above in the introduction section. Quite a bit of commands want a RID -to work, since they wouldn't know where to send information otherwise. And in -quite a few cases the script gets invoked with a RID of zero (like through -OnTime special labels). If an NPC script needs this, it can attach a specified -character's id to itself. by calling the 'attachrid' function. +These commands allow the manipulation of the script's currently attached player. +While attachrid allows attaching of a different player by using it's account id +for the parameter rid, detachrid makes the following commands run, as if the +script was never invoked by a player. -'attachrid' returns 1 if the character was found online and 0 if it wasn't. - -This could also be used, while running in a script invoked by a character -through talking to an NPC, to mess with other characters. -Detaching the RID will make the RID of the script zero. +In case, that the player cannot be attached, such as, when the player went +offline in the mean time, attachrid returns 0, otherwise 1. --------------------------------------- @@ -3836,8 +3844,6 @@ It would be entered in the equip bonus section of an item 2338,Wedding_Dress,Wedding Dress,5,43000,,500,,0,,0,119529470,7,0,16,,0,1,0,{ bonus bMdef,15; changebase 22; } -This command only works when inside item scripts. - --------------------------------------- *classchange ,; @@ -4279,14 +4285,13 @@ effect is still in effect). *itemskill ,; *itemskill "",; -This is a command meant for item scripts to replicate single-use skills. It will -not work properly in NPC scripts a lot of the time because casting a skill is -not allowed when there is a message window or menu on screen. If there isn't one -cause you've made sure to run this when they already closed it, it should work -just fine and even show a targeting pointer if this is a targeting skill. +This command meant for item scripts to replicate single-use skills in usable +items. It will not work properly, if there is a visible dialog window or menu. +If the skill is self or auto-targeting, it will be used immediately otherwise a +target cursor is shown. -// When you use Anodyne, you will cast Endure(8) level 1, -// and "Endure" will appear above your head as you use it. +// When Anodyne is used, it will cast Endure (8), Level 1, as if the actual +// skill has been used from skill tree. 605,Anodyne,Anodyne,11,2000,0,100,,,,,10477567,2,,,,,{ itemskill 8,1; },{} @@ -4424,14 +4429,13 @@ Example(s): *openstorage; -This will open a character's Kafra storage window on the client connected to the -invoking character. It does not check wherever it is run from, so you can allow -any feasible NPC to open a kafra storage. (It's not certain whether this works -in item scripts, but if it does, it could be interesting.) +This will open character's Kafra storage window on the client connected to the +invoking character. It can be used from any kind of NPC or item script, not just +limited to Kafra Staff. -The storage window might not open if a message box or a trade deal is present on -screen already, so you should at least make sure the message box is closed -before you open storage. +The storage window opens regardless of whether there are open NPC dialogs or +not, but it is preferred to close the dialog before displaying the storage +window, to avoid any disruption when both windows overlap. mes "I will now open your stash for you"; close2; @@ -4626,23 +4630,26 @@ should be rather obvious. *skilleffect ,; *skilleffect "",; -This command will display the visual and sound effects of a specified skill (see -'db/skill_db.txt' for a full list of skills) on the invoking character's sprite. -Nothing but the special effects and animation will happen. If the skill's normal -effect displays a floating number, the number given will float up. +This command displays visual and aural effects of given skill on currently +attached character. The number parameter is for skill whose visual effect +involves displaying of a number (healing or damaging). Note, that this command +will not actually use the skill, it is intended for scripts, which simulate +skill usage by the NPC, such as buffs, by setting appropriate status and +displaying the skill's effect. - // This will heal the character with 2000 hp, buff with - // Bless 10 and Increase AGI 5, and display appropriate - // effects. - mes "Blessed be!"; - skilleffect 28,2000; + mes "Be blessed!"; + // Heal of 2000 HP heal 2000,0; - skilleffect 34,0; - // That's bless 10. + skilleffect 28,2000; + // Blessing Level 10 sc_start 10,240000,10; - skilleffect 29,0; - // That's agi 5 + skilleffect 34,0; + // Increase AGI Level 5 sc_start 12,140000,5; + skilleffect 29,0; + +This will heal the character with 2000 HP, buff it with Blessing Lv 10 and +Increase AGI Lv 5, and display appropriate effects. --------------------------------------- @@ -5205,21 +5212,16 @@ invoked by the RID that was active in the script that issued a 'doevent'. *donpcevent "{NPC NAME}::"; -This command is kinda confusing cause it performs in two completely different -ways. - -If the event label is phrased like "::