A quick, biased article looking at useful BGE (Blender Game Engine) parameters.
Note that this is out of date, targeting Blender 2.4x.

Works pretty much the same in 2.6x. 

Rigid bodies

Blender objects have several properties used to determine their dynamic behavior: rbFlags, rbMass, rbRadius, rbShapeBoundType.

rbFlags ( => API docs ) provides a bunch of properties, the most useful properties may be:

• ACTOR (Actor)
• DYNAMIC (Dynamic)
• RIGIDBODY (Rigid Body)
• COLLISION_RESPONSE (No sleeping)
• GHOST (Ghost)
• BOUNDS

Decimators and LoD

The Decimator modifier can be useful to cut down face count; for example suppose you have an object ‘X’ with 5k triangles and you’d like to cut this down to 1k when generating a triangle mesh for the physics engine:

obj = Object.Get(“X”)
for mod in obj.modifiers:
  if mod.type is Modifier.Types.DECIMATE:
    if mod.name==’physics’
      mod[Modifier.Settings.REALTIME] = False # use ‘False’ to disable the decimator, ‘True’ to enable it.

When collapsing the modifier stack we temporarily enable ‘REALTIME’. We don’t see the cut down version while editing the scene, but can still export a simplified mesh.

Properties

Blender allows defining arbitrary properties per object; this can be handy in many situations.

list = obj.getAllProperties()
p = list[0] # then use p.name, p.data, p.type …

where type is one of:

• BOOL (bool)
• INT (int)
• FLOAT (float)
• STRING (string)
• TIME (timer)

When the motion of game actors is driven by a physics engine, we need a reliable method to control their motion. A governor uses negative feedback to adjust forces given a target velocity.

Principle

When a body of mass M is at rest, applying a force F will result in a speed S = F / m.

This formula can be used to write a simple governor – given the current velocity V0 and a target velocity V1, we have:

F = ( V1 – V0 ) * M

Units:

• F – force applied (Newtons)
• V1, V0 – velocity (meters per second)
• M – mass (kilograms)

Given the above we can write a very simple function that will calculate the force F required to update the velocity of an actor at every frame.

It may be working better than you’d expect – notably, given motion conservation, even a trivial governor (based on the above principle) will quickly achieve target velocity.

Scaling the output

The above formula can be modified by introducing a scale parameter:

F = ( V1 – V0 ) * M * S

The scale parameter may have uses – for example you can use it to increase the governor’s output when friction/air resistance become significant.

Note that scaling the output in this way may break time invariance – the simulation will behave somewhat differently depending on the size of time steps.

Implementation notes

Impulses vs continuous forces

A simple way to implement the above consists in delivering the governor’s output as impulses. An impulse is a discrete force applied to a physical body. A priori it may appear that continuous forces would be a better choice. However, depending on the way continuous forces are implemented by the physics engine, an impulse governor may be preferable:

• When applying a continuous force, the force is usually given in newtons per second. Therefore additional calculations are needed to precisely determine the total force delivered by the governor.
• With impulses applied at every frame, the ‘stop and start’ effect that one should expect is not visible.

Issues

Sharp changes in orientation

In some games, sharp changes in orientation are not a problem, especially when the actor need to be responsive (e.g. controlled by the player). For large actors and some other games however, sharp changes in orientation look ugly. A low value for S ( ~0.1 or less ) will reduce artifacts but this solution is not ideal.

A simple way to solve this problem is to interpolate between the current orientation and the target velocity before passing the target velocity to the governor.

Note: I removed the ‘motion aliasing’ section referred here previously; the artifacts I observed in my simulations were not related to the governor itself.

Going further: adaptive governors

Compared to the solution described above an adaptive governor can handle various situations by automatically correcting the scale factor S. This is done by measuring the bias between the expected output (target velocity at frame t0) and the actual output (real velocity at frame t1 = t0+1).

It is wiser to start with a simple governor - whether adaptive or not, the governor needs to be initialized with a base value for S; additionally when encountering obstructions, adaptive governors tend to ‘overheat’ – increasing S to a very high value. While it is possible to clamp the scale factor to a specific range, this is probably just the first in a series of adjustments – adaptive governors are smarter, they are also harder to design.

In the Bullet Physics Library, collision shapes are used to detect collisions between physical bodies.

