(DRAFT) Project Wonderland v0.5: Cell and Cell Component Architecture

Introduction

This document describes the Cell and Cell Component architecture in Project Wonderland v0.5. Cells represent 3D volumes in a virtual world; they also represent units of functional and network abstraction in Project Wonderland. They are the chief means to extend Project Wonderland's functionality. Cell Components, new to version 0.5, provide a way to generically add functionality to any Cell; they were designed to eliminate limitations of the pre-0.5 architecture.

Background

The Cell architecture in Project Wonderland v0.5 has been updated with two key goals in mind. firstly to make the creation of new cells (or addition of cell features) easier for developers and secondly to support better world scalability. In the updated API cells are now classic Model/View approach used in most modern UI development. The Cell is now responsible for maintaining the data model for it's state while the CellRenderer provides the view, or visual rendering, of the cell. The system supports multiple CellRenderer types for a given cell so users can, for example, develop both 2D and 3D views of a cell to provide support for differing user interfaces or devices.

In 0.4 the characteristics of a cell were hard coded in the cell's api (either directly or via subclassing), so for example, a cell was either static or could be moved around the world depending on the implementation extending MovableCell class. In 0.5 the approach has been updated to include CellComponents. These CellComponents provide the ability to dynamically add (and remove) features to a cell, which means that expensive features such as communication and movement don't have to be hardcoded into all cells. Cell developers will use a combination of subclassing and CellComponents to build new cells.

Every cell has a server and client representation, by convention the naming is Cell for the client and CellMO for the server (MO is ManagedObject).

Cells

Definition

A Cell represents a 3D volume in virtual world space, and has the following characteristics:

• A Cell represents an encapsulated unit of functionality in the virtual world.
• Cells have parent-child relationships: each Cell has a single parent (which may be the world "root") and zero or more child Cells.

Hierarchy

The entire 3D space of the virtual world consists of a hierarchy of Cells, represented by a tree. Each Cell has a single parent. Cells at the highest level in the Cell hierarchy have the world "root" as their parent, represented by a (null) value as a Cell's parent. Cells may have a set of zero or more child Cells. There is no ordering to the set of child Cells. If a Cell 'A' has a Cell 'B' as its child, then Cell 'B' must have Cell 'A' as its parent.

Figure 1: Cell hierarchy

The Cell hierarchy is mutable: child Cells may be added or removed from a parent Cell at any time. Or similarly, the parent of a Cell may be changed at any time. Altering the parent-child relationships in the Cell hierarchy may affect the appearance of a Cell in the 3D virtual world space (e.g. a Cell may move in the 3D space if its parent is changed).

IDs

Each Cell in the 3D virtual world is represented by a unique ID. The CellID class (package org.jdesktop.wonderland.common.cell) represents Cell IDs. When a Cell is created, it is assigned an unused Cell ID. Cell ID's can generally be thought of as integers, however treating them explicitly as integers should never be necessary. The CellID.equals() method can be used to compare whether two CellID objects represent the same Cell ID. The CellID.toString() method may be used to print out a Cell ID. The CellID class also implements the hashCode() method so that CellID objects may be used as keys in Maps, for example.

Name

Each Cell in the 3D virtual world has a name. The name is a non-null String. (If a null-String is set as the Cell name, then the Cell ID is returned as the name). The Cell name need not be unique, either for all Cells or even Cells with the same parent.

Transforms

A Cell transform is a tuple of < translation, rotation, scaling >. Cell transforms are represented by the CellTransform class (package org.jdesktop.wonderland.common.cell). The Cell translation is a floating-point vector <x, y, z>. The Cell rotation is a Quaternion (that can be converted into angle-axis form or Euler angle form). A Cell scaling is a single floating-point value that scales each axis by the same factor.

Bounds

A Cell bounds represents a convex and closed area that encloses the Cell in the 3D space of the virtual world. While a Cell's bounds may in theory be an arbitrarily-shaped area, in practice, two kinds of Cell bounds are supported. A rectangular bounds is represented by the tuple < origin, x-extent, y-extent, z-extent >, where origin is a 3D floating-point vector that specifies the origin of the Cell bounds with respect to the origin of the Cell. (A Cell bounds origin of < 0, 0, 0 > coincides with the Cell's origin). The x-extent, y-extent, and z-extent are floating-point values that represent the radius of the rectangular bounds along each of the x, y, and z axes. A spherical bounds is represented by the tuple < origin, radius >, where the origin is a 3D floating-point vector that specifies the origin of the Cell bounds with respect to the origin of the Cell, and radius is the radius of the sphere.

A Cell's bound is represented by the BoundingVolume class (package com.jme.bounding.BoundingVolume). The BoundingVolume class has two sub-classes: BoundingBox for rectangular-shaped bounds, and BoundingSphere for spherical-shaped bounds.

Coordinate systems

