RakNet  4.0
Public Member Functions | Protected Member Functions | List of all members
RakNet::ReplicaManager3 Class Referenceabstract

System to help automate game object construction, destruction, and serialization. More...

#include <ReplicaManager3.h>

Inheritance diagram for RakNet::ReplicaManager3:
RakNet::PluginInterface2

Public Member Functions

virtual Connection_RM3AllocConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID) const =0
 Implement to return a game specific derivation of Connection_RM3.
 
virtual void DeallocConnection (Connection_RM3 *connection) const =0
 Implement to destroy a class instanced returned by AllocConnection()
 
void SetAutoManageConnections (bool autoCreate, bool autoDestroy)
 Enable or disable automatically assigning connections to new instances of Connection_RM3.
 
bool GetAutoCreateConnections (void) const
 
bool GetAutoDestroyConnections (void) const
 
void AutoCreateConnectionList (DataStructures::List< RakNetGUID > &participantListIn, DataStructures::List< Connection_RM3 * > &participantListOut, WorldId worldId=0)
 Call AllocConnection() and PushConnection() for each connection in participantList.
 
bool PushConnection (RakNet::Connection_RM3 *newConnection, WorldId worldId=0)
 Track a new Connection_RM3 instance.
 
RakNet::Connection_RM3PopConnection (RakNetGUID guid, WorldId worldId=0)
 Stop tracking a connection.
 
void Reference (RakNet::Replica3 *replica3, WorldId worldId=0)
 Adds a replicated object to the system.
 
void Dereference (RakNet::Replica3 *replica3, WorldId worldId=0)
 Removes a replicated object from the system.
 
void DereferenceList (DataStructures::List< Replica3 * > &replicaListIn, WorldId worldId=0)
 Removes multiple replicated objects from the system.
 
void GetReplicasCreatedByGuid (RakNetGUID guid, DataStructures::List< Replica3 * > &replicaListOut, WorldId worldId=0)
 Returns all objects originally created by a particular system.
 
void GetReplicasCreatedByMe (DataStructures::List< Replica3 * > &replicaListOut, WorldId worldId=0)
 Returns all objects originally created by your system.
 
void GetReferencedReplicaList (DataStructures::List< Replica3 * > &replicaListOut, WorldId worldId=0)
 Returns the entire list of Replicas that we know about.
 
unsigned GetReplicaCount (WorldId worldId=0) const
 Returns the number of replicas known about.
 
Replica3GetReplicaAtIndex (unsigned index, WorldId worldId=0)
 Returns a replica by index.
 
unsigned int GetConnectionCount (WorldId worldId=0) const
 Returns the number of connections.
 
Connection_RM3GetConnectionAtIndex (unsigned index, WorldId worldId=0) const
 Returns a connection pointer previously added with PushConnection()
 
Connection_RM3GetConnectionBySystemAddress (const SystemAddress &sa, WorldId worldId=0) const
 Returns a connection pointer previously added with PushConnection()
 
Connection_RM3GetConnectionByGUID (RakNetGUID guid, WorldId worldId=0) const
 Returns a connection pointer previously added with PushConnection.()
 
void SetDefaultOrderingChannel (char def)
 
void SetDefaultPacketPriority (PacketPriority def)
 
void SetDefaultPacketReliability (PacketReliability def)
 
void SetAutoSerializeInterval (RakNet::Time intervalMS)
 
void GetConnectionsThatHaveReplicaConstructed (Replica3 *replica, DataStructures::List< Connection_RM3 * > &connectionsThatHaveConstructedThisReplica, WorldId worldId=0)
 Return the connections that we think have an instance of the specified Replica3 instance.
 
bool GetAllConnectionDownloadsCompleted (WorldId worldId=0) const
 Returns if GetDownloadWasCompleted() returns true for all connections.
 
void AddWorld (WorldId worldId)
 ReplicaManager3 can support multiple worlds, where each world has a separate NetworkIDManager, list of connections, replicas, etc A world with id 0 is created automatically. If you want multiple worlds, use this function, and ReplicaManager3::SetNetworkIDManager() to have a different NetworkIDManager instance per world.
 
void RemoveWorld (WorldId worldId)
 Deallocate a world added with AddWorld, or the default world with id 0 Deallocating a world will also stop tracking and updating all connections and replicas associated with that world.
 
WorldId GetWorldIdAtIndex (unsigned int index)
 Get one of the WorldId values added with AddWorld()
 
