Collidable Model

Since I published my Bounce demo in April 2008, I have received quite a number of emails with questions and problems concerning the collision detection code. Many people had trouble with the matlab bindings, others ran into problems with the conversion of models to .obj format,…

So I decided recently to take the collision detection system one step further, and integrate it completely into the XNA framework. On this page you can find an XNA content processor, that will compute collision data directly during the model build stage. The processor comes along with a set of runtime classes that perform direct sphere-mesh collision detection.

Features and Limitations

Collidable model can process any static model that can be processed with the XNA content pipeline and add collision data to it. In the runtime, you can then use the collision data to efficiently determine the triangles of the model that intersect a given sphere.

However, the collision detection is restricted to static models only like environments, terrain and static (non-moving) objects. You can make it work with objects that move as one entity by transforming the sphere into the objects coordinate system, but you can’t use it on objects that have independently moving parts, e.g. skinned models etc.

Adding the processor to your project

Download the binary package to your computer and copy the dlls to a location of your choice. The only restriction is that the CollidableModelProcessor.dll and GeometryHelper.dll end up in in the same directory.

Open up your game project and add the CollidableModelProcessor.dll to the list of references of the Content Project. This step will allow you to choose CollidableModel as a processor for models. Next you need to add the runtime components to the Code Project. Select the code project and click Add Reference…. Pick the CollidableModel library appropriate for your target platform, i.e. on Windows pick CollidableModel_Windows.dll and on Xbox 360 choose CollidableModel_Xbox360.dll

collidable_model_addreference collidable_model_processor

Choose the model you want collision data for, and select CollidableModelProcessor as content processor.

collidable_model_processor collidable_model_processor2

The processor supports various parameters:

  • AddVisualizationData: Will create an XNA model to visualize the collision geometry if set to true. This can be very helpful for debugging. Note that the visualization data can add significant overhead.
  • ModelProcessor: The name of the processor used to import the model.
  • NumProcessingThreads: The number of concurrent threads used for processing the collision geometry. Set to 0 or 1 to disable multithreading
  • NumVerticesPerBin: The number of vertices per collision node. The lower the value, the faster collision detection will usually be. Beware of setting this parameter too low though, as processing time increases significantly, and the processor might even stop Visual Studio from responding. If set to 0, the processor will try to find an optimal value.

Using the collidable model class

Once you built a model with the CollidableModelProcessor, you can load it using the ContentManager:

CollidableModel.CollidableModel myModel =
    ContentManager.Load<CollidableModel.CollidableModel>( "model_name" );

Note that all classes are contained in the namespace CollidableModel. You can access the original XNA model with the property model, i.e.

Model = myModel.model;

To access the collision data, use the property collisionData. The returned object is of type BspTree, which provides you with functions like

public void collisions(BoundingSphere b, LinkedList<Face> collidingFaces,
        LinkedList<Vector3> collisionPoints)

public void checkedFaces(BoundingSphere b, LinkedList<Face> result)

that directly return the colliding faces, as well as the exact collision points, respectively the list of faces that were checked for collision. The type Face represents a triangle, where v1, v2 and v3 correspond to the vertices and n1, n2 and n3 correspond to the normals. Note that these values are indices into the geometry buffers, stored in BspTree.geometry. The following code would for example print the vertices of all triangles colliding with the bounding sphere b to the console:

var collidingFaces = new LinkedList();
var collisionPoints = new LinkedList();

myModel.collisionData.collisions( b, collidingFaces, collisionPoints );

foreach( var f in collidingFaces )
    System.Console.WriteLine( "Vertex 1: {0}",
        myModel.collisionData.geometry.vertices[f.v1].ToString() );
    System.Console.WriteLine( "Vertex 2: {0}",
        myModel.collisionData.geometry.vertices[f.v2].ToString() );
    System.Console.WriteLine( "Vertex 3: {0}",
        myModel.collisionData.geometry.vertices[f.v3].ToString() );

Note that I have updated the Bounce demo to use these classes. Have a look at the Bounce source code to see the collision detection in action.

Downloads and Acknowledgements

The CollidableModel processor is available as precompiled libraries (dll), as well as complete source code. The source comes with Visual Studio 2010 project files, which should make compilation easy. Just think of putting the GeometryHelper.dll and the CollidableModelProcessor.dll into the same directory. Note that the code uses the Template Numerical Toolkit library. See the official homepage for more details.