Don’t retain anything unless you must

Regarding reference counting, this is the idea I’d like a developer to at least consider. For several reasons.

• A dangling pointer / weak reference needn’t be evil. During development hitting a dangling pointer is better than preventing an object to deallocate when it should. An object that exceeds it’s intended lifetime can behave in undesirable, unpredictable ways. All it takes to detect an invalid object is turning NSZombieEnabled on.
• Everything retained needs to be released. Retain less = less work.
• If the sums don’t add up (over-released/over-retained object) it’s easier to work out what’s wrong when the number of objects involved is small (e.g. 1, 2 or 3)
• Potentially any object that retains a target will increase the target’s lifetime; this a priori translates into increased memory usage.
• Whenever retaining an object we risk creating a cyclic reference. Of course ‘we know what we’re doing’ (and cyclic dependencies can be removed) but isn’t it just easier to avoid getting too many of these.

Unwanted objects that remain inside the runtime after they should have deallocated will harm you. The more your system is dynamic (e.g. game, simulation) the more these objects are likely to generate functional bugs that are hard to figure.

I read a little about automated reference counting (ARC) which we are getting in iOS5. If I understand correctly (reading here) the central idea of this article will translate to ‘don’t abuse strong references’. Now that I more or less get it I look forward to using ARC but I guess I’ll be waiting for another 6 months or so, being a happy laggard.

A quick introduction

Reference counting approaches memory management indirectly, using concurrent ownership:

• Take ownership of an object by retaining it
• Relinquish ownership by releasing the object.
• When all owners of an object have released it, the object is deallocated.

indirect : we don’t explicitly deallocate the object.
concurrent: several objects can simultaneously retain the same target.

The basic rules are covered in many places, like here and here and from the horse’s mouth, here.

Reference counting is efficient, error prone and occasionally awkward.

More efficient than garbage collection: objects get deallocated as soon as their reference count reaches zero, whereas GC is heuristic and may cause your program to slow down unexpectedly while it’s doing its thing.

Error prone – programmers need to pair release/retain statements (either directly or indirectly). Mismatched statements cause a program to leak or crash. Additionally reference counting is hackable; it is easy to traffic the sums (either accidentally or by design) and obtain a valid program that handles memory correctly, while violating reference counting rules.

Awkward, notably when we know beforehand that we would like to deallocate a well defined subset of the runtime graph. A typical example is when you start a kind of ’session’, allocate any number of objects in the course of the session and wish to deallocate all the objects at the end of the session. In such cases opting out may be somewhat short sighted yet remains attractive.

A design idea

There is a principle which I find rather productive: instead of thinking about whether an object should retain X or not, consider X then try to think about an object ‘up the runtime graph’ that should own X. Often there is an object Y such that, if Y deallocates, X should also deallocate. It could be the parent of X or maybe another object up the chain.

Now, if there is only one such object Y, then you don’t need to retain X anywhere else. You can even assert the retain count to ensure that X is unambiguously managed by Y.

Anti-patterns?

There are little recipes around (e.g. here and here) that you can use to ‘ease the pain of memory management’.  From the point of ownership these recipes work the same way GC does: easy way out of memory management issues, hard into functional bugs with all the enticing prospects of a muddle-through approach.

One point these approaches have in common is ‘if in doubt, retain’. I’m OK with that as long as I know (beyond reasonable doubt) that keeping the target alive won’t generate unwanted behavior. If the target is an observer that receives and processes notifications… …then if in doubt, don’t retain. A clean, happy crash will provide the decision point where you can say:

• ‘Yea, this object should still be alive at this point’ (in which case maybe something else should have retained it) or…
• ‘No, this object is dead and well dead, we should have sent a death note’

Additionally these approaches look incomplete. You need to use class extensions if you want to declare everything as a property without exposing all your ivars.

Weak references

An unretained field is a ‘weak reference’. At least in a first approach, the use of weak references is encouraged in a number of situations:

• Backward references from a child to a parent
• Listener sets. See a straightforward application here.
• Same type objects cross-referencing each other.
• Any situation where you feel unsure whether to claim ownership (retain) or not.

Implementation details

Maybe for historical reasons there are two approaches to enforcing reference counting in objective C:

• The non intrusive approach revolves around tagging using properties and indirect access using self.x = . Although this approach looks theoretically better and safer there are practical details of how it is done in Objective C which I often find off-putting. For one I like to not declare properties until I want to expose public state, and I’m not used to class extensions, thus find myself unwilling to add class extensions to my .m files.
• An older approach revolves around the [release] and [retain] statements. The advantage (easier reviewing/debugging) and inconvenience (intrusive approach leading to somewhat cluttered code) are the explicit way in which things are done. This leads to a weird situation because it makes it more likely that bugs are introduced while making the same bugs easier to fix.

Note about [autorelease]

[autorelease] is very convenient and helps avoid errors in many situations. Sadly enough when an error does occur and [autorelease] is the lucky guy that causes a target to deallocate, we get very little debugging information because [autorelease] doesn’t take effect until we exit the frame.

So I try to limit its usage to where it’s unavoidable.

What is covered elsewhere (or should be)

• Cocoa collections (NSArray, NSSet, NSDictionary) retain all their elements. This can be a hindrance in some cases, but you can configure the underlying, toll-free bridged counterparts, as demonstrated here.
• There are various approaches to notifying stakeholders when an object gets deallocated. I will try to write a quick article about an approach I find useful when implementing observer schemes.

What a great title. I’m having issues fixing up a physical model for my game character. Since this has been dragging on for a while I decided to review the situation.

The problem given

Game character:

• Walk, run, jump
• Can get hit by heavy projectiles (when hit, we want a ‘physical reaction’)
• Can fall

The terrain:

• Arbitrary shape including slopes (in the worst case scenario, modeled as a mesh)
• Walls and other obstructions
• steps – probably not staircases but a variety of things that look like steps, including non static models (e.g. planks)

Animation system:

• Traditional animation cycles (no physics in here)

What I’ve done

I tried two distinct physical models

• Capsule. A single capsule is used to represent the actor
• Balls. One ball is used to represent the actor’s feet, another represents the head.

I have also written a servo to control walking and running. A ballistic simulation (running in a sandbox) is used to prepare jumps.

What doesn’t work, or doesn’t work well

A ground ball isn’t great

Up to a point, rolling a ball on the ground (aka ‘ground ball’) to represent walking is OK, and I can also add impulses to make it jump. But this isn’t perfect:

• If we really let the ball roll, we can’t attach anything to it. This means that we need a constraint to maintain the relative position of the feet with another ball representing the head/upper body.
• If the character is thin, the feet can’t skip stairs or climb over obstacles unless we add a vertical impulse. Or we have to make the ground ball larger.
• Balls don’t respond very well to friction. This means that the actor tend to drift especially when stopping on inclined surfaces.

Capsules aren’t perfect

Using a capsule brings a different set of problems:

• In my previous tests I’ve seen a kind of stop and start effect which is probably the result of sliding the capsule on the ground using my servo. This might be because friction plays a very different part when sliding versus rolling.
• I can’t really lock the capsule’s rotation. locking a body’s rotation is a one liner which makes sense in some cases. Let’s take a simple case where it doesn’t work: I have a heavy block falling on a game actor – then locking the capsule’s rotation is plain wrong.

Common issues

Handling climbing gracefully is a chore. So far I found it difficult to tune my servo to get seamless climbing – in other words, slope transitions generate a kind of noise while the servo is adjusting.

Sudden altitude changes (e.g climbing on top of a plank) are also difficult to handle correctly. If the servo is too loose, velocity tends to get out of control. If the servo is too tight the actor will stop, or even backtrack a little when an obstacle is encountered.

All the above problems are made more visible (a) by the use of a traditional animation system and (b) by the fact that I’m animating a human character. Human (or animals for all that matters) negotiate obstacles with grace and can adjust their motor functions in a smart way.

I’m reluctant to use a rag-doll (actually model limbs and joints). In theory it’s the best solution. In practice it might bring enough problems to keep me busy for a month (or three?)

Then… what?

Here’s my guess:

1. Use a capsule (or even a box). Using a ground ball doesn’t solve half of my problems and forces a clumsy model for the upper body.
2. Add a soft constraint to maintain posture (in other words, ‘lock rotation’ ). The constraint should do ‘enough of a decent job’ that the actor won’t tilt more than 5-10 degrees while walking or running. When a heavy object hit the actor the constraint should saturate, and we also want to adjust the same constraint dynamically (e.g, when an actor is KO or badly stunned they can’t stand, so we relax the constraint)
3. Test the feet’s line of sight (eyes in your toes?) to detect obstacles. We’d rather never do that because it’s expensive but we don’t need to do it at every frame ‘just sometimes’.
4. Consider using fixed settings instead of a servo (or write a better servo) to handle slopes and other continuous changes.

