 |
Home | Changes | Index | Search | Go
(DRAFT) Project Wonderland v0.5 Module Specification
1. Introduction
This specification defines a module system for the Project Wonderland Virtual World Toolkit. Modules contain
add-on functionality to Wonderland in the form of either (or all) executable code (e.g. new services, cell types),
collections of artwork, textures, or 3D geometry to be used within virtual worlds, and WFSs (Wonderland File
Systems) that assemble geometry, art, and textures into re-usable portions of virtual worlds.
A module in Project Wonderland is a JAR-formatted archive file. This specification defines
the structure of module archive files.
In previous versions of Project Wonderland (v0.4 and earlier), 'modules' referred strictly to runnable code. Here,
the term 'modules' assumes a broader meaning to include artwork as well. Runnable code--now contained within
a modules--are called 'plugins'.
2. Module Archive Files
Modules are contained within JAR-formatted archive files. No special entries are needed within the manifest
of the JAR archive. The JAR archive file may assume any name, however, it is recommended that developers
include a '-wlm' suffix in their JAR archive file names to distinguish Wonderland module archives from other
types of archives.
Each module installed within a single Wonderland server must have a unique name. The name of the archive is
given in a module.xml file contained within the archive (see Section 2.1 below).
Each module may have an optional version, also defined within the module.xml file. Only a single version of each
module may be installed on a single Wonderland server. Modules may declare dependencies on specific modules
they depend upon. In the 'requires' declaration, modules may require certain specific versions of other modules that
need to be installed.
The structure within a module archive is (Figure 1):
Figure 1: Module directory structure
module-wlm.jar/
|------ module.xml
|------ requires.xml
|------ repository.xml
|------ client/
|------ common/
|------ server/
|------ wfs/
|------ art/
|------ help/
A module consists of a series of XML-formatted files describing the module (module.xml, requires.xml, and
repository.xml). Only the module.xml file is required. Modules also contains subdirectories containing module
"parts". A module part is a component of a module for a specific purpose: to include 3D art assets, to include
client-side code, etc. The types of module parts is flexible, although several standard module parts are defined
in this specification.
2.1 The module.xml file
Each module has a unique name and version, as defined in the module.xml file. The module.xml file
(Figure 2, example; Figure 3, DTD) contains the module's name, an (optional) version number, and an
(optional) text description between the <wonderland-module></wonderland-module> tags. A module's
version consists of a major and minor version number between the tags. If version
tags exist, a major version number must be provided; the minor version number is optional. If a minor
version number is not specified, zero (0) is assumed.
Figure 2: Example module.xml
<?xml version="1.0"?>
<wonderland-module>
<name>MPK20 Demo</name>
<version>
<major>1</major>
<minor>2</minor>
</version>
<description>The MPK20 demo building</description>
</wonderland-module>
Figure 3: XML DTD for module.xml
<?xml version="1.0"?>
<!ELEMENT wonderland-module (name, version?, description?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT version (major, minor?)>
<!ELEMENT major (#PCDATA)>
<!ELEMENT minor (#PCDATA)>
<!ELEMENT description (#PCDATA)>
2.2 The requires.xml file
Modules may require other modules to be installed too. A module may define these dependencies via the
requires.xml file (Figure 4, example; Figure 5, DTD). Each dependency consists of the unique module name
and an optional version number. If no version number is specified, then any version of the module is acceptable.
If a version number is specified in the requires.xml file, then any later version of the required module (greater than
or equal to the specified version) is also acceptable. A module is installed only after all of its dependencies have
already been installed. Cyclic dependencies are not permitted; modules with cyclic dependencies will not be installed.
Each requires.xml file contains one or more tags. Within each exists the unique name of the
module dependency and an optional version number. The minor version number may be omitted, if so, zero (0) is
assumed. In the example below (Figure 4), any version >= 1.0 of the "MPK20 Demo" module is acceptable.
Figure 4: Example requires.xml
<?xml version="1.0"?>
<requires>
<name>MPK20 Demo</name>
<version>
<major>1</major>
</version>
</requires>
Figure 5: XML DTD for requires.xml
<?xml version="1.0"?>
<!ELEMENT requires (name, version?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT version (major, minor?)>
<!ELEMENT major (#PCDATA)>
<!ELEMENT minor (#PCDATA)>
2.3 The repository.xml file
The repository.xml file contains a list of base URLs that describe the master and list of mirror repositories
of where assets within the module can be downloaded (Figure 6, example; Figure 7, DTD). It is
optional: if it does not exist, then Wonderland assumes the machine on which the module is installed is
the sole repository of assets. Any master or mirror entry within the repository.xml file may contain the
special tag, %WL_SERVER%, to indicate that the machine on which the module is installed is designated
as the repository. When the Wonderland server loads the module, it replaces the %WL_SERVER% tag
with its own URL of where clients can download assets.
Figure 6: Example repository.xml file
<module-repository>
<master>%WL_SERVER%</master>
<mirror>http://www.arts.com/art/modules/mpk20</mirror>
<mirror>http://java.net</mirror>
</module-repository>
Figure 7: The repository.xml DTD
<?xml version="1.0"?>
<!ELEMENT repository (master?, mirror*)>
<!ELEMENT master (#PCDATA)>
<!ELEMENT mirror (#PCDATA)>
Asset repositories are discussed further below, in section 2.6: Artwork repositories: masters and mirrors.
2.4 Module "Parts"
Every module contains a collection of "parts"; module parts contain assets or software that belong to the module
and are deployed to Wonderland. All module parts are contained within the top-level directory of the module; each
part is identified by the name of the directory. The structure of the module part directory itself is specific to the
module part type. The supported module part types may be easily expanded in the future, however, several common
part types are defined here.
2.4.1 Artwork Assets (art/)
Artwork (i.e. textures, images, or 3D geometry models) are contained within a module beneath the art/ directory.
Developers are free to organize their artwork into arbitrary subdirectories beneath this directory, for example, into
models/, textures/, and images/ subdirectories. The chosen directory structure also defines the way each art resource
is uniquely identified. If a developer changes this directory structure, then references to each resource (e.g. when cells
use these resources as defined in a WFS) must also change.
Each artwork asset contained within an installed module can be identified by a unique URI. Parts
of the system that refer to the resources within modules (e.g. cell definitions within a WFS) do so
via this unique name. The unique URI of the resource consists of the Wonderland module
identifier (wla://), followed by the name of the module, followed by its location within the module:
wla://<module name>/<resource path>
For example, if a module named "mpk20" contains a model in models/mpk20-building.dae, then
its unique name is:
wla://mpk20/models/mpk20-building.dae
If the module is installed on the system, then cell files within WFS may use this unique naming
scheme to identify artwork resources. Note that the art/ directory name is assumed and does not
appear in the 'wla' URI.
2.4.2 Client-side plugins (client/)
Client-side software plugins are contained within a module beneath the client/ directory. Examples of client
plugins include new cell types. (Typically code in client/ is often paired with code in common/ and server/).
The client/ directory contains a collection of JAR archive files of compiled Java code.
2.4.3 Server-side plugins (server/)
Server-side software plugins are contained within a module beneath the server/ directory. Examples of server
plugins include new cell types. (Typically code in server/ is often paired with code in common/ and client/).
The server/ directory contains a collection of JAR archive files of compiled Java code.
2.4.4 Common code (common/)
Common software code is contained within a module beneath the common/ directory. Examples of common
code include utility code used both in client and server software plugins. (Typically code in common/ is often
paired with code in server/ and client/). The common/ directory contains a collection of JAR archive files of
compiled Java code.
2.4.5 Help
TBD
2.4.6 WFS
Modules may also contain zero or more Wonderland File Systems (WFS) within the wfs/ directory
-- the root directories for each WFS (i.e. those with the -wfs extension) should all be contained
immediately therein. The Wonderland module system automatically discovers WFSs contained
within the wfs/ directory and makes them available to whomever uses the module. For example,
if the module directory structure contained (Figure 8):
Figure 8. WFS within modules
wfs/
|------ building-wfs/
|------ room-wfs/
|------ closet/
|------ others/
|-------------- my-wfs/
then the two recognized WFSs are building-wfs/ and room-wfs/. The closet/ directory is ignored
because it does not contain the -wfs extension, nor is my-wfs/ because it not contained directly
within the wfs/ directory.
WFSs may also be contained within the wfs/ directory as jar-formatted archive files. No special
naming convention is required for the jar file names (i.e. all jar files contained directly within the
wfs/ directory are searched); see the Wonderland File System specification for the proper way to
archive WFSs.
2.5 The checksums.xml file
Different module parts may maintain list of checksums for their contents (e.g. art assets within
art/). To help uniquely identify a resource within a module and to help determine whether the correct
version of the resource is cached locally on the client, a module part may include a checksums.xml file
with unique checksums for some or all of the resources contained within it. Typically, this checksum file
is generated automatically during the installation process and developers need not be concerned about
it. Nevertheless, Figures 9 and 10 provide an example of DTD of the checksums.xml file.
Figure 9: Example checksums.xml
<?xml version="1.0"?>
<module-checksum>
<resource-path>models/castle.jme.gz</resource-path>
<checksum>ASFTGEEWDLKJF:IOSDOIJFOIJOPER</checksum>
<last-modified>16075346232</last-modified>
</module-checksum>
<module-checksum>
<resource-path>models/mpk20.jme.gz</resource-path>
<checksum>DC;GLJADSFL;ESFLJDF;ERF344ASDF</checksum>
<last-modified>16075346231</last-modified>
</module-checksum>
Figure 10: XML DTD for checksums.xml
<?xml version="1.0"?>
<!ELEMENT module-checksum (resource-path, checksum, last-modified)>
<!ELEMENT resource-path (#PCDATA)>
<!ELEMENT checksum (#PCDATA)>
<!ELEMENT last-modified (#PCDATA)>
There may be multiple <module-checksum></module-checksum> entries, each corresponding to the checksum
of some resource within the module. The <resource-path></resource-path> element gives the relative path
name of the resource, beneath the part subdirectory. The element gives the SHA-1
hash of the resource, and the <last-modified></last-modified> time gives the time (in milliseconds since the
epoch) the resource file was last modified.
In general, Wonderland allows to multiple instances of an asset with different checksums to exist at the same
time. How the Wonderland client chooses to cache assets in light of this fact is up to the implementation of
the client.
2.6 Artwork repositories: masters and mirrors
The Wonderland module system supports the notion of artwork repositories--a 'repository' is a
collection of related artwork (modules, textures, images) typically served to clients over the network.
Repository artwork is typically cached by clients locally to improve performance. In the most simple
case, an artwork repository is located within an installed module on a server; a web server embedded
in the Wonderland server delivers the artwork to clients.
Figure 11: Artwork within a module
Artwork within repositories may be served by web servers external to the Wonderland server, however.
For example, all artwork associated with the "MPK20 Demo" may be delivered by a 'master' web server
located over the Internet. Other servers ('mirrors') may also host the same artwork content, and perhaps
may be located topographically nearer to clients for better download performance or may serve as
backups for the master repository.
Figure 12: Master and mirror repositories
Figure 12 illustrates the idea of master and mirrors of artwork repositories. The "MPK20 Demo" module
has been installed on the Wonderland server. The module defines an external master host for the artwork
repository and two mirror hosts. The Wonderland server itself also serves as an available mirror. Wonderland
client (1) can successfully reach the master client and downloads the artwork from there. Wonderland client (2)
is unable to reach the master host of the repository and downloads the artwork from one of the mirrors.
Wonderland client (3) is also unable to reach the master host and decides to download the artwork from the
Wonderland server itself.
To make sure the repository contains the correct version of the desired Wonderland asset, the Wonderland
client will likely query each master/mirror repository for the checksum associated with the asset first. Then,
the Wonderland client will compare the checksum to that stored within the module checksums.xml file. (The
idea being that the module installation knows what the correct version should be). If the Wonderland client
queries all of the master/mirror repositories and does not find a suitable copy, it is up to the implementation
whether to accept a slightly different version.
This scheme allows the Wonderland client to cache multiple copies of the same asset but with different
checksums. This is useful, for example, if a user is teleporting between two Wonderland servers that rely
up the same asset, but different versions. In this case, the client should download and cache each version
of the asset once, rather than re-load the asset each time a teleport between servers happens.
2.6.1 Artwork contained locally only -- no master or mirrors (most common)
In this example, all of the artwork is contained locally within the module and served by a web server
embedded in the Wonderland server. No repository.xml file is needed. The client will always retrieve
the artwork from the Wonderland server (in addition to making local caches of the artwork for performance reasons).
2.6.2 Artwork contained within master and mirror repositories
The tags define the base URL from which the repository's artwork can be downloaded.
If the resource is specified as "wla:///" within the WFS cell file, then, in this example,
the client will form the following URL to download the artwork from the master repository:
http://wlr.arts.com//. Only one master is allowed for each repository; zero or more
tags are permitted.
Figure 13. Specifying a master and mirror repositories
<repository>
<master>http://wlr.arts.com/</master>
<mirror>http://java.net/</mirror>
<mirror>http://artwork.server.it</mirror>
</repository>
3. Issues & Future Work
This specification does not address the following issues:
- There is no support for scripts within modules.
- Module dependencies are done simply--in the future, modules may provide Java classes that can contain code that tests whether a dependency is satisfied based upon information about installed modules. Also module dependencies do not currently support localization.
- There is no way for a module to depend upon the version of the Wonderland software.
- Modules must be installed locally; there is no way to perform a network install of a module affecting multiple Wonderland installations.
- Currently, if the master host of an artwork repository is reachable, then it must be consulted first. Should this constraint should be loosened so that it is up to the client?
- There is no way to allow a user/system administrator to configure a module upon installation.
- Multi-node configurations are not yet considered for its impact on this specification.
|