Loading WFS into a Wonderland workspace you have built yourself

Loading WFS into a Wonderland binary build

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

Loading WFS into a Wonderland workspace you have build yourself

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

1. Click on the "Apply" button to connect to the Wonderland server.

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

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.

1. Create a file my.build.properties in your lg3d-wonderland/ directory and add the line:

1. Start the Wonderland server using the following command: ant run-sgs
2. Start the Wonderland client using the following command: ant run

1. In the building-wld/ subdirectory, create a file named slideshow-wlc.xml and copy

1. In the lg3d-wonderland/ directory, execute the following command: ant run-manager

1. Click on the "Reload Root WFS" button on your manager window and observe that the

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.

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, or by default, the origin becomes (0, 0, 0) using the origin property that takes an array of doubles of length 3. For example, the following sets the origin to (50, 0, 50). Note that missing 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 itself 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> 

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 "Connect" 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 observer 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.

1. Select a place on your hard drive 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="boundsRadius"> 
   <double>100.0</double> 
  </void> 
  <void property="boundsType"> 
   <string>BOX</string> 
  </void> 
  <void property="cellGLOClassName"> 
   <string>org.jdesktop.lg3d.wonderland.darkstar.server.cell.SimpleTerrainCellGLO</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> 
  <void property="origin"> 
   <void index="0"> 
    <double>50.0</double> 
   </void> 
   <void index="2"> 
    <double>50.0</double> 
   </void> 
  </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 attributes.

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

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.
2. Create a file my.build.properties in your lg3d-wonderland directory and add the line: wonderland.wfs.root=base_path/test-wfs. Save the file and exit your text editor.
3. Start the Wonderland server using the following command: ant run-sgs
4. Start the Wonderland client using the following command: ant run

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

Adding new cells to your virtual world

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

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

Project Wonderland: A Brief Architecture Overview

Project Wonderland is a software platform for the creation of 3D 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 3D volume in the world. A world has a single, right-handed, 3D cartesian coordinate system (hereafter referred to as "world coordinates"). 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. Persons, called Avatars, are also represented by cells.

Each cell has a position and bounds inside the virtual world. Each cell defines its own coordinate system, where the cell's center is at (0, 0, 0). A cell may contain 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.

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

<-- This creates the navigation links to :  Home | Help | Index | etc.  -->

ProjectWonderlandWFS

<-- this automatically adds a header showing the name of this page -->

<-- Your JavaDesktop? article goes here. Please try to include at least one sentence describing this topic. -->

<-- Also please try to include at least one sentence describing where each link goes. -->

<-- Please make sure some other page points to your new article so that others can find it! -->

<-- For more on how to write Javapedia articles please read the WritingArticles? page. -->

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

This is a DRAFT and is subject to revision: don't believe it until we tell you to

Purpose

Prerequisites

Structure of a Wonderland File System (WFS)

Creating a simple WFS

Loading the WFS into Wonderland

Details on XML-formatted cell setup files

Next Steps