You can get a feel of what’s available by looking at the inheritance diagram (from the Bullet docs). Depending on the workflow you’re implementing, just using meshes may be a quick-fix. However meshes have several disadvantages, which is why geometric primitives are thrown in:

• Performance – colliding meshes can be slow
• Reliability – high speed objects are more likely to miss/fall through when colliding with meshes. This can be fixed using ‘continuous collision detection’ or stepping the simulation slower, but it may reduce performance even more.
• Memory – Primitives use very little memory.

Convex/Concave

Convex shapes tend to process collisions faster:

• cone, capsule, sphere, box, cylinder …

Concave shapes tend to process collisions slower

• Banana, bowl, ring, coffee cup…

If your mesh is convex (boulder?) or mainly interacts with objects 5-10 times bigger than itself, btConvexPointCloudShape has better performance than btBvhTriangleMeshShape.

If we model a coffee cup using a convex point cloud, we can’t shoot  a bullet through the handle(*). But there’s no effective difference when simulating a cup falling on the ground (either way it won’t shatter like the real one, which is sad).

(*) got this example from Wikipedia

Code samples

Collision mesh

To create a collision mesh, we can use…

• btBvhTriangleMeshShape. This gets populated using an instance of btStridingMeshInterface.
• btTriangleMesh, an easy to setup implementer of btStridingMeshInterface.
• btVector3, instantiated using 3 arguments of type btScalar
• btScalar – a typedef for float.

Example:

#include “btBulletDynamicsCommon.h”

// … DIY: put this code in a function or class method…

btTriangleMesh* data = new btTriangleMesh();

btVector3 A(0.0f,0.0f,0.0f);

btVector3 B(1.0f,0.0f,0.0f);

btVector3 C(0.0f,0.0f,1.0f);

data->addTriangle(A,B,C,false); // false, don’t remove duplicate vertices

// true for using quantization; true for building the BVH

btBvhTriangleMeshShape* shape=new btBvhTriangleMeshShape(data,true,true);

The flags (quantization, BVH) have to do with internal optimizations, I just use the recommended defaults.

Note: I once idiotically created degenerate meshes (each triangle used 3 times the same point). A mesh setup in this awful way may sometimes generate collisions and cause fancy restitution effects. Before you start looking everywhere else for ways to fix tunneling and restitution, make sure your mesh is correctly setup (sigh).

Sphere

float radius=2.5f;

btCollisionShape* shape = new btSphereShape(radius);

Capsule

float totalHeight=5.0f;

float radius=1.0f;

btCollisionShape* shape = new btCapsuleShape(radius,totalHeight-radius*2.0f);

A capsule looks like a medicine pill standing upright. You can use btCapsuleShapeX / btCapsuleShapeZ if you want a different orientation. You could also use btMultiSphereShape if you want to create ‘thick segments’ with round caps (without using a transform) or other interesting things (rounded cuboids and such…)

Workflow notes

If you don’t want your setup to be completely game/application specific, simple techniques can be used to select the right primitives.

In my 3D editor, I use layers to hold various kinds of objects. So I have a layer for actors, another for the terrain, etc…

• If you don’t need much realism, capsules are a popular choice for actors (another time, I’ll explain why I prefer using spheres).
• boxes or spheres may be a good choice if you want to include collectible items in your simulation.

Instead of, or in combination with layers, you can use reference metrics to help you decide how an object should be represented:

• large, concave objects (e.g, weird shaped platforms and such) may require ad-hoc meshes with as few triangles as possible (use a triangle mesh)
• medium sized objects may use convex point clouds.
• small objects can use box, cylinder or sphere primitives. If you don’t want your objects to roll, boxes and cylinders are a better choice.
• fast, small objects (projectiles) can miss collisions easily. Using an elongated ‘dash-arrow-shaped-thing’ (triangle or cylinder) eliminates this problem.

‘Reference metrics’ means that you pass a descriptor defining ‘large, medium, small and fast’ to the class that builds your collision shapes. Then we can use the same factory over and over with game specific metrics. If you simulate very large or very small objects (‘not human scale’), you should worry about scaling (link to the Bullet wiki).

Next time…

Gravity’s fun. Applying forces and shoving bodies around is more fun. Next time we’ll look into dynamic and kinematic behavior.

