Blender and SIO2

This section tries to explain how to use Blender with the SIO2 SDK.
It is not a blender tutorial, but you might find some links in Recommended Reading for that.

SIO2 Exporter

Exporting a Scene - Basics

Unless you are completely familiar with what properties are saved when using the SIO2 exporter's "update" function, you should completely erase your .sio2 file and export a new one from scratch each time you make a change. This way you can be sure that you know your current .sio2 file is completely up to date with your blender project.

If something isn't working, erase the .sio2 and its unzipped folder and export the scene again. Consider erasing the .sio2 and re-exporting to be the unwritten first step in each troubleshooting scenario.


Ensure that the script version matches the SIO2 SDK version.

Ensure that all objects to be exported are selected.

Ensure that all objects to be exported are in layer 1.


If surfaces are not rendering properly, it's possible that it the material (and texture if applied) is on the opposite face to the one you think. You can check this by entering EDIT mode (F9) in blender, while the object or face is selected. Under “Mesh Tools More” button panel, select “Draw Normals”. The normals will then appear as a small perpindicular blue line. Rotate the drawing around to get a clear view of which way the normal is pointing. If it's the wrong way, hit “Flip Normal” under the “mesh tools” button panel.

NOTE: these panels may not be visible, if not, try panning the button panels.

Convert Quads to Triangles

Objects will not render unless quads (square faces) have been converted to triangles, so one square face becomes two triangles in place of the square.

To do this, select the object, enter edit mode, hit CTRL-T. The triangles will be visible in the mesh.


Getting objects from blender to the simulator is pretty straightforward. They generally appear in the simulator in the same way they look in Blender.

The pivot point of an object is showed in blender by the location of the movement arrows when the object is selected. Hitting "center new" (as discussed in the video tutorial) makes sure the pivot point is centered in the object. It can become skewed when changing the object in edit mode.

You also might not want the pivot point to be at the objects center.

Object duplicates

The way SIO2 handles duplicate objects can be confusing. Any object with ".001" or something similar as a suffix in it's name will be treated as a "duplicate" of the object with the same (suffix-less) name. If you want the object to be different, you have to change the name to something without the ".001." If you want it to be treated as a duplicate, make sure you call sio2ResourceBindAllInstances( sio2->_SIO2resource ); during the binding process, as explained later.

Troubleshooting: Objects don't appear correctly in simulator/device

1. Are all the faces triangles? Go into edit mode, select all the faces, and hit "ctrl t" to convert the faces to triangles

2. Does the object name have a suffix like ".001" ? If so, try changing the name and re-exporting

3. Try deleting the object's material and adding a new one with the default properties

4. Have you been messing with vertex groups? Delete all the vertex groups and re-export.


1.6 Textures

When I was getting started I had a ton of trouble getting textures to appear. Even after watching the video tutorial I was having no luck. Here is a way to ensure that what you are seeing in Blender is what you will see in the simulator/device:

The image that is exported to the .sio2 is the image that you have assigned in the object's texture slot in the Blender texture panel. However, the positioning and scaling of the image must be set separately. Select an object in object mode, press TAB, and go into edit mode. With the desired faces selected, press "u" and then choose "unwrap," "project from view," or whichever is your desired means of unwrapping. In the UV editor window, you can tweak your unwrapping and apply a UV image, BUT note that the image chosen here is separate from the one that is exported to the .sio2 (as mentioned before). This UV image is merely the one that is shown on the object in blender. If this image is the same as the one you have attached to the object's texture slot, then when you choose the "textured" shading/viewing mode in blender the object should appear exactly as it will in the simulator, provided that you follow SIO2's image format guidelines.

Troubleshooting: Textures don't appear correctly in simulator/device

1. Make sure the object has the desired appearance when you view it in blender's "textured" view mode

2. Go into the unzipped sio2 folder and check whether the image has been exported

3. Make sure the image follows SIO2's image format guidelines (DIMENSIONS MUST BE MULTIPLE OF 2, less that 1024 x 1024, etc)

4. It is possible to do all the steps correctly, but in object mode rather than edit mode - this will cause the textures to render correctly in blender but not in the engine - so always make sure you are in edit mode when applying textures to an object

Transparent Textures

In blender, in the "map to" tab under the "materials" panel, make sure the "alpha" button is selected. Change the blend mode from the default "mix" to "value." In the "shaders" tab also under "materials" panel, set the "Tralu" slider to something other than 0.00. The video talks more about this slider.


If objects are falling through each other, there are a couple things to check.

1. Have you set the objects as actors? This is an obvious one, but sometimes the most obvious points are the easiest to forget

2. Hit "ctrl a" with the object selected and choose "Scale and Rotation to obData." When you transform an object in blender, it changes it's x, y, and z "Scale" from 1.000 to a new value. "ctrl a" will set the scale back to 1.000. Sometimes having this scale at a value other than 1.000 when you export can cause physics issues.s

3. Are the objects extremely small? This can cause inaccuracies in the collision detection. Try scaling them up, but don't forget to do "ctrl a" after youre done.

4. Are all the faces triangles? Go into edit mode, select all the faces, and choose "convert to triangles."

5. Try clicking "center new." Sometimes you can run into physics problems with uncentered objects.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License