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

Network Events and Their Handlers

Network Events

The following network messages can be received by the server or a client.

Connection Status Messages

  • NETWORK_ON_CLIENT_CONNECTED — a client has connected
  • NETWORK_ON_CLIENT_DISCONNECTED — a client has disconnected
  • NETWORK_ON_CLIENT_CONNECTION_LOST — connection to the client has been lost
  • NETWORK_ON_SERVER_ACCEPTED_CONNECTION — connection to the server is successfully established
  • NETWORK_ON_SERVER_СONNECTION_ATTEMPT_ERROR — an error occurred while trying to connect to the server
  • NETWORK_ON_SERVER_SHUTDOWN — the server shuts down
  • NETWORK_ON_SERVER_CONNECTION_LOST — connection to the server has been lost
  • NETWORK_ON_NETWORK_ERROR — a network error has occured

Received Data Message

  • NETWORK_ON_DATA_RECEIVED — data is received over the network

States Synchronization Messages

  • NETWORK_ON_SHARED_STATE_CONSTRUCT — one of the connected network nodes has created SharedState
  • NETWORK_ON_SHARED_STATE_DESTRUCT — one of the connected network nodes has deleted SharedState
  • NETWORK_ON_SHARED_STATE_DESERIALIZE — update for the SharedState has been received over the network.

LAN Server Discovery / Offline Ping Messages

  • NETWORK_ON_PONG_RECEIVED — a reply is received from the network node, to which a request (ping or LAN server discovery) has been sent
  • NETWORK_ON_LAN_SERVER_ADVERTISE — data from the server in LAN is received

Registration of Event Handlers

To receive network messages, register an event handler for them using network.registerHandler() function. To unsubscribe from event notifications, network.unregisterHandler() is called.

Notice
Network event handlers can only be world script functions since Plugin uses Engine::runWorld() to call event handlers.

  • int network.registerHandler(int network_event_type, string handler) - registers a handler for the network message:
    • network_event_type — type of the network message to be subscribed to (see event types)
    • handler — name of the network message handler (see handler formats)

      The function returns 1 if the handler was successfully registered; otherwise, 0.

  • int network.unregisterHandler(int network_event_type) — deletes a handler from the list of registered ones:
    • network_event_type — message to unsubscribe from

      The function returns 1 if the handler was successfully deleted; otherwise, 0.

Handler Formats

An event handler can have any name, but it should take certain arguments.

  • NETWORK_ON_CLIENT_CONNECTED
    void onClientConnected(NetworkAddress client_address)
    • client_address — address of the connected client
  • NETWORK_ON_CLIENT_DISCONNECTED
    void onClientDisconnected(NetworkAddress client_address, NetworkStatistics network_statistics)
    • client_address — address of the disconnected client.
    • network_statistics — network statistics on the closed connection. This is an optional parameter.
  • NETWORK_ON_CLIENT_CONNECTION_LOST
    void onClientConnectionLost(NetworkAddress client_address, NetworkStatistics network_statistics)
    • client_address — address of the client with which connection is lost.
    • network_statistics — network statistics on the broken connection. This is an optional parameter.
  • NETWORK_ON_SERVER_ACCEPTED_CONNECTION
    void onServerAcceptedConnection(NetworkAddress server_address)
    • server_address — address of the server that accepted connection
  • NETWORK_ON_SERVER_CONNECTION_ATTEMPT_ERROR
    void onServerConnectionAttemptError(NetworkAddress server_address, int error_code, string message)
    • server_address — address of the server, connection with which has failed
    • error_code — code of the error (see the possible values)
    • message — message with error description
  • NETWORK_ON_SERVER_SHUTDOWN
    void onServerShutdown(NetworkAddress server_address, NetworkStatistics network_statistics)
    • server_address — address of the server
    • network_statistics — network statistics on the closed connection. This is an optional parameter.
  • NETWORK_ON_SERVER_CONNECTION_LOST
    void onServerConnectionLost(NetworkAddress server_address, NetworkStatistics network_statistics)
    • server_address — address of the server
    • network_statistics — network statistics on the broken connection. This is an optional parameter.
  • NETWORK_ON_NETWORK_ERROR
    void onNetworkError(string message)
    • server_address — address of the server
    • message — message with error description
  • NETWORK_ON_DATA_RECEIVED
    void onDataReceived(NetworkAddress sender_address, SharedData data, long sent_timestamp, long recvd_timestamp)
    • sender_address — address of the sender
    • data — the received data. This data is copied and passed under script ownership, after which it is handled by the garbage collector.
    • sent_timestamp — time when the data has been sent (set by the sender). It can be used to calculate the total latency of the message:

      latency = current_network_time - sent_timestamp
    • recvd_timestamp — time when the data has been received (set immediately when a network packet has been received by the low level network component). It can be used to calculate the latency of a message waiting in a queue and being processed by the script.

      processing_latency = current_network_time - recvd_timestamp
      This is an optional parameter.
  • NETWORK_ON_SHARED_STATE_CONSTRUCT
    void onSharedStateConstruct(NetworkAddress sender_address, SharedState constructed_state)
    • sender_address — address of the sender
    • constructed_state — constructed state
  • NETWORK_ON_SHARED_STATE_DESTRUCT
    void onSharedStateDestruct(NetworkAddress sender_address, SharedState destructed_state)
    • sender_address — address of the sender
    • destructed_state — destructed state
  • NETWORK_ON_SHARED_STATE_DESERIALIZE
    void onSharedStateDeserialize(NetworkAddress sender_address, SharedState deserialized_state)
    • sender_address — address of the sender
    • deserialized_state — updated state
  • NETWORK_ON_PONG_RECEIVED
    void onPongReceived(NetworkAddress sender_address, int ping_time, string game_type, string custom_info)
    • sender_address — an address of the sender
    • ping_time — ping time (in ms)
    • game_type — a type of the game. It is an editable string used to filter pong messages. For example, you can write into this string a name and a version of the game.
    • custom_info — additional information. It is an editable string to store any custom information about the game. For example, you can write into this string the number of connected players, state of the game, etc.
  • NETWORK_ON_SERVER_ADVERTISE
    void onLANServerAdvertise(NetworkAddress server_address, string game_type, string сustom_info)
    • server_address — an address of the server
    • game_type — a type of the game. It is an editable string used to filter pong messages. For example, you can write into this string a name and a version of the game.
    • custom_info — additional information. It is an editable string to store any custom information about the game. For example, you can write into this string the number of connected players, state of the game, etc.
Last update: 2017-07-03