---------------------------------------------- W3BWORLD v0.2 README (released 16th October 2012) ---------------------------------------------- This document is part of W3bworld (http://caia.swin.edu.au/urp/l3dge/tools/w3bworld/). It gives an overview of W3bworld. OVERVIEW -------- W3bworld is an evolution of the L3DGE [1] project. It aims to provide useful visual monitoring and interaction inside a 3D environment in a HTML5, typically in a networking related situation. Support for HTML5 in browsers is growing, with some mobile devices supporting WebGL functionality. W3bworld leverages this provide support for an increasing range of platforms. DOCUMENTATION ------------- For installation instructions, see INSTALL.txt W3bworld is made up of a NodeJS server and a HTML client. The server accepts input and sends output to and from a l3dgecomm daemon. The client uses a HTML5 library, Processing.JS to render the W3bworld environment. Apart from the snippet of Processing.JS code in gfx.pde, everything is written in Javascript. The server and client communicate using websockets, which allows for a webpage to communicate with a foreign host in an asynchronous bidirectional manner. All data that the server sends the client is cached, such that the client can continue operating with stale data without a server until a page reload. Communication between the server and the environment being monitored happens using l3dgecomm. See the l3dgecomm 2.3 specifications [2] for more information. Each l3dgecomm entity is represented by a single in-world object. W3bworld will not adjust how many entities are displayed based on how many entities it receives updates for - you must make sure the entity list file (see INSTALL.txt) has the correct amount of entities in it. Which file to read entities from is set by elementsFilename in w3bworld.js. The server, by default, listens for l3dgecomm input on port 27960 and websocket connections on port 80. The server will send l3dgecomm output to the IP address and port listed in w3bworld-output-daemon.txt The client is separated out in to a number of modules, each contained within a separate file: * w3b-core.js: contains functions mostly dealing with user input * w3b-entity.js: contians functions and classes for storing and using state information about each entity * w3b-hit.js: contains hit-detection for triggering actions on an entity * w3b-camera.js: contains camera manipulation functionality * w3b-socketio.js: contains network communcation functionality * gfx.pde: contains the processing.js scripts for rendering the world In addition to these, there are a number of third party libraries in use: * jquery-1.7.2.min.js: jQuery, used for simpler DOM manipiulation and JS shorthand * processing.bug608.js: a modified version of Processing.js that allows for .obj file loading * fullscreenapi.js: a short script to enable the fullscreen API in web browsers that support it. In the near future, fullscreen support will become standardised and this script will not be needed * socket.io.min.js: the client-side Socket.IO implementation. Some example model files are also included. The server is separated out in to two modules and two configuration files: * w3bworld.js: contains entity management and client communication code * l3dgecomm-server.js: contains a Node.js l3dgecomm module * w3bworld-output-daemon.txt: defines the address to send l3dgecomm output. The IP address goes on line 1 and the port on line 2. * elements.txt: the default layout of the W3bworld entities. Each line is three integer or float values separated by commas, representing the location of one entity. The server also relies upon the Socket.IO library and The interface between w3bworld.js and l3dgecomm-server.js has one event in each direction, making it simple to modify. Installation & Configuration [3] describes how to implement a new module to put in place of l3dgecomm-server.js. example-module.js demonstrates what is needed to be done to create a new module. Likewise, the l3dgecomm-server.js module can be used in other projects with similar ease. Start W3bworld using: node w3bworld.js Press ctrl+c to exit, or send a SIGTERM to the process. Included with the client are a number of entity model options. You can set which shape you would like your entities to be by changing defaultEntityType in w3bworld.js The default types are as follows: 1: Cube 2: Sphere 3: Star drawn using vertexes 4: Pyramid drawn using vertexes 5: Star model from LCMon 6: Switch model 7: IP Phone model Options 1 to 4 allow you to paint them in any RGB colour through l3dgecomm. Options 5 through 7 are statically coloured by the model file. You can add additional shapes by modifying the switch() statement in the draw loop of gfx.pde. REFERENCES ---------- [1] http://caia.swin.edu.au/urp/l3dge/ L3DGE [2] http://caia.swin.edu.au/reports/080222C/CAIA-TR-080222C.pdf Lucas Parry, "L3dgecomm 2.3 Input & Output Specifications", CAIA Technical Report 080222C [3] http://caia.swin.edu.au/urp/l3dge/tools/w3bworld/configuration.html Installation & Configuration - W3bworld LICENSE ------- W3bworld is distributed under the FreeBSD license. Copyright (c) 2012 Centre for Advanced Internet Architectures, Swinburne University of Technology. Authors: Chris Holman ( 6963420@student.swin.edu.au ) Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. CONTACT ------- The W3bworld website is: http://www.caia.swin.edu.au/urp/l3dge/tools/w3bworld/ If you have any questions or want to report any bugs please contact Chris Holman ( 6963420@student.swin.edu.au ) Grenville Armitage (garmitage@swin.edu.au). Centre for Advanced Internet Architectures Swinburne University of Technology Melbourne, Australia CRICOS number 00111D http://www.caia.swin.edu.au