UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
Content Creation
Materials
Unigine Material Library
Tutorials

Sending Data with SharedData

SharedData Class

SharedData class allows for data to be sent over the network. The following data types are supported:

Standard types Special types
int
long
float
double

vec3
dvec3
ivec3

vec4
dvec4
ivec4

mat4
dmat4
quat

string
NetworkAddress

This class has the following members:

  • SharedData() — default constructor that creates an empty container.
  • SharedData(int array[]) — constructor that creates SharedData instance using a standard UnigineScript array (i.e. a vector).
  • void addField(variable field) — adds a field to the container. Field variable can be of any type that is supported by SharedData.
  • void setField(int index, variable field) — updates the field specified by its index. If there is no such a field, variable is added to the end of the container as a new field.
  • void setField(variable field) — updates a zero field (if the field does not exist, it will be added).
  • variable getField(int index) — gets a field by its index.
  • variable getField() — gets a zero field (this is convenient if container has only one field).
  • variable setNextField(variable field) — updates the next field (for sequential update of fields).
  • variable getNextField() — gets the next field (for sequential reading of the fields).
  • void setArray(int array[]) — fills SharedData with data from a specified array. If SharedData contains some fields, they will be overwritten.
  • void getArray(int array[]) — fills the specified array with SharedData data.
  • void getArray(Variable array_id,int start_field_num,int end_field_num) — fills the specified array with SharedData data from the range [start_field_num,end_field_num).
  • void addArray(int array[]) — adds the specified array to the end of SharedData data.
  • int getNumFields() — gets the number of fields in the container.
  • void resetCurField() — resets the pointer to the current field (to reread the fields once again).
  • int getCurFieldIndex() — gets the index of the current field.
  • void clear() — empties a container.
  • void copy(SharedData src) — copies data from the specified source src container into the current one.

SharedData Serialization

When sent as a timestamped RakNet packet, SharedData is serialized into a bitstream in the following way:

  1. Packet timestamp ID ID_TIMESTAMP (unsigned char)
  2. Packet timestamp value (uint64_t returned by RakNet::GetTime())
  3. Packet type ID_CUSTOM (unsigned char)
  4. Number of fields in SharedData instance (uint8_t)
  5. For each field in SharedData instance:
    1. Type of the field (uint8_t). For example, for Unigine::Variable::INT, it is 0 and for Unigine::Variable::STRING, it is 13.
    2. Value of the field. For example, 60 or "text".

For example, if it is necessary to get lower-level RakNet packets after they were sent by the Unigine client application and read SharedData from them, they can be deserialized on the server side in the following way:

Source code (UnigineScript)
bit_stream.Read(packet_type);
 
if(packet_type == ID_TIMESTAMP) {
        bit_stream.Read(timestamp);
        bit_stream.Read(packet_type);
}

int num_fields = 0;
int res = stream.ReadCasted<uint8_t,int>(num_fields);
data.reserveFields(num_fields);

for(int i = 0; i < num_fields; ++i) {
        Variable field;
        res = deserialize(field,stream);
        data.setField(i,field);
}

After that, a custom packet is accessed in the following way:

Source code (UnigineScript)
int custom_packet_type = shared_data.getField(0).getInt();

Sending Data Functions

  • int network.send(SharedData data, Variable target,int send_mode) — sends data over the network:
    • data — data to be sent (see SharedData class)
    • target — an address of the recipient. It can be one of the following:
    • send_mode — a send mode. This is an optional parameter. By default it is equal to the SEND_MODE_NORMAL.
      The function returns 1 if the data was successfully sent; otherwise, 0.
  • int network.sendAll(SharedData data, int send_mode) — sends the data to all connected clients over the network:
    • data — data to be sent
    • send_mode — a send mode. This is an optional parameter. By default it is equal to the SEND_MODE_NORMAL.
      The function returns 1 if the data was successfully sent; otherwise, 0.
  • int network.sendAll(SharedData data, Variable exclude_target,int send_mode) — sends the data to all connected clients over the network, with the exception of a specified address:
    • data — data to be sent
    • exclude_address — a host address to be excluded. It can be one of the following types:
    • send_mode — a send mode. This is an optional parameter. By default it is equal to the SEND_MODE_NORMAL.
      The function returns 1 if the data was successfully sent; otherwise, 0.

Sending Modes

Possible send modes are as follows.

  • SEND_MODE_NORMAL - for each of the messages send with a SEND_MODE_IMMEDIATE mode, there will be sent one message with SEND_MODE_NORMAL mode. Such messages are placed into a buffer and are sent every 10 ms to keep the overhead low and to reduce the network load.
  • SEND_MODE_IMMEDIATE - such messages are sent immediately, without any buffering.

Samples

  • Example of sending messages between the client and a server can be found under <UnigineSDK>/data/network/samples/latency folder.
  • Example of simple network chat can be found under <UnigineSDK>/data/network/chat folder.
Last update: 2017-07-03