Networking

More...

Classes:

class

AIClient

Simulated client driven by AI commands.

class

AIConnection

Special client connection driven by an AI, rather than a human.

class

GameConnection

The game-specific subclass of NetConnection.

class

HTTPObject

Allows communications between the game and a server using HTTP.

class

NetConnection

Provides the basis for implementing a multiplayer game protocol.

class

NetObject

Superclass for all ghostable networked objects.

class

SimpleMessageEvent

A very simple example of a network event.

class

SimpleNetObject

A very simple example of a class derived from NetObject.

class

TCPObject

Allows communications between the game and a server using TCP/IP protocols.

Functions

string

addTaggedString(string str)

Use the addTaggedString function to tag a new string and add it to the NetStringTable.

void

allowConnections(bool allow)

Sets whether or not the global NetInterface allows connections from remote hosts.

string

buildTaggedString(string format, ... )

Build a string using the specified tagged string format.

void

closeNetPort()

Closes the current network port.

void

commandToClient(NetConnection client, string func, ... )

Send a command from the server to the client.

void

commandToServer(string func, ... )

Send a command to the server.

string

detag(string str)

Returns the string from a tag string.

void

DNetSetLogging(bool enabled)

Enables logging of the connection protocols.

void

dumpNetStats()

Dumps network statistics for each class to the console.

void

dumpNetStringTable()

Dump the current contents of the networked string table to the console.

string

getTag(string textTagString)

Extracts the tag from a tagged string.

string

getTaggedString(string tag)

Use the getTaggedString function to convert a tag to a string.

bool

isAddressTypeAvailable(int addressType)

Determines if a specified address type can be reached.

void

pathOnMissionLoadDone()

Load all Path information from the mission.

void

removeTaggedString(int tag)

Remove a tagged string from the Net String Table.

bool

setNetPort(int port, bool bind)

Set the network port for the game to use.

Variables

int

LagThreshold

How long between received packets before the client is considered as lagging (in ms).

int

netBitsReceived

The number of bytes received during the last packet process operation.

int

netBitsSent

The number of bytes sent during the last packet send operation.

int

netGhostUpdates

The total number of ghosts added, removed, and/or updated on the client during the last packet process operation.

int

PacketRateToClient

Sets how often packets are sent from the server to a client.

int

PacketRateToServer

Sets how often packets are sent from the client to the server.

int

PacketSize

Sets the maximum size in bytes an individual network packet may be.

Detailed Description

Functions

addTaggedString(string str)

Use the addTaggedString function to tag a new string and add it to the NetStringTable.

Parameters:

str	The string to be tagged and placed in the NetStringTable. Tagging ignores case, so tagging the same string (excluding case differences) will be ignored as a duplicated tag.

return:

Returns a string( containing a numeric value) equivalent to the string ID for the newly tagged string

see:

syntaxDataTypes under Tagged Strings

see:

removeTaggedString()

see:

getTaggedString()

allowConnections(bool allow)

Sets whether or not the global NetInterface allows connections from remote hosts.

allowConnections(bool allow)

Parameters:

allow

Set to true to allow remote connections.

buildTaggedString(string format, ... )

Build a string using the specified tagged string format.

This function takes an already tagged string (passed in as a tagged string ID) and one or more additional strings. If the tagged string contains argument tags that range from %%1 through %%9, then each additional string will be substituted into the tagged string. The final (non-tagged) combined string will be returned. The maximum length of the tagged string plus any inserted additional strings is 511 characters.

Parameters:

format	A tagged string ID that contains zero or more argument tags, in the form of %%1 through %%9.
...	A variable number of arguments that are insterted into the tagged string based on the argument tags within the format string.

return:

An ordinary string that is a combination of the original tagged string with any additional strings passed in inserted in place of each argument tag.

// Create a tagged string with argument tags
%taggedStringID = addTaggedString("Welcome %1 to the game!");

// Some point later, combine the tagged string with some other string
%string = buildTaggedString(%taggedStringID, %playerName);
echo(%string);

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

getTaggedString()

closeNetPort()

Closes the current network port.

commandToClient(NetConnection client, string func, ... )

Send a command from the server to the client.

Parameters:

client	The numeric ID of a client GameConnection
func	Name of the client function being called
...	Various parameters being passed to client command

// Set up the client command.  Needs to be executed on the client, such as
// within scripts/client/client.cs
// Update the Ammo Counter with current ammo, if not any then hide the counter.
function clientCmdSetAmmoAmountHud(%amount)
{
   if (!%amount)
     AmmoAmount.setVisible(false);
   else
   {
     AmmoAmount.setVisible(true);
     AmmoAmount.setText("Ammo: "@%amount);
   }
}

// Call it from a server function.  Needs to be executed on the server, 
//such as within scripts/server/game.cs
function GameConnection::setAmmoAmountHud(%client, %amount)
{
   commandToClient(%client, 'SetAmmoAmountHud', %amount);
}

commandToServer(string func, ... )

Send a command to the server.

Parameters:

func	Name of the server command being called
...	Various parameters being passed to server command

// Create a standard function.  Needs to be executed on the client, such 
// as within scripts/client/default.bind.cs
function toggleCamera(%val)
{
   // If key was down, call a server command named 'ToggleCamera'
   if (%val)
      commandToServer('ToggleCamera');
}

