Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins

Unigine::Syncker

Syncker is a multi-node rendering system that makes it easy to create an immersive CAVE system or a large-scale visualization wall on a computer cluster synchronized over the network in real-time.

Simply connect multiple computers into one high-resolution seamless display using LAN. And it does not matter if these computers are running on Windows, Linux and Mac OS X at the same time, as Syncker works even across different platforms. Moreover, the created virtual environments can be of any monitor configuration, since all viewports are fully configurable.

Syncker

Computers in LAN connected via Syncker

See Also

Structure

Syncker allows you to render a world with a fixed FPS (by default, 60 FPS) across different computers synchronized over LAN. These computers can be of two types:

Master Master application is the main computer. This engine instance always renders the main viewport, and is not included into monitor configuration set up for CAVE rendering. Instead, its purpose is to perform calculation:
  • Nodes are moved according to the application logic.
  • Nodes are moved in the editor as the world is set up.

All other applications are synchronized with a master.
Slaves Slave applications are all other applications connected over the network. There can be an unlimited number of slaves connected to one master (as long as network bandwidth allows it). The purpose of such applications is to render all nodes that are seen in their viewports.
  • All rendering is done directly on a slave GPU.
  • Animations are updated on the master computer, while slaves only get calculated bone transformations.
  • Particles systems are updated on the slave but according to parameters sent from the master.
  • Physics in slave applications should be disabled not to override position and orientation of nodes sent over the network from a master.

Configuration of slaves is set up to fit positioned monitors.

Syncker Pipeline

To connect computers and synchronize them, the following pipeline is used.

  1. First, a master is sending broadcast messages that it is available using a UDP protocol.
  2. All slaves in LAN listen to a default UDP port. Upon receiving this message, they connect to a master via a TCP protocol.
  3. After the connection was established, both UDP and TCP protocols are used to exchange data between the master and slaves.
    • Over UDP protocol non-critical messages are sent. This includes messages on render parameters (for example, ambient color or HDR exposure), position of a player and all nodes that are synchronized. It also includes frame-related information (if the game is enabled, the current frame number, frame duration, a time scale and even the game seed for random number generators).
    • Over TCP protocol critical messages are sent. These are messages on creation and deletion of nodes.

Screen Configurations

There are 3 ways to specify the screen configuration that can be used with Syncker:

  • As a grid of monitors, where each slave renders its viewport on the corresponding monitor.

    Grid of 4 monitors
  • As a mesh that is created in a 3rd-party 3D editor. When preparing a mesh in a 3D editor, the following requirements must be met:
    • Each surface of the mesh must correspond to one of the monitors.
    • Names of the mesh surfaces should match names of the corresponding slaves.
    • Coordinate system of the mesh must be expressed in meters.
    • Position and orientation of each monitor must be relative to the camera.
    • The pivot point of the mesh must correspond to the camera position.
    Notice
    Projection and modelview matrices are automatically calculated on the basis of the camera position and slave name.

    Screen configuration (the right picture) represented by a mesh (the left picture)
  • As a projection onto a curved screen.

    Each slave projects its viewport onto the projection screen

Preparing Your Environment

It is recommended to use at least 1 Gb LAN. Otherwise, you may experience network lags (see Troubleshooting section).

All application you will use need to have access to all Unigine files and project data. You can choose one of two variants:

  • Copy Unigine files and your project onto all computers. If some nodes will be missing in the world file on the local computer, they will not be rendered.

Running Syncker

To run Syncker to synchronize Unigine-based applications over LAN, you can choose one of two ways:

How To Run What Can be Run What Is the Profit Comments
On the start-up or via the interface Any Unigine project Fast This high-level method can be used straight away to load any samples, demos or your project across multiple computers. However, it is not performance-efficient, since it synchronizes states of all nodes and all materials.

Only nodes from a world file (*.world) can be synchronized using this approach.
  • Objects created dynamically cannot be synchronized even if they are created from a script both on the master and slave side.
  • Nodes added in the editor in the master application, do not appear in slave applications.

Editor functionality is not available in slave applications.
Via a script Syncker samples in SDK or coded projects Performance-efficient Using this low-level method, you can specify what nodes and what materials need to be synchronized. To avoid network lags especially for big projects, it is a preferred variant.