The Bullet Physics Library is an open source (free for private and commercial use) physics engine mainly written by Erwin Coumans. After 8 years of development or more, it is a mature library. Integrations with Ogre, Irrlicht, Unity and other engines are available. It also integrates with content creation software, including Maya and Blender and has been used in a lot of games (wikipedia?)

After messing with the build a little (see my recent posts), we are ready for a friendly introduction.

How simple is simple?

Conceptually, this is how I want to setup a physics simulation:

1. Create a container (‘physics world’).
2. Add objects, aka ‘rigid bodies’.
3. Step the simulation and enjoy the result.

That would be 3 lines of code, right? How about something like…

PhysicalWorld world=new PhysicalWorld();
world.addBody(new Ball());
for(int i=0;i<10;i++)world.step(10); // 10 milliseconds

There are countless assumptions underlying this code. Gravity. Friction. Flying cows. You name it. I’m not saying that a physics engine should provide this level of integration (who would ever need it?); definitely not saying that there shouldn’t be 3 or 4 additional constructors taking in quizzical parameters.

I know this: if a physics engine’s hello world program looked like this, countless school kids would try it out, feel an atavistic surge of adrenaline and dive into the gory details.

You won’t get away without reading the bullet hello world tutorial

Let’s see how Bullet lives up to the leap of faith. I simplified their hello world tutorial for you, but frankly I’m just trying to encourage you to read it. I also highlighted the key steps.

#include <btBulletDynamicsCommon.h>

int main (void){

 // create the 'physical world'

 //

        btBroadphaseInterface* broadphase =

            new btDbvtBroadphase();

        btDefaultCollisionConfiguration* collisionConfiguration =

            new btDefaultCollisionConfiguration();

        btCollisionDispatcher* dispatcher =

            new btCollisionDispatcher(collisionConfiguration);

        btSequentialImpulseConstraintSolver* solver =
            new btSequentialImpulseConstraintSolver;

        btDiscreteDynamicsWorld* dynamicsWorld = 
            new btDiscreteDynamicsWorld(
                  dispatcher,broadphase,solver,collisionConfiguration);

        dynamicsWorld->setGravity(btVector3(0,-10,0));

 // create the ball
 //
        btCollisionShape* shape = new btSphereShape(1);
        btDefaultMotionState* motionState =
                new btDefaultMotionState(

                      btTransform(btQuaternion(0,0,0,1),

                                  btVector3(0,50,0))

                );
        btScalar mass = 1;
        btVector3 inertia(0,0,0);
        shape->calculateLocalInertia(mass,inertia);
        btRigidBody::btRigidBodyConstructionInfo

             bodyDescriptor(mass,motionState,shape,inertia);
        btRigidBody* ball = new btRigidBody(bodyDescriptor);
        dynamicsWorld->addRigidBody(ball);

 // step the simulation (and enjoy the result)

 //

        for (int i=0 ; i<10 ; i++){
          dynamicsWorld->stepSimulation(1/60.0f,10);

        }

 // remove and delete the ball

 //

        dynamicsWorld->removeRigidBody(ball);
        delete ball->getMotionState();
        delete ball;
        delete shape;

 // delete the world

 //

        delete dynamicsWorld;
        delete solver;
        delete collisionConfiguration;
        delete dispatcher;
        delete broadphase;

        return 0;
}

Not self explanatory

To avoid plagiarism and rest my keyboard, I suggest you go and read that tutorial. It explains everything step by step. Aside, the original tutorial includes a ground plane and log output so you can ‘see the ball falling and bouncing’ (that is, read the log and observe that the height of the ball varies).

Seeing is believing. Testing is learning.

After pasting in the original tutorial, we have a choice:

1. Plug graphic output of sorts and start hacking way
2. Read on, write sample code and verify our assumptions using tests.

I’m totally against option 1.

• If you haven’t got a system that produces graphic output yet, trying out everything at once will bring utter confusion.
• If you do have a system that produces graphic output and attempt integrating right away, you’re burdening yourself with the need to match your transforms and rotations to bullet’s before learning anything physics related, which is somewhat demotivating; or…
• …you are blissfully ignoring the fact that with screwed up transforms, the physics will appear to go awfully wrong. Then you’ll be asking around, complaining and imagining bugs that aren’t there.

