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.
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.
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 |
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 |