package org.jdesktop.lg3d.wonderland.shapecell.server;

public class ShapeCellGLO {
}

First, copy the necessary import statements into your Java class beneath the package statement:

    @Override
    public ShapeCellSetup getSetupData() {
        ShapeCellSetup setup = new ShapeCellSetup();
        setup.setShapeType(this.shapeType);
        return setup;
    }

Shape Cell: A New Cell Type

1. On the 3d folder, right-click and select New ->Folder. For Folder Name, enter shapecell and click Finish.

Inside your new folder, you will create two files: build.xml and project.xml.

1. On the shapecell folder, right-click and select New -> Other.
2. In the dialog box select Other -> Empty File. Click Next.
3. Name the file build.xml and click Finish.

Copy the following XML text int your build.xml file. Once copied, save the file.

1. Right-click on the shapecell folder and select New -> Folder. Name the folder nbproject and click Finish.
2. Inside the nbproject sub-folder, create an empty file named project.xml and copy the following contents into it.
3. Save the project.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://www.netbeans.org/ns/project/1">
    <type>org.netbeans.modules.ant.freeform</type>
    <configuration>
        <general-data xmlns="http://www.netbeans.org/ns/freeform-project/1">
            <name>shapecell</name>
        </general-data>
        <general-data xmlns="http://www.netbeans.org/ns/freeform-project/2">
            <!-- Do not use Project Properties customizer when editing this file manually. -->
            <name>shapecell</name>
            <properties>
                <property-file>nbproject/nb.properties</property-file>
            </properties>
            <folders>
                <source-folder>
                    <label>src/classes</label>
                    <type>java</type>
                    <location>src/classes</location>
                    <encoding>UTF-8</encoding>
                </source-folder>
                <source-folder>
                    <label>shapecell</label>
                    <location>.</location>
                    <encoding>UTF-8</encoding>
                </source-folder>
            </folders>
            <ide-actions>
                <action name="build">
                    <target>jar</target>
                </action>
                <action name="clean">
                    <target>clean</target>
                </action>
                <action name="javadoc">
                    <target>javadoc</target>
                </action>
                <action name="rebuild">
                    <target>clean</target>
                    <target>jar</target>
                </action>
            </ide-actions>
            <view>
                <items>
                    <source-folder style="packages">
                        <label>src/classes</label>
                        <location>src/classes</location>
                    </source-folder>
                    <source-file>
                        <location>build.xml</location>
                    </source-file>
                </items>
                <context-menu>
                    <ide-action name="build"/>
                    <ide-action name="clean"/>
                    <ide-action name="javadoc"/>
                    <ide-action name="rebuild"/>
                </context-menu>
            </view>
            <subprojects>
                <project>../../../../../../lg3d-wonderland</project>
            </subprojects>
        </general-data>
        <java-data xmlns="http://www.netbeans.org/ns/freeform-project-java/1">
            <compilation-unit>
                <package-root>src/classes</package-root>
                <classpath mode="compile">${wonderland.client.classpath}:${wonderland.server.classpath}</classpath>
                <source-level>1.5</source-level>
            </compilation-unit>
        </java-data>
    </configuration>
</project>

1. Right-click on the shapecell folder and select New -> Folder. For Folder Name, enter src/classes and click Finish.
2. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.shapecell.client" in the File Name text box and click Finish.
3. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.shapecell.common" in the File Name text box and click Finish.
4. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.shapecell.server" in the File Name text box and click Finish.

The ShapeCellGLO server class

First you will create the server-side class representing the cell, ShapeCellGLO. The purpose of the server-side class is to store the basic configuration information defined by the XML cell descriptor file in WFS. It also manages the shared state of the cell for all clients. To help manage that state, and the individual, asynchronous updates to the state from clients, the ShapeCellGLO class participates in the Project Darkstar transactional gaming infrastructure. In this first example, however, the ShapeCellGLO does not maintain shared state for different clients, and will not make use of the Darkstar transaction mechanism. (Future tutorials, will however, exercise some of this functionality.)

1. Right-click on the server folder and select New -> Java Class. Name the class ShapeCellGLO and click Finish.

First, copy the necessary import statements into your Java class:

import org.jdesktop.lg3d.wonderland.darkstar.server.cell.*;
import org.jdesktop.lg3d.wonderland.darkstar.server.setup.*;
import org.jdesktop.lg3d.wonderland.shapecell.common.ShapeCellSetup;
import javax.media.j3d.*;

Next, define your Java class:

public class ShapeCellGLO extends StationaryCellGLO implements BeanSetupGLO {

This class extends StationaryCellGLO that resides in the org.jdesktop.lg3d.wonderland.darkstar.server.cell package and is the base class for all cells that do not move. (It itself extends the CellGLO class). The ShapeCellGLO class is a "managed object" in the context of Project Darkstar (because the CellGLO class implements the ManagedObject interface). The ShapeCellGLO class also implements the BeanSetupGLO interface and its three methods setupCell(), reconfigureCell(), and getCellGLOSetup(). You will implement these three methods below shortly.

The ShapeCellGLO class maintains one piece of configurable information: a String describing the shape of the object to draw: either BOX or SPHERE. You will store this String in the ShapeCellGLO class:

       private String shapeType = null;

Implement the methods of the BeanSetupGLO class as follows:

    public void setupCell(CellGLOSetup setupData) {
        super.setupCell((BasicCellGLOSetup<?>) setupData);
        
        BasicCellGLOSetup<ShapeCellSetup> setup = (BasicCellGLOSetup<ShapeCellSetup>)setupData;
        this.shapeType = setup.getCellSetup().getShapeType();
        
        /* Setup bounds based upon shape of the object */
        if (this.shapeType.compareTo("BOX)") == 0) {
            super.setBounds(new BoundingBox());
            
        }
        else if (this.shapeType.compareTo("SPHERE") == 0) {
            super.setBounds(new BoundingSphere());
        }
    }

The setupCell() method is called after an instance of the ShapeCellGLO class is created to initialize the configurable parameters of the cell. The configurable parameters are usually set by the XML cell descriptor files within a WFS--details on how to configure this file will be discussed below. This method is passed an object that implements the CellGLOSetup interface, but also is an instance of the BasicCellGLOSetup class. The BasicCelGLOSetup class stores information common to all cell types--origin, rotation, scaling, and bounds. New cell types do not need to worry about storing these configurable parameters--the StationaryCellGLO class handles this via its own setupCell() method.

The BasicCellGLOSetup class has as one of its members (called cellSetup) a class that stores the parameters specific to your new cell type. You will define this class (ShapeCellSetup) later. The ShapeCellSetup class stores the shape type--you will use this value to initialize the shapeType String in the ShapeCellGLO class. You also use it to properly initialize the bounds of the cell.

Next, implement the reconfigureCell() and getCellGLOSetup() methods. The reconfigureCell() method is called if the parameters within the XML cell descriptor file within the WFS changes while the server is running. We leave this method unimplemented for now, but will return to it later.

    public void reconfigureCell(CellGLOSetup setupData) {
    }

The getCellGLOSetup() method returns a new BasicCellGLOSetup class (parameterized by the ShapeCellSetup class).

    public CellGLOSetup getCellGLOSetup() {
        return new BasicCellGLOSetup<ShapeCellSetup>(getBounds(),
            getOrigin(), getClass().getName(), getSetupData());
    }

Finally, implement the getClientCellClassName() method as follows. This method returns the fully-qualified class name of the client-side cell class (which you will implement shortly).

    @Override
    public String getClientCellClassName() {
        return "org.jdesktop.lg3d.wonderland.shapecell.client.ShapeCell";
    }

The ShapeCellSetup common class

Next, you will implement the ShapeCellSetup class that is compiled both into the server-side and client-side code. This class follows the Java Bean pattern and is simply meant as a container of configurable information that is passed from the server to the client.

1. Right-click on the common folder and select New -> Java Class. Name the class ShapeCellSetup and click Finish.

Implement this class as follows:

package org.jdesktop.lg3d.wonderland.shapecell.common;

import org.jdesktop.lg3d.wonderland.darkstar.common.CellSetup;

public class ShapeCellSetup implements CellSetup {

    private String shapeType = null;

    public ShapeCellSetup() {}
    
    public String getShapeType() {
        return shapeType;
    }

    public void setShapeType(String shapeType) {
        this.shapeType = shapeType;
    }
}

This class stores the type of shape as a String and has a default constructor and the standard setter and getter methods. If you wish to extend the functionality of the shape cell type (e.g. by including a radius or color configurable parameters), you would include these new parameters in this class, for example.

The ShapeCell client class

Finally, you will implement the ShapeCell client-side class that draws the shape in-world.

1. Right-click on the client folder and select New -> Java Class. Name the class ShapeCell and click Finish.

Implement this class as follows:

package org.jdesktop.lg3d.wonderland.shapecell.client;

import javax.media.j3d.*;
import com.sun.j3d.utils.geometry.*;
import javax.vecmath.Matrix4d;
import org.jdesktop.j3d.util.SceneGraphUtil;
import org.jdesktop.lg3d.wonderland.darkstar.client.cell.Cell;
import org.jdesktop.lg3d.wonderland.darkstar.common.*;
import org.jdesktop.lg3d.wonderland.shapecell.common.ShapeCellSetup;

public class ShapeCell extends Cell {