unsigned int GetWorldCount (void) const
 Returns the number of world id specifiers in memory, added with AddWorld() and removed with RemoveWorld()
 
void SetNetworkIDManager (NetworkIDManager *_networkIDManager, WorldId worldId=0)
 
NetworkIDManagerGetNetworkIDManager (WorldId worldId=0) const
 
void BroadcastDestructionList (DataStructures::List< Replica3 * > &replicaListSource, const SystemAddress &exclusionAddress, WorldId worldId=0)
 
virtual void Update (void)
 Call interfaces, send data.
 
- Public Member Functions inherited from RakNet::PluginInterface2
virtual void OnAttach (void)
 Called when the interface is attached.
 
virtual void OnRakPeerStartup (void)
 Called when RakPeer is initialized.
 
virtual void OnFailedConnectionAttempt (Packet *packet, PI2_FailedConnectionAttemptReason failedConnectionAttemptReason)
 
virtual bool UsesReliabilityLayer (void) const
 
virtual void OnDirectSocketSend (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 
virtual void OnDirectSocketReceive (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 
virtual void OnReliabilityLayerNotification (const char *errorMessage, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress, bool isError)
 
virtual void OnInternalPacket (InternalPacket *internalPacket, unsigned frameNumber, SystemAddress remoteSystemAddress, RakNet::TimeMS time, int isSend)
 
virtual void OnAck (unsigned int messageNumber, SystemAddress remoteSystemAddress, RakNet::TimeMS time)
 
virtual void OnPushBackPacket (const char *data, const BitSize_t bitsUsed, SystemAddress remoteSystemAddress)
 

Protected Member Functions

virtual PluginReceiveResult OnReceive (Packet *packet)
 
virtual void OnClosedConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, PI2_LostConnectionReason lostConnectionReason)
 
virtual void OnNewConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, bool isIncoming)
 
virtual void OnRakPeerShutdown (void)
 Called when RakPeer is shutdown.
 
virtual void OnDetach (void)
 Called when the interface is detached.
 

Detailed Description

System to help automate game object construction, destruction, and serialization.

ReplicaManager3 tracks your game objects and automates the networking for replicating them across the network
As objects are created, destroyed, or serialized differently, those changes are pushed out to other systems.
To use:

  1. Derive from Connection_RM3 and implement Connection_RM3::AllocReplica(). This is a factory function where given a user-supplied identifier for a class (such as name) return an instance of that class. Should be able to return any networked object in your game.
  2. Derive from ReplicaManager3 and implement AllocConnection() and DeallocConnection() to return the class you created in step 1.
  3. Derive your networked game objects from Replica3. All pure virtuals have to be implemented, however defaults are provided for Replica3::QueryConstruction(), Replica3::QueryRemoteConstruction(), and Replica3::QuerySerialization() depending on your network architecture.
  4. When a new game object is created on the local system, pass it to ReplicaManager3::Reference().
  5. When a game object is destroyed on the local system, and you want other systems to know about it, call Replica3::BroadcastDestruction()


At this point, all new connections will automatically download, get construction messages, get destruction messages, and update serialization automatically.

Member Function Documentation

void RakNet::ReplicaManager3::AddWorld ( WorldId  worldId)

ReplicaManager3 can support multiple worlds, where each world has a separate NetworkIDManager, list of connections, replicas, etc A world with id 0 is created automatically. If you want multiple worlds, use this function, and ReplicaManager3::SetNetworkIDManager() to have a different NetworkIDManager instance per world.

Parameters
[in]worldIdA unique identifier for this world. User-defined
virtual Connection_RM3* RakNet::ReplicaManager3::AllocConnection ( const SystemAddress systemAddress,
RakNetGUID  rakNetGUID 
) const
pure virtual

Implement to return a game specific derivation of Connection_RM3.

The connection object represents a remote system connected to you that is using the ReplicaManager3 system.
It has functions to perform operations per-connection.
AllocConnection() and DeallocConnection() are factory functions to create and destroy instances of the connection object.
It is used if autoCreate is true via SetAutoManageConnections() (true by default). Otherwise, the function is not called, and you will have to call PushConnection() manually

