From a2edaef3d051fbb3d3b642cf5b01a3fbfc3cfa18 Mon Sep 17 00:00:00 2001 From: FlavioJS Date: Fri, 9 Feb 2007 19:57:20 +0000 Subject: - Corrected/updated info on Xor/setd/getd/callfunc/callsub/return and updated some examples to use "better" code. git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@9838 54d463be-8e91-2dee-dedb-b68131a5f0ec --- doc/script_commands.txt | 377 ++++++++++++++++++++++++------------------------ 1 file changed, 189 insertions(+), 188 deletions(-) diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 9a8499b88..549fbb729 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -9,7 +9,7 @@ //= Maeki Rika - A section on general concepts and lots of //= other updates and additions. //===== Version =========================================== -//= 3.00.20070208 +//= 3.02.20070209 //========================================================= //= 1.0 - First release, filled will as much info as I could //= remember or figure out, most likely there are errors, @@ -56,6 +56,9 @@ //= 3.01.20070209 //= Updated 'cutin' (removed lies, removed outdated bmp list) [ultramage] //= Removed 'cutincard' since eA no longer implements it +//= 3.02.20070209 +//= Corrected/updated info on Xor/setd/getd/callfunc/callsub/return and +//= updated some examples to use "better" code. [FlavioJS] //===== Compatible With =================================== //= LOL, can be used by anyone hopefully //===== Description ======================================= @@ -644,6 +647,13 @@ Resume of the allowed variable and array scopes |.@Int | OK! | OK! | +----------+------+-------+ +Variable References +------------------- + +//##TODO + + + Operators --------- @@ -677,7 +687,7 @@ you can not compare numbers to strings. Examples: - 1=1 is True. + 1==1 is True. 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. @@ -688,18 +698,18 @@ strings by alphabet would be pointless anyway. Comparisons can be stacked in the same condition: && - Is True if and only if BOTH sides are true. - ('1==1 && 2=2' is true. '2=1 && 1=1' is false.) + ('1==1 && 2==2' is true. '2==1 && 1==1' is false.) || - Is True if either side of this expression is True. - 1=1 && 2=2 is True. - 1=1 && 2=1 is False. - 1=1 || 2=1 is True. + 1==1 && 2==2 is True. + 1==1 && 2==1 is False. + 1==1 || 2==1 is True. Logical bitwise operators work only on numbers, and they are the following: << - Left shift. >> - Right shift. - Left shift moves the binary 1(s) of a number n positions to the left, + Left shift moves the binary 1(s) of a number n positions to the left, which is the same as multiplying by 2, n times. In the other hand, Right shift moves the binary 1(s) of a number n positions to the right, which is the same as dividing by 2, n times. @@ -747,19 +757,28 @@ Logical bitwise operators work only on numbers, and they are the following: This would return the messages about option 2, 3 and 5 being shown (since we've set the 2,4 and 16 bit to 1). ^ - Xor. - The bitwise operator XOR (eXclusive OR) sets to 0 a binary position if both numbers have a 1 - in the said position. On the other hand, it sets to 1 if there's a 1 in any of the number in - the said binary position. - This is the counter-part of the OR operator, the opposite if you like. This is used to remove a - bitmask, which is the same as substracting it. + The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if both + numbers have the same value in the said position. On the other hand, it + sets to 1 if they have different values in the said binary position. + This is another way of setting and unsetting bits in bitmasks. Example: - - We set the variable first: - set a,2|4|8|16; // this would be the same as 2+4+8+16 = 30 - - After some checks, we find he didn't do the third quest, which we asigned the 3rd value (8) - so now we have to remove it: - set a,a^8; //this would be the same as 30-8 = 22. 22 = 16+4+2, which are the flags left. - + - First let's set the quests that are currently in progress: + set inProgress,1|8|16; // quest 1,8 and 16 are in progress + - After playing for a bit, the player starts another quest: + if( inProgress&2 == 0 ){ + // this will set the bit for quest 2 (inProgress has that bit set to 0) + set inProgress,inProgress^2; + mes "Quest 2: find a newbie and be helpfull to him for an hour."; + close; + } + - After spending some time reading info on Xor's, the player finally completes quest 1: + if( inProgress&1 && isComplete ){ + // this will unset the bit for quest 1 (inProgress has that bit set to 1) + set inProgress,inProgress^1; + mes "Quest 1 complete!! You unlocked the secrets of the Xor dinasty, use them wisely."; + close; + } Labels ------ @@ -849,9 +868,8 @@ Example: monster "prontera.gat",123,42,"Poringz0rd",2341,23,"Master::OnThisMobDeath"; amatsu.gat,13,152,4 script Master 767,{ - -mes "Hi there"; -close; + mes "Hi there"; + close; OnThisMobDeath: announce "Hey, "+strcharinfo(0)+" just killed a Poringz0rd!",bc_blue|bc_all; @@ -1008,7 +1026,7 @@ of 'end' stops this, and ends the script. This command will set a variable to the value that the expression results in. This is the only way to set a variable directly. -This is the most basic script command and is uses a lot whenever you try to do +This is the most basic script command and is used a lot whenever you try to do anything more advanced than just printing text into a messagebox. set @x,100; @@ -1022,10 +1040,12 @@ integer in this language) and make @x equal it. --------------------------------------- -*setd "variable name",; +*setd "",; Works almost identical as set, just that the variable name is identified as a string, thus can be constructed dynamically. +This command is equivalent to: +set getd("variable name"),; Example: set $var$, "Poring"; @@ -1040,23 +1060,29 @@ mes $Poporing123$; // Will return Poporing is cool. *getd("") -Retrieves variable, name can be constructed dynamically. Refer to setd for usage. +Returns a reference to a variable, the name can be constructed dynamically. +Refer to setd for usage. Example: +set getd("$varRefence"), 1; set @i, getd("$pikachu"); --------------------------------------- -*getvariableofnpc ,; +*getvariableofnpc(,"") -Enables you to get a NPC variable (. prefix) from the given NPC. This can only be used to get . variables. +Returns a reference to a NPC variable (. prefix) from the target NPC. +This can only be used to get . variables. Example(s): -//This will return the value or .var, note that this can't be used, since the value isn't catched. - getvariableofnpc .var,"A NPC"; +//This will return the value of .var, note that this can't be used, since the value isn't catched. + getvariableofnpc(.var,"TargetNPC"); -//This will set the .v variable to the value of the A NPC's .var variable. - set .v,getvariableofnpc(.var,"A NPC"); +//This will set the .v variable to the value of the TargetNPC's .var variable. + set .v,getvariableofnpc(.var,"TargetNPC"); + +//This will set the .var variable of TargetNPC to 1. + set getvariableofnpc(.var,"TargetNPC"),1; --------------------------------------- @@ -1065,11 +1091,13 @@ Example(s): This command will make the script jump to a label, usually used in conjunction with other command, such as "if", but often used on it's own. - ... - goto Label; - mes "This will not be seen"; - Label: - mes "This will be seen"; + ... + goto Label; + mes "This will not be seen"; +Label: + mes "This will be seen"; + +Note by FlavioJS: goto's are "evil" and should be avoided if possible (ò_ó) --------------------------------------- @@ -1115,37 +1143,35 @@ with the strings that should go into the menu at this execution, making sure not to leave any gaps. Normally, you do it with a loop and an extra counter, like this: - setarray @possiblemenuitems$[0],; - set @i,0; // That's our loop counter. - set @j,0; // That's the menu lines counter. - - makemenuloop: - - // We record the number of option into the list of options actually - // available. That 'condition' is whatever condition that determines whether - // a menu item number @i actually goes into the menu or not. - - if () set @menulist$[@j],@possiblemenuitems$[@i]; - - // We just copied the string, we do need it's number for later though, so we - // file it away as well. - - if () set @menureference[@j],@i; - - // Since we've just added a menu item into the list, we increment the menu - // lines counter. - - if () set @j,@j+1; - - // We go on to the next possible menu item. - - set @i,@i+1; - - // And continue looping through the list of possible menu items until it - // ends. - - if (@i<=getarraysize(@possiblemenuitems)) goto makemenuloop; - + setarray @possiblemenuitems$[0],; + set @j,0; // That's the menu lines counter. + + // We loop through the list of possible menu items. + // @i is our loop counter. + for( set @i,0; @i) + { + // We record the option into the list of options actually available. + + set @menulist$[@j],@possiblemenuitems$[@i]; + + // We just copied the string, we do need it's number for later + // though, so we record it as well. + + set @menureference[@j],@i; + + // Since we've just added a menu item into the list, we increment + // the menu lines counter. + + set @j,@j+1; + } + + // We go on to the next possible menu item. + } This will create you an array @menulist$ which contains the text of all items that should actually go into the menu based on your condition, and an array @@ -1153,10 +1179,10 @@ that should actually go into the menu based on your condition, and an array (Remember, arrays start with 0.) There's less of them than the possible menu items you've defined, but the menu command can handle the empty lines - only if they are last in the list, and if it's made this way, they are. Now comes a - - // X is whatever the most menu items you expect to handle. dirty trick: - menu @menulist$[0],-,@menulist$[1],-,....@menulist$[],-; + + // X is whatever the most menu items you expect to handle. + menu @menulist$[0],-,@menulist$[1],-,....@menulist$[],-; This calls up a menu of all your items. Since you didn't copy some of the possible menu items into the list, it's end is empty and so no menu items will @@ -1229,36 +1255,44 @@ invoking character, to allow entering of a number or a string. This has many uses, one example would be a guessing game, also making use of the 'rand' function: - mes "[Woman]"; - mes "Try and guess the number I am thinking of."; - mes "The number will be between 1 and 10."; - next; - set @number, rand(1,10); - input @guess; - if(@guess==@number) goto L_Correct; - mes "[Woman]"; - mes "Sorry, that wasn't the number I was thinking of."; - close; - L_Correct: - mes "[Woman]"; - mes "Well done that was the number I was thinking of"; - close; + mes "[Woman]"; + mes "Try and guess the number I am thinking of."; + mes "The number will be between 1 and 10."; + next; + set @number, rand(1,10); + input @guess; + if(@guess==@number) + { + mes "[Woman]"; + mes "Well done that was the number I was thinking of"; + close; + } + else + { + mes "[Woman]"; + mes "Sorry, that wasn't the number I was thinking of."; + close; + } If you give the input command a string variable to put the input in, it will allow the player to enter text. Otherwise, only numbers will be allowed. - mes "[Woman]"; - mes "Please say HELLO"; - next; - input @var$; - if(@var$=="HELLO") goto L_Correct; - mes "[Woman]"; - mes "Sorry you got it wrong"; - close; - L_Correct: - mes "[Woman]"; - mes "Well done you typed it correctly"; - close; + mes "[Woman]"; + mes "Please say HELLO"; + next; + input @var$; + if(@var$=="HELLO") + { + mes "[Woman]"; + mes "Well done you typed it correctly"; + close; + } + else + { + mes "[Woman]"; + mes "Sorry you got it wrong"; + close; + } Notice that in current SVN, you may not input a negative number with this command. This was done to prevent exploits in badly written scripts, which would @@ -1275,19 +1309,19 @@ This command lets you call up a function NPC. A function NPC can be called from any script on any map server. Using the 'return' command it will come back to the place that called it. - place.gat,50,50,6%TAB%script%TAB%Woman%TAB%115,{ - mes "[Woman]" - mes "Lets see if you win"; - callfunc "funcNPC"; - mes "Well done you have won"; - close; - } - function%TAB%script%TAB%funcNPC%TAB%{ - set @win, rand(2); - if(@win==0) return; - mes "Sorry you lost"; - end; - } + place.gat,50,50,6%TAB%script%TAB%Woman%TAB%115,{ + mes "[Woman]" + mes "Lets see if you win"; + callfunc "funcNPC"; + mes "Well done you have won"; + close; + } + function%TAB%script%TAB%funcNPC%TAB%{ + set @win, rand(2); + if(@win==0) return; + mes "Sorry you lost"; + end; + } You can pass arguments to your function - values telling it what exactly to do - which will be available there with getarg() (see 'getarg') @@ -1297,24 +1331,22 @@ If you want to return a real value from inside your function NPC, it is better to write it in the function form, which will also work and will make the script generally cleaner: - place.gat,50,50,6%TAB%script%TAB%Man%TAB%115,{ - mes "[Man]" - mes "Gimme a number!"; - next; - input @number; - if (callfunc("OddFunc",@number)) mes "It's Odd!"; - close; - } - function%TAB%script%TAB%OddFunc%TAB%{ - if (getarg(0)%2==0) goto ItsEven; - return (1); - ItsEven: - return (0); - } + place.gat,50,50,6%TAB%script%TAB%Man%TAB%115,{ + mes "[Man]" + mes "Gimme a number!"; + next; + input @number; + if (callfunc("OddFunc",@number)) mes "It's Odd!"; + close; + } + function%TAB%script%TAB%OddFunc%TAB%{ + if (getarg(0)%2==0) return 0;// it's even + return 1;// it's odd + } --------------------------------------- -*callsub