Blender Exporter Documentation

Before you begin
In order to use the blender exporter, you must have both Blender 2.49 and Python 2.6 installed on your computer.  These can be found at the following places:
Blender: http://www.blender.org/download/get-blender/  (you should download the current stable release.  The exporter has been tested using version 2.49b)
Python: http://www.python.org/download/ (use the current version in the 2.6.x series to avoid any potential compatibility concerns)

Once you have both of these pieces of software installed on your computer, you may now download the Wild Pockets Blender exporter script and copy it into your blender scripts directory. Depending on your install of Blender, this may be located in one of a few places:
Windows XP: C:\Program Files\Blender Foundation\Blender\.blender\scripts

Windows XP (alt): C:\Documents and Settings\<USERNAME>\Application Data\Blender Foundation\Blender\.blender\scripts
Windows Vista & 7: C:\Users\<USERNAME>\AppData\Roaming\Blender Foundation\Blender\.blender\scripts

Also, keep in mind that some of those folders might be hidden, so turn on hidden folders in your folder options if you don't see a directory

If one of these directories exists, copy the WildPocketsBlenderExporter.py file into that directory.  Now, when you start Blender, you should be able to go to "file->export->Wild Pockets..." to start the exporter and see something like this:


This means that you have successfully installed all of the necessary items to use the Wild Pockets Blender exporter.


Notes for Beginners
If you are new to Blender, you might notice that bringing up the exporter takes up your scene view.  If you want to be able to work in your scene while using the exporter, it is a good idea to put it in its own panel.  To do this, right click on the right or left side of the 3D view panel(your main viewing space), then click "split area", and hit the tab key so that a vertical line will show where you will be creating a new panel.  Once you click again, a new 3D view space will show up next to the 3D space you were already working in.

Now you will wan to make it so that this new panel displays the exporter.  To do this, click on the icon that should be on the left side of the panel's header(which should be at the top or bottom of your new panel) and then changing the view to "scripts window".  Then from the toolbar of that panel you can go to "Scripts->export->Wild Pockets...".  Any panel in blender can be changed to any other panel using this method, so you can use any open panel to open up the exporter, not just new ones.



Using the Exporter
The Basics:
The basic function of the exporter is simply to take whatever you have in your scene, convert it to a wild pockets compatible format, and upload it to your account where you can access it using the Wild Pockets Builder.  To export anything, you need to have three fields filled out in the exporter: Model Name, Username, Password.  Once you enter those three, you can hit "export scene" or "export animation" to complete an export.  Once the export is finished, the Blender console will read if it was a success or not.
If you only want to export part of your scene, you can activate the "Only Selected" toggle and the exporter will only upload objects you have selected in the scene.  This includes collision meshes as well, so make sure if you want your collision volumes to export that you have them selected before starting the upload.

Animation:
In order to export an animation you need to first set up your animations in the blender timeline and choose to either export the entire animation or just selected frames of animation using the toggle box in the exporter.  If you have multiple animations for your object, you can set them all at different times and export each one separately by restricting the frames to export.  When you have set the frames you want to export, click on the Export Animation button, and check the console to see if the export was successful.
The "only selected" button works for animations as well.  The way that it works is that only animations for skeletons attached to selected meshes will be exported.  That means any object you select that has an armature will have its animation data exported.