    public ShapeCell(CellID cellID, String channelName, Matrix4d origin) {
        super(cellID, channelName, origin);
    }
    
    @Override
    public void setup(CellSetup setupData) {
        BranchGroup bg = new BranchGroup();
        bg.setCapability(BranchGroup.ALLOW_CHILDREN_EXTEND);
        bg.setCapability(BranchGroup.ALLOW_CHILDREN_WRITE);
        SceneGraphUtil.setCapabilitiesGraph(bg, false);
            
        if (((ShapeCellSetup)setupData).getShapeType().compareTo("BOX") == 0) {
            Box box = new Box();
            SceneGraphUtil.setCapabilitiesGraph(box, false);
            bg.addChild(box);
        }
        else if (((ShapeCellSetup)setupData).getShapeType().compareTo("SPHERE") == 0) {
            Sphere sphere = new Sphere();
            SceneGraphUtil.setCapabilitiesGraph(sphere, false);
            bg.addChild(sphere);
        }
        cellLocal.addChild(bg);
 
    }    
}

The ShapeCell class extends the Cell class that provides the basic functionality of all client-side cells. Each sublcass must override the setup() method that takes the set of parameters configured on the server side and draws the cell in-world. In this case, the CellSetup object is an instance of the ShapeCellSetup class. Using the type of shape specified, the setup() method draws either a box or sphere (each of radius 1).

Creating a Shape Cell In-World

To create an instance of your new shape cell type in-world, you can create an XML cell descriptor file and place it within your world's WFS. In this tutorial, you will create a WFS that contains only this cell, however feel free to drop as many copies of this cell into existing worlds.

1. Edit the build.properties class in the lg3d-wonderland workspace. Change the wonderland.wfs.root property to point to ${src.dir}/worlds/shape-wfs.
2. Create the shape-wfs directory within the ${src.dir}/worlds directory (which is typically lg3d-wonderand/src/worlds/).
3. Inside the shape-wfs directory, create a file named shape-wlc.xml.

Copy the following contents into your shape-wlc.xml file and save.

<?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.shapecell.server.ShapeCellGLO</string> 
  </void> 
  <void property="cellSetup"> 
   <object class="org.jdesktop.lg3d.wonderland.shapecell.common.ShapeCellSetup"> 
    <void property="shapeType"> 
     <string>SPHERE</string> 
    </void> 
   </object> 
  </void> 
  <void property="origin"> 
   <void index="0"> 
    <double>50.0</double> 
   </void> 
   <void index="1"> 
    <double>2.0</double> 
   </void> 
   <void index="2">
    <double>40.0</double>
   </void>
  </void> 
 </object> 
</java> 

This file is formatted according to the Long-term Persistence for Java Beans mechanism (JSR-57, see http://java.sun.com/products/jfc/tsc/articles/persistence3/). It creates an instance of the BasicCellGLOSetup class containing all of the basic cell attributes (in this case, its origin) and provides the name of the cell to create in the cellGLOClassName property. As discussed previously, the BasicCellGLOSetup class has a member, cellSetup, that contains cell-type specific configuration information. In this case, we populate this member with an instance of the ShapeCellSetup class, that has a single attribute, shapeType, that stores the type of shape to draw.

The origin of the shape is set to (x, y, z) = (50.0, 2.0, 40.0) that makes the sphere hover slightly in front of our initial position.

Compiling and Running

One nice feature of the lg3d-wonderland workspace is that is automatically looks for and compiles the wonderland-modules directory. To compile and run your new cell type, inside of a shell type:

% cd lg3d-wonderland
% ant run-sgs

And in a separate shell, type:

% cd lg3d-wonderland
% ant run

The Wonderland client should appear, ask you to log in (you can use no password by default) and in a few moments you should see a black sphere appear before you.

Extra Credit

Next Steps

You should also be familiar with Project Wonderland's architecture (here) and elements of the Wonderland File System (WFS) (see tutorial here) before completing this tutorial too.

TextCell: A New Cell Type

In this tutorial, you will learn how to create a new cell type that draws 3D text in-world. The value of this text is set by a parameter in the XML-formatted cell descriptor file within WFS.

Setting up your build environment

If you have not done so already, you should have downloaded and compiled both the lg3d-wonderland and wonderland-modules workspaces. This tutorial will assume you are familiar with the Netbeans IDE--since the Netbeans compilation mechanism is based upon ant, you may complete this tutorial using other IDEs that use ant for their build infrastructure or command-line tools.

Once you have compiled your workspaces, open the wonderland-modules workspace in Netbeans using File -> Open Project. As a first step, you will copy an existing cell type's infrastructure for your new module.

1. Click on the Files view on the top-left of your Netbeans Window.
2. Expand the nodes so that the wonderland-modules/src/modules/apps/3d path is fully exposed.
3. On the 3d folder, right-click and select New ->Folder. For Folder Name, enter textcell and click Finish.
4. Expand the musicinwonderland folder and copy nbproject/project.xml and nbproject/ide-file-targets.xml files into your textcell directory.
5. Edit the project.xml file and replace the two instances of MusicInWonderland with textcell.
6. Edit the ide-file-targets.xml file and replace the one instance of MusicInWonderland with TextCell.

Next, you will create a build.xml file that compiles your cell into two JAR files: one included in the server's classpath and one included in the client's classpath. On the textcell folder, right-click and select New -> Other. In the dialog box select Other -> Empty File. Click Next. Name the file build.xml and click Finish. Copy the following XML text into your build.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="jar" name="textcell">
    <property name="modules.dir" location="../../../../.."/>
    <property name="current.dir" location="."/>

    <!-- Use my-build.properties to override default values in build.properties -->
    <property file="my.build.properties"/>

    <!-- set the project name -->
    <property name="project.name" value="${ant.project.name}"/>

    <!-- import the common build attributes -->
    <import file="${modules.dir}/build-tools/import/module-common.xml"/>
    
    <!-- the name of the client jar file -->
    <property name="module.client.jar" value="textcell-client.jar"/>
    
    <!-- all files that should be built as part of the client jar file -->
    <patternset id="module.client.classes">
        <include name="org/jdesktop/lg3d/wonderland/textcell/client/**"/>
        <include name="org/jdesktop/lg3d/wonderland/textcell/common/**"/>
    </patternset>
   
    <!-- the name of the server jar file -->
    <property name="module.server.jar" value="textcell-server.jar"/>
    
    <!-- all files that should be built as part of the server jar file -->
    <patternset id="module.server.classes">
        <include name="org/jdesktop/lg3d/wonderland/textcell/server/**"/>
        <include name="org/jdesktop/lg3d/wonderland/textcell/common/**"/>
    </patternset>
    
    <!-- extra classes for compiling the server -->
    <!-- <path refid="extra-server.classpath"/> -->
      
    <!-- copy targets so NetBeans will recognize them -->
    <target name="compile" depends="compile-client, compile-server"/>
    <target name="jar" depends="jar-client, jar-server"/>
    <target name="clean" depends="clean-all"/>
    
    <!-- You can override default methods to add functions at various
         points.  See module-common.xml for more information:
         
         -pre-init: before init
         -post-init: after init
         -pre-compile-client: before compiling client
         -post-compile-client: after compiling client
         -pre-compile-server: before compiling server
         -post-compile-server: after compiling server
         -pre-jar-client: before jar client
         -post-jar-client: after jar client
         -pre-jar-server: before jar server
         -post-jar-server: after jar server
         -pre-clean: before clean
         -post-clean: after clean
    -->
     
    <target name="-post-compile-server">
        <!-- build Search Inside the Music service -->
        <javac debug="${build.debug}"
               debuglevel="${build.debuglevel}"
               deprecation="${build.showdeprecation}" 
               destdir="${module.classes.dir}" 
               srcdir="${module.javasrc.dir}"
               nowarn="true" 
               source="1.5" 
               target="1.5">
            <classpath>
                <pathelement path="${wonderland-server.classpath}"/>
            </classpath>
        </javac>
    </target>
</project>

1. Right-click on the textcell folder and select New -> Folder. For Folder Name, enter src/classes and click Finish.

Source package architecture

Once you have your project and ant files all setup, you can create the directories in which your source code will reside. The source code for new cell types are broken up into three packages: client, common, and server. Classes in the client package are compiled into the Wonderland client, classes in the server package are compiled into the Wonderland server, and classes in the common package are compiled into both the client and server.

1. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.textcell.client" in the File Name text box and click Finish.
2. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.textcell.common" in the File Name text box and click Finish.
3. On the classes folder node, right-click and select New -> Java Package. Enter "org.jdesktop.lg3d.wonderland.textcell.server" in the File Name text box and click Finish.

The TextCellGLO server class

Cell Architecture

The basic 3D visual building block inside Wonderland are cells, comprised over a sever piece and a client piece (Figure 1).

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

Extending Project Wonderland by Creating New Cell Types

<-- 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. -->

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 and v0.4 releases of Project Wonderland.

Prerequisites