Home | Changes | Index | Search | Go

Tutorial: How to create a world using a Wonderland File System (WFS)

Purpose

In this tutorial, you will learn how to create your own virtual world in a Wonderland File System (WFS) and load that virtual world into a running instance of the Wonderland server. A WFS lets you define cells in your world and organize them hierarchically using standard file system principles. Each cell is defined by an XML file specifying the cell's setup parameters (e.g. origin, model files) and may be created using a standard text editor available on your operating system.

This tutorial is designed for the v0.3 release of Project Wonderland.

Prerequisites

In order to complete this tutorial, you will need read/write access to some place on a file system mounted on your local machine. You should be able to create new directories (whether by command-line or a graphical file browser) and edit text-formatted files within those directories using a text editor on your machine.

You should also have downloaded, compiled, and have successfully run the Wonderland client and server. Instructions on downloading and running Wonderland can be found at https://lg3d-wonderland.dev.java.net/#try.

Project Wonderland: A Brief Architecture Overview

Project Wonderland is a software platform for the creation of 3-D virtual worlds, primarily enabling geographically distributed participants to collaborate with one another. A virtual world is composed of a collection of "cells", each of which represents a visual 3-D volume in the world. A world has a single, right-handed, 3-D cartesian coordinate system. From the viewer's perspective, the +X axis is towards the right, the +Y axis is gravitationally up, and the +Z axis is towards the user. Cells may be scenery or objects in the virtual world.

Each cell has a position and bounds inside the virtual world. Each cell defines its own local coordinate system, where the cell's center is at (0, 0, 0). A cell may contain within its bounds zero of more other cells, and hence there exists the notion of a "parent" and "children" for each cell. (In theory, a cell may have multiple parent cells, but in WFS, cells must only have one parent in the current revision of the software). A cell's position within the world is given relative to its parent's origin.

Structure of a Wonderland File System (WFS)

A WFS consists of a hierarchy of directories and XML files following certain naming conventions. The directory structure of the WFS reflects the hierarchical structure of cells in your virtual world. Child cells are contained within parent cells in your virtual world; similarly, child cell XML files are contained with a specially-named directory associated with the parent cell.

For reference, the following shows the WFS you will create during this tutorial (you will be taken through the individual steps to create the file system hierarchy, so there is no need to create it now).

+ test-wfs/
+ ----------- version.xml
+ ----------- aliases.xml
+ ----------- building-wlc.xml
+ ----------- building-wld/
+ ---------------------------- slideshow-wlc.xml
+ ---------------------------- dukejet-wlc.xml
+ ---------------------------- blackbox-wlc.xml

Creating a simple WFS

In these first steps, you will create a simple WFS with a single cell and load the WFS into Wonderland.

1. Select a place on your hard drive or on a file system mounted on your machine where you have read/write access. We will refer to this location by base_path for the remainder of the tutorial. For example, on Linux/UNIX systems, base_path may be /home/user/worlds, on Mac OS X it may be /Users/user/worlds and on Windows, it may be C:\worlds.
2. Create a new directory named test-wfs in base_path. Each WFS is rooted by a directory whose name contains the suffix -wfs.
3. In the *base_path*/test-wfs directory, create a file named building-wlc.xml with the following content. All XML files that define cells in your virtual world contain the suffix -wlc.xml.

<?xml version="1.0" encoding="UTF-8"?> 
<java version="1.6.0-dp" class="java.beans.XMLDecoder"> 
 <object class="org.jdesktop.lg3d.wonderland.darkstar.server.setup.BasicCellGLOSetup"> 
  <void property="cellGLOClassName"> 
   <string>org.jdesktop.lg3d.wonderland.darkstar.server.cell.SimpleTerrainCellGLO</string> 
  </void>
 <void property="origin"> 
   <void index="0"> 
    <double>50.0</double> 
   </void> 
   <void index="2"> 
    <double>50.0</double> 
   </void> 
  </void> 
  <void property="boundsRadius"> 
   <double>100.0</double> 
  </void> 
  <void property="boundsType"> 
   <string>BOX</string> 
  </void> 
  <void property="cellSetup"> 
   <object class="org.jdesktop.lg3d.wonderland.darkstar.common.setup.ModelCellSetup"> 
    <void property="modelFile"> 
     <string>models/mpk20-web.j3s.gz</string> 
    </void> 
   </object> 
  </void> 
 </object> 
</java> 