Examples can be found under the UnigineSDK/data/samples/syncker/ folder.

Via Interface

To run a high-level variant of Syncker via the interface, you need to follow these simple steps:

  1. Run all slave applications that will be synchronized with the master.

    For that, specify the following option on the slave application start-up to override a default editor script with the Syncker script for slaves:

    Shell commands
    main_x86 -data_path "../" -editor_script "core/systems/syncker/syncker_slave.cpp"
    
    Do not forget to add other required start-up arguments.
  2. If the editor on slave applications is not loaded, load it via the following console command:
    Source code
    editor_load
    
    If you open the console, you will see that a slave application listens on two ports for packets from a master (this default values can be left unchanged):
    Output
    ---- Syncker::Slave ----
    Name: unknown
    UDP: 8890
    TCP: 8891
    							
  3. Run a master Unigine application on the main computer.
  4. Open ToolsPlugins tab and load the Syncker master script for the editor: data/core/systems/syncker/syncker_master.cpp.
    If you open the console, you will see the current master network broadcast address:
    Output
    ---- Syncker::Master ----
    Address: 192.168.0.255
    UDP: 8890
    TCP: 8891
    						
  5. To change the broadcasting network address of the master, type the following console command:
    Source code
    master_address xxx.xxx.xxx.xxx
    
    And reload the Syncker master script: open ToolsPlugins tab, choose the master script and press the Reload button. After that, in the master console you will see messages that slaves have connected. For example:
    Output
    Connection from "xxx.xxx.xxx.xxx" "unknown" accepted in 0.01 seconds
    						
    Also, in the console of the connected slaves you will see the following:
    Output
    Connection to "xxx.xxx.xxx.xxx" accepted in 0.00 seconds
    						

If any slaves are added after the Syncker master script was loaded (or their names or addresses were changed), you will need to reload the master script via Reload button on ToolsPlugins tab.

You can open new worlds or quit from the current one in the master application and slaves will automatically do the same.

Notice
Console commands world_reload or world_load with the same world as currently loaded are not run on slaves after the master.
To edit the nodes in the world in the master application and see changes in effect on slaves, see How to synchronize nodes in the world.

On Start-Up

If you choose to run a high-level variant of Syncker directly on start-up, editor functionality in the master application will not be available, just like on slave ones.

  1. Run all slave applications as described above.
  2. Run a master Unigine application on the main computer with the default editor script overridden by the Syncker script for master.

    For that, specify the following option the master application start-up:

    Shell commands
    main_x86 -data_path "../" -editor_script "core/systems/syncker/syncker_master.cpp"
    
    Do not forget to add other required start-up arguments.
  3. If the editor on the master is not loaded, load it via the following console command:
    Source code
    editor_load
    
    In the console, the current master network broadcast address will be shown:
    Output
    ---- Syncker::Master ----
    Address: 192.168.0.255
    UDP: 8890
    TCP: 8891
    
  4. To change the network broadcast address of the master, type the following console command:
    Source code
    master_address xxx.xxx.xxx.xxx
    
    And then reload the master script as follows:
    Source code
    editor_reload
    
    After that, in the console you will see messages that slaves have connected:
    Output
    Connection from "xxx.xxx.xxx.xxx" "unknown" accepted in 0.00 seconds
    
    In the console of the connected slaves you will see the following:
    Output
    Connection to "xxx.xxx.xxx.xxx" accepted in 0.00 seconds
    

If any slaves are added after the Syncker master script was loaded (or slave names or addresses were changed), you will need to reload the master script via the console by using the editor_reload command.

You can open new worlds or quit from the current one in the master application and slaves will automatically do the same.

Notice
Console commands world_reload or world_load with the same world as currently loaded are not run on slaves after the master.

Changing Screen Configuration

By default all computers will be showing the same screen as a master computer does. The master viewport cannot be changed, it is used purely to control the world.
To set the screen configuration on slave computers used for rendering, all you need to do is specify your monitors setup for the master and all slaves (it is required that the same configuration is set for all computers connected via Syncker). After that, you can choose the viewport each slave computer shows, as well as compensate for the monitor angle.

