RakNet::ReplicaManager2 Class Reference
[ReplicaManager2]

A management system for your game objects and players to make serialization, scoping, and object creation and destruction easier. More...

#include <ReplicaManager2.h>

Inheritance diagram for RakNet::ReplicaManager2:

PluginInterface2

List of all members.

Public Member Functions

void SetConnectionFactory (Connection_RM2Factory *factory)
void SetDefaultOrderingChannel (char def)
void SetDefaultPacketPriority (PacketPriority def)
void SetDefaultPacketReliability (PacketReliability def)
void SetAutoUpdateScope (bool construction, bool visibility)
void SetAutoAddNewConnections (bool autoAdd)
bool AddNewConnection (SystemAddress systemAddress)
bool RemoveConnection (SystemAddress systemAddress)
bool HasConnection (SystemAddress systemAddress)
void SetDoReplicaAutoSerializeUpdate (bool autoUpdate)
void SendConstruction (Replica2 *replica, BitStream *replicaData, SystemAddress recipient, RakNetTime timestamp, bool sendMessage, DataStructures::OrderedList< SystemAddress, SystemAddress > &exclusionList, unsigned char localClientId, SerializationType type=SEND_CONSTRUCTION_GENERIC_TO_SYSTEM, PacketPriority priority=NUMBER_OF_PRIORITIES, PacketReliability reliability=NUMBER_OF_RELIABILITIES, char orderingChannel=-1)
void SendDestruction (Replica2 *replica, BitStream *replicaData, SystemAddress recipient, RakNetTime timestamp, bool sendMessage, DataStructures::OrderedList< SystemAddress, SystemAddress > &exclusionList, SerializationType type=SEND_DESTRUCTION_GENERIC_TO_SYSTEM, PacketPriority priority=NUMBER_OF_PRIORITIES, PacketReliability reliability=NUMBER_OF_RELIABILITIES, char orderingChannel=-1)
void SendSerialize (Replica2 *replica, BitStream *replicaData, SystemAddress recipient, RakNetTime timestamp, DataStructures::OrderedList< SystemAddress, SystemAddress > &exclusionList, SerializationType type=SEND_SERIALIZATION_GENERIC_TO_SYSTEM, PacketPriority priority=NUMBER_OF_PRIORITIES, PacketReliability reliability=NUMBER_OF_RELIABILITIES, char orderingChannel=-1)
void SendVisibility (Replica2 *replica, BitStream *replicaData, SystemAddress recipient, RakNetTime timestamp, DataStructures::OrderedList< SystemAddress, SystemAddress > &exclusionList, SerializationType type=SEND_VISIBILITY_TRUE_TO_SYSTEM, PacketPriority priority=NUMBER_OF_PRIORITIES, PacketReliability reliability=NUMBER_OF_RELIABILITIES, char orderingChannel=-1)
unsigned GetReplicaCount (void) const
Replica2GetReplicaAtIndex (unsigned index)
unsigned GetConnectionCount (void) const
Connection_RM2GetConnectionAtIndex (unsigned index) const
Connection_RM2GetConnectionBySystemAddress (SystemAddress systemAddress) const
unsigned int GetConnectionIndexBySystemAddress (SystemAddress systemAddress) const
void RecalculateVisibility (Replica2 *replica)
void GetConnectionsWithReplicaConstructed (Replica2 *replica, DataStructures::OrderedList< SystemAddress, Connection_RM2 *, ReplicaManager2::Connection_RM2CompBySystemAddress > &output)
void GetConnectionsWithSerializeVisibility (Replica2 *replica, DataStructures::OrderedList< SystemAddress, Connection_RM2 *, ReplicaManager2::Connection_RM2CompBySystemAddress > &output)
RakPeerInterfaceGetRakPeer (void) const
void Reference (Replica2 *replica, bool *newReference)
void Dereference (Replica2 *replica)

Protected Member Functions

void OnAttach (void)
PluginReceiveResult OnReceive (Packet *packet)
void OnClosedConnection (SystemAddress systemAddress, RakNetGUID rakNetGUID, PI2_LostConnectionReason lostConnectionReason)
void OnRakPeerShutdown (void)
 Called when RakPeer is shutdown.