Note
If you do not want a new network connection to immediately download game objects, SetAutoManageConnections() and PushConnection() are how you do this.
See Also
SetAutoManageConnections()
Parameters
[in]systemAddressAddress of the system you are adding
[in]rakNetGUIDGUID of the system you are adding. See Packet::rakNetGUID or RakPeerInterface::GetGUIDFromSystemAddress()
Returns
The new connection instance.
void RakNet::ReplicaManager3::AutoCreateConnectionList ( DataStructures::List< RakNetGUID > &  participantListIn,
DataStructures::List< Connection_RM3 * > &  participantListOut,
WorldId  worldId = 0 
)

Call AllocConnection() and PushConnection() for each connection in participantList.

Parameters
[in]participantListInThe list of connections to allocate
[in]participantListOutThe connections allocated, if any
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::BroadcastDestructionList ( DataStructures::List< Replica3 * > &  replicaListSource,
const SystemAddress exclusionAddress,
WorldId  worldId = 0 
)

Send a network command to destroy one or more Replica3 instances Usually you won't need this, but use Replica3::BroadcastDestruction() instead. The objects are unaffected locally

Parameters
[in]replicaListList of Replica3 objects to tell other systems to destroy.
[in]exclusionAddressWhich system to not send to. UNASSIGNED_SYSTEM_ADDRESS to send to all.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
virtual void RakNet::ReplicaManager3::DeallocConnection ( Connection_RM3 connection) const
pure virtual

Implement to destroy a class instanced returned by AllocConnection()

Most likely just implement as {delete connection;}
It is used if autoDestroy is true via SetAutoManageConnections() (true by default). Otherwise, the function is not called and you would then be responsible for deleting your own connection objects.

Parameters
[in]connectionThe pointer instance to delete
void RakNet::ReplicaManager3::Dereference ( RakNet::Replica3 replica3,
WorldId  worldId = 0 
)

Removes a replicated object from the system.

The object is not deallocated, it is up to the caller to do so.
This is called automatically from the destructor of Replica3, so you don't need to call it manually unless you want to stop tracking an object before it is destroyed.

Parameters
[in]replica3The object to stop tracking
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::DereferenceList ( DataStructures::List< Replica3 * > &  replicaListIn,
WorldId  worldId = 0 
)

Removes multiple replicated objects from the system.

Same as Dereference(), but for a list of objects.
Useful with the lists returned by GetReplicasCreatedByGuid(), GetReplicasCreatedByMe(), or GetReferencedReplicaList().

Parameters
[in]replicaListInList of objects
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
bool RakNet::ReplicaManager3::GetAllConnectionDownloadsCompleted ( WorldId  worldId = 0) const

Returns if GetDownloadWasCompleted() returns true for all connections.

Parameters
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
True when all downloads have been completed
bool RakNet::ReplicaManager3::GetAutoCreateConnections ( void  ) const
Returns
What was passed to the autoCreate parameter of SetAutoManageConnections()
bool RakNet::ReplicaManager3::GetAutoDestroyConnections ( void  ) const
Returns
What was passed to the autoDestroy parameter of SetAutoManageConnections()
Connection_RM3* RakNet::ReplicaManager3::GetConnectionAtIndex ( unsigned  index,
WorldId  worldId = 0 
) const

Returns a connection pointer previously added with PushConnection()

Parameters
[in]indexAn index, from 0 to GetConnectionCount()-1.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
A Connection_RM3 pointer
Connection_RM3* RakNet::ReplicaManager3::GetConnectionByGUID ( RakNetGUID  guid,
WorldId  worldId = 0 
) const

Returns a connection pointer previously added with PushConnection.()

Parameters
[in]guidThe guid of the connection to return
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
A Connection_RM3 pointer, or 0 if not found
Connection_RM3* RakNet::ReplicaManager3::GetConnectionBySystemAddress ( const SystemAddress sa,
WorldId  worldId = 0 
) const

Returns a connection pointer previously added with PushConnection()

Parameters
[in]saThe system address of the connection to return
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
A Connection_RM3 pointer, or 0 if not found
unsigned int RakNet::ReplicaManager3::GetConnectionCount ( WorldId  worldId = 0) const

Returns the number of connections.

Returns the number of connections added with ReplicaManager3::PushConnection(), minus the number removed with ReplicaManager3::PopConnection()

Parameters
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
The number of registered connections
void RakNet::ReplicaManager3::GetConnectionsThatHaveReplicaConstructed ( Replica3 replica,
DataStructures::List< Connection_RM3 * > &  connectionsThatHaveConstructedThisReplica,
WorldId  worldId = 0 
)

