This guide is in a very early stage... please feel free to contribute!
Introduction#This guide pretends to summarise all the resources available to developers. From how to start developing for Wonderland, to advanced topics, with links to existing documentation and providing new tutorials on areas that haven't been dully documented yet.
Searching for and reading the documentation#The main resource is the Open Wonderland Portal for documentation, with guides sorted by types of user.
Recommendations of how to read the docs for developers#Start by reading the introductions guides (links). then the how to develop a Cell, part 1 and 2, and then read the first simple tutorials at the jME site (links)/. Then continue parts 3 and 4. After that, it depends what you want to do.
When to read more about jME? Do I need jME at all? What versions of jME are supported? why is jME the only rendering engine? Could it be extended to support others? Yes, all is in place for other systems.
when would you need MTGame?
when to read more about swing and HUDs?
How about the other projects like avatars or others such as softphone?
Tips and tricks#We have a page dedicated to tips and tricks. Check it out and please adds tips so that other developers can benefit; Thanks in advance!
High level architecture#This is a video that introduces the different architectural levels in Wonderland.
Extending the toolkit -- Development artifacts#
How is the code structured#
The structure can be a bit confusing at the beginning because of the fact that the core of Open Wonderland is really small, and it is supplemented with a series of basic modules that give it some default functionality. All these (core + default modules) are what we generally call the Wonderland project.
The Wonderland-modules project is a series of additional modules that are not installed by default. You can choose to download it or not, although we recommend you do so if you want to benefit from the latest changes that had not made it yet to the modules warehouse.
To add a bit to the difficulty, each of these higher level projects are divided into a multitude of subprojects. Each module will be an independent project if you look at it from a development point of view. You can see them as Netbeans projects.
The following screenshots give an idea of how the two main projects are structured:
The main wonderland project, at times called also wonderland core, is divided into a series of projects in which core is one of them. That project hosts the core functionality of Wonderland, and it is supported by the other projects that can be seen in the picture.
The modules subproject is particularly important and that is why it was unfolded to show its components. The folders foundation, tools and world contain wonderland modules that provide default functionality such as HUD support, Cell functionality such as edition, or the possibility to load collada files.
The Wonderland-modules higher level project is divided into two main areas as can be seen in the screenshot. The stable folder contains modules that had been extensively tested. The unstable folder contains newer developments such as the video player.
Added to this, there is an additional set of projects that are also part of the overall Open Wonderland ecosystem. These are MT_Game, the avatars project, the modified version of JME2... complete this bit
Setting up a development environment#
You can follow the instructions in each of the projects to get this set up, or you can keep of reading for a proposed initial development environment. Please note that this initial environment is not the only or the right way to do it. You can customise as you see fits if you are familiar with technologies such as subversion and ant. You shouldn't have to do much customisation work if you follow these guidelines, and that's why this information is here.
Please note the requirements for the two projects (Java SE 6, ant 1.7.1+, and subversion). This guide will use subversion from the command line:
Proposed Structure#The symbol ~ denotes your user directory. In Windows this might be something like C:\Users\your_name, in Mac something like /Users/Your_name, and in Linux something like /home/your_name.
You can have a structure such as: ~/openwonderland/src/ and inside of it 3 main directories as follows:
| --> wonderland | | [... sources go here ...] | | --> wonderland-modules | | --> stable | | --> unstable | | --> my-wonderland-modules | | --> stable | | --> unstable
Downloading the sources#To create a structure like the one in the previous section, you just have to create the folders openwonderland/src/ within your user directory. To do so you can open a shell and do (%> denotes the prompt in your console):
%> cd ~ %> mkdir openwonderland %> cd openwonderland %> mkdir src %> cd src
Now that you are in src we are can download the sources for both core and modules projects. Please note that we are only downloading the latest version or trunk in subversion parlance.
Download core make sure you are in ~/openwonderland/src
%> svn checkout http://openwonderland.googlecode.com/svn/trunk wonderland
This should have created a wonderland folder with all the sources inside.
Download modules make sure you are in ~/openwonderland/src
%> svn checkout http://openwonderland-modules.googlecode.com/svn/trunk/0.5 wonderland-modulesthis should have created a wonderland-modules folder with all the sources inside.
the last step is to create manually the my-wonderland-modules directory and then the stable and unstable directories so you can host the modules you write.
Create my-wonderland-modules make sure you are in ~/openwonderland/src
%> mkdir my-wonderland-modules %> mkdir my-wonderland-modules/stable %> mkdir my-wonderland-modules/unstable
Now you should be ready to start developing modules. Make sure you run ant in your wonderland core directory to compile everything needed for the modules project.
Overview of the core VS module extensibility#TODO: What's in core, what parts of that are modules... structures of foundation, world, etc.
TODO: Describe extensibility points from the IEEE document
Main extensibility points#TODO: Cells and Components -- describe and introduce modules
Modules#Modules written in Java.
Cell based modules#
Cell modules with Jme
Cell modules with Swing
Components/Capabilities components also written in Java but that can be applied to any type of object inworld, providing the capabilities that the component was written for.
Plugins Although they are needed to create some modules, they can be considered an artifact by themselves (or can they?)
HUDs Heads Up Displays to show information and provide functionality in an individual way.
Scripting#Talk about the scripting engine, how it can be used and when is it a better solution than a full blow Java module.
more to come soon!