W3bworld: in-browser 3D visualisation of network state

Requirements

The client will operate on any browser that supports WebGL. Currently, W3bworld is tested with Firefox and Chrome on Windows. Opera and Safari are listed as having support, and IE supports WebGL with the addition of the IEWebGL plugin. The use of the Socket.IO library negates the need for your browser to support Websockets, but it is optimal to have it.

The server requires NodeJS and a HTTP server. NodeJS operates on FreeBSD, MacOS, Windows and Linux on the x86 and x86-64 platforms. Any HTTP server is adequate as only static files need to be served.

Installation

The W3bworld console.

The W3bworld project is made up of two parts - the application server and the client page. The application server is made up of w3bworld.js and l3dgecomm-server.js, and the two configuration files: w3bworld-output-daemon.txt (optional) and the list of entity positions. The remainder of the files make up the client portion of the project.

Install a web server. It only needs to serve static files, so there are no special requirements. While Node.js does have a HTTP server module, it is not used in W3bworld in order to keep the codebase simpler. Extract all of the W3bworld project to a directory inside the document root of your webserver. Optionally, w3bworld.js and l3dgecomm-server.js can be kept elsewhere.

Note that the webserver is not optional - websocket connections will not work if you open the client HTML file straight from your filesystem (ie, through a file:/// URI.). This is due to security measures enforced by every major browser.

Download Node.js from its website and install it. If you are using Windows, you will need to either log out and in again, or set the %PATH% variable for that session using: `set PATH=c:\path\to\nodejs;%PATH%`. Once installed, test that it was sucessfully installed by running `node` from a command line. If you are presented with a ">" prompt, press Ctrl+C twice to exit. Change directories to where w3bworld.js and l3dgecomms.js are and run `npm install socket.io`.

Copy socket.io.min.js from node_modules\socket.io\node_modules\socket.io-client\dist\ to the same directory as the W3bworld HTML and JS files. This should replace whichever version of socket.io.min.js is included in the W3bworld package.

Create the entity position list file. Each line is an entity and contains three comma separated (optionally decimal) values in the form: x,y,z. x and z are the position on the horizontal plane and y is the height. Name the file something obvious, such as "entity-pos.txt" and set the "elementsFilename" variable in w3bworld.js to the chosen filename.

If you are using an output daemon, create "w3bworld-output-daemon.txt". Put the IP address on the first line and the port on the second line.

W3bworld, by default, listens on port 10001 UDP. If you are behind a firewall that blocks this port, you can do one of two things:

• Operate a reverse proxy on port 80 to separate out the HTTP and the Websocket connections to different ports. You must use a proxy that is websocket-aware (eg, HA Proxy).
• Operate the websocket server on a different IP address to the HTTP server, but on port 80.

In the latter case, you need to change the W3bworld listen port to 80. This needs to be changed in `var listenPort = 10001` of W3bworld and in the client HTML file - `websocketServer = window.location.hostname.toString() + ":10001";`. In both places, change the 10001 to whichever port you desire. If you utilise a reverse proxy, only the port in the client HTML file needs to be changed.

An example of a working W3bworld installation.

Interfacing l3dgecomm daemons

Interfacing a l3dgecomm daemon with W3bworld is trivial. If the daemon is only an input daemon (that is, data is only sent from the daemon to W3bworld), then no configuration of W3bworld is necessary. If the daemon is an output daemon too (that is, user interaction within W3bworld triggers events in the output daemon), then the w3bworld-output-daemon.txt file needs to contain the IP of the daemon on the first line, and the port on the second line.

For example, fakematter.py (included with W3bworld) can be used to generate random data:
./fakematter.py -n 100 -a 127.0.0.1 -p 27960 --spin --bounce-height
This will send random data for 100 entities (-n 100) to 127.0.0.1:27960, setting the spin rate and bounce height to random values.

Forcing browser compatibility

Some web browsers require changing a setting to enable WebGL. If W3bworld does not work straight away, try the following:

• Firefox: In FF13, go to 'about:config' from the URL bar. If presented with a warning regarding the dangers of changing settings, continue past the warning. Use the search box to find all 'webgl' settings. Change both webgl.force-enabled and webgl.prefer-native-gl to true, and restart Firefox. Other versions of Firefox may vary
• Chrome: Go to 'chrome://gpu/' in the URL Bar. Check the top list to see if WebGL is enabled. If it is not hardware accelerated, check for 'Override software rendering list' in 'chrome://flags'. Also in chrome://flags, older versions of chrome have required WebGL to be force enabled, which can be done here.

Using a non-l3dgecomm input

The W3bworld server is structured in such a way that it is simple to remove the l3dgecomm portion of the code and replace it with something else. Simply create a new NodeJS module, make the exports an EventEmitter, and set it to handle the 'entityHit' events and send 'update' events. Edit w3bworld.js - find `var l3dgecomms = require("./l3dgecomm-server.js");` and change it to use your file. An example module is included in example-module.js.