How to export .bullet files from Blender | xissburg

July 16, 2017

How to export .bullet files from Blender

To export .bullet files from Blender you have to use the Blender Game Engine. First you have to setup the physical properties of each object, then create a little Python script which is invoked by a keyboard action you create in the Logic Editor. Then you run the game engine and press that key to run the script which exports the file. Let’s go over this process step by step.

After creating your objects move over to the Properties Editor, Physics tab. Make sure you select Blender Game as the renderer or the Physics tab won’t be visible.

Physics Tab

Usually you want to set the Physics Type to either Static or Rigid Body. If it’s a rigid body then you should also set the Mass. Then you should check the Collision Bounds box and select the type of collision shape you want. If you select either one of Capsule, Box, Cylinder, Cone and Sphere, you might notice the shape does not align with your object. That’s because the center of the shape is set to the center of the object in Blender, then to fix it you should change the origin of your object so the physics shape will fit the way you want. Also note that Triangle Mesh is only valid for static objects (it outputs a btScaledBvhTriangleMeshShape).

Once your objects have their physical properties set, you’re ready to export. Then open the Text Editor…

Text Editor location

…and select New to create a new script and give it a name like exportBullet. Then paste this piece of python in it:

import PhysicsConstraints

Replace the string parameter with the full path where you want to export.


Now select any of your objects and open the Logic Editor. Here we’re going to add a keyboard sensor which will invoke the script we just created with the press of a key. In the Logic Editor click on Add Sensor and select Keyboard.

Logic Editor Keyboard sensor

Then click on Key and press P (you’ll understand why later). On the right, click on Add Controller and select Python. On Script select exportBullet which is the script we created earlier. To make the keypress invoke the script you have to connect the output of the keyboard sensor to the input of the python controller. You do so by dragging from the pin on the top right of the keyboard sensor to the pin on the top left of the controller.

Sensor connected to Controller

Since the coordinate system in Blender is different of Bullet’s, you have to rotate the object -90 degrees along the X axis to export in the correct orientation. You can do it quickly pressing R X -90 enter before exporting.

To execute the script we have to run the Blender Game Engine and press the key. To do that you can press P (the dynamic objects will start falling down because of gravity) and then press P again to run the script and export the .bullet file (make sure you’re in Object Mode). Press esc to stop the game engine. Now the file should be in the location you passed to exportBulletFile. You can import it to a btDynamicsWorld using btBulletWorldImporter.

Always remember to use realistic metric units for the scale of your objects, unless you really know what you’re doing.

Compound Shapes

To export compound shapes you have to select one object as the parent and add the other shapes of the compound as children and check Compound for all objects. For this bowling pin for example, you might want to have a more precise representation for its shape. Since it has a concave shape and collision detection between concave shapes is generally too complicated (it is supported in Bullet using Gimpact but it’s not that great/stable) it’s better to approximate concave shapes as a compound of convex shapes (a.k.a. convex decomposition). In this case it seems a good idea to simply split it in a lower and upper part and use their convex hull as the collision shape. Then, in Edit Mode, select an edge loop in the middle and split.

Edge split

Then select the top part (place cursor over it and press L or select one of its vertices/edges/faces and press ctrl L) and then separate it from the current object pressing P. In Object Mode select the top part first and then the bottom part and press ctrl P to make the top a child of the bottom. Check Compound for both objects, or more generally, check it for the parent and all children.

Compound shape

Note that the mass of the parent is used as the mass of the compound object.

The center of mass of the compound will be the geometric center of the parent object so this effectively shifts the center of mass to the bottom, which is something you’d want in a bowling pin. If you want to shift the center of mass even further down, you can create a small box and place inside of it close to the bottom and use this box as the parent instead.

For compound shapes you only have to rotate the parent object before exporting to fix the orientation since the children transforms are derived from the parent.