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

Extending Project Wonderland by Creating New Cell Types - Part II

<-- 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 extend the simple new cell type you created in Part 1 of this tutorial series. One nice feature of Wonderland and WFS is the ability to update the world on-the-fly by simply editing XML files on the server. In this tutorial, you will learn how to support the dynamic updating of a cell's configuration.

This tutorial is designed for the v0.3 and v0.4 releases of Project Wonderland.

Prerequisites

Before completing this tutorial, you should have already successfully completed Part 1 of this tutorial series. You will be extending the functionality you implemented there.

Extending the ShapeCellGLO Class

Whenever the WFS on the server is updated and the Wonderland server is told to re-load the world, any cell whose configuration properties have changed will have its reconfigureCell() method invoked. This method is declared in the BeanSetupGLO interface.

In Part 1 of this tutorial series, you left this method empty. Here, in ShapeCellGLO.java, implement the reconfigureCell() method simply as follows:

    public void reconfigureCell(CellGLOSetup setupData) {
        setupCell(setupData);
    }

The implementation of the reconfigureCell() method simply calls the setupCell() method you implemented earlier. As a result, if you change properties of the cell such as the shape's type or its origin, the server-side object's state is updated.

Extending the ShapeCell Class

When one of a cell's properties is updated in WFS, the Wonderland server automatically sends a message to each client to tell it to update its own state -- you do not need to worry about generating these communication messages yourself! All that's left for you to implement is handle when the client-side portion of your cell type is told to reconfigure itself.

On the client-side, when one of a cell's configuration properties is updated, the Wonderland client invokes the reconfigure() method on your client-side cell class (overriding the definition of this method found in the Cell class).

Before you implement this method, make one change to your existing ShapeCell class. Make the BranchGroup you created in the setup() method to be a member variable of the class:

public class ShapeCell extends Cell {

    BranchGroup bg = null;

   .....

You will also have to modify the first line of your setup() method to read:

        bg = new BranchGroup();

Now you are ready to implement reconfigure():

    @Override
    public void reconfigure(Matrix4d origin, Bounds bounds, CellSetup setupData) {
   super.reconfigure(origin, bounds, setupData);

        if (bg != null) {
            bg.detach();
        }
        this.setup(setupData);
    }

In reconfigure() you first call the Cell.reconfigure() method. This method updates the appearance of the cell if any of its most basic properties (e.g. origin, bounds) are updated in WFS. For the remainder of your reconfigure() method, you just need to worry about the configuration properties specific to your cell class -- in this case, the cell's shape type.

To update the cell's shape type, you must first remove the existing shape and recreate a new shape. For other new cell types, you can imagine that the entire geometry need not be removed, but in this case, there is no way to change a box into a sphere without first removing the existing shape and creating a new shape.

The bg.detach() call removes the existing geometry from the world. To create the new geometry, simply reuse the code in your setup() method.

Compiling and Running

Before you recompile and run Wonderland, you should make one additional change to your environment to make things a bit easer. In the lg3d-wonderland directory, create a file (if it does not already exist) called my.build.properties and add the following line:

wonderland.developerfeatures=true

To recompile 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 (if you have left your shape-wlc.xml WFS file as is from Part 1 of this tutorial series.

Updating WFS and Reloading the World

Now you can update the type of shape in your shape-wlc.xml WFS file (or even perhaps its origin) and have its appearance instantaneously be updated in-world without having to restart either the Wonderland client or server.

1. Edit the shape-wlc.xml file in your WFS and change SPHERE to BOX. Save the file.
2. In your Wonderland Client, select Tools -> Reload World

You should see your sphere change in a box nearly instantaneously. Note that although you asked the world to be reloaded from your client, all clients will see the updated world.

Next Steps

In the next tutorial, you will learn how to texture your shape, enhancing its appearance. By using textures, you will learn how to interact with artwork repositories. Future tutorials will also explore how to receive notification of events (e.g. mouse clicks) for your cell and also manage and update the state of your cell shared among many clients.