void Update (void)
 Update is called every time a packet is checked for .
virtual void OnNewConnection (SystemAddress systemAddress, RakNetGUID rakNetGUID, bool isIncoming)


Detailed Description

A management system for your game objects and players to make serialization, scoping, and object creation and destruction easier.

<OL> Create a class that derives from Connection_RM2, implementing the Construct() function. Construct() is a factory function that should return instances of your game objects, given a user-defined identifier. Create a class that derives from Connection_RM2Factory, implementing AllocConnection() and DeallocConnection() to return instances of the class from step 1. Attach ReplicaManager2 as a plugin Call ReplicaManager2::SetConnectionFactory with an instance of the class from step 2. For each of your game classes that use this system, derive from Replica2 and implement SerializeConstruction(), Serialize(), Deserialize(). The output of SerializeConstruction() is sent to Connection_RM2::Construct() When these classes are allocated, call Replica2::SetReplicaManager() with the instance of ReplicaManager2 class created in step 3 (this could be done automatically in the constructor) Creation: Use Replica2::SendConstruction() to create the object remotely, Replica2::SendDestruction() to delete the object remotely. Scoping: Override Replica2::QueryVisibility() and Replica2::QueryConstruction() to return BQR_YES or BQR_NO if an object should be visible and in scope to a given connection. Defaults to BQR_ALWAYS Automatic serialization: Call Replica2::AddAutoSerializeTimer() to automatically call Replica2::Serialize() at intervals, compare this to the last value, and broadcast out the object when the serialized variables change. <>

Precondition:
Call RakPeer::SetNetworkIDManager()

This system is a server or peer: Call NetworkIDManager::SetIsNetworkIDAuthority(true).

This system is a client: Call NetworkIDManager::SetIsNetworkIDAuthority(false).

If peer to peer, NETWORK_ID_SUPPORTS_PEER_TO_PEER should be defined in RakNetDefines.h


Member Function Documentation

bool RakNet::ReplicaManager2::AddNewConnection ( SystemAddress  systemAddress  ) 

If SetAutoAddNewConnections() is false, you need to add connections manually connections are also created implicitly if needed

Parameters:
[in] systemAddress The address of the new system
Returns:
false if the connection already exists

void RakNet::ReplicaManager2::Dereference ( Replica2 replica  ) 

Stops tracking this replica. Call before deleting the Replica. Done automatically in ~Replica()

Connection_RM2* RakNet::ReplicaManager2::GetConnectionAtIndex ( unsigned  index  )  const

Returns a connection pointer previously implicitly added.

Parameters:
[in] index An index, from 0 to GetConnectionCount()-1.
Returns:
A Connection_RM2 pointer

Connection_RM2* RakNet::ReplicaManager2::GetConnectionBySystemAddress ( SystemAddress  systemAddress  )  const

Returns a connection pointer previously implicitly added.

Parameters:
[in] systemAddress The system address of the connection to return
Returns:
A Connection_RM2 pointer

unsigned RakNet::ReplicaManager2::GetConnectionCount ( void   )  const

Returns the number of registered connections. Connections are registered implicitly when used. Connections are unregistered on disconnect.

Returns:
The number of registered connections

unsigned int RakNet::ReplicaManager2::GetConnectionIndexBySystemAddress ( SystemAddress  systemAddress  )  const

Returns the index of a connection, by SystemAddress

Parameters:
[in] systemAddress The system address of the connection index to return
Returns:
The connection index, or -1 if no such connection

void RakNet::ReplicaManager2::GetConnectionsWithReplicaConstructed ( Replica2 replica,
DataStructures::OrderedList< SystemAddress, Connection_RM2 *, ReplicaManager2::Connection_RM2CompBySystemAddress > &  output 
)

Given a replica instance, return all connections that are believed to have this replica instantiated.

Parameters:
[in] replica Which replica is being refered to
[out] output List of connections, ordered by system address

