Creation/Dev/Output Methods
Introduction
With the addition of the new scripting engine, there are a number of new methods in which you can create output from an NPC. In this article, I will discuss a couple of ways.
Useful Things To Know
If you've played with the new engine for a while, you're probably aware of the string concationation operators. If not, here they are.
String Concatenation a @ b
with space a SPC b
with newline a NL b
with tabulator a TAB b
What these operators do is join values together to form one value.
An example of using @ would be:
"Hello, " @ player.account
... which would produce "Hello, accountnamehere".
The SPC, NL and TAB operators work using the same principal - except that they insert a Space, New Line or Tab Space respectively.
If you don't put a space at the end of the first value or at the beginning of the second value when using @, you don't get a visible space, for example:
"Hello" @ "World"
... will produce "HelloWorld".
However! If you use SPC, you'll get a space in place of the operator:
"Hello" SPC "World"
... producing "Hello World".
You can use these operators just about anywhere that a variable is requested, i.e. setting a variable, or sending to a function.
format() function
Or, if you aren't so interested in using the concationation operators, you can use the format() function.
What this function does, is that it takes a sort of template from the first parameter you give it, and replaces % codes with other parameters you give it.
Now, the template format primarily uses the following % characters:
%d %i - Integer %f - Float (number with decimal) %s - String %c - Single character %% - Literal "%" character %x %X - Print an integer as a hexadecimal
There are more, since the function is made to be compatible with C's printf() function.
In the template, every % code will be replaced with the respective parameter.
Say you want to produce "Hello, Mr. Skyld. You ate 4 apples today!" using format(). First, your format would be this:
"Hello, %s. You ate %i apples today!"
... and you must not forget to give the parameters containing the values:
format("Hello, %s. You ate %i apples today!", "Mr. Skyld", 4);
You can give the format() functions as many parameters as necessary to build up your value. If you use a % code and a value isn't present for it, a 0 (zero) will appear in it's place.
format2() function
You can also use format2(), which acts just like format() with the exception that instead of passing variables as separate parameters, they are sent as an array to the 2nd parameter. The example above would become
format2("Hello, %s. You ate %i apples today!", {"Mr. Skyld", 4});
Along with format2() came the indexing of the parameters. This method will work with both format() and format2() functions. It allows us to choose which parameter to place in which position in the format string. The problem of parameters being placed in the wrong order will not exist if each parameter has a different data type, however.
format2("Hello, %2$s. You ate %1$s apples today!", {"four","Mr. Skyld"});
In the example, both parameters are strings, so it would be necessary to give them an index when trying to insert them in a different order than they were passed. %1$s refers to the 1st object in the array inserted as a string. %n$T is general; the nth parameter inserted with datatype of T.
Now, let's continue on various ways of outputting data.
Outputs
Direct Output
Direct Output is sending an output directly to the game client, or to RC/NC. There are a number of functions for these tasks.
echo()
The echo() function will, on the serverside, send data to NC (by default), so RC users who have the NPC-Control right will see the message in RC chat, and on the clientside, sends the message to the F2 window. It expects one parameter, and that's the message you're sending. For example:
echo("This is a message!");
The message "This is a message!" will appear either in RC or the F2 window using this example.
Servers can change the sendechotorc server option to allow echo() messages to be sent to everyone on RC.
sendtorc()
The sendtorc() function works in the same way that the echo() function does, however, it only usually works on the serverside. It will appear to all RC users. For example:
sendtorc("This is a message!");
... will send "NPC-Server (Server): This is a message!" to RC.
Note that this function can only be used on the clientside when Client-RC is active.
sendtonc()
The sendtonc() function works in exactly the same way as echo() does serverside, except the message will display only to NC users.
sendrpgmessage()
The sendrpgmessage() will send a message appearing in the player's F2 log window and can be used on both client- and server-side. For example:
sendrpgmessage("This is a message!");
... will send "This is a message!" to the player's F2 window.
Working with Files
loadstring()
loadstring() is an object function which loads the contents of a given file.
Say that the file "levels/file.txt" contains the message "HELLO WORLD". If you want to load that value into a variable called "myVar", you should use this function:
myVar.loadstring("levels/file.txt");
You can easily check the contents of the file:
echo(myVar);
Use myVar.escape() if you want to print a string that might contain special characters like new-line which would not appear on RC-chat.
savestring()
savestring() is another object function, however, instead of loading the contents of a file, it writes the contents instead.
Consider this with the previous example:
myVar = "HELLO PLANET";
myVar.savestring("levels/file.txt", 0);
... would write "HELLO PLANET" to "levels/file.txt".
The second operator, which is 0 (zero) in that example, is the Append function, and decides whether the file should be overwritten with the new value, or whether the new value should be added onto the end of the file. If you specify 1, then the value will be appended, if not, it will overwrite the file.
savevars()
savevars() is an object function which saves the variables of an object into a file. Consider this example:
myVar = new TStaticVar(); // Create a TStaticVar
myVar.variable = "Hello";
myVar.secondvariable = "World";
myVar.saveVars("levels/test.txt", 0);
This will save the variables inside the "myVar" object into "levels/test.txt". You can then recall these variables using loadvars();
Like savelines(), the second parameter controls whether the variables are to be appended to the file. 0 will overwrite the file, and 1 will append to the file.
loadvars()
loadvars() is another object function which loads savevars()-style variables from a file into an object. Let's say you used the previous example from savevars(), then you could restore these values using the following:
myNewVar.loadvars("levels/test.txt");
echo(myNewVar.secondvariable);
... which will output "World".
Private Messages (PMs)
From the serverside, you can send PMs to players. They appear from the NPC-Server.
If you wanted to send a PM to the player "Skyld" (if the player is online), the you would use the following example:
findPlayer("Skyld").sendPM("This is a PM");
... and then the specified player (account), in this case Skyld, would receive the PM "This is a PM".
If you want to send a PM to the current player, you would simply use:
player.sendPM("This is a PM");