Bounce Lite is a light-weight 3D physics engine for games.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Src
Testbed
README.md

README.md

Abstract

Bounce Lite is a lightweight 3D physics engine.

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