void RakNet::ReplicaManager2::GetConnectionsWithSerializeVisibility ( Replica2 replica,
DataStructures::OrderedList< SystemAddress, Connection_RM2 *, ReplicaManager2::Connection_RM2CompBySystemAddress > &  output 
)

Given a replica instance, return all connections that are believed to have this replica visible

Parameters:
[in] replica Which replica is being refered to
[out] output List of connections, ordered by system address

RakPeerInterface* RakNet::ReplicaManager2::GetRakPeer ( void   )  const

Gets the instance of RakPeerInterface that this plugin was attached to

Returns:
The instance of RakPeerInterface that this plugin was attached to

Replica2* RakNet::ReplicaManager2::GetReplicaAtIndex ( unsigned  index  ) 

Returns a previously registered Replica2 *, from index 0 to GetReplicaCount()-1. Replica2* objects are returned in the order they were registered.

Parameters:
[in] index An index, from 0 to GetReplicaCount()-1.
Returns:
A Replica2 pointer

unsigned RakNet::ReplicaManager2::GetReplicaCount ( void   )  const

Returns how many Replica2 instances are registered. Replica2 instances are automatically registered when used, and unregistered when calling Deref (which is automatically done in the destructor). Used for GetReplicaAtIndex if you want to perform some object on all registered Replica objects.

Returns:
How many replica objects are in the list of replica objects

bool RakNet::ReplicaManager2::HasConnection ( SystemAddress  systemAddress  ) 

Is this connection registered with the system?

Parameters:
[in] systemAddress The address of the system to check
Returns:
true if this address is registered, false otherwise

void RakNet::ReplicaManager2::OnAttach ( void   )  [protected, virtual]

Called when the interface is attached

Parameters:
[in] peer the instance of RakPeer that is calling Receive

Reimplemented from PluginInterface2.

void RakNet::ReplicaManager2::OnClosedConnection ( SystemAddress  systemAddress,
RakNetGUID  rakNetGUID,
PI2_LostConnectionReason  lostConnectionReason 
) [protected, virtual]

Called when a connection is dropped because the user called RakPeer::CloseConnection() for a particular system

Parameters:
[in] systemAddress The system whose connection was closed
[in] rakNetGuid The guid of the specified system
[in] lostConnectionReason How the connection was closed: manually, connection lost, or notification of disconnection

Reimplemented from PluginInterface2.

virtual void RakNet::ReplicaManager2::OnNewConnection ( SystemAddress  systemAddress,
RakNetGUID  rakNetGUID,
bool  isIncoming 
) [protected, virtual]

Called when we got a new connection

Parameters:
[in] systemAddress Address of the new connection
[in] rakNetGuid The guid of the specified system
[in] isIncoming If true, this is ID_NEW_INCOMING_CONNECTION, or the equivalent

Reimplemented from PluginInterface2.

PluginReceiveResult RakNet::ReplicaManager2::OnReceive ( Packet packet  )  [protected, virtual]

OnReceive is called for every packet.

Parameters:
[in] packet the packet that is being returned to the user
Returns:
True to allow the game and other plugins to get this message, false to absorb it

Reimplemented from PluginInterface2.

void RakNet::ReplicaManager2::RecalculateVisibility ( Replica2 replica  ) 

Call this when Replica2::QueryVisibility() or Replica2::QueryConstructionVisibility() changes from BQR_ALWAYS or BQR_NEVER to BQR_YES or BQR_NO Otherwise these two conditions are assumed to never change

Parameters:
[in] Which replica to update

void RakNet::ReplicaManager2::Reference ( Replica2 replica,
bool *  newReference 
)

Internally starts tracking this replica

bool RakNet::ReplicaManager2::RemoveConnection ( SystemAddress  systemAddress  ) 

Remove an existing connection. Also done automatically on ID_DISCONNECTION_NOTIFICATION and ID_CONNECTION_LOST

Parameters:
[in] systemAddress The address of the system to remove the connection for
Returns:
false if the connection does not exist