Alternatively, I could try using a very simple rag-doll (e.g 3 to 5 bodies for the legs and trunk). But most problems will remain integer and even a simple rag-doll may be a lot more work.

[to be continued]

This article is somewhat personal… It illustrates the kind of problem you might run into if you try to enforce integer separation ‘between view and model’. In this case, ‘integer separation’ means that I can run my game without popping an Open GL rendering surface or a UI. Getting this to work has been some work. Getting to work without it being in the way of even the simplest things may require more work.

Yesterday I added basic support for playing image sequences to my StageComponent. StageComponent seemed a good choice because it is a high level controller owning the stage (model), the stage view (3D canvas) and the stage UI.

Cut scenes are often triggered by simple events – defeating an enemy, entering a new area. So it made sense to call my stage component from a trigger handler. I unexpectedly bumped into an idiotic problem: according to the framework *I* wrote, I’m not supposed to call StageComponent from game code (at least, not directly). Heck, why is that and what am I supposed to do about it?

So I dug a little and run into my StageManager. StageManager is readily accessible to game code. It doesn’t know about the stage component or the UI, and the intent became clear: to run my game without graphics (for test), I’m hiding dependencies on OpenGL and the UI toolkit.

Now I also remember another design goal: hot switching. The idea of that is to allow seamlessly switching the scene or the UI without breaking behavior.

Looks nice, but it can’t be really nice if it makes me feel like a pedantic ass when I’m just trying to play a slideshow.

A route

A found a way to call the stage component, however the result isn’t very satisfying. It looks like this:

• StageManager playCutScene:(tag)name
  • <UADelegate> playCutScene:(tag)name
    TestUADelegate playCutScene:(tag)name (skip the cut scene)
    VisualUADelegate playCutScene:(tag)name (call StageComponent)
    • StageComponent playCutScene:(tag)name

Maybe you can see where this is coming from:

• StageManager may be more adequately named ‘GameSessionManager’. It is a top level game controller that gives indirect access to the game UI.
• User Agent (UA) delegates are classes that can either emulate or wrap the game UI.
• The stage component looks like an MVC controller. When running without graphics, I still instantiate a stage (typically from a data file) but I don’t instantiate a stage component.

So why is it bad (setting pedantry aside)?

Part of the problem is simply that I’m not used working this way.

Another part of the problem is that I couldn’t find a route to bridge these classes using game code. All the above classes are framework level.

Finally, I think part of the problem is that visual and non visual agents are defined as an alternative. This disposition looks fragile. I’m guessing a more durable disposition would be to have all interactions processed by a non visual agent, and have visual agents (the UI) call into that.

I wrote about (realtime) game behavior and activities before. I still see a lot of bugs on this side. This is isn’t a surprise because most behaviors I wrote lack unit tests and my activity framework may lack safeguards. So I decided to write a short series of articles in which I explore possible ways to make game behavior less error prone. Expect a lot of trial and error, nothing especially didactic.

To quickly summarize the story so far, an activity is an object that manipulates the state of an agent on it’s behalf. For example a Walking activity cause the agent location to be updated and make this agent perform animations.

Programming real time behavior is inherently error prone. I’ve seen countless bugs related to realtime behavior wherever I worked, even in situations where behavior remain fairly predictable. So I decided to document my progress (or the lack thereof).

Things I’m interested in:

• Rogues – activities that do not release all their notifications when completing or being interrupted.
• Sleepwalkers – activities that continue execution after disabling their target agent.
• [...] (will add things later)

The terminology is my own. It is very possible that somebody came up with something better already, but I don’t know what that is. I use ‘Sleepwalkers’ because Zombies are a term in memory management, and disabled agents may be re-enabled in some cases.

Testing a behavior

I wrote a test for one of my game’s activity: JumpActivity.

The test uses two stubs, one for the actor that does the jumping, one for the caller that receives notifications from the activity.

It is not a unit test. Instead a unique test method walks through every step in the activity, finally asserting whether the caller was notified that the activity is complete:

[x startWithCaller id<Caller>)caller agent:nil];

[x animationPaused:TAKEOFF_FRAME];

[x animationPaused:APEX_FRAME];

[x motionDirectionChanged:goingDown];

[x onContact];

[x animationComplete];