// Server command being called from above.  Needs to be executed on the 
// server, such as within scripts/server/commands.cs
function serverCmdToggleCamera(%client)
{
   if (%client.getControlObject() == %client.player)
   {
     %client.camera.setVelocity("0 0 0");
     %control = %client.camera;
   }
   else
   {
     %client.player.setVelocity("0 0 0");
     %control = %client.player;
  }
   %client.setControlObject(%control);
   clientCmdSyncEditorGui();
}

detag(string str)

Returns the string from a tag string.

Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context. Use getTaggedString() to convert a tagged string ID back into a regular string at any time.

// From scripts/client/message. cs
function clientCmdChatMessage(%sender, %voice, %pitch, %msgString, %a1, %a2, %a3, %a4, %a5, %a6, %a7, %a8, %a9, %a10)
{
   onChatMessage(detag(%msgString), %voice, %pitch);
}

see:

syntaxDataTypes under Tagged Strings

see:

getTag()

see:

getTaggedString()

DNetSetLogging(bool enabled)

Enables logging of the connection protocols.

When enabled a lot of network debugging information is sent to the console. Parameters:

enabled

True to enable, false to disable

dumpNetStats()

Dumps network statistics for each class to the console.

The returned avg, min and max values are in bits sent per update. The num value is the total number of events collected.

note:
This method only works when TORQUE_NET_STATS is defined in torqueConfig.h.

dumpNetStringTable()

Dump the current contents of the networked string table to the console.

The results are returned in three columns. The first column is the network string ID. The second column is the string itself. The third column is the reference count to the network string.

note:
This function is available only in debug builds.

getTag(string textTagString)

Extracts the tag from a tagged string.

Should only be used within the context of a function that receives a tagged string, and is not meant to be used outside of this context.

Parameters:

textTagString

The tagged string to extract.

return:

The tag ID of the string.

see:

syntaxDataTypes under Tagged Strings

see:

detag()

getTaggedString(string tag)

Use the getTaggedString function to convert a tag to a string.

This is not the same as detag() which can only be used within the context of a function that receives a tag. This function can be used any time and anywhere to convert a tag to a string.

Parameters:

tag	A numeric tag ID.

return:

The string as found in the Net String table.

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

removeTaggedString()

isAddressTypeAvailable(int addressType)

Determines if a specified address type can be reached.

pathOnMissionLoadDone()

Load all Path information from the mission.

This function is usually called from the loadMissionStage2() server-side function after the mission file has loaded. Internally it places all Paths into the server's PathManager. From this point the Paths are ready for transmission to the clients.

// Inform the engine to load all Path information from the mission.
pathOnMissionLoadDone();

see:

NetConnection::transmitPaths()

see:

NetConnection::clearPaths()

see:

Path

removeTaggedString(int tag)

Remove a tagged string from the Net String Table.

Parameters:

tag	The tag associated with the string

see:

syntaxDataTypes under Tagged Strings

see:

addTaggedString()

see:

getTaggedString()

setNetPort(int port, bool bind)

Set the network port for the game to use.

Parameters:

port	The port to use.
bind	True if bind() should be called on the port.

return:

True if the port was successfully opened. This will trigger a windows firewall prompt. If you don't have firewall tunneling tech you can set this to false to avoid the prompt.

Variables

int LagThreshold

How long between received packets before the client is considered as lagging (in ms).

This is used by GameConnection to determine if the client is lagging. If the client is indeed lagging, setLagIcon() is called to inform the user in some way. i.e. display an icon on screen.

see:

GameConnection, GameConnection::setLagIcon()

int netBitsReceived

The number of bytes received during the last packet process operation.

note:
Even though this variable has 'Bits' in it, the value is indeed reported in bytes. This name is a legacy holdover and remains for compatibility reasons.

int netBitsSent

The number of bytes sent during the last packet send operation.

note:
Even though this variable has 'Bits' in it, the value is indeed reported in bytes. This name is a legacy holdover and remains for compatibility reasons.

int netGhostUpdates

The total number of ghosts added, removed, and/or updated on the client during the last packet process operation.

int PacketRateToClient

Sets how often packets are sent from the server to a client.

It is possible to control how often packets may be sent to the clients. This may be used to throttle the amount of bandwidth being used, but should be adjusted with caution.

The actual formula used to calculate the delay between sending packets to a client is:

Packet Update Delay To Client = 1024 / $pref::Net::PacketRateToClient

with the result in ms. A minimum rate of 1 is enforced in the source code. The default value is 10.

note:
When using a local connection (local_connections) be aware that this variable is always forced to 128.

int PacketRateToServer

Sets how often packets are sent from the client to the server.

It is possible to control how often packets may be sent to the server. This may be used to throttle the amount of bandwidth being used, but should be adjusted with caution.

The actual formula used to calculate the delay between sending packets to the server is:

Packet Update Delay To Server = 1024 / $pref::Net::PacketRateToServer

with the result in ms. A minimum rate of 8 is enforced in the source code. The default value is 32.

note:
When using a local connection (local_connections) be aware that this variable is always forced to 128.

int PacketSize

Sets the maximum size in bytes an individual network packet may be.

It is possible to control how large each individual network packet may be. Increasing its size from the default allows for more data to be sent on each network send. However, this value should be changed with caution as too large a value will cause packets to be split up by the networking platform or hardware, which is something Torque cannot handle.

A minimum packet size of 100 bytes is enforced in the source code. There is no enforced maximum. The default value is 200 bytes.

note:
When using a local connection (local_connections) be aware that this variable is always forced to 1024 bytes.