void RakNet::ReplicaManager2::SendConstruction ( Replica2 replica,
BitStream replicaData,
SystemAddress  recipient,
RakNetTime  timestamp,
bool  sendMessage,
DataStructures::OrderedList< SystemAddress, SystemAddress > &  exclusionList,
unsigned char  localClientId,
SerializationType  type = SEND_CONSTRUCTION_GENERIC_TO_SYSTEM,
PacketPriority  priority = NUMBER_OF_PRIORITIES,
PacketReliability  reliability = NUMBER_OF_RELIABILITIES,
char  orderingChannel = -1 
)

Sends a construction command to one or more systems, which will be relayed throughout the network. Recipient(s) will allocate the connection via Connection_RM2Factory::AllocConnection() if it does not already exist. Will trigger a call on the remote system(s) to Connection_RM2::Construct()

Note:
If using peer-to-peer, NETWORK_ID_SUPPORTS_PEER_TO_PEER should be defined in RakNetDefines.h.

This is a low level function. Beginners may wish to use Replica2::SendConstruction() or Replica2::BroadcastConstruction(). You can also override Replica2::QueryConstruction()

Parameters:
[in] replica The class to construct remotely
[in] replicaData User-defined serialized data representing how to construct the class. Could be the name of the class, a unique identifier, or other methods
[in] recipient Which system to send to. Use UNASSIGNED_SYSTEM_ADDRESS to send to all previously created connections. Connection_RM2Factory::AllocConnection will be called if this connection has not been previously used.
[in] timestamp Timestamp to send with the message. Use 0 to not send a timestamp if you don't need it.
[in] sendMessage True to actually send a network message. False to only register that the object exists on the remote system, useful for objects created outside ReplicaManager2, or objects that already existed in the world.
[in] exclusionList Which systems to not send to. This list is carried with the messsage, and appended to at each node in the connection graph. This is used to prevent infinite cyclical sends.
[in] localClientId If replica->QueryIsConstructionAuthority()==false, this number will be sent with SEND_CONSTRUCTION_REQUEST_TO_SERVER to the recipient. SEND_CONSTRUCTION_REPLY_ACCEPTED_TO_CLIENT or SEND_CONSTRUCTION_REPLY_DENIED_TO_CLIENT will be returned, and this number will be used to look up the local object in Replica2::clientPtrArray
[in] type What kind of serialization operation this is. Use one of the pre-defined types, or create your own. This will be returned in type in Connection_RM2::Construct()
[in] priority PacketPriority to send with. Use NUMBER_OF_PRIORITIES to use the default defined by SetDefaultPacketPriority().
[in] reliability PacketReliability to send with. Use NUMBER_OF_RELIABILITIES to use the default defined by SetDefaultPacketReliability();
[in] orderingChannel ordering channel to send on. Use -1 to use the default defined by SetDefaultOrderingChannel()
Precondition:
Call SetConnectionFactory() with a derived instance of Connection_RM2Factory.

void RakNet::ReplicaManager2::SendDestruction ( Replica2 replica,
BitStream replicaData,
SystemAddress  recipient,
RakNetTime  timestamp,
bool  sendMessage,
DataStructures::OrderedList< SystemAddress, SystemAddress > &  exclusionList,
SerializationType  type = SEND_DESTRUCTION_GENERIC_TO_SYSTEM,
PacketPriority  priority = NUMBER_OF_PRIORITIES,
PacketReliability  reliability = NUMBER_OF_RELIABILITIES,
char  orderingChannel = -1 
)

Sends a destruction command to one or more systems, which will be relayed throughout the network. Recipient(s) will allocate the connection via Connection_RM2Factory::AllocConnection() if it does not already exist. Will trigger a call on the remote system(s) to Replica2::ReceiveDestruction() which in turn calls Replica2::DeserializeDestruction() with the value passed in replicaData Note: This is a low level function. Beginners may wish to use Replica2::SendDestruction() or Replica2::BroadcastDestruction().

