Import Content from Blender into Project Wonderland
Blender is an open-source 3D modeling tool. It can export many formats, some of which can be imported into Project Wonderland. Here are some initial instructions on how to import content generated in Blender into a Wonderland world.
Getting art assets into Project Wonderland is a 3 step process
Create the model in Blender and export as x3d
Use the Import tool in the wonderland client to load the x3d model and position it within the world
Deploy the new art work to your wonderland server
Exporting your model from Blender
If you don't already have Blender installed you can download it from here Blender
Download and install the Blender X3D? Exporter from here: http://www.bitbucket.ca/~acheater/blender/ -- (also included here: AdrianCheaterX3DExporter under the GPL) while the default X3D? exporter included with Blender will work, it does not export normal information, so all your textured models (i.e. models for which color information is determined by a bitmap image file) will render completely flat and unshaded (which you may prefer for aesthetic reasons).
The next step is to use Blender to create your model. In this case, we'll keep things simple by just using a cube. If you're using the default startup scene in blender, then you'll be ready to go -- otherwise, simply add a cube to your scene.
A simple cube in Blender
If you're using the default startup scene, you should have a cube with a material already applied to it (named "Material").
So now that we have a 3d model, we need to color it by using a 2d texture. I'm going to assume that you already understand how to layout UVs and save out a reference image of the UV layout -- there are a number of resources available that explain how to do this -- but for a cube with the same texture on each side the uv layout is pretty much done for you. I personally like to arrange my Blender windows such that I have the UV Editor in one window and the 3d view in another:
Laying out UVs
For my texture I downloaded a nice photo of plywood from http://www.cgtextures.com/ -- this one is 800x595 pixels:
Photo of plywood
The first thing we need to do is optimize the image for Wonderland. Optimizing images is an important part of enabling the world to render quickly and with a good framerate. When optimizing, the following things need to be taken into consideration:
Image size: the image only needs to be as large as it will be displayed on-screen. For example, let's say you are creating a texture for a sign that appears over a doorway. If the sign is placed such that it will never take up more than 300 pixels wide on-screen, then the image doesn't need to be any larger than 300 pixels wide.
Power of two:Because of the way rendering engines work, images whose dimensions are in powers of two (e.g. 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, etc.) generally require less processing and therefore can speed up rendering, so resize your images accordingly.
Square: Blender assumes all texture images are square, so to make things easier make sure your images are cropped or scaled to be square.
File size: smaller files require less memory and load faster, so it's a good idea to make your files as small as possible while maintaining a reasonable level of quality. At this point it's a good time to consider what file format to use. I recommend JPG or PNG, depending on what you want to do with your image. JPG offers a high-level of compression at the expense of quality. PNG offers some compression while maintaining image quality, and can support transparency.
Our plywood image is quite large, rectangular, and its dimensions are not in powers of two, so let's fix that:
Optimized texture
Now the image is a reasonable 256x256 and ready to be used as a texture. Note that I saved it as a PNG file -- it was originally a JPG, and while resaving it as a JPG could significantly decrease the filesize, it would also introduce some additional noise into the image and wash out the colors somewhat. To preserve the quality of the image I resaved it as a PNG which provides some compression but is (in this case) lossless.
Now we are ready to import the image into Blender.
Begin by going into the Shading panel:
Now bring up the Texture buttons:
Change the texture type to "Image":
Click the "Load" button and select the image to import:
Now that the image is loaded into Blender, we can load it into the UV Editor to get it to display on the model:
And behold, a plywood box:
Once you have your model and texture ready, there's one more thing to do before exporting. Since Blender uses a Z-up coordinate system and Wonderland is Y-up, rotate the entire model -90 degrees X to have it face in the right direction. Now export to X3D? using the exporter you installed (see above). Be sure to pick the one labeled "X3D" in the menu (the other is the default Blender exporter that doesn't export normals):
Save the file as "cube.x3d". Please note that the x3d file assumes the image is in the same directory, so copy the image file to the x3d file's directory (if necessary) before trying to import the x3d into Wonderland.
Importing your model into Project Wonderland
Start the wonderland client and log into a server. Then from the menus select Tools->Import Model, this will open the Import Manager dialog.
Import Manager dialog
Click on the 'Load Model' button to import your first model. This will open the Model Import dialog and a file chooser dialog. Select your desired X3D? file and press OK in the file chooser.
Model Import dialog
Once the model is loaded it will be automatically positioned in front of the avatar, and by default will stay positioned in front of the avatar so it can be pushed around the world.
If your model is small you may need to change the camera mode of the avatar (press C) to first person, if it's a large model (like a room) the avatar will be within the model. Remember the model
is moving with the avatar so for large rooms you may appear stuck because every time you move the room moves with you. To prevent the model moving with the avatar by deselectiing the 'Move with Avatar' checkbox.
Check your model appears as you expect. If the textures are missing ensure you performed the UV mapping step in blender and that the material colour is not black (white is a good default).
Position your model in the world either by moving it with the avatar or adjust the center coordinates manually in the dialog box by changing the Location and Rotation values. Once satisfied press OK which will return you the Import Manager dialog. You can import more models and edit the location of models already imported in this session (note once deployed models can no longer be editing using this tool).
Once you have all your models imported and positioned to your satisfaction the next step is to Deploy the model to the server
Deploying your Models
There are two choices for deploying your models to the server
Use the Deploy to server option to automatically deploy the art and wfs files to the server
Save to local system to save the art files to the local directory, you will then need to create your own wfs files and and copy everything to the server yourself.
Option (1) is by far the easiest, but it requires that your server was setup with art upload enabled, see Web Admin Deployment for details. If the 'Deploy to server' button is enabled then your server supports this option, pressing this button will copy all the art to the server, create the wfs files and cause the world to be reloaded. At this point everyone in the world will see the new art you have created.
If deploy to server is not available then you will need to the save the model to the local file system. Clicking on the 'Save to local system...' button will display a dialog which allows you to select the directory into which you want the art files written. By default the export will create 2 directories, one containing the 3d models and another containing the textures. After completing this step you will need to create the wfs file for the models and copy all the files into locations used by the server, the details are covered in the next section of this tutorial.
Manually Deploying your Models
This part of the tutorial assumes you have the Wonderland source code installed and are running both the client and server on the same machine. To get the source code and default art content follow these steps
Check out the source for Project Wonderland ad Wonderland artwork into a common directory. I used the following commands:
$ mkdir wl-blender
$ cd wl-blender/
$ cvs -d :pserver:username@cvs.dev.java.net:/cvs co lg3d-wonderland lg3d-wonderland-art
Where username is my java.net login.
Once everything is checked out, you'll need to configure Wonderland to use local artwork. You can do this by creating the file lg3d-wonderland/my.build.properties. Add the lines:
wonderland.useLocalArt=true
To the file. The useLocalArt property tells the Wonderland client to load artwork locally, by default from the ../lg3d-wonderland-art directory.
Next you did to copy the model and texture files to the correct location. You can either select the lg3d-wonderland-art/compiled_models directory as the location into which to save the models from the Import tool. If you choose a different directory to save the files then you need to copy the contents of the models and textures directory to lg3d-wonderland-art/compiled_models/models and lg3d-wonderland-art/compiled_models/textures respectively.
The next step is to configure Wonderland to use an empty world. Using an empty world will mean that we see just the models we are adding, and not all the default models that come with Wonderland. Once you know your models are working properly, you can integrate them into the entire world. To accomplish this, we are going to create a new Wonderland File System and tell our client to use it instead of the default world (for more information about the Wonderland File System, see http://wiki.java.net/bin/view/Javadesktop/ProjectWonderlandWFS).
$ cd lg3d-wonderland/src/worlds/
In this directory you will see a number of other directories ending in "-wfs"; each one represents a "world" in Wonderland File System format. Create a new directory here for your world using the same naming convention, e.g. "test-wfs" -- the "-wfs" is important! All Wonderland File System world directories end in "-wfs".
Now add the following line to the "my.build.properties" file you created earlier:
substituting BASEPATH with the path to where your lg3d-wonderland directory resides, and YOURWORLD for the name of your world directory (e.g. "test-wfs").
We can now load up Wonderland with our new, empty world. Open two terminals and "cd" to the lg3d-wonderland directory in each. In one terminal run:
$ ant run-sgs
And in the other run:
$ ant run
You should see something like figure 1, a very empty world.
Figure 1. A minimal world
To manually add the model you just created to your world, you need to create a file in the "-wfs" directory your server is using; this file essentially describes the content of the world.
Copy the text below into a new xml file whose name ends with "-wlc" (e.g. "test-wlc.xml"):
This is the basic setup code for a new section of the world, describing its origin in 3d space and what type of Cell(s) we're working with. This code can vary somewhat, depending on the configuration of the world and the desired Cell-type(s), but for our purposes the provided code should suffice. Notice the last line of this snippet indicates we're starting an array -- this array will be populated with objects, each of which describes an object in the world.
Here we're describing an object, its Cell-type, and (since this Cell-type loads in a model) which model file will be loaded, in this case "models/cube.j3s.gz" (the file created earlier in the tutorial). We're also providing some optional information about the object's location (in 3d coordinates x, y, z) and rotation (in degrees about the axes x, y, z, and in radians). The "instanced" boolean is useful if the model you are loading will be used more than once, for example if you want a number of chairs in your world and you want them all to use the same model file, it makes sense to simply reuse the model file already loaded into the world; this boolean flag enables exactly this feature.
For now, we're only going to place a single object in the world, but if we wanted to add more objects to the world, we'd simply repeat the code above for each object, making adjustments to location and/or rotation accordingly. Then we close up the array and the rest of the file with the remaining xml code.
Now start Wonderland again with two windows, one which runs:
$ ant run-sgs
And one which runs:
$ ant run
If all goes well, you should see your model load at the same location as your avatar If you back up a little way, the world should look something like this:
Plywood box model in world
Deploying to a local wonderland server
Check out the source for Project Wonderland and Wonderland artwork into a common directory. I used the following commands:
$ mkdir wl-blender
$ cd wl-blender/
$ cvs -d :pserver:username@cvs.dev.java.net:/cvs co lg3d-wonderland lg3d-wonderland-art
Where username is my java.net login.
Once everything is checked out, you'll need to configure Wonderland to use local artwork. You can do this by creating the file lg3d-wonderland/my.build.properties. Add the lines:
wonderland.useLocalArt=true
To the file. The useLocalArt property tells the Wonderland client to load artwork locally, by default from the ../lg3d-wonderland-art directory.
The next step is to configure Wonderland to use an empty world. Using an empty world will mean that we see just the models we are adding, and not all the default models that come with Wonderland. Once you know your models are working properly, you can integrate them into the entire world. To accomplish this, we are going to create a new Wonderland File System and tell our client to use it instead of the default world (for more information about the Wonderland File System, see http://wiki.java.net/bin/view/Javadesktop/ProjectWonderlandWFS).
$ cd lg3d-wonderland/src/worlds/
In this directory you will see a number of other directories ending in "-wfs"; each one represents a "world" in Wonderland File System format. Create a new directory here for your world using the same naming convention, e.g. "test-wfs" -- the "-wfs" is important! All Wonderland File System world directories end in "-wfs".
Now add the following line to the "my.build.properties" file you created earlier:
substituting BASEPATH with the path to where your lg3d-wonderland directory resides, and YOURWORLD for the name of your world directory (e.g. "test-wfs").
We can now load up Wonderland with our new, empty world. Open two terminals and "cd" to the lg3d-wonderland directory in each. In one terminal run:
$ ant run-sgs
And in the other run:
$ ant run
You should see something like figure 1, a very empty world.
Figure 1. A minimal world
Congratulations! You've imported a model into Wonderland!
One final note. Since Wonderland caches models, if you update your model in Blender, you will need to re-export it and then run:
$ ant clean-cache
To ensure that a new model is downloaded.
Advanced Import options
The Advanced tab in the import dialog allows you to review the textures that are part of the model and to change the name of the directory in which the textures will be deployed. You can also review the auto computed bounds of the model.
