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

#include <ReplicaManager3.h>

Inheritance diagram for RakNet::ReplicaManager3:

Public Member Functions
virtual Connection_RM3 *	AllocConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID) const =0
	Implement to return a game specific derivation of Connection_RM3.
void	BroadcastDestruction (Replica3 *replica, const SystemAddress &exclusionAddress)
void	BroadcastDestructionList (DataStructures::Multilist< ML_STACK, Replica3 * > &replicaList, const SystemAddress &exclusionAddress)
void	Clear (void)
virtual void	DeallocConnection (Connection_RM3 *connection) const =0
	Implement to destroy a class instanced returned by AllocConnection()
void	Dereference (RakNet::Replica3 *replica3)
	Removes a replicated object from the system.
void	DereferenceList (DataStructures::Multilist< ML_STACK, Replica3 * > &replicaListIn)
	Removes multiple replicated objects from the system.
Connection_RM3 *	GetConnectionAtIndex (unsigned index) const
	Returns a connection pointer previously added with PushConnection()
Connection_RM3 *	GetConnectionByGUID (RakNetGUID guid) const
	Returns a connection pointer previously added with PushConnection.()
Connection_RM3 *	GetConnectionBySystemAddress (const SystemAddress &sa) const
	Returns a connection pointer previously added with PushConnection()
DataStructures::DefaultIndexType	GetConnectionCount (void) const
	Returns the number of connections.
void	GetConnectionsThatHaveReplicaConstructed (Replica3 replica, DataStructures::Multilist< ML_STACK, Connection_RM3 > &connectionsThatHaveConstructedThisReplica)
	Return the connections that we think have an instance of the specified Replica3 instance.
PRO	GetDefaultSendParameters (void) const
NetworkIDManager *	GetNetworkIDManager (void) const
	Returns what was passed to SetNetworkIDManager(), or the instance on RakPeerInterface if unset.
void	GetReferencedReplicaList (DataStructures::Multilist< ML_STACK, Replica3 * > &replicaListOut)
	Returns the entire list of Replicas that we know about.
Replica3 *	GetReplicaAtIndex (unsigned index)
	Returns a replica by index.
unsigned	GetReplicaCount (void) const
	Returns the number of replicas known about.
void	GetReplicasCreatedByGuid (RakNetGUID guid, DataStructures::Multilist< ML_STACK, Replica3 * > &replicaListOut)
	Returns all objects originally created by a particular system.
void	GetReplicasCreatedByMe (DataStructures::Multilist< ML_STACK, Replica3 * > &replicaListOut)
	Returns all objects originally created by your system.
unsigned char	GetWorldID (void) const
RakNet::Connection_RM3 *	PopConnection (RakNetGUID guid)
	Stop tracking a connection.
bool	PushConnection (RakNet::Connection_RM3 *newConnection)
	Track a new Connection_RM3 instance.
void	Reference (RakNet::Replica3 *replica3)
	Adds a replicated object to the system.
	ReplicaManager3 ()
void	SetAutoManageConnections (bool autoCreate, bool autoDestroy)
	Enable or disable automatically assigning connections to new instances of Connection_RM3.
void	SetAutoSerializeInterval (RakNet::Time intervalMS)
void	SetDefaultOrderingChannel (char def)
void	SetDefaultPacketPriority (PacketPriority def)
void	SetDefaultPacketReliability (PacketReliability def)
void	SetNetworkIDManager (NetworkIDManager *_networkIDManager)
void	SetWorldID (unsigned char id)
	Defines the unique instance of ReplicaManager3 if multiple instances are on the same instance of RakPeerInterface.
virtual void	Update (void)
	Call interfaces, send data.
virtual	~ReplicaManager3 ()
Protected Member Functions
Replica3 *	GetReplicaByNetworkID (NetworkID networkId)
virtual void	OnClosedConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, PI2_LostConnectionReason lostConnectionReason)
PluginReceiveResult	OnConstruction (Packet packet, unsigned char packetData, int packetDataLength, RakNetGUID senderGuid, unsigned char packetDataOffset)
virtual void	OnDetach (void)
	Called when the interface is detached.
PluginReceiveResult	OnDownloadComplete (Packet packet, unsigned char packetData, int packetDataLength, RakNetGUID senderGuid, unsigned char packetDataOffset)
PluginReceiveResult	OnDownloadStarted (Packet packet, unsigned char packetData, int packetDataLength, RakNetGUID senderGuid, unsigned char packetDataOffset)
virtual void	OnNewConnection (const SystemAddress &systemAddress, RakNetGUID rakNetGUID, bool isIncoming)
virtual void	OnRakPeerShutdown (void)
	Called when RakPeer is shutdown.
