shown in other instead.
Replicating Data with SharedState
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.
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.
- int getOwnerID() — gets ID of the owner. If the owner is unknown, returns UNASSIGNED_OWNER_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 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.
- 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.
- 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
- 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 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.
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.
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.
- 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
- 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).
- 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.
- 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.