Option 2 consists in getting a test framework up and running and writing innocuous simulations using the hello world tutorial as a starting point. Use console output; assert results; use breakpoints.

You can test without a test framework but you’ll end up with a mess of ‘little tests’ that only run when you ask them to. Lining up tests using a test framework is cleaner, faster and documents our learning process.

Outlook

This article is retrospective. I’m integrating bullet with my game engine and hope to get ‘all basic stuff’ sorted this weekend. Seven rough days in, I can build a ‘physics world’ that matches my game scenes, got the transforms sorted and can mix dynamic and kinematic objects.

In the next articles I will cover the following:

• collision and contact
• dynamics and kinematics (aka ‘the motion state’)
• creating meshes and other objects
• transforms and rendering.

Last time I documented a rough setup for Bullet on iOS. I think this is much cleaner and would highly recommend you try it. It should take no more than an hour. If you have problems with this, please drop a comment and I’ll try to help you out.

Recipe for building bullet as an iOS ready static library

1. Grab the archive. I used the *.tgz version (=> download page; Bullet physics engine homepage)
2. Extract this somewhere you like; I put this under trunk/ext/bullet, thus renaming from bullet-x.xx to bullet
3. Go to bullet/Extras/AllBulletDemosOSX; find a project named AllBulletDemos.xcodeproj
4. Drag the project in your xcode workspace (requires XCode 4 or later). At the time of writing the OS X demos build correctly with XCode  4.0.2. Note that this is a MacOS project, not an iOS project – if you build and run you should see a window with lots of attractive demos. If you don’t see this window try to fix the project first(!).
5. Create a new project (static library) in the same workspace. If you create this project inside the bullet folder, you could name it ios, then rename the project to bullet. You may let XCode create a unit tests target for you.
6. Use the project navigator to find a group under AllBulletDemosOSX/src/src. Drag this group to the newly created bullet project.
7. At project level in build settings, set the header search path to ../src and check ‘recursive’
8. build.
9. At this point you can remove AllBulletDemosOSX from your workspace if you wish.
10. (strongly recommended) use the ‘hello world’ code from the bullet wiki to write a simple test, and make sure you get the test to build and run correctly. You probably need to add files that were not under AllBulletDemosOSX/src/src. This is likely to happen because there is no automation that reliably tells xcode to include new source files as they are added to the underlying src folder (sigh).
    In practice you will see a lot of linkage errors that can be easily fixed by adding the missing files from src/LinearMath/, src/BulletSoftBody, src/BulletCollision etc…
11. (optional) fix the warnings that appear here and there and spoil the build.

Why do it this way?

There are several assumptions underlying this approach:

• You won’t update very often and would like to check in the source in your own repository, or maybe you don’t use version control but want to keep tidy. I use the so called ‘ext’ folder for third party stuff.
• You want a separate library; for this to work with iOS it has to be a static library.
• You don’t want to ‘rearrange’ the archive content. You just want to refer the files you need. Using the archive ‘as is’ makes it easier to setup on several computers (you can check in your project along with the archive so anybody on your team can build it).
• You want to have ‘unit tests’ handy so you can write tests while you’re learning how to use the library. I like to write tests to make sure I understand how the library works, and later the same tests can help me update to a newer version of the same library. Plus I find it much easier to write a few tests that output to the command line, rather than doing a big upfront integration with my software.
• If you look at the sources it should become clear that you don’t need everything. I use AllBulletDemosOSX because it already contains references to most of the source files we need, so it saves time and effort (thanks to the bullet forums for the tip)

Is there a better way to do it?

I guess if you have the right make file or know how to create one and are willing to spend the time, maybe it would be better. Especially if it can automatically detect changes when you update to a more recent version of the library.

A few caveats

• To rename a project, you can use the project navigator or the file inspector. You can rename a project the same way you rename a file in your xcode workspace and xcode will try to help you rename various entries. It’s easier than renaming the *.xcodeproj file yourself.
• You may need help to setup unit tests. If you’ve never done it please consider doing it as it’s well worth it and there are good articles about this lying around.

After yesterday’s draft, I tried to implement a simple physical body, PCylinder.

