|
|
|
|
The game-specific subclass of NetConnection. More...
Public Member Functions | |
| void | activateGhosting () |
| Called by the server during phase 2 of the mission download to start sending ghosts to the client. | |
| bool | chaseCam (int size) |
| Sets the size of the chase camera's matrix queue. | |
| void | clearCameraObject () |
| Clear the connection's camera object reference. | |
| void | delete (string reason="") |
| On the server, disconnect a client and pass along an optional reason why. | |
| SimObject | getCameraObject () |
| Returns the connection's camera object used when not viewing through the control object. | |
| float | getControlCameraDefaultFov () |
| Returns the default field of view as used by the control object's camera. | |
| float | getControlCameraFov () |
| Returns the field of view as used by the control object's camera. | |
| GameBase | getControlObject () |
| On the server, returns the object that the client is controlling.By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game. | |
| float | getDamageFlash () |
| On the client, get the control object's damage flash level. | |
| float | getWhiteOut () |
| On the client, get the control object's white-out level. | |
| bool | isAIControlled () |
| Returns true if this connection is AI controlled. | |
| bool | isControlObjectRotDampedCamera () |
| Returns true if the object being controlled by the client is making use of a rotation damped camera. | |
| bool | isDemoPlaying () |
| Returns true if a previously recorded demo file is now playing. | |
| bool | isDemoRecording () |
| Returns true if a demo file is now being recorded. | |
| bool | isFirstPerson () |
| Returns true if this connection is in first person mode. | |
| void | listClassIDs () |
| List all of the classes that this connection knows about, and what their IDs are. Useful for debugging network problems. | |
| bool | play2D (SFXProfile profile) |
| Used on the server to play a 2D sound that is not attached to any object. | |
| bool | play3D (SFXProfile profile, TransformF location) |
| Used on the server to play a 3D sound that is not attached to any object. | |
| bool | playDemo (string demoFileName) |
| On the client, play back a previously recorded game session. | |
| void | resetGhosting () |
| On the server, resets the connection to indicate that ghosting has been disabled. | |
| void | setBlackOut (bool doFade, int timeMS) |
| On the server, sets the client's 3D display to fade to black. | |
| bool | setCameraObject (GameBase camera) |
| On the server, set the connection's camera object used when not viewing through the control object. | |
| void | setConnectArgs (const char *args) |
| On the client, pass along a variable set of parameters to the server. | |
| void | setControlCameraFov (float newFOV) |
| On the server, sets the control object's camera's field of view. | |
| bool | setControlObject (GameBase ctrlObj) |
| On the server, sets the object that the client will control. | |
| void | setFirstPerson (bool firstPerson) |
| On the server, sets this connection into or out of first person mode. | |
| void | setJoinPassword (string password) |
| On the client, set the password that will be passed to the server. | |
| void | setMissionCRC (int CRC) |
| On the server, transmits the mission file's CRC value to the client. | |
| void | startRecording (string fileName) |
| On the client, starts recording the network connection's traffic to a demo file. | |
| void | stopRecording () |
| On the client, stops the recording of a connection's network traffic to a file. | |
| void | transmitDataBlocks (int sequence) |
| Sent by the server during phase 1 of the mission download to send the datablocks to the client. | |
Callbacks | |
| void | initialControlSet () |
| Called on the client when the first control object has been set by the server and we are now ready to go. | |
| void | onConnectionAccepted () |
| Called on the client when the connection to the server has been established. | |
| void | onConnectionDropped (string reason) |
| Called on the client when the connection to the server has been dropped. | |
| void | onConnectionError (string errorString) |
| Called on the client when there is an error with the connection to the server. | |
| void | onConnectionTimedOut () |
| Called on the client when the connection to the server times out. | |
| void | onConnectRequestRejected (string reason) |
| Called on the client when the connection to the server has been rejected. | |
| void | onConnectRequestTimedOut () |
| Called when connection attempts have timed out. | |
| void | onDataBlocksDone (int sequence) |
| Called on the server when all datablocks has been sent to the client. | |
| void | onDrop (string disconnectReason) |
| Called on the server when the client's connection has been dropped. | |
| void | onFlash (bool state) |
| Called on the client when the damage flash or white out states change. | |
| void | setLagIcon (bool state) |
| Called on the client to display the lag icon. | |
Static Public Member Functions | |
| static int | getServerConnection () |
| On the client, this static mehtod will return the connection to the server, if any. | |
The game-specific subclass of NetConnection.
The GameConnection introduces the concept of the control object. The control object is simply the object that the client is associated with that network connection controls. By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
Torque uses a model in which the server is the authoritative master of the simulation. To prevent clients from cheating, the server simulates all player moves and then tells the client where his player is in the world. This model, while secure, can have problems. If the network latency is high, this round-trip time can give the player a very noticeable sense of movement lag. To correct this problem, the game uses a form of prediction - it simulates the movement of the control object on the client and on the server both. This way the client doesn't need to wait for round-trip verification of his moves. Only in the case of a force acting on the control object on the server that doesn't exist on the client does the client's position need to be forcefully changed.
To support this, all control objects (derivative of ShapeBase) must supply a writePacketData() and readPacketData() function that send enough data to accurately simulate the object on the client. These functions are only called for the current control object, and only when the server can determine that the client's simulation is somehow out of sync with the server. This occurs usually if the client is affected by a force not present on the server (like an interpolating object) or if the server object is affected by a server only force (such as the impulse from an explosion).
The Move structure is a 32 millisecond snapshot of player input, containing x, y, and z positional and rotational changes as well as trigger state changes. When time passes in the simulation moves are collected (depending on how much time passes), and applied to the current control object on the client. The same moves are then packed over to the server in GameConnection::writePacket(), for processing on the server's version of the control object.
| void GameConnection::activateGhosting | ( | ) |
Called by the server during phase 2 of the mission download to start sending ghosts to the client.
Ghosts represent objects on the server that are in scope for the client. These need to be synchronized with the client in order for the client to see and interact with them. This is typically done during the standard mission start phase 2 when following Torque's example mission startup sequence.
function serverCmdMissionStartPhase2Ack(%client, %seq, %playerDB)
{
// Make sure to ignore calls from a previous mission load
if (%seq != $missionSequence || !$MissionRunning)
return;
if (%client.currentPhase != 1.5)
return;
%client.currentPhase = 2;
// Set the player datablock choice
%client.playerDB = %playerDB;
// Update mod paths, this needs to get there before the objects.
%client.transmitPaths();
// Start ghosting objects to the client
%client.activateGhosting();
}
| bool GameConnection::chaseCam | ( | int | size | ) |
Sets the size of the chase camera's matrix queue.
| void GameConnection::clearCameraObject | ( | ) |
Clear the connection's camera object reference.
| void GameConnection::delete | ( | string | reason = "" |
) |
On the server, disconnect a client and pass along an optional reason why.
This method performs two operations: it disconnects a client connection from the server, and it deletes the connection object. The optional reason is sent in the disconnect packet and is often displayed to the user so they know why they've been disconnected.
| reason | [optional] The reason why the user has been disconnected from the server. |
function kick(%client)
{
messageAll( 'MsgAdminForce', '\c2The Admin has kicked %1.', %client.playerName);
if (!%client.isAIControlled())
BanList::add(%client.guid, %client.getAddress(), $Pref::Server::KickBanTime);
%client.delete("You have been kicked from this server");
}
| SimObject GameConnection::getCameraObject | ( | ) |
Returns the connection's camera object used when not viewing through the control object.
| float GameConnection::getControlCameraDefaultFov | ( | ) |
Returns the default field of view as used by the control object's camera.
| float GameConnection::getControlCameraFov | ( | ) |
Returns the field of view as used by the control object's camera.
| GameBase GameConnection::getControlObject | ( | ) |
On the server, returns the object that the client is controlling.By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
| float GameConnection::getDamageFlash | ( | ) |
On the client, get the control object's damage flash level.
| static int GameConnection::getServerConnection | ( | ) | [static] |
On the client, this static mehtod will return the connection to the server, if any.
| float GameConnection::getWhiteOut | ( | ) |
On the client, get the control object's white-out level.
| void GameConnection::initialControlSet | ( | ) |
Called on the client when the first control object has been set by the server and we are now ready to go.
A common action to perform when this callback is called is to switch the GUI canvas from the loading screen and over to the 3D game GUI.
| bool GameConnection::isAIControlled | ( | ) |
Returns true if this connection is AI controlled.
| bool GameConnection::isControlObjectRotDampedCamera | ( | ) |
Returns true if the object being controlled by the client is making use of a rotation damped camera.
| bool GameConnection::isDemoPlaying | ( | ) |
Returns true if a previously recorded demo file is now playing.
| bool GameConnection::isDemoRecording | ( | ) |
Returns true if a demo file is now being recorded.
| bool GameConnection::isFirstPerson | ( | ) |
Returns true if this connection is in first person mode.
| void GameConnection::listClassIDs | ( | ) |
List all of the classes that this connection knows about, and what their IDs are. Useful for debugging network problems.
| void GameConnection::onConnectionAccepted | ( | ) |
Called on the client when the connection to the server has been established.
| void GameConnection::onConnectionDropped | ( | string | reason | ) |
Called on the client when the connection to the server has been dropped.
| reason | The reason why the connection was dropped. |
| void GameConnection::onConnectionError | ( | string | errorString | ) |
Called on the client when there is an error with the connection to the server.
| errorString | The connection error text. |
| void GameConnection::onConnectionTimedOut | ( | ) |
Called on the client when the connection to the server times out.
| void GameConnection::onConnectRequestRejected | ( | string | reason | ) |
Called on the client when the connection to the server has been rejected.
| reason | The reason why the connection request was rejected. |
| void GameConnection::onConnectRequestTimedOut | ( | ) |
Called when connection attempts have timed out.
| void GameConnection::onDataBlocksDone | ( | int | sequence | ) |
Called on the server when all datablocks has been sent to the client.
During phase 1 of the mission download, all datablocks are sent from the server to the client. Once all datablocks have been sent, this callback is called and the mission download procedure may move on to the next phase.
| sequence | The sequence is common between the server and client and ensures that the client is acting on the most recent mission start process. If an errant network packet (one that was lost but has now been found) is received by the client with an incorrect sequence, it is just ignored. This sequence number is updated on the server every time a mission is loaded. |
| void GameConnection::onDrop | ( | string | disconnectReason | ) |
Called on the server when the client's connection has been dropped.
| disconnectReason | The reason why the connection was dropped. |
| void GameConnection::onFlash | ( | bool | state | ) |
Called on the client when the damage flash or white out states change.
When the server changes the damage flash or white out values, this callback is called either is on or both are off. Typically this is used to enable the flash postFx.
| state | Set to true if either the damage flash or white out conditions are active. |
| bool GameConnection::play2D | ( | SFXProfile | profile | ) |
Used on the server to play a 2D sound that is not attached to any object.
| profile | The SFXProfile that defines the sound to play. |
function ServerPlay2D(%profile)
{
// Play the given sound profile on every client.
// The sounds will be transmitted as an event, not attached to any object.
for(%idx = 0; %idx < ClientGroup.getCount(); %idx++)
ClientGroup.getObject(%idx).play2D(%profile);
}
| bool GameConnection::play3D | ( | SFXProfile | profile, | |
| TransformF | location | |||
| ) |
Used on the server to play a 3D sound that is not attached to any object.
| profile | The SFXProfile that defines the sound to play. | |
| location | The position and orientation of the 3D sound given in the form of "x y z ax ay az aa". |
function ServerPlay3D(%profile,%transform)
{
// Play the given sound profile at the given position on every client
// The sound will be transmitted as an event, not attached to any object.
for(%idx = 0; %idx < ClientGroup.getCount(); %idx++)
ClientGroup.getObject(%idx).play3D(%profile,%transform);
}
| bool GameConnection::playDemo | ( | string | demoFileName | ) |
On the client, play back a previously recorded game session.
It is often useful to play back a game session. This could be for producing a demo of the game that will be shown at a later time, or for debugging a game. By recording the entire network stream it is possible to later play game the game exactly as it unfolded during the actual play session. This is because all user control and server results pass through the connection.
| void GameConnection::resetGhosting | ( | ) |
On the server, resets the connection to indicate that ghosting has been disabled.
Typically when a mission has ended on the server, all connected clients are informed of this change and their connections are reset back to a starting state. This method resets a connection on the server to indicate that ghosts are no longer being transmitted. On the client end, all ghost information will be deleted.
// Inform the clients for (%clientIndex = 0; %clientIndex < ClientGroup.getCount(); %clientIndex++) { // clear ghosts and paths from all clients %cl = ClientGroup.getObject(%clientIndex); %cl.endMission(); %cl.resetGhosting(); %cl.clearPaths(); }
| void GameConnection::setBlackOut | ( | bool | doFade, | |
| int | timeMS | |||
| ) |
On the server, sets the client's 3D display to fade to black.
| doFade | Set to true to fade to black, and false to fade from black. | |
| timeMS | Time it takes to perform the fade as measured in ms. |
| bool GameConnection::setCameraObject | ( | GameBase | camera | ) |
On the server, set the connection's camera object used when not viewing through the control object.
| void GameConnection::setConnectArgs | ( | const char * | args | ) |
On the client, pass along a variable set of parameters to the server.
Once the connection is established with the server, the server calls its onConnect() method with the client's passed in parameters as aruments.
| void GameConnection::setControlCameraFov | ( | float | newFOV | ) |
On the server, sets the control object's camera's field of view.
| newFOV | New field of view (in degrees) to force the control object's camera to use. This value is clamped to be within the range of 1 to 179 degrees. |
| bool GameConnection::setControlObject | ( | GameBase | ctrlObj | ) |
On the server, sets the object that the client will control.
By default the control object is an instance of the Player class, but can also be an instance of Camera (when editing the mission, for example), or any other ShapeBase derived class as appropriate for the game.
| ctrlObj | The GameBase object on the server to control. |
| void GameConnection::setFirstPerson | ( | bool | firstPerson | ) |
On the server, sets this connection into or out of first person mode.
| firstPerson | Set to true to put the connection into first person mode. |
| void GameConnection::setJoinPassword | ( | string | password | ) |
On the client, set the password that will be passed to the server.
On the server, this password is compared with what is stored in
pref::Server::Password is empty then the client's sent password is ignored. Otherwise, if the passed in client password and the server password do not match, the CHR_PASSWORD error string is sent back to the client and the connection is immediately terminated.
This password checking is performed quite early on in the connection request process so as to minimize the impact of multiple failed attempts -- also known as hacking.
| void GameConnection::setLagIcon | ( | bool | state | ) |
Called on the client to display the lag icon.
When the connection with the server is lagging, this callback is called to allow the game GUI to display some indicator to the player.
| state | Set to true if the lag icon should be displayed. |
| void GameConnection::setMissionCRC | ( | int | CRC | ) |
On the server, transmits the mission file's CRC value to the client.
Typically, during the standard mission start phase 1, the mission file's CRC value on the server is send to the client. This allows the client to determine if the mission has changed since the last time it downloaded this mission and act appropriately, such as rebuilt cached lightmaps.
| CRC | The mission file's CRC value on the server. |
function serverCmdMissionStartPhase1Ack(%client, %seq)
{
// Make sure to ignore calls from a previous mission load
if (%seq != $missionSequence || !$MissionRunning)
return;
if (%client.currentPhase != 0)
return;
%client.currentPhase = 1;
// Start with the CRC
%client.setMissionCRC( $missionCRC );
// Send over the datablocks...
// OnDataBlocksDone will get called when have confirmation
// that they've all been received.
%client.transmitDataBlocks($missionSequence);
}
| void GameConnection::startRecording | ( | string | fileName | ) |
On the client, starts recording the network connection's traffic to a demo file.
It is often useful to play back a game session. This could be for producing a demo of the game that will be shown at a later time, or for debugging a game. By recording the entire network stream it is possible to later play game the game exactly as it unfolded during the actual play session. This is because all user control and server results pass through the connection.
| fileName | The file name to use for the demo recording. |
| void GameConnection::stopRecording | ( | ) |
On the client, stops the recording of a connection's network traffic to a file.
| void GameConnection::transmitDataBlocks | ( | int | sequence | ) |
Sent by the server during phase 1 of the mission download to send the datablocks to the client.
SimDataBlocks, also known as just datablocks, need to be transmitted to the client prior to the client entering the game world. These represent the static data that most objects in the world reference. This is typically done during the standard mission start phase 1 when following Torque's example mission startup sequence.
When the datablocks have all been transmitted, onDataBlocksDone() is called to move the mission start process to the next phase.
| sequence | The sequence is common between the server and client and ensures that the client is acting on the most recent mission start process. If an errant network packet (one that was lost but has now been found) is received by the client with an incorrect sequence, it is just ignored. This sequence number is updated on the server every time a mission is loaded. |
function serverCmdMissionStartPhase1Ack(%client, %seq)
{
// Make sure to ignore calls from a previous mission load
if (%seq != $missionSequence || !$MissionRunning)
return;
if (%client.currentPhase != 0)
return;
%client.currentPhase = 1;
// Start with the CRC
%client.setMissionCRC( $missionCRC );
// Send over the datablocks...
// OnDataBlocksDone will get called when have confirmation
// that they've all been received.
%client.transmitDataBlocks($missionSequence);
}