diff options
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 119 |
1 files changed, 87 insertions, 32 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 05d075ac1..097cae665 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -1188,7 +1188,7 @@ From here on, we will have the commands sorted as followed: //===================================== --------------------------------------- -*mes "<string>"{,"<string>"..."<string>"}; +*mes "<string>"; 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 @@ -1220,14 +1220,6 @@ non-English characters, the color codes might get screwed if they stick to letters with no intervening space. Separating them with spaces from the letters on either side solves the problem. -To display multiple lines of message while only using a single mes; -command, use the script command in the following format: - - mes "Line 1", "Line 2", "Line 3"; - -This will display 3 different lines while only consuming a single line in -the relevant script file. - 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: @@ -1243,6 +1235,23 @@ Clicking Google will open the browser and point to Google website. --------------------------------------- +*mesf("<format>"{,<param>{, <param>{, ...}}}) + +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 +into that box, after applying the same format-string replacements as sprintf(). + +Example: + + mesf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class)); + // is equivalent to: + mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); + +This command is a combination of mes() and sprintf(). See their documentation +for more details. + +--------------------------------------- + *next; This command will display a 'next' button in the message window for the @@ -3035,25 +3044,6 @@ the function is called. This function is intended for use in item scripts. --------------------------------------- -*getnameditem(<item id>,"<name to inscribe>"); -*getnameditem("<item name>","<name to inscribe>"); - -This function is equivalent to using 'getitem', however, it will not just -give the character an item object, but will also inscribe it with a -specified character's name. You may not inscribe items with arbitrary -strings, only with names of characters that actually exist. While this -isn't said anywhere specifically, apparently, named items may not have -cards in them, slots or no - these data slots are taken by the character -ID who's name is inscribed. Only one remains free and it's not quite clear -if a card may be there. - -This function will return 1 if an item was successfully created and 0 if -it wasn't for whatever reason. Like 'getitem', this function will also -accept an 'english name' from the item database as an item name and will -return 0 if no such item exists. - ---------------------------------------- - *getitemslots(<item ID>) This function will look up the item with the specified ID number in the @@ -8067,10 +8057,75 @@ Example: *sprintf(<format>{,param{,param{,...}}}) -C style sprintf. The resulting string is returned same as in PHP. All C -format specifiers are supported except %n. For more info check sprintf -function at www.cplusplus.com -Number of params is only limited by Hercules' script engine. +C style sprintf. The resulting string is returned. + +The format string can contain placeholders (format specifiers) using the +following structure: + + %[parameter][flags][width]type + +The following format specifier types are supported: + +%%: Prints a literal '%' (special case, doesn't support parameter, flag, width) +%d, %i: Formats the specified value as a decimal signed number +%u: Formats the specified value as a decimal unsigned number +%x: Formats the specified value as a hexadecimal (lowercase) unsigned number +%X: Formats the specified value as a hexadecimal (uppercase) unsigned number +%o: Formats the specified value as an octal unsigned number +%s: Formats the specified value as a string +%c: Formats the specified value as a character (only uses the first character + of strings) + +The following format specifier types are not supported: + +%n (not implemented due to safety concerns) +%f, %F, %e, %E, %g, %G (the script engine doesn't use floating point values) +%p (the script engine doesn't use pointers) +%a, %A (not supported, use 0x%x and 0x%X respectively instead) + +An ordinal parameter can be specified in the form 'x$' (where x is a number), +to reorder the output (this may be useful in translated strings, where the +sentence order may be different from the original order). Example: + + // Name, level, job name + mes(sprintf("Hello, I'm %s, a level %d %s", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); + +When translating the sentence to other languages (for example Italian), +swapping some arguments may be appropriate, and it may be desirable to keep the +actual arguments in the same order (i.e. when translating through the HULD): + + // Job name is printed before the level, although they're specified in the opposite order. + // Name, job name, level + mes(sprintf("Ciao, io sono %1$s, un %3$s di livello %2$d", strcharinfo(PC_NAME), BaseLevel, jobname(Class))); + +The supported format specifier flags are: + +- (minus): Left-align the output of this format specifier. (the default is to + right-align the output). ++ (plus): Prepends a plus for positive signed-numeric types. positive = '+', + negative = '-'. +(space): Prepends a space for positive signed-numeric types. positive = ' ', + negative = '-'. This flag is ignored if the '+' flag exists. +0 (zero): When a field width option is specified, prepends zeros for numeric + types. (the default prepends spaces). +A field width can be specified. + + mes(sprintf("The temperature is %+d degrees Celsius", .@temperature)); // Keeps the '+' sign in front of positive values + .@map_name$ = sprintf("quiz_%02d", .@i); // Keeps the leading 0 in "quiz_00", etc + +A field width may be specified, to ensure that 'at least' that many characters +are printed. If a star ('*') is specified as width, then the width is read as +argument to the sprintf() function. This also supports positional arguments. + + sprintf("%04d", 10) // Returns "0010" + sprintf("%0*d", 5, 10) // Returns "00010" + sprintf("%5d", 10) // Returns " 10" + sprintf("%-5d", 10) // Returns "10 " + sprintf("%10s", "Hello") // Returns " Hello"; + sprintf("%-10s", "Hello") // Returns "Hello "; + +Precision ('.X') and length ('hh', 'h', 'l', 'll', 'L', 'z', 'j', 't') +specifiers are not implemented (not necessary for the script engine purposes) Example: .@format$ = "The %s contains %d monkeys"; |