From TDN

This page is a Work In Progress by Seth Willits, dated May 15, 2008.

TGB Networking >> Remote Commands

Contents 1 Communicating Between Server and Client 1.1 commandToServer 1.2 commandToClient 1.3 String Substitution

Communicating Between Server and Client

Torque Game Builder has what is called "event-based" networking. Essentially, nothing is sent between the client and server unless one end of the connection creates and sends an "event" to the other end. This event-based networking is carried out by way of Remote Procedure Calls (RPCs). A remote procedure call allows for a program on one end of a networked connection to remotely execute a procedure (e.g. a function) in the program on the other end of the connection.

Torque Game Builder has two functions which will form the entire basis for network communication between clients and servers: commandToClient(), and commandToServer(). commandToClient() is executed on the server to remotely execute a function on a specific client. commandToServer() is executed on the client to remotely execute a function on the server the client is connected to.

commandToServer

The commandToServer() function takes the form: commandToServer(commandName, arg1, arg2, arg3, ... ). The function called on the server is identified by prefixing serverCmd to the string parameter commandName . For example, if commandName were "SayHello", then the function called on the server will have the name serverCmdSayHello. The parameters to the called function serverCmdSayHello will be the client object for the client who sent the command to the server, followed by the same parameters following commandName in the call to commandToServer(). The number and content of arguments passed to commandToServer() after commandName (and thus received by the server) are entirely up to you, but the data types must be either strings or numbers.

For example, on the client:

   commandToServer("SayHello", "Seth");

On the server:

function serverCmdSayHello(%client, %fromWho)
{
   echo("The client named" SPC %fromWho SPC "said hello to us!");
}

Will echo the following, in the server's console:

The client named Seth said hello to us!

commandToClient

The commandToClient() function takes the form: commandToClient(client, commandName, arg1, arg2, arg3, ... ). The function called on the client is identified by prefixing clientCmd to the string parameter commandName . For example, if commandName were "SayGoodbye", then the function called on the client will have the name clientCmdSayGoodbye. The parameters to the called function clientCmdSayGoodbye will simply be the same parameters following commandName in the call to commandToClient(). The number and content of arguments passed to commandToClient() after commandName (and thus received by the client) are entirely up to you, but the data types must be either strings or numbers.

For example, on the server:

   commandToClient(ClientGroup.getObject(0), "SayGoodbye", "Until next time!");

On the client:

function clientCmdSayGoodbye(%message)
{
   echo("The server said goodbye with the message:" SPC %message);
}

Will echo the following, in the client's console:

The server said goodbye with the message: Until next time!

String Substitution

The commandToClient and commandToServer functions perform string argument substitution automatically using the in-string % modifier. For example:

commandToClient('EchoMessage',
                'This %1 guy is super %2',
                'Got Milk?',
                'slow at writing documentation');

is executed on the client as:

function clientCmdEchoMessage(%message, %a1, %a2, %a3, %a4)
{
    // tagged strings must be detagged in order to be displayed.
    echo(detag(%message));
    echo("a1 = " @ detag(%a1));
    echo("a2 = " @ detag(%a2));
    echo("a3 = " @ detag(%a3));
    echo("a4 = " @ detag(%a4));
}

and would echo:

This Got Milk? guy is super slow at writing documentation
a1 = Got Milk?
a2 = slow at writing documentation
a3 =
a4 =

The string substitution number (after the %) refers to the argument position n spaces after the current argument:

CommandToClient('EchoMessage',
                '%1 is a good %2 for %3',
                '%1 the good %2',
                'Role Model',
                'SuperDood %1',
                'the dude of super');

Would echo:

Role Model the good SuperDood the dude of super is a good Role Model
for SuperDood the dude of super
A1 = Role Model the good SuperDood the dude of super
A2 = Role Model
A3 = SuperDood the dude of super
A4 = the dude of super

This functionality is especially useful for status and game messages coming from the server, because each text message compresses into just a small array of tag identifiers.