bounce_lite: A C++ repository from MateusGPe

Abstract

Bounce Lite is a lightweight 3D physics engine for games.

Features

Rigid body simulation with contact and friction
Mouse joint, spherical joint, and revolute joint with angle limits
Sensor shapes/Ghost objects/Phantoms support
Collision events dispatching via contact listener, ray-cast listener, or AABB-cast listener
Box stacking
Simulation islands and body sleeping
Semi-Implicit Euler's method for solving systems of ordinary differential equations
Sequential Impulses technique for solving velocity constraints
Baumgarte method for position constraint stabilization
Broad-Phase Collision Detection implemented by a Dynamic AABB Tree
Narrow-Phase Collision Detection implemented by the Separating Axis Test (SAT) and the Gauss-map Optimization
Half-edge centric convex hulls
Built-in math library and memory allocation using stack and block allocators

Examples

Setting up and Stepping a World

// Create a b3World object.
b3World m_world;
// Create a b3TimeStep object to define the configuration of a single
simulation step.
b3TimeStep m_step;
// Setup the simulation frequency (here 60 Hz).
m_step.dt = 1.0 / 60.0f;
// Setup the number of LCP Solver iterations.
m_step.velocityIterations = 10;
// Optionally allow rigid bodies to sleep under unconsiderable motion.
// This increases the performance of the application substantially.
m_step.allowSleeping = true;
// Call the function below to simulate a single physics step.
m_world.Step( m_step );

Creating a Rigid Body and Attaching a Convex Polyhedron to It

To setup a convex hull as a box, call the b3Hull::SetAsBox(b3Vec3) function passing the scale of the box as the argument, as exemplified below.

b3Hull hull;
hull.SetAsBox( b3Vec3(1.0f, 1.0f, 1.0f) );
b3Polyhedron polyhedron;
polyhedron.SetHull( hull );

Bounce Lite assume MKS (meters, kilometers, and seconds) as units. In the code above the box dimensions are 1 m^3 (cubic meters).

To setup a general convex hull given its faces and vertices, you must define a valid declaration for the faces and fed it into the b3HullDef structure when creating the shape. More specifically, an array of b3Face objects and the unique vertices of the hull should be passed to the structure. A b3Face object is simply a list of vertex indices. The vertices of a face must be ordered CW. Right after that, call the function b3Hull::SetFromFaces(b3HullDef). Example:

b3Vec3 vertices[N];
b3Face faces[2];

faces[0].vertexCount = 4;
faces[0] = i1;
faces[1] = i2;
faces[2] = i3;
faces[3] = i4;

faces[0].vertexCount = n;
faces[0] = i7;
faces[1] = ix;
faces[2] = iy;
faces[3] = iz;
...

b3HullDef hullDef;
hullDef.vertexCount = n;
hullDef.vertices = vertices;
hullDef.faceCount = 2;
hullDef.faces = faces;

b3Hull hull;
hull.SetFromFaces( hullDef );

b3Polyhedron polyhedron;
polyhedron.SetHull( hull );

Once a polyhedron shape is created, we can create a rigid body or use an existing one and attach the polyhedron to it.

b3BodyDef bodyDef;
// Set the rest of the body definition attributes here.
b3Body* m_body = m_scene.CreateBody( &bodyDef );

// Create a shape and attach to the body.
b3ShapeDef shapeDef;
shapeDef.shape = &polyhedron;
// Set the rest of the shape definition attributes here.

b3Shape* shape = m_body->CreateShape( &shapeDef );

To destroy a shape the following code must be called:

m_body->DestroyShape( shape );

For more detailed information please see the code comments at b3Polyhedron.cpp, b3Hull.cpp, b3World.h, and b3World.cpp.

Future Work

Contact Point Reduction
Support for spheres, capsules, and triangle meshes as well as mesh contacts
Keep the Dynamic AABB-Tree balanced
Continuous Collision Detection
Implement QuickHull in a separate module from the collision's (maybe in the tools side of the engine)

Acknowledgments

Thanks to Erin Catto for sharing the very excelent GDC slides from the physics talks at Box2D's website (http://box2d.org/downloads/) and for Box2D
Special thanks to Dirk Gregorius for helping me to efficiently implement the SAT algorithm on this old thread: http://www.gamedev.net/topic/667499-3d-sat-problem/ and for sharing the ideas behind Rubikon's physics engine and collision detection module in the forums

Testbed

The button description to control Bounce Testbed are:

Camera Controls (as in Maya):

Rotate the camera holding ALT + LMB
Translate the camera holding ALT + RMB
Zoom in/out the camera using ALT + Mouse Wheel

Scene Controls:

SPACEBAR to replay the scene
RMB to throw an object into the scene
ESC to exit the application

Before running Bounce Lite's Testbed please make sure that you have the Visual C++ 2015 Redistributable Packages installed on your machine. If you don't have them installed then they can be downloaded at https://www.microsoft.com/en-us/download/details.aspx?id=48145.

Credits

Bounce Lite is released and will be kept under the zlib license.

Irlan Robson https://irlans.wordpress.com

MateusGPe/bounce_lite