Return the connections that we think have an instance of the specified Replica3 instance.

This can be wrong, for example if that system locally deleted the outside the scope of ReplicaManager3, if QueryRemoteConstruction() returned false, or if DeserializeConstruction() returned false.

Parameters
[in]replicaThe replica to check against.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
[out]connectionsThatHaveConstructedThisReplicaPopulated with connection instances that we believe have replica allocated
NetworkIDManager* RakNet::ReplicaManager3::GetNetworkIDManager ( WorldId  worldId = 0) const

Returns what was passed to SetNetworkIDManager(), or the instance on RakPeerInterface if unset.

Parameters
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::GetReferencedReplicaList ( DataStructures::List< Replica3 * > &  replicaListOut,
WorldId  worldId = 0 
)

Returns the entire list of Replicas that we know about.

This is all Replica3 instances passed to Reference, as well as instances we downloaded and created via Connection_RM3::AllocReference()

Parameters
[out]Listof Replica3 instances to be returned
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Replica3* RakNet::ReplicaManager3::GetReplicaAtIndex ( unsigned  index,
WorldId  worldId = 0 
)

Returns a replica by index.

Returns one of the items in the list that would be returned by GetReferencedReplicaList()

Parameters
[in]indexAn index, from 0 to GetReplicaCount()-1.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
A Replica3 instance
unsigned RakNet::ReplicaManager3::GetReplicaCount ( WorldId  worldId = 0) const

Returns the number of replicas known about.

Returns the size of the list that would be returned by GetReferencedReplicaList()

Parameters
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
Returns
How many replica objects are in the list of replica objects
void RakNet::ReplicaManager3::GetReplicasCreatedByGuid ( RakNetGUID  guid,
DataStructures::List< Replica3 * > &  replicaListOut,
WorldId  worldId = 0 
)

Returns all objects originally created by a particular system.

Originally created is defined as the value of Replica3::creatingSystemGUID, which is automatically assigned in ReplicaManager3::Reference().
You do not have to be directly connected to that system to get the objects originally created by that system.

Parameters
[in]guidGUID of the system we are referring to. Originally passed as the guid parameter to ReplicaManager3::AllocConnection()
[out]Listof Replica3 instances to be returned
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::GetReplicasCreatedByMe ( DataStructures::List< Replica3 * > &  replicaListOut,
WorldId  worldId = 0 
)

Returns all objects originally created by your system.

Calls GetReplicasCreatedByGuid() for your own system guid.

Parameters
[out]Listof Replica3 instances to be returned
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
unsigned int RakNet::ReplicaManager3::GetWorldCount ( void  ) const

Returns the number of world id specifiers in memory, added with AddWorld() and removed with RemoveWorld()

Returns
The number of worlds added
WorldId RakNet::ReplicaManager3::GetWorldIdAtIndex ( unsigned int  index)

Get one of the WorldId values added with AddWorld()

WorldId 0 is created by default. Worlds will not necessarily be in the order added with AddWorld(). Edit RemoveWorld() changing RemoveAtIndexFast() to RemoveAtIndex() to preserve order.

Parameters
[in]indexA value between 0 and GetWorldCount()-1
Returns
One of the WorldId values added with AddWorld()
virtual void RakNet::ReplicaManager3::OnClosedConnection ( const SystemAddress systemAddress,
RakNetGUID  rakNetGUID,
PI2_LostConnectionReason  lostConnectionReason 
)
protectedvirtual

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

Parameters
[in]systemAddressThe system whose connection was closed
[in]rakNetGuidThe guid of the specified system
[in]lostConnectionReasonHow the connection was closed: manually, connection lost, or notification of disconnection

Reimplemented from RakNet::PluginInterface2.

virtual void RakNet::ReplicaManager3::OnNewConnection ( const SystemAddress systemAddress,
RakNetGUID  rakNetGUID,
bool  isIncoming 
)
protectedvirtual

Called when we got a new connection

Parameters
[in]systemAddressAddress of the new connection
[in]rakNetGuidThe guid of the specified system
[in]isIncomingIf true, this is ID_NEW_INCOMING_CONNECTION, or the equivalent

Reimplemented from RakNet::PluginInterface2.

virtual PluginReceiveResult RakNet::ReplicaManager3::OnReceive ( Packet packet)
protectedvirtual

OnReceive is called for every packet.

Parameters
[in]packetthe 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 RakNet::PluginInterface2.