Collision:
Wild Pockets uses a physics system that can detect boxes and spheres for collision.  In order to take advantage of this collision, you must add in the boxes and spheres yourself.  The exporter has two buttons; "Add Collision Sphere" and "Add Collision Box" to help you set up the collision for your object.  When you click on one of those buttons, the proper object will appear in your scene and you just need to line it up with your object the way you want.  When you use a box or sphere for collision, you have to maintain their basic shapes.  A sphere must remain uniform in its radius(can't be an elliptical spheroid), otherwise the exporter will try to figure out a radius that might not be consistent with what you want.  The box on the other hand, can be stretched in any direction, but still must be a box with no angled faces(all angles must remain at 90 degrees).
The other two pieces of physics information you can set are the mass and center of mass properties.  If you don't create a center of mass and select it to be used for the export, Wild Pockets will determine the center of mass of your object based on the orientation of your collision objects.  Creating a center of mass just creates a set of axes that you can move around and place where you want the center of mass on your object to be.  In order to use that point, you need to click the "Use COM" button.  Along with this, you can change the mass of your object with the mass slider, though you can still change the mass in the Wild Pockets builder when using your object.

Extra Features:
When you export your object, you can include extra pieces of information to help your work flow when working with the object in the builder.  You can set keywords for either the object or the animation you are exporting.  These keywords will be stored by the object library and will cause your object to show up when doing a search with them in the library search bar.  When entering keywords, you can separate multiple keywords with commas. 
Two other items you can set are "script containing class" and "default class name" which allow you to specify the script this object will use and the name of the class the object will belong to respectively.  This is useful for exporting objects that will frequently be used by the same classes and scripts so that you don't have to always set it up in the builder.

Preview:
If you click on the "Web Preview" toggle box, the exporter will automatically direct you to a web page with a Wild Pockets preview of your model after you do a model export.  This allows you to immediately see what your model is going to look like without having to open up the builder and finding the file.

Going Through The Export Process:
When you initiate an upload, the exporter will turn everything you are exporting into a compatible format, then it will upload that information to the Wild Pockets servers.  This process will make that instance of blender unusable for the duration of the export.  There is a status bar underneath the "anim name" dialog box letting you know if the exporter is currently running an export or not.  Once the export is finished, it will read either "animation export finished" or "model export finished" and a popup box should appear letting you know if the export was successful or not.  At this point, you can continue working in that instance of blender.  If you missed the popup dialog, you can check the blender console to see if the upload was a success or not.


Other Items
Thumbnail:
Once a model upload is finished, the exporter attempts to create a thumbnail image of your model to assist with viewing it in the Wild Pockets library.  If you don't want a thumbnail, just delete the camera from your scene.  Otherwise, it would be a good idea to remember to move your camera around so that it has a good view of the model.  It will also be a good idea to set up some basic lighting.  It is also good to note that the final thumbnail will be a 90x90 image, so make whatever you want to convey with the thumbnail is done so with a small image.  The FOV will not be changed from whatever you have it set to as well.

For Beginners
Texturing:
There are two methods of texturing that the exporter will recognize.  The first is loading an image directly onto the model using the UV/Image editor.  For applying a basic texture using this method, select your model, go into edit mode, hit the 'u' key, then select unwrap.  This will create UV coordinates for your mesh.  Then you can go into the UV/Image editor with the model selected, then go to "image->open" and select the image you want.  Please note that Wild Pockets only accepts PNG and JPEG images.  Any other type of image will produce an error.  To make the image show up on your mesh, go to the mesh's material settings and select "TexFace".  Now if you do a render, you will see that your mesh has the image applied to it.

The other method of applying textures is by using materials.  Using this method, you can apply basic textures as well as normal maps.  While materials in blender are very powerful and wide ranging, Wild Pockets only supports use of texture maps and normal maps, so if you apply material colors, translucency, effects, etc. they will not be exported.  To start with a material texture, you need to unwrap your mesh like in the previous method.  Once you do that, go to the material button for your mesh, and if it did not come with one, add a material by clicking the "add new" button.  At this point you can click on the texture button that is on the header bar next to the material button.  From there you can add a new texture if there is not already a default one, then change the type to "image".  Now there should be an image box where you can load your image.  If you go back to the material buttons, you can see the texture you created on the right side of the panel.  Click over to the "map input" tab and change the texturing to "UV".  Now, if you placed a basic texture, you should set in the "mat to" tab, "col".  This is the default, but what it basically means is that the object will receive the color of your texture(each pixel will show as it is supposed to).  Now, if you applied a normal map, you'll want to deselect col and select "Nor".  Now, you should have an object that has the texture you have applied.  If you want a flat texture and a normal texture on one mesh, you can just add another texture to the material.  But make sure you only have one texture and one normal map.  If you try to add more than one texture or normal map to a mesh, the export will error.

Rigging:
Blender supports several ways of rigging meshes with skeletons, including skin weight painting and bone envelopes.  Wild Pockets currently only supports use of skin weight painting.  This involves creating a skeleton, which is called an "Armature" in blender, and painting the weights each bone in the armature has to the vertices in your model.  A helpful tutorial for beginning rigging can be found here: http://wiki.blender.org/index.php/Doc:Tutorials/Animation/BSoD/Character...
If you attempt to export a model that uses a technique not recognized by blender, your model will not be animatable in Wild Pockets.