STAssertTrue([caller completed],@”activity should have completed”);

Testing against rogue activities

Testing retain count after an activity is complete

Rogue activities, so to speak, are a common source of bugs in game programs. A rogue activity is an activity that does not release all it’s notifications upon completion or while stopping. First I modified my ActorStub, like this:

-(void)addMotionListener:(id)l{ [l retain]; }

-(void)removeMotionListener:(id)l{ [l release]; }

Then I can assert the retain count after the activity is complete:

STAssertTrue(x.retainCount==1,@”should be 1: %i”,x.retainCount);

I think it makes sense to test it this way. I also think this would help with memory management.

Testing retain count after an activity has stopped

Rogue activities are more likely to occur when stopping an activity. It’s harder to test too. ActorStub is naive and will cause the retain count to decrease even if the listener have never been added. I’m not very hot on making this stub any more complex than it already is. So I’ll try using an actual implementation instead.

With an actual Actor3D instance, the test passes but this doesn’t actually ensure correct behavior.

Note that the retain/release events that I was simulating with my stub are due to the activity being added to / removed from NSMutableArray instances as part of registering notifications.

I instantiate my actor using a no-arg constructor. Most notifications from Actor3D are delegated, so in this case most delegates are nil, and as a result retain/release operations are not invoked as expected.

Instantiating a full blown actor may require a fair amount of boiler plate. Actors are backed by scene nodes and physics engine nodes. I doubt whether setting up the boiler plate is worth the effort. For one it will add typing dependencies to my test because I would have to pass Node3D and PhysicalBody, and it violates encapsulation because we don’t want to care about Actor3D delegates when testing an activity.

Asserting?

Although it doesn’t sound as good as a test, maybe the retain count can be asserted after stopping a behavior. Most of the time, [behavior stop] is called implicitly when an agent start a new activity. Seems like a good place to assert the retain count. Since it’s just ‘most of the time’, it’s not entirely reliable. But I haven’t paid much attention to memory management or rogue activities so far, so I expect running into this assert about 50 times before things start running smoothly again, and this will encourage me to improve all my activity implementations.

Back to mocks

Finally I decided writing a mock instead of using the actual collaborator. I kept my assert statement but debugging my activities this way is much less attractive than using tests. The mock actually registers listeners and manages retain/release operations so it’s a little beefy to my taste, but I can reuse it with many behaviors I need to test.

Preventing is better than curing: hooked listeners

I came up with the idea of a hooked listener. Suppose we have a foolproof listener registering with a target, like this:

[trigger addContactListener:foolproof];

Then trigger will invoke the following:

[self.safeContactListeners add:foolproof]

And finally safeContactListeners calls back a base method defined in the FoolProof class:

[foolproof hook:safeContactListeners]

Causing foolproof to maintain a list of its triggers. Upon calling [foolproof stop], we then iterate the list and release all the hooks. In which case instead of burdening the activity implementer with the duty to release all notifications, this happens automatically.

If foolproof explicitly stop listening to trigger, [unhook] is called and the matching entry is removed from the list.

There are potential disadvantages:

• This doesn’t do away with the need to track all and every trigger since third party services wont call the hook() method; in fact because operation is ‘hidden’ you might even suggest the scheme is a little evil.
• We now have backwards references from foolproof to all it’s triggers. Maybe it uses memory – but in my case the number of foolproof entities would be in the hundreds or thousands so it’s no big deal. Still, maybe it’s bad in some way.

The big advantage if notifications are internal/custom, is that activities needn’t provide a custom implementation of the [stop] method – doing away with rogues once and for all.

So I’m giving it a try.

I just did a test using blender 2.49’s radiosity feature. I wanted to bake self illumination to vertex color.

However, this opens more questions than it solves.

Radiosity in 2.49 doesn’t support double sided faces. This seems to cause artifacts when baking clothes and hair (clothes don’t have thickness, and I doubt I would go this far – the model is heavy enough as it is).

Additionally, the rendering is not very clean with the original, mid poly model (~5k faces). I can increase the definition to render lighting (using radio buttons), but then I need to transfer the result back to the original model.

So the plan (assuming I persist) would be to modify the model, add thickness to clothes, bake illumination, then write a script that can transfer color data back to the original model.

I think it’s a bit over the top but radio bakes play an important part in our pipeline already, and I feel vertex paint, however old fashioned, offers distinctive possibilities. For example I already have a script that can extract dark areas from the radio bake, which gives access to ’shadow geometry’ – so we can take this into account when programming gameplay.

