ProjectWonderlandWorldBuilder < Javadesktop < TWiki

TWiki . Javadesktop . ProjectWonderlandWorldBuilder

Home | Changes | Index | Search | Go

Tutorial: Project Wonderland World Builder

by Author (Email)

Introduction

The Project Wonderland World Builder is a web application for constructing Wonderland worlds using a tile-based, drag-and-drop interface. It consists of a server-side component, a set of Javascript libraries, an HTML page, a catalog file, a set of graphics for use by the interface, and a set of specially constructed 3d models for the Wonderland client.

Installing, Setting up, and Starting the Application

  1. If you haven't already, set up your Wonderland environment to serve art locally as instructed in the ProjectWonderlandBlenderImport tutorial. Make sure you have the latest Project Wonderland artwork (the default 3d assets for the World Builder will be included).
  2. Change your "my.build.properties" file so that wonderland.wfs.root=file://YOURUSERDIRECTORY/.wonderland/worldbuilder-wfs
  3. Download the WonderlandWorldBuilder.war file from the Daily (nightly) Builds section here: https://lg3d-wonderland.dev.java.net/binary-builds.html
  4. Download Jetty from http://www.mortbay.org/
  5. Unzip the Jetty archive and put the WonderlandWorldBuilder.war file in the Jetty "webapps" directory
  6. Start the server (from the Jetty directory): java -jar start.jar
  7. In a web browser (Firefox recommended), go to http://localhost:8080/WonderlandWorldBuilder/

Using the World Builder

If everything is working, you should see an empty World Builder workspace. It may give you an error saying "Failed to load world from server." -- not to worry! We simply don't have a world to load. So let's make one.

The World Builder consists of a toolbar at the top, a large grid area (the "workspace") on the left, and a library pane on the right. The workspace is where you will assemble your world, looking at it from a top-down view. Each grid square represents an area suitable for a single avatar to stand in.