This XML file is a serialization of a Java bean (BasicCellGLOSetup^?). You may read the full "Long Term Persistence of Java Beans" (http://java.sun.com/products/jfc/tsc/articles/persistence3/) technical article, but you should be able to build virtual worlds by simply copying example XML files and modifying key properties.

This single XML file creates a 'simple terrain' cell that loads the MPK20 demo building into the virtual world at the location (50, 0, 50).

Loading the WFS into Wonderland

Next, you will tell Wonderland to create the virtual world defined by your WFS. At this point you should have either downloaded and compiled Wonderland or downloaded a binary build of Wonderland.

Loading WFS into a Wonderland workspace you have built yourself

1. In your lg3d-wonderland/ directory, edit the src/config/WonderlandServerConfig.xml file in a text editor and edit the worldType property to read WFS (between the <string> ... </string> tags). Save the file and exit the text editor. (You may also have a WonderlandServerConfig.xml file in your home directory at ~/.wonderland/config/WonderlandServerConfig.xml. Settings in this file will override settings in the WonderlandServerConfig.xml located in the lg3d-wonderland/ directory).
2. Create a file my.build.properties in your lg3d-wonderland/ directory and add the line: wonderland.wfs.root=file://base_path/test-wfs. Save the file and exit your text editor. Note that this property must be a well-formed URL, so the file:// prefix is needed.
3. Start the Wonderland server using the following command: ant run-sgs
4. Start the Wonderland client using the following command: ant run

Loading WFS into a Wonderland binary build

1. Find your Wonderland installation directory. This directory depends on the platform you are using. On Windows, this is typically in C:\Program Files\Project Wonderland. On Unix platform, it is in /opt/wonderland. On all platforms, the Wonderland installation directory will include a number of files and folders, including an ant, lib and worlds directory.
2. In the Wonderland installation directory, create a file called my.run.properties if it does not exist.
3. Add the line:

   wonderland.wfs.root=file://base_path/test-wfs

   Save the file and exit your text editor. Note that this property must be a well-formed URL, so the file:// prefix is needed. For example:

   wonderland.wfs.root=file://opt/wonderland/worlds/test_world

4. Restart the Wonderland server and voice bridge

After a few moments, you should find yourself inside of the (empty) MPK20 demo building. You will learn how to add items inside this building shortly.

Tour of a cell's XML file

Before you learn some more features of WFS, let's take a closer look at the XML file describing the setup properties of the simple terrain cell you created in your first WFS. In fact, all cell types share many of the same setup properties; the simple terrain cell XML setup file makes a good example.

All XML files contain the same header and footer that identifies the Java bean long-term persistence mechanism as the facility that performs the de-serialization.

<?xml version="1.0" encoding="UTF-8"?> 
<java version="1.6.0-dp" class="java.beans.XMLDecoder"> 
... body ...
</java> 

All XML files result in the creation of a BasicCellGLOSetup^? class; the next line in the XML file after the header instantiates this class:

<object class="org.jdesktop.lg3d.wonderland.darkstar.server.setup.BasicCellGLOSetup">

Within the object declaration exists a series of Java bean property definitions that take the general form:

<void property="name">
   ... properties values ...
</void>

Property definitions may appear in any order within the object declaration.

First, you specify which type of cell you are creating with the cellGLOClassName property, that takes the class name of the cell:

 <void property="cellGLOClassName"> 
   <string>org.jdesktop.lg3d.wonderland.darkstar.server.cell.SimpleTerrainCellGLO</string> 
  </void> 

Each cell must define its origin with respect to its parent using the origin property that takes an array of doubles of length 3. (Strictly speaking, the origin property is optional and if absent, the origin of the cell defaults to (0, 0, 0)). For example, the following sets the origin to (50, 0, 50). Note that missing individual elements of the array default to the value zero.

<void property="origin"> 
   <void index="0"> 
    <double>50.0</double> 
   </void> 
   <void index="2"> 
    <double>50.0</double> 
   </void> 
  </void> 

As a short-cut, arrays may be defined in a property definition as follows too:

<void property="origin">
  <double>50.0</double>
  <double>0.0</double>
  <double>50.0</double>
</void>

Next, you may define the bounds of your cell. The bounds are used when computing which cells are currently visible to the avatar. The following defines the bounds to be a (3-D) box with a radius of 100.0 units. (The radius of a box is half of the length of one of its sides).

<void property="boundsRadius"> 
   <double>100.0</double> 
</void> 
<void property="boundsType"> 
   <string>BOX</string> 
</void>

Finally, the simple terrain cell contains one cell-specific property: the name of the file containing the 3-D geometry. This property is a class related to the cell type, in this case, the ModelCellSetup^? class. The ModeCellSetup^? object itself has one property, modelFile, a string name of the property file. The property file is given with respect to the Wonderland system-wide base URL used for visual resources.

 <void property="cellSetup"> 
   <object class="org.jdesktop.lg3d.wonderland.darkstar.common.setup.ModelCellSetup"> 
    <void property="modelFile"> 
     <string>models/mpk20-web.j3s.gz</string> 
    </void> 
   </object> 
  </void> 

Adding new cells to your virtual world

One nice feature of WFS is you may add (and remove/edit) cells in your virtual world without having to restart your Wonderland client and server. You may edit your WFS on disk and tell the Wonderland server to re-load its contents on-the-fly. We will flush out several of the items inside the MPK20 demo building. These cells also illustrate the use of other cell types.

1. In your *base_path*/test-wfs directory, create a subdirectory named building-wld. Wonderland automatically looks for child cells in specially named directory with a -wld suffix. In this case, for the building-wlc.xml cell, Wonderland will look for the building-wld/ directory.
2. In the building-wld/ subdirectory, create a file named slideshow-wlc.xml and copy the following contents into it using a text editor. Save and exit the text editor.

<?xml version="1.0" encoding="UTF-8"?> 
<java version="1.6.0-dp" class="java.beans.XMLDecoder"> 
 <object class="org.jdesktop.lg3d.wonderland.darkstar.server.setup.SlideShowCellGLOSetup"> 
  <void property="cellSetup"> 
   <object class="org.jdesktop.lg3d.wonderland.darkstar.common.setup.SlideShowCellSetup"> 
    <void property="mode"> 
     <object class="org.jdesktop.lg3d.wonderland.darkstar.common.setup.SlideShowCellSetup$Mode" method="valueOf"> 
      <string>CLIENT_AUTO</string> 
     </object> 
    </void> 
    <void property="slideFiles"> 
     <array class="java.lang.String" length="8"> 
      <void index="0"> 
       <string>welcome_slides/img0.png</string> 
      </void> 
      <void index="1"> 
       <string>welcome_slides/img1.png</string> 
      </void> 
      <void index="2"> 
       <string>welcome_slides/img2.png</string> 
      </void> 
      <void index="3"> 
       <string>welcome_slides/img3.png</string> 
      </void> 
      <void index="4"> 
       <string>welcome_slides/img4.png</string> 
      </void> 
      <void index="5"> 
       <string>welcome_slides/img5.png</string> 
      </void> 
      <void index="6"> 
       <string>welcome_slides/img6.png</string> 
      </void> 
      <void index="7"> 
       <string>welcome_slides/img7.png</string> 
      </void> 
     </array> 
    </void> 
   </object> 
  </void> 
  <void property="origin"> 
   <void index="0"> 
    <double>-0.3100000000000023</double> 
   </void> 
   <void index="1"> 
    <double>1.9</double> 
   </void> 
   <void index="2"> 
    <double>-1.3599999999999994</double> 
   </void> 
  </void> 
 </object> 
</java> 

Next, tell Wonderland to load the new cell into your world on-the-fly with the following steps:

1. In the lg3d-wonderland/ directory, execute the following command: ant run-manager
2. Click on the "Apply" button to connect to the Wonderland server.
3. Click on the "Maintenance" tab, click the "Reload Root WFS" button. The new cell should display a slide show introducing Wonderland and the MPK20 demo; the slides should advance automatically.

One convenient feature of WFS is the ability to quickly add and remove cells from your world. To remove the 'slide show' cell you just created (temporarily):

1. Rename the slideshow-wlc.xml file to slideshow.xml. Since it no longer has its -wlc suffix, it will no longer be recognized as a cell within your virtual world.
2. Click on the "Reload Root WFS" button on your manager window and observe that the slide show disappears.

You may also rename the entire buidling-wld directory to (temporarily) remove all of the child cells underneath the building-wlc.xml cell.

Next Steps

Feel free to experiment with adding more cells to the MPK20 demo building; the complete MPK20 demo WFS can be found in the lg3d-wonderland/src/worlds directory. Other types of cells include animated, audio, and model viewer cells.

You may also place your WFS inside of a JAR file--inside your JAR file, your WFS directory (e.g. test-wfs) is the root-level entry. The JAR file may be placed on your local hard drive or file system mounted on your machine, or it may be downloaded over the internet. In the latter case, set your wonderland.wfs.root property to jar:http://www.domain.com/file.jar!/, where for example, your JAR file is found at http://www.domain.com/file.jar.