I’m also working on a method to simplify geometry while losing as little color information as possible – ultimately this should help me improve rendering quality without losing much performance.

An activity is a realtime process; often, activities in games are programmed asynchronously. This means that we use frame calls, events and observers and is probably what most game programmers are familiar with.

Programming activities is often time consuming, typically involving a lot of debugging. This is an exploratory article – just throwing in a few ideas without trying to reason everything. The article focuses on how to expose activities as agent methods, so that implementing more complex activities can be faster and less error prone.

1 class = 1 activity

This is a safe start. The unsafe, quick to start, painful to get done with way consists in dumping several activities in the same class. For example you might want to have an ‘Actor class’ and dump walking, striking and jumping code all in there. That is so very short sighted that you might start regretting it (or blindly assuming the consequences) even before the result becomes demo-able.

Helping activity implementers

A little bit of design

In a best case scenario, implementing an activity boils down to delegating to other activities. Broadly, an activity class is a kind of controller so you don’t want detailed implementations of anything the activity does, anywhere in your activity class.

Let’s assume that you sit at your desk and start designing your activity; let’s take the example of a jump activity – one way to design it could be:

• start playing the jump animation until the actor feet should leave the ground.
• at this point, give an impulse for the underlying physical body to start moving up; also, play the animation until the apex position.
• when the apex is reached by the actor, start playing the ‘descent’ animation segment until the actor feet touch the ground.
• When the feet touch the ground, play the end of the animation and (if applicable) kill the actor’s velocity.

What the implementer need

In this case we can see that the implementer start delegate activities, then they either wait for these activities to complete or for some condition to occur, then fire up more activities, until the super-activity we want to implement is complete.

1. Starting delegates

To start an activity, the implementer need easy to access semantics. There are two cases:

• An object is passed to the activity constructor, and this object is capable of invoking the desired activities. This is easy because the object (’actor’) defines a subset of available APIs.
• Activities are available as classes that need to be instantiated. This is harder – especially if the classes are un-packaged. It’s just harder because there are more activities to choose from, and ultimately more parameters to pass.

So even though we prefer implementing activities using separate classes, it is good practice (and often intuitive) to make activities available as methods that can be invoked on objects (for example you can have Run, Walk activities, and you can then invoke run(), walk() upon instances of an ‘Actor’ class).

2. Resuming an activity

Aside from starting activities, we want to be notified ‘when the next part is ready to start’. Here again, there are two cases:

• Chaining. In this case we want to be notified when the previous activity ends. When chaining, the easiest for the programmer may be to assign a callback that gets handled automatically when the previous activity is complete.
• Triggers. In this case we don’t care about the previous activity we started (for example, ‘wait until the actor reach the apex’ has no direct relation to passing an impulse to the underlying physical body, or playing the next phase of an animation).

There are complex cases where we want for several conditions to complete before starting the next activity. I will ignore this for now.

Considering the above, ideally the most helpful form is like this:

actor.performAnActivity([params], aCallback)

There are several things that are important here…

• We don’t explicitly register to receive a notification using a separate call.
• We don’t need to explicitly handle a notification. The downside is that reading the class interface hardly tells us which notifications are handled – but the code itself is very concise and sufficiently informative.
• We don’t have to explicitly unregister to avoid receiving unwanted notifications later. This simply avoids lots of bugs.

Starting from this ideal case, we can formulate an alternative when triggers are used instead of chains:

• We don’t want to register as a listener bound to an interface. This would mean
  • Adding no-op implementations for many events we don’t care about, which is a lot of ‘free clutter’
  • Having to unregister manually.
  • Potentially having to deal with conflated implementations, where we expect the same notification to be handled several times during the activity life cycle, so we have to add control flow to the handler.
• We want to be notified selectively. In the best case scenario when the callback fires we hope that we can execute the intended action without checking the details of what’s happening first.

If we think a little further, we might find that even indirect conditions (’notify when the actor reach the apex’ may advantageously bind to actions (e.g. giving an impulse will affect an object’s trajectory, so it’s little surprise that we’re interested in finding when the actor touch the ground, or reach the apex of their trajectory). However this is probably extrapolating a little too much.

3. Selective notifications

There are forms which make it easier for implementers to selectively register their callbacks:

• Name trees – name trees mean that the implementer start typing a word and this points at a general type of condition, then auto-complete (where available) will point at detailed conditions available. Even if you don’t have auto-complete, or like it turned off, naming trees will tend to alphabetize choices in the API documentation, which is good.
• Include additional parameters to help the implementer reduce the scope of the notification.

4. Summary

Let’s summarize the important points:

• Although activities are implemented as classes, accessing them as methods of the main actor(s) involved is convenient.
• If callbacks (passing functions for later invocations) are available, their use is encouraged.
• Having to register an activity as a qualified listener is evil in many ways.
• Having to unregister so we do not receive further notifications is a burden. Additionally it is evil because if somebody forget to unregister, we may end up with a variety of errors, including intermittent bugs

The good news

There are a few good points here:

The API designer can help

A lot of the above depends on the affordances provided by the actors and activities exposed to the implementer.

In other words, if the ‘core activities’ provided by the game framework are implemented according to the above, it looks like the game programmer will work faster, and their code will be safer and more concise.

It’s not about how the game programmer write their code

I refer to APIs as ‘affordances’. Aside from ‘that essential piece of advice’ (1 class = 1 activity) we have said nothing about how the implementer should actually write their code. We just make APIs available, and these APIs help implementers not go wrong.

It points at (hopefully) easy, yet non trivial ways to re-factor activities

Ailing game code may benefit from refactoring supporting activities as described. However, this refactoring isn’t entirely trivial – For example, observer schemes are essentially innocuous – not bad practice. But in this case we can clearly benefit from specialized observer schemes – using callbacks and fire-once notifications. This contrasts with other styles of programming (e.g, programming the user interface) where fire-once notifications could actually end up creating a lot of bugs, because usually we need to receive the same notifications whenever the same conditions occur, not just once!

Exposing activities

Once a game programmer have successfully implemented an activity, they need to expose (some of) it. This is the flip side of the above.

Untamed activities

The activity, originally, should be implemented as a separate class. If the scope of the project allows it, this may be sufficient – as long as there aren’t too many activities in our library/game, we can just instantiate these activity whenever we need them.

Generally speaking it is probably better NOT to attempt exposing an activity further before it is actually needed. If nobody needs an API, why write it?

The idea here is that activities can exist without exposing much APIs, let alone partaking a kind of framework. This idea makes it easier to focus on making it work, versus worrying about how to make it available. The opposite trend is perverse – giving ourselves less time to make sure the activity works, and putting work into making unreliable code visible to other parts of the system.

Progressive integration?

A first, progressive step may consist in exposing the activity via an actor. This is as simple as just adding a walk method to an actor class, and calling Walk from that method.

Then we want to provide support for activity specific callbacks. Here a base class can help – e.g. if you inherit the “Activity” class then you can automatically inherit methods to register/unregister listeners. Listeners must be cleared after each and every notification, which satisfies one of the fundamental constraints described above.

Routing the callback should come naturally – as long as the actor’s ‘walk’ method doesn’t actually return the underlying activity, we can’t register the callback ourselves, so the ‘walk’ method providing a (possibly optional) callback as a parameter should be okay.

Note that callbacks (versus interfaces) can have frustrating caveats – in many scripted languages callbacks are only checked at runtime. Having an interface that specifies ‘just a no arg function’ may be dumb but if it can improve compile time safety, I would prefer interfaces – and use a strict naming convention to associate such interfaces to the activities that spawn them.

Until next time?

I haven’t been entirely happy with my real time / behavior code so far. I tried to write a framework which doesn’t look all bad, then I had a little break away from programming, which hopefully gives me a little hindsight.

I especially like the ideas in this article because they’re not framework specific – so there’s no requirement to impose a wholesale change on your game code to apply them. This stuff isn’t tried and tested but looks pretty interesting. After I test-drive it a little, I’ll let you know how it goes.

Obviously there’s a lot more to real time game behavior (e.g. how to interrupt / resume, override activities – how to avoid resource conflicts… .); hopefully I can cover some of it in another article.

I have decided to wrap up my quick series about the Bullet Physics engine for now. Later I hope to cover raycast (we’re using that to test whether a NPC can see the PC in our coming game), constraints and soft bodies.

The survival kit includes the following articles:

• (Hello) Balls! – the basics
• Collision shapes – sample code showing how to setup common geometric primitives
• Dynamics – applying forces and impulses
• Kinematics – some information about kinematics objects and the motion state
• Collisions and contact – how to retrieve contact points and find out whether two bodies have collided.

Remember these are working notes. I still recommend you look at the official tutorials on the Bullet website – they are definitely more comprehensive.

We’re getting good results with Bullet so far and we feel really happy that I bothered building an integration for it. Our integration uses Objective C++ and provides a wrapper that can be used from Objective C. Here are some reasons we feel happy:

1. Integrating bullet with our engine has been fairly smooth. There is a learning curve (and I’m still learning!) but the APIs are often fairly explicit and the library is kind of easy to use.
2. Having a nice physics engine take care of collisions and moving objects around just saves a lot of work. Game dev folklore claims that non-physics oriented games won’t take advantage of a physics engine. Think again?
3. Objective C is not very fast. Bullet provides many optimizations that we couldn’t afford coding ourselves – and it’s all C++.

Getting notified when a collision occurs is very useful:

• Did a projectile or weapon score a hit?
• Did an actor enter an active area?
• Did an actor start falling?

Bullet uses the following concepts to handle collisions and contact:

• Contact Pair: two objects that may collide form a contact pair. This contact pair exists even if there is no collision. Here a synonym for contact pair is ‘manifold’.
• Contact Points: at any time two objects may have zero, one or more contact points.

After iterating the simulation, we can retrieve contact pairs and check the number of contact points. So we can tell whether two objects collided (contact points > 0) or lost contact (contact points == 0)

Colliding objects are returned as instances of btCollisionObject (which btRigidBody inherits from). The method used to return collision pairs (aka manifolds) can return a pair with zero contact points. Just because we have a pair doesn’t mean there’s a collision, or contact.

The following code fragment may be called after stepSimulation().

__________________________

int numManifolds = world->getDispatcher()->getNumManifolds();

for (int i=0;i<numManifolds;i++){

btPersistentManifold* contactManifold =
world->getDispatcher()->getManifoldByIndexInternal(i);

btCollisionObject* obA =
static_cast<btCollisionObject*>(contactManifold->getBody0());

btCollisionObject* obB =
static_cast<btCollisionObject*>(contactManifold->getBody1());

int numContacts = contactManifold->getNumContacts();
}
_________________________

You can also find information about the location of contact points. Check the Bullet Wiki tutorials for more information about collisions and collision filtering

Impact velocity

I find that impact velocity can be reliably retrieved right when the bodies collide – in the code fragment above, obA, obB thus store their velocity at the time of impact, right before applying restitution. This is convenient to evaluate damage (e.g. remove health points / apply a stunning effect etc… ) resulting from collisions.

Most 3D applications use a scenegraph that stores scene node coordinates and we need a convenient way to update these coordinates from the physical simulation. In this case the simulation contains a dynamic object which moves ‘on its own’, being subject to gravity, collisions and other forces.

Often we want to animate objects ourselves, but we still want other objects to bounce off such objects, so we create a kind of alias or reference to the object we’re animating. Such an alias or reference is made into a kinematic object. A kinematic object still has physical properties (e.g. friction) that help determine how dynamic objects interact with it.

This article is a work in progress. Please refer to the motion state tutorial on the Bullet wiki. In theory motion states and kinematic bodies are ‘pretty simple’. I often find it easier to use dynamic bodies out of the box and rely on the default motion state.

The motion state

All bodies in the simulation are setup with a motion state.

The motion state allows sharing a node’s transform between the physics engine and the renderer. btMotionState is a small interface that specifies a getter/setter pair. The bullet API calls the getter to retrieve the shared transform and calls the setter to assign it.

Kinematic objects aren’t animated by the simulation, ‘we do it ourselves’. How do we let the simulation know that these objects have moved?

1. Create a rigid body that will ’stand for’ the kinematic object. This will be a kind of ‘alias’ or ‘reference’ to the object we’re animating, so we need to disable dynamics for this object (so it won’t be influenced by gravity or other objects).
2. implement getWorldTransform() so that an up to date transform is returned whenever the simulation calls that function.
3. Implement setWorldTransform() so that you (or the engine, if interpolating) can set the transform.
4. Make the object ‘kinematic’ (see below)

Configuration:

There are two steps to ‘make an object kinematic’.

body->setCollisionFlags(body->getCollisionFlags() | btCollisionObject::CF_KINEMATIC_OBJECT);

This flag tells the engine that the object is kinematic – so it shouldn’t move under the influence of gravity or because of colliding with other objects.

body->setActivationState(DISABLE_DEACTIVATION);

This prevents the object from ‘falling asleep’. Normally objects that haven’t moved in a while aren’t processed and keep sleeping until something bumps into them, or something that they’re in contact with wakes them up. Since kinematic objects aren’t affected by forces, we need to prevent them from falling asleep.

Back to dynamic state (UNTESTED)

body->setCollisionFlags( body->getCollisionFlags() & ~(btCollisionObject::CF_KINEMATIC_OBJECT));

body->activate(true); // or try… body->forceActivationState(ACTIVE_FLAG)

Tips and Caveats

• Avoid relying on how many times or when the motion state’s get/set methods are accessed. Even if your object is not kinematic, the motion state’s getter may be called after the initial simulation step (TESTED).
• If you ‘teleport’ a dynamic object, set the object’s transform by calling body->getWorldTransform().setOrigin(); even if you have removed the body from the simulation, after adding this object again the transform underlying your motion state may be overridden by a call to setWorldTransform before getWorldTransform is called by the engine.
• In my experience it would appear that kinematic objects are somewhat less reliable than dynamic objects. I often seen tunneling effects that disappear if I use a dynamic object instead. Once again testing in a sandbox can be very helpful in such cases.

Today I’m covering simple methods used to move dynamic objects. I am also introducing servo-controllers.

To study the effect of forces on an object’s velocity and position, it is good to know how to step the simulation correctly. Before reading this tutorial, you may wish to have a look on the bullet wiki and read stepping the world.

Additionally, you may want to check the btRigid body class reference on the Bullet site. btRigidBody provides other methods that can be used to apply torques and forces.

Forces

You can apply forces using:

btRigidBody::applyCentralForce(btVector3 F)

If you call this method, a force equal to F*t will be applied at the next frame, where:

• F is expressed in Newtons per second.
• t is the duration of the next ‘physics frame’.

When using applyCentralForce, the total force applied depends on the duration of the next frame.

Example 1:

float duration = 0.5f; // frame duration (seconds)
float maxSubsteps = 5; // max number of substeps to update
float tick = 0.1f;  // max duration of a substep (seconds)

body->applyCentralForce(btVector3(1,0,0));
world->step(duration,maxSubsteps,tick); // total force applied: 0.5N

Example 2:

float duration = 0.2f;
float maxSubsteps = 5;
float tick = 0.1f;

body->applyCentralForce(btVector3(1,0,0));
world->step(duration,maxSubsteps,tick); // total force applied: 0.2N

Impulses

If you want to give a one-off ‘impulse’ irrespective of frame duration, you can use:

btRigidBody::applyCentralImpulse(btVector3 F)

In this case the total force applied at the next frame is F, irrespective of frame duration.

Continuous forces

If you want to apply continuous forces (e.g, traction generated by an engine), you should call applyCentralForce at every frame. This is because forces are reset after the next frame:

body->applyCentralForce(btVector3(1,0,0));
world->step(0.1f,10,0.02f); // applied 0.1 N

world->step(0.1f,10,0.02f); // applied 0.0 N

High-school memory: Just because forces are reset doesn’t mean the object will stop moving right away! If there is no air resistance or friction, the body will continue moving forever.

How do I control the object’s velocity?

When dealing with forces, you can adjust forces using a servo-controller (aka servo-mechanism or servo). A servo uses negative feedback to adjust it’s input in order to regulate it’s output.

Why can’t I just set the velocity directly?

If you want a dynamic object that collides, falls under the effect of gravity and rests on the ground automagically, setting velocity directly isn’t a good idea (you’ll end up canceling the effect of all these forces). Instead you want to set the target velocity and let a servo generate forces to adjust your object’s velocity.

OK, how do I write a servo? Is it hard?

A basic servo works like this:

1. Assume a target velocity v0
2. Read the current velocity v
3. Evaluate the error: e = v – v0
4. Evaluate a correction factor: c = – e = v0 – v
5. Apply the correction factor multiplied by an arbitrary scale factor k:
   F = k . ( v0 – v )

Use btRigidBody:getLinearVelocity() to read a body’s current velocity.

The tricky part is getting the scale factor right. As a rule of the thumb if you try with a 1kg sphere, a factor between 10 and 50 works fine. A smart servo adjusts the scale factor automatically.

I will provide sample code for servos another time. We have enough on our hands learning Bullet.