404 lines
16 KiB
C++
Executable File
404 lines
16 KiB
C++
Executable File
//-----------------------------------------------------------------------------
|
|
// Torque Game Engine
|
|
// Copyright (C) GarageGames.com, Inc.
|
|
//-----------------------------------------------------------------------------
|
|
|
|
#ifndef _NETOBJECT_H_
|
|
#define _NETOBJECT_H_
|
|
|
|
#ifndef _SIMBASE_H_
|
|
#include "console/simBase.h"
|
|
#endif
|
|
#ifndef _MMATH_H_
|
|
#include "math/mMath.h"
|
|
#endif
|
|
|
|
|
|
//-----------------------------------------------------------------------------
|
|
class NetConnection;
|
|
class NetObject;
|
|
|
|
//-----------------------------------------------------------------------------
|
|
|
|
struct CameraScopeQuery
|
|
{
|
|
NetObject *camera; ///< Pointer to the viewing object.
|
|
Point3F pos; ///< Position in world space
|
|
Point3F orientation; ///< Viewing vector in world space
|
|
F32 fov; ///< Viewing angle/2
|
|
F32 sinFov; ///< sin(fov/2);
|
|
F32 cosFov; ///< cos(fov/2);
|
|
F32 visibleDistance; ///< Visible distance.
|
|
};
|
|
|
|
struct GhostInfo;
|
|
|
|
|
|
//-----------------------------------------------------------------------------
|
|
/// Superclass for ghostable networked objects.
|
|
///
|
|
/// @section NetObject_intro 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.
|
|
///
|
|
/// @section NetObject_Implementation 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:
|
|
///
|
|
/// @code
|
|
/// class SimpleNetObject : public NetObject
|
|
/// {
|
|
/// public:
|
|
/// typedef NetObject Parent;
|
|
/// DECLARE_CONOBJECT(SimpleNetObject);
|
|
/// @endcode
|
|
///
|
|
/// Above is the standard boilerplate code for a Torque class. You can find out more about this in SimObject.
|
|
///
|
|
/// @code
|
|
/// char message1[256];
|
|
/// char message2[256];
|
|
/// enum States {
|
|
/// Message1Mask = BIT(0),
|
|
/// Message2Mask = BIT(1),
|
|
/// };
|
|
/// @endcode
|
|
///
|
|
/// 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.)
|
|
///
|
|
/// @code
|
|
/// 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!");
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @code
|
|
/// 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;
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @code
|
|
/// 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);
|
|
/// }
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @code
|
|
/// void setMessage1(const char *msg)
|
|
/// {
|
|
/// setMaskBits(Message1Mask);
|
|
/// dStrcpy(message1, msg);
|
|
/// }
|
|
/// void setMessage2(const char *msg)
|
|
/// {
|
|
/// setMaskBits(Message2Mask);
|
|
/// dStrcpy(message2, msg);
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @code
|
|
/// 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]);
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @nosubgrouping
|
|
class NetObject: public SimObject
|
|
{
|
|
// The Ghost Manager needs read/write access
|
|
friend class NetConnection;
|
|
friend struct GhostInfo;
|
|
friend class ProcessList;
|
|
|
|
// Not the best way to do this, but the event needs access to mNetFlags
|
|
friend class GhostAlwaysObjectEvent;
|
|
|
|
private:
|
|
typedef SimObject Parent;
|
|
|
|
/// Mask indicating which states are dirty and need to be retransmitted on this
|
|
/// object.
|
|
U32 mDirtyMaskBits;
|
|
|
|
/// @name 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.
|
|
/// @{
|
|
|
|
/// Static pointer to the head of the dirty NetObject list.
|
|
static NetObject *mDirtyList;
|
|
|
|
/// Next item in the dirty list...
|
|
NetObject *mPrevDirtyList;
|
|
|
|
/// Previous item in the dirty list...
|
|
NetObject *mNextDirtyList;
|
|
|
|
/// @}
|
|
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.
|
|
SimObjectPtr<NetObject> mServerObject;
|
|
|
|
enum NetFlags
|
|
{
|
|
IsGhost = BIT(1), ///< This is a ghost.
|
|
ScopeAlways = BIT(6), ///< Object always ghosts to clients.
|
|
ScopeLocal = BIT(7), ///< Ghost only to local client.
|
|
Ghostable = BIT(8), ///< Set if this object CAN ghost.
|
|
|
|
MaxNetFlagBit = 15
|
|
};
|
|
|
|
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.
|
|
|
|
public:
|
|
NetObject();
|
|
~NetObject();
|
|
|
|
/// @name Miscellaneous
|
|
/// @{
|
|
DECLARE_CONOBJECT(NetObject);
|
|
static void initPersistFields();
|
|
bool onAdd();
|
|
void onRemove();
|
|
/// @}
|
|
|
|
static void collapseDirtyList();
|
|
|
|
/// Used to mark a bit as dirty; ie, that its corresponding set of fields need to be transmitted next update.
|
|
///
|
|
/// @param orMask Bit(s) to set
|
|
void setMaskBits(U32 orMask);
|
|
|
|
/// Clear the specified bits from the dirty mask.
|
|
///
|
|
/// @param orMask Bits to clear
|
|
void clearMaskBits(U32 orMask);
|
|
|
|
/// 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 setScopeAlways();
|
|
|
|
/// Stop scoping the object to all connections.
|
|
///
|
|
/// The object's ScopeAlways flag is cleared and the object is removed from
|
|
/// all current active connections.
|
|
void clearScopeAlways();
|
|
|
|
/// 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.
|
|
///
|
|
/// @param focusObject Information from a previous call to onCameraScopeQuery.
|
|
/// @param updateMask Current update mask.
|
|
/// @param updateSkips Number of ticks we haven't been updated for.
|
|
/// @returns A floating point value indicating priority. These are typically < 5.0.
|
|
virtual F32 getUpdatePriority(CameraScopeQuery *focusObject, U32 updateMask, S32 updateSkips);
|
|
|
|
/// Instructs this object to pack its state for transfer over the network.
|
|
///
|
|
/// @param conn Net connection being used
|
|
/// @param mask Mask indicating fields to transmit.
|
|
/// @param 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.
|
|
virtual U32 packUpdate(NetConnection * conn, U32 mask, BitStream *stream);
|
|
|
|
/// Instructs this object to read state data previously packed with packUpdate.
|
|
///
|
|
/// @param conn Net connection being used
|
|
/// @param stream stream to read from
|
|
virtual void unpackUpdate(NetConnection * conn, BitStream *stream);
|
|
|
|
/// 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.
|
|
///
|
|
/// @param cr Net connection requesting scope information.
|
|
/// @param camInfo Information about what this object can see.
|
|
virtual void onCameraScopeQuery(NetConnection *cr, CameraScopeQuery *camInfo);
|
|
|
|
/// Get the ghost index of this object.
|
|
U32 getNetIndex() { return mNetIndex; }
|
|
|
|
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?
|
|
};
|
|
|
|
//-----------------------------------------------------------------------------
|
|
|
|
inline bool NetObject::isGhost() const
|
|
{
|
|
return mNetFlags.test(IsGhost);
|
|
}
|
|
|
|
inline bool NetObject::isClientObject() const
|
|
{
|
|
return mNetFlags.test(IsGhost);
|
|
}
|
|
|
|
inline bool NetObject::isServerObject() const
|
|
{
|
|
return !mNetFlags.test(IsGhost);
|
|
}
|
|
|
|
inline bool NetObject::isScopeLocal() const
|
|
{
|
|
return mNetFlags.test(ScopeLocal);
|
|
}
|
|
|
|
inline bool NetObject::isScopeable() const
|
|
{
|
|
return mNetFlags.test(Ghostable) && !mNetFlags.test(ScopeAlways);
|
|
}
|
|
|
|
inline bool NetObject::isGhostable() const
|
|
{
|
|
return mNetFlags.test(Ghostable);
|
|
}
|
|
|
|
inline bool NetObject::isGhostAlways() const
|
|
{
|
|
AssertFatal(mNetFlags.test(Ghostable) || mNetFlags.test(ScopeAlways) == false,
|
|
"That's strange, a ScopeAlways non-ghostable object? Something wrong here");
|
|
return mNetFlags.test(Ghostable) && mNetFlags.test(ScopeAlways);
|
|
}
|
|
|
|
#endif
|