Plastic Gem #30: Torque Tips for Noobs

Download Code File




Torque Tips for Noobs

Like any language there are intricacies that one learnes as they are exposed to the language longer. The next two Gems will discuss Top Tips and Fubars for the benefit of programmers new to Torque script.

1. Dynamic Fields are great.
In Torque script any object (including datablocks) can have fields created dynamically. This allows programmers to store values on any object on the server instead of making tons of global variables. To see if a value exist on an object you can test against an empty string

if(%client.score $= "")
%client.score = 0;

To clear a field as if it never existed, set to the empty string:

%client.score = "";

2. CommandToServer VS CommandToClient

Torque is great for prototyping in so many ways. It even has a form of Remote Procedure Calls (RPC) using the functions commandToServer() and commandToClient(). These methods allow you to have script running on the server "call a function" on the client or script running on the client "call a function" on the server. This can be good for quick design choices. Keep in mind that it is not ideal because it increases network traffic more than implementing the same functionality in C++.

An example will make this more clear. Here is an example of the client sending a command to the server.

Client Script:

commandToServer( 'SomeCommandFromClient', %p1, %p2);

Server Script:

function ServerCmdSomeCommandFromClient (%client, %p1, %p2){
	echo("Server command SomeCommandFromClient received:" SPC %client);
}

A command received by the server uses the prefix ServerCmd, ie the format is ServerCmdFUNCTIONNAME. The function's first parameter will be the client which invoked the command.

NOTE: note the use of the single quotes around the value sent to commandToServer(). Single quotes means "tagged string" in Torque (more on this in the next gem). The single quotes are important.

Commands received by a client have a prefix of ClientCmdFUNCTIONNAME. There is no intrinsic parameter for these functions. But remember they are only occurring on one client and no one else. Here is an example

Server Script

commandToClient(%client, 'SomeCommandFromServer',%param);

Client Script:

function ClientCmdSomeCommandFromServer(){
echo("Client command  SomeCommandFromServer received");
}

There is a limit to how many parameters you can send across on a command to server but it is rather high like twelve.

If you are an object on the server you could send information to any client if you have that client's game connection id, which is often called %client in the scripts. Remember the function names are considered tagged strings so they must be passed in with single quotes

In case you want to send information to all clients use the ClientGroup which will exist on the server:

for(%i = 0; %i < ClientGroup.getCount(); %i++)
	commandToClient(ClientGroup.getObject(%i), 'SomeCommandFromServer');

3. Strings
Everything is a string, yes let's repeat that, every thing is a string so it is good to know a few simple conventions for construction strings, first are the operators

@		Concatenation
SPC		Concatenate with a space, same as @" "@
NL		Concatenates with a new line character, same as @"n"@  
TAB		Concatenates with a tab character, same as @"t"@
$= 		String is Equal to.

Everything is a String so if it doesn't exist it should be an empty string,

if(%var $= "")
	echo("Var does not exist");

Everything is a String, even numbers. This means you have to use the right operator to get the right result. Want to treat some variables as numbers? Use the == operator to compare them. Want to treat them as strings? Use the $= operator instead.

Everything is a string so you might as well start formatting them so they look good when you display them. I encourage using GuiMLTextCtrl() instead of GuiTextCtrl().The MLText control allows you to provide some simple markup tags within the string which can trump the GUI's profile,

<font:name:size>-Sets the current font to the indicated name and size. Example: <font:Arial Bold:20> 
 	<tag:ID>-Set a tag to which we can scroll a GuiScrollContentCtrl (parent control of the guiMLTextCtrl) 
 	<color:RRGGBBAA>-Sets text color. Example: <color:ff0000> will display red text. 
 	<linkcolor:RRGGBBAA>-Sets the color of a hyperlink. 
 	<linkcolorHL:RRGGBBAA>-Sets the color of a hyperlink that is being clicked. 
 	<shadow:x:y>-Add a shadow to the text, displaced by (x, y). 
 	<shadowcolor:RRGGBBAA>-Sets the color of the text shadow. 
 	<bitmap:filePath>-Displays the bitmap image of the given file. Example: <bitmap:demo/client/ui/separator> 
 	<bitmapk:filePath>-Same as bitmap above, but the blockerList comes into play. 
 	<spush>-Saves the current text formatting so that temporary changes to formatting can be made. Used with <spop>. 
 	<spop>-Restores the previously saved text formatting. Used with <spush>. 
 	<sbreak>-Produces line breaks, similarly to <br>. 
 	<just:left>-Left justify the text. 
 	<just:right>-Right justify the text. 
 	<just:center>-Center the text. 
 	<a:URL>content</a>-Inserts a hyperlink into the text, which will open the user's browser. In the URL, the leading "http://" is understood. Example: <a:www.garagegames.com>Garage Games Website</a>. 
 	<lmargin:width>-Sets the left margin. 
 	<lmargin%:width>-Sets the left margin as a percentage of the full width. 
 	<rmargin:width>-Sets the right margin. 
 	<rmargin%:width>-Sets the right margin as a percentage of the full width. 
 	<clip:width>content</clip>-Produces the content, but clipped to the given width. 
 	<div:bool>-Use the profile's fillColorHL to draw a background for the text. 
 	<tab:##[,##[,##]]>-Sets tab stops at the given locations. 
 	<br>-Forced line break.

BUT remember once new text is set you must call the GUI method forceReflow() in order for the new changes to take effect

%mlcode = "<font:Impact:20>";
%text ="So";
%text2 =  "Cool";
%output = %text @ %mlCode SPC %text2;
MLGUICONTROL.setText(%output);
MLGUICONTROL.forceReflow();