Replicating Data with SharedState
Replication Module
Replication module is designed to make synchronization of objects on the network easier. I helps to update and synchronize objects as they change over time. For example, it can be used to broadcast a message on new object creation, serializing an object state and sending it from a server to a client or vice versa.
Replication module consists of the following:
- SharedState represents a replicated object state in the application(with the specified replication parameters). See more details below.
- NetworkReplicator is based on the RakNet ReplicaManager3 class. It is used to automate game object construction, destruction, and serialization.
- NetworkReplicatorConnection is based on the RakNet Connection_RM3 class. It is used to allocate replicas and track which instances have been allocated.
- NetworkReplica is based on the RakNet Replica3 class. It is a base class for replicated objects.
SharedState Class
This class defines the state that is synchronized over the network. It contains internal instance(s) of SharedData plus additional options that specify how this state should be synchronized (the rate of synchronization, reliability of packets delivery, whether to send all updates to clients or filter them). In addition, it can also store the history of updates received from the server.
A state cannot be created using a constructor. It is created and deleted only by its owner using network.createSharedState() and network.destroySharedState() functions.
- int getOwnerID() — gets ID of the owner. If the owner is unknown, returns UNASSIGNED_OWNER_ID constant.
- int getStateID() — gets ID of the state. By unknown identifier returns UNASSIGNED_STATE_ID constant.
- void setUpdateInterval(int interval) — sets an interval for state updates (in ms). By default, it is equal to 0 ms (i.e. the state is not updated by default).
- int getUpdateInterval() — gets the interval of state update (in ms).
- void setReliability(int reliability) — sets the reliability of state updates delivery. Possible values for reliability are:
- RT_UNRELIABLE — updates are unordered, delivery is not guaranteed.
- RT_UNRELIABLE_SEQUENCED — delivery is not guaranteed: old packets are not delivered after new packets are received.
- RT_RELIABLE — reliable delivery, order is not guaranteed.
- RT_RELIABLE_ORDERED — reliable delivery, updates are ordered.
- RT_RELIABLE_SEQUENCED — reliable delivery, only new updates are delivered (if older packets are received after newer ones, they are not delivered).
- int getReliability() — gets the current reliability of state updates delivery.
- void setAutoUpdate(int is_auto_update_on) — enable/disable the automatic update mode for state. By default, updates of all states are sent automatically. If you want to send them manually, set the disabled flag.
- int isAutoUpdate() — returns a value indicating if the automatic update mode for state is enabled or disabled.
State Update
- void updateSharedData(SharedData data) — updates the current (actual) state (i.e. overwrites SharedData)
- void appendSharedData(SharedData data) — adds new data to the end of state updates history (i.e. it will be the last, actual state). This data will have the current timestamp.
Member functions for working with the current (latest) state are listed below.
Notice
When calling one the following methods, the current history of state updates is deleted.
- void addDataField(variable field) — adds a new data field
- void clearData() — clears the state (all data fields are deleted)
- void setDataField(int index,variable field) — updates the data field with specified index (if no such field exists, it will be added to the end)
- void setDataField(variable field) — updates the data field with zero index
- variable getDataField(int index) — gets the data field with specified index
- variable getDataField() — gets the data field with zero index
- int getNumDataFields() — gets the total number of data fields
- variable getNextDataField() — gets the next field (used for sequential data reading)
- void setNextDataField(variable field) — updates the next field (used for sequential data writing)
- void resetCurDataField() — sets the counter of the current data field to 0
- void setData(SharedData data) — updates the current state from the specified SharedData instance
- void setArray(int array[]) — updates the current state from the specified UnigineScript array (i.e. a vector).
Actual State Accessing
To access the last synchronized data that arrived over the network with the last state update (i.e. access the latest internal instance of SharedData), use the following functions.
State Relevance
If on the client machine the camera is far away from an object, it makes no visual difference whether its state is updated each frame or not. To minimize network traffic, data can be sent basing on relevance parameter: in full, only on creation/deletion of objects or no data at all.
- void setRelevantState(NetworkAddress target_address, int relevant_state) — sets the relevance of state updates to the specified network node.
- target_address — an address of the target network node relative to which relevance of state updates is set.
- relevant_state — a relevance state. Its possible values are:
- RELEVANT_STATE_IRRELEVANT — the given state is irrelevant; no state-related data will be sent to the specified network node
- RELEVANT_STATE_SEND_ALL_CHANGES — the given state is relevant; all state-related data will be sent to the specified target
- RELEVANT_STATE_SEND_CONSTRUCT_DESTRUCT — send messages only on creation or destruction of the state
- int getRelevantState(NetworkAddress target_address) — gets a relevance of the network node relative a specified target node.
State History
To work with the history of state updates, use the following functions.
- void setMaxHistorySize(int size) — sets the maximum size for update history stored within the state. By default it is equal to 1. If state interpolation is necessary, the size of history should be increased (history is stored only in the network node that receives updates).
- int getMaxHistorySize() — gets the maximum size set for update history.
- int getHistorySize() — gets the current size of the update history (how many states have been saved at the moment).
- SharedData getHistoryEntry(int index) — gets the state update saved in the history with the specified index.
- int getTimestamp() — gets the timestamp of the last received update.
States Synchronization Functions
- SharedState network.createSharedState(int owner_id, int state_id) — creates a state (an object of SharedState type that be will be synchronized over the network; see details on SharedState class).
- owner_id — identifier of the state owner (for example, object identifier)
- state_id — identifier of the state
- SharedState network.createSharedState(int owner_id, int state_id, SharedData data) — creates a state (an object of SharedState type that be will be synchronized over the network; see details on SharedState class).
- owner_id — identifier of the state owner (for example, object identifier)
- state_id — identifier of the state
- data — data to be synchronized
- void network.destroySharedState(SharedState shared_state) — deletes the state.
- int network.sendUpdateSharedState(SharedState shared_state) — forces to send state update. To send state updates manually, disable the automatic sending of updates (by default).
This function returns 1 if the state update was successfully sent; otherwise, 0. - void network.setDropThreshold(int threshold) — sets the time threshold used to drop the expired state updates (in ms). By default it is equal to 300 ms. This threshold is used for updating SharedState (or for skipping the received update if this threshold is exceeded).
- int network.getDropThreshold() — gets the time threshold used to drop the expired state updates (in ms).
- int network.getNumDroppedUpdates() — gets the number of the expired state updates that were dropped during the last update() of the Network plugin.
- void network.setAuthority(int authority) — sets the authority for the current network node:
- authority — flag indicating if the current network node is authorized to create/delete states (1 or 0). For a server, it is usually set to 1; for a client — to 0.
- int network.getAuthority() — returns 1 if the given node is authorized to create/delete states; otherwise, 0.
Samples
- Example of states synchronization (creation/deletion, update) on a relevance basis can be found under <UnigineSDK>/data/network/samples/synchronization folder.
- Example of noninteractive synchronization of the character can be found under <UnigineSDK>/data/network/samples/character_synchronization folder.
- Example of noninteractive synchronization of different objects can be found under <UnigineSDK>/data/network/network_viewer folder.
Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)