summaryrefslogtreecommitdiff
path: root/doc/script_commands.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/script_commands.txt')
-rw-r--r--doc/script_commands.txt100
1 files changed, 87 insertions, 13 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 05d075ac1..f0758de71 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
@@ -8067,10 +8076,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";