GameConnection Messages

Most of the other kinds of messaging used when making a game with Torque are handled automatically. However, in addition to the direct messaging techniques we just looked at, there are other more indirect messaging capabilities available to the Torque game developer. These are messages related to the GameConnection object.

I call these methods indirect because we, as programmers, don't get to use them in any old way of our choosing. But we can, nonetheless, use these methods, in the form of message handlers, when the Torque Engine decides it needs to send the messages.

What GameConnection Messages Do

GameConnection messages are of great importance to us during the negotiation process that takes place between the client and server when a client joins a game. They are network messages with game-specific uses, as opposed to being potentially more general-purpose network messages.

Torque calls a number of GameConnection message handlers at different times during the process of establishing, maintaining, and dropping game-related connections. In the Torque demo software, many of these handlers are defined in the common code base, whereas others aren't used at all. You are encouraged to override the common code message handlers with your own GameConnection message handlers or use the unused handlers, if you need to.

Specifics

During program execution, the client will at some point try to connect to the server using a set of function calls like this:

    %conn = new GameConnection(ServerConnection);    %conn.SetConnectArgs(%username);    %conn.Connect(); 

In this example the %conn variable holds the handle to the GameConnection. The Connect() function call initiates a series of network transactions that culminate at the server with a call to the GameConnection::OnConnect handler.

The following descriptions are listed roughly in the order that they are used in the program.

onConnectionRequest()
Parameters:	none
Return:	" " (null string)	Indicates that connection is accepted.
	None	Indicates rejection for some reason.
Description:	Called when a client attempts a connection, before the connection is accepted.
Usage:	Common—Server

This handler is used to check if the server-player capacity has been exceeded. If not exceeded, then " " is returned, which allows the connection process to continue. If the server is full, then CR_SERVERFULL is returned. Returning any value other than " " will cause an error condition to be propagated back through the engine and sent to the client as a call to the handler GameConnection:: onConnectRequestRejected. Any arguments that were passed to GameConnection::::Connect are also passed to this handler by the engine.

onConnectionAccepted(handle)
Parameters:	handle	GameConnection handle.
Return:	nothing
Description:	Called when a Connect call succeeds.
Usage:	Client

This handler is a good place to make last-minute preparations for a connected session.

onConnectRequestRejected(handle, reason)
Parameters:	handle	GameConnectionhandle.
	reason	Indicates why connection was rejected.
Return:	nothing
Description:	Called when Connect call fails.
Usage:	Client

If you arrive in this handler you should display, or at least log, the fact that the connection was rejected and why.

onConnect(client, name)
Parameters:	client	Client's GameConnection handle.
	name	Name of client's account or username.
Return:	nothing
Description:	Called when a client has successfully connected.
Usage:	Server

In this case the second parameter (%name) is the value the client has used, while establishing the connection, as the parameter to the %(GameConnection).SetConnectArgs(%username) call.

onConnectRequestTimedOut(handle)
Parameters:	handle	GameConnection handle.
Return:	nothing
Description:	Called when establishing a connection takes too long.
Usage:	Client

When this gets called you probably want to display, or at least log, some message indicating that the connection has been lost because of a timeout.

onConnectionTimedOut(handle)
Parameters:	handle	GameConnection handle.
Return:	nothing
Description:	Called when a connection ping (heartbeat) has not been received.
Usage:	Server, Client

When this gets called you probably want to display, or at least log, some message indicating that the connection has been lost because of a timeout.

onConnectionDropped(handle, reason)
Parameters:	handle	GameConnection handle.
	reason	String indicating why server dropped the connection.
Return:	nothing
Description:	Called when the server initiates the disconnection of a client.
Usage:	Client

When this gets called you probably want to display, or at least log, some message indicating that the connection has been lost because of a timeout.

onConnectRequestRejected(handle, reason)
Parameters:	handle	GameConnection handle.
	reason	See Table 6.2 for a list of conventional reason codes defined by GarageGames in script.
Return:	nothing
Description:	Called when a client's connection request has been turned down by the server.
Usage:	Client

Table 6.2: Connection Request Rejection Codes

Reason Code	Meaning
CR_INVALID_PROTOCOL_VERSION	The wrong version of client was detected.
CR_INVALID_CONNECT_PACKET	There is something wrong with the connection packet.
CR_YOUAREBANNED	Your game username has been banned.
CR_SERVERFULL	The server has reached the maximum number of players.
CHR_PASSWORD	The password is incorrect.
CHR_PROTOCOL	The game protocol version is not compatible.
CHR_CLASSCRC	The game class version is not compatible.
CHR_INVALID_CHALLENGE_PACKET	The client detected an invalid server response packet.

When this gets called you probably want to display, or at least log, some message indicating that the connection has been lost because of a timeout.

onConnectionError(handle, errorString)
Parameters:	handle	GameConnection handle.
	errorString	String indicating the error encountered.
Return:	nothing
Description:	General connection error, usually raised by ghosted objects' initialization problems, such as missing files. The errorString is the server's connection error message.
Usage:	Client

onDrop(handle, reason)
Parameters:	handle	GameConnection handle.
	reason	Reason for connection being dropped, passed from server.
Return:	nothing
Description:	Called when a connection to a server is arbitrarily dropped.
Usage:	Client

initialControlSet (handle)
Parameters:	handle	GameConnection handle.
Return:	nothing
Description:	Called when the server has set up a control object for the GameConnection. For example, this could be an avatar model or a camera.
Usage:	Client

setLagIcon(handle, state)
Parameters:	handle	GameConnection handle.
	state	Boolean that indicates whether to display or hide the icon.
Return:	nothing
Description:	Called when the connection state has changed, based upon the lag setting. stateis set to true when the connection is considered temporarily broken or set to false when there is no loss of connection.
Usage:	Client

onDataBlocksDone(handle, sequence)
Parameters:	handle	GameConnection handle.
	sequence	Value that indicates which set of data blocks has been transmitted.
Return:	nothing
Description:	Called when the server has received confirmation that all data blocks have been received.
Usage:	Server

Use this handler to manage the mission loading process and any other activity that transfers datablocks.

onDataBlockObjectReceived(index, total)
Parameters:	index	Index number of data block objects.
	total	How many sent so far.
Return:	nothing
Description:	Called when the server is ready for data blocks to be sent.
Usage:	Client

onFileChunkReceived(file, ofs, size)
Parameters:	file	The name of the file being sent.
	ofs	Offset of data received.
	size	File size.
Return:	nothing
Description:	Called when a chunk of file data from the server has arrived.
Usage:	Client

onGhostAlwaysObjectReceived()
Parameters:	none
Return:	nothing
Description:	Called when a ghosted object's data has been sent across from the server to the client.
Usage:	Client

onGhostAlwaysStarted(count)
Parameters:	count	The number of ghosted objects dealt with so far.
Return:	nothing
Description:	Called when a ghosted object has been sent to the client.
Usage:	Client