[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ] [ Search: ]

4.14.2 Physics using Bullet

The ‘Bullet’ plugin implements physical simulation for Crystal Space using the Bullet library.

This section will present the main concepts that are used within a physical simulation. A tutorial with example of codes can be found with the application ‘phystut’ (see in ‘CS/apps/tutorial/phystut’).

iDynamics Plugin Interface

The name of the ‘Bullet’ plugin is ‘crystalspace.dynamics.bullet’, and this plugin implements also the iDynamics interface. This interface can be used in order to create the various dynamic systems that will contain the virtual objects of the simulation.

Dynamic Systems

Dynamic systems are independent virtual worlds containing physical objects. The physical objects are active only when they are put inside a dynamic system, and they will interact only with the objects in the same dynamic system. It is not possible to put an object in more than one dynamic system.

At least one dynamic system should therefore be created. Usually, one would need one dynamic system per Crystal Space sector, the problem being to switch the dynamic systems when an object crosses a portal. This is not yet made automatically by the ‘Bullet’ plugin, this is however a feature of the WIP ‘physics2’ plugin.

Each dynamic system has separate parameters such as the gravity force, the visual debug mode, the internal scale, and whether or not soft bodies are allowed within the system.

Dynamic systems are also used to create the bodies, joints and colliders.

The common interface for dynamic systems is iDynamicSystem. However, the ‘Bullet’ plugin also exhibits the interface CS::Physics::Bullet::iDynamicSystem that extends the system with additional functionalities.

Stepping the Physical Simulation

In order to actually perform the physical simulation, you must specify manually to the ‘Bullet’ plugin how much time has elapsed since the previous frame. The method iDynamics::Step() is responsible of that, and takes as a parameter the delta time value in seconds.

The iDynamics::Step() method will update all the dynamic systems that have been created. If you want to control them separately, you can use instead the method iDynamicSystem::Step().

Several other parameters allow to control the stepping and the precision of the simulation. Those parameters are set using the method CS::Physics::Bullet::iDynamicSystem::SetStepParameters().

Rigid Bodies and Colliders

Rigid bodies are bodies whose shape do not vary over the time. They are the physical objects that are the most used because their motion is the less costly to compute.

The shape of the rigid bodies are defined by a set of one or more colliders. There are several types of colliders, varying in computation cost and in stability, and that can be combined to approximate the shape of the physical object:

Once the set of colliders is defined for a given rigid bodies, several other properties can be set up, such as the mass or the density, the friction and the elasticity of the body.

Finally, in order to visualize the rigid body in the rendering engine, a mesh should be attached to the rigid body, using the method iRigidBody::AttachMesh(). The position of this mesh will then be updated automatically whenever the physical object is moved within the simulation. Additional lights and cameras can attached too.

The common interface for rigid bodies is iRigidBody, but the ‘Bullet’ plugin also exhibits the interface CS::Physics::Bullet::iRigidBody

Static, Dynamic and Kinematic States

A rigid body can be in one of the states static, dynamic or kinematic, and that state that will define the behavior of the body in the physical simulation:

Changing the state of a rigid body is made through the methods iRigidBody::MakeStatic(), iRigidBody::MakeDynamic(), CS::Physics::Bullet::iRigidBody::MakeKinematic() and CS::Physics::Bullet::iRigidBody::SetDynamicState().

Joints and Motors

Joints (interface iJoint) can be set up between two rigid bodies in order to constrain their motion together.

A joint is defined by the degrees of freedom that are allowed, that is whether the rotations and/or translations are allowed, along what axis, and the minimal and maximal values that are allowed.

Additionally, a force can be generated on the joint, and that will act as a motor. This is made using the method iJoint::SetDesiredVelocity()

An alternative type of joint is also available with the pivot joint (interface CS::Physics::Bullet::iPivotJoint), that allows to grab a rigid body at a given point and move its position in the world. This is useful e.g. for grabbing an object through a mouse interaction.

Soft Bodies

Soft bodies (interface CS::Physics::Bullet::iSoftBody) are bodies whose shape is soft and is therefore modified by the physical simulation. Soft bodies are quite costly to compute and should therefore be used carefully.

A soft body is basically made of a set of vertices and triangles defining its shape and the straightness of the forces applied between the vertices. There are several ways to create a soft body, using the methods CS::Physics::Bullet::iDynamicSystem::CreateRope(), CreateCloth() and CreateSoftBody():

Displaying a soft body is more complex than a rigid body because its shape should be updated depending on the physical simulation. In that goal, a soft body animation controller has been created, allowing to animate automatically the Genmesh associated to a given soft body. See the class CS::Animation::iSoftBodyAnimationControl and related.

The parts of a soft body can be attached to a rigid body in order to follow its motion and act as a joint. This is made using anchors (see CS::Physics::Bullet::iSoftBody::AnchorVertex).

The CS::Animation::iSoftBodyAnimationControl has also additional functionalities in order to attach a soft body more precisely to an Animesh, and have the position of the anchors updated when the mesh is animated. All of these functionalities are useful to simulate the clothes of a character. As an example, you can have a look at the ‘Krystal’ scene in the ‘avatartest’ tutorial application (in ‘CS/apps/tutorial/avatartest’).


Terrain physical colliders are special objects allowing to create static colliders for terrain2 objects. They are created using the methods CS::Physics::Bullet::iDynamicSystem::AttachColliderTerrain().

If the collider is associated with an object iTerrainSystem, then the iTerrainCollider will update automatically its collider model whenever a new cell is added or removed from the terrain.


For characters and more complex objects made of a set of rigid bodies linked through joints, then it is advised to use the Animeshes and the ragdoll animation node. This system allows to manage automatically the physical simulation and the animation of the whole skeleton of the animesh. This can be typically be used in order to simulate a character falling on the floor, or to attach other physical bodies such as clothes to an animesh.

Hit Beams

Collision tests can be performed against a hit beam, e.g. in order to find the objects that are pointed by a mouse or a weapon. This is similar to the hit beam tests that can be performed with the Crystal Space engine, although they will act only on the objects that are present in the dynamic simulation (and not on their visual counterpart in the rendering engine).

Hit beams can be done using the method CS::Physics::Bullet::iDynamicSystem::HitBeam.

Moving Objects Inside a Dynamic System

A rigid body cannot be moved freely in a virtual world, and care should be taken whenever the position of an object has to be changed in order to not alter the stability of the simulation.

There are several ways to move a rigid body:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html 1.76.