Parameters:
[in] replica The class to destroy remotely
[in] replicaData User-defined serialized data. Passed to Replica2::ReceiveDestruction()
[in] recipient Which system to send to. Use UNASSIGNED_SYSTEM_ADDRESS to send to all previously created connections. Connection_RM2Factory::AllocConnection will be called if this connection has not been previously used.
[in] timestamp Timestamp to send with the message. Use 0 to not send a timestamp if you don't need it.
[in] sendMessage True to actually send a network message. False to only register that the object no longer exists on the remote system.
[in] exclusionList Which systems to not send to. This list is carried with the messsage, and appended to at each node in the connection graph. This is used to prevent infinite cyclical sends.
[in] type What kind of serialization operation this is. Use one of the pre-defined types, or create your own. This will be returned in type in Connection_RM2::Construct()
[in] priority PacketPriority to send with. Use NUMBER_OF_PRIORITIES to use the default defined by SetDefaultPacketPriority().
[in] reliability PacketReliability to send with. Use NUMBER_OF_RELIABILITIES to use the default defined by SetDefaultPacketReliability();
[in] orderingChannel ordering channel to send on. Use -1 to use the default defined by SetDefaultOrderingChannel()
Precondition:
Replica::QueryIsDestructionAuthority() must return true

Call SetConnectionFactory() with a derived instance of Connection_RM2Factory.

void RakNet::ReplicaManager2::SendSerialize ( Replica2 replica,
BitStream replicaData,
SystemAddress  recipient,
RakNetTime  timestamp,
DataStructures::OrderedList< SystemAddress, SystemAddress > &  exclusionList,
SerializationType  type = SEND_SERIALIZATION_GENERIC_TO_SYSTEM,
PacketPriority  priority = NUMBER_OF_PRIORITIES,
PacketReliability  reliability = NUMBER_OF_RELIABILITIES,
char  orderingChannel = -1 
)

Sends a serialized object to one or more systems, which will be relayed throughout the network. Recipient(s) will allocate the connection via Connection_RM2Factory::AllocConnection() if it does not already exist. Will trigger a call on the remote system(s) to Replica2::ReceiveSerialization() which in turn calls Replica2::Deserialize() with the value passed in replicaData Note: This is a low level function. Beginners may wish to use Replica2::SendSerialize() or Replica2::BroadcastSerialize().

Parameters:
[in] replica The class to serialize
[in] replicaData User-defined serialized data. Passed to Replica2::ReceiveSerialization()
[in] recipient Which system to send to. Use UNASSIGNED_SYSTEM_ADDRESS to send to all previously created connections. Connection_RM2Factory::AllocConnection will be called if this connection has not been previously used.
[in] timestamp Timestamp to send with the message. Use 0 to not send a timestamp if you don't need it.
[in] exclusionList Which systems to not send to. This list is carried with the messsage, and appended to at each node in the connection graph. This is used to prevent infinite cyclical sends.
[in] type What kind of serialization operation this is. Use one of the pre-defined types, or create your own. This will be returned in type in Connection_RM2::Construct()
[in] priority PacketPriority to send with. Use NUMBER_OF_PRIORITIES to use the default defined by SetDefaultPacketPriority().
[in] reliability PacketReliability to send with. Use NUMBER_OF_RELIABILITIES to use the default defined by SetDefaultPacketReliability();
[in] orderingChannel ordering channel to send on. Use -1 to use the default defined by SetDefaultOrderingChannel()
Precondition:
Replica::QueryIsSerializationAuthority() must return true

Call SetConnectionFactory() with a derived instance of Connection_RM2Factory.

void RakNet::ReplicaManager2::SendVisibility ( Replica2 replica,
BitStream replicaData,
SystemAddress  recipient,
RakNetTime  timestamp,
DataStructures::OrderedList< SystemAddress, SystemAddress > &  exclusionList,
SerializationType  type = SEND_VISIBILITY_TRUE_TO_SYSTEM,
PacketPriority  priority = NUMBER_OF_PRIORITIES,
PacketReliability  reliability = NUMBER_OF_RELIABILITIES,
char  orderingChannel = -1 
)

Sets the visibility status of an object. which will be relayed throughout the network. Objects that are not visible should be hidden in the game world, and will not send AutoSerialize updates Recipient(s) will allocate the connection via Connection_RM2Factory::AllocConnection() if it does not already exist. Will trigger a call on the remote system(s) to Connection_RM2::ReceiveVisibility() Note: This is a low level function. Beginners may wish to use Connection_RM2::SendVisibility() or override Replica2::QueryVisibility()