PCylinder implements both <PhysicalTarget> and <Collider>. Depending on how much realism we want, PCylinder can do a number of things as part of collision management. For example – it could be used to prevent cylindrical objects from overlapping with other objects, or it could move cylindrical objects in response to collisions.

I chose PCylinder because it provides a reasonably accurate bounding model for actors – especially bipeds.

But I think this is a little too quick, so let’s backtrack a little and see how we can improve the original model.

The ‘no difference’ simulation

PhysicalSystem, as drafted in the previous session is too preemptive. Instead of addressing collisions at this level, we can just iterate a list of ‘physical bodies’ and call their update function.

Initially, a ‘no difference’ physical simulation would just take updates from the ‘user model’ and endorse them; schematically, we’d have aggregations like:

• Node3D
  • PhysicalBody

then a user would call:

node3d.location = x;

and the no difference simulation would update physical body (and the user node), so PhysicalBody’s update method would look like this:

u=node3d.location – self.location // extract location update ‘request’.
// do nothing here, don’t modify u (‘no difference’)
self.location += u;
node3d.location = self.location;

Why this looks pretty dumb, we can use it as a more reliable starting point, whereas the previous model jumps to collision management without preamble.

The no-overlap rule

Given the above, we can apply a simple no-overlap rule, as follows:

1. extract update request
2. apply the updated location to the physical body
3. check for overlap with colliders.
   1. If there is no overlap, apply the updated location to the user node
   2. Otherwise, restore the physical body to it’s previous location and apply the unchanged location to the user node.

As you can see, there are no physics involved here. In fact not just there are no physics, but with 100% motion absorption, the ‘slightest collisions’ cause actors to freeze. This is a very poor way to handle collisions – so bad in fact that players are likely to complain about getting stuck on every obstacle.

Deflections, bouncing and absorption

For PC navigation, the most satisfying is probably a ‘deflection rule’ that corrects the NPC trajectory while avoiding overlaps, and preserves speed completely. this is less like physics, and more like assisted navigation.

We can take bouncing and absorption into account, if it is relevant to the objects we’re modeling, and the style of gameplay we’re designing. Applying these effects to various objects can be fun (e.g: bouncing of a falling rock). Applying them to the PC adds a gameplay element to navigation – it may fulfill a design requirement, add an element of polish or just frustrate players.

Contact model and platforms

Managing contact is essential to walking, rolling and other ‘ground motion’. A simple, reliable contact model assumes that a physical body is either airborne or not. If the object isn’t airborne, it is resting/moving on the ground. For the sake of simplicity and efficiency, we could provide separate implementations of PhysicalBody for platforms (walkable surfaces) and items.

The crux is that objects will behave quite differently when they’re airborne, and when they’re not.

• If an object isn’t airborne, we model this object as a ‘contact node’ owned by the platform it is resting on/moving over. This avoids defeating performance overheads.
• If an airborne object collides with a platform’s walkable surface, it will either bounce or become a contact node.

The minimal setup involves three essential steps:

First we enable ‘cloth mode’ on the target (a mesh we’d like to behave as clothe, e.g. a table cloth, a pair of jeans etc…). This means that we tell Blender to compute cloths physics based on gravity and collisions on this object.

I just outline the procedure, if you’re getting lost please refer to the links provided or dig up a YouTube video (no, really!). The caveats section is more interesting.

• Setup clothe:
  • select the mesh that you want to use as cloth.
  • select object > physics > cloth > enable clothe
  • enable clothe.
• Enable clothe collision
  • In cloth tab group, select collision tab
  • enable collisions
  • enable self collisions (recommended)
• Setup collider
  • select object to collide with
  • select object > physics > enable collisions.
• Bake and playback
  • Again, select the clothe object, then object > physics > cloth
  • Select the start and end frame. The 250 frames default will have you wait a couple of hours or more. Just pick the frame range you need, or less to experiment with parameters.
  • Press ALT+A to preview the animation for baking is complete.
  • Select Free bake to get rid of the current simulation.

Caveats

1. The first time I run this simulation I had the character’s skin clipping (showing through) the clothe. Not just a bit, really showing through.
   => If we have a character animated with an armature, and we want to ‘let physics take care of clothing’ we probably don’t want the armature to be enabled for the cloth object. However, with a posed character, that typically means that, in the first frame, the clothe object won’t be fitting, it will overlap the character. The simulation starts with the posed character as is (not the rest position).
   I shifted all keyframes 10 frames forward, then key-framed the character back to rest position (at frame zero) and fitted the clothe correctly. That got rid of clipping (no need to worry about collision quality just yet).
