Lightstreamer - 3D World Demo - Java Adapter

The 3D World Demo shows how well the real-time positions of objects in a multiplayer 3D world can be delivered over WebSockets and HTTP via Lightstreamer Server. Particular attention is paid to aspects of real-time communication and opportunities to minimize the network bandwidth utilization.

This project shows the Data Adapter and Metadata Adapters for the 3D World Demo and how they can be plugged into Lightstreamer Server.

As an example of a client using this adapter, you may refer to the 3D World Demo - HTML (Three.js) Client and view the corresponding Live Demo

Details

To fully understand this demo, please read the article: Optimizing Multiplayer 3D Game Synchronization Over the Web

There are two ways the demo can work.

• First way: the physics engine runs on the client side, which periodically synchronizes with the authoritative server.
• Second way: the physics engine runs on the server side only and the positional and rotational data for all the players in a world are transmitted to all the clients. In other words, the clients are pure renderers.

Java Data Adapter and MetaData Adapter

This project includes the implementation of both the SmartDataProvider interface and the MetadataProviderAdapter interface to inject data into Lightstreamer server with real-time information about the movement of every object in the world. Both translations and rotations in 3D space are calculated by the adapter and transmitted to the clients in a 7-value array: position for axis X, position for axis Y, position for axis Z, and a quaternion object for rotation information: x, y, z, Quat(X, Y, Z, W). Precision and format of data in output are configurable by each user among these choices:

• binary Base64 encoded float numbers in single precision;
• binary Base64 encoded float numbers in double precision;
• string with fixed decimal places (ranging from 1 to 15).

The adapter receives input commands from Lightstreamer server, which forwards messages arrived from clients to the adapter in relation to:

• Changing nickname for the player;
• Changing last message for the player;
• Changing world scenario for the player;
• Movement commands.

The Adapter Set Configuration

This Adapter Set Name is configured and will be referenced by the clients as DEMOMOVE3D.

The adapters.xml file for this demo should look like:

<?xml version="1.0"?>
<adapters_conf id="DEMOMOVE3D">

    <!--
      Not all configuration options of an Adapter Set are exposed by this file. 
      You can easily expand your configurations using the generic template, 
      `DOCS-SDKs/sdk_adapter_java_inprocess/doc/adapter_conf_template/adapters.xml`,
      as a reference.
    -->
    
    <metadata_adapter_initialised_first>Y</metadata_adapter_initialised_first>

    <metadata_provider>
        <adapter_class>com.lightstreamer.adapters.DemoQuat3d.Move3dMetaAdapter</adapter_class>
        
        <!-- Optional configuration file for the Adapter's own logging.
             Logging is managed through log4j. -->
        <param name="log_config">adapters_log_conf.xml</param>
        <param name="log_config_refresh_seconds">10</param>

        <!--
          TCP port on which Sun/Oracle's JMXMP connector will be
          listening.
        -->
        <param name="jmxPort">9999</param>
        
        <!--
          Max number of players in server-side modality.
        -->
        <param name="Max_Srv_Players">10</param>
		  
    </metadata_provider>
    
    <data_provider>
        <adapter_class>com.lightstreamer.adapters.DemoQuat3d.Move3dAdapter</adapter_class>
  
        <!--
          Frame rate for physics calculations. In milliseconds.
        -->
        <param name="frameRate">10</param>
        
        <!--
          Default option for number of decimals.
        -->
        <param name="precision">8</param>
        
        <!--
          Max interval of time without send any commands after which
          the player is forcibly disconnected.
        -->
        <param name="Max_Inactivity">60000</param>
        
        <!--
          Number of Ghost players in the <Default> world. Ghosts are automatically
          killed when the number of real players is approaching the overcrowded 
          value and regenerate when this number decreases.
        -->
        <param name="Ghost_Players">7</param>
        
        <!--
          Max number of total players in the all the worlds.
        -->
        <param name="Max_Players">100</param>
        
        <!--
          Max number of players in the same world.
        -->
        <param name="overcrowded">10</param>
    </data_provider>
</adapters_conf>

NOTE: not all configuration options of an Adapter Set are exposed by the file suggested above. You can easily expand your configurations using the generic template, DOCS-SDKs/sdk_adapter_java_inprocess/doc/adapter_conf_template/adapters.xml, as a reference.

Please refer here for more details about Lightstreamer Adapters.

Install

If you want to install a version of this demo in your local Lightstreamer server, follow these steps:

• Download Lightstreamer Server Vivace (make sure you use Vivace edition, otherwise, you will see a limit on the event rate; Lightstreamer Server comes with a free non-expiring demo license for 20 connected users) from Lightstreamer Download page, and install it, as explained in the GETTING_STARTED.TXT file in the installation home directory.
• Get the deploy.zip file of the latest release and unzip it.
• Copy the just unzipped 3DWorldDemo folder into the adapters folder of your Lightstreamer Server installation.
• Download croftsoft library and compile a croftsoft-math.jar version. Please make sure to include: applet, io, inlp, lang, and math packages.
• Copy the just compiled croftsoft-math.jar file in the 3DWorldDemo/lib folder.
• [Optional] Customize the specific "LS_3DWorldDemo_Logger" and "LS_demos_Logger" categories in log4j configuration file 3DWorldDemo/adapters_log_conf.xml.
• Launch Lightstreamer Server.
• Launch a client like the 3D World Demo - HTML (Three.js) Client

Build

To build your own version of LS_3DWorldDemo_Adapters.jar, instead of using the one provided in the deploy.zip file from the Install section above, follow these steps:

• Clone this project.
• Get the ls-adapter-interface.jar file from the Lightstreamer distribution and copy it into the lib folder.
• Get the log4j-1.2.17.jar file from Apache log4j and copy it into the lib folder.
• Download croftsoft library and compile a croftsoft-math.jar version. Please make sure to include: applet, io, inlp, lang, and math packages.
• Put the just compiled croftsoft-math.jar file in the lib folder.
• Build the java source files in the src folder into a LS_3DWorldDemo_Adapters.jar file. Here is an example for that:

  >javac -source 1.7 -target 1.7 -nowarn -g -classpath lib/croftsoft-math.jar;lib/ls-adapter-interface.jar;lib/log4j-1.2.17.jar -sourcepath src -d tmp_classes src/com/lightstreamer/adapters/DemoQuat3d/Move3dAdapter.java
  >jar cvf LS_3DWorldDemo_Adapters.jar -C tmp_classes com

• Copy the just compiled LS_3DWorldDemo_Adapters.jar in the adapters/3DWorldDemo/lib folder of your Lightstreamer Server installation.

See Also

• Optimizing Multiplayer 3D Game Synchronization Over the Web

Clients Using This Adapter

• Lightstreamer - 3D World Demo - Three.js Client

Related Projects

• Lightstreamer - Reusable Metadata Adapters - Java Adapter

Lightstreamer Compatibility Notes

• Compatible with Lightstreamer SDK for Java In-Process Adapters since 6.0

• For a version of this example compatible with Lightstreamer SDK for Java Adapters version 5.1, please refer to this tag.