Download, Configure, Build and Run from the Wonderland Source
This page describes how to download, configure, build and run Project Wonderland from the source
code. Generally only software developers will use Wonderland in this way--to do so, you should be
familiar and comfortable with building open-source software from the command-line using ant or
via an IDE.
The Project Wonderland source code comes bundled with most of the software you will need, including
an up-to-date version of Java 3D and Project Darkstar.
In the basic installation, you will download and compile the most essential elements of Project Wonderland.
Requirements
Wonderland is set up as a Netbeans project that includes ant scripts for running the various Wonderland services. If you're using Netbeans you can check
out and compile the project directly. If not, you need to install the following tools if not already present on your system:
Have Java SE 5 or Java SE 6 installed on your system (See these special instructions if you are running on Mac OS X).
Note that although Netbeans comes with ant, it does not add it to your path, if you wish to use the command-line too.
If you are using Netbeans, the lg3d-wonderland workspace is setup as a Netbeans project. The Netbeans community
has published tutorials on using CVS (here) and Subversion
(here).
You may invoke the ant targets (specified below) directly from Netbeans. For Eclipse users, this tutorial will guide you.
Download the lg3d-wonderland workspace
The lg3d-wonderland workspace contains all of the source code and any libraries that Project
Wonderland depends upon and is available via cvs. It contains its own ant-based build system.
This tutorial assumes you will place this workspace inside of a directory named ~/Wonderland,
although you are free to place it anywhere. To download the source, inside a terminal window from
your home directory, after you have created the Wonderland subdirectory:
where you should replace <username> with your java.net user name.
Download the wonderland-modules workspace (optional)
The wonderland-modules workspace (see http://wonderland-modules.dev.java.net) contains
a collection of optional add-on modules--for example, the PDF Viewer, and the audio and video
recorder--for Project Wonderland. The source for these add-on modules is available via a
subversion workspace. If you place the wonderland-modules workspace in the proper
location (as shown below), the lg3d-wonderland workspace will know how to compile these
add-on modules and include them in the Wonderland client and server software.
You should place your wonderland-modules workspace in the same directory as your
lg3d-wonderland workspace (e.g. ~/Wonderland). That is, lg3d-wonderland and
wonderland-modules should be sibling directories. Inside of a terminal window:
% cd ~/Wonderland
% svn checkout https://wonderland-modules.dev.java.net/svn/wonderland-modules/trunk wonderland-modules --username <username>
where you should replace <username> with your java.net user name.
Configuring Project Wonderland
The Project Wonderland software should require little configuration, if any at all. The
configuration options are stored within a properties file within the lg3d-wonderland
directory. The comprehensive list of properties and default values are stored within the
build.properties file.
You can override any of these properties by creating a my.build.properties file in the
lg3d-wonderland directory. Each entry is a key=value pair.
sgs.host
If you plan on running the Wonderland server on the same machine as the Wonderland
client (for example, for testing purposes), you may leave this property as-is. Otherwise, you
should set the IP address of your server.
For example,
sgs.host=18.203.0.46
Building Project Wonderland
You can build the Project Wonderland source code (and the optional add-on modules if you chose
to download the wonderland-modules workspace) by running the ant command in a terminal
window:
% ant
Running Project Wonderland
You run Project Wonderland by using ant targets provided by the build system. Three targets
are provided to start the voice bridge, Wonderland server, and the client respectively.
In separate terminals start the voice bridge and server:
% ant run-bridge
% ant run-sgs
When the server is ready, you should see the following message:
[java] INFO: Wonderland: application is ready
In another terminal, start the Wonderland client:
% ant run
The Wonderland client should appear and display a login dialog. Enter your name (you can use an empty password
by default).
If you'd like to run the smc (server-master client), part of the Wonderland X11 application sharing mechanism,
you can run the following script from the lg3d-wonderland directory in a fourth terminal window:
% ./src/scripts/runsmc
Note that the smc can only be run on either Solaris or Linux systems.
Finally, if you wish to run all of the server components (the Wonderland server, the voice bridge, and the smc) all
at once, rather than starting them separately as above, from a single terminal window within the lg3d-wonderland directory:
% ./src/scripts/server.sh
This script takes ~1 min to run and returns you to the prompt when complete. It automatically creates log files
in the lg3d-wonderland directory for the Wonderland server, voice bridge, and smc (named wonderland-sgs.log,
wonderland-bridge.log, and wonderland-smc.log, respectively).
Advanced Installation and Configuration
The following set of configuration steps are not required to get the Project Wonderland
software up and running--they are optional and typically only advanced users would
need to take these additional steps.
Download the lg3d-wonderland-art workspace
The lg3d-wonderland-art workspace contains all of the compiled artwork resources used
in the default (MPK20) world provided with Project Wonderland. This artwork also resides over
the Internet at 192.18.37.42, and by default, Project Wonderland will look there to download
the resources. You also have the ability to have the client load the artwork resources locally.
You may wish to download the artwork if you plan to host the artwork that comes with Project Wonderland
yourself (e.g. if you are behind a firewall and can't access the public art web server), or if you
plan on creating new worlds that include the Project Wonderland artwork along with your
own, new art.
Inside a terminal window:
% cd ~/Wonderland
% cvs -d :pserver:<username>@cvs.dev.java.net:/cvs checkout lg3d-wonderland-art
where you should replace <username> with your java.net user name.
Configuration for Different Artwork Repositories
wonderland.art.url.base
By default, each Wonderland client looks for artwork resources in a repository located at
http://192.18.37.42/trunk/lg3d-wonderland-art/compiled_models. If you wish to use another
repository, perhaps hosted by a web server on your own machine, override this property
in a my.build.properties file.
For example,
Note that the wonderland.useLocalArt must be set to false in order for Wonderland
to look for art remotely.
wonderland.useLocalArt and wonderland.art.url.local
When used in conjunction, these two parameters can be used to instruct Wonderland to
use resources located locally (i.e. on local disk). To use local artwork resources, first set the wonderland.useLocalArt
property to true and set the wonderland.art.url.local property to the URL of the local
artwork. By default, wonderland.art.url.local is set to ${wonderland.art.dir}/compiled_models,
which is the lg3d-wonderland-art workspace if you chose to download it.
For example,
If you wish to create your own custom world (see Blender Import tutorial
and the WFS tutorial), you may set the
wonderland.wfs.root property in your my.build.properties file. This property sets the URL of
the location of the WFS that describes the world. By default, it is set to file:${src.dir}/worlds/default-wfs, where {src.dir} is typically lg3d-wonderland/src.
This contains a demonstration world provided with Project Wonderland. If you wish your world
to be created from your own WFS, modify this property, for example:
wonderland.wfs.root=file:~/my-wfs
on Linux/Unix/Mac OS X and
wonderland.wfs.root=file://C:\my-wfs
on Windows.
Or if your WFS is located over the Internet inside an archive file:
You usually only need the X11 sources if you plan to make modifications to it--a binary version is included with the Java sources for normal use. It is extremely rare that you might want to download this source code, but here are the instructions just in case.
(Note: another situation in which you might need the X11 sources is if you don't have the necessary versions of certain libraries on your system and need to recompile the X11 server to use the versions of the libraries that you do have. For example, right now the binary Xvfb shipped with Wonderland requires the following Ubuntu packages: LibXfont1?, LibXext6?, LibXau6?, LibXdmcp6?, LibXtst6?, LibXi6?). If you are, for example, running on a Red Hat system that doesn't have these versions of these libraries you will need to recompile Xvfb to use the libraries you do have.).
Wonderland X11 App Sharing uses a special X server known as the "X Remote Window (XRemwin) Server." This server is similar to an VNC server except it handles windows separately. That is, instead of just displaying an entire X desktop inside the virtual world it allows windows to be individually integrated into the virtual world. This allows X windows to be treated as first class objects in the world. For example, these windows can be moved into different locations in the world and do not even have to reside in the same plane. They have complete freedom of movement and orientation.
The source code for XRW resides here. This source code is based on Xorg 7.3. It contains only the Xremwin-specific differences. It contains some entire files, which are new, and also some code fragments which change existing Xorg files. These changes must be applied incrementally to an existing Xorg source code tree. Both Linux and Solaris changes are available. There is a file in the zip bundles called README-XREMWIN which explains how to integrate this code into an Xorg server source base.
This code is licensed under the MIT License.
Other Advanced Configuration Options
For other more advanced configuration options for Project Wonderland, please see the following tutorials:
Once you have downloaded, configured, compiled, and ran Project Wonderland from the source code, you
can explore the default world provided with the distribution. To learn how to navigate and use the features
of Wonderland, read the User's Guide
and also this Quick Reference Sheet.
If you are ready to develop content or extend Project Wonderland, visit the Project Wonderland Wiki
for detailed documentation.