virtual PluginReceiveResult	OnReceive (Packet *packet)
PluginReceiveResult	OnSerialize (Packet packet, unsigned char packetData, int packetDataLength, RakNetGUID senderGuid, RakNet::Time timestamp, unsigned char packetDataOffset)
RakNet::Connection_RM3 *	PopConnection (DataStructures::DefaultIndexType index)
DataStructures::DefaultIndexType	ReferenceInternal (RakNet::Replica3 *replica3)
Protected Attributes
bool	autoCreateConnections
bool	autoDestroyConnections
RakNet::Time	autoSerializeInterval
DataStructures::Multilist < ML_STACK, Connection_RM3 * >	connectionList
PRO	defaultSendParameters
RakNet::Time	lastAutoSerializeOccurance
NetworkIDManager *	networkIDManager
DataStructures::Multilist < ML_STACK, Replica3 * >	userReplicaList
unsigned char	worldId
Friends
class	Connection_RM3

Detailed Description

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:

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.
Derive from ReplicaManager3 and implement AllocConnection() and DeallocConnection() to return the class you created in step 1.
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.
When a new game object is created on the local system, pass it to ReplicaManager3::Reference().
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.

Definition at line 68 of file ReplicaManager3.h.

Constructor & Destructor Documentation

RakNet::ReplicaManager3::ReplicaManager3 ( )

virtual RakNet::ReplicaManager3::~ReplicaManager3 ( ) [virtual]

Member Function Documentation

virtual Connection_RM3* RakNet::ReplicaManager3::AllocConnection	(	const SystemAddress &	systemAddress,
		RakNetGUID	rakNetGUID
	)		const `[pure virtual]`

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]	systemAddress	Address of the system you are adding
[in]	rakNetGUID	GUID of the system you are adding. See Packet::rakNetGUID or RakPeerInterface::GetGUIDFromSystemAddress()

Returns:: The new connection instance.

void RakNet::ReplicaManager3::BroadcastDestruction	(	Replica3 *	replica,
		const SystemAddress &	exclusionAddress
	)

void RakNet::ReplicaManager3::BroadcastDestructionList	(	DataStructures::Multilist< ML_STACK, Replica3 * > &	replicaList,
		const SystemAddress &	exclusionAddress
	)

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]	replicaList	List of Replica3 objects to tell other systems to destroy.
[in]	exclusionAddress	Which system to not send to. UNASSIGNED_SYSTEM_ADDRESS to send to all.

void RakNet::ReplicaManager3::Clear ( void )

virtual void RakNet::ReplicaManager3::DeallocConnection ( Connection_RM3 * connection ) const [pure virtual]

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] connection The pointer instance to delete

void RakNet::ReplicaManager3::Dereference ( RakNet::Replica3 * replica3 )

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] replica3 The object to stop tracking

void RakNet::ReplicaManager3::DereferenceList ( DataStructures::Multilist< ML_STACK, Replica3 * > & replicaListIn )

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

Parameters:

[in] replicaListIn List of objects

Connection_RM3* RakNet::ReplicaManager3::GetConnectionAtIndex ( unsigned index ) const

Parameters:

[in] index An index, from 0 to GetConnectionCount()-1.

Returns:: A Connection_RM3 pointer

Connection_RM3* RakNet::ReplicaManager3::GetConnectionByGUID ( RakNetGUID guid ) const

Parameters:

[in] guid The guid of the connection to return

Returns:: A Connection_RM3 pointer, or 0 if not found

Connection_RM3* RakNet::ReplicaManager3::GetConnectionBySystemAddress ( const SystemAddress & sa ) const

Parameters:

[in] sa The system address of the connection to return

Returns:: A Connection_RM3 pointer, or 0 if not found

DataStructures::DefaultIndexType RakNet::ReplicaManager3::GetConnectionCount ( void ) const

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

Returns:: The number of registered connections

void RakNet::ReplicaManager3::GetConnectionsThatHaveReplicaConstructed	(	Replica3 *	replica,
		DataStructures::Multilist< ML_STACK, Connection_RM3 * > &	connectionsThatHaveConstructedThisReplica
	)

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]	replica	The replica to check against.
[out]	connectionsThatHaveConstructedThisReplica	Populated with connection instances that we believe have replica allocated

PRO RakNet::ReplicaManager3::GetDefaultSendParameters ( void ) const

NetworkIDManager* RakNet::ReplicaManager3::GetNetworkIDManager ( void ) const

void RakNet::ReplicaManager3::GetReferencedReplicaList ( DataStructures::Multilist< ML_STACK, Replica3 * > & replicaListOut )

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

Parameters:

[out] List of Replica3 instances to be returned

Replica3* RakNet::ReplicaManager3::GetReplicaAtIndex ( unsigned index )

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

Parameters:

[in] index An index, from 0 to GetReplicaCount()-1.

Returns:: A Replica3 instance