RakNet::Connection_RM3* RakNet::ReplicaManager3::PopConnection ( RakNetGUID  guid,
WorldId  worldId = 0 
)

Stop tracking a connection.

On call, for each replica returned by GetReplicasCreatedByGuid(), QueryActionOnPopConnection() will be called. Depending on the return value, this may delete the corresponding replica.
If autoDestroy is true in the call to SetAutoManageConnections() (true by default) then this is called automatically when the connection is lost. In that case, the returned connection instance is deleted.

Parameters
[in]guidof the connection to get. Passed to ReplicaManager3::AllocConnection() originally.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
bool RakNet::ReplicaManager3::PushConnection ( RakNet::Connection_RM3 newConnection,
WorldId  worldId = 0 
)

Track a new Connection_RM3 instance.

If autoCreate is false for SetAutoManageConnections(), then you need this function to add new instances of Connection_RM3 yourself.
You don't need to track this pointer yourself, you can get it with GetConnectionAtIndex(), GetConnectionByGUID(), or GetConnectionBySystemAddress().

Parameters
[in]newConnectionThe new connection instance to track.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::Reference ( RakNet::Replica3 replica3,
WorldId  worldId = 0 
)

Adds a replicated object to the system.

Anytime you create a new object that derives from Replica3, and you want ReplicaManager3 to use it, pass it to Reference().
Remote systems already connected will potentially download this object the next time ReplicaManager3::Update() is called, which happens every time you call RakPeerInterface::Receive().
You can also call ReplicaManager3::Update() manually to send referenced objects right away

Parameters
[in]replica3The object to start tracking
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()
void RakNet::ReplicaManager3::RemoveWorld ( WorldId  worldId)

Deallocate a world added with AddWorld, or the default world with id 0 Deallocating a world will also stop tracking and updating all connections and replicas associated with that world.

Parameters
[in]worldIdA worldId value previously added with AddWorld()
void RakNet::ReplicaManager3::SetAutoManageConnections ( bool  autoCreate,
bool  autoDestroy 
)

Enable or disable automatically assigning connections to new instances of Connection_RM3.

ReplicaManager3 can automatically create and/or destroy Connection_RM3 as systems connect or disconnect from RakPeerInterface.
By default this is on, to make the system easier to learn and setup.
If you don't want all connections to take part in the game, or you want to delay when a connection downloads the game, set autoCreate to false.
If you want to delay deleting a connection that has dropped, set autoDestroy to false. If you do this, then you must call PopConnection() to remove that connection from being internally tracked. You'll also have to delete the connection instance on your own.

Parameters
[in]autoCreateAutomatically call ReplicaManager3::AllocConnection() for each new connection. Defaults to true. Also see AutoCreateConnectionList()
[in]autoDestroyAutomatically call ReplicaManager3::DeallocConnection() for each dropped connection. Defaults to true.
void RakNet::ReplicaManager3::SetAutoSerializeInterval ( RakNet::Time  intervalMS)

Every intervalMS milliseconds, Connection_RM3::OnAutoserializeInterval() will be called.
Defaults to 30.
Pass with <0 to disable. Pass 0 to Serialize() every time RakPeer::Recieve() is called
If you want to control the update interval with more granularity, use the return values from Replica3::Serialize().

Parameters
[in]intervalMSHow frequently to autoserialize all objects. This controls the maximum number of game object updates per second.
void RakNet::ReplicaManager3::SetDefaultOrderingChannel ( char  def)
Parameters
[in]Defaultordering channel to use for object creation, destruction, and serializations
void RakNet::ReplicaManager3::SetDefaultPacketPriority ( PacketPriority  def)
Parameters
[in]Defaultpacket priority to use for object creation, destruction, and serializations
void RakNet::ReplicaManager3::SetDefaultPacketReliability ( PacketReliability  def)
Parameters
[in]Defaultpacket reliability to use for object creation, destruction, and serializations
void RakNet::ReplicaManager3::SetNetworkIDManager ( NetworkIDManager _networkIDManager,
WorldId  worldId = 0 
)

Sets the networkIDManager instance that this plugin relys upon.
Uses whatever instance is attached to RakPeerInterface if unset.
To support multiple worlds, you should set it to a different manager for each instance of the plugin

Parameters
[in]_networkIDManagerThe externally allocated NetworkIDManager instance for this plugin to use.
[in]worldIdUsed for multiple worlds. World 0 is created automatically by default. See AddWorld()

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