Parameters:
[in] objectList The objects to send to the system.
[in] replicaData User-defined serialized data. Read in Connection_RM2::ReceiveVisibility()
[in] recipient Which system to send to. Use UNASSIGNED_SYSTEM_ADDRESS to send to all previously created connections. Connection_RM2Factory::AllocConnection will be called if this connection has not been previously used.
[in] timestamp Timestamp to send with the message. Use 0 to not send a timestamp if you don't need it.
[in] sendMessage True to actually send a network message. False to only register that the objects exist on the remote system
[in] type What kind of serialization operation this is. Use one of the pre-defined types, or create your own. This will be returned in type in Connection_RM2::Construct()
[in] priority PacketPriority to send with. Use NUMBER_OF_PRIORITIES to use the default defined by SetDefaultPacketPriority().
[in] reliability PacketReliability to send with. Use NUMBER_OF_RELIABILITIES to use the default defined by SetDefaultPacketReliability();
[in] orderingChannel ordering channel to send on. Use -1 to use the default defined by SetDefaultOrderingChannel()
Precondition:
Replica::QueryIsConstructionAuthority() must return true

Call SetConnectionFactory() with a derived instance of Connection_RM2Factory.

void RakNet::ReplicaManager2::SetAutoAddNewConnections ( bool  autoAdd  ) 

Autoadd will cause a Connection_RM2 instance to be allocated for every connection. Defaults to true. Set this to false if you have connections which do not participate in the game (master server, etc).

Parameters:
[in] autoAdd If true, all incoming connections are added as ReplicaManager2 connections.

void RakNet::ReplicaManager2::SetAutoUpdateScope ( bool  construction,
bool  visibility 
)

Auto scope will track the prior construction and serialization visibility of each registered Replica2 class, for each connection. Per-tick, as the visibility or construction status of a replica changes, it will be constructed, destroyed, or the visibility will change as appropriate.

Parameters:
[in] construction If true, Connection_RM2::SetConstructionByReplicaQuery will be called once per PluginInterface::Update tick. This will call Replica2::QueryConstruction to return if an object should be exist on a particular connection
[in] visibility If true, Connection_RM2::SetConstructionSerializationByReplicaQuery will be called once per PluginInterface::Update tick. This will call Replica2::QuerySerialization to return if an object should be visible to a particular connection or not.

void RakNet::ReplicaManager2::SetConnectionFactory ( Connection_RM2Factory factory  ) 

Sets the factory class used to allocate connection objects

Parameters:
[in] factory A pointer to an instance of a class that derives from Connection_RM2Factory. This pointer it saved and not copied, so the object should remain in memory.

void RakNet::ReplicaManager2::SetDefaultOrderingChannel ( char  def  ) 

Parameters:
[in] Default ordering channel to use when passing -1 to a function that takes orderingChannel as a parameter

void RakNet::ReplicaManager2::SetDefaultPacketPriority ( PacketPriority  def  ) 

Parameters:
[in] Default packet priority to use when passing NUMBER_OF_PRIORITIES to a function that takes priority as a parameter

void RakNet::ReplicaManager2::SetDefaultPacketReliability ( PacketReliability  def  ) 

Parameters:
[in] Default packet reliability to use when passing NUMBER_OF_RELIABILITIES to a function that takes reliability as a parameter

void RakNet::ReplicaManager2::SetDoReplicaAutoSerializeUpdate ( bool  autoUpdate  ) 

If true, autoserialize timers added with Replica2::AddAutoSerializeTimer() will automatically decrement. If false, you must call Replica2::ElapseAutoSerializeTimers() manually. Defaults to true

Parameters:
[in] autoUpdate True to automatically call ElapseAutoSerializeTimers(). Set to false if you need to control these timers.


The documentation for this class was generated from the following file:

Generated on Fri Jul 22 08:28:36 2011 for RakNet by  doxygen 1.5.7.1