Replica3* RakNet::ReplicaManager3::GetReplicaByNetworkID ( NetworkID networkId ) [protected]

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

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

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

void RakNet::ReplicaManager3::GetReplicasCreatedByGuid	(	RakNetGUID	guid,
		DataStructures::Multilist< ML_STACK, Replica3 * > &	replicaListOut
	)

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]	guid	GUID of the system we are referring to. Originally passed as the guid parameter to ReplicaManager3::AllocConnection()
[out]	List	of Replica3 instances to be returned

void RakNet::ReplicaManager3::GetReplicasCreatedByMe ( DataStructures::Multilist< ML_STACK, Replica3 * > & replicaListOut )

Calls GetReplicasCreatedByGuid() for your own system guid.

Parameters:

[out] List of Replica3 instances to be returned

unsigned char RakNet::ReplicaManager3::GetWorldID ( void ) const

Returns:: Whatever was passed to SetWorldID(), or 0 if it was never called.

virtual void RakNet::ReplicaManager3::OnClosedConnection	(	const 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 RakNet::PluginInterface2.

PluginReceiveResult RakNet::ReplicaManager3::OnConstruction	(	Packet *	packet,
		unsigned char *	packetData,
		int	packetDataLength,
		RakNetGUID	senderGuid,
		unsigned char	packetDataOffset
	)		`[protected]`

virtual void RakNet::ReplicaManager3::OnDetach ( void ) [protected, virtual]

Reimplemented from RakNet::PluginInterface2.

PluginReceiveResult RakNet::ReplicaManager3::OnDownloadComplete	(	Packet *	packet,
		unsigned char *	packetData,
		int	packetDataLength,
		RakNetGUID	senderGuid,
		unsigned char	packetDataOffset
	)		`[protected]`

PluginReceiveResult RakNet::ReplicaManager3::OnDownloadStarted	(	Packet *	packet,
		unsigned char *	packetData,
		int	packetDataLength,
		RakNetGUID	senderGuid,
		unsigned char	packetDataOffset
	)		`[protected]`

virtual void RakNet::ReplicaManager3::OnNewConnection	(	const 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 RakNet::PluginInterface2.

virtual void RakNet::ReplicaManager3::OnRakPeerShutdown ( void ) [protected, virtual]

Reimplemented from RakNet::PluginInterface2.

virtual PluginReceiveResult RakNet::ReplicaManager3::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 RakNet::PluginInterface2.

PluginReceiveResult RakNet::ReplicaManager3::OnSerialize	(	Packet *	packet,
		unsigned char *	packetData,
		int	packetDataLength,
		RakNetGUID	senderGuid,
		RakNet::Time	timestamp,
		unsigned char	packetDataOffset
	)		`[protected]`

RakNet::Connection_RM3* RakNet::ReplicaManager3::PopConnection ( RakNetGUID guid )

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] guid of the connection to get. Passed to ReplicaManager3::AllocConnection() originally.

RakNet::Connection_RM3* RakNet::ReplicaManager3::PopConnection ( DataStructures::DefaultIndexType index ) [protected]

bool RakNet::ReplicaManager3::PushConnection ( RakNet::Connection_RM3 * newConnection )

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] newConnection The new connection instance to track.

void RakNet::ReplicaManager3::Reference ( RakNet::Replica3 * replica3 )

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] replica3 The object to start tracking

DataStructures::DefaultIndexType RakNet::ReplicaManager3::ReferenceInternal ( RakNet::Replica3 * replica3 ) [protected]

void RakNet::ReplicaManager3::SetAutoManageConnections	(	bool	autoCreate,
		bool	autoDestroy
	)

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]	autoCreate	Automatically call ReplicaManager3::AllocConnection() for each new connection. Defaults to true.
[in]	autoDestroy	Automatically 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] intervalMS How frequently to autoserialize all objects. This controls the maximum number of game object updates per second.

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

Parameters:

[in] Default ordering channel to use for object creation, destruction, and serializations

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

Parameters:

[in] Default packet priority to use for object creation, destruction, and serializations

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

Parameters:

[in] Default packet reliability to use for object creation, destruction, and serializations

void RakNet::ReplicaManager3::SetNetworkIDManager ( NetworkIDManager * _networkIDManager )

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] _networkIDManager The externally allocated NetworkIDManager instance for this plugin to use.

void RakNet::ReplicaManager3::SetWorldID ( unsigned char id )

ReplicaManager3 supports multiple instances of itself attached to the same instance of rakPeer, in case your game has multiple worlds.
Call SetWorldID with a different number for each instance.
The default worldID is 0.
To use multiple worlds, you will also need to call ReplicaManager3::SetNetworkIDManager() to have a different NetworkIDManager instance per world

virtual void RakNet::ReplicaManager3::Update ( void ) [virtual]

Reimplemented from RakNet::PluginInterface2.