Home | Changes | Index | Search | Go

Article: Project Wonderland File System (WFS) Reference

This page provides a comprehensive reference for the XML file format that describes cells definitions contained within a WFS. This reference is meant for content and software developers who wish to create their own worlds. All XML- formatted cell description files contained within a WFS have a '-wlc.xml' suffix and extension. This page describes the attributes common to all cells.

Prerequisites

If you are new to Wonderland and have not used WFS to construct worlds before, please read the Tutorial: How to create a world using a Wonderland File System (WFS).

Preamble and footer

All XML-formatted WFS cell files begin with the same preamble and end with the same footer. All subsequent tags with these files go between these two, as denoted by the "..." below (for example, to specify the cell's origin, bounds, and other configuration information):

<?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"> 
    ...
  </object>
</java>

There is no pre-defined ordering of tags between the two <object></object> tags above.

Each of these files is an XML serialization of a Java Bean. The serialization follows the JSR 57:Long-Term Persistence for JavaBeansTM Specification. You can read tutorials and documentation on this mechanism of serialization:

• Long-Term Persistence for JavaBean (Article)
• Long-Term Persistence: An Update (Article
• Long Term Persistence of JavaBeans Components: XML Schema (Article)
• XMLEncoder and XMLDecoder classes in the Java API Documentation

The cell XML files are serializations of the org.jdesktop.lg3d.wonderland.darkstar.server.setup.BasicCellGLOSetup class.

The Cell GLO Class

The cellGLOClassName defines the type of cell created in the world and configured by the XML cell file. This must appear in the file; there may be at most one cellGLOClassName property in each XML cell file. The string value of this property depends upon what type of cell you wish to create. Please consult the quick reference table at the end of this reference for a list of all cell types and values for this property. The format of this property is as follows:

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

where in this case a "simple terrain" cell is created.

The cell origin

The (x, y, z) origin of a cell is defined by the origin property within the XML cell file. Note that the origin given is with respect to its parent cell in the spatial (and WFS directory) hierarchy. The origin property is optional within the XML cell file--if not specified, a default origin--relative to its parent--of (0, 0, 0) is used. There may be at most one origin property defined within the file.The format of this property is as follows:

    <void property="origin"> 
      <void index="0"> 
        <double>50.0</double> 
       </void> 
      <void index="1">
        <double>0.0</double>
      </void>
      <void index="2"> 
        <double>-10.0</double> 
      </void> 
    </void>

where index="0" denotes the x-axis, index="1" denotes the y-axis, and index="2" denotes the z-axis. Each cartesian component of the origin is a double-precision floating point number. In the example above, the origin is set to (50.0, 0.0, -10.0). Any individual cartesian component of the origin can be omitted, in which case it defaults to a value of zero. For example, the following sets the origin to (50.0, 0.0, 0.0):

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

The cell bounds

The bounds (3D spatial extent) of a cell is defined by both the boundsType and boundsRadius properties. Note that the bounds is with respect to the spatial center of the cell. The geometric shape of the bounds is either a sphere or a box of a given radius. The boundsType and boundsRadius properties are optional within the XML cell file--if not specified, the default bounds is a sphere of radius 4.0. There may be at most one boundsType and boundsRadius properties defined within the file. The format of these two properties is as follows:

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

These two properties can appear in either order. The boundsRadius property is a double-precision floating point number. The boundsType property is a string and must be either SPHERE or BOX. Either one of these properties may be absent: if so, then their individual values default to SPHERE (for boundsType) and 4.0 (for boundsRadius). For example, the bounds in the following example would be a box of radius 4.0:

    <void property="boundsType">
      <string>BOX</string>
    </void>

The cell scaling

The amount to visually scale the size of the geometry in the cell is given by the scale property. The scale property is optional within the XML cell file--if not specified, a default scaling of 1.0 is used. There may be at most one scale property defined within the file. The format of this property is as follows:

    <void property="scale">
       <double>3.2</double>
    </void>

In this example, the visual size of the cell is scaled by 3.2x.

The cell rotation

The visual orientation of a cell is defined by the rotation property. The cell rotation is given by a single (x, y, z) axis of rotation and a single angle (in radians) which to rotate about the rotation axis. The rotation property is optional within the XML cell file--if not specified, a default rotation of 0.0 radians about the (0.0, 1.0, 0.0) axis is used. The fact that the default axis of rotation is (0.0, 1.0, 0.0) may lead to confusing behavior and should be approached with caution (see discussion below). There may be at most one rotation property defined within the file. The format of this property is as follows:

    <void property="rotation">
      <void index="0"> 
        <double>1.0</double> 
       </void> 
      <void index="1">
        <double>0.0</double>
      </void>
      <void index="2"> 
        <double>1.0</double> 
      </void>
      <void index="3">
        <double>1.57</double>
      </void>
    </void>

where index="0" gives the x-axis component of rotation, index="1" gives the y-axis component of rotation, index="2" gives the z-axis of rotation, and index="3" gives the angle of rotation in radians. All values are double-precision floating point numbers. In the example above, the cell is rotated 1.57 radians (or 90 degrees) about the (1.0, 0.0, 1.0) axis. The angle of rotation can be either positive or negative depending upon the desired direction of rotation.

Any of the individual components may be omitted, however, care must be taken because the default value of the y-axis component of the rotation axis defaults to 1.0. In the following example, the cell is rotated 3.14 radians (180 degrees) about the (0.0, 1.0, 0.0) axis:

    <void property="rotation">
      <void index="3">
        <double>3.14</double>
      </void>
    </void>

And in the following example, the cell is rotated -1.57 radian (-90 degrees) about the (1.0, 1.0, 0.0) axis:

    <void property="rotation">
      <void index="0">
        <double>1.0</double>
      </void>
      <void index="3">
        <double>-1.57</double>
      </void>
    </void>

If you wish the y-axis component of the rotation to be a value other than 1.0, you must explicitly include the index="2" value.

The cell-type specific setup information

The cellSetup property defines the cell type-specific configuration information. Each specific cell type may contain additional configuration information. For example, the "simple terrain" cell type takes the path name of the 3D geometry model file within the WFS cell file. In general, this property is required; at most one cellSetup property may appear in the XML file. The general format of this property is as follows:

    <void property="cellSetup">
      <object class="classname">
        ...
      <object>
    </void>

where "classname" is the fully-qualified class name of the cell type-specific configuration class. A list of these classes for the standard cell types in Project Wonderland is given below. The additional configuration attributes are placed between the <object></object> tags, denoted by "...".

Summary of XML attributes

This table summarizes the information contained within this reference:

List of cellGLOClassName and cellSetup property values for standard cell types

The following lists the standard set of cell types within Project Wonderland, the value of their cellGLOClassName and cellSetup properties, and a link for more detailed information about their configuration parameters.