From d58ab3d97beb5c495bc7a82c4fa71f444ba67b72 Mon Sep 17 00:00:00 2001 From: Haru Date: Sun, 21 Aug 2016 17:14:53 +0200 Subject: Syntax clean up in the script documentation - Changed all function calls to encourage parenthesized calls - Replaced numbers with constants where appropriate - Removed some incorrect remarks Signed-off-by: Haru --- doc/script_commands.txt | 3332 ++++++++++++++++++++++++----------------------- 1 file changed, 1680 insertions(+), 1652 deletions(-) diff --git a/doc/script_commands.txt b/doc/script_commands.txt index e1f68916e..204723905 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -57,7 +57,7 @@ you didn't, get used to it, that's how big boys do it. If a command can optionally take an unspecified number of arguments, you'll see a list like this: -command {,...} +command({, ...}) This still means they will want to be separated by commas. @@ -386,7 +386,7 @@ Unless you use 'attachrid' to explicitly attach a character to the script first (see player-related commands). Whenever we say 'invoking character', we mean 'the character who's RID is -attached to the running script. The script function "playerattached" can +attached to the running script. The script function playerattached() can be used to check which is the currently attached player to the script (it will return 0 if the there is no player attached or the attached player no longer is logged on to the map-server). @@ -395,8 +395,8 @@ But what about GID? --- ---- ----- ---- GID stands for the Game ID of something, this can either be the GID of a -mob obtained through the monster script command (if only summoned one), -the GID of a NPC obtained through the getnpcid script command or the +mob obtained through the monster() script command (if only summoned one), +the GID of a NPC obtained through the getnpcid() script command or the account ID of a character (same as its RID). Another way would be to right click on a mob, NPC or char as GM sprited char to view its GID. @@ -487,7 +487,7 @@ nothing - A permanent variable attached to the character, the default ".@" - A scope variable. They are unique to the character, script and scope. Each script execution has its own scope that ends when the script ends. - Calling a function with callsub/callfunc starts a new scope, + Calling a function with callsub()/callfunc() starts a new scope, returning from the function ends it. When a scope ends, its variables are converted to values ('return .@var;' returns a value, not a reference). @@ -750,10 +750,10 @@ other, but you can not compare numbers to strings. < - 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 + 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 + first value. Both values must be strings. See script function pcre_match() for more details and advanced features. Examples: @@ -787,12 +787,12 @@ Logical bitwise operators work only on numbers, and they are the following: Example: b = 2; a = b << 3; - mes a; + mes(a); a = a >> 2; - mes a; - The first mes command would display 16, which is the same as: + mes(a); + The first mes() command would display 16, which is the same as: 2 x (2 x 2 x 2) = 16. - The second mes command would display 4, which is the same as: + The second mes() command would display 4, which is the same as: 16 / 2 = 8; 8 / 2 = 4. & - And. | - Or. @@ -824,13 +824,18 @@ Logical bitwise operators work only on numbers, and they are the following: active (1) in both. Resulting in the bit 0010, which is 2. - Basic example of creating and using a bit-mask: .@options = 2|4|16; // (note: this is the same as 2+4+16, or 22) - if (.@options & 1) mes "Option 1 is activated"; - if (.@options & 2) mes "Option 2 is activated"; - if (.@options & 4) mes "Option 3 is activated"; - if (.@options & 8) mes "Option 4 is activated"; - if (.@options & 16) mes "Option 5 is activated"; - 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). + if (.@options & 1) + mes("Option 1 is activated"); + if (.@options & 2) + mes("Option 2 is activated"); + if (.@options & 4) + mes("Option 3 is activated"); + if (.@options & 8) + mes("Option 4 is activated"); + if (.@options & 16) + mes("Option 5 is activated"); + This would print the messages about option 2, 3 and 5 (since we've set + the 2,4 and 16 bit to 1). ^ - Xor. The bitwise operator XOR (eXclusive OR) sets a binary position to 0 if both numbers have the same value in the said position. On the other @@ -842,19 +847,19 @@ Logical bitwise operators work only on numbers, and they are the following: - First let's set the quests that are currently in progress: 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 ){ + if (inProgress&2 == 0) { // this will set the bit for quest 2 (inProgress has that bit set to 0) inProgress = inProgress^2; - mes "Quest 2: find a newbie and be helpful to him for an hour."; - close; + mes("Quest 2: find a newbie and be helpful to him for an hour."); + close(); } - After spending some time reading info on Xor's, the player finally completes quest 1: - if( inProgress&1 && isComplete ) { + if (inProgress&1 && isComplete) { // this will unset the bit for quest 1 (inProgress has that bit set to 1) inProgress = inProgress^1; - mes "Quest 1 complete!! You unlocked the secrets of the Xor dynasty, use them wisely."; - close; + mes("Quest 1 complete!! You unlocked the secrets of the Xor dynasty, use them wisely."); + close(); } Unary operators with only with a single number, which follows the @@ -866,16 +871,16 @@ operator, and are the following: Example: .@myvar = 10; - mes "Negative 10 is "+(-.@myvar); + mes("Negative 10 is "+(-.@myvar)); ! - Logical Not. - Reverses the boolean result of an expression. True will become false - and false will become true. + Reverses the boolean result of an expression. True will become false + and false will become true. Example: - if(!callfunc("F_dosomething")) { - mes "Doing something failed."; - close; + if (!callfunc("F_dosomething")) { + mes("Doing something failed."); + close(); } ~ - Bitwise Not. @@ -886,7 +891,7 @@ operator, and are the following: - Ensure, that quest 2 is disabled, while keeping all other active, if they are. inProgress = inProgress&(~2); - // same as set inProgress,inProgress&0xfffffffd + // same as set inProgress, inProgress&0xfffffffd Ternary operators take three expressions (numbers, strings or boolean), and are the following: @@ -895,13 +900,13 @@ and are the following: Very useful e.g. to replace if (Sex == SEX_MALE) - mes "You're Male."; + mes("You're Male."); else - mes "You're Female."; + mes("You're Female."); clauses with simple - mes "Welcome, " + (Sex == SEX_MALE ? "Mr." : "Mrs.") + " " + strcharinfo(0); + mes("Welcome, " + (Sex == SEX_MALE ? "Mr." : "Mrs.") + " " + strcharinfo(PC_NAME)); or to replace any other simple if-else clauses. It might be worth mentioning that ?: has low priority and has to be enclosed with @@ -1000,8 +1005,8 @@ OnDay: This will execute when the server clock hits the specified date or time. Hours and minutes are given in military time. ('0105' will mean 01:05 AM). -Weekdays are Sun,Mon,Tue,Wed,Thu,Fri,Sat. Months are 01 to 12, days are 01 -to 31. Remember the zero. :) +Weekdays are Sun, Mon, Tue, Wed, Thu, Fri, Sat. Months are 01 to 12, days are +01 to 31. Remember the zero. :) OnInit: OnInterIfInit: @@ -1099,8 +1104,8 @@ OnCountFunds: This special label is triggered when a player opens a trader NPC object that is NST_CUSTOM. It is used to define different currency types to the trader via -*setcurrency. Should be used along with OnPayFunds, see /doc/sample/npc_trader_sample.txt -for more information. +setcurrency(). Should be used along with OnPayFunds, see +doc/sample/npc_trader_sample.txt for more information. OnPayFunds: @@ -1119,14 +1124,14 @@ must be started with "On". Example: -monster "prontera",123,42,"Poringz0rd",2341,23,"Master::OnThisMobDeath"; +monster("prontera", 123, 42, "Poringz0rd", 2341, 23, "Master::OnThisMobDeath"); amatsu,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; + announce("Hey, "+strcharinfo(PC_NAME)+" just killed a Poringz0rd!", bc_blue|bc_all); end; } @@ -1134,12 +1139,12 @@ Each time you kill one, that announce will appear in blue to everyone. "Global" labels -There's a catch with labels and doevent. If you call a label (using -doevent) and called label is in NPC that has trigger area, that label must -end with "Global" to work globally (i.e. if RID is outside of the trigger -area, which usually happens since otherwise there would be no point -calling the label with doevent, because OnTouch would do the job). For -further reference look for npc_event in npc.c. +There's a catch with labels and doevent(). If you call a label (using +doevent()) and called label is in NPC that has trigger area, that label must +end with "Global" to work globally (i.e. if RID is outside of the trigger area, +which usually happens since otherwise there would be no point calling the label +with doevent(), because OnTouch would do the job). For further reference look +for npc_event in npc.c. Scripting commands and functions -------------------------------- @@ -1147,16 +1152,11 @@ Scripting commands and functions The commands and functions are listed here in no particular order. There's a difference between commands and functions - commands leave no 'return value' which might be used in a conditional statement, as a command -argument, or stored in a variable. Calling commands as if they were -functions will sometimes work, but is not advised, as this can lead to -some hard to track errors. Calling functions as if they were commands will -mess up the stack, so 'return' command will not return correctly after -this happens in a particular script. +argument, or stored in a variable. -All commands must end with a ';'. Actually, you may expect to have -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. +All instructions must end with a ';'. Actually, you may expect to have multiple +instructions on one line if you properly terminate them with a ';', but it's +consider ill practice, since it impairs legibility of the script. Please note that command and function names are case sensitive. @@ -1193,7 +1193,7 @@ From here on, we will have the commands sorted as followed: //===================================== --------------------------------------- -*mes ""; +*mes("") This command will displays a box on the screen for the invoking character, if no such box is displayed already, and will print the string specified @@ -1202,7 +1202,7 @@ unless you create one with 'close' or 'next', and while it's open the player can't do much else, so it's important to create a button later. If the string is empty, it will show up as an empty line. - mes "Text that will appear in the box"; + mes("Text that will appear in the box"); Inside the string you may put color codes, which will alter the color of the text printed after them. The color codes are all '^' and @@ -1213,13 +1213,13 @@ a color that is considered transparent whenever the client is drawing windows on screen, so printing text in that color will have kind of a weird effect. You may also use C_ constants accompany with "F_MesColor" function for the color effect, see the full list of the available ones -in 'db/constants.conf' -under 'C_'. Once you've set a text's color to something, you have to set -it back to black unless you want all the rest of the text be in that color: +in 'db/constants.conf' under 'C_'. Once you've set a text's color to something, +you have to set it back to black unless you want all the rest of the text be in +that color: + + mes("This is ^FF0000 red ^000000 and this is ^00FF00 green, ^000000 so."); + mes(callfunc("F_MesColor", C_BLUE) +"This message is now in BLUE"); - mes "This is ^FF0000 red ^000000 and this is ^00FF00 green, ^000000 so."; - mes callfunc("F_MesColor", C_BLUE) +"This message is now in BLUE"; - Notice that the text coloring is handled purely by the client. If you use non-English characters, the color codes might get screwed if they stick to letters with no intervening space. Separating them with spaces from the @@ -1229,18 +1229,18 @@ If you're using a client from 2011-10-10aRagexe.exe onwards, you can also use automatic navigation and open URLs in browser by using some HTML-like labels. For example: - mes "go to [Hat Maker]izlude,131,148, to make hats"; + mes("go to [Hat Maker]izlude,131,148, to make hats"); Will make the [Hat Maker] text clickable in the client and start a navigation to that point. - mes "You can Googlehttp://www.google.com/ anything"; + mes("You can Googlehttp://www.google.com/ anything"); Clicking Google will open the browser and point to Google website. --------------------------------------- -*mesf(""{,{, {, ...}}}) +*mesf(""{, {, {, ...}}}) This command will display a box on the screen for the invoking character, if no such box is displayed already, and will print the string specified @@ -1257,27 +1257,26 @@ for more details. --------------------------------------- -*next; +*next() 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'. +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"; - next; - // This is needed since it is a new page and the top will now be blank - mes "[Woman]"; - mes "This would appear on the 2nd page"; + mes("[Woman]"); + mes("This would appear on the page"); + next(); + mes("[Woman]"); // This is needed since it is a new page and the top will now be blank + mes("This would appear on the 2nd page"); --------------------------------------- -*close; +*close() This command will create a 'close' button in the message window for the invoking character. If no window is currently on screen, the script @@ -1285,14 +1284,14 @@ command 'end;' must be used. This is one of the ways to end a speech from an NPC. Once the button is clicked, the NPC script execution will end, and the message box will disappear. - mes "[Woman]"; - mes "I am finished talking to you, click the close button."; - close; - mes "This command will not run at all, since the script has ended."; + mes("[Woman]"); + mes("I am finished talking to you, click the close button."); + close(); + mes("This command will not run at all, since the script has ended."); --------------------------------------- -*close2; +*close2() This command will create a 'close' button in the message window for the invoking character. WARNING: If no window is currently on screen, the @@ -1302,35 +1301,36 @@ closed, the script execution will not stop, and commands after 'close2' will still run, meaning an 'end' has to be used to stop the script, unless you make it stop in some other manner. - mes "[Woman]"; - mes "I will warp you now."; - close2; - warp "place",50,50; + mes("[Woman]"); + mes("I will warp you now."); + close2(); + warp("place", 50, 50); end; - + Don't expect things to run smoothly if you don't make your scripts 'end'. --------------------------------------- -*end; +*end -This command will stop the execution for this particular script. -It is required for any script not using 'mes'. +This instruction will stop the execution for this particular script. +Note that this is to be considered a special instruction (not a regular +command or function), and as such doesn't require parentheses. if (BaseLevel <= 10) { - npctalk "Look at that you are still a n00b"; + npctalk("Look at that you are still a n00b"); end; } if (BaseLevel <= 20) { - npctalk "Look at that you are getting better, but still a n00b"; + npctalk("Look at that you are getting better, but still a n00b"); end; } if (BaseLevel <= 30) { - npctalk "Look at that you are getting there, you are almost 2nd profession now right???"; + npctalk("Look at that you are getting there, you are almost 2nd profession now right???"); end; } if (BaseLevel <= 40) { - npctalk "Look at that you are almost 2nd profession"; + npctalk("Look at that you are almost 2nd profession"); end; } @@ -1340,8 +1340,7 @@ lines, the use of 'end' stops this, and ends the script. --------------------------------------- -*set ,; -*set(,) +*set(, ) This command will set a variable to the value that the expression results in. This isn't the only way to set a variable directly: you can set them @@ -1349,83 +1348,83 @@ much like any other programming language as stated before (refer to the 'Assigning variables' section). This command is deprecated and it shouldn't be used in new scripts, except -some special cases (mostly, set getvariableofnpc). Use direct value +some special cases (mostly, set(getvariableofnpc(), )). Use direct value assignment instead. --------------------------------------- -*setd "",; +*setd("", ) -Works almost identically as set, except the variable name is identified as -a string and can thus be constructed dynamically. +Works almost identically as set(), except the variable name is +identified as a string and can thus be constructed dynamically. This command is equivalent to: - set getd("variable name"),; + set(getd("variable name"), ); Examples: - setd ".@var$", "Poporing"; - mes .@var$; // Displays "Poporing". + setd(".@var$", "Poporing"); + mes(.@var$); // Displays "Poporing". - setd ".@" + .@var$ + "123$", "Poporing is cool"; - mes .@Poporing123$; // Displays "Poporing is cool". + setd(".@" + .@var$ + "123$", "Poporing is cool"); + mes(.@Poporing123$); // Displays "Poporing is cool". --------------------------------------- *getd("") Returns a reference to a variable, the name can be constructed dynamically. -Refer to 'setd' for usage. +Refer to setd() for usage. This can also be used to set an array dynamically: - setarray getd(".array[0]"), 1, 2, 3, 4, 5; + setarray(getd(".array[0]"), 1, 2, 3, 4, 5); Examples: - mes "The value of $varReference is: " + getd("$varRefence"); - set .@i, getd("$" + "pikachu"); + mes("The value of $varReference is: " + getd("$varRefence")); + set(.@i, getd("$" + "pikachu")); --------------------------------------- -*getvariableofnpc(,"") +*getvariableofnpc(, "") Returns a reference to a NPC variable (. prefix) from the target NPC. This can only be used to get . variables. Examples: -//This will return the value of .var, note that this can't be used, since +//This will return the value of .var, note that this can't be used, since //the value isn't caught. - getvariableofnpc(.var,"TargetNPC"); + getvariableofnpc(.var, "TargetNPC"); -//This will set the .v variable to the value of the TargetNPC's .var +//This will set the .@v variable to the value of the TargetNPC's .var //variable. - .v = getvariableofnpc(.var,"TargetNPC"); + .@v = getvariableofnpc(.var, "TargetNPC"); //This will set the .var variable of TargetNPC to 1. - set getvariableofnpc(.var,"TargetNPC"), 1; + set(getvariableofnpc(.var, "TargetNPC"), 1); -Note: even though function objects can have .variables, getvariableofnpc -will not work on them. +Note: even though function objects can have .variables, +getvariableofnpc() should not be used on them. --------------------------------------- -*goto