2. To prepare my models for Open GL rendering I usually split meshes by color (otherwise color bleeding occurs). Unfortunately this also means that each colored piece of clothe becomes a separate object in it’s own right.
   => A cloth object must be ‘in one piece’ for the simulation to work correctly. separating color groups should be done later (e.g. when exporting the animation)
3. Initially my character didn’t have a trunk (anymore). Why include faces and vertices that won’t ever be displayed? Unfortunately this doesn’t work any good with clothes, because there’s nothing to collide with(!). The solution, obviously, is to have a complete body with a decent shape! In fact we don’t need to use the same object for simulating the clothe and rendering (let alone animation playback in a game).
4. Physics ‘takes time to boot’. The piece of clothe we’re animating won’t look right at frame 1, it needs to ‘shape up’ following the rules of the simulation.
   If we’re already adding lead frames at the beginning of the simulation to match the shape of the cloth with a ‘rest position’ then this may leave enough lead time for the clothe to start fitting naturally before our animation really begins, otherwise there is a technique (see links above) which allows baking a pre-calculated deformation for the cloth, so we could replace the original mesh by a fitted version.
5. Why does it look all rounded?
   If we’re using something like 1 blender unit = 1 metre (I do) then the default minimum distance for collision is really set too high. if we’re trying to fit a cloth nicely, it will look good in places, bad in others. In my case I had a sleeveless dress with just a couple of ribbons to fit at the top, so the ribbons looked all round and even bounced unrealistically against… …nothing. Reduce the collision distance as much as possible (there are two settings for this, one in the collision tab for the cloth, one in the collision tab for the character’s body.
6. Clothe simulation per se isn’t overly time consuming (or the Blender routines are deadly optimized), collisions are. Animating just about 20 frames takes minutes, and my model isn’t really high poly. This isn’t a problem except tuning parameters is time consuming.

Simple experiments

While trying to get around the ’rounded sleeves bouncing in thin air’ issue, I tried a few things…

• Combining with the sub-surface modifier. It may be fairly obvious that, if we want smooth wrinkles and other clothe-like appearance, we might want to refine the definition of the source mesh. Adding a subsurface modifier does the trick (without the need to generate hard to edit vertex data). The subsurface modifier should be at the top, keep the cloth modifier (gets generated automatically when we check the cloth setting) at the bottom.
  Make sure the resulting subsurface doesn’t overlap the character
• Pinning. With most garments, not all parts are meant to flow freely. In fact, some parts are stretched. The cloth simulator gives a light ‘free flow effect’ that looks nice in parts and rather terrible in others. So Blender includes a ‘pinning feature’. The idea of pinning is that a selected group of vertices will be very ‘stiff’ compared to other, keeping the default shape of the mesh throughout the simulation (can save a lot of time trying to tune cloth parameters).
  With a posed character, we really can’t use pinning without  adding the armature modifier to the clothe. While this hurts my logic a little (I want the body to the move the clothe, not the armature…) it can be fairly easy to limit the armature’s influence (e.g. use envelopes or vertex groups) to avoid unwanted effects.1

I’m seeing weird glitches when I combine sub-surface, pinning and armature together (sometimes). Aside, my character’s dress seems to bounce up all too willingly. It’s almost amusing but not always desirable; but I’m really just learning how to tune this up and there’s quite a bunch of parameters to go through.

Conclusion

Animating clothes with bones is a total pain (I tried). In contrast, using the Blender cloth functionality definitely has a learning curve, but the results look very promising. I can see many useful applications, even with fairly stiff, low poly clothe models. With a reasonably high poly count it can get really pretty.

I’m expecting the baked cloth animations to go through when I export the animation (because the exporter collapses the modifier stack, and cloth is a modifier) so I may be able to get this working in my game. Frames may need to be offset to allow time for ‘shaping up’ the garment, then I would need to adapt my exporter.

Finally, many animations cycle through. The physics simulation doesn’t take this into account, so beginning and ending frames must be interpolated, either while exporting or later.