Torque Game Engine Documentation
TGE Version 1.5.2

NetObject Class Reference

#include <netObject.h>

Inheritance diagram for NetObject:

[legend]

Detailed Description

Superclass for ghostable networked objects.

Introduction To NetObject And Ghosting

One of the most powerful aspects of Torque's networking code is its support for ghosting and prioritized, most-recent-state network updates. The way this works is a bit complex, but it is immensely efficient. Let's run through the steps that the server goes through for each client in this part of Torque's networking:

First, the server determines what objects are in-scope for the client. This is done by calling onCameraScopeQuery() on the object which is considered the "scope" object. This is usually the player object, but it can be something else. (For instance, the current vehicle, or a object we're remote controlling.)
Second, it ghosts them to the client; this is implemented in netGhost.cc.
Finally, it sends updates as needed, by checking the dirty list and packing updates.

There several significant advantages to using this networking system:

Efficient network usage, since we only send data that has changed. In addition, since we only care about most-recent data, if a packet is dropped, we don't waste effort trying to deliver stale data.
Cheating protection; since we don't deliver information about game objects which aren't in scope, we dramatically reduce the ability of clients to hack the game and gain a meaningful advantage. (For instance, they can't find out about things behind them, since objects behind them don't fall in scope.) In addition, since ghost IDs are assigned per-client, it's difficult for any sort of co-ordination between cheaters to occur.

NetConnection contains the Ghost Manager implementation, which deals with transferring data to the appropriate clients and keeping state in synch.

An Example Implementation

The basis of the ghost implementation in Torque is NetObject. It tracks the dirty flags for the various states that the object trackers, and does some other book-keeping to allow more efficient operation of the networking layer.

Using a NetObject is very simple; let's go through a simple example implementation:

 class SimpleNetObject : public NetObject
 {
 public:
   typedef NetObject Parent;
   DECLARE_CONOBJECT(SimpleNetObject);

Above is the standard boilerplate code for a Torque class. You can find out more about this in SimObject.

    char message1[256];
    char message2[256];
    enum States {
       Message1Mask = BIT(0),
       Message2Mask = BIT(1),
    };

For our example, we're having two "states" that we keep track of, message1 and message2. In a real object, we might map our states to health and position, or some other set of fields. You have 32 bits to work with, so it's possible to be very specific when defining states. In general, you should try to use as few states as possible (you never know when you'll need to expand your object's functionality!), and in fact, most of your fields will end up changing all at once, so it's not worth it to be too fine-grained. (As an example, position and velocity on Player are controlled by the same bit, as one rarely changes without the other changing, too.)

    SimpleNetObject()
    {
       // in order for an object to be considered by the network system,
       // the Ghostable net flag must be set.
       // the ScopeAlways flag indicates that the object is always scoped
       // on all active connections.
       mNetFlags.set(ScopeAlways | Ghostable);
       dStrcpy(message1, "Hello World 1!");
       dStrcpy(message2, "Hello World 2!");
    }

Here is the constructor. Here, you see that we initialize our net flags to show that we should always be scoped, and that we're to be taken into consideration for ghosting. We also provide some initial values for the message fields.

    U32 packUpdate(NetConnection *, U32 mask, BitStream *stream)
    {
       // check which states need to be updated, and update them
       if(stream->writeFlag(mask & Message1Mask))
          stream->writeString(message1);
       if(stream->writeFlag(mask & Message2Mask))
          stream->writeString(message2);

       // the return value from packUpdate can set which states still
       // need to be updated for this object.
       return 0;
    }

Here's half of the meat of the networking code, the packUpdate() function. (The other half, unpackUpdate(), we'll get to in a second.) The comments in the code pretty much explain everything, however, notice that the code follows a pattern of if(writeFlag(mask & StateMask)) { ... write data ... }. The packUpdate()/unpackUpdate() functions are responsible for reading and writing the dirty bits to the bitstream by themselves.

    void unpackUpdate(NetConnection *, BitStream *stream)
    {
       // the unpackUpdate function must be symmetrical to packUpdate
       if(stream->readFlag())
       {
          stream->readString(message1);
          Con::printf("Got message1: %s", message1);
       }
       if(stream->readFlag())
       {
          stream->readString(message2);
          Con::printf("Got message2: %s", message2);
       }
    }

The other half of the networking code in any NetObject, unpackUpdate(). In our simple example, all that the code does is print the new messages to the console; however, in a more advanced object, you might trigger animations, update complex object properties, or even spawn new objects, based on what packet data you unpack.

    void setMessage1(const char *msg)
    {
       setMaskBits(Message1Mask);
       dStrcpy(message1, msg);
    }
    void setMessage2(const char *msg)
    {
       setMaskBits(Message2Mask);
       dStrcpy(message2, msg);
    }

Here are the accessors for the two properties. It is good to encapsulate your state variables, so that you don't have to remember to make a call to setMaskBits every time you change anything; the accessors can do it for you. In a more complex object, you might need to set multiple mask bits when you change something; this can be done using the | operator, for instance, setMaskBits( Message1Mask | Message2Mask ); if you changed both messages.

 IMPLEMENT_CO_NETOBJECT_V1(SimpleNetObject);

 ConsoleMethod(SimpleNetObject, setMessage1, void, 3, 3, "(string msg) Set message 1.")
 {
    object->setMessage1(argv[2]);
 }

 ConsoleMethod(SimpleNetObject, setMessage2, void, 3, 3, "(string msg) Set message 2.")
 {
    object->setMessage2(argv[2]);
 }

Finally, we use the NetObject implementation macro, IMPLEMENT_CO_NETOBJECT_V1(), to implement our NetObject. It is important that we use this, as it makes Torque perform certain initialization tasks that allow us to send the object over the network. IMPLEMENT_CONOBJECT() doesn't perform these tasks, see the documentation on AbstractClassRep for more details.

Dirty List

Whenever a NetObject becomes "dirty", we add it to the dirty list.
We also remove ourselves on the destructor.
This is done so that when we want to send updates (in NetConnection), it's very fast to find the objects that need to be updated.

NetObject * mPrevDirtyList

Next item in the dirty list...

NetObject * mNextDirtyList

Previous item in the dirty list...

static NetObject * mDirtyList

Static pointer to the head of the dirty NetObject list.

Miscellaneous

DECLARE_CONOBJECT (NetObject)

bool onAdd ()

Called when the object is added to the sim.

void onRemove ()

Called when the object is removed from the sim.

static void initPersistFields ()

Register dynamic fields in a subclass of ConsoleObject.

Public Member Functions

NetObject ()

~NetObject ()

void setMaskBits (U32 orMask)

Used to mark a bit as dirty; ie, that its corresponding set of fields need to be transmitted next update.

void clearMaskBits (U32 orMask)

Clear the specified bits from the dirty mask.

void setScopeAlways ()

Scope the object to all connections.

void clearScopeAlways ()

Stop scoping the object to all connections.

virtual F32 getUpdatePriority (CameraScopeQuery *focusObject, U32 updateMask, S32 updateSkips)

This returns a value which is used to prioritize which objects need to be updated.

virtual U32 packUpdate (NetConnection *conn, U32 mask, BitStream *stream)

Instructs this object to pack its state for transfer over the network.

virtual void unpackUpdate (NetConnection *conn, BitStream *stream)

Instructs this object to read state data previously packed with packUpdate.

virtual void onCameraScopeQuery (NetConnection *cr, CameraScopeQuery *camInfo)

Queries the object about information used to determine scope.

U32 getNetIndex ()

Get the ghost index of this object.

bool isServerObject () const

Is this a server object?

bool isClientObject () const

Is this a client object?

bool isGhost () const

Is this is a ghost?

bool isScopeLocal () const

Should this object only be visible to the client which created it?

bool isScopeable () const

Is this object subject to scoping?

bool isGhostable () const

Is this object ghostable?

bool isGhostAlways () const

Should this object always be ghosted?

Static Public Member Functions

static void collapseDirtyList ()

Protected Types

enum NetFlags {
  IsGhost = BIT(1),
  ScopeAlways = BIT(6),
  ScopeLocal = BIT(7),
  Ghostable = BIT(8),
  MaxNetFlagBit = 15
}

Protected Attributes

SimObjectPtr< NetObject > mServerObject

Pointer to the server object; used only when we are doing "short-circuited" networking.

BitSet32 mNetFlags

Flag values from NetFlags.

U32 mNetIndex

The index of this ghost in the GhostManager on the server.

GhostInfo * mFirstObjectRef

Head of a linked list storing GhostInfos referencing this NetObject.

Private Types

typedef SimObject Parent

Private Attributes

U32 mDirtyMaskBits

Mask indicating which states are dirty and need to be retransmitted on this object.

Friends

class NetConnection

struct GhostInfo

class ProcessList

class GhostAlwaysObjectEvent

Member Typedef Documentation

typedef SimObject NetObject::Parent [private]

Member Enumeration Documentation

enum NetObject::NetFlags [protected]

Enumerator:

IsGhost	This is a ghost.
ScopeAlways	Object always ghosts to clients.
ScopeLocal	Ghost only to local client.
Ghostable	Set if this object CAN ghost.
MaxNetFlagBit

Constructor & Destructor Documentation

NetObject::NetObject ( )

NetObject::~NetObject ( )

Member Function Documentation

NetObject::DECLARE_CONOBJECT ( NetObject )

static void NetObject::initPersistFields ( ) [static]

See also:: addField(), addFieldV(), addDepricatedField(), addGroup(), endGroup()

Reimplemented from SimObject.

Reimplemented in AudioEmitter, Camera, Debris, FireballAtmosphere, Explosion, fxFoliageReplicator, fxLight, fxRenderObject, fxShapeReplicator, fxSunLight, Lightning, ParticleEmitterNode, Precipitation, WeatherLightning, GameBase, Item, MissionArea, MissionMarker, SpawnSphere, PathCamera, PhysicalZone, Projectile, RigidShape, StaticShape, Trigger, TSStatic, FlyingVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, InteriorMap, MirrorSubObject, PathedInterior, sgLightObject, sgMissionLightingFilter, volumeLight, SceneObject, Marker, Sky, Sun, TerrainBlock, and WaterBlock.

bool NetObject::onAdd ( ) [virtual]

Called when the object is added to the sim.

Reimplemented from SimObject.

Reimplemented in AudioEmitter, Camera, Debris, FireballAtmosphere, Explosion, fxFoliageReplicator, fxLight, fxRenderObject, fxShapeReplicator, fxSunLight, Lightning, ParticleEmitterNode, ParticleEmitter, Precipitation, Splash, WeatherLightning, GameBase, Item, MissionArea, MissionMarker, SpawnSphere, PathCamera, PhysicalZone, Player, Projectile, RigidShape, ShapeBase, ShowTSShape, StaticShape, Trigger, TSStatic, FlyingVehicle, HoverVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, InteriorMap, PathedInterior, sgLightObject, sgMissionLightingFilter, volumeLight, SceneObject, Marker, Sky, Sun, TerrainBlock, and WaterBlock.

void NetObject::onRemove ( ) [virtual]

Called when the object is removed from the sim.

Reimplemented from SimObject.

Reimplemented in AudioEmitter, Camera, Debris, FireballAtmosphere, Explosion, fxFoliageReplicator, fxLight, fxRenderObject, fxShapeReplicator, fxSunLight, Lightning, ParticleEmitterNode, ParticleEmitter, Precipitation, Splash, WeatherLightning, GameBase, Item, MissionMarker, PathCamera, PhysicalZone, Player, Projectile, RigidShape, ShapeBase, ShowTSShape, StaticShape, Trigger, TSStatic, FlyingVehicle, HoverVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, InteriorMap, PathedInterior, sgMissionLightingFilter, volumeLight, SceneObject, Marker, Sky, TerrainBlock, and WaterBlock.

static void NetObject::collapseDirtyList ( ) [static]

void NetObject::setMaskBits ( U32 orMask )

Used to mark a bit as dirty; ie, that its corresponding set of fields need to be transmitted next update.

Parameters:

orMask

Bit(s) to set

void NetObject::clearMaskBits ( U32 orMask )

Clear the specified bits from the dirty mask.

Parameters:

orMask

Bits to clear

void NetObject::setScopeAlways ( )

Scope the object to all connections.

The object is marked as ScopeAlways and is immediately ghosted to all active connections. This function has no effect if the object is not marked as Ghostable.

void NetObject::clearScopeAlways ( )

Stop scoping the object to all connections.

The object's ScopeAlways flag is cleared and the object is removed from all current active connections.

virtual F32 NetObject::getUpdatePriority	(	CameraScopeQuery *	focusObject,
		U32	updateMask,
		S32	updateSkips
	)			`[virtual]`

This returns a value which is used to prioritize which objects need to be updated.

In NetObject, our returned priority is 0.1 * updateSkips, so that less recently updated objects are more likely to be updated.

In subclasses, this can be adjusted. For instance, ShapeBase provides priority based on proximity to the camera.

Parameters:

	focusObject	Information from a previous call to onCameraScopeQuery.
	updateMask	Current update mask.
	updateSkips	Number of ticks we haven't been updated for.

Returns:: A floating point value indicating priority. These are typically < 5.0.

Reimplemented in GameBase, Projectile, and ShapeBase.

virtual U32 NetObject::packUpdate	(	NetConnection *	conn,
		U32	mask,
		BitStream *	stream
	)			`[virtual]`

Instructs this object to pack its state for transfer over the network.

Parameters:

	conn	Net connection being used
	mask	Mask indicating fields to transmit.
	stream	Bitstream to pack data to

Returns:: Any bits which were not dealt with. The value is stored by the networking system. Don't set bits you weren't passed.

Reimplemented in AudioEmitter, Camera, FireballAtmosphere, fxFoliageReplicator, fxLight, fxRenderObject, fxShapeReplicator, fxSunLight, Lightning, ParticleEmitterNode, Precipitation, Splash, WeatherLightning, GameBase, Item, MissionArea, MissionMarker, SpawnSphere, PathCamera, PhysicalZone, Player, Projectile, RigidShape, ShapeBase, StaticShape, Trigger, TSStatic, FlyingVehicle, HoverVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, InteriorMap, PathedInterior, sgLightObject, sgMissionLightingFilter, volumeLight, Marker, Sky, Sun, TerrainBlock, and WaterBlock.

virtual void NetObject::unpackUpdate	(	NetConnection *	conn,
		BitStream *	stream
	)			`[virtual]`

Instructs this object to read state data previously packed with packUpdate.

Parameters:

	conn	Net connection being used
	stream	stream to read from

virtual void NetObject::onCameraScopeQuery	(	NetConnection *	cr,
		CameraScopeQuery *	camInfo
	)			`[virtual]`

Queries the object about information used to determine scope.

Something that is 'in scope' is somehow interesting to the client.

If we are a NetConnection's scope object, it calls this method to determine how things should be scoped; basically, we tell it our field of view with camInfo, and have the opportunity to manually mark items as "in scope" as we see fit.

By default, we just mark all ghostable objects as in scope.

Parameters:

	cr	Net connection requesting scope information.
	camInfo	Information about what this object can see.

Reimplemented in Player, and ShapeBase.

U32 NetObject::getNetIndex ( ) [inline]

Get the ghost index of this object.

bool NetObject::isServerObject ( ) const [inline]

Is this a server object?

bool NetObject::isClientObject ( ) const [inline]

Is this a client object?

bool NetObject::isGhost ( ) const [inline]

Is this is a ghost?

bool NetObject::isScopeLocal ( ) const [inline]

Should this object only be visible to the client which created it?

bool NetObject::isScopeable ( ) const [inline]

Is this object subject to scoping?

bool NetObject::isGhostable ( ) const [inline]

Is this object ghostable?

bool NetObject::isGhostAlways ( ) const [inline]

Should this object always be ghosted?

Friends And Related Function Documentation

friend class NetConnection [friend]

friend struct GhostInfo [friend]

friend class ProcessList [friend]

Reimplemented in GameBase.

friend class GhostAlwaysObjectEvent [friend]

Field Documentation

U32 NetObject::mDirtyMaskBits [private]

Mask indicating which states are dirty and need to be retransmitted on this object.

NetObject* NetObject::mDirtyList [static, private]

Static pointer to the head of the dirty NetObject list.

NetObject* NetObject::mPrevDirtyList [private]

Next item in the dirty list...

NetObject* NetObject::mNextDirtyList [private]

Previous item in the dirty list...

SimObjectPtr<NetObject> NetObject::mServerObject [protected]

Pointer to the server object; used only when we are doing "short-circuited" networking.

When we are running with client and server on the same system (which can happen be either when we are doing a single player game, or if we're hosting a multiplayer game and having someone playing on the same instance), we can do some short circuited code to enhance performance.

This variable is used to make it simpler; if we are running in short-circuited mode, it's set to the object on the server that this NetObject is ghosting.

Note:: "Premature optimization is the root of all evil" - Donald Knuth. The current codebase uses this feature in three small places, mostly for non-speed-related purposes.

BitSet32 NetObject::mNetFlags [protected]

Flag values from NetFlags.

U32 NetObject::mNetIndex [protected]

The index of this ghost in the GhostManager on the server.

GhostInfo* NetObject::mFirstObjectRef [protected]

Head of a linked list storing GhostInfos referencing this NetObject.