Notice
You can specify the required screen configuration on the application start-up.
  1. First of all, set a monitor configuration on the master application via the following console command. The first argument specifies the number of monitors in a row and the second one specifies the number of columns. (Do not count in a master computer as its screen is non-configurable!)
    Source code
    master_grid 5 1
    
    For example, this command specifies that there are 5 slave monitors standing in a row.
  2. Set the same configuration for all slaves. This can be done in two ways. To specify it from master application for all slaves at once:
    Source code
    master_run slave_grid 5 1
    
    This would run the corresponding console command on all slaves.
    You can also run this console command in a usual way - by opening consoles on each slave computer and typing the following:
    Source code
    slave_grid 5 1
    
  3. Now you need to specify what each slave computer will show on its monitor by typing the following command into the console. For example, here is the slave that is the 1st in a row:
    Source code
    slave_view 0 0
    
    And here is a monitor in the middle (the 3rd monitor in the row):
    Source code
    slave_view 2 0
    
    And here is a slave that is the 5th in a row:
    Source code
    slave_view 4 0
    
    If we'd had two rows of monitors (grid 5x2), the computer in the right bottom would have slave_view configuration set to 4 1.
  4. You can check the viewport configuration of all slaves by the typing the master computer the following console command:
    Source code
    master_view
    
    It will output the configuration of all slave monitors.
  5. You can also specify if a slave monitor stands at a certain angle to other monitors. To set an angle for all slaves at once, type the following console command on the master computer:
    Source code
    master_angle 20
    
    You can also set an angle for each slave application individually via its console:
    Source code
    slave_angle 20
    
    The angles are specified in degrees.
    You cannot compensate for both vertical and horizontal turn of monitors. The engine automatically sets the compensation angle specified for a horizontal row or a vertical column depending on the number of monitors. If there are more monitors in a row (for example, 5 in a row and 2 columns), then the angle will be applied for horizontal compensation. If there are more monitors in a column (for example, 2 in a row and 6 columns), then the angle will be applied for vertical compensation.
  6. In addition to a monitor turning angle, it is also possible to compensate for a monitor frame around the screen (in order for objects not to teleport across the screens). To compensate for a bezel on all slave computers at once, type the following console command:
    Source code
    master_bezel 0.2 0
    
    This would specify that the screen of all computers should be rendered smaller horizontally (there is a frame between computers standing is a row). The specified value is range [0;1], where:
    • 0 is no bezel compensation
    • 1 is a half-screen size bezel
    For bezel compensation of computers standing in a column (i.e. to use only vertical bezel compensation), use the following:
    Source code
    master_bezel 0 0.2
    
    You can also set a bezel for each slave application individually via its console:
    Source code
    slave_bezel 0 0.2
    

Synchronizing Nodes in the World

If you run a high-lever version of Syncker via the interface or on the start-up, you can see that only camera position is synchronized by default. To synchronize nodes and their materials within a certain radius, run the following command in the master application:

Source code
master_radius 10
master_materials 15
  • master_radius command specifies that all nodes loaded from a *.world file should be synchronized if they inside a 10-unit radius around the player. Both their position and orientation will be synchronized.
    Notice
    It is not possible to synchronize nodes created dynamically via a script or added in the editor.
  • master_materials command specifies that states and parameters of materials that get inside a 15-unit radius around the player are synchronized to a master computer.
    Notice
    It is not possible to synchronize materials created in the editor in run time and not loaded from a material library on the disk.

The method described above is good enough to try out Syncker features. It is not performance-friendly since it synchronizes all nodes and all materials each frame. When a Syncker is used for a release version of the project, run it via a script and synchronize nodes and materials selectively, only on demand.

Troubleshooting

If the network latency is too large despite 1Gb bandwidth or higher, it can be caused by a 100 Mb or 10 Mb device connected to a network. Data exchange rate will drop down to the maximum rate supported by such device, slowing down Syncker connection speed.

  • Some 100 Mb or 10 Mb devices can have a working network interface when they are turned off.
  • It is also possible that when turned off, 1 Gb devices have a network interface working at 100 Mb rate, which will slow down connection in LAN.

Useful Tool

If you have a source SDK, you can use a simple and useful tool to monitor the network messages exchange speed. It is server.usc found in source/tools/Interpreter/scripts/network/.

Last update: 2017-07-03