Example of a mushroom with two cylinders in a compound physics shape.

Here’s a little Blender script I wrote to export Bullet-compatible compound physics collision shapes to a YAML text file. I’ve released it as open-source on Google Code:

Export Physics Shapes Addon For Blender

YAML is a great file format I’ve been using a lot lately. YAML parsers support JSON and the format is more compact and more readable than XML, but adds some great features like type-tags and a simple comment format. I highly recommend it.

Application Usage

If you are using Bullet Physics, your application must create a parent btCompoundShape and then parse the exported YAML file to create the child shapes. The exporter supports the following shapes: Box, Sphere, Cylinder, Cone, Capsule, and ConvexHull

Note that even though the exported shapes are siblings of one another, by default the btCompoundShape class will create an automatic AABB tree so that it won’t be testing against every shape on collision with your object.

Your application should construct a btTransform from the properties originscale and rotate. The rotate property provides a quaternion sequence in WXYZ order and is compatible with btTransform::setRotation().

yaml-cpp (new API) is recommended for parsing YAML files in C++.

Blender Installation

This script has only been tested with Blender 2.63, but it may work with earlier versions as well. In Blender User Preferences > Addons tab, click the [Install Addon...] button and select the export_physics.py script file. Alternatively, copy the export_physics.py script file to your blender addons folder and enable it in User Preferences > Addons. See blender documentation for more information.

Blender Usage

To create a compound physics shape for a mesh in blender:

  1. Place the 3D cursor at the origin of the mesh object.
  2. Add > Empty, name it “physics”
  3. Create a physics shape with Add > Mesh > Cube, UV Sphere, Cylinder, Cone or create an arbitrary mesh for a ConvexHull shape.
  4. Parent the new shape to the “physics” Empty.
  5. The mesh name must start with: Box, Sphere, Cylinder, Cone, Capsule, or ConvexHull, depending on the shape you want.
  6. Position and scale the shape object, but do not modify the internal vertices, unless it is a ConvexHull type.
  7. Repeat steps 3-6 until your compound shape is complete. Shapes can only be a 1-level deep hierarchy.
  8. Important: Select the parent empty object named “physics”
  9. Click File > Export > Physics Shapes (.yaml)

Exporter Options

  • Append To Existing File –> Appends the Physics shapes to an existing YAML file
  • Convert To Y-Up –> Converts the values to a Y-Axis Up coordinate system
  • Root Name –> The top-level name (in the YAML file) that will contain the physics shapes

Example YAML output

This physics shape output was appended from 2 separate meshes: tree and stalagmite

  - shape: Cylinder
    origin: [-0.0272567,0.630798,0.0155753]
    half-extents: [0.123097,0.64184,0.123097]
  - shape: Sphere
    origin: [0.0406867,1.64268,-0.0203434]
    radius: 0.4183913767337799
  - shape: Cone
    origin: [0.0335,1.0,0]
    radius: 0.35
    height: 1.0