Each Cell has a right-handed cartesian, local coordinate system, where the +y axis is "up". (For example, if the +x axis is "to the right" and the +y axis is "up", then the +z axis is "out of the board" or towards the viewer). A Cell's local coordinate system has a translation of < 0, 0, 0 > and rotation (in Euler angle form) of < 0, 0, 0 > and a scaling of 1.0. Each Cell has a local transform with respect to its local coordinate system, and a local bounds with respect to its local coordinate system.

Figure 2 represents the Cell local coordinate system and the local transform for each Cell. For simplicity, only the Cell's local translation is shown.

Figure 2: Cell local coordinate system

Each Cell also has a right-handed cartesian, world coordinate system, where the +y axis is "up". The world coordinate system is formed by composing the local transforms of each of a Cell's parents in the Cell hierarchy, up to the world root. A Cell's world transform is its local transform composed with its world coordinate system. (A Cell's world coordinate system, therefore, is the same as its parent Cell's world transform). A Cell's world transform represents its actual position, orientation, scaling, and bounds within the 3D space of the virtual world.

Generally developers (and content creators) only consider and manipulate a Cell's local transform, but should be mindful of how it will be composed into the world transform.

Figure 3 represents the world transforms of the local translations of the Cells from Figure 2. Note that Cell translations down the Cell hierarchy tree are composed by summing the individual cartesian coordinates. (To compose the Cell rotations, the Quaternions are multiplied down the Cell hierarchy. To compose the Cell scaling, the floating-point scaling factories are multiplied down the Cell hierarchy. To compose the Cell bounds, the Cell's local bounds are transformed into the Cell's world coordinate system. (Paul, is this right?).

Figure 3: Cell world coordinate system

Client-server architecture

Project Wonderland implements a traditional client-server architecture. The server stores the state of the 3D virtual world, manages the sessions to each client, and provides security to the virtual world. Clients acts as the renderer for the 3D virtual world and accept input from the user.

Each Cell is represented by a client-side piece and a server-side piece. Each Cell has an underlying Java(TM) class that implements its client-side functionality that is a subclass of the Cell class (package org.jdesktop.wonderland.client.cell). Each Cell also has an underlying Java(TM) class that implements its server-side functionality that is a subclass of the CellMO class (package org.jdesktop.wonderland.server.cell). (The suffix "MO" indicates that it is a "Managed Object", an abstraction defined by the Project Darkstar middleware layer).

Both the server and clients maintain the Cell hierarchy. The server's Cell hierarchy represents the definitive set of all Cells that are present in the 3D virtual world. This tree of server-side Cell objects may be traversed using methods on the CellManagerMO and CellMO class (package org.jdesktop.wonderland.server.cell). The Cell hierarchy may be different on each client: only those Cells which are in-range of the client's avatar are in the client-side Cell hierarchy. This helps save the network bandwidth and client resources by not communicated Cells that are not visible to the client. Therefore, the client-side Cell hierarchy is a subset of the Cell hierarchy on the server. In addition to culling based upon distance, the server may not inform clients of Cells because of security reasons. For this reason, the client-side view of the Cell hierarchy is referred to as the Cell "cache", where the server determines which Cells appears in the caches for each client.

Figure 4: Client and server Cell hierarchy

Cell types

A Cell type is simply a set of Java(TM) classes that implement some new functionality in the 3D virtual world. The Cell, therefore, is the primary means that developers extend the functionality of the 3D virtual world. The Project Wonderland code base contains some standard Cell types, for example, a Cell type that displays a 3D COLLADA(TM) model in the virtual world space. Developers can easily create new Cell types to dramatically expand the functionality of the world, and distributed their new Cell types via modules.

Strictly speaking, there is no single "type" that defines a new Cell type. Rather, a new Cell type is a collection of Java(TM) classes that implement the necessary functionality. It almost always consists of a Java(TM) class that is a subclass of the Cell class on the client-side, and a Java(TM) class that is a subclass of the CellMO class on the server-side. It also typically consists of a server-side state class, a client-side state class, one or more client-side Cell renderers, a Cell factory, and optionally Cell message classes.

Client and server state

Both the client-side and server-side Cell pieces have a "state". As in a traditional client-server model, the server-side state represents the single, true state of the Cell. The client-side Cell state represents state that is derived from the server-side state and is used to initialize key parameters necessary for the client-side Cell piece to render the Cell in the 3D virtual world space. While the Project Darkstar middleware layer automatically persists the fine-grained changes in state to the server-side Cell class, a Cell's server-state is used to persist its state for the long-term. This long-term persistence can be used to "back-up" the state of the world or transfer the state of the world to another installation. Typically, the server-side Cell class (that is a subclass of the CellMO class) maintains its state in member variables and translates state into the member variables from the server-state object or translates the state stored in its member variables into a server-state object upon request.

Server-side state objects are instances of Java(TM) classes that extend the CellServerState class (package org.jdesktop.wonderland.common.cell.state). To note: although these objects are used primary on the server, they appear in the "common" package and get compiled into the client, because the server state object is also used in Project Wonderland clients. These server-side state objects, therefore, should not have any server-specific code (i.e. should not refer to classes in the "server" package). Currently, JAXB: Java Architecture for XML Binding is used as the mechanism to convert server-side state objects into XML for long-term persistence. In summary, JAXB consists of a set of Java(TM) annotations that are used to describe how member variables in the server-state state classes map to an XML schema.

Client-side state objects are instances of Java(TM) classes that extend the CellClientState class (package org.jdesktop.wonderland.common.cell.state). To note: although these objects are used primary on the client, they appear in the "common" package and get compiled into the server, because the client state object is also used in then Project Wonderland server. The server-side Cell class generates a client-side state object upon request. Typically this happens when a Cell is being added to a client's Cell cache.

Often times, the server-side state objects is nearly identical to the client-side state object. While this unfortunately results in repeating very similar code in two separate classes, the distinction is nonetheless useful in case the state the server wishes to communicate to the client some alternative or simplified representation of the state.

Figure 5: Client and server states

Life-cycle (server-side)

The server-side Cell objects have a simple life-cycle: when they exist in the server-side Cell hierarchy, they are considered "live". When they are subsequently removed from the server-side Cell hierarchy, they are considered "not live". The CellMO.isLive() method returns whether a server-side Cell class is live or not live. A Cell can only be added to a Cell cache for a client if it is live. If a Cell that is live and currently exists in any Cell cache for the client is made not live, then the Cell is removed from the Cell cache for the client.

Life-cycle (client-side)

The client-side Cell objects have a life-cycle based upon a simple state machine. If a Cell exists in the cache of the client, then the avatar is within range of the Cell, although it may not be strictly visible. The client-side Cell transitions through a series of states (here, called "status" so that it is not be confused with client-side and server-side state objects). The client-side Cell status is represented by the CellStatus class (package org.jdesktop.wonderland.common.cell).

Figure 6: Client-side Cell status

The DISK status is both the initial and the final status for the client-side Cell. When a client-side Cell transitions to a new status, it passes through all intermediate state values. The current status is available via the Cell.getStatus() method; developers may override the Cell.setStatus() method to take certain actions upon status transitions. The details of how the system affects the Cell upon status transitions is described later. The following table summarizes the meanings of each status value:

Table 1: The client-side Cell status values

Cell renderers

A Cell renderer provides a visual representation of a Cell. Multiple Cell renderers may exist for each kind of Cell. Different kinds of clients with different rendering capabilities may request different renderers for their hardware. For example, both clients may exist for 3D-capable desktop machines and clients for mobile devices that can connect to the same different and get appropriate views of the world. Currently, the Project Wonderland codebase only supports renderers for 3D-capable desktop-class machines, based upon the jMonkeyEngine rendering pipeline.

A Cell type creates a requested renderer by overriding the Cell.createCellRenderer() method. This method returns an object that implements the CellRenderer interface (package org.jdesktop.wonderland.client.cell) based upon the given renderer type. The only supported renderer type right now is for jMonkeyEngine (jME).

Cell factories

A Cell factory is a class that implements the CellFactorySPI interface (package org.jdesktop.wonderland.client.cell.registry.spi) and is annotated with the @CellFactory annotation (package org.desktop.wonderland.client.cell.registry.annotation). A Cell factory is a client-side facility that is responsible for generating a new instance of a Cell of a particularly Cell type. (Therefore, each Cell type typically has a Cell factory). A Cell factory returns an instance of the Cell's server-side state object; with that, the system knows how to create a new instance of the Cell type in the 3D virtual world.

The CellRegistry class (package org.jdesktop.wonderland.client.cell.registry) supplies a list of Cell factories registered in the system.

Cell Components

A Cell Component is a collection of Java(TM) classes for both the client-side and server-side that implement some add-on functionality to Cells independent of a specific Cell type. The Cell Component system is designed to allow the functionality of Cells to be extended without the need to subclass a particular Cell type. A Cell contains an unordered set of Cell Components. Cell Components may be dynamically added to or removed from Cells. Only a single type of Cell Component (determined by the run-time Class of the Cell Component) may exist on a Cell at a time.

XXXXX

1. CellChannelConnection - this component provides a communication channel, specific to this cell instance in the virtual world
2. MovableComponent - provides the infrastructure and api's for cells that move within the world. This component requires that CellChannelConnection component.
3. ProximityComponent(MO) - provides listeners for notification of a view crossing a set of proximity bounds. The ProximityComponent^? class is for use on the client and ProximityComponentMO^? on the server.

Cell Cache and the ViewCell

In 0.5 the ViewCell has been introduced. this cell encapsulates a real users view into the virtual world. This local view may be an avatar (see LocalAvatar^?.java) or virtual video camera etc. Each ViewCell is associated with a CellCache which manages the set of a cells that are close to and potentially visible from the ViewCell position. In 0.5 the CellCache as been refactored into an interface to allow for different cache implementations on different client types. For convenience CellCacheBasicImpl class provides implementations for the core cache features and can be used as a proxy from your own cache implementation. See ClientManager^?.Cache for the JME client implementation of the CellCache.

TODO - Document ProximityListener