First we need to load a catalog. A catalog is a collection of components that can be used to construct a world, represented as JSON. In the future, you will be able to load a catalog from any URL, but for now only local catalog files may be loaded. The text field labeled "Load Catalog:" is pre-populated with the URL to the default catalog (http://localhost:8080/WonderlandWorldBuilder/catalog.json), so simply click in the text field and press the Enter or Return key on your keyboard to load the catalog from the URL.

The dropdown labeled "Select Library:" should now be populated and the first library in the list should display, in this case the library is "Floors" and there is an icon for a floor tile in the library pane.

Catalogs can contain multiple libraries, which are essentially tags which can be applied to components to group them together. In the default catalog, the libraries are Floors, Furniture, Office-Conservative, and Walls. The libraries make it easy to select components that have a common visual style (e.g. Office-Conservative), or components that are of a particular type (e.g. Floors). Components from different libraries, even from different catalogs, can be mixed and matched to form your world.

Now that we have a catalog loaded, we can begin selecting components from the libraries and build the world. Select libraries using the dropdown menu -- the library pane will be updated automatically with icons representing the components in the selected library. Click-and-drag a Floor component from the library onto the grid. Notice that the icon swaps to a top-down-view "tile" representation of the component. Components can be repositioned on the grid by dragging. Unwanted components can be removed by dragging-and-dropping on the trash can in the lower left of the workspace. Place some floor tiles together to form a rectangular area suitable for a room. A single avatar comfortably occupies one grid square, so use that as a rule of thumb when building your room.

Some components, such as walls, have a facing direction, meaning they can be rotated to face north, south, east, or west in the world. Components that have a facing direction will display arrows upon dropping in the workspace; mousing over these arrows changes the facing direction of the component; clicking on an arrow sets the facing direction, as does mousing off the arrow in the corresponding direction. With a little practice you can quickly set rotations for components just by mousing off in the desired direction. Clicking a component with a facing direction will re-display the arrows. Drag out some wall components to create walls for your room, rotating them into position.

When you have completed your room, simply click the Save World button on the toolbar. The application will create a Wonderland File System (for more into see ProjectWonderlandWFS) at YOURUSERDIRECTORY/.wonderland/worldbuilder-wfs which can now be loaded into Wonderland. Start up your server and client to see your World Builder world.

The next time you start the World Builder, it will load the Wonderland File System from the worldbuilder-wfs directory and display it within the workspace for you to edit.

Note that there is a known bug that prevents worlds with single components (e.g. a world with 1 floor tile) from loading properly into the World Builder. The workaround is to just add another component and resave.

Creating Custom Components for the World Builder...

Note, you should carefully review the new ProjectWonderlandArtImportTutorial document. If you use the built-in model import tool instead of j3dfly, then file locations for models and textures might be different. Specifically, select the lg3d-wonderland-art/compiled_models directory. This puts models in lg3d-wonderland-art/compiled_models/models and textures in lg3d-wonderland-art/compiled_models/textures.

Before starting make sure you have downloaded J3DFly? from cvs:

cvs -d :pserver:username@cvs.dev.java.net:/cvs co j3dfly

You will need J3DFly? to export models to your local Wonderland art directory.

...with just a Text Editor and any Image Editing Application (e.g. Gimp)

Although it requires a dedicated 3d modeling application to create a custom component for the World Builder from scratch, there are template files included with the World Builder that can be modified using relatively simple tools. One thing that is simple to do is to create the basic room construction components (walls, floor and ceiling) and give them your own textures.

  1. With the World Builder running, open a browser and go to http://localhost:8080/WonderlandWorldBuilder/template_files/ -- it should display a directory listing. (note, if you built your own Wonderland.war and deployed on Glassfish, the directory listing may be here instead: http://localhost:8080/Wonderland/worldbuilder/template_files/ )

  2. Let's start by customizing the floor/ceiling tile. Download the following files:
  3. Open worldbuilder_template_floor.x3d in a text editor (e.g. Notepad). Since we're making a custom version of the floor/ceiling tile, let's immediately save this file as with a different name, worldbuider_custom_floor.x3d.
  4. Open worldbuilder_template_floor.png and worldbuilder_template_ceiling.png in your image editing application of choice. Again, since we are making custom versions of these files, it's a good idea to immediately save these files with different file names so we don't accidentally overwrite our template files (although you can always get them again from http://localhost:8080/WonderlandWorldBuilder/template_files/). Save them as worldbuilder_custom_floor.png and worldbuilder_custom_ceiling.png.
  5. Modify these images as you see fit (change the color, paste in another image file, etc.) and save your work.
  6. In your text editor, search for worldbuilder_template_floor.png and replace it with worldbuilder_custom_floor.png. Search for worldbuilder_template_ceiling.png and replace it with worldbuilder_custom_ceiling.png. Save the file.
  7. Start J3dFly? (in the j3dfly directory use the command ant run-j3dfly), and load worldbuilder_custom_floor.x3d. At first you will probably see nothing -- this is because the camera you are looking through is positioned at the same coordinates as the floor/ceiling tile. Choose Viewing Platform -> Show All -> Y and you should see your customized floor. Choose Viewing Platform -> Show All -> -Y and you should see your customized ceiling. Selecting Viewing Platform -> Orbit will allow you to rotate/translate the camera with your mouse, so you can see how the floor and ceiling face each other. The Orbit controls are:
  8. Now we're ready to export our custom floor/ceiling tile for use in Wonderland, but first let's make custom directories for our model and texture files to keep things organized. In your lg3d-wonderland-art directory, create the following directories:
  9. Now we can save out the file for use in Wonderland. Choose Plugins -> Wonderland -> Export to Wonderland. Choose directory paths that you just created, lg3d-wonderland-art/compiled_models/models/worldbuilder/custom/ and lg3d-wonderland-art/compiled_models/textures/worldbuilder/custom/ for the model and texture files, respectively.
  10. Don't forget to copy the texture files (worldbuilder_custom_floor.png and worldbuilder_custom_ceiling.png) to lg3d-wonderland-art/compiled_models/textures/worldbuilder/custom/.
  11. The World Builder interface requires a couple of image files to represent our custom floor/ceiling tile -- an icon which will appear in the library, and a tile which will be positioned within the workspace. So we'll take some screenshots in J3DFly? and use our image editor to make those:
  12. Before we make our custom icon and tile images, we need a place to put them that can be easily accessed by the World Builder application. In your Jetty installation webapps directory (e.g. jetty-6.1.8/webapps/) where you put your WonderlandWorldBuilder.war file, create a new directory, custom/.
  13. Now open up worldbuilder_template_floor_icon.png and worldbuilder_template_floor_tile.png in your image editor. Save these as worldbuilder_custom_floor_icon.png and worldbuilder_custom_floor_tile.png in the webapps/custom/ directory you made previously.
  14. Open up your screenshots and use them to create a new icon and a new floor tile, using the existing files as templates. Save your work.

The same process can be repeated using the worldbuilder_template_wall and worldbuilder_template_corner files to create the pieces necessary to build walls. The only different is that these require four tile images for each of the cardinal directions -- north, south, east, and west (e.g. worldbuilder_template_wall_tile_n.png, worldbuilder_template_wall_tile_s.png, etc.). In addition, the wall and corner pieces use the same (and only one) texture file, worldbuilder_template_wall.png.

The next step is to create a custom catalog and add your new component(s) to it. Scroll down to the section "Adding a Custom Catalog, and Adding New Components to the Catalog".

...Using a 3d Modeling Application (e.g. Blender)

With a 3d modeling tool you can make a endless amount of custom content for the World Builder, provided you follow a few guidelines to make your components "fit".

In this tutorial we will create one of the basic room components: a floor/ceiling tile. This will help you understand the how to correctly size and position your objects so they will function properly in the World Builder. The steps will be explained using Blender, but the process for Maya is similar (exceptions will be noted below).

  1. Start Blender. If you have a default installation, your scene will contain a Cube at the center.



    Add a new Cube to your scene if you don't have one already. Luckily the default Cube size in Blender is 2x2x2 units (you can verify this in the Transform Properties panel by hitting "N" on the keyboard with the Cube selected), which corresponds nicely to the World Builder grid. A World Builder grid square is exactly 2x2 Blender (or Maya) units. Roughly this is enough space for a single avatar to stand in.
  2. Treat the grid plane as the "floor" relative to what you are building. Since we are building a floor/ceiling tile, we'll start by translating the Cube up so that it sits on the grid.



    Holding CTRL while translating will snap the movement in even increments, making it easy to position the Cube on the grid perfectly.
  3. The floor/ceiling tile is really just two planes facing each other, 8 units apart. Therefore we can go ahead and remove the four extra vertical faces of the Cube, so we just have the top and the bottom.



    Select the top and bottom faces and flip the normals (so the floor faces up and the ceiling faces down).
  4. the recommended height for World builder ceilings and walls is 8 units high -- they don't have to be, but using this as a guideline facilitates interoperability between various World Builder catalogs and components. While still in Edit Mode, select the vertices of the upper face (ceiling) and translate them up so they are 8 units from the floor (easiest way to do this is to hit "N" on the keyboard to bring up the Transform Properties panel, set the coordinates to Global, and set the Median Z value to 8).

  5. All World Builder components have their centers at 0,0,0. Currently our "Cube" still has its center point floating above the grid plane, so let's fix that. If you haven't moved your 3d Cursor, it should still be at 0,0,0, so simply click the Center Cursor button in the Mesh panel of the Editing group:



    If your 3d Cursor is not at 0,0,0, press shift-C to move it to 0,0,0 (alternatively, you can create an Empty, set the Location and Rotation values to 0, then (with the Empty selected) hit Shift+S and select Snap Cursor -> Selection. Then hit the Center Cursor button).
  6. Unfortunately, the x3d exporters for Blender do not support using multiple images for textures, so without getting into laying out UVs and compositing a new image file with both floor and ceiling textures, we'll just make the floor and ceiling look the same. Go into the Shading -> Texture panels and load the worldbuilder_template_floor.png file into the texture channel of the material (the default material, or create a new material).

  7. Now that the image is loaded into the texture channel, split your work area so that you have the UV/Image Editor open in one pane and the 3D View open in the other. Go into UV Select Mode, select all faces, and assign the worldbuilder_template_floor.png to the faces in the UV/Image Editor (since you already loaded the file into the texture channel, you can simply select the loaded texture from the dropdown in the UV/Image Editor).



    To see the texture on the object, go into Object Mode and select Textured Viewport Shading.

  8. While the coordinate system in Wonderland is "Y-up" (meaning the y-axis points up), the coordinate system in Blender is Z-up. Therefore, we need to rotate our model -90 degrees on the x-axis to get the floor facing up.

  9. Export the model using Adrian Cheater's x3d exporter (http://www.bitbucket.ca/~acheater/blender/). Note that this will be listed as just "X3D" under the File -> Export menu, not "X3D Extensible 3D (.x3d)" (that's the default one included with Blender). Also, you may need to install Python to get it to work, depending on your computing environment. Choose "Selected Objects" not "All Objects". Save it as worldbuilder_custom_floor.x3d.
  10. Start J3dFly? (in the j3dfly directory use the command ant run-j3dfly), and load worldbuilder_custom_floor.x3d. At first you will probably see nothing -- this is because the camera you are looking through is positioned at the same coordinates as the floor/ceiling tile. Choose Viewing Platform -> Show All -> Y and you should see your customized floor. Choose Viewing Platform -> Show All -> -Y and you should see your customized ceiling. Selecting Viewing Platform -> Orbit will allow you to rotate/translate the camera with your mouse, so you can see how the floor and ceiling face each other. The Orbit controls are:
  11. Now we're ready to export your custom floor/ceiling tile for use in Wonderland, but first let's make custom directories for the model and texture files to keep things organized. In your lg3d-wonderland-art directory, create the following directories:
  12. Now we can save out the file for use in Wonderland. Choose Plugins -> Wonderland -> Export to Wonderland. Choose directory paths that you just created, lg3d-wonderland-art/compiled_models/models/worldbuilder/custom/ and lg3d-wonderland-art/compiled_models/textures/worldbuilder/custom/ for the model and texture files, respectively.
  13. Don't forget to copy the texture file (worldbuilder_custom_floor.png) to lg3d-wonderland-art/compiled_models/textures/worldbuilder/custom/.
  14. The World Builder interface requires a couple of image files to represent our custom floor/ceiling tile -- an icon which will appear in the library, and a tile which will be positioned within the workspace. So make a couple of renders for those:
  15. Before we make our custom icon and tile images, we need a place to put them that can be easily accessed by the World Builder application. In your Jetty installation webapps directory (e.g. jetty-6.1.8/webapps/) where you put your WonderlandWorldBuilder.war file, create a new directory, custom/.
  16. Now open up worldbuilder_template_floor_icon.png and worldbuilder_template_floor_tile.png in your image editor. Save these as worldbuilder_custom_floor_icon.png and worldbuilder_custom_floor_tile.png in the webapps/custom/ directory you made previously.
  17. Open up your renders and use them to create a new icon and a new floor tile, using the existing files as templates. Save your work.

For furniture and other objects larger than 1 grid square, remember that currently objects can only occupy spaces of equal width and height on the grid, e.g. 1x1 grid square, 2x2, 3x3, and so on. Always expand out from 0,0,0, and place everything on the grid plane.

Take a look at the template files for the wall and corner sections to see how to construct your own wall pieces. The process is similar to creating the floor/ceiling tile.

Template files for Blender and Maya have been created to use as reference. To retrieve these files:

  1. With the World Builder running, open a browser and go to http://localhost:8080/WonderlandWorldBuilder/template_files/ -- it should display a directory listing.
  2. The template files are (.blend for Blender and .mb for Maya):
    Note
    Blender 2.45 and Maya 2008 were used to create these files.
  3. The texture files are:

Proceed to the next section to create a custom catalog and add your new component(s) to it.

Adding a Custom Catalog, and Adding New Components to the Catalog

  1. The catalog file is a simple text file containing JSON code. With your Jetty server running, download http://localhost:8080/template_file/worldbuilder_template_catalog.json (or http://localhost:8080/Wonderland/worldbuilder/template_files/worldbuilder_template_catalog.json on Glassfish scratch build) and save it to your Jetty installation directory's webapps/custom/ directory (or create a "custom" directory if you don't have one already). Rename it catalog.json to keep things simple. (note: Glassfish directory will be more like this: glassfish/domains/domain1/docroot/custom)
  2. Open this file in a text editor. You will see it contains sample data already: "Floor", "Wall", and "Corner Wall". Each entry has a set of fields containing data about the component, e.g.: 
             name: "Floor",
         library: ["Floors","Template"],
         width: 1,
         height: 1,
         zIndex: 1,
         rotatable: false,
         description: "A floor tile.",
         tileImageURL: "worldbuilder_template_floor_tile.png",
         iconImageURL: "worldbuilder_template_floor_icon.png",
         modelURL: "models/worldbuilder/template/worldbuilder_template_floor.j3s.gz",
         cellSetupType: "org.jdesktop.lg3d.wonderland.darkstar.server.setup.BasicCellGLOSetup{org.jdesktop.lg3d.wonderland.darkstar.common.setup.ModelCellSetup}", 
         cellType: "org.jdesktop.lg3d.wonderland.darkstar.server.cell.SimpleTerrainCellGLO"
    Let's look at each field in this entry and see what they mean. Follow along and make changes as necessary in your catalog.json for your new component(s).
  3. So if you are following one of the tutorials above and creating a custom component, for example "worldbuilder_custom_floor", you would make changes to your catalog like so: 
             name: "Floor",
         library: ["Floors","Custom"],
         width: 1,
         height: 1,
         zIndex: 1,
         rotatable: false,
         description: "A floor tile.",
         tileImageURL: "worldbuilder_custom_floor_tile.png",
         iconImageURL: "worldbuilder_custom_floor_icon.png",
         modelURL: "models/worldbuilder/custom/worldbuilder_custom_floor.j3s.gz",
         cellSetupType: "org.jdesktop.lg3d.wonderland.darkstar.server.setup.BasicCellGLOSetup{org.jdesktop.lg3d.wonderland.darkstar.common.setup.ModelCellSetup}", 
         cellType: "org.jdesktop.lg3d.wonderland.darkstar.server.cell.SimpleTerrainCellGLO"
  4. Go to the World Builder (http://localhost:8080/WonderlandWorldBuilder/), enter http://localhost:8080/custom/catalog.json in the "Load Catalog" text field, and press the "Enter" key to load your custom catalog.

TO DO:

Using a Custom World Builder WFS Path

----- Revision r15 - 06 Aug 2008 